Test hook behavior
Test a hook
agnostic-ai hook run <hook> runs a hook spec the way each tool would, before a session fires it. A hook that blocks on Claude Code and does nothing on Codex shows up here, not in a live session:
$ agnostic-ai hook run protect-files --edit .github/workflows/tests.yml
claude: block (exit 2, 12ms)
event: PreToolUse (Write)
command: .claude/hooks/protect-files.sh
stderr: Blocked: .github/workflows/tests.yml is protected.
codex: allow (exit 0, 9ms)
event: PreToolUse (apply_patch)
command: export AGNOSTIC_AI_TARGET=codex; .codex/hooks/protect-files.sh
hook protect-files: targets decide differently: claude block, codex allow
For each configured tool the hook reaches, it runs every command sync wrote for that tool, from the project root, or from the handler's cwd on Copilot.
Build sample event data
--edit <path> and --bash <command> build a PreToolUse or PostToolUse tool call (BeforeTool or AfterTool on Gemini). --prompt <text> builds UserPromptSubmit (BeforeAgent on Gemini). SessionStart takes its source from the matcher, or startup when the matcher is empty. --payload <file> sends a JSON file as is, for any event. A file that does not hold one JSON object fails before any hook runs.
Apply matchers
When the matcher does not match the tool or source, that tool reports allow and why, since it would not run the hook. A --payload tool call matches its tool_name by the tool's own rules, including Codex's Edit and Write aliases for apply_patch. Cursor, Goose, Copilot, and Kiro match the field their docs name for the event, such as the command, file path, or prompt text.
Skip unsupported events
A tool without the hook's event, such as Codex for Notification, is not run.
Use the configured timeout
The command uses the timeout sync writes, or the tool's default in the table below.
Report background hooks
An async: true hook, or asyncRewake: true on Claude Code and Qoder, runs and prints its output, but the tool does not wait for it. Its result is not judged and stays out of --expect and the comparison. The same holds for Cursor sessionStart and sessionEnd, Copilot notification, and Cline hooks on any event but PreToolUse and PostToolUse.
Stop leftover background commands
On macOS and Linux, a command the hook leaves running is killed once the hook exits.
Find stale generated hook files
Commands come from the spec, so a command that calls a hook script needs a "Script path only" and "assumed" cells are assumed results. A handler's sync first to copy the script. A warning names the synced file when it is missing, when no handler under the event runs the spec's command, or when that handler's group matcher, timeout, or (on Gemini) env differs from the spec. It also compares failClosed on Claude Code and Cursor, cwd on Copilot, and confirm on Kiro. An env warning names keys, never values. A warning does not fail the run; sync clears it. The file is the one each tool page lists, or the path outputs sets.Environment variables per tool
hook run clears these variables from the calling shell's env, then sets them per tool. Other variables pass through.Target Variables set Claude Code AGNOSTIC_AI_TARGET=claude, CLAUDE_PROJECT_DIRCodex none; its command sets the target itself Gemini GEMINI_PROJECT_DIR, GEMINI_CWD, GEMINI_SESSION_ID, CLAUDE_PROJECT_DIR, then the handler's env, which holds AGNOSTIC_AI_TARGET=geminiTrae TRAE_PROJECT_DIR, CLAUDE_PROJECT_DIROpenHands OPENHANDS_PROJECT_DIR, OPENHANDS_SESSION_ID, OPENHANDS_EVENT_TYPE, OPENHANDS_TOOL_NAMEGoose PLUGIN_ROOT, with AGNOSTIC_AI_TARGET=goose from its commandAugment AUGMENT_PROJECT_DIR, AUGMENT_CONVERSATION_ID, AUGMENT_HOOK_EVENT, AUGMENT_TOOL_NAMECursor CURSOR_PROJECT_DIR, CURSOR_VERSION (empty), CLAUDE_PROJECT_DIR, and AGNOSTIC_AI_TARGET=cursor, which the sessionStart entry that sync adds sets for later hooksCrush CRUSH=1, AGENT=crush, AI_AGENT=crush, CRUSH_EVENT, CRUSH_TOOL_NAME, CRUSH_SESSION_ID, CRUSH_CWD, CRUSH_PROJECT_DIR, CRUSH_TOOL_INPUT_COMMAND or CRUSH_TOOL_INPUT_FILE_PATH when the tool input has one, and editor and pager variables that keep anything from waiting for a terminal; AGNOSTIC_AI_TARGET=crush comes from its commandCopilot the handler's env, which holds AGNOSTIC_AI_TARGET=copilot. Copilot is not run when a value holds $.Factory FACTORY_PROJECT_DIRQoder QODER_PROJECT_DIR, then the handler's env, which holds AGNOSTIC_AI_TARGET=qoderAntigravity none Cline none; the script exports AGNOSTIC_AI_TARGET=clineKiro USER_PROMPT on UserPromptSubmitWindsurf DEVIN_PROJECT_DIRShell and default timeout per tool
Target Shell Default timeout Claude Code bash -c, on Windows with Git Bash (CLAUDE_CODE_GIT_BASH_PATH, else the Git install that holds git.exe), or PowerShell when there is none and the spec sets no shell; exec-form args with no shell; shell: powershell with PowerShell600 seconds, except 30 on UserPromptSubmit, PreModelSwitch, and PostModelSwitch, and 10 on MessageDisplayCodex sh -c; on Windows, commandWindows with powershell.exe -Command600 seconds Gemini bash -c, or Windows PowerShell on Windows, after Gemini replaces $GEMINI_PROJECT_DIR, $GEMINI_CWD, $GEMINI_SESSION_ID, and $CLAUDE_PROJECT_DIR with the quoted root60 seconds Trae bash -c, or PowerShell on Windows30 seconds OpenHands /bin/sh -c, or cmd.exe /c on Windows60 seconds Goose sh -c on every platform30 seconds Augment A .sh, .ps1, .cmd, or .bat script path only, run directly on macOS and Linux, and on Windows with powershell.exe -Command (.ps1) or cmd.exe /c (.cmd, .bat). An inline command is not run.60 seconds Cursor Script path only Assumed 30 seconds Crush Crush's embedded POSIX shell, on every platform. A path starting with ./, ../, or / runs through its shebang interpreter, or with no shebang as shell source. A path without that prefix, such as hooks/guard.sh, starts as a program; on macOS and Linux one without a shebang then fails with exit 1.30 seconds Copilot Exec-form args with no shell. A command is script path only.30 seconds Factory Script path only, where "$FACTORY_PROJECT_DIR" counts as a plain word60 seconds Qoder Exec-form args with no shell; shell: bash with bash -c on macOS and Linux. Without shell, script path only, where "$QODER_PROJECT_DIR" or "${QODER_PROJECT_DIR}" counts as a plain word. shell: powershell, exec form with a $ in command or args, and a shell-form command on Windows are not run.600 seconds Antigravity Script path only 30 seconds Cline bash, running the event script sync writes. Not run on Windows.120 seconds on PreToolUse and PostToolUse; sync drops timeoutKiro Script path only 60 seconds, and assumed 60 for timeout: 0Windsurf Script path only Assumed 30 seconds Claude Code `if` rules
if permission rule decides whether it runs, as in Claude Code. It applies only on PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, and PermissionDenied. See the if field and permission rule syntax.Bash(git *) matches any part of a command split by &&, ||, ;, |, and &, and commands inside $() and backticks, past leading VAR=value assignments and wrappers such as timeout 30. A trailing * also matches the bare command, and :* equals *.$(), backtick, or $VAR. A command that does not parse always runs.Edit(path) covers Edit, Write, MultiEdit, and NotebookEdit, with gitignore patterns: //path from the filesystem root, ~/path from home, /path and path from the project root, and a bare name such as .env at any depth. Tool(param:value) matches a top-level input field.
Decisions
Each command reports one decision.
block: exit 2, or exit 0 with a JSON reply that has"permissionDecision": "deny","decision": "block", or"continue": false.allow: any other exit 0.error: any other non-zero exit.timeout: the command ran past its timeout.
With failClosed: true, Claude Code treats a hook failure as exit 2 for its event, and on PermissionRequest denies the request. Claude Code hook mappings lists the events and handlers that ignore it.
Exit 2 cannot stop anything on Reads stdout, or stderr when stdout is empty. A JSON As Claude Code. Blocks only on Blocks only on Exit 2 blocks on Exit 2 blocks the tool call; exit 49 also halts the whole turn, with a note. Other non-zero exits and a timeout do not block. At exit 0, a JSON Exit 2 blocks, except on Drops Exit 2 blocks on A Only exit 0 with a JSON reply of the documented shape counts; anything else reads as Ignores the exit code and reads stdout as JSON: the last line starting CLI V3 blocks on exit 2 on Devin CLI blocks on exit 2, or exit 0 with Exit 2 blocks on SessionStart, SessionEnd, Notification, PreCompact, and PostCompact, so it reads as error there. On PostToolUse the tool already ran, so block sends stderr back to the model. A context line marks output the tool adds to the session: plain stdout on SessionStart and UserPromptSubmit, or a JSON reply's additionalContext.How other tools read replies
Gemini replies
"decision": "deny" or "block", "continue": false, or plain text with an exit other than 0 and 1 is block. No text, or exit 1, is error. SessionStart, SessionEnd, Notification, and PreCompress ignore decisions, so a block there reads as error. Only a JSON additionalContext reaches the model; plain stdout goes to the user.Trae replies
OpenHands replies
PreToolUse, UserPromptSubmit, and Stop: on exit 2, or a JSON "decision": "deny" or "continue": false at any exit code. A context line marks a JSON additionalContext on UserPromptSubmit and Stop only.Goose replies
PreToolUse and Stop: on exit 2, or stdout starting with { whose decision is "block", at any exit code. Exit 0 with empty stdout or "decision": "allow" allows. Anything else is error, or block with x-goose.on_failure: block.Cursor replies
beforeSubmitPrompt and the permission events: beforeShellExecution, beforeMCPExecution, beforeReadFile, beforeTabFileRead, subagentStart, and preToolUse. At exit 0, a permission event blocks on "permission": "deny", on "ask" (except preToolUse, which does not enforce it), and on output that is not a valid JSON reply; no output fails open. beforeSubmitPrompt blocks on "continue": false. Other failures fail open as error, or block with failClosed: true.Crush replies
"decision": "deny" or "halt": true blocks. A reply with a hookSpecificOutput key reads as Claude Code's, and its top-level fields are ignored. A field of the wrong type voids the reply, which then allows. A context line marks context or additionalContext.Factory replies
Notification, SubagentStop, PreCompact, SessionStart, and SessionEnd, where it reads as error. At exit 0, PreToolUse blocks on permissionDecision "deny" or "ask"; PostToolUse, UserPromptSubmit, Stop, and SubagentStop on "decision": "block"; and every event but SessionEnd on "continue": false.Copilot replies
{"type": "progress"} lines from stdout and parses the rest as one JSON reply; text that does not parse, or two objects, is no reply. preToolUse blocks on any non-zero exit, a command that did not start, or "permissionDecision" "deny" or "ask". A failure other than exit 2 also counts as error, so --expect block fails on a hook that never ran. permissionRequest blocks on exit 2 or "behavior": "deny"; replies merge in order, so a later "behavior": "allow" overrides an earlier deny. agentStop and subagentStop block on "decision": "block". Other events cannot block: failures read as error, except exit 2 on postToolUseFailure, which adds context. A timeout fails open everywhere. PascalCase events decide as their camelCase twins.Qoder replies
UserPromptSubmit, PreToolUse, Stop, SubagentStop, PreCompact, ConfigChange, Elicitation, and ElicitationResult, and any non-zero exit blocks on WorktreeCreate. Other failures read as error; StopFailure and InstructionsLoaded ignore the result. At exit 0, a JSON reply blocks on:"continue": false"decision": "deny", where exit 2 blockspermissionDecision "deny" or "ask" on PreToolUse, which wins over decisiondecision.behavior of "deny" on PermissionRequestaction of "decline" or "cancel" on the elicitation eventshookSpecificOutput without hookEventName voids the reply as error. A ConfigChange with source: policy_settings cannot block, so a block there reads as error. TaskCreated, TaskCompleted, TeammateIdle, and Setup have no documented decision rules, so Qoder is not run for them. A handler's if glob in parentheses matches the command of Bash or the file_path of a file tool; a glob on another tool is not run.Antigravity replies
error or timeout, not counted. On PreToolUse, "decision": "auto_approve" is allow, with a note that explicit user rules still apply; "deny" blocks; "force_ask" blocks, with a note that Antigravity asks the user. "allow" (which defers to the next hook or default policy) reads as allow, and "ask" and "deny_unless_prior_grant" (which saved permissions can let through) read as block; hook run cannot see either, so none of the three is counted. On Stop, "decision": "continue" keeps the agent running and reads as block; any other value allows. PostToolUse, SessionStart, PreInvocation, and PostInvocation allow on a JSON object. hook run builds no SessionStart payload; pass --payload <file>.Cline replies
HOOK_CONTROL and a tab, else the whole stdout. On PreToolUse and PostToolUse, "cancel": true blocks and stops the Cline run; on PostToolUse the tool already ran. Empty stdout and other JSON allow, and a non-zero exit adds a note that Cline ignores it. Stdout that is not JSON reads as error and a timeout as timeout, each with a note that Cline goes on as if the hook allowed. A context line marks context, contextModification, or errorMessage. When other specs reach Cline on the same event, sync writes them into one script that shares stdout, so the result is not counted, even with --include-assumed.Kiro replies
PreToolUse. Another non-zero exit there reads as error, not counted, since Kiro's docs disagree on whether it blocks. UserPromptSubmit allows every exit code, with a note that only the IDE blocks prompts; a non-zero exit adds the output and exit code to context. Stop reads exit 1, or exit 0 with "decision": "block", as block, with a note that Kiro keeps the agent running. Other non-zero exits on PostToolUse and Stop read as error. A context line marks prompt stdout, non-zero prompt exits, and a Stop continuation's reason.Windsurf replies
"decision": "block", on PreToolUse, PermissionRequest, UserPromptSubmit, and Stop. "decision": "approve", no decision, and plain stdout allow. Another non-zero exit is error. Not counted: a block on PostToolUse, PostCompaction, PreCompact, PostCompact, SessionStart, or SessionEnd; a reply on a non-zero exit, except exit 2 with "decision": "block"; and a decision other than "approve" or "block". A PreToolUse reply with hookSpecificOutput.updatedInput gets a note, since Devin CLI merges it into the tool's arguments. A context line marks hookSpecificOutput.additionalContext on UserPromptSubmit, SessionStart, and PostToolUse. Both count only when hookSpecificOutput.hookEventName names the event that ran.Augment replies
PreToolUse only. Exit 0 blocks with permissionDecision: "deny", decision: "block" (inside hookSpecificOutput on Stop and PostToolUse), or "continue": false. A context line marks plain stdout on SessionStart and hookSpecificOutput.additionalContext at exit 0, as on Claude Code.
The run exits 1, so it works as a CI check, when a counted command times out or errors, when two counted tools decide differently, or, with --expect allow or --expect block, when a counted tool decides otherwise.
Assumed results
Some tools' docs leave out part of how a command runs. hook run runs those commands on an assumption instead of skipping them, ends the result line in (assumed: shell, timeout), and adds one line per assumption. An assumed result stays out of --expect and the comparison unless you pass --include-assumed. A warning flags an assumed result that disagrees with the counted ones, and a summary such as 0 checked, 1 assumed (not counted; --include-assumed to count) shows what was left out. With --expect, a run where only assumed results ran fails and asks for --include-assumed, so a CI check never passes on nothing. In JSON, each target has assumptions (item, value, reason) and counted.
| Assumption | Targets | What hook run assumes |
|---|---|---|
| Shell | Cursor, Factory, Antigravity, Kiro, Windsurf, Copilot's command form, Qoder without shell | sh -c on macOS and Linux, only for a script path with plain or single-quoted arguments. A command with shell syntax, such as a pipe, is not run, with a note to use a script path; Windows is not run. Copilot's and Qoder's exec form (args) runs with no shell and assumes none. |
| Timeout | Cursor, Windsurf | 30 seconds when the spec sets none. Set timeout to remove it. |
| Timeout | Kiro | 60 seconds for timeout: 0, which Kiro documents as no limit. |
| Working directory | Copilot | The project root for a hook without cwd. With cwd, a relative exec path resolves from it. |
| Working directory | Factory, Qoder, Antigravity, Windsurf | The project root, since the docs do not say. A command starting "$FACTORY_PROJECT_DIR"/ or "${QODER_PROJECT_DIR}"/ counts as a script path, with the variable set to the root; Windsurf sets DEVIN_PROJECT_DIR the same way. |
| Working directory | Cline | The project root, where Cline uses the directory the CLI started in. |
jq, coreutils | Crush | Crush has built-in jq and, on Windows, cat, ls, rm, find, and the other core utilities, unless CRUSH_CORE_UTILS=false. hook run runs the ones on PATH and adds an assumption for each it reached, only for inline commands and ./ scripts without a shebang. |
Counted and assumed results
A not counted result is one the replies above mark not counted. It stays out of --expect and the comparison even with --include-assumed, though with that flag a timeout or error from another of that tool's commands still fails the run.
Kiro is not run for an agent action, which runs no command; a hook with confirm, which asks the user first; and every trigger but UserPromptSubmit, PreToolUse, PostToolUse, and Stop, whose event data the docs do not show.
A Cursor hook spec uses Cursor's own event names, so other tools are not run. A Copilot hook spec with a PascalCase event such as PreToolUse also runs on Claude Code, which counts, so --expect checks Claude Code and shows Copilot beside it.
The Cline VS Code extension does not read stdout when the script exits non-zero, so a reply printed before a failing exit blocks in the CLI and not in the extension.
JSON output
--format json, or --json, prints the same results as one JSON object; --json fails with any other --format. Each target has a decision (allow, block, error, timeout, or not run with a reason), its warnings, its assumptions, whether it is counted, and one entry per command. exit_code is null after a timeout or a command that did not start. error holds the reason the run fails. When a target cannot be set up, such as a matcher that is not a valid pattern, the object still prints, with the targets checked before it and error naming that target. The exit code is the same as in text:
{
"hook": "protect-files",
"targets": [
{
"target": "claude",
"decision": "block",
"event": "PreToolUse",
"trigger": "Write",
"async": false,
"commands": [
{
"command": ".claude/hooks/protect-files.sh",
"decision": "block",
"exit_code": 2,
"elapsed_ms": 12,
"timed_out": false,
"stdout": "",
"stderr": "Blocked: .github/workflows/tests.yml is protected.\n",
"adds_context": false
}
],
"notes": [],
"warnings": [],
"assumptions": [],
"counted": true
}
]
}
Sample event inputs
A tool that lacks the input a flag needs is not run, and the other tools still run. In each row, tool_response holds placeholder values, and session IDs and transcript paths are made up. Where a section lists several tool names, hook run calls the first one the matcher matches. Gemini, Trae, Goose, Cursor, Crush, Windsurf, and Augment read the matcher as an unanchored regular expression.
Claude Code sample events
--edit calls Write, Edit, or MultiEdit, with an absolute tool_input.file_path. SubagentStart needs no input and starts general-purpose, Explore, or Plan.
Codex sample events
--edit calls apply_patch with an *** Add File: or *** Update File: patch in tool_input.command, and Edit and Write match it.
Gemini sample events
--edit calls write_file or replace, with an absolute tool_input.file_path; --bash calls run_shell_command. A SessionStart source must match exactly.
Trae sample events
--bash calls RunCommand. Trae lists no edit tool input, so Trae is not run on --edit.
OpenHands sample events
--bash calls terminal. The file editor's input is undocumented, so OpenHands is not run on --edit. A * or empty matcher matches all; one with a regex character, or written /re/, must match the whole tool name; any other is an exact name.
Goose sample events
--bash calls shell; --edit calls write or edit. BeforeShellExecution and AfterShellExecution take --bash, and AfterFileEdit and BeforeReadFile take --edit. The matcher applies to matcher_context; one that does not compile, such as *, skips the rule.
Cursor sample events
--bash builds beforeShellExecution and afterShellExecution, and preToolUse and postToolUse on the Shell tool. --edit builds afterFileEdit only, so on preToolUse and postToolUse Cursor is not run. --prompt builds beforeSubmitPrompt.
Crush sample events
hook run builds only PreToolUse and reports other Crush events as not run, so --prompt does not apply. --bash calls bash; --edit calls edit or write. The matcher applies to the lowercase tool name; one that does not compile makes Crush skip the hook, and hook run reports it.
Factory sample events
--bash calls Execute. --edit calls Create; when the matcher picks Edit or ApplyPatch, Factory is not run. --prompt builds UserPromptSubmit. Empty or * matches everything, letters and \| list exact names, and anything else is a case-sensitive regular expression.
Antigravity sample events
--bash calls run_command; --edit calls write_to_file, replace_file_content, or multi_replace_file_content. Antigravity has no prompt event; PreInvocation, PostInvocation, and Stop take --payload. The matcher must match the whole tool name; empty or * matches everything.
Copilot sample events
--bash builds preToolUse and postToolUse on bash, and PreToolUse on Bash. --prompt builds userPromptSubmitted or UserPromptSubmit. --edit is refused, and so is --bash on PostToolUse. A camelCase matcher is anchored as ^(?:PATTERN)$. Copilot runs JavaScript regexes, so a matcher with inline flags, lookaround, backreferences, (?P<name>), POSIX classes, or Go-only escapes such as \A is not run.
Qoder sample events
--bash calls Bash. --edit calls Write; when the matcher picks Edit, Qoder is not run. Empty or * matches everything, letters and \| list exact names, and anything else is a regular expression.
Cline sample events
--bash calls run_commands; --edit calls editor (a model whose id holds gpt or codex calls apply_patch instead, which a note says). --prompt builds UserPromptSubmit, with a note that the CLI may not send that event. Cline has no matcher, so every hook fires; a portable match kind runs the script's tool name check, which allows a call to another tool. PreCompact is not run.
Kiro sample events
--prompt supplies UserPromptSubmit; Stop needs no input. Tool events require --payload; --bash and --edit are refused. CLI V3 ignores prompt and Stop matchers. See Kiro matchers.
Windsurf sample events
--bash builds PreToolUse, PostToolUse, and PermissionRequest on exec. --prompt builds UserPromptSubmit; Stop and PostCompaction need no input. --edit is refused. SessionStart, SessionEnd, PreCompact, and PostCompact take --payload. The matcher applies to tool_name, so a Claude-style Bash matcher does not fire. PreCompact and PostCompact accept manual or auto; a matcher on another event is not run.
Augment sample events
--bash calls launch-process; --edit calls str-replace-editor or save-file. Augment has no prompt event.
Matcher and plugin limits
Gemini matchers compile as Go regular expressions, which reject a few JavaScript forms such as lookahead. Gemini CLI would run those, and hook run compares them as a literal name. GEMINI_PLANS_DIR is not set.
OpenCode and Kilo run hooks as plugins and Zed as tasks, so they are not run. OpenCode V2 plugins receive native event JSON on stdin; the command does not simulate their runtime.
Kiro matchers
Kiro tool matchers without regular-expression syntax select tool IDs, the documented read, write, shell, and web categories, or source tags. They support * and ? wildcards and also try an unanchored regular expression against the tool ID. A matcher with regular-expression syntax uses that expression only.
@mcp, @builtin, @server, and @server/tool select MCP or built-in tools. execute_bash and execute_pwsh selectors match each other. CLI 2.x aliases are not expanded.
@powers, spec, subagent, and context are not run because their complete tool membership is undocumented. A named MCP selector is also not run when underscores make its server/tool boundary ambiguous. Use an anchored regular expression against the internal tool ID.
Sources
Vendor docs and pinned source each tool's hook behavior is checked against:
- Claude Code: Hooks guide.
- Codex: Hooks.
- Copilot: Hooks reference, using hooks with Copilot CLI.
- Cursor: Hooks.
- Gemini CLI: Hooks reference, file system tools, source
c6bccb7. - Qoder: Hooks, hooks reference.
- Factory: Hooks.
- Devin CLI: Hooks, commands triggered by session events.
- Antigravity: Hooks.
- Kiro: Hooks, hook types, hook actions, CLI V3 migration, built-in tools.
- Trae: automate actions with hooks, hook reference.
- Augment: Hooks.
- OpenHands: Hooks, source
fad6377. - Goose: Hooks, source
bab8ff6and runner. - Cline: source
39ff235:hook-file-hooks.ts,subprocess-runner.ts, tool schemas. - Crush: source
76cc5c5:config/config.go,hooks/input.go,hooks/runner.go,shell/dispatch.go,shell/run.go. hook runshell: mvdan.cc/sh and its core utilities, gojq.