/hooks-management

name: hooks-management
description: Manage hooks and automation for coding agents (Claude Code, Codex CLI, OpenCode, Devin CLI/Desktop). 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.

Hooks Management

Manage hooks and automation through natural language commands.

**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.

Quick Reference

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

• *Session lifecycle*: SessionStart, SessionEnd, InstructionsLoaded
• *User input*: UserPromptSubmit, UserPromptExpansion
• *Tool execution*: PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch
• *Permissions*: PermissionRequest, PermissionDenied
• *Model output*: Stop, StopFailure
• *Subagents/tasks*: SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle
• *Config/state*: ConfigChange, FileChanged, CwdChanged
• *Compaction*: PreCompact, PostCompact
• *Worktree*: WorktreeCreate, WorktreeRemove
• *MCP*: Elicitation, ElicitationResult
• *Notifications*: Notification

**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).

**Claude Code Settings Files**:

• User-wide: `~/.claude/settings.json`
• Project: `.claude/settings.json`
• Local (not committed): `.claude/settings.local.json`
• Drop-in policy fragments: `~/.claude/managed-settings.d/` (managed-settings only)

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

• User config: `~/.codex/config.toml`
• User hooks: `~/.codex/hooks.json` or inline `[hooks]` tables in `~/.codex/config.toml`
• Project hooks: `<repo>/.codex/hooks.json` or inline `[hooks]` tables in `<repo>/.codex/config.toml` (trusted projects only)
• Codex App and CLI share these config layers. In the App/IDE, the settings UI opens the same `config.toml`.
• Hooks are enabled by default. Use `[features].hooks = false` to disable them. `codex_hooks` is a deprecated alias.
• Non-managed Codex command hooks must be reviewed/trusted with `/hooks`; changed hook definitions are skipped until trusted.

**Devin CLI / Desktop hook locations**:

• Project: `.devin/hooks.v1.json` (standalone hooks object, recommended) or `"hooks"` in `.devin/config.json` / `.devin/config.local.json`
• User: `"hooks"` in `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` on Windows)
• Claude-format hooks under `.claude/` are imported automatically when `read_config_from.claude` is on (default)
• Events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, Stop, PostCompaction, SessionStart, SessionEnd; `matcher` is a regex on `tool_name`
• See [references/devin-hooks.md](references/devin-hooks.md) for the full event/output contract

**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](#decision-control-pretooluse). 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.

**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.

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

Workflow

1. Understand the Request

Parse what the user wants:

• **Add/Create**: New hook for specific event and tool
• **List/Show**: Display current hooks configuration
• **Remove/Delete**: Remove specific hook(s)
• **Update/Modify**: Change existing hook
• **Validate**: Check hooks for errors

2. Validate Before Writing

Always run validation before saving:

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

3. Read Current Configuration

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

4. Apply Changes

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

Adding Hooks

Translate Natural Language to Hook Config

| User Says | Event | Matcher | Notes | |-----------|-------|---------|-------| | "log all bash commands" | PreToolUse | Bash | Logging to file | | "format files after edit" | PostToolUse | Edit\|Write | Run formatter | | "block .env file changes" | PreToolUse | Edit\|Write | Exit code 2 blocks | | "notify me when done" | Notification | "" | Desktop notification | | "run tests after code changes" | PostToolUse | Edit\|Write | Filter by extension | | "ask before dangerous commands" | PreToolUse | Bash | Claude 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" | PreToolUse | Bash/Edit/Write | Claude Code: emit JSON `permissionDecision: "ask"`, NOT exit 2. Codex: choose policy prompt or hard block. | | "block unless confirmed" | PreToolUse | Bash | Claude Code: JSON `"ask"` lets the user approve per call. Codex: no hook-created confirmation prompt yet. |

Hook Configuration Template

{
  "hooks": {
    "EVENT_NAME": [
      {
        "matcher": "TOOL_PATTERN",
        "hooks": [
          {
            "type": "command",
            "command": "SHELL_COMMAND",