Factory Droid

Factory Droid Hooks: hooks.json, PreToolUse Matchers and Exit Codes

How do I set up hooks in Factory Droid?

Put hooks in ~/.factory/hooks.json for yourself or .factory/hooks.json in the repo for your team, keyed by event name such as PreToolUse. Each entry has a matcher and a list of command hooks. A hook that exits with code 2 blocks the tool call in PreToolUse.

Hook events

  • PreToolUse
  • PostToolUse
  • UserPromptSubmit
  • Notification
  • Stop
  • SubagentStop
  • PreCompact
  • SessionStart
  • SessionEnd

Where to put hooks

  • User: ~/.factory/hooks.json. Applies to all your projects.
  • Project: .factory/hooks.json. Commit it for teammates.
  • Enterprise: org managed settings.
  • Legacy: .factory/hooks/hooks.json still loads, and the next save moves it to .factory/hooks.json.

If there is no hooks.json, Droid reads a hooks key in the matching settings.json. In settings.json the same event map sits under a top level "hooks" key.

Example: audit every git command

.factory/hooks.json

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

How matchers work

  • An empty, missing or * matcher matches everything.
  • An exact string matches one tool.
  • Regex is supported and is case sensitive.
  • commandRegex filters Execute calls by the shell command text. Invalid regex is skipped.
  • MCP tools are named mcp__<server>__<tool>, so mcp__.* matches all of them.

Exit codes

  • 0: success. For UserPromptSubmit and SessionStart, stdout can add context.
  • 2: blocking feedback. PreToolUse blocks the tool call. PostToolUse and Stop send stderr back to Droid. UserPromptSubmit blocks the prompt.
  • Any other non zero code: a non blocking error. Droid records stderr and continues.

Check what is active with /hooks

Run /hooks inside Droid to open the hooks manager. It has User, Project, Plugins and Effective tabs. Plugins and Effective are read only.

Get Factory Droid settings changes by email

When a setting, flag or permission rule in this guide changes, it goes in the weekly AgentAtlas update, checked against the vendor docs. One email a week.

Sources

Factory: Hooks

More on Factory Droid

Factory Droid standards support

More Factory Droid guides

Other guides

Cursor: allow all terminal commandsClaude Code: allow commands without promptsClaude Code permissions: allow, ask and deny rules, rule syntax and allowed toolsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryCLAUDE.md: where it goes, how it loads, and how it works with AGENTS.mdClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call itAdd MCP servers to Cursor with mcp.json: Keep files out of Cursor with .cursorignore: Configure Codex with config.toml: Configure Gemini CLI with settings.json: Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes): Claude Code custom slash commands and skills (SKILL.md): GitHub Copilot custom instructions: Adding MCP servers to GitHub Copilot: Claude Code settings.json: file locations, precedence, and key settingsClaude Code plugins and marketplaces: install, create, and shareGemini CLI extensions and custom commands: Configuring OpenCode with opencode.json: Cline Rules: workspace, global, and conditional rulesKiro steering files: .kiro/steering, inclusion modes, and AGENTS.mdZed agent: instruction files, MCP servers, tool permissions, and ACP agentsCursor CLI: install, headless mode, permissions and CIAider: CONVENTIONS.md, .aider.conf.yml and API keysJunie guidelines, MCP and the Action Allowlist: Amp AGENTS.md, settings.json and MCP: Configure Goose extensions, hints, recipes and permissions: Customize OpenHands with skills, AGENTS.md, setup.sh and MCP: Configure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modesCursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codesCursor sandbox: sandbox.json, network allowlist and run modesCursor settings: settings.json, Cursor Settings and the ~/.cursor config filesCursor browser agent: @browser, browser automation and approval modesCursor subagents: .cursor/agents, frontmatter, built-in Explore, Bash and BrowserCursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API): Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.mdClaude Code headless mode: claude -p, --output-format json, --bare and CI flagsClaude Code statusline: custom status bar in settings.json with context %, cost and git branchClaude Code /model: switch models, aliasesClaude Code /cost and /usage: check token spend, usage limits and reduce costsClaude Code VS Code extension: install, shortcuts, settings and /ideCodex AGENTS.md: global, project and override instruction files explainedCodex MCP servers: codex mcp add and [mcp_servers] in config.tomlCodex sandbox modes: read-only, workspace-write, danger-full-access and network accesscodex exec: run Codex non-interactively in scripts and CI with JSON outputCodex skills: create SKILL.md, skill folder locations and $skill invocationGEMINI.md in Gemini CLI: context file locations, imports and /memoryGemini CLI MCP servers: gemini mcp add and mcpServers in settings.jsonGemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CIGemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisorcopilot-setup-steps.yml: set up the GitHub Copilot cloudGitHub Copilot CLI permissions: --allow-tool, --deny-tool, --allow-all-tools and trusted directoriesGitHub Copilot custom agents: .github/agents/*.agent.md profiles, tools and frontmatterGitHub Copilot code review settings: automatic PR reviews, rulesets, effort level and approvalsOpenCode MCP Server Setup: Local and Remote Servers in opencode.jsonOpenCode Permissions: Allow, Ask or Deny Bash, Edit and WebfetchOpenCode Custom Agents and Subagents: Markdown Files, Modes and @ MentionsCline MCP Setup: cline_mcp_settings.json for Local and Remote ServersCline Auto Approve and YOLO Mode: Run Commands and Edits Without PromptsCline Skills: SKILL.md Location, Format and Slash Command UseAmp MCP Setup: amp mcp add, amp.mcpServers and Workspace ApprovalAmp AGENTS.md: File Locations, @ Mentions and Glob-Scoped GuidanceAmp Skills: SKILL.md Folders, amp skill add and Search OrderKiro MCP Setup: .kiro/settings/mcp.json, autoApprove and OAuthKiro Hooks: .kiro/hooks JSON, PreToolUse, PostFileSave and StopKiro Permissions: permissions.yaml Allow, Ask and Deny RulesJunie MCP Setup: .junie/mcp/mcp.json for CLI and /mcp CommandJunie Brave Mode and Action Allowlist: Auto-Approve Commands in Junie CLIJunie Custom Slash Commands: .junie/commands Markdown Files and Argumentsgoose .goosehints and AGENTS.md: Global and Project Instructionsgoose Permission Modes: GOOSE_MODE auto, approve, smart_approve and chatgoose Recipes: recipe.yaml Format, Parameters and goose run --recipeZed Agent Tool Permissions: Auto-Approve Terminal Commands with tool_permissionsUse Claude, Codex and Gemini CLI in Zed: External Agents and agent_serversZed with Ollama, LM Studio and llama.cpp: Local Model Setup and Context Length

Reviewed Oct 13, 2026. Settings change often; the linked vendor docs are the source of truth.