Factory Droid — Hooks

File format: JSON
Discovery path: .factory/settings.json
Syllago install method: JSON merge
Symlink support: No
Config file: .factory/settings.json
Handler types: command

Hook events

Canonical Event	Native Name	Category
`after_tool_execute`	`PostToolUse`	Tool
`agent_stop`	`Stop`	Lifecycle
`before_compact`	`PreCompact`	Context
`before_prompt`	`UserPromptSubmit`	Lifecycle
`before_tool_execute`	`PreToolUse`	Tool
`session_end`	`SessionEnd`	Lifecycle
`session_start`	`SessionStart`	Lifecycle
`subagent_start`	`SubagentStart`	Lifecycle
`subagent_stop`	`SubagentStop`	Lifecycle

Features

How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.

Fields

Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.

Provider field	Conversion	Canonical key	Summary
`hooks`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	—	JSON config under top-level hooks key; each event maps to an array of matcher objects, each with a matcher string and a hooks array of {type: command, command: string, timeout?: number} entries.
`PreCompact`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	—	Fires before context compaction, allowing hooks to inject memory or state into the compaction prompt to preserve important context.

Other features

Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.

Feature	Conversion	Summary
`async_execution`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Matching hooks for the same event execute concurrently (in parallel); deduplication consolidates identical commands automatically
`context_injection`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	additionalContext field in PostToolUse, UserPromptSubmit, and SessionStart hook output injects information into the agent session; systemMessage field in JSON output provides session-level injection
`decision_control`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	PreToolUse hooks return JSON with allow/deny/ask decision field; exit code 2 blocks with stderr fed back to Droid; non-zero non-2 shows stderr to user as non-blocking error
Hook Events	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Nine hook events: PreToolUse (block/allow/ask/modify input), PostToolUse (block with reasoning/add context), UserPromptSubmit (block or add context), Stop (block stopping), SubagentStop (block stopping), PreCompact (inject memory), SessionStart (add context), SessionEnd (cleanup), Notification (custom alerts).
Hook Exit Code Behavior	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Exit code 0 = success (stdout shown in transcript, or adds context for UserPromptSubmit/SessionStart); exit code 2 = blocking error (stderr fed back to Droid); other non-zero = non-blocking error (stderr shown to user). JSON output fields: continue, stopReason, suppressOutput, systemMessage, plus event-specific fields (allow/deny/ask/updatedInput for PreToolUse; block/additionalContext for PostToolUse and UserPromptSubmit; block for Stop/SubagentStop; additionalContext for SessionStart).
`hook_scopes`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Four scopes documented: user-level (~/.factory/settings.json), project-level (.factory/settings.json), local-uncommitted (.factory/settings.local.json), and enterprise managed policies
`input_modification`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	PreToolUse hooks return updatedInput in JSON output to modify tool parameters before execution
`json_io_protocol`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Hooks receive JSON via stdin containing session_id, transcript_path, cwd, permission_mode, hook_event_name, and event-specific fields; hooks return JSON output with continue, stopReason, suppressOutput, systemMessage, and event-specific fields
`matcher_patterns`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	PreToolUse and PostToolUse hooks use matcher strings supporting exact tool names, regex patterns (Edit\|Create, Notebook.), MCP tool patterns (mcp__<server>__<tool>), and wildcard () to match all tools
`permission_control`	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	PreToolUse hooks return allow, deny, or ask in the JSON decision field to bypass, block, or escalate tool permission decisions
Hook Execution Details	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Default timeout is 60 seconds per command (configurable via timeout field). Matching hooks for the same event run concurrently. Identical commands are automatically deduplicated. Plugin hooks via plugins/[name]/hooks/hooks.json use ${DROID_PLUGIN_ROOT} env var and merge with user configurations.
Hook Input: JSON stdin and Environment Variables	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Hooks receive full JSON context via stdin (session_id, transcript_path, cwd, permission_mode, hook_event_name, plus event-specific tool data). Environment variables available include FACTORY_PROJECT_DIR (project root) and standard shell environment.
Hook Scope Files	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Hooks live in scoped settings files: ~/.factory/settings.json (user-level), .factory/settings.json (project-level), .factory/settings.local.json (local uncommitted), plus enterprise managed policies.
MCP Tool Hook Matchers	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	MCP tools follow the naming pattern mcp__<server>__<tool> and can be matched with regex patterns in PreToolUse/PostToolUse matchers (e.g., mcp__memory__.* for all memory server tools, mcp__.__write. for write operations across all MCP servers).

Sources

Source
https://docs.factory.ai/cli/configuration/hooks-guide
https://docs.factory.ai/reference/hooks-reference