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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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	TranslatedConversion type: TranslatedActively 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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 portableConversion type: Not portableUnique 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