Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

docs(hooks): add the hooks guide with type-checked examples

Jack Rudenkoeb289f3beae0
diff --git a/docs/advanced/hooks.md b/docs/advanced/hooks.md
new file mode 100644
index 00000000..b3497918
--- /dev/null
+++ b/docs/advanced/hooks.md
@@ -0,0 +1,854 @@
+# Hooks
+
+**Your own code, run by claudish at named points of a request and of a Claude Code session.**
+
+A hook can change the request a model receives, repair a tool call, add text to or remove text from
+a model's response before Claude Code sees it, and start a new turn on the user's behalf. Hooks
+return **actions**: plain data that claudish checks, applies, logs and attributes to the hook. For
+work no action covers, an **unsafe raw tier** hands a hook the live provider objects.
+
+Hooks are trusted local code. claudish runs them in its own process, with no sandbox. Load only
+modules you wrote or have read.
+
+---
+
+## Quick start
+
+```bash
+claudish hooks init # writes ~/.claudish/hooks/example-hook.ts and claudish-hooks.d.ts
+```
+
+Add the module to `~/.claudish/config.json`:
+
+```json
+{
+ "hooks": {
+ "modules": ["~/.claudish/hooks/example-hook.ts"]
+ }
+}
+```
+
+Check it, then see where it sits among the built-in hooks:
+
+```bash
+claudish hooks check ~/.claudish/hooks/example-hook.ts
+claudish hooks list
+```
+
+This is the file `claudish hooks init` writes:
+
+```ts
+/// <reference path="./claudish-hooks.d.ts" />
+/**
+ * An example claudish hook. Add its path to "hooks.modules" in
+ * ~/.claudish/config.json, then run `claudish hooks list` to see it.
+ *
+ * Check it with: claudish hooks check example-hook.ts
+ */
+import type { HookDefinition } from "claudish/hooks";
+
+export default {
+ apiVersion: 1,
+ id: "reply-language",
+ description: "Asks foreign models to answer in English",
+ routes: "foreign",
+ on: {
+ request(ctx) {
+ ctx.log(`request for ${ctx.route.modelId}`);
+ return [{ type: "injectSystemNote", text: "Always answer in English." }];
+ },
+ },
+} satisfies HookDefinition;
+```
+
+**When a change takes effect.** Each claudish process loads its hooks once, at start. A new
+interactive session or a new `create_session` / `team` child picks up an edit. The MCP server does
+not: it runs the session events of every child it starts, so restart it after you change
+`hooks.modules`. If a child produced an injection that the server cannot deliver, because the server
+loaded no session hooks, claudish says so on stderr when the child ends:
+
+```
+[claudish] a pane child produced hook injections, but this process loaded no session hooks: restart the MCP server after changing hooks.modules
+```
+
+---
+
+## Configuration
+
+Hooks are read from the **global config only**: `~/.claudish/config.json`, or the file named by
+`--config` / `CLAUDISH_CONFIG`, which replaces the global and the project config entirely. A `hooks`
+key in a project `.claudish.json` is ignored, with one line:
+
+```
+[claudish] hooks in <path> ignored: hooks are read from the global config only
+```
+
+A project file is controlled by whoever controls the repository, and claudish will not run code it
+names. A hook that should act only in some projects can check `ctx.session.cwd` or `ctx.harness`.
+
+The same rule covers a repository choosing the config file itself, or posing as claudish's own
+child process. A few environment variables steer claudish rather than configure a provider:
+`CLAUDISH_CONFIG`, the pane-child markers (`CLAUDISH_PANE_CHILD`, `CLAUDISH_PANE_ENV`,
+`CLAUDISH_PANE_CWD`), the hook inbox (`CLAUDISH_HOOK_INBOX`, `CLAUDISH_HOOK_SESSION`) and
+`CLAUDISH_BIN`. They count only when they come from your shell, the MCP server's own `env`, or the
+parent claudish that started the process. No file in the working directory can set them:
+
+- claudish starts Bun with `--no-env-file`: the npm `claudish` command, the `dist/index.js`
+ shebang, and every claudish child it spawns. The shebang uses `env -S`, which GNU and BSD `env`
+ have and BusyBox `env` (Alpine) does not: there, use the npm `claudish` command or run
+ `bun --no-env-file dist/index.js`. The release binary is built with Bun's `.env`
+ autoload off. So Bun reads none of `.env`, `.env.local`, `.env.<NODE_ENV>` or
+ `.env.<NODE_ENV>.local`.
+- claudish reads `.env` in the working directory itself, and takes only provider API keys and
+ claudish model settings from it, so none of these variables, and nothing like `CLAUDE_PATH` or
+ `BUN_OPTIONS` that would choose the code claudish runs. If the file names one you have not set, claudish prints one
+ line and goes on without it:
+
+ ```
+ [claudish] ignoring CLAUDISH_CONFIG in .env: a repository's .env may set only provider API keys and claudish model settings. Set it in your shell, or pass --config.
+ ```
+
+- If Bun was started some other way and did load those files (a hand-typed `bun <path>/index.js`,
+ or `bun <path>/claudish.cjs`), claudish cannot tell their values from yours, so it drops every one
+ of these variables and every name those files set, with one line naming them, and reads
+ `~/.claudish/config.json`. Run the installed `claudish` command, or start Bun with
+ `--no-env-file`.
+
+`--config` is always honoured, because you typed it, and team slots and channel sessions receive it
+from the claudish that started them.
+
+```jsonc
+{
+ "hooks": {
+ // Loaded in order. Absolute, "~/…", or relative to the config file's directory.
+ "modules": ["~/.claudish/hooks/verify-tests.ts", "hooks/tidy-reply.ts"],
+
+ // Severity per hook id. Key: "[modelGlob:]hookIdGlob". Value: "off" | "warn" | "fix".
+ "severity": {
+ "plan-mode/*": "warn",
+ "gpt-5.6-*:plan-mode/plan-file-path": "fix",
+ "hook:tidy-reply/*": "off"
+ },
+
+ // Most hook-caused turns in a row in one session. Integer 1..20, default 3.
+ "injection": { "maxConsecutive": 3 },
+
+ // The built-in observer. mode is "off" or "suggest".
+ "observer": { "enabled": false, "mode": "off" },
+
+ // Upload consent for behaviour telemetry. Default off. The local journal is always on.
+ "telemetry": { "enabled": false }
+ }
+}
+```
+
+| Key | Meaning |
+|---|---|
+| `modules` | Hook modules, loaded in this order. A relative path resolves against the directory of the config file, never the working directory. |
+| `severity` | Overrides a hook's default severity. See [Severity](#severity). |
+| `injection.maxConsecutive` | The cap on consecutive hook-caused turns. A turn the caller or a person starts resets the count. |
+| `observer` | The built-in `observer/divergence` hook: `enabled`, `mode` (`off` or `suggest`), `model`, `timeoutMs`, `watchTools`. |
+| `telemetry.enabled` | Consent to upload behaviour telemetry. `claudish hooks telemetry --enable` sets it. |
+
+An invalid `hooks` block never stops claudish. It prints one line per problem, prefixed
+`[claudish] hooks config:`, and runs with built-in hooks at their default severity and no user
+modules.
+
+### Severity
+
+| Severity | Effect |
+|---|---|
+| `off` | The hook is not called. |
+| `warn` | The hook is called at its place in the chain. Its actions are journaled as `warned` and not applied, so the hooks after it see no change. A `toolCall` or `responseRewrite` hook at `warn` never holds the stream: it sees the response as it was delivered. |
+| `fix` | The hook is called and its actions are applied. This is the default for your hooks. |
+
+A key is `hookIdGlob` or `modelGlob:hookIdGlob`. `*` matches any run of characters, `/` included.
+Model-scoped keys beat unscoped keys. Within each group an exact id beats a glob, and a longer glob
+beats a shorter one. A key that starts with `hook:` is a hook id, never a model scope. For proxy
+events the model is the bare model name the route serves. For session events it is the model the
+caller asked for.
+
+---
+
+## Writing a hook
+
+A module's **default export** is one hook definition or an array of them. Nothing else in the
+module is read.
+
+| Field | Required | Meaning |
+|---|---|---|
+| `apiVersion` | yes | Must be `1`. |
+| `id` | yes | Lowercase letters, digits, `.`, `_`, `-`, with `/` between segments; at most 64 characters. |
+| `description` | no | Shown by `claudish hooks list`. |
+| `defaultSeverity` | no | `off`, `warn` or `fix`. Default `fix`. |
+| `order` | no | `pre`, `normal` or `post`. Default `normal`. |
+| `models` | no | A glob or a list of globs on the bare model name. Default `*`. Proxy events only. |
+| `routes` | no | `foreign`, `native` or `all`. Default `all`. Proxy events only. |
+| `timeoutMs` | no | Per handler call, clamped to the event's maximum and to what is left of the event's budget when your hook's turn comes (see [Events](#events)). |
+| `on` | one of `on` or `raw` | The event handlers. |
+| `unsafe`, `raw` | together | The raw tier. See [The unsafe raw tier](#the-unsafe-raw-tier). |
+
+A hook's **effective id** is `hook:<module file name without extension>/<id>`, for example
+`hook:verify-tests/verify-tests`. Built-in hooks carry no prefix, so a user hook can never take a
+built-in's id. Use the effective id in `severity` keys.
+
+**A module that cannot load is skipped, and claudish starts anyway.** Each problem prints one line
+naming the module and the reason:
+
+- an import error, a throw during import, or an import slower than 10 seconds;
+- no default export, or an export that is not an object;
+- `apiVersion` missing or not `1`:
+ `[claudish] hook <module>#<id>: apiVersion 2 is not supported (this claudish supports 1)`;
+- an invalid field, an unknown key in `on` or `raw` (`on.onRequest is not a hook event`), or no
+ handler at all;
+- `raw` without `unsafe: true`, or a `raw.providerChunk` declared `async`;
+- two modules with the same file name: the later one is skipped whole
+ (`hook module b/ping.js skipped: its name "ping" is already used by a/ping.ts; rename one`);
+- a second hook with the same id in one module: the first is kept.
+
+`claudish hooks check <file>` runs the same checks on one file and exits 1 when it is invalid.
+
+### Types
+
+Two ways to get types, and both need nothing installed:
+
+1. **Type-only import.** `import type { HookDefinition } from "claudish/hooks"` with
+ `export default { … } satisfies HookDefinition`. The import is erased when the module loads. Your
+ editor finds the types in the `claudish-hooks.d.ts` that `claudish hooks init` writes, or in the
+ npm package (`npm i -D claudish`), which exports `claudish/hooks`.
+2. **Value import.** `import { defineHook, act } from "claudish/hooks"`. claudish serves this module
+ itself when it loads your hook. `defineHook` returns its argument and gives the editor full
+ inference. `act` builds actions: `act.appendText("…")` equals `{ type: "appendText", text: "…" }`.
+
+Modules may be `.ts` or `.js`.
+
+### Logging
+
+Log with `ctx.log(message)`. It writes to claudish's debug log, prefixed `[hook <id>]`. Anything a
+hook writes with `console.*`, `process.stdout.write` or `process.stderr.write` goes there too. None
+of it reaches the terminal, Claude Code's screen or the MCP protocol stream. The debug log is written
+only when claudish runs with `--debug-claudish` (or `-d`, or `CLAUDISH_DEBUG=1`), into `logs/` in the
+working directory. That includes the MCP server: `claudish --mcp --debug-claudish`.
+
+The MCP server keeps its protocol stream clean by giving standard output to the protocol writer
+alone. On a platform where it cannot do that, the MCP server loads built-in hooks only, and says:
+
+```
+[claudish] hook modules not loaded by the MCP server: this platform cannot keep hook output off the MCP protocol stream
+```
+
+Every released claudish binary target can.
+
+**Where claudish's own `[claudish] …` lines go.** To stderr, with one exception. Once the
+interactive launcher has handed the screen to Claude Code, they go to `~/.claudish/diag-<pid>.log`
+for the life of the session (deleted when it ends), and to the debug log when it is on. Load-time
+lines, such as a module that failed to load, print before Claude Code starts.
+
+---
+
+## Events
+
+There are two pipelines. **Proxy events** happen to one request on its way to a provider and back.
+**Session events** happen to the Claude Code session claudish runs in a magmux pane.
+
+| Event | Fires | Allowed actions | Timeout per hook (default / max) · budget for all hooks |
+|---|---|---|---|
+| `request` | Once per upstream attempt, on the Claude-format request, before it is converted for the provider. Each provider the routing chain tries is a new attempt. | `injectSystemNote`, `appendUserText`, `replaceMessageText`, `removeMessageText`, `rewriteToolDescription`, `replaceToolDescription`, `replaceToolSchema`, `removeTool`, `warn` | 1 s / 5 s · 5 s |
+| `toolCall` | For each `tool_use` block whose tool the hook lists, once its arguments are complete. | `repairToolArgs`, `warn` | 1 s / 5 s · 5 s per call |
+| `responseRewrite` | Once per response the hook claimed, when the response's `message_delta` arrives. | `appendText`, `prependText`, `replaceText`, `removeText`, `warn` | 2 s / 10 s · 10 s |
+| `responseEnd` | Once per successful response, after the response's end was sent to Claude Code. Every response counts: tool-loop steps, the final answer, side requests. | `injectSystemNote`, `injectUserTurn`, `annotateTurn`, `warn` | 5 s / 30 s · 30 s |
+| `sessionStart` | When the session starts (details below). | `injectUserTurn`, `warn` | 5 s / 30 s · 30 s |
+| `sessionIdle` | Once each time a turn settles, before claudish decides what the session does next. | `injectUserTurn`, `warn` | 5 s / 30 s · 30 s |
+| `sessionBlocked` | A question (`AskUserQuestion`) or a permission or plan dialog opened. | `warn` | 5 s / 30 s · 30 s |
+| `sessionEnd` | The session ended. | `warn` | 1.5 s · 1.5 s |
+
+**Hooks run in a chain.** The hooks of one event run **one after another**, in effective order:
+`order` (`pre`, then `normal`, then `post`), then built-in hooks before yours, then the order of
+`hooks.modules`, then export order. `claudish hooks list` prints this order. Each hook's actions are
+applied before the next hook is called, so a hook sees the request, the tool arguments or the
+response **as the hooks before it left them**. `ctx.prior` lists what those hooks did, with their
+ids. A hook at `warn`, or one that fails, changes nothing for the hooks after it.
+
+A handler may be `async`. Each one gets its own timeout and its own `AbortSignal` (`ctx.signal`).
+Because the hooks of an event take turns, their times add up, so every event also has a **budget**
+for all its hooks together (the last column above). Your hook's timeout is cut to what is left of
+the budget when its turn comes; if nothing is left, it is skipped and journaled `skipped`. Keep
+`request` hooks fast: they run before the request is sent. Different requests, and different tool
+calls of one response, still run independently.
+
+### Proxy events
+
+Every proxy context carries `ctx.route` (`modelId`, `provider`, `native`), `ctx.request` (the model
+Claude Code asked for, `stream`, the system prompt as text, and read-only views of `messages` and
+`tools`), `ctx.harness` (plan mode, the plan file path, the Claude Code session id, the skill
+listing), `ctx.host.mode` and `ctx.session`.
+
+`ctx.session` says which pane session a request belongs to: `{ kind, id, role }`, where `role` is
+`"slot"` or `"judge"` in a team run. It is set in `create_session` and `team` children. It is `null`
+in the interactive launcher and in `claudish serve`.
+
+- **`request`** sees the request after claudish turned it into Claude format, after the actions of
+ every hook before it in the chain, and before any provider conversion. Change it only through
+ actions. Tool descriptions already show earlier hooks' description changes. `ctx.harness` is
+ worked out once, from the request as Claude Code sent it, and is the same for every hook.
+- **Every context is read-only, all the way down.** `ctx.request` (its `messages`, every message and
+ every tool schema), `ctx.harness`, `ctx.route`, `ctx.session`, the actions in `ctx.prior`,
+ `ctx.tool.args` and `ctx.response` are frozen, so a write or an in-place `reverse()`, `sort()` or
+ `push()` throws (the hook fails as any throwing hook does) and never changes what is sent or what
+ the next hook sees. Change things only through actions; to repair arguments, return a new object,
+ such as `act.repairToolArgs({ ...ctx.tool.args, file_path: path }, "reason")`.
+- **`toolCall`** is an object, not a function:
+ - `tools`: the tool names this hook sees. `"*"` means every tool, which holds every tool call's
+ input until it is complete.
+ - `armed(ctx)`: optional and synchronous, called once per request with the request context. Return
+ `false` to skip this request. A throw counts as `false`.
+ - `observe: true`: see the call after it was forwarded. Such a hook can only `warn`, and never holds
+ the stream.
+ - `handle(ctx)`: receives `ctx.tool` (`id`, `name`, `args`, `rawArgs`). `args` are the arguments
+ after any repair an earlier hook made; `rawArgs` is always the model's own JSON. If the model's
+ arguments are not valid JSON, no hook is called and the block passes unchanged.
+
+ Only the listed tool's block is held. Other blocks, text and pings keep flowing.
+- **`responseRewrite`** is an object: `claims(ctx)` and `handle(ctx)`. See
+ [Rewriting a response](#rewriting-a-response).
+- **`responseEnd`** receives `ctx.response`: the response **as Claude Code received it**, after any
+ rewrite and any raw replacement. It holds the blocks, the joined `text` and `reasoning`, the
+ `toolNames` called, and `stopReason`. A `stopReason` of `"tool_use"` marks a step of a tool loop:
+ the turn goes on after the tool runs. `responseEnd` blocks nothing. For turn-level decisions, use
+ `sessionIdle`.
+
+`models` and `routes` filter proxy events only. Hooks never see token-count requests, Claude Code's
+auto-mode classifier calls, `--monitor` traffic, `--probe` traffic, or responses with a non-2xx
+status.
+
+### Session events
+
+Every session context carries `ctx.session`:
+
+| Field | Meaning |
+|---|---|
+| `kind` | `interactive` (the launcher), `channel` (`create_session`) or `team` |
+| `role` | `"slot"` or `"judge"` in a team run; `null` otherwise |
+| `id` | the channel `session_id`, `<run_id>:<slot id>` for a team, or the Claude Code session id for the launcher |
+| `claudeSessionId` | the Claude Code session id, when known |
+| `model` | the model the caller asked for |
+| `cwd` | the session's working directory |
+| `shape` | `interactive` or `one-shot` |
+| `injection` | `available` when claudish can type into the session, else `unavailable` |
+
+- **`sessionStart`** fires in a pane session when the initial prompt starts, or when Claude Code is
+ ready if there is no prompt. In the interactive launcher it fires at the first empty input box. An
+ injection it returns is delivered at the first idle after the initial turn.
+- **`sessionIdle`** receives `ctx.turn`: `index` (1-based; a turn that a background task wakes again
+ keeps its index, and fires `sessionIdle` again when it settles), `answer`, `stopReason`,
+ `apiError`, `hookCaused`, and `annotations`. It also receives `ctx.consecutiveHookTurns` and
+ `ctx.callerInputPending`: when that is `true`, the caller's input goes next, and an injection
+ returned now is dropped as stale.
+- **`sessionBlocked`** receives `ctx.block`: `{ kind: "question" | "permission", text }`. A hook
+ cannot answer the dialog.
+- **`sessionEnd`** receives `ctx.outcome`: `{ state, reason, exitCode }`. In a pane session it never
+ delays the end. In the interactive launcher claudish waits up to 1.5 s for it before shutting down.
+
+`sessionIdle` and `sessionBlocked` need a pane claudish can read. The interactive launcher without
+one (no terminal, no magmux, or `-p`) fires only `sessionStart`, at spawn, and `sessionEnd`, at exit.
+
+---
+
+## Actions
+
+Return an array of actions, or nothing. An action an event does not allow is `invalid` and ignored.
+A hook returns at most 64 actions per call; any beyond the 64th are journaled `invalid`
+(`too_many_actions`) and not applied.
+
+| Action | What it does |
+|---|---|
+| `injectSystemNote` `{ text }` | Appends 1–20,000 characters to the system prompt, as a new paragraph or a new text block. A text an earlier hook of the same request already added is journaled `superseded` and not added again. It reaches every route, chat-completions providers included. Returned from `responseEnd`, it waits for the same Claude Code session's next request that gets a 2xx response. With no session id it is dropped. |
+| `appendUserText` `{ text }` | Adds a text block (1–20,000 characters) at the end of the last `user` message, after any tool results. A text an earlier hook already appended is `superseded`. |
+| `replaceMessageText` `{ find, replace, regex?, flags?, roles? }` | Replaces text in the text blocks of messages whose role is in `roles` (default `["user"]`). Never touches tool calls, tool results, thinking, images or documents. A text block left empty is dropped. An edit that would empty a message is undone for that message. |
+| `removeMessageText` `{ find, regex?, flags?, roles? }` | `replaceMessageText` with an empty replacement. |
+| `rewriteToolDescription` `{ tool, append }` | Appends 1–4,000 characters to a tool's description as the hooks before you left it; later hooks see the result. Applied after claudish shortens tool descriptions (`--summarize-tools`), so the appended text always survives. |
+| `replaceToolDescription` `{ tool, description }` | Replaces a tool's description (1–20,000 characters), at the same point. |
+| `replaceToolSchema` `{ tool, inputSchema }` | Replaces a tool's current input schema; later hooks see yours: a JSON object with `type: "object"`, at most 64 KiB. |
+| `removeTool` `{ tool }` | Removes a tool from the request; later hooks no longer see it. Refused while any message holds a call to that tool. |
+| `repairToolArgs` `{ args, reason }` | Replaces a tool call's current arguments (at most 1 MiB of JSON); later hooks see yours in `ctx.tool.args`. |
+| `appendText` `{ text }` | Appends to the last text block of the response. With no text block, inserts a new one just before the first tool call, or at the end. |
+| `prependText` `{ text }` | Prepends to the first text block. With no text block, inserts one at the start of the held part, after any leading thinking. |
+| `replaceText` `{ find, replace, regex?, flags? }` | Replaces text in each text block of the response, one block at a time. |
+| `removeText` `{ find, regex?, flags? }` | `replaceText` with an empty replacement. A text block left empty is dropped. |
+| `injectUserTurn` `{ text }` | Starts a new user turn when the session is idle. 1–100,000 characters, and it must not start with `/`. See [Starting a new turn](#starting-a-new-turn). |
+| `annotateTurn` `{ key, value }` | Attaches a JSON value (at most 16 KiB) to the current turn. It arrives in `sessionIdle` as `ctx.turn.annotations`. `key` matches `^[a-z0-9][a-z0-9._-]{0,63}$`. Never uploaded. |
+| `warn` `{ message }` | Logged and journaled. Changes nothing. |
+
+**Matching.** `find` is literal by default and replaces every occurrence. A literal `replace` is
+inserted as written: `"$500"` stays `$500`. With `regex: true`, `find` is a regular expression
+source, `flags` is a subset of `gimsuy` (default `"g"`), and `$1`, `$<name>`, `$&` and `$$` work in
+`replace`. An action with `flags` but no `regex: true` is `invalid` and ignored, so a typo never
+turns into a silent literal match.
+
+**Order.** Every action applies over the result of every action before it: your own earlier actions
+in the order you returned them, and everything the hooks before you did. Nothing is first-wins: two
+hooks changing one tool's description, one tool's schema or one tool call's arguments both apply, in
+chain order, and the second sees the first's result. A `replaceToolDescription` therefore drops any
+text an earlier hook appended, a built-in hook's included; append instead, or check `ctx.prior`. A
+duplicate system note or appended user text from a later hook, or an action on a tool an earlier
+hook removed, is journaled `superseded`. Injections from several hooks merge into one turn.
+
+**Failures never break a request or a session.** A throw, a rejected promise, a timeout or an invalid
+return value counts as "no actions" and is journaled; the chain goes on, and the next hook sees what
+the failed one saw. A skip is not counted. A timeout counts unless the hooks before yours cut your
+turn short by more than max(250 ms, 10% of your hook's own timeout), or by more than half your
+hook's own timeout when that is less: then the budget, not your hook, ran out, and it is not
+counted. A smaller cut is just the time the earlier hooks normally
+take, so a hook that hangs is still counted when other hooks run before it. After 5 failures in a
+row a hook is disabled for the rest of the process, with one line:
+`[claudish] hook <id> disabled after 5 consecutive failures (see the debug log)`. One success resets
+the count.
+
+---
+
+## Where hooks run
+
+A hook module's **top-level state belongs to one process**. Which process runs an event depends on
+how Claude Code was started:
+
+| How Claude Code runs | Proxy events run in | Session events run in |
+|---|---|---|
+| Interactive launcher (`claudish`, `claudish -i`) | the claudish process | the same process |
+| `create_session` child (MCP) | the child's own claudish process | the MCP server |
+| `team` slot or judge (MCP or CLI) | the child's own claudish process | the MCP server, or the `claudish team` process |
+| `claudish serve`, the MCP server's own `run_prompt` | that process | none: there is no session |
+
+So in a `create_session` or `team` child, a variable your `responseEnd` handler sets is **not** the
+variable your `sessionIdle` handler reads. They are two copies in two processes. To carry what one
+turn's responses saw into `sessionIdle`, return **`annotateTurn`** from `responseEnd`. It travels with
+the turn and arrives in `ctx.turn.annotations`, in arrival order, in every setup. Filter by
+`a.hookId === ctx.hookId` to read only your own.
+
+**The interactive launcher.** When a loaded hook declares `responseEnd` or a session event, claudish
+needs a pane to read and type into. Started from a normal terminal, it runs Claude Code inside a
+visible magmux, even with `--no-recovery` (the recovery banner and retry watchdog stay off). Started
+inside a magmux pane, it uses that pane. With no terminal, no magmux or `-p`, injections are dropped,
+with one line:
+
+```
+[claudish] hook injection dropped: this claudish process has no Claude Code session to deliver it to
+```
+
+---
+
+## Starting a new turn
+
+`injectUserTurn` types a user message into the session, which starts a new turn. It works in the
+interactive launcher and in `create_session` and `team` children. An injected turn is a user
+message, and the model acts on it as on anything you type, with the session's permissions, so
+inject an instruction ("Run the test suite and report the result."), never a bare marker or token
+that leaves the model to guess what you meant. The rules:
+
+1. **Only when idle.** The turn has settled, the input box is empty, no dialog is open and nothing is
+ running. In the interactive launcher the box must also have stayed empty and unchanged for 1.5 s,
+ so claudish never types into a prompt you are writing. claudish re-reads the transcript and the
+ screen at the moment it would type, not only on its last periodic check: a background task that
+ woke the model, or a prompt you just submitted, makes the injection wait. If the model was woken,
+ the turn runs on and the `responseEnd` injections are offered again when it settles; the
+ `sessionIdle` ones are dropped `rewake`.
+2. **Never over anything.** claudish never presses Esc for an injection, and never types into a
+ dialog or a running turn.
+3. **The caller goes first.** `send_input`, or a prompt you type, always goes before an injection. An
+ injection queued before a caller turn starts is dropped as `stale`. A `sessionStart` injection
+ survives the session's initial prompt. Caller input that arrives while `sessionIdle` hooks run
+ ends the wait at once and drops that wait's injections.
+4. **One turn per idle.** Every injection waiting at one idle merges into one message: `sessionStart`
+ injections, then those from `responseEnd` in arrival order, then those from `sessionIdle` in
+ chain order. They are joined with a blank line, and exact duplicates appear once. However many
+ hooks inject, it is one turn against the cap. A hook can see an earlier hook's injection in
+ `ctx.prior` and skip its own.
+5. **A cap.** At most `hooks.injection.maxConsecutive` (default 3) hook-caused turns in a row. A
+ caller turn resets the count. Over the cap, the injection is dropped `capped`.
+6. **Delivery.** A single line of up to 512 characters is typed. Anything else goes into a file that
+ Claude Code is told to read. When the Read tool is not available, such a message is dropped
+ `delivery_unavailable`.
+7. **Expiry.** An injection not delivered within 10 minutes is dropped `expired`.
+8. **Never mid-turn.** An injection returned from `responseEnd` waits for the turn to settle, even when
+ the response was a tool-loop step.
+
+Every drop is journaled. A pane session also records it in its `events.jsonl` as
+`hook_injection_dropped:<reason>`, and records `hook_injection_delivered` for a delivered one.
+
+An injection is always typed text or a turn file. Its text may not start with `/`: hook text never
+runs a slash command. In `create_session` and `team` children the injections cross from the child's
+proxy to the session's owner through a file, and the owner checks every line again against the same
+rules (`/`, the 100,000-character limit, annotation keys and sizes) before it queues anything. A
+line that fails is dropped `invalid`.
+
+In an interactive session, the turn an injection follows is judged first, as any turn is. A turn
+that ended in an API error fails the session, and the injection is dropped `session_ended`. A task
+file you sent with `send_input` that was not fully read is still reported as `prompt_not_read`.
+
+Residual race in the interactive launcher: a key pressed in the instant between claudish's last check
+and its typing joins the injected line. magmux has no atomic "type only if empty".
+
+### One-shot sessions and team slots: the turn chain
+
+A one-shot `create_session` and every `team` slot normally end at their first settled turn. An
+injection changes that: it **extends the session's turn chain**, and the session ends when the chain
+settles.
+
+- The session reports `RUNNING` from the first turn to the last. It never reports `AWAITING_INPUT`
+ between chain turns, and its `shape` stays `one-shot`.
+- The session's answer is every chain turn's answer joined with a blank line. `get_output` grows
+ turn by turn, and a team slot's `response-<slot>.md` is rewritten after each chain turn.
+- `require_pattern` passes when it matches the joined answer **or any single turn's answer**, so a
+ pattern anchored with `^` still finds the turn that starts with it.
+- Whether the prompt was read is judged on the **first** turn, the one the caller's prompt started.
+ An injected turn delivered as a file and not read records `hook_injection_not_read` and changes no
+ verdict.
+- `timeout_seconds` covers the whole chain. A hook never extends the caller's deadline. A timeout
+ mid-chain keeps every answer already recorded.
+- An injected turn that Claude Code never accepts is dropped `send_not_accepted`, and the session
+ ends on the chain so far.
+- The cap applies: by default a slot runs at most 3 extra turns.
+
+In an interactive `create_session` and in the launcher, an injection simply becomes the next turn,
+with no `waiting_for_input` between the two.
+
+### Judges
+
+A team run's judges are team children too, and hooks run in them. `ctx.session.role` is `"judge"` for
+a judge, in session events and in proxy events alike. An injecting hook would extend a judge's
+verdict into a chain, and a rewriting hook would edit it. **Skip judges** unless you mean to change
+how a team is judged:
+
+```ts
+if (ctx.session?.role === "judge") return;
+```
+
+---
+
+## Rewriting a response
+
+Response rewriting is **opt-in buffering**. A request is held only when a `fix`-severity
+`responseRewrite` hook claims it. Every other request streams exactly as it would with no hooks.
+
+```ts
+responseRewrite: {
+ claims(ctx) { /* synchronous; true = hold this request's response */ },
+ handle(ctx) { /* ctx.response is the held response, with earlier hooks' edits; return text actions */ },
+}
+```
+
+- **`claims(ctx)`** runs once per request, before the response starts, with the request context.
+ Omitted, it counts as `true`, which holds every response on the routes and models the hook
+ matches. Narrow it with `models`, `routes` and `claims`. A throw counts as `false`.
+- **What is held.** The message start and any leading thinking blocks stream live. From the first
+ other block (text, tool call, anything else) until `message_delta`, claudish holds the response.
+ Pings still pass through, and claudish sends its own once a second while it waits, so Claude Code
+ never times out.
+- **The cost.** Text and tool input of a claimed response reach Claude Code all at once, at the end,
+ instead of streaming. Claude Code runs a tool only once its call is complete, so tools are not
+ delayed. What you lose is the live display.
+- **Limits.** If more than 8 MiB is held, claudish sends everything unchanged and stops holding. A
+ text block that carries citations is never rewritten.
+- `stream: false` requests are rewritten the same way, on the JSON body.
+
+---
+
+## The unsafe raw tier
+
+For what no action covers, a hook can declare `unsafe: true` and a `raw` object. Raw hooks receive
+provider-format objects. claudish cannot check what a raw hook writes into them.
+
+```
+[claudish] hook hook:hide-reasoning/hide-reasoning is UNSAFE (raw middleware): it receives live request and response objects
+```
+
+That line prints when the module loads. Every request a raw hook touches also writes one journal line
+(`decision: "raw"`) and one debug-log line.
+
+| Stage | Runs | Gets |
+|---|---|---|
+| `providerRequest(ctx)` | after the request actions, before the request is sent; routes that convert the request (not native Anthropic) | clones of `claudeRequest`, `messages` and `tools` in provider format |
+| `providerChunk(ctx)` | for each parsed provider event, on the `openai-sse` and Responses stream formats | a clone of the event in `ctx.chunk`, its delta in `ctx.delta`, and a per-stream `ctx.metadata` map |
+| `providerStreamEnd(ctx)` | when the provider stream ends, on the `openai-sse`, Responses and Gemini stream formats | `ctx.metadata` |
+| `response(ctx)` | on the Claude-format response, every route | a replay of the response in `ctx.response`; return a new `Response` to replace it |
+
+Raw contexts have no `ctx.log`. Use `console.*`, which goes to the debug log.
+
+The raw hooks of one stage run in a chain too: one after another, in effective order, each on what
+the one before it committed. A stage runs after the closed hooks of its point: `providerRequest`
+after every `request` hook, `response` after every `responseRewrite` hook. A hook with both closed
+and raw handlers takes a turn in each chain.
+
+### What containment covers
+
+A failing raw hook is contained like any other: the request goes on as if the hook had not run.
+
+- **Clone and commit.** `providerRequest` and `providerChunk` work on copies. The copies replace the
+ real objects only when the call returns normally (and, for `providerRequest`, within its timeout).
+ A throw, a rejection or a timeout discards every change, so a hook that empties `messages` and then
+ throws changes nothing.
+- **`providerChunk` must be synchronous.** It runs on the parser's loop. Declared `async`, the module
+ is rejected at load:
+ `raw.providerChunk must be synchronous (it runs on the parser's loop)`. A plain function that
+ returns a promise is caught on each call: its copy is discarded even if it was edited first, the
+ call counts as a failure, and a later rejection is journaled, never thrown. On a normal return the
+ copy is committed as a whole: it **becomes** the event the parser reads, so edits through
+ `ctx.delta`, replacements of `ctx.chunk` and deleted fields all take effect.
+- **A replacement is held whole.** claudish reads the original response to its end itself, so a hook
+ that ignores `ctx.response` delays nothing. A replacement is forwarded only after it closes cleanly
+ within the hook's timeout. On any failure the original goes to Claude Code from its first byte.
+ Claude Code never sees part of a replacement.
+- **The bytes you read are yours.** Each chunk `ctx.response` yields is a copy. Editing it in place
+ changes nothing that is forwarded: the original Claude Code gets on a failure, or at `warn`, is the
+ bytes the provider sent.
+- **`ctx.response` ends when the call does.** Read it inside `response(ctx)`, or in the `Response`
+ you return. A hook that returns nothing and keeps reading in the background sees the stream end
+ early. A returned replacement built from `ctx.response` is read to the original's end, at `fix`
+ and at `warn`.
+- **Severity.** At `warn` a raw hook runs on copies that are never committed, so the next raw hook
+ starts from the uncommitted state, and a replacement is read and discarded.
+
+Containment does **not** cover what a raw hook does on purpose. A hook that returns normally after
+emptying `messages`, or a replacement that closes cleanly with malformed content, is applied as
+written. That is what `unsafe` means.
+
+| Raw stage | Timeout per hook (default / max) · budget for all hooks |
+|---|---|
+| `providerRequest` | 1 s / 5 s · 5 s |
+| `providerChunk` | none: it is synchronous |
+| `providerStreamEnd` | 1 s / 5 s · 5 s |
+| `response` | 1 s / 5 s, for the call and again for the replacement to close · no budget: each hook keeps its own deadlines |
+
+### Example: hide streamed reasoning
+
+```ts
+/// <reference path="./claudish-hooks.d.ts" />
+/**
+ * UNSAFE: a raw hook. It receives provider-format objects, and claudish
+ * cannot check what it writes into them.
+ */
+import type { HookDefinition } from "claudish/hooks";
+
+export default {
+ apiVersion: 1,
+ id: "hide-reasoning",
+ description: "Drops streamed reasoning text before claudish converts it to thinking blocks",
+ unsafe: true,
+ models: "kimi-*",
+ raw: {
+ // Synchronous. It runs on a clone of each parsed provider event; on a
+ // normal return the clone, deletions included, is what the parser reads.
+ providerChunk(ctx) {
+ if (!ctx.delta) return;
+ const hadReasoning = "reasoning_content" in ctx.delta;
+ delete ctx.delta.reasoning_content;
+ if (hadReasoning) ctx.metadata.set("hid", ((ctx.metadata.get("hid") as number) ?? 0) + 1);
+ },
+ providerStreamEnd(ctx) {
+ // console output from a hook goes to claudish's debug log.
+ console.log(`hid ${ctx.metadata.get("hid") ?? 0} reasoning chunks`);
+ },
+ },
+} satisfies HookDefinition;
+```
+
+---
+
+## Worked example 1: inject a user turn and start a new turn
+
+**Goal.** When a model says the tests pass but ran no command during the turn, start one more turn
+that asks it to run them.
+
+**How.** A turn is many responses: each tool call is a step. `responseEnd` sees each response and
+records, with `annotateTurn`, that a command ran. `sessionIdle` fires once when the turn settles,
+reads the annotations, and returns `injectUserTurn` when no command ran.
+
+The two handlers may run in different processes (see [Where hooks run](#where-hooks-run)), which is
+why the fact travels as an annotation and not as a module variable.
+
+```ts
+/// <reference path="./claudish-hooks.d.ts" />
+/**
+ * Starts one extra turn when the model says the tests pass but ran no
+ * command during the turn.
+ */
+import type { HookDefinition } from "claudish/hooks";
+
+export default {
+ apiVersion: 1,
+ id: "verify-tests",
+ description: "Asks the model to run the tests when it claims they pass without running them",
+ on: {
+ // A proxy event. In a team slot or a create_session child it runs in the
+ // pane child's claudish process.
+ responseEnd(ctx) {
+ if (!ctx.response.toolNames.includes("Bash")) return;
+ return [{ type: "annotateTurn", key: "ran-command", value: true }];
+ },
+
+ // A session event. It runs in the process that drives the pane, which may
+ // be a different process: module variables set above are not visible here,
+ // but the annotation is.
+ sessionIdle(ctx) {
+ if (ctx.session.role === "judge") return; // never change a judge's verdict
+ if (ctx.turn.hookCaused) return; // one extra turn per human turn
+ if (ctx.callerInputPending) return; // it would be dropped as stale
+ const ranCommand = ctx.turn.annotations.some(
+ (a) => a.hookId === ctx.hookId && a.key === "ran-command"
+ );
+ if (ranCommand || !/\btests? (all )?pass/i.test(ctx.turn.answer)) return;
+ return [
+ {
+ type: "injectUserTurn",
+ text: "You said the tests pass, but you ran no command this turn. Run the test suite and quote its summary line.",
+ },
+ ];
+ },
+ },
+} satisfies HookDefinition;
+```
+
+**What happens.**
+
+1. The model answers "All tests pass." without calling `Bash`. No annotation arrives.
+2. The turn settles. `sessionIdle` finds the claim and no annotation, and returns the injection.
+3. claudish waits until the session is idle, then types the line. It is one line under 512
+ characters, so it is typed, not sent as a file.
+4. The model runs the tests in a new turn. That turn has `hookCaused: true`, so the hook returns
+ nothing, and the cap is never reached.
+
+In a `team` slot the slot's answer becomes both turns joined, and the slot ends after the second
+turn. In the interactive launcher the new turn appears in your session as if you had typed it.
+
+---
+
+## Worked example 2: add and remove text in a model response
+
+**Goal.** Remove a closing pleasantry that some models add, and put the model's name under its final
+answer.
+
+**How.** A `responseRewrite` hook, scoped with `models` and `claims` so that only the responses it
+edits are held.
+
+```ts
+/// <reference path="./claudish-hooks.d.ts" />
+/**
+ * Removes a closing pleasantry and appends the name of the model that
+ * answered. Only the requests this hook claims are buffered.
+ */
+import { type RewriteAction, act, defineHook } from "claudish/hooks";
+
+export default defineHook({
+ apiVersion: 1,
+ id: "tidy-reply",
+ description: "Removes a closing pleasantry and names the model under its answer",
+ models: ["glm-*", "kimi-*"],
+ routes: "foreign",
+ on: {
+ responseRewrite: {
+ // Decided per request, before the response starts. Unclaimed requests
+ // stream as if the hook did not exist.
+ claims: (ctx) => ctx.session?.role !== "judge",
+ handle(ctx) {
+ const actions: RewriteAction[] = [
+ act.removeText("\\s*I hope this helps[.!]?\\s*$", { regex: true, flags: "i" }),
+ ];
+ // "tool_use" is a step in a tool loop; the turn goes on after the tool
+ // runs. Mark only the response that ends the turn.
+ if (ctx.response.stopReason !== "tool_use") {
+ actions.push(act.appendText(`\n\n_${ctx.route.modelId}_`));
+ }
+ return actions;
+ },
+ },
+ },
+});
+```
+
+**What happens.** A `glm-5` answer ending
+
+```
+Fixed the off-by-one in parse().
+
+I hope this helps!
+```
+
+reaches Claude Code as
+
+```
+Fixed the off-by-one in parse().
+
+_glm-5_
+```
+
+The removal applies to each text block on its own, so `$` means the end of a block. The append goes
+to the last text block. On a response with no text block, `appendText` inserts a new block just
+before the first tool call, which is why the example skips tool-loop steps. Requests to other models,
+and requests from team judges, are not held at all.
+
+---
+
+## Commands
+
+| Command | What it does | Exit |
+|---|---|---|
+| `claudish hooks list [--json]` | Every hook, built-in and yours, in effective order, with its source, events, default and resolved severity, routes, models, order and `UNSAFE` flag. Then the modules that failed to load, and whether a `behavior` block is still in the config. | 0 |
+| `claudish hooks check <file> [--json]` | Loads one module on its own and validates it. | 0 valid, 1 invalid |
+| `claudish hooks init [dir]` | Writes `example-hook.ts` and `claudish-hooks.d.ts` into `dir` (default `~/.claudish/hooks`). Refuses to overwrite either file. | 0, or 1 if a file exists |
+| `claudish hooks corpus [--write] [--json]` | Replays recorded Claude Code transcripts offline and counts plan-mode divergences per model. | 0 |
+| `claudish hooks telemetry [--enable \| --disable] [--json]` | Shows or sets `hooks.telemetry.enabled`, and says what is sent and what never is. | 0 |
+
+### Built-in hooks
+
+| Id | What it does |
+|---|---|
+| `gemini/thought-signature` | Raw. Carries Gemini thought signatures between turns, for model names containing `gemini` or `google/`. |
+| `plan-mode/plan-file-path` | Foreign routes. In plan mode, puts the assigned plan-file path into the `ExitPlanMode` tool description, and moves a `Write`, `Edit` or `NotebookEdit` aimed at another file in the plan directory onto the assigned plan file. |
+| `session-context/no-harness-echo` | Foreign routes. Adds a system note telling the model not to reproduce the session context Claude Code injects (hook output, reminders) in its answer. |
+| `observer/divergence` | Foreign routes, off until `hooks.observer.enabled`: `claudish hooks list` shows the severity it would act with (`fix`) and marks it `inactive` while that setting is off. Asks a small local model whether a watched tool call breaks one of claudish's conformance rules, and logs the verdict to `~/.claudish/behavior-divergences.jsonl`. Advisory only. |
+
+Turn any of them down with a `severity` key, for example `{ "plan-mode/*": "warn" }`.
+
+---
+
+## The journal
+
+Every decision is written to `~/.claudish/behavior-journal.jsonl`: one JSON line with the event, the
+effective hook id, the action, the decision (`matched`, `warned`, `repaired`, `superseded`,
+`invalid`, `timeout`, `error`, `disabled`, `dropped`, `queued`, `delivered`, `raw`, `skipped`, …) and
+the model. `skipped` means the event's budget was used up before your hook's turn; a `timeout` with
+detail `event_budget` means your hook's turn came with less time left than its own timeout, short by
+more than that margin; a shorter cut is journaled with the milliseconds. The
+journal is local and always on. It never stores argument values.
+
+Behaviour telemetry is a separate opt-in (`hooks.telemetry.enabled`). It uploads one set of counts
+per session. Built-in hook ids are uploaded as they are. **Your hook ids are uploaded as `user`**,
+and an MCP tool name on one of your hooks' rows is withheld. Raw-tier rows and the new session
+decisions stay local. `claudish hooks telemetry` prints what is sent and what never is.
+
+---
+
+## Moving from the `behavior` block
+
+The hook system replaces the earlier `behavior` config block and the `claudish behavior` command.
+claudish no longer reads `behavior` at all. If the global config still holds one, claudish prints
+what to move, once per process, and otherwise ignores it:
+
+```
+[claudish] the "behavior" config block is no longer read. Move it to "hooks":
+[claudish] behavior.rules → hooks.severity
+[claudish] behavior.hooks → hooks.modules (modules must be rewritten to the claudish/hooks contract, apiVersion: 1)
+```
+
+It lists only the keys your block has. The full set:
+
+| Old key | Now |
+|---|---|
+| `behavior.rules` | `hooks.severity`, same key syntax |
+| `behavior.hooks` | `hooks.modules`. Each module must be rewritten for this contract: `apiVersion: 1` and handlers under `on`. |
+| `behavior.observer` | `hooks.observer` |
+| `behavior.telemetry` | `hooks.telemetry`. Consent is **not** carried over: set `hooks.telemetry.enabled` yourself. |
+| `behavior.preset` | removed |
+
+claudish leaves the old block in the file and does not drop it on save, so you can copy from it. Delete
+it once you have moved it. `claudish behavior rules|corpus|telemetry` are now
+`claudish hooks list|corpus|telemetry`.
diff --git a/docs/index.md b/docs/index.md
index 93b35e93..c6670731 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -114,6 +114,7 @@ Then just ask Claude:
- **[Environment Variables](advanced/environment.md)** - All configuration options explained
- **[Cost Tracking](advanced/cost-tracking.md)** - Monitor your API spending
- **[Automation](advanced/automation.md)** - Pipes, scripts, CI/CD integration
+- **[Hooks](advanced/hooks.md)** - Your own code at named points of a request and a session: rewrite requests and responses, start a new turn
### AI Integration
- **[For AI Agents](ai-integration/for-agents.md)** - How Claude sub-agents should use Claudish
diff --git a/packages/cli/src/hooks-docs.test.ts b/packages/cli/src/hooks-docs.test.ts
new file mode 100644
index 00000000..7fa0e702
--- /dev/null
+++ b/packages/cli/src/hooks-docs.test.ts
@@ -0,0 +1,100 @@
+/**
+ * The hook examples in `docs/advanced/hooks.md` against the real contract.
+ *
+ * Every ```ts block in the guide that is a whole hook file (it starts with the
+ * same `/// <reference …>` line as the file `claudish hooks init` writes) is
+ * type-checked under `strict` against the declaration `init` writes, and then
+ * loaded with `claudish hooks check`. The guide must also show the init example
+ * verbatim, so the template and the documented starter cannot drift apart.
+ *
+ * The CLI runs with a generated HOME and a `CLAUDISH_CONFIG` override, so the
+ * developer's config is never read or written.
+ */
+
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLI_ROOT = join(import.meta.dir, "..");
+const ENTRY = join(import.meta.dir, "index.ts");
+const DOC = join(CLI_ROOT, "..", "..", "docs", "advanced", "hooks.md");
+const REFERENCE = '/// <reference path="./claudish-hooks.d.ts" />';
+
+const root = mkdtempSync(join(tmpdir(), "claudish-hooks-docs-"));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+let seq = 0;
+/** A fresh directory with an empty override config, and `hooks init` run into `<dir>/hooks`. */
+function initDir(): { target: string; configPath: string } {
+ const dir = mkdtempSync(join(root, `s${++seq}-`));
+ const configPath = join(dir, "config.json");
+ writeFileSync(configPath, "{}");
+ const target = join(dir, "hooks");
+ expect(cli(["init", target], configPath).code).toBe(0);
+ return { target, configPath };
+}
+
+function cli(args: string[], configPath: string) {
+ const proc = Bun.spawnSync(["bun", "--no-env-file", ENTRY, "hooks", ...args], {
+ cwd: CLI_ROOT,
+ env: {
+ PATH: process.env.PATH ?? "",
+ HOME: join(root, "home"),
+ CLAUDISH_CONFIG: configPath,
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+ NO_COLOR: "1",
+ },
+ });
+ return { code: proc.exitCode, stdout: proc.stdout.toString() };
+}
+
+/** Every ```ts block of the guide that is a whole hook file. */
+function examples(): string[] {
+ return [...readFileSync(DOC, "utf8").matchAll(/```ts\n([\s\S]*?)```/g)]
+ .map((m) => m[1] ?? "")
+ .filter((block) => block.startsWith(REFERENCE));
+}
+
+describe("docs/advanced/hooks.md examples", () => {
+ it("shows the file `claudish hooks init` writes, verbatim", () => {
+ const { target } = initDir();
+ expect(examples()).toContain(readFileSync(join(target, "example-hook.ts"), "utf8"));
+ });
+
+ it("every whole-file example type-checks against the init declaration and loads", () => {
+ const { target, configPath } = initDir();
+ const blocks = examples();
+ // The init example, the raw example and the two worked examples.
+ expect(blocks.length).toBeGreaterThanOrEqual(4);
+ const files = blocks.map((block, i) => {
+ const name = `doc-example-${i + 1}.ts`;
+ writeFileSync(join(target, name), block);
+ return name;
+ });
+ writeFileSync(
+ join(target, "tsconfig.json"),
+ JSON.stringify({
+ compilerOptions: {
+ strict: true,
+ noEmit: true,
+ target: "ES2022",
+ module: "ESNext",
+ moduleResolution: "bundler",
+ types: [],
+ },
+ files,
+ })
+ );
+ const tsc = join(CLI_ROOT, "node_modules", ".bin", "tsc");
+ const proc = Bun.spawnSync([tsc, "-p", join(target, "tsconfig.json")], { cwd: target });
+ expect(proc.stdout.toString() + proc.stderr.toString()).toBe("");
+ expect(proc.exitCode).toBe(0);
+
+ for (const name of files) {
+ const r = cli(["check", join(target, name), "--json"], configPath);
+ expect({ name, valid: JSON.parse(r.stdout).valid }).toEqual({ name, valid: true });
+ }
+ });
+});