{"slug":"hooks-management","title":"hooks-management","summary":"Manage hooks and automation for coding agents (Claude Code, Codex CLI, OpenCode). Use when users want to add, list, remove, update, or validate hooks. Triggers on requests like \"add a hook\", \"create a hook that...\", \"list my hooks\", \"remove the hook\", \"validate hooks\", or any men","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-14T21:20:10.245807Z","repo":{"url":"https://github.com/CodeAlive-AI/ai-driven-development","stars":149,"forks":13,"license":"MIT","updatedAt":"2026-09-25T21:32:01Z"},"bodyHtml":"
\n

name: hooks-management\ndescription: Manage hooks and automation for coding agents (Claude Code, Codex CLI, OpenCode). Use when users want to add, list, remove, update, or validate hooks. Triggers on requests like \"add a hook\", \"create a hook that...\", \"list my hooks\", \"remove the hook\", \"validate hooks\", or any mention of automating agent behavior with shell commands or plugins.

\n

Hooks Management

\n

Manage hooks and automation through natural language commands.

\n

IMPORTANT: After adding, modifying, or removing hooks, always inform the user that they need to restart the agent for changes to take effect. Hooks are loaded at startup.

\n

Quick Reference

\n

Hook Events (Claude Code, as of 2026-04 — 28 events):

\n\n

Handler types: command, http, mcp_tool, prompt, agent. Some events are command-only (PostCompact, PermissionDenied, Elicitation/ElicitationResult, FileChanged, CwdChanged, ConfigChange, InstructionsLoaded, WorktreeCreate/Remove, SubagentStart, StopFailure, TeammateIdle, Setup, SessionStart, SessionEnd, Notification).

\n

Claude Code Settings Files:

\n\n

Codex CLI / Codex App Settings Files (current as of 2026-06):

\n\n

Claude Code default control mechanism for PreToolUse: emit JSON on stdout with hookSpecificOutput.permissionDecision set to \"allow\", \"deny\", \"ask\" (triggers the built-in user confirmation prompt), or \"defer\" (pause headless tool calls; resume with -p --resume). See Decision Control. Do NOT roll your own confirmation schemes (env-var flags, interactive osascript prompts, bypass tokens) — those break the built-in UX and silently fail under existing permissions.allow entries.

\n

Codex exception: Codex PreToolUse does not support \"ask\" yet. In Codex configs, use deny / exit code 2 for hard blocks, additionalContext for advisory context, or Codex approval policy/permissions for native prompts.

\n

Disable all hooks: set disableAllHooks: true in settings.json.

\n

Workflow

\n

1. Understand the Request

\n

Parse what the user wants:

\n\n

2. Validate Before Writing

\n

Always run validation before saving:

\n
python3 \"$SKILL_PATH/scripts/validate_hooks.py\" ~/.claude/settings.json\n
\n

3. Read Current Configuration

\n
cat ~/.claude/settings.json 2>/dev/null || echo '{}'\n
\n

4. Apply Changes

\n

Use Edit tool for modifications, Write tool for new files.

\n

Adding Hooks

\n

Translate Natural Language to Hook Config

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
User SaysEventMatcherNotes
\"log all bash commands\"PreToolUseBashLogging to file
\"format files after edit\"PostToolUseEdit|WriteRun formatter
\"block .env file changes\"PreToolUseEdit|WriteExit code 2 blocks
\"notify me when done\"Notification\"\"Desktop notification
\"run tests after code changes\"PostToolUseEdit|WriteFilter by extension
\"ask before dangerous commands\"PreToolUseBashClaude Code: emit JSON permissionDecision: \"ask\" (built-in confirm UI). Codex: use approval policy if possible; hook-level ask is unsupported.
\"require manual approval for X\"PreToolUseBash/Edit/WriteClaude Code: emit JSON permissionDecision: \"ask\", NOT exit 2. Codex: choose policy prompt or hard block.
\"block unless confirmed\"PreToolUseBashClaude Code: JSON \"ask\" lets the user approve per call. Codex: no hook-created confirmation prompt yet.
\n

Hook Configuration Template

\n
{\n  \"hooks\": {\n    \"EVENT_NAME\": [\n      {\n        \"matcher\": \"TOOL_PATTERN\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"SHELL_COMMAND\",\n            \"timeout\": 60\n          }\n        ]\n      }\n    ]\n  }\n}\n
\n

Simple vs Complex Hooks

\n

PREFER SCRIPT FILES for complex hooks. Inline commands with nested quotes, osascript, or multi-step logic often break due to JSON escaping issues.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ComplexityApproachExample
SimpleInlinejq -r '.tool_input.command' >> log.txt
MediumInlineSingle grep/jq pipe with basic conditionals
ComplexScript fileDialogs, multiple conditions, osascript, error handling
\n

Script location: ~/.claude/hooks/ (create if needed)

\n

Script template for PreToolUse (~/.claude/hooks/my-hook.sh) — use JSON decision control as the primary mechanism; exit codes are a fallback for simple blocking only:

\n
#!/bin/bash\nset -euo pipefail\n\n# Read JSON input from stdin\ninput=$(cat)\ncmd=$(echo \"$input\" | jq -r '.tool_input.command')\n\n# Your logic here\nif echo \"$cmd\" | grep -q 'pattern-requiring-confirmation'; then\n    # PRIMARY PATTERN for \"require user confirmation\": emit JSON on stdout.\n    # Claude Code will show its built-in confirm prompt to the user.\n    jq -n '{\n      hookSpecificOutput: {\n        hookEventName: \"PreToolUse\",\n        permissionDecision: \"ask\",\n        permissionDecisionReason: \"Explain why this call is risky\"\n      }\n    }'\n    exit 0\nfi\n\nif echo \"$cmd\" | grep -q 'pattern-to-hard-block'; then\n    # Hard block (no user override possible): JSON deny, NOT exit 2.\n    jq -n '{\n      hookSpecificOutput: {\n        hookEventName: \"PreToolUse\",\n        permissionDecision: \"deny\",\n        permissionDecisionReason: \"Reason shown to Claude\"\n      }\n    }'\n    exit 0\nfi\n\nexit 0  # Allow (silent)\n
\n

Why JSON decisions, not exit 2 or home-grown prompts:

\n\n

Hook config using script:

\n
{\n  \"type\": \"command\",\n  \"command\": \"~/.claude/hooks/my-hook.sh\"\n}\n
\n

Other handler types (2026): http (POSTs event JSON to a URL), mcp_tool (calls a tool on a configured MCP server), prompt (evaluates a prompt with an LLM, supports $ARGUMENTS), agent (runs an agentic verifier with tools). Some events are command-only (PostCompact, PermissionDenied, Elicitation/ElicitationResult, FileChanged, CwdChanged, ConfigChange, InstructionsLoaded, WorktreeCreate/Remove, SubagentStart, StopFailure, TeammateIdle, SessionStart/End, Notification).

\n

Always:

\n
    \n
  1. Create script in ~/.claude/hooks/
    2. \n
  2. Make executable: chmod +x ~/.claude/hooks/my-hook.sh
    3. \n
  3. Test with sample input: echo '{\"tool_input\":{\"command\":\"test\"}}' | ~/.claude/hooks/my-hook.sh
    4. \n
\n

Common Patterns

\n

Logging (PreToolUse):

\n
{\n  \"matcher\": \"Bash\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"jq -r '.tool_input.command' >> ~/.claude/command-log.txt\"\n  }]\n}\n
\n

File Protection (PreToolUse, exit 2 to block):

\n
{\n  \"matcher\": \"Edit|Write\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"jq -r '.tool_input.file_path' | grep -qE '(\\\\.env|secrets)' && exit 2 || exit 0\"\n  }]\n}\n
\n

Auto-format (PostToolUse):

\n
{\n  \"matcher\": \"Edit|Write\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"file=$(jq -r '.tool_input.file_path'); [[ $file == *.ts ]] && npx prettier --write \\\"$file\\\" || true\"\n  }]\n}\n
\n

Desktop Notification (Notification):

\n
{\n  \"matcher\": \"\",\n  \"hooks\": [{\n    \"type\": \"command\",\n    \"command\": \"osascript -e 'display notification \\\"Claude needs attention\\\" with title \\\"Claude Code\\\"'\"\n  }]\n}\n
\n

Decision Control (Claude Code PreToolUse)

\n

Claude Code PreToolUse hooks control tool execution by emitting JSON on stdout. This is the default mechanism — use it instead of exit codes whenever the intent is richer than \"silently allow / hard block\", especially when the user should be asked to confirm.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
permissionDecisionBehaviorUse for
\"allow\"Bypass permissions, proceed silentlyPre-approving a safe call
\"deny\"Block, reason shown to ClaudeHard block (no user override)
\"ask\"Built-in Claude Code confirm UI shown to user\"Require manual approval for X\" — the canonical pattern
\"defer\"Pause headless tool call, resume via -p --resumeExternal-system integrations in headless (-p) sessions
\n

Additional JSON fields:

\n\n

Ask user before dangerous command (the canonical pattern)

\n

When the user says anything like \"require manual confirmation\", \"ask before doing X\", \"don't run Y without my approval\" — this is the pattern. Do not invent bypass env vars, osascript dialogs, or confirmation tokens. The built-in prompt already handles per-call allow/deny and is the only path that integrates with existing permissions.allow rules correctly.

\n
#!/bin/bash\nset -euo pipefail\ninput=$(cat)\ncmd=$(echo \"$input\" | jq -r '.tool_input.command // empty')\n\nif echo \"$cmd\" | grep -qE 'supabase\\s+db\\s+reset'; then\n    jq -n '{\n      hookSpecificOutput: {\n        hookEventName: \"PreToolUse\",\n        permissionDecision: \"ask\",\n        permissionDecisionReason: \"This will destroy and recreate the local database.\"\n      }\n    }'\nelse\n    exit 0\nfi\n
\n

Deny with reason (hard block)

\n
jq -n '{\n  hookSpecificOutput: {\n    hookEventName: \"PreToolUse\",\n    permissionDecision: \"deny\",\n    permissionDecisionReason: \"Destructive command blocked by hook\"\n  }\n}'\n
\n

Gotcha: \"ask\" vs existing permissions.allow rules

\n

If the tool call already matches an entry in .claude/settings.local.json → permissions.allow (for example, \"Bash\" is blanket-allowed for this session), the hook's \"ask\" is bypassed and the call proceeds silently. Symptom: the hook appears to do nothing. Diagnose by reading .claude/settings.local.json and narrowing the allow rule, or remove the blanket allow for the matcher while the hook is in effect.

\n

See references/claude-event-schemas.md for the full output schema.

\n

Codex CLI / Codex App Hooks

\n

As of June 2026, Codex hooks are enabled by default and are shared by Codex CLI, Codex IDE extension, and Codex App/desktop sessions through the same ~/.codex and trusted project .codex configuration layers.

\n

Current Codex lifecycle events:

\n\n

Do not add the old feature flag for new configs. If hooks must be disabled, use:

\n
[features]\nhooks = false\n
\n

Minimal PreToolUse blocking hook:

\n
[[hooks.PreToolUse]]\nmatcher = \"^Bash$\"\n\n[[hooks.PreToolUse.hooks]]\ntype = \"command\"\ncommand = '/usr/bin/python3 ~/.codex/hooks/policy.py'\ntimeout = 30\nstatusMessage = \"Checking Bash command\"\n
\n

Equivalent ~/.codex/hooks.json:

\n
{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"^Bash$\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"/usr/bin/python3 ~/.codex/hooks/policy.py\",\n            \"timeout\": 30,\n            \"statusMessage\": \"Checking Bash command\"\n          }\n        ]\n      }\n    ]\n  }\n}\n
\n

Prefer one representation per config layer: either hooks.json or inline [hooks]. Codex loads both and warns if both exist in the same layer.

\n

Blocking semantics: exit code 2 blocks (stderr is reason), or emit JSON {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"...\"}}.

\n

Important Codex gap: PreToolUse currently does not support permissionDecision: \"ask\". Returning \"ask\" makes the hook run fail and Codex continues the tool call. For fail-closed behavior, map Claude-style ask to Codex deny.

\n

When adapting a Claude Code ask hook to Codex, prefer this order:

\n
    \n
  1. Use hard deny / exit 2 when the command must not run without review.
    2. \n
  2. If the risky action can be expressed as command argv prefixes and the user explicitly accepts best-effort native Codex prompts, use Codex rules for the prompt and keep the hook silent for that exact reason code.
    3. \n
  3. Do not put the whole hook into shadow mode unless you intentionally want logging only; that allows every risky action the hook would otherwise catch.
    4. \n
\n

For bash-guard specifically, Codex live mode defaults to hard deny for internal ask decisions. Only reason codes listed in BASH_GUARD_CODEX_DEFER_REASON_CODES are allowed to pass through to execpolicy, and installers only add that env var when the user passes --codex-native-prompts. Each deferred reason code must have a matching prefix_rule(... decision=\"prompt\"); otherwise the risky command would be silently allowed.

\n

PermissionRequest only fires when Codex is already about to ask for approval. It can return allow, deny, or no decision; it cannot create a prompt for commands that Codex would otherwise run without asking.

\n

Codex PreToolUse can intercept Bash, apply_patch file edits, and MCP tool calls, but it is not a complete enforcement boundary: interception of richer shell paths is incomplete, and WebSearch / non-shell / non-MCP tool calls are out of scope.

\n

See references/codex-hooks.md for full Codex hooks reference, all event input/output schemas, common patterns, and migration from the legacy AfterAgent / AfterToolUse events.

\n

OpenCode Hooks (Plugin-based)

\n

OpenCode (anomalyco/opencode v1.14.x) does NOT use config-based shell hooks. Hooks are TypeScript/JavaScript plugins that subscribe to lifecycle events. The closest analogue to PreToolUse is tool.execute.before — throwing inside it blocks the tool call.

\n
// .opencode/plugins/env-protection.ts\nimport type { Plugin } from \"@opencode-ai/plugin\"\n\nexport default (async () => ({\n  tool: {\n    execute: {\n      before: async (input, output) => {\n        if (output.args.filePath?.includes(\".env\")) {\n          throw new Error(\"Reading .env is forbidden\")\n        }\n      },\n    },\n  },\n})) satisfies Plugin\n
\n

Plugin locations:

\n\n

Common events: tool.execute.before, tool.execute.after, session.idle, session.created, file.edited, permission.asked, command.executed (~25 total).

\n

Critical caveat (v1.14.x): tool.execute.* hooks do NOT fire for MCP tool calls — use the permission block in opencode.json to control MCP tool access instead.

\n

For \"ask before\" semantics, prefer permission rules over plugin throws — they integrate with the built-in confirm UI:

\n
{ \"permission\": { \"bash\": { \"rm -rf *\": \"ask\" } } }\n
\n

See references/opencode-hooks.md for the full event catalog, migration patterns from Claude Code hooks, and npm plugin distribution.

\n

Event Input Schemas

\n

See references/claude-event-schemas.md for complete JSON input schemas for each event type (Claude Code).

\n

Validation

\n

Run validation script to check hooks:

\n
python3 \"$SKILL_PATH/scripts/validate_hooks.py\" <settings-file>\n
\n

Validates:

\n\n

Removing Hooks

\n
    \n
  1. Read current config
    2. \n
  2. Identify hook by event + matcher + command pattern
    3. \n
  3. Remove from hooks array
    4. \n
  4. If array empty, remove the matcher entry
    5. \n
  5. If event empty, remove event key
    6. \n
  6. Validate and save
    7. \n
\n

Exit Codes

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CodeMeaningUse Case
0Success/AllowContinue execution
2BlockSimple blocking (prefer JSON decision control for PreToolUse)
OtherErrorLog to stderr, shown in verbose mode
\n

Security Checklist

\n

Before adding hooks, verify:

\n\n

Troubleshooting

\n

Hook not triggering: Check matcher case-sensitivity, ensure event name is exact.

\n

Command failing: Test command standalone with sample JSON input.

\n

Permission denied: Ensure script is executable (chmod +x).

\n

Timeout: Increase timeout field or optimize command.

\n","files":[{"path":"references/claude-event-schemas.md","sizeBytes":10916,"isText":true},{"path":"references/claude-templates.md","sizeBytes":6011,"isText":true},{"path":"references/codex-hooks.md","sizeBytes":14531,"isText":true},{"path":"references/devin-hooks.md","sizeBytes":2647,"isText":true},{"path":"references/opencode-hooks.md","sizeBytes":10613,"isText":true},{"path":"scripts/validate_hooks.py","sizeBytes":6936,"isText":true},{"path":"SKILL.md","sizeBytes":19037,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"notes-only","suspicious":0,"notes":22,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-19T13:50:56.891722Z","sha256":"943CF01EA3A59C3EF08957F44903FA07F74EAE20D21886C07A867672AECFA7A3","sizeBytes":25134},"review":null,"source":{"repositoryUrl":"https://github.com/CodeAlive-AI/ai-driven-development","path":"skills/hooks-management","license":"MIT","commit":"99caded200d70ea0c80365928aea912679ee116a","subtreeSha":"35754E0AD84191800EADC70104EE653E4B854CD132882DD38AD887741333B2DD","lastSyncedAt":"2026-09-27T19:48:01.568101Z"},"reviewedAt":"2026-09-19T13:52:51.030678Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/hooks-management"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codealive-ai-ai-driven-development@llmmart"},{"target":"git","command":"git clone https://github.com/CodeAlive-AI/ai-driven-development.git"}]}