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