Diagnosing Hooks

Diagnosing Hook Configuration

Goal: reduce any hook problem to a single concrete fix.

Note on trust: plugin hooks execute regardless of the marketplace they came from — third-party plugin hooks run just like built-in ones. Any "diagnostic-only until trusted" wording you may see for marketplace hooks is stale; a plugin's detail view marks each hook as runnable, and that is now true for all hooks.

1. Configuration sources and merging

• Configuration-file hooks: the top-level hooks key in ~/.zcode/cli/config.json (or the workspace <repo>/.zcode/config.json / zcode.json), shaped as { enabled?, timeoutMs?, maxOutputBytes?, events: { <Event>: [ { matcher?, hooks: [...] } ] } }. These are disabled by default — configuration-file hooks must set hooks.enabled: true to run.
• Plugin hooks: each plugin's hooks/hooks.json (or its manifest hooks field). Plugin matchers are appended after configuration matchers. When any plugin contributes a hook, the hook runner is enabled automatically.
• Non-plugin (user or workspace) configuration hooks have no trust gate; with enabled: true they run unconditionally.

2. hooks.json schema

{ "hooks": { "<Event>": [ { "matcher": "...", "hooks": [ { "type": "command"|"process", ... } ] } ] } }

(A plugin file uses the outer hooks wrapper; the configuration file uses hooks.events.<Event>. The inner array is the same.)

• Event names (exactly seven): SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Stop. Any other name is an unsupported event. (Events such as Notification, SubagentStop, and PreCompact are not supported.)
• The matcher is a case-sensitive regular expression, tested against the event's match value:
  • SessionStart → one of startup, resume, clear, compact
  • Tool events (PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure) → the tool name (Bash, Read, Write, Edit, Agent, …), with aliases Task ↔ Agent and Write/Edit ← ApplyPatch
  • UserPromptSubmit → the prompt text; Stop → the response preview
  • An omitted matcher matches everything; an invalid regular expression never matches (silently)
• type: "command": command (a shell string); optional shell, timeout (in seconds), timeoutMs (in milliseconds, takes precedence), and statusMessage. Note that async currently has no runtime effect.
• type: "process": command (an executable) plus args[] (an argument vector run without a shell, the most portable choice), timeoutMs (in milliseconds), and statusMessage.
• Timeout resolution: timeoutMs → timeout × 1000 → the configuration's timeoutMs → a default of 60000 ms.
• Template variables (expanded in the command and each argument, and also injected as environment variables): ${CLAUDE_PROJECT_DIR} / ${ZCODE_PROJECT_DIR}, ${CLAUDE_SESSION_ID}; and, for plugin hooks only, ${CLAUDE_PLUGIN_ROOT} / ${ZCODE_PLUGIN_ROOT} and the plugin data directory. Note that a skill-directory variable is not valid in a hook and raises an error.
• Hook output: standard output is parsed as JSON (a strict schema — any extra key fails validation), or you may use exit codes: 0 passes, 2 blocks (a deny for PreToolUse/PermissionRequest), and any other non-zero raises an error. additionalContext is injected into the conversation; PreToolUse may return a permission decision of allow/ask/deny; Stop may request continuation (up to three times).

3. How to inspect hooks

• In the client: Settings → Plugin Management → open a plugin's detail view to see the hooks it registers and whether each is runnable.
• As an agent: read the hooks/hooks.json (or the manifest hooks field) for a plugin, and the hooks block of ~/.zcode/cli/config.json / the workspace config for configuration hooks.
• Execution (fired, timed out, blocked) is recorded in the ZCode log, with the hook's source, matcher, outcome, duration, and a preview of its error stream — enough to distinguish a timeout from a failure from a block.

4. Common pitfalls (symptom → cause → fix)

1. Configuration-file hooks do not run — you added hooks.events.* but nothing fires. They are disabled by default and are enabled automatically only when a plugin hook is present. → Set "hooks": { "enabled": true, ... } in the configuration.
2. Wrong event name — the hook never triggers. → Use exactly one of the seven supported events.
3. Matcher does not match (tool name, case, or regex) — it is registered but never fires for the tool you expect. The matcher is a case-sensitive regular expression; "bash" will not match Bash, and an invalid expression never matches. → Use the exact tool name or a correct expression (for example "Edit|Write"), or omit the matcher to match all. Remember the aliases Task → Agent and Write/Edit → ApplyPatch.
4. Script is not executable — permission denied, with a failed outcome. The script was installed without the executable bit. → Run chmod +x on it, or invoke it through an interpreter, e.g. {"type":"command","command":"bash \"${CLAUDE_PLUGIN_ROOT}/hooks/x.sh\""}, so the executable bit is irrelevant.
5. Template variable not expanded — a literal ${...} or an empty path. Only recognized variables are expanded; a skill-directory variable raises an error inside a hook, and ${CLAUDE_PLUGIN_ROOT} is available only for plugin hooks. → Use only supported variables, and ${CLAUDE_PLUGIN_ROOT} for plugin-relative paths.
6. Timeout unit mistaken — the hook is killed with a timed-out outcome. command's timeout is in seconds; process's timeoutMs is in milliseconds. timeout: 500 means 500 seconds; timeoutMs: 5 means 5 milliseconds. → Use "timeout": <seconds> for a command hook and "timeoutMs": <milliseconds> for a process hook.
7. Command and process fields mixed — the hook is dropped. A process hook accepts only command, args, and timeoutMs; a command hook accepts command, shell, timeout, and timeoutMs. → Match the fields to the type.
8. JSON output fails validation — the hook ran but its effect was discarded and the run marked failed. The output was not valid JSON, contained an extra key (the schema is strict), or its event-specific output named the wrong event. → Emit only the recognized keys with the correct event name, or emit nothing (empty output is fine) and rely on exit codes.
9. Assuming async runs in the background — you set async: true but the session still waits. The async field has no runtime effect and hooks always run inline. → Do not rely on async; for background work, have the script daemonize itself.
10. Cross-platform failure — it works on one operating system but not another. A command hook runs through a shell, so POSIX syntax fails on Windows. → Prefer a process hook (an argument vector, no shell), or ship a polyglot wrapper script and keep hook scripts extensionless.
11. A hook blocks the session unexpectedly — a tool is denied or the run halts. The hook returned a block, exited with code 2, or returned a deny decision. → Inspect the block's reason in the log; fix the script's exit code — return 0 to pass and reserve 2 for a deliberate block.
12. Believing third-party hooks are "diagnostic only" — a third-party plugin hook did not run and you suspect a trust gate. That is not the cause: all plugin hooks are runnable. → Diagnose via pitfalls 2, 3, 4, and 8.