Hooks

Hooks are shell commands that run at defined points in a Droid session. Use them for deterministic behavior that should happen every time, such as validating tool calls, formatting changed files, injecting local context, logging activity, or enforcing team policy.

Configuration

Hooks live alongside settings at each scope:

If hooks.json is absent, Droid also reads hook declarations from the hooks key in the matching settings.json.

Structure

Hook files are keyed by event name. Each event contains matcher groups, and each group contains one or more shell commands.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Execute",
        "commandRegex": "^git ",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/audit-git-command.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Common tool matchers include Execute, Read, Edit, Create, ApplyPatch, LS, Glob, Grep, Task, FetchUrl, and WebSearch. MCP tools use the mcp__<server>__<tool> naming pattern, so mcp__.* matches all MCP tools.

Quickstart

This example logs every shell command Droid runs.

1. 1
   Open the hooks manager

   In Droid, run:

   /hooks

   Select PreToolUse.

2. 2
   Add an Execute matcher

   Add a new matcher and enter:

   Execute

3. 3
   Add the hook command

   Add a command hook:

   Bash

   jq -r '.tool_input.command' >> ~/.factory/bash-command-log.txt

4. 4
   Save and verify

   Save to user settings, ask Droid to run a simple command, then inspect the log:

   Bash

   cat ~/.factory/bash-command-log.txt

The saved configuration looks like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Execute",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.factory/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

Hook events

Hook input

Every hook receives JSON on stdin. Common fields are also exposed as environment variables when their values are strings, booleans, or numbers.

{
  session_id: string
  transcript_path: string
  cwd: string
  permission_mode: "off" | "spec" | "auto-low" | "auto-medium" | "auto-high"
  hook_event_name: string
  message_id?: string
}

Tool hooks add tool-specific fields:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.factory/projects/.../session.jsonl",
  "cwd": "/Users/me/project",
  "permission_mode": "off",
  "hook_event_name": "PreToolUse",
  "tool_name": "Create",
  "tool_input": {
    "file_path": "/Users/me/project/file.txt",
    "content": "file content"
  }
}

PostToolUse includes tool_response as well. The exact shape of tool_input and tool_response depends on the tool.

Hook output

Hooks communicate through exit codes, stderr, stdout, and optional JSON emitted on stdout.

PreToolUse control

Use hookSpecificOutput.permissionDecision for tool-call control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Documentation reads are safe",
    "updatedInput": {
      "file_path": "/Users/me/project/README.md"
    }
  }
}

updatedInput can modify tool parameters before execution. Use it carefully and only for fields you understand.

PostToolUse, prompt, and stop control

Plugin hooks

Installed plugins can provide hooks. Droid loads hooks from hooks/hooks.json in the plugin root and merges them with user, project, and managed hooks when the plugin is enabled.

my-plugin/
├── .factory-plugin/
│   └── plugin.json
├── hooks/
│   ├── hooks.json
│   └── format.sh
└── ...

{
  "PostToolUse": [
    {
      "matcher": "Create|Edit|ApplyPatch",
      "hooks": [
        {
          "type": "command",
          "command": "${DROID_PLUGIN_ROOT}/hooks/format.sh",
          "timeout": 30
        }
      ]
    }
  ]
}

Plugin hook commands may use ${DROID_PLUGIN_ROOT}, $DROID_PLUGIN_ROOT, ${CLAUDE_PLUGIN_ROOT}, or $CLAUDE_PLUGIN_ROOT. Droid expands those variables to the installed plugin cache path when loading plugin hooks. Outside plugins, use $FACTORY_PROJECT_DIR or an absolute path.

Org-managed hooks

Organizations can define authoritative hooks in Enterprise Controls through managed settings. Org hooks always load unless hooks are globally disabled, and lower levels cannot remove them.

{
  "allowManagedHooksOnly": true,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Execute",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/audit-command.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

See Enterprise Controls & Managed Settings for how org, project, folder, and user settings merge.

Examples

Format changed TypeScript files

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Create|Edit|ApplyPatch",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$FACTORY_PROJECT_DIR\"/.factory/hooks/format_changed_file.py"
          }
        ]
      }
    ]
  }
}

Block edits to sensitive files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Create|Edit|ApplyPatch",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$FACTORY_PROJECT_DIR\"/.factory/hooks/protect_paths.py"
          }
        ]
      }
    ]
  }
}

A blocking script exits 2 and writes the reason to stderr.

Add context before each prompt

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$FACTORY_PROJECT_DIR\"/.factory/hooks/add_ticket_context.py"
          }
        ]
      }
    ]
  }
}

Security considerations

• Treat hook input as untrusted JSON. Validate and sanitize paths, prompts, and command strings.
• Quote shell variables, for example "$FACTORY_PROJECT_DIR", to avoid word splitting.
• Block path traversal and sensitive paths such as .env, .git/, credentials, and deployment secrets.
• Prefer small scripts checked into .factory/hooks/ over long inline one-liners.
• Test hooks manually before enabling them for a team or organization.
• Remember that hooks inherit your local environment. Avoid commands that exfiltrate data or mutate systems unexpectedly.

Droid snapshots hooks at startup and warns when hooks are modified externally. Review changes in the /hooks UI before relying on them in the current session.

Debugging

Run droid --debug to inspect hook matching and execution details.