diagnosing-hookslisted

Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds versus milliseconds), the command and process field styles are mixed, a hook's JSON output fails validation, a hook blocks the session unexpectedly, or configuration-file hooks are not enabled. Provides configuration sources, the hooks.json schema, how to inspect hooks in the client, and a step-by-step localization and repair workflow.
phoben/agent-skills · ★ 0 · Data & Documents · score 70

Install: claude install-skill phoben/agent-skills

# 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 ```json { "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`, `Pr