Skip to content

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

test(hooks): add black-box tests written from the hook contract

Jack Rudenko2ee3647ff80a
diff --git a/packages/cli/src/hooks/blind/chain.blind.test.ts b/packages/cli/src/hooks/blind/chain.blind.test.ts
new file mode 100644
index 00000000..7b50b223
--- /dev/null
+++ b/packages/cli/src/hooks/blind/chain.blind.test.ts
@@ -0,0 +1,1231 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFakeClaudeWrapper } from "../../pane/test-helpers/hermetic-env.ts";
+import { startStubUpstream, stubEndpointConfig } from "../../test-helpers/stub-upstream.ts";
+import {
+ events,
+ ENTRY,
+ type JournalRow,
+ type ProxyFixture,
+ Workspace,
+ hook,
+ readUntil,
+ startProxy,
+ textOf,
+ toolInputs,
+ until,
+ userRows,
+ waitJournal,
+} from "./support.ts";
+
+const fixtures: ProxyFixture[] = [];
+afterEach(async () => {
+ for (const f of fixtures.splice(0)) await f.close();
+});
+
+const disabledBuiltins = { "plan-mode/*": "off", "session-context/*": "off" };
+const traceImports = `import {appendFileSync,existsSync,writeFileSync} from "node:fs";
+import {join} from "node:path";
+const record=(kind,value)=>appendFileSync(join(process.env.HOME,"chain-seen.jsonl"),JSON.stringify({kind,value})+"\\n");`;
+const traced = (on: string, fields = "") => `${traceImports}\n${hook(on, fields)}`;
+const id = (name: string) => `hook:${name}/test`;
+const readTool = {
+ name: "Read",
+ description: "ORIGINAL-DESCRIPTION",
+ input_schema: { type: "object", properties: { file_path: { type: "string" } } },
+};
+
+type ProxyOptions = NonNullable<Parameters<typeof startProxy>[0]>;
+type TraceRow = { kind: string; value: any };
+type ProviderMessage = { role: string; content: string | Array<{ type: string; text?: string }> };
+type ProviderBody = {
+ messages: ProviderMessage[];
+ tools?: Array<{
+ type: string;
+ function: { name: string; description?: string; parameters?: unknown };
+ }>;
+};
+
+async function setup(opts: ProxyOptions = {}): Promise<ProxyFixture> {
+ const f = await startProxy({
+ ...opts,
+ hooks: {
+ ...opts.hooks,
+ severity: { ...disabledBuiltins, ...(opts.hooks?.severity as object) },
+ },
+ });
+ fixtures.push(f);
+ return f;
+}
+
+function trace(ws: Workspace): TraceRow[] {
+ const path = join(ws.layout.home, "chain-seen.jsonl");
+ return existsSync(path)
+ ? readFileSync(path, "utf8")
+ .split("\n")
+ .filter(Boolean)
+ .map((s) => JSON.parse(s))
+ : [];
+}
+function provider(f: ProxyFixture, n = 0): ProviderBody {
+ expect(f.stub.requests[n]).toBeDefined();
+ return f.stub.requests[n]!.body as ProviderBody;
+}
+function contentText(content: ProviderMessage["content"]): string {
+ if (typeof content === "string") return content;
+ expect(content.map((b) => b.type)).toEqual(content.map(() => "text"));
+ return content.map((b) => b.text ?? "").join("\n\n");
+}
+function systemText(f: ProxyFixture, n = 0): string {
+ return provider(f, n)
+ .messages.filter((m) => m.role === "system")
+ .map((m) => contentText(m.content))
+ .join("\n\n");
+}
+// §4.6: hooks edit the Claude-format system prompt ("appended … as a new paragraph"); Stage A
+// runs "before conversion". What conversion to the provider format adds is not fixed by the hook
+// contract (this route prepends its own leading paragraph). So the provider text must END with
+// exactly the hook-controlled text, at a paragraph boundary, and no paragraph before it may be
+// one of the hook-controlled paragraphs (or one listed in `absent`).
+function expectSystem(f: ProxyFixture, expected: string, n = 0, absent: string[] = []): void {
+ const text = systemText(f, n);
+ if (!text.endsWith(expected)) expect(text).toBe(expected); // prints the whole provider text
+ const head = text.slice(0, text.length - expected.length);
+ const hookParagraphs = new Set([...expected.split("\n\n"), ...absent]);
+ expect({
+ boundary: head === "" || head.endsWith("\n\n"),
+ hookParagraphsBeforeIt: head.split("\n\n").filter((p) => hookParagraphs.has(p)),
+ }).toEqual({ boundary: true, hookParagraphsBeforeIt: [] });
+}
+// §4.8 does not say a journal line is on disk by the time the client has the response; wait for
+// the expected number of rows, then assert on them exactly.
+async function settle(ws: Workspace, event: string, count: number): Promise<void> {
+ await until(
+ () =>
+ ws.journal().filter((r) => r.hookId.startsWith("hook:") && r.event === event).length >= count,
+ `${count} ${event} journal rows`
+ );
+}
+function rows(ws: Workspace, event: string): JournalRow[] {
+ const selected = ws.journal().filter((r) => r.hookId.startsWith("hook:") && r.event === event);
+ for (const r of selected)
+ expect({ schema: r.schema, ruleId: r.ruleId }).toEqual({ schema: 2, ruleId: r.hookId });
+ return selected;
+}
+function decisions(ws: Workspace, event: string): string[][] {
+ return rows(ws, event).map((r) => [r.hookId, r.decision]);
+}
+function actions(ws: Workspace, event: string) {
+ return rows(ws, event).map((r) => ({ hookId: r.hookId, action: r.action, decision: r.decision }));
+}
+const applied = (name: string, action: string, decision = "matched") => ({
+ hookId: id(name),
+ action,
+ decision,
+});
+// §4.8 fixes the fields of a journal line, not the order of lines, and in runs 1–2 the lines of
+// one dispatch landed in varying order (even one hook's own actions). Chain ORDER is proven by the
+// traces, ctx.prior and the provider payload; journal rows are compared as an exact multiset.
+const bag = <T>(xs: T[]): T[] =>
+ [...xs].sort((x, y) => JSON.stringify(x).localeCompare(JSON.stringify(y)));
+
+// support.startProxy has no extra-argv/environment seam. This variant uses the same
+// Workspace, fake Claude and stub APIs only, for the public flag and inbox env contract.
+async function launchProxy(
+ opts: ProxyOptions,
+ flags: string[] = [],
+ inbox = false
+): Promise<ProxyFixture> {
+ const ws = new Workspace();
+ const stub = startStubUpstream({
+ format: "openai-sse",
+ script: opts.script ?? [{ parts: [{ text: "original" }] }],
+ });
+ try {
+ const modules = (opts.modules ?? []).map((m) => ws.module(m.name, m.code));
+ ws.save({
+ ...stubEndpointConfig(stub),
+ ...opts.config,
+ hooks: {
+ ...opts.hooks,
+ modules,
+ severity: { ...disabledBuiltins, ...(opts.hooks?.severity as object) },
+ },
+ });
+ const sessionId = randomUUID();
+ ws.sessionIds.push(sessionId);
+ const dump = join(ws.layout.tmp, "claude-env.json");
+ const extra: Record<string, string> = {
+ CLAUDE_PATH: writeFakeClaudeWrapper(ws.layout.tmp),
+ FAKE_CLAUDE_DUMP: dump,
+ CONTRACT_FAKE_MAX_MS: "60000",
+ };
+ if (inbox) {
+ extra.CLAUDISH_HOOK_INBOX = ws.file("hook-inbox.jsonl", "");
+ extra.CLAUDISH_HOOK_SESSION = JSON.stringify({ kind: "channel", id: "0123abcd", role: null });
+ }
+ const p = ws.track(
+ [
+ process.execPath,
+ "--no-env-file",
+ ENTRY,
+ "--config",
+ ws.configFile,
+ "-i",
+ "--model",
+ "stub@fake-model",
+ "-y",
+ "--quiet",
+ "--session-id",
+ sessionId,
+ "--debug-claudish",
+ ...flags,
+ ],
+ extra
+ );
+ await until(() => existsSync(dump) || p.closed, "the configured fake Claude environment");
+ if (!existsSync(dump))
+ throw new Error(`Launcher exited before Claude started: ${p.stderr}\n${p.stdout}`);
+ const env = JSON.parse(readFileSync(dump, "utf8")).env as Record<string, string>;
+ const base = env.ANTHROPIC_BASE_URL;
+ if (!base || !/^http:\/\/(127\.0\.0\.1|localhost):\d+/.test(base))
+ throw new Error(`Not a loopback proxy: ${String(base)}`);
+ const send = (body: Record<string, unknown> = {}) =>
+ fetch(`${base.replace(/\/$/, "")}/v1/messages`, {
+ method: "POST",
+ signal: AbortSignal.timeout(15000),
+ headers: {
+ "content-type": "application/json",
+ "anthropic-version": "2023-06-01",
+ "x-api-key": env.ANTHROPIC_API_KEY ?? "test-placeholder",
+ },
+ body: JSON.stringify({
+ model: "stub@fake-model",
+ max_tokens: 1024,
+ stream: true,
+ messages: [{ role: "user", content: "HELLO" }],
+ metadata: { user_id: JSON.stringify({ session_id: sessionId }) },
+ ...body,
+ }),
+ });
+ const f: ProxyFixture = {
+ ws,
+ process: p,
+ stub,
+ sessionId,
+ fetch: send,
+ async read(body) {
+ const res = await send(body);
+ expect(res.status).toBe(200);
+ expect(res.headers.get("content-type")?.includes("text/event-stream")).toBe(true);
+ const raw = await res.text();
+ expect(events(raw).filter((e) => e.type === "message_stop")).toHaveLength(1);
+ return raw;
+ },
+ async close() {
+ stub.stop();
+ await ws.close();
+ },
+ };
+ fixtures.push(f);
+ return f;
+ } catch (error) {
+ stub.stop();
+ await ws.close();
+ throw error;
+ }
+}
+
+describe("hook chain: each step sees earlier applied actions (§4.4.1 / §4.6)", () => {
+ test("C-1 request B sees A's system note and both reach the provider", async () => {
+ const f = await setup({
+ modules: [
+ { name: "a.ts", code: hook('request(){return [{type:"injectSystemNote",text:"A-NOTE"}]}') },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",ctx.request.systemText);return [{type:"injectSystemNote",text:"B-NOTE"}]}'
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expect(trace(f.ws)).toEqual([{ kind: "B", value: "BASE\n\nA-NOTE" }]);
+ expectSystem(f, "BASE\n\nA-NOTE\n\nB-NOTE");
+ await settle(f.ws, "request", 2);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([applied("a", "injectSystemNote"), applied("b", "injectSystemNote")])
+ );
+ }, 30000);
+
+ test("C-2 B sees appended message blocks and edits A's text before conversion", async () => {
+ const f = await setup({
+ modules: [
+ { name: "a.ts", code: hook('request(){return [{type:"appendUserText",text:"A"}]}') },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",ctx.request.messages);return [{type:"replaceMessageText",find:"A",replace:"B"},{type:"removeMessageText",find:"HOME"}]}'
+ ),
+ },
+ ],
+ });
+ // §4.6: a literal find "replaces all occurrences" in "every text block", so the base text must
+ // not contain "A" ("HEAD" became "HEBD" in the first run).
+ expect(textOf(await f.read({ messages: [{ role: "user", content: "HOME" }] }))).toBe(
+ "original"
+ );
+ expect(trace(f.ws)).toEqual([
+ {
+ kind: "B",
+ value: [
+ {
+ role: "user",
+ content: [
+ { type: "text", text: "HOME" },
+ { type: "text", text: "A" },
+ ],
+ },
+ ],
+ },
+ ]);
+ // Dropping HOME leaves precisely one block: no provider-specific join separator to guess.
+ expect(
+ provider(f)
+ .messages.filter((m) => m.role === "user")
+ .map((m) => contentText(m.content))
+ ).toEqual(["B"]);
+ await settle(f.ws, "request", 3);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([
+ applied("a", "appendUserText"),
+ applied("b", "replaceMessageText"),
+ applied("b", "removeMessageText"),
+ ])
+ );
+ }, 30000);
+
+ for (const reverse of [false, true]) {
+ test(`C-3 response B sees earlier text; ${reverse ? "reversed-order negative control" : "append then replace"}`, async () => {
+ const modules = [
+ {
+ name: "a.ts",
+ code: hook('responseRewrite:{handle(){return [{type:"appendText",text:"-A"}]}}'),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'responseRewrite:{handle(ctx){record("B",{text:ctx.response.text,blocks:ctx.response.blocks});return [{type:"replaceText",find:"-A",replace:"-B"}]}}'
+ ),
+ },
+ ];
+ const f = await setup({
+ modules: reverse ? modules.reverse() : modules,
+ script: [{ parts: [{ text: "seed-A" }] }],
+ });
+ expect(textOf(await f.read())).toBe(reverse ? "seed-B-A" : "seed-B-B");
+ const seen = reverse ? "seed-A" : "seed-A-A";
+ expect(trace(f.ws)).toEqual([
+ { kind: "B", value: { text: seen, blocks: [{ type: "text", text: seen }] } },
+ ]);
+ const ordered = reverse ? ["b", "a"] : ["a", "b"];
+ await settle(f.ws, "responseRewrite", 2);
+ expect(bag(decisions(f.ws, "responseRewrite"))).toEqual(
+ bag(ordered.map((name) => [id(name), "matched"]))
+ );
+ expect(bag(actions(f.ws, "responseRewrite"))).toEqual(
+ bag(ordered.map((name) => applied(name, name === "a" ? "appendText" : "replaceText")))
+ );
+ }, 30000);
+ }
+
+ test("C-4 repairs compose; args change but rawArgs stays the model's JSON", async () => {
+ const originalArgs = { file_path: "MODEL-PATH" };
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'toolCall:{tools:["Read"],handle(ctx){record("A",{args:ctx.tool.args,rawArgs:ctx.tool.rawArgs,prior:ctx.prior});return [{type:"repairToolArgs",args:{file_path:"/a"},reason:"first"}]}}'
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'toolCall:{tools:["Read"],handle(ctx){record("B",{args:ctx.tool.args,rawArgs:ctx.tool.rawArgs,prior:ctx.prior});return [{type:"repairToolArgs",args:{file_path:"/b"},reason:"second"}]}}'
+ ),
+ },
+ ],
+ script: [{ parts: [{ toolCall: { name: "Read", args: originalArgs } }], deltaChars: 2 }],
+ });
+ const raw = await f.read({ tools: [readTool] });
+ expect(textOf(raw)).toBe("");
+ expect(toolInputs(raw)).toEqual([{ name: "Read", input: { file_path: "/b" } }]);
+ expect(trace(f.ws)).toEqual([
+ {
+ kind: "A",
+ value: { args: originalArgs, rawArgs: JSON.stringify(originalArgs), prior: [] },
+ },
+ {
+ kind: "B",
+ value: {
+ args: { file_path: "/a" },
+ rawArgs: JSON.stringify(originalArgs),
+ prior: [
+ {
+ hookId: id("a"),
+ action: { type: "repairToolArgs", args: { file_path: "/a" }, reason: "first" },
+ },
+ ],
+ },
+ },
+ ]);
+ await settle(f.ws, "toolCall", 2);
+ expect(bag(actions(f.ws, "toolCall"))).toEqual(
+ bag([applied("a", "repairToolArgs", "repaired"), applied("b", "repairToolArgs", "repaired")])
+ );
+ expect(rows(f.ws, "toolCall").map((r) => ({ tool: r.toolName, keys: r.argKeys }))).toEqual([
+ { tool: "Read", keys: ["file_path"] },
+ { tool: "Read", keys: ["file_path"] },
+ ]);
+ }, 30000);
+
+ for (const summarize of [false, true]) {
+ test(`C-5 description replace then append composes${summarize ? " under --summarize-tools" : " without summarisation"}`, async () => {
+ const f = await launchProxy(
+ {
+ modules: [
+ {
+ name: "a.ts",
+ code: hook(
+ 'request(){return [{type:"replaceToolDescription",tool:"Read",description:"X"}]}'
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",ctx.request.tools);return [{type:"rewriteToolDescription",tool:"Read",append:"Y"}]}'
+ ),
+ },
+ ],
+ },
+ summarize ? ["--summarize-tools"] : []
+ );
+ expect(textOf(await f.read({ tools: [readTool] }))).toBe("original");
+ expect(trace(f.ws)).toEqual([{ kind: "B", value: [{ ...readTool, description: "X" }] }]);
+ expect(
+ provider(f).tools?.map((t) => ({
+ name: t.function.name,
+ description: t.function.description,
+ }))
+ ).toEqual([{ name: "Read", description: "XY" }]);
+ await settle(f.ws, "request", 2);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([applied("a", "replaceToolDescription"), applied("b", "rewriteToolDescription")])
+ );
+ }, 30000);
+ }
+
+ test("C-6 later schema replacement sees the earlier schema and wins on the provider payload", async () => {
+ const first = {
+ type: "object",
+ properties: { first: { type: "integer" } },
+ required: ["first"],
+ };
+ const second = {
+ type: "object",
+ properties: { second: { type: "string" } },
+ required: ["second"],
+ };
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: hook(
+ `request(){return [{type:"replaceToolSchema",tool:"Read",inputSchema:${JSON.stringify(first)}}]}`
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ `request(ctx){record("B",ctx.request.tools);return [{type:"replaceToolSchema",tool:"Read",inputSchema:${JSON.stringify(second)}}]}`
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ tools: [readTool] }))).toBe("original");
+ expect(trace(f.ws)).toEqual([{ kind: "B", value: [{ ...readTool, input_schema: first }] }]);
+ expect(
+ provider(f).tools?.map((t) => ({ name: t.function.name, schema: t.function.parameters }))
+ ).toEqual([{ name: "Read", schema: second }]);
+ await settle(f.ws, "request", 2);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([applied("a", "replaceToolSchema"), applied("b", "replaceToolSchema")])
+ );
+ }, 30000);
+
+ test("C-7 removed tools disappear from B's view and a later append is tool_removed", async () => {
+ const keep = {
+ name: "Keep",
+ description: "KEEP",
+ input_schema: { type: "object", properties: {} },
+ };
+ const f = await setup({
+ modules: [
+ { name: "a.ts", code: hook('request(){return [{type:"removeTool",tool:"Read"}]}') },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",{names:ctx.request.tools.map(t=>t.name),prior:ctx.prior});return [{type:"rewriteToolDescription",tool:"Read",append:"LATE"}]}'
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ tools: [readTool, keep] }))).toBe("original");
+ expect(trace(f.ws)).toEqual([
+ {
+ kind: "B",
+ value: {
+ names: ["Keep"],
+ prior: [{ hookId: id("a"), action: { type: "removeTool", tool: "Read" } }],
+ },
+ },
+ ]);
+ expect(provider(f).tools?.map((t) => t.function)).toEqual([
+ { name: "Keep", description: "KEEP", parameters: keep.input_schema },
+ ]);
+ await settle(f.ws, "request", 2);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([applied("a", "removeTool"), applied("b", "rewriteToolDescription", "superseded")])
+ );
+ expect(userRows(f.ws, id("b")).map((r) => r.detail)).toEqual(["tool_removed"]);
+ }, 30000);
+});
+
+describe("hook chain: failure, severity, order and prior (§4.4.1 / §4.5 / §4.8)", () => {
+ for (const [target, failure, decision] of [
+ ["C-8", "throw", "error"],
+ ["C-9", "timeout", "timeout"],
+ ["C-10", "invalid", "invalid"],
+ ] as const) {
+ test(`${target} ${failure} in the middle leaves A's change visible to C`, async () => {
+ const middle =
+ failure === "throw"
+ ? 'request(ctx){record("B-start",Date.now());throw new Error("MIDDLE-FAIL")}'
+ : failure === "invalid"
+ ? 'request(ctx){record("B-start",Date.now());return "not-an-array"}'
+ : 'request(ctx){record("B-start",Date.now());return new Promise(resolve=>ctx.signal.addEventListener("abort",()=>{record("B-aborted",Date.now());setTimeout(()=>{record("B-late",true);resolve([{type:"injectSystemNote",text:"LATE"}])},100)},{once:true}))}';
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced('request(){record("A",true);return [{type:"injectSystemNote",text:"A"}]}'),
+ },
+ { name: "b.ts", code: traced(middle, "timeoutMs:500,") },
+ {
+ name: "c.ts",
+ code: traced(
+ 'request(ctx){record("C",{at:Date.now(),system:ctx.request.systemText,prior:ctx.prior});return [{type:"injectSystemNote",text:"C"}]}'
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expectSystem(f, "BASE\n\nA\n\nC", 0, ["LATE"]);
+ await settle(f.ws, "request", 3);
+ const beforeLate = trace(f.ws);
+ const c = beforeLate.find((r) => r.kind === "C")!;
+ expect({ system: c.value.system, prior: c.value.prior }).toEqual({
+ system: "BASE\n\nA",
+ prior: [{ hookId: id("a"), action: { type: "injectSystemNote", text: "A" } }],
+ });
+ if (failure === "timeout") {
+ await until(
+ () => trace(f.ws).some((r) => r.kind === "B-late"),
+ "the discarded late result"
+ );
+ const seen = trace(f.ws);
+ expect(seen.map((r) => r.kind)).toEqual(["A", "B-start", "B-aborted", "C", "B-late"]);
+ expect(c.value.at).toBeGreaterThanOrEqual(seen.find((r) => r.kind === "B-aborted")!.value);
+ expect(
+ userRows(f.ws, id("b"))
+ .filter((r) => r.decision === "timeout")
+ .map((r) => r.detail === "event_budget")
+ ).toEqual([false]);
+ } else expect(beforeLate.map((r) => r.kind)).toEqual(["A", "B-start", "C"]);
+ expect(bag(decisions(f.ws, "request"))).toEqual(
+ bag([
+ [id("a"), "matched"],
+ [id("b"), decision],
+ [id("c"), "matched"],
+ ])
+ );
+ // The late timeout result has had a chance to resolve; it still applied nowhere.
+ expectSystem(f, "BASE\n\nA\n\nC", 0, ["LATE"]);
+ }, 30000);
+ }
+
+ test("C-11 a warn middle hook contributes neither working text nor prior actions", async () => {
+ const f = await setup({
+ modules: [
+ { name: "a.ts", code: hook('request(){return [{type:"injectSystemNote",text:"A"}]}') },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",{system:ctx.request.systemText,prior:ctx.prior});return [{type:"injectSystemNote",text:"WARN-EDIT"}]}'
+ ),
+ },
+ {
+ name: "c.ts",
+ code: traced(
+ 'request(ctx){record("C",{system:ctx.request.systemText,prior:ctx.prior});return [{type:"injectSystemNote",text:"C"}]}'
+ ),
+ },
+ ],
+ hooks: { severity: { "hook:b/test": "warn" } },
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ const value = {
+ system: "BASE\n\nA",
+ prior: [{ hookId: id("a"), action: { type: "injectSystemNote", text: "A" } }],
+ };
+ expect(trace(f.ws)).toEqual([
+ { kind: "B", value },
+ { kind: "C", value },
+ ]);
+ expectSystem(f, "BASE\n\nA\n\nC", 0, ["WARN-EDIT"]);
+ await settle(f.ws, "request", 3);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([
+ applied("a", "injectSystemNote"),
+ applied("b", "injectSystemNote", "warned"),
+ applied("c", "injectSystemNote"),
+ ])
+ );
+ }, 30000);
+
+ test("C-12 a fast post hook starts only after the slow pre hook returns, despite export order", async () => {
+ const code = `${traceImports}
+ export default [
+ {apiVersion:1,id:"post",order:"post",on:{request(ctx){record("post-start",ctx.request.systemText);return [{type:"injectSystemNote",text:"POST"}]}}},
+ {apiVersion:1,id:"pre",order:"pre",timeoutMs:5000,on:{async request(){record("pre-start",true);while(!existsSync(join(process.env.HOME,"release-pre")))await Bun.sleep(10);record("pre-return",true);return [{type:"injectSystemNote",text:"PRE"}]}}}
+ ];`;
+ const f = await setup({ modules: [{ name: "ordered.ts", code }] });
+ const request = f.read({ system: "BASE" });
+ try {
+ await until(() => trace(f.ws).some((r) => r.kind === "pre-start"), "the pre hook's gate");
+ expect(trace(f.ws)).toEqual([{ kind: "pre-start", value: true }]);
+ } finally {
+ writeFileSync(join(f.ws.layout.home, "release-pre"), "GO");
+ }
+ expect(textOf(await request)).toBe("original");
+ expect(trace(f.ws)).toEqual([
+ { kind: "pre-start", value: true },
+ { kind: "pre-return", value: true },
+ { kind: "post-start", value: "BASE\n\nPRE" },
+ ]);
+ expectSystem(f, "BASE\n\nPRE\n\nPOST");
+ await settle(f.ws, "request", 2);
+ expect(bag(decisions(f.ws, "request"))).toEqual(
+ bag([
+ ["hook:ordered/pre", "matched"],
+ ["hook:ordered/post", "matched"],
+ ])
+ );
+ }, 30000);
+
+ test("C-13 prior is empty for the first step and lists only applied actions, in order", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'request(ctx){record("A",ctx.prior);return [{type:"injectSystemNote",text:"A"},{type:"injectSystemNote",text:"A"},{type:"warn",message:"ADVISORY"},{type:"removeTool",tool:"Missing"}]}'
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",ctx.prior);return [{type:"appendUserText",text:"B"}]}'
+ ),
+ },
+ { name: "c.ts", code: traced('request(ctx){record("C",ctx.prior)}') },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ const a = { hookId: id("a"), action: { type: "injectSystemNote", text: "A" } };
+ const b = { hookId: id("b"), action: { type: "appendUserText", text: "B" } };
+ expect(trace(f.ws)).toEqual([
+ { kind: "A", value: [] },
+ { kind: "B", value: [a] },
+ { kind: "C", value: [a, b] },
+ ]);
+ expectSystem(f, "BASE\n\nA");
+ await settle(f.ws, "request", 5);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([
+ applied("a", "injectSystemNote"),
+ applied("a", "injectSystemNote", "superseded"),
+ applied("a", "warn", "warned"),
+ applied("a", "removeTool", "invalid"),
+ applied("b", "appendUserText"),
+ ])
+ );
+ expect(
+ userRows(f.ws, id("a"))
+ .filter((r) => r.decision === "superseded")
+ .map((r) => r.detail)
+ ).toEqual(["duplicate"]);
+ }, 30000);
+});
+
+describe("hook chain: budgets, signals and dispatch independence (§4.4.1 / §4.5)", () => {
+ test("C-14 event budget clips step 3, skips step 4, and five budget timeouts do not disable step 3", async () => {
+ const modules = ["a", "b", "c"].map((name) => ({
+ name: `${name}.ts`,
+ code: traced(
+ `async request(ctx){
+ const probe=ctx.request.systemText.startsWith("PROBE"), started=Date.now();
+ record("${name}-start",{probe,at:started});
+ ctx.signal.addEventListener("abort",()=>record("${name}-abort",{probe,elapsed:Date.now()-started}),{once:true});
+ if(!probe)await Bun.sleep(2000);
+ record("${name}-return",{probe});
+ return [{type:"injectSystemNote",text:"${name.toUpperCase()}"}];
+ }`,
+ "timeoutMs:5000,"
+ ),
+ }));
+ modules.push({
+ name: "d.ts",
+ code: traced(
+ 'request(ctx){record("d-start",{probe:ctx.request.systemText.startsWith("PROBE")});return [{type:"injectSystemNote",text:"D"}]}',
+ "timeoutMs:5000,"
+ ),
+ });
+ const f = await setup({ modules });
+ for (let n = 0; n < 5; n++) {
+ const sentAt = Date.now();
+ expect(textOf(await f.read({ system: `BASE-${n}` }))).toBe("original");
+ expectSystem(f, `BASE-${n}\n\nA\n\nB`, n, ["C", "D"]);
+ // Broad bounds, measured at the upstream, not completion/startup or a thin 5 s cutoff.
+ expect(f.stub.requests[n]!.at - sentAt).toBeGreaterThanOrEqual(4000);
+ expect(f.stub.requests[n]!.at - sentAt).toBeLessThan(14000);
+ }
+ await settle(f.ws, "request", 20);
+ expect(bag(decisions(f.ws, "request"))).toEqual(
+ bag(
+ Array.from({ length: 5 }, () => [
+ [id("a"), "matched"],
+ [id("b"), "matched"],
+ [id("c"), "timeout"],
+ [id("d"), "skipped"],
+ ]).flat()
+ )
+ );
+ expect(
+ userRows(f.ws, id("c")).map((r) => ({ decision: r.decision, detail: r.detail }))
+ ).toEqual(Array.from({ length: 5 }, () => ({ decision: "timeout", detail: "event_budget" })));
+ expect(
+ userRows(f.ws, id("d")).map((r) => ({ decision: r.decision, detail: r.detail }))
+ ).toEqual(Array.from({ length: 5 }, () => ({ decision: "skipped", detail: "event_budget" })));
+ expect(trace(f.ws).filter((r) => r.kind === "d-start")).toEqual([]);
+ const aborted = trace(f.ws).filter((r) => r.kind === "c-abort");
+ expect(aborted).toHaveLength(5);
+ for (const r of aborted) {
+ expect(r.value.probe).toBe(false);
+ expect(r.value.elapsed).toBeGreaterThanOrEqual(0);
+ expect(r.value.elapsed).toBeLessThan(3500);
+ }
+ // A sixth, fast dispatch proves C still runs after the fifth timeout.
+ expect(textOf(await f.read({ system: "PROBE" }))).toBe("original");
+ expectSystem(f, "PROBE\n\nA\n\nB\n\nC\n\nD", 5);
+ await settle(f.ws, "request", 24);
+ expect(bag(decisions(f.ws, "request").slice(-4))).toEqual(
+ bag(["a", "b", "c", "d"].map((name) => [id(name), "matched"]))
+ );
+ expect(
+ trace(f.ws)
+ .filter((r) => r.kind === "c-start")
+ .map((r) => r.value.probe)
+ ).toEqual([false, false, false, false, false, true]);
+ expect(rows(f.ws, "request").filter((r) => r.decision === "disabled")).toEqual([]);
+ await until(
+ () => trace(f.ws).filter((r) => r.kind === "c-return").length === 6,
+ "all discarded late C returns"
+ );
+ expect(userRows(f.ws, id("c")).map((r) => r.decision)).toEqual([
+ "timeout",
+ "timeout",
+ "timeout",
+ "timeout",
+ "timeout",
+ "matched",
+ ]);
+ }, 90000);
+
+ test("C-15 five own-timeout failures disable a hook; later steps and the sixth request still succeed", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'request(ctx){record("A-call",true);return new Promise(()=>ctx.signal.addEventListener("abort",()=>record("A-abort",true),{once:true}))}',
+ "timeoutMs:200,"
+ ),
+ },
+ { name: "b.ts", code: hook('request(){return [{type:"injectSystemNote",text:"B"}]}') },
+ ],
+ });
+ for (let n = 0; n < 6; n++) {
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expectSystem(f, "BASE\n\nB", n);
+ }
+ await waitJournal(f.ws, (r) => r.hookId === id("a") && r.decision === "disabled");
+ // Journal line order is not part of the contract (§4.8; session decision 2026-10-15): the fifth
+ // timeout and the disable come from one request, so wait for all six A rows and compare them as
+ // an exact multiset.
+ await until(() => userRows(f.ws, id("a")).length >= 6, "six A journal rows");
+ expect(trace(f.ws)).toEqual(
+ Array.from({ length: 5 }, () => [
+ { kind: "A-call", value: true },
+ { kind: "A-abort", value: true },
+ ]).flat()
+ );
+ expect(bag(userRows(f.ws, id("a")).map((r) => r.decision))).toEqual(
+ bag(["timeout", "timeout", "timeout", "timeout", "timeout", "disabled"])
+ );
+ expect(
+ userRows(f.ws, id("a"))
+ .filter((r) => r.decision === "timeout")
+ .map((r) => r.detail === "event_budget")
+ ).toEqual([false, false, false, false, false]);
+ await until(() => userRows(f.ws, id("b")).length >= 6, "six B journal rows");
+ expect(userRows(f.ws, id("b")).map((r) => r.decision)).toEqual(Array(6).fill("matched"));
+ expect(
+ f.ws.diagnostics(f.process).split(`hook ${id("a")} disabled after 5 consecutive failures`)
+ ).toHaveLength(2);
+ }, 30000);
+
+ test("C-16 A timing out does not abort B's separate signal at B's return", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'request(ctx){return new Promise(()=>ctx.signal.addEventListener("abort",()=>record("A",ctx.signal.aborted),{once:true}))}',
+ "timeoutMs:200,"
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'async request(ctx){await Bun.sleep(100);record("B",{aborted:ctx.signal.aborted,prior:ctx.prior,system:ctx.request.systemText});return [{type:"injectSystemNote",text:"B"}]}',
+ "timeoutMs:2000,"
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expect(trace(f.ws)).toEqual([
+ { kind: "A", value: true },
+ { kind: "B", value: { aborted: false, prior: [], system: "BASE" } },
+ ]);
+ expectSystem(f, "BASE\n\nB");
+ await settle(f.ws, "request", 2);
+ expect(bag(decisions(f.ws, "request"))).toEqual(
+ bag([
+ [id("a"), "timeout"],
+ [id("b"), "matched"],
+ ])
+ );
+ }, 30000);
+
+ test("C-17 client cancel aborts a running rewrite and never invokes or journals its successor", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'responseRewrite:{handle(ctx){if(ctx.request.systemText==="CONTROL")return [{type:"appendText",text:"-A"}];record("A-start",true);return new Promise(resolve=>ctx.signal.addEventListener("abort",()=>{record("A-abort",ctx.signal.aborted);setTimeout(()=>{record("A-late",true);resolve([{type:"appendText",text:"-LATE"}])},100)},{once:true}))}}',
+ "timeoutMs:8000,"
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'responseRewrite:{handle(ctx){record("B",ctx.request.systemText);return [{type:"appendText",text:"-B"}]}}'
+ ),
+ },
+ ],
+ });
+ const res = await f.fetch({ system: "CANCEL" });
+ expect(res.status).toBe(200);
+ const reader = res.body!.getReader();
+ try {
+ const prefix = await readUntil(reader, (raw) =>
+ events(raw).some((e) => e.type === "message_start")
+ );
+ expect(textOf(prefix)).toBe("");
+ await until(
+ () => trace(f.ws).some((r) => r.kind === "A-start"),
+ "the cancellable rewrite step"
+ );
+ await reader.cancel();
+ await until(
+ () => trace(f.ws).some((r) => r.kind === "A-late"),
+ "dispatch abort and the discarded late rewrite"
+ );
+ expect(trace(f.ws)).toEqual([
+ { kind: "A-start", value: true },
+ { kind: "A-abort", value: true },
+ { kind: "A-late", value: true },
+ ]);
+ expect(rows(f.ws, "responseRewrite")).toEqual([]);
+ // This successor does run on a fresh dispatch: its absence above is cancellation, not filtering.
+ expect(textOf(await f.read({ system: "CONTROL" }))).toBe("original-A-B");
+ expect(trace(f.ws)).toEqual([
+ { kind: "A-start", value: true },
+ { kind: "A-abort", value: true },
+ { kind: "A-late", value: true },
+ { kind: "B", value: "CONTROL" },
+ ]);
+ await settle(f.ws, "responseRewrite", 2);
+ expect(bag(actions(f.ws, "responseRewrite"))).toEqual(
+ bag([applied("a", "appendText"), applied("b", "appendText")])
+ );
+ } finally {
+ await reader.cancel().catch(() => {});
+ }
+ }, 30000);
+
+ test("C-23 a second tool call's whole chain completes while the first call's first step is gated", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'toolCall:{tools:["Read","Write"],async handle(ctx){record("A-start",ctx.tool.name);if(ctx.tool.name==="Read"){ctx.signal.addEventListener("abort",()=>record("A-abort","Read"),{once:true});while(!existsSync(join(process.env.HOME,"release-tool"))&&!ctx.signal.aborted)await Bun.sleep(10);record("A-return","Read")}return [{type:"repairToolArgs",args:{file_path:ctx.tool.args.file_path+"-A"},reason:"A"}]}}',
+ "timeoutMs:5000,"
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'toolCall:{tools:["Read","Write"],handle(ctx){record("B",{name:ctx.tool.name,args:ctx.tool.args,prior:ctx.prior});return [{type:"repairToolArgs",args:{file_path:ctx.tool.args.file_path+"-B"},reason:"B"}]}}'
+ ),
+ },
+ ],
+ script: [
+ {
+ parts: [
+ { toolCall: { name: "Read", args: { file_path: "FIRST" } } },
+ { toolCall: { name: "Write", args: { file_path: "SECOND" } } },
+ ],
+ },
+ ],
+ });
+ const request = f.read();
+ try {
+ await until(
+ () => trace(f.ws).some((r) => r.kind === "B" && r.value.name === "Write"),
+ "the independent Write chain"
+ );
+ expect(trace(f.ws).map((r) => r.kind)).toEqual(["A-start", "A-start", "B"]);
+ expect(
+ trace(f.ws)
+ .filter((r) => r.kind === "A-start")
+ .map((r) => r.value)
+ ).toEqual(["Read", "Write"]);
+ expect(trace(f.ws).find((r) => r.kind === "B")!.value).toEqual({
+ name: "Write",
+ args: { file_path: "SECOND-A" },
+ prior: [
+ {
+ hookId: id("a"),
+ action: { type: "repairToolArgs", args: { file_path: "SECOND-A" }, reason: "A" },
+ },
+ ],
+ });
+ } finally {
+ writeFileSync(join(f.ws.layout.home, "release-tool"), "GO");
+ }
+ const raw = await request;
+ expect(textOf(raw)).toBe("");
+ expect(toolInputs(raw)).toEqual([
+ { name: "Read", input: { file_path: "FIRST-A-B" } },
+ { name: "Write", input: { file_path: "SECOND-A-B" } },
+ ]);
+ expect(trace(f.ws).map((r) => r.kind)).toEqual(["A-start", "A-start", "B", "A-return", "B"]);
+ expect(
+ trace(f.ws)
+ .filter((r) => r.kind === "B")
+ .map((r) => r.value)
+ ).toEqual([
+ {
+ name: "Write",
+ args: { file_path: "SECOND-A" },
+ prior: [
+ {
+ hookId: id("a"),
+ action: { type: "repairToolArgs", args: { file_path: "SECOND-A" }, reason: "A" },
+ },
+ ],
+ },
+ {
+ name: "Read",
+ args: { file_path: "FIRST-A" },
+ prior: [
+ {
+ hookId: id("a"),
+ action: { type: "repairToolArgs", args: { file_path: "FIRST-A" }, reason: "A" },
+ },
+ ],
+ },
+ ]);
+ await settle(f.ws, "toolCall", 4);
+ expect(
+ bag(
+ rows(f.ws, "toolCall").map((r) => ({
+ hookId: r.hookId,
+ decision: r.decision,
+ tool: r.toolName,
+ }))
+ )
+ ).toEqual(
+ bag([
+ { hookId: id("a"), decision: "repaired", tool: "Write" },
+ { hookId: id("b"), decision: "repaired", tool: "Write" },
+ { hookId: id("a"), decision: "repaired", tool: "Read" },
+ { hookId: id("b"), decision: "repaired", tool: "Read" },
+ ])
+ );
+ }, 30000);
+});
+
+describe("hook chain: responseEnd hand-off and stored-note step zero", () => {
+ // C-18 first draft drove the inbox from an `-i` launcher. The inbox is a pane-child sink
+ // ("set by the owner for every pane child", §4.10); in a no-surface launcher injections are
+ // "dropped `unavailable`" (§4.7 rule 8). So this test uses the hand-off that host does accept:
+ // a responseEnd note "queued for the next request" (§4.4.1 rule 5). Inbox order is C-18b.
+ test("C-18 responseEnd B sees A's queued note in prior; injections a no-surface launcher drops are not listed", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "a.ts",
+ code: traced(
+ 'responseEnd(ctx){record("A",ctx.prior);return [{type:"injectSystemNote",text:"A-END"},{type:"injectUserTurn",text:"X"}]}'
+ ),
+ },
+ {
+ name: "b.ts",
+ code: traced(
+ 'responseEnd(ctx){record("B",ctx.prior);return [{type:"injectUserTurn",text:"Y"}]}'
+ ),
+ },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ await until(
+ () => trace(f.ws).some((r) => r.kind === "B"),
+ "the responseEnd chain's second step"
+ );
+ expect(trace(f.ws)).toEqual([
+ { kind: "A", value: [] },
+ {
+ kind: "B",
+ value: [{ hookId: id("a"), action: { type: "injectSystemNote", text: "A-END" } }],
+ },
+ ]);
+ await settle(f.ws, "responseEnd", 3);
+ const end = rows(f.ws, "responseEnd");
+ expect(
+ bag(
+ end
+ .filter((r) => r.action === "injectUserTurn")
+ .map((r) => ({ hookId: r.hookId, decision: r.decision, detail: r.detail }))
+ )
+ ).toEqual(
+ bag([
+ { hookId: id("a"), decision: "dropped", detail: "unavailable" },
+ { hookId: id("b"), decision: "dropped", detail: "unavailable" },
+ ])
+ );
+ expect(end.filter((r) => r.action === "injectSystemNote").map((r) => r.hookId)).toEqual([
+ id("a"),
+ ]);
+ // §4.7 rule 8: "one stderr line per process the first time it happens" — two drops, one line.
+ // Once the launcher handed the screen over, `[claudish] …` lines go to diag-<pid>.log (guide,
+ // Logging), whose line prefix is not fixed; match the guide's message text, as C-15 does.
+ expect(
+ f.ws
+ .diagnostics(f.process)
+ .split(
+ "hook injection dropped: this claudish process has no Claude Code session to deliver it to"
+ )
+ ).toHaveLength(2);
+ // The queued note is real: the session's next request carries it.
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expectSystem(f, "BASE\n\nA-END", 1, ["X", "Y"]);
+ }, 30000);
+ test.todo(
+ "C-18b inbox inject lines follow responseEnd chain order: needs a pane-child host (CLAUDISH_HOOK_INBOX is set by the owner, §4.10)"
+ );
+
+ test("C-20 a pending responseEnd note is visible to the next request's first hook as step zero", async () => {
+ const f = await setup({
+ modules: [
+ {
+ name: "request.ts",
+ code: traced(
+ 'request(ctx){record("request",{system:ctx.request.systemText,prior:ctx.prior})}'
+ ),
+ },
+ {
+ name: "end.ts",
+ code: `${traceImports}\nlet calls=0;${hook('responseEnd(ctx){if(++calls===1)return [{type:"injectSystemNote",text:"PENDING"}]}')}`,
+ },
+ ],
+ });
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === id("end") && r.event === "responseEnd" && r.action === "injectSystemNote"
+ );
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expect(trace(f.ws)).toEqual([
+ { kind: "request", value: { system: "BASE", prior: [] } },
+ {
+ kind: "request",
+ value: {
+ system: "BASE\n\nPENDING",
+ prior: [
+ {
+ hookId: "behavior/pending-correction",
+ action: { type: "injectSystemNote", text: "PENDING" },
+ },
+ ],
+ },
+ },
+ ]);
+ expectSystem(f, "BASE", 0, ["PENDING"]);
+ expectSystem(f, "BASE\n\nPENDING", 1);
+ // A third request proves the note was consumed, rather than put in global state.
+ expect(textOf(await f.read({ system: "BASE" }))).toBe("original");
+ expect(trace(f.ws).slice(-1)).toEqual([
+ { kind: "request", value: { system: "BASE", prior: [] } },
+ ]);
+ expectSystem(f, "BASE", 2, ["PENDING"]);
+ await waitJournal(f.ws, (r) => r.hookId === "behavior/pending-correction");
+ expect(
+ f.ws
+ .journal()
+ .filter((r) => r.hookId === "behavior/pending-correction")
+ .map((r) => ({ hookId: r.hookId, event: r.event, action: r.action, decision: r.decision }))
+ ).toEqual([
+ {
+ hookId: "behavior/pending-correction",
+ event: "request",
+ action: "injectSystemNote",
+ decision: "matched",
+ },
+ ]);
+ }, 30000);
+
+ // These targets need inputs/interfaces the supplied contract does not define.
+ // Named TODOs keep them visible without guessing a host API or passing a weaker test.
+ test.todo(
+ "C-19 sessionIdle prior, duplicate merge and one hook-caused turn: needs a documented session owner/driver setup"
+ );
+ test.todo(
+ "C-21 harness.planModeActive stays true after removing the marker: needs the exact plan-mode request marker"
+ );
+ test.todo(
+ "C-22 pre precedes and normal follows the plan-mode built-in: needs the plan marker/path format and exact ExitPlanMode append"
+ );
+});
+
+describe("hook chain: controls and the array-system coverage target", () => {
+ test("C-24 one hook preserves the single-hook semantics; no modules is the negative control", async () => {
+ const single = await setup({
+ modules: [
+ {
+ name: "single.ts",
+ code: traced(
+ 'request(ctx){record("request-prior",ctx.prior);return [{type:"injectSystemNote",text:"ONE"}]},responseRewrite:{handle(ctx){record("rewrite-prior",ctx.prior);return [{type:"appendText",text:"-ONE"}]}}'
+ ),
+ },
+ ],
+ });
+ expect(textOf(await single.read({ system: "BASE" }))).toBe("original-ONE");
+ expectSystem(single, "BASE\n\nONE");
+ expect(trace(single.ws)).toEqual([
+ { kind: "request-prior", value: [] },
+ { kind: "rewrite-prior", value: [] },
+ ]);
+ await settle(single.ws, "request", 1);
+ await settle(single.ws, "responseRewrite", 1);
+ expect(rows(single.ws, "request")).toHaveLength(1);
+ expect(bag(actions(single.ws, "request"))).toEqual(
+ bag([applied("single", "injectSystemNote")])
+ );
+ expect(bag(actions(single.ws, "responseRewrite"))).toEqual(
+ bag([applied("single", "appendText")])
+ );
+ expect(
+ single.ws
+ .journal()
+ .filter((r) => r.hookId.startsWith("hook:"))
+ .map((r) => ({ event: r.event, hookId: r.hookId, action: r.action, decision: r.decision }))
+ ).toEqual([
+ { event: "request", ...applied("single", "injectSystemNote") },
+ { event: "responseRewrite", ...applied("single", "appendText") },
+ ]);
+ const none = await setup({ modules: [] });
+ expect(textOf(await none.read({ system: "BASE" }))).toBe("original");
+ expectSystem(none, "BASE");
+ expect(none.ws.journal().filter((r) => r.hookId.startsWith("hook:"))).toEqual([]);
+ }, 45000);
+
+ test("C-25 extra target: array system keeps every existing block and adds the same note only once", async () => {
+ const f = await setup({
+ modules: [
+ { name: "a.ts", code: hook('request(){return [{type:"injectSystemNote",text:"NOTE"}]}') },
+ {
+ name: "b.ts",
+ code: traced(
+ 'request(ctx){record("B",ctx.request.systemText);return [{type:"injectSystemNote",text:"NOTE"}]}'
+ ),
+ },
+ ],
+ });
+ expect(
+ textOf(
+ await f.read({
+ system: [
+ { type: "text", text: "BLOCK-1" },
+ { type: "text", text: "BLOCK-2" },
+ ],
+ })
+ )
+ ).toBe("original");
+ // Conversion's separator for array-system blocks is not fixed by §4.6. Compare
+ // the entire ordered text list, not a substring or the raw clone's incidental shape.
+ expect(trace(f.ws).map((r) => ({ kind: r.kind, text: r.value.split(/\n+/) }))).toEqual([
+ { kind: "B", text: ["BLOCK-1", "BLOCK-2", "NOTE"] },
+ ]);
+ // Same rule as expectSystem: the provider text ends with the three blocks, NOTE once, and the
+ // paragraphs conversion put before them are none of these.
+ const blocks = systemText(f).split(/\n+/);
+ expect(blocks.slice(-3)).toEqual(["BLOCK-1", "BLOCK-2", "NOTE"]);
+ expect(blocks.slice(0, -3).filter((p) => ["BLOCK-1", "BLOCK-2", "NOTE"].includes(p))).toEqual(
+ []
+ );
+ await settle(f.ws, "request", 2);
+ expect(bag(actions(f.ws, "request"))).toEqual(
+ bag([applied("a", "injectSystemNote"), applied("b", "injectSystemNote", "superseded")])
+ );
+ expect(userRows(f.ws, id("b")).map((r) => r.detail)).toEqual(["duplicate"]);
+ }, 30000);
+});
diff --git a/packages/cli/src/hooks/blind/cli.blind.test.ts b/packages/cli/src/hooks/blind/cli.blind.test.ts
new file mode 100644
index 00000000..a2385ea4
--- /dev/null
+++ b/packages/cli/src/hooks/blind/cli.blind.test.ts
@@ -0,0 +1,405 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Workspace, hook } from "./support.ts";
+
+const workspaces: Workspace[] = [];
+function workspace() {
+ const ws = new Workspace();
+ workspaces.push(ws);
+ ws.save({ hooks: {} });
+ return ws;
+}
+afterEach(async () => {
+ for (const ws of workspaces.splice(0)) await ws.close();
+});
+
+interface ListedHook {
+ id: string;
+ source: string;
+ events: string[];
+ defaultSeverity: string;
+ severity: string;
+ routes: string;
+ models: string[];
+ order: string;
+ unsafe: boolean;
+}
+interface Listed {
+ apiVersion: number;
+ configFile: string;
+ hooks: ListedHook[];
+ errors: Array<{ module: string; reason: string }>;
+ behaviorConfigFound: boolean;
+}
+async function list(ws: Workspace): Promise<Listed> {
+ const result = await ws.cli(["hooks", "list", "--json"]);
+ expect(result.code).toBe(0);
+ const parsed = JSON.parse(result.stdout) as Listed;
+ expect(Object.keys(parsed).sort()).toEqual([
+ "apiVersion",
+ "behaviorConfigFound",
+ "configFile",
+ "errors",
+ "hooks",
+ ]);
+ expect({ apiVersion: parsed.apiVersion, configFile: parsed.configFile }).toEqual({
+ apiVersion: 1,
+ configFile: ws.configFile,
+ });
+ return parsed;
+}
+
+describe("FR-1 / FR-7 / FR-10 CLI and module loading (§4.1–4.3, §4.9)", () => {
+ for (const extension of ["ts", "js"]) {
+ test(`L-1/L-2 ${extension} default hook loads with exact metadata and valid check exit`, async () => {
+ const ws = workspace();
+ const file = ws.module(`sample.${extension}`, hook("request() { return []; }"));
+ ws.save({ hooks: { modules: [file] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:"))).toEqual([
+ {
+ id: "hook:sample/test",
+ source: expect.any(String),
+ events: ["request"],
+ defaultSeverity: "fix",
+ severity: "fix",
+ routes: "all",
+ models: ["*"],
+ order: "normal",
+ unsafe: false,
+ },
+ ]);
+ expect(result.errors).toEqual([]);
+ expect(result.behaviorConfigFound).toBe(false);
+ expect((await ws.cli(["hooks", "check", file])).code).toBe(0);
+ }, 20000);
+ }
+
+ test("L-3 default array preserves export order and built-in hook ids", async () => {
+ const ws = workspace();
+ const file = ws.module(
+ "array.ts",
+ `export default [
+ {apiVersion:1,id:"first",on:{request(){return []}}},
+ {apiVersion:1,id:"second",on:{responseEnd(){return []}}}
+ ];`
+ );
+ ws.save({ hooks: { modules: [file] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual([
+ "hook:array/first",
+ "hook:array/second",
+ ]);
+ for (const id of [
+ "plan-mode/plan-file-path",
+ "session-context/no-harness-echo",
+ "gemini/thought-signature",
+ "observer/divergence",
+ ]) {
+ expect(result.hooks.find((h) => h.id === id)?.source).toBe("builtin");
+ }
+ }, 20000);
+
+ test("L-4 author value imports resolve without installing a separate hooks module", async () => {
+ const ws = workspace();
+ const file = ws.module(
+ "author.ts",
+ `import {act,defineHook} from "claudish/hooks";
+ const action = act.injectSystemNote("VALUE-IMPORT");
+ if (action.type !== "injectSystemNote" || action.text !== "VALUE-IMPORT") throw new Error("bad action constructor");
+ export default defineHook({apiVersion:1,id:"author",on:{request(){return [action]}}});`
+ );
+ expect((await ws.cli(["hooks", "check", file, "--json"])).code).toBe(0);
+ ws.save({ hooks: { modules: [file] } });
+ expect((await list(ws)).hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual(
+ ["hook:author/author"]
+ );
+ }, 20000);
+
+ const invalid = [
+ ["L-5 missing apiVersion", `export default {id:"test",on:{request(){}}};`, "apiVersion"],
+ [
+ "L-5 wrong apiVersion",
+ `export default {apiVersion:2,id:"test",on:{request(){}}};`,
+ "apiVersion 2 is not supported",
+ ],
+ ["L-6 missing id", "export default {apiVersion:1,on:{request(){}}};", "id"],
+ ["L-6 uppercase id", `export default {apiVersion:1,id:"Upper",on:{request(){}}};`, "id"],
+ [
+ "L-6 id exceeds 64 chars",
+ `export default {apiVersion:1,id:"${"a".repeat(65)}",on:{request(){}}};`,
+ "id",
+ ],
+ [
+ "L-7 raw without unsafe",
+ `export default {apiVersion:1,id:"test",raw:{providerChunk(){}}};`,
+ "unsafe",
+ ],
+ [
+ "L-8/X-3 async providerChunk",
+ `export default {apiVersion:1,id:"test",unsafe:true,raw:{async providerChunk(){}}};`,
+ "raw.providerChunk must be synchronous",
+ ],
+ [
+ "L-9 no default export",
+ `export const named = {apiVersion:1,id:"test",on:{request(){}}};`,
+ "default",
+ ],
+ ["L-9 primitive export", `export default "not a hook";`, "hook"],
+ [
+ "L-10 unknown old event",
+ `export default {apiVersion:1,id:"test",on:{onRequest(){}}};`,
+ "onRequest",
+ ],
+ ["L-10 no handler", `export default {apiVersion:1,id:"test"};`, "handler"],
+ ["L-11 throwing import", `throw new Error("IMPORT-FAIL"); export default {};`, "IMPORT-FAIL"],
+ ];
+ for (const [scenario, code, diagnostic] of invalid) {
+ test(`${scenario} exits check 1, reports the cause, and does not block a valid sibling`, async () => {
+ const ws = workspace();
+ const bad = ws.module("bad.ts", code!);
+ const good = ws.module("good.ts", hook("request(){return []}"));
+ const check = await ws.cli(["hooks", "check", bad]);
+ expect(check.code).toBe(1);
+ expect(check.stdout + check.stderr).toContain(diagnostic!);
+ ws.save({ hooks: { modules: [bad, good] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual([
+ "hook:good/test",
+ ]);
+ expect(result.errors.some((e) => e.module === bad && e.reason.includes(diagnostic!))).toBe(
+ true
+ );
+ }, 30000);
+ }
+
+ test("L-12 nonexistent module is reported but hooks list still exits zero", async () => {
+ const ws = workspace();
+ const missing = join(ws.layout.tmp, "does-not-exist.ts");
+ ws.save({ hooks: { modules: [missing] } });
+ const result = await list(ws);
+ expect(result.errors.map((e) => e.module)).toEqual([missing]);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:"))).toEqual([]);
+ }, 20000);
+
+ test("L-13 duplicate effective id keeps only the first hook", async () => {
+ const ws = workspace();
+ const file = ws.module(
+ "dup.ts",
+ `export default [
+ {apiVersion:1,id:"same",on:{request(){}}},
+ {apiVersion:1,id:"same",on:{responseEnd(){}}}
+ ];`
+ );
+ ws.save({ hooks: { modules: [file] } });
+ const p = await ws.cli(["hooks", "list", "--json"]);
+ const result = JSON.parse(p.stdout) as Listed;
+ expect(p.code).toBe(0);
+ expect(result.hooks.filter((h) => h.id === "hook:dup/same").map((h) => h.events)).toEqual([
+ ["request"],
+ ]);
+ // L-13: §4.9 — `hooks list` reports load problems in `errors`; the duplicate is named there.
+ expect(result.errors.map((e) => e.module)).toEqual([file]);
+ }, 20000);
+
+ test("L-14 basename collision skips the later module whole and names both paths", async () => {
+ const ws = workspace();
+ const earlier = ws.module("a/ping.ts", hook("request(){}"));
+ const later = ws.module(
+ "b/ping.js",
+ `export default [{apiVersion:1,id:"different",on:{responseEnd(){}}}];`
+ );
+ ws.save({ hooks: { modules: [earlier, later] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual([
+ "hook:ping/test",
+ ]);
+ expect(result.errors).toEqual([
+ { module: later, reason: expect.stringContaining("already used") },
+ ]);
+ expect(result.errors[0]!.reason).toContain(earlier);
+ }, 20000);
+
+ test("L-15 relative module path resolves against config directory rather than cwd", async () => {
+ const ws = workspace();
+ ws.file("config/hooks/relative.ts", hook("request(){}"));
+ ws.save({ hooks: { modules: ["hooks/relative.ts"] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id === "hook:relative/test").map((h) => h.events)).toEqual([
+ ["request"],
+ ]);
+ expect(result.errors).toEqual([]);
+ }, 20000);
+
+ test("L-16 a hook: severity key is unscoped and exact id beats shorter globs", async () => {
+ const ws = workspace();
+ const file = ws.module("sample.ts", hook("request(){}"));
+ ws.save({
+ hooks: {
+ modules: [file],
+ severity: { "*": "off", "hook:sample/*": "warn", "hook:sample/test": "fix" },
+ },
+ });
+ expect((await list(ws)).hooks.find((h) => h.id === "hook:sample/test")?.severity).toBe("fix");
+ }, 20000);
+
+ for (const badHooks of [
+ { modules: [123] },
+ { modules: [], severity: { "*": "enforce" } },
+ { modules: [], injection: { maxConsecutive: 0 } },
+ { modules: [], injection: { maxConsecutive: 21 } },
+ { modules: [], observer: { enabled: true, mode: "enforce" } },
+ ]) {
+ test(`L-17 invalid hooks ${JSON.stringify(badHooks)} warns and runs defaults`, async () => {
+ const ws = workspace();
+ ws.save({ hooks: badHooks });
+ const result = await ws.cli(["hooks", "list", "--json"]);
+ expect(result.code).toBe(0);
+ expect(result.stderr).toContain("[claudish] hooks config:");
+ const parsed = JSON.parse(result.stdout) as Listed;
+ expect(parsed.hooks.filter((h) => h.id.startsWith("hook:"))).toEqual([]);
+ expect(parsed.hooks.find((h) => h.id === "plan-mode/plan-file-path")?.severity).toBe("fix");
+ }, 20000);
+ }
+
+ test("L-18 old behavior is reported once, not executed, and not rewritten on read", async () => {
+ const ws = workspace();
+ const executed = join(ws.layout.tmp, "old-imported");
+ const old = ws.module(
+ "old.ts",
+ `import {writeFileSync} from "node:fs"; writeFileSync(${JSON.stringify(executed)}, "WRONG"); export default {};`
+ );
+ ws.save({
+ behavior: {
+ rules: { "*": "off" },
+ hooks: [old],
+ observer: { enabled: true },
+ telemetry: { enabled: true },
+ preset: "old",
+ },
+ hooks: {},
+ });
+ const before = readFileSync(ws.configFile, "utf8");
+ const result = await ws.cli(["hooks", "list", "--json"]);
+ expect(result.code).toBe(0);
+ expect((JSON.parse(result.stdout) as Listed).behaviorConfigFound).toBe(true);
+ expect(existsSync(executed)).toBe(false);
+ expect(
+ (result.stderr.match(/the "behavior" config block is no longer read/g) ?? []).length
+ ).toBe(1);
+ for (const key of [
+ "behavior.rules",
+ "hooks.severity",
+ "behavior.hooks",
+ "hooks.modules",
+ "apiVersion: 1",
+ "behavior.observer",
+ "hooks.observer",
+ "behavior.telemetry",
+ "hooks.telemetry",
+ "behavior.preset",
+ ])
+ expect(result.stderr).toContain(key);
+ expect(readFileSync(ws.configFile, "utf8")).toBe(before);
+ }, 20000);
+
+ test("L-19 init writes a loadable example and declaration, then preserves both on refusal", async () => {
+ const ws = workspace();
+ const dir = join(ws.layout.tmp, "author-hooks");
+ expect((await ws.cli(["hooks", "init", dir])).code).toBe(0);
+ const example = join(dir, "example-hook.ts");
+ const types = join(dir, "claudish-hooks.d.ts");
+ const before = [readFileSync(example, "utf8"), readFileSync(types, "utf8")];
+ expect(before[0]).toContain("apiVersion: 1");
+ expect(before[1]).toContain("HookDefinition");
+ expect((await ws.cli(["hooks", "check", example])).code).toBe(0);
+ expect((await ws.cli(["hooks", "init", dir])).code).toBe(1);
+ expect([readFileSync(example, "utf8"), readFileSync(types, "utf8")]).toEqual(before);
+ }, 30000);
+
+ for (const filename of ["example-hook.ts", "claudish-hooks.d.ts"]) {
+ test(`L-20 init refuses when only ${filename} exists and preserves its bytes`, async () => {
+ const ws = workspace();
+ const dir = join(ws.layout.tmp, "existing-hooks");
+ mkdirSync(dir, { recursive: true });
+ const file = join(dir, filename);
+ writeFileSync(file, "DO-NOT-OVERWRITE\n");
+ expect((await ws.cli(["hooks", "init", dir])).code).toBe(1);
+ expect(readFileSync(file, "utf8")).toBe("DO-NOT-OVERWRITE\n");
+ }, 20000);
+ }
+
+ test("L-21 telemetry requires explicit new consent and preserves old block on save", async () => {
+ const ws = workspace();
+ const behavior = { telemetry: { enabled: true } };
+ ws.save({ behavior, hooks: { modules: [], severity: { "*": "off" } } });
+ const before = readFileSync(ws.configFile, "utf8");
+ expect((await ws.cli(["hooks", "telemetry"])).code).toBe(0);
+ expect(readFileSync(ws.configFile, "utf8")).toBe(before);
+ expect((await ws.cli(["hooks", "telemetry", "--enable"])).code).toBe(0);
+ const enabled = JSON.parse(readFileSync(ws.configFile, "utf8"));
+ expect({
+ consent: enabled.hooks.telemetry.enabled,
+ old: enabled.behavior,
+ severity: enabled.hooks.severity,
+ }).toEqual({ consent: true, old: behavior, severity: { "*": "off" } });
+ expect((await ws.cli(["hooks", "telemetry", "--disable"])).code).toBe(0);
+ expect(JSON.parse(readFileSync(ws.configFile, "utf8")).hooks.telemetry.enabled).toBe(false);
+ }, 30000);
+
+ test("L-22 project hooks are ignored and reported without importing repository code", async () => {
+ const ws = workspace();
+ const marker = join(ws.layout.tmp, "project-hook-executed");
+ const mod = ws.module(
+ "project.ts",
+ `import {writeFileSync} from "node:fs";writeFileSync(${JSON.stringify(marker)}, "BAD");${hook("request(){}")}`
+ );
+ writeFileSync(join(ws.layout.home, ".claudish", "config.json"), JSON.stringify({ hooks: {} }));
+ const project = join(ws.layout.cwd, ".claudish.json");
+ writeFileSync(project, JSON.stringify({ hooks: { modules: [mod] } }));
+ const p = ws.spawn(["hooks", "list", "--json"]);
+ expect(await p.finish()).toBe(0);
+ expect(p.stderr).toContain(
+ `[claudish] hooks in ${project} ignored: hooks are read from the global config only`
+ );
+ expect((JSON.parse(p.stdout) as Listed).hooks.filter((h) => h.id.startsWith("hook:"))).toEqual(
+ []
+ );
+ expect(existsSync(marker)).toBe(false);
+ }, 20000);
+
+ test("L-23 cwd .env cannot select the hooks config, while explicit --config can", async () => {
+ const ws = workspace();
+ const mod = ws.module("repo.ts", hook("request(){}"));
+ ws.save({ hooks: { modules: [mod] } });
+ writeFileSync(join(ws.layout.home, ".claudish", "config.json"), JSON.stringify({ hooks: {} }));
+ writeFileSync(join(ws.layout.cwd, ".env"), `CLAUDISH_CONFIG=${ws.configFile}\n`);
+ // L-23: start Bun with --no-env-file, as the launcher does, so claudish's own .env handling is
+ // under test rather than Bun's autoload.
+ const p = ws.spawn(["hooks", "list", "--json"]);
+ expect(await p.finish()).toBe(0);
+ expect(p.stderr).toContain(
+ "[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."
+ );
+ expect((JSON.parse(p.stdout) as Listed).hooks.filter((h) => h.id.startsWith("hook:"))).toEqual(
+ []
+ );
+ expect((await list(ws)).hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual(
+ ["hook:repo/test"]
+ );
+ }, 30000);
+
+ test("L-24 top-level hook output cannot enter CLI JSON stdout", async () => {
+ const ws = workspace();
+ const mod = ws.module(
+ "chatty.ts",
+ `console.log("IMPORT-CHATTER");process.stdout.write("IMPORT-WRITE\\n");${hook("request(){}")}`
+ );
+ ws.save({ hooks: { modules: [mod] } });
+ const result = await list(ws);
+ expect(result.hooks.filter((h) => h.id.startsWith("hook:")).map((h) => h.id)).toEqual([
+ "hook:chatty/test",
+ ]);
+ }, 20000);
+});
diff --git a/packages/cli/src/hooks/blind/output-isolation.blind.test.ts b/packages/cli/src/hooks/blind/output-isolation.blind.test.ts
new file mode 100644
index 00000000..37362ab1
--- /dev/null
+++ b/packages/cli/src/hooks/blind/output-isolation.blind.test.ts
@@ -0,0 +1,220 @@
+import { describe, expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+import {
+ OUTPUT_CAPTURE,
+ Workspace,
+ hook,
+ rpc,
+ rpcLines,
+ startProxy,
+ textOf,
+ until,
+} from "./support.ts";
+
+const escapeModule = `import {writeSync} from "node:fs";
+function write(prefix){
+ console.log(prefix+"-A");
+ process.stdout.write(prefix+"-B\\n");
+ writeSync(1,prefix+"-C\\n");
+ void Bun.write(Bun.stdout,prefix+"-D\\n");
+}
+process.stdin.on("data",()=>write("LEAK"));
+process.on("SIGUSR2",()=>write("LEAK"));
+setTimeout(()=>write("SCOPED"),20);
+export default {apiVersion:1,id:"escape",on:{sessionStart(){}}};`;
+
+describe("FR-7 / FR-8 / FR-9 protocol output isolation (§4.2, §4.10, §11.5)", () => {
+ test("O-1 import, handler and inherited timer output reach debug, never the child screen", async () => {
+ const code = `console.log("IMPORT-OUTPUT");
+ ${hook('request(ctx){console.log("CALL-LOG");console.info("CALL-INFO");console.debug("CALL-DEBUG");console.warn("CALL-WARN");console.error("CALL-ERROR");process.stdout.write("CALL-STDOUT\\n");process.stderr.write("CALL-STDERR\\n");ctx.log("CTX-LOG");setTimeout(()=>console.log("TIMER-OUTPUT"),20);return []}')} `;
+ const f = await startProxy({ modules: [{ name: "chatty.ts", code }] });
+ try {
+ expect(textOf(await f.read())).toBe("original");
+ const markers = [
+ "IMPORT-OUTPUT",
+ "CALL-LOG",
+ "CALL-INFO",
+ "CALL-DEBUG",
+ "CALL-WARN",
+ "CALL-ERROR",
+ "CALL-STDOUT",
+ "CALL-STDERR",
+ "CTX-LOG",
+ "TIMER-OUTPUT",
+ ];
+ await until(
+ () => markers.every((marker) => f.ws.debug().includes(marker)),
+ "all captured hook output"
+ );
+ const debug = f.ws.debug();
+ for (const marker of markers) {
+ expect(f.process.stdout).not.toContain(marker);
+ expect(f.process.stderr).not.toContain(marker);
+ expect(debug).toContain(marker);
+ }
+ expect(debug).toMatch(/\[hook hook:chatty\/test\][^\n]*TIMER-OUTPUT/);
+ expect(debug).toMatch(/\[hook hook:chatty\/test\][^\n]*CTX-LOG/);
+ } finally {
+ await f.close();
+ }
+ }, 20000);
+ test("X-9 stdin/signal/timer escape routes stay off MCP stdout while four requests answer", async () => {
+ const ws = new Workspace();
+ try {
+ const mod = ws.module("escape.ts", escapeModule);
+ ws.save({ hooks: { modules: [mod] } });
+ const p = ws.spawn(["--config", ws.configFile, "--mcp", "--debug-claudish"]);
+ rpc(p, 1, "initialize", {
+ protocolVersion: "2024-11-05",
+ capabilities: {},
+ clientInfo: { name: "blind-hook-test", version: "1" },
+ });
+ await until(
+ () => p.stdout.includes('"id":1') || p.stdout.includes('"id": 1'),
+ "MCP initialization response"
+ );
+ p.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}\n`);
+ rpc(p, 2, "tools/list", {});
+ rpc(p, 3, "ping", {});
+ await until(() => ws.debug().includes("SCOPED-A"), "import-timer output in debug log");
+ expect(p.child.kill("SIGUSR2")).toBe(true);
+ rpc(p, 4, "tools/list", {});
+ await until(() => {
+ try {
+ return [1, 2, 3, 4].every((id) => rpcLines(p.stdout).some((row) => row.id === id));
+ } catch {
+ return false;
+ }
+ }, "all four MCP responses");
+ await until(
+ () =>
+ ["LEAK-C", "LEAK-D", "SCOPED-C", "SCOPED-D"].every((marker) => p.stderr.includes(marker)),
+ "descriptor writes on stderr"
+ );
+ await until(
+ () =>
+ ws.debug().includes("LEAK-A") &&
+ ws.debug().includes("LEAK-B") &&
+ ws.debug().includes("SCOPED-B"),
+ "captured scoped and unscoped debug writes"
+ );
+
+ const lines = rpcLines(p.stdout);
+ expect(lines.length).toBeGreaterThanOrEqual(4);
+ for (const line of lines) expect(line.jsonrpc).toBe("2.0");
+ for (const id of [1, 2, 3, 4]) {
+ const answer = lines.filter((row) => row.id === id);
+ expect(answer).toHaveLength(1);
+ expect(answer[0]).toHaveProperty("result");
+ expect(answer[0]).not.toHaveProperty("error");
+ }
+ expect(p.stdout).not.toMatch(/LEAK|SCOPED/);
+ const debug = ws.debug();
+ expect(debug).toMatch(/\[stdout\][^\n]*LEAK-A/);
+ expect(debug).toMatch(/\[stdout\][^\n]*LEAK-B/);
+ expect(debug).toMatch(/\[hook [^\]\n]*escape[^\]\n]*\][^\n]*SCOPED-A/);
+ expect(debug).toMatch(/\[hook [^\]\n]*escape[^\]\n]*\][^\n]*SCOPED-B/);
+ } finally {
+ await ws.close();
+ }
+ }, 30000);
+
+ test("X-9 positive control: bare Bun import really emits all four LEAK routes to stdout", async () => {
+ const ws = new Workspace();
+ try {
+ const mod = ws.module("escape.ts", escapeModule);
+ const entry = ws.file(
+ "bare.ts",
+ `await import(${JSON.stringify(mod)});process.stderr.write("READY\\n");setTimeout(()=>process.exit(0),2000);`
+ );
+ const p = ws.track([process.execPath, "--no-env-file", entry]);
+ await until(() => p.stderr.includes("READY"), "bare module registration");
+ p.write("trigger\n");
+ await until(
+ () => ["LEAK-A", "LEAK-B", "LEAK-C", "LEAK-D"].every((marker) => p.stdout.includes(marker)),
+ "all four bare stdout leaks"
+ );
+ for (const marker of ["LEAK-A", "LEAK-B", "LEAK-C", "LEAK-D"])
+ expect(p.stdout).toContain(marker);
+ expect(() => rpcLines(p.stdout)).toThrow();
+ } finally {
+ await ws.close();
+ }
+ }, 15000);
+
+ test("X-11 seam: failed libc binding reports inactive without redirecting stdout", async () => {
+ const ws = new Workspace();
+ try {
+ const entry = ws.file(
+ "inactive.ts",
+ `import {isolateProtocolStdout} from ${JSON.stringify(OUTPUT_CAPTURE)};
+ const out=isolateProtocolStdout({bind(){throw new Error("no ffi")}});
+ process.stdout.write(JSON.stringify({active:out.active,same:out.protocolOut===process.stdout})+"\\n");
+ console.log("STDOUT-UNTOUCHED");`
+ );
+ const p = ws.track([process.execPath, "--no-env-file", entry]);
+ expect(await p.finish()).toBe(0);
+ expect(p.stdout).toBe('{"active":false,"same":true}\nSTDOUT-UNTOUCHED\n');
+ } finally {
+ await ws.close();
+ }
+ }, 15000);
+
+ test("X-12 4 MiB protocol frame survives a reader starting one second late and callback fires", async () => {
+ const ws = new Workspace();
+ const size = 4 * 1024 * 1024;
+ const makeFrame = (n: number) => {
+ const head = '{"jsonrpc":"2.0","id":1,"result":{"text":"';
+ const tail = '"}}\n';
+ return head + "x".repeat(n - Buffer.byteLength(head + tail)) + tail;
+ };
+ const expected = Buffer.from(makeFrame(size));
+ const script = ws.file(
+ "backpressure.ts",
+ `import {isolateProtocolStdout} from ${JSON.stringify(OUTPUT_CAPTURE)};
+ const out=isolateProtocolStdout();
+ if(!out.active){process.stderr.write("ISOLATION-INACTIVE\\n");process.exit(2)}
+ const head='{"jsonrpc":"2.0","id":1,"result":{"text":"';const tail='"}}\\n';
+ const frame=head+"x".repeat(${size}-Buffer.byteLength(head+tail))+tail;
+ out.protocolOut.write(frame,err=>{if(err){process.stderr.write(String(err));process.exit(1)}process.stderr.write("WRITE-CALLBACK\\n");process.exit(0)});`
+ );
+ const child = spawn(process.execPath, ["--no-env-file", script], {
+ cwd: ws.layout.cwd,
+ env: ws.layout.env,
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ let closed = false;
+ let stderr = "";
+ const received: Buffer[] = [];
+ child.stderr.on("data", (chunk: Buffer) => {
+ stderr += chunk.toString();
+ });
+ const exit = new Promise<number>((yes, no) => {
+ child.once("error", no);
+ child.once("close", (code) => {
+ closed = true;
+ yes(code ?? -1);
+ });
+ });
+ const watchdog = setTimeout(() => child.kill("SIGKILL"), 12000);
+ try {
+ child.stdout.pause();
+ await Bun.sleep(1000); // This delay is the X-12 input, not an eventual-consistency guess.
+ child.stdout.on("data", (chunk: Buffer) => received.push(Buffer.from(chunk)));
+ child.stdout.resume();
+ expect(await exit).toBe(0);
+ expect(Buffer.concat(received)).toEqual(expected);
+ expect(stderr.split("\n").filter((line) => line === "WRITE-CALLBACK")).toEqual([
+ "WRITE-CALLBACK",
+ ]);
+ expect(JSON.parse(Buffer.concat(received).toString()).id).toBe(1);
+ } finally {
+ clearTimeout(watchdog);
+ if (!closed) {
+ child.kill("SIGKILL");
+ await exit;
+ }
+ await ws.close();
+ }
+ }, 20000);
+});
diff --git a/packages/cli/src/hooks/blind/public.blind.test.ts b/packages/cli/src/hooks/blind/public.blind.test.ts
new file mode 100644
index 00000000..680e9d72
--- /dev/null
+++ b/packages/cli/src/hooks/blind/public.blind.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import { useBlackboxEnv } from "../../test-helpers/blackbox-env.ts";
+import { HOOK_API_VERSION, act, defineHook } from "../public.ts";
+
+useBlackboxEnv();
+
+describe("FR-6 / FR-7 public author API (§4.3)", () => {
+ const schema = { type: "object" as const, properties: { x: { type: "number" } } };
+ const cases: Array<[string, () => unknown, unknown]> = [
+ [
+ "P-1 injectSystemNote",
+ () => act.injectSystemNote("NOTE"),
+ { type: "injectSystemNote", text: "NOTE" },
+ ],
+ [
+ "P-2 appendUserText",
+ () => act.appendUserText("TAIL"),
+ { type: "appendUserText", text: "TAIL" },
+ ],
+ [
+ "P-3 replaceMessageText",
+ () =>
+ act.replaceMessageText("(a)", "$1!", { regex: true, flags: "gi", roles: ["assistant"] }),
+ {
+ type: "replaceMessageText",
+ find: "(a)",
+ replace: "$1!",
+ regex: true,
+ flags: "gi",
+ roles: ["assistant"],
+ },
+ ],
+ [
+ "P-4 removeMessageText",
+ () => act.removeMessageText("private", { roles: ["user"] }),
+ { type: "removeMessageText", find: "private", roles: ["user"] },
+ ],
+ [
+ "P-5 rewriteToolDescription",
+ () => act.rewriteToolDescription("Read", "TAIL"),
+ { type: "rewriteToolDescription", tool: "Read", append: "TAIL" },
+ ],
+ [
+ "P-6 replaceToolDescription",
+ () => act.replaceToolDescription("Read", "NEW"),
+ { type: "replaceToolDescription", tool: "Read", description: "NEW" },
+ ],
+ [
+ "P-7 replaceToolSchema",
+ () => act.replaceToolSchema("Read", schema),
+ { type: "replaceToolSchema", tool: "Read", inputSchema: schema },
+ ],
+ ["P-8 removeTool", () => act.removeTool("Read"), { type: "removeTool", tool: "Read" }],
+ [
+ "P-9 repairToolArgs",
+ () => act.repairToolArgs({ x: 3 }, "normalise"),
+ { type: "repairToolArgs", args: { x: 3 }, reason: "normalise" },
+ ],
+ ["P-10 appendText", () => act.appendText("END"), { type: "appendText", text: "END" }],
+ ["P-11 prependText", () => act.prependText("START"), { type: "prependText", text: "START" }],
+ [
+ "P-12 replaceText",
+ () => act.replaceText("(x)", "$1!", { regex: true, flags: "i" }),
+ { type: "replaceText", find: "(x)", replace: "$1!", regex: true, flags: "i" },
+ ],
+ [
+ "P-13 removeText",
+ () => act.removeText("x", { regex: true, flags: "g" }),
+ { type: "removeText", find: "x", regex: true, flags: "g" },
+ ],
+ [
+ "P-14 injectUserTurn",
+ () => act.injectUserTurn("HOOK-PING"),
+ { type: "injectUserTurn", text: "HOOK-PING" },
+ ],
+ [
+ "P-15 annotateTurn",
+ () => act.annotateTurn("seen", { n: 1 }),
+ { type: "annotateTurn", key: "seen", value: { n: 1 } },
+ ],
+ ["P-16 warn", () => act.warn("advisory"), { type: "warn", message: "advisory" }],
+ ];
+
+ for (const [name, call, expected] of cases) {
+ test(`${name} returns exactly the closed action data`, () => {
+ expect(call()).toEqual(expected);
+ });
+ }
+
+ test("P-17 defineHook returns the same definition and supports apiVersion 1", () => {
+ const h = {
+ apiVersion: 1 as const,
+ id: "author",
+ on: {
+ request() {
+ return [];
+ },
+ },
+ };
+ expect({ identity: defineHook(h) === h, version: HOOK_API_VERSION }).toEqual({
+ identity: true,
+ version: 1,
+ });
+ });
+});
diff --git a/packages/cli/src/hooks/blind/raw.blind.test.ts b/packages/cli/src/hooks/blind/raw.blind.test.ts
new file mode 100644
index 00000000..edfad9b2
--- /dev/null
+++ b/packages/cli/src/hooks/blind/raw.blind.test.ts
@@ -0,0 +1,352 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stubEvents } from "../../test-helpers/stub-upstream.ts";
+import {
+ events,
+ type ProxyFixture,
+ gatedProvider,
+ readUntil,
+ startProxy,
+ textOf,
+ thinkingOf,
+ until,
+ userRows,
+ waitJournal,
+} from "./support.ts";
+
+const fixtures: ProxyFixture[] = [];
+const servers: Array<{ stop(force?: boolean): void }> = [];
+afterEach(async () => {
+ for (const server of servers.splice(0)) server.stop(true);
+ for (const f of fixtures.splice(0)) await f.close();
+});
+const imports =
+ 'import {writeFileSync,appendFileSync} from "node:fs";import {join} from "node:path";';
+const rawHook = (raw: string, fields = "") =>
+ `export default {apiVersion:1,id:"test",unsafe:true,${fields}raw:{${raw}}};`;
+
+async function fixture(code: string, opts: Partial<Parameters<typeof startProxy>[0]> = {}) {
+ const f = await startProxy({ ...opts, modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ return f;
+}
+function userMessage(f: ProxyFixture) {
+ const body = f.stub.requests[0]!.body as { messages: Array<{ role: string; content: unknown }> };
+ return body.messages.filter((m) => m.role === "user");
+}
+
+function replayProvider(deltas: Array<{ delta: Record<string, unknown>; finish?: string }>) {
+ const frames = deltas.map(
+ (e) =>
+ `data: ${JSON.stringify({ id: "chatcmpl-raw", object: "chat.completion.chunk", created: 0, model: "fake-model", choices: [{ index: 0, delta: e.delta, finish_reason: e.finish ?? null }] })}\n\n`
+ );
+ frames.push("data: [DONE]\n\n");
+ const server = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch(req) {
+ if (req.method !== "POST") return Response.json({ data: [] });
+ return new Response(
+ new ReadableStream<Uint8Array>({
+ start(c) {
+ for (const frame of frames) c.enqueue(new TextEncoder().encode(frame));
+ c.close();
+ },
+ }),
+ { headers: { "content-type": "text/event-stream" } }
+ );
+ },
+ });
+ servers.push(server);
+ return `http://127.0.0.1:${server.port}`;
+}
+function withoutPings(raw: string): string {
+ return raw
+ .split(/\r?\n\r?\n/)
+ .slice(0, -1)
+ .filter((frame) => {
+ // REQ RAW-4 / X-6 / X-7: the stream may end with the OpenAI-style `data: [DONE]` terminator,
+ // which is not JSON; keep it as an ordinary frame.
+ const data = frame
+ .split(/\r?\n/)
+ .find((l) => l.startsWith("data:"))
+ ?.slice(5)
+ .trim();
+ return !data || data === "[DONE]" || JSON.parse(data).type !== "ping";
+ })
+ .map((frame) => `${frame}\n\n`)
+ .join("");
+}
+
+const captureOriginal = `${imports}
+export default {apiVersion:1,id:"capture",unsafe:true,timeoutMs:5000,raw:{async response(ctx){
+ writeFileSync(join(process.env.HOME,"original.sse"),new Uint8Array(await ctx.response.arrayBuffer()));
+}}};`;
+
+describe("FR-6 / FR-8 exact raw parser rows X-1–X-4 (§11.5)", () => {
+ test("X-1 mutated chunk followed by rejecting thenable is discarded without unhandled rejection", async () => {
+ const code = `${imports}
+ process.on("unhandledRejection",()=>writeFileSync(join(process.env.HOME,"unhandled"),"BAD"));
+ ${rawHook('providerChunk(ctx){if(!ctx.delta?.content)return;ctx.delta.content="CORRUPTED";return Promise.reject(new Error("x"))},async providerStreamEnd(){await new Promise(setImmediate);writeFileSync(join(process.env.HOME,"rejection-barrier"),"DONE")}')}`;
+ const f = await fixture(code);
+ expect(textOf(await f.read())).toBe("original");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "error");
+ await until(
+ () => existsSync(join(f.ws.layout.home, "rejection-barrier")),
+ "a child event-loop rejection barrier"
+ );
+ const rows = userRows(f.ws);
+ expect(
+ rows.some((r) => r.decision === "invalid" && (r.detail ?? "").includes("async_return"))
+ ).toBe(true);
+ expect(rows.some((r) => r.decision === "error")).toBe(true);
+ expect(existsSync(join(f.ws.layout.home, "unhandled"))).toBe(false);
+ }, 20000);
+
+ test("X-2 eight mutated thenables yield original text, exactly five invalids and one disable", async () => {
+ const code = `${imports}${rawHook('providerChunk(ctx){if(!ctx.delta?.content)return;appendFileSync(join(process.env.HOME,"calls"),"CALL\\n");ctx.delta.content="CORRUPTED";return Promise.resolve()}')}`;
+ const f = await fixture(code, { script: [{ parts: [{ text: "abcdefgh" }], deltaChars: 1 }] });
+ expect(textOf(await f.read())).toBe("abcdefgh");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "disabled");
+ expect(
+ userRows(f.ws).filter(
+ (r) => r.decision === "invalid" && (r.detail ?? "").includes("async_return")
+ )
+ ).toHaveLength(5);
+ expect(userRows(f.ws).filter((r) => r.decision === "disabled")).toHaveLength(1);
+ expect(readFileSync(join(f.ws.layout.home, "calls"), "utf8").trim().split("\n")).toEqual(
+ Array(5).fill("CALL")
+ );
+ expect(
+ (f.ws.diagnostics(f.process).match(/disabled after 5 consecutive failures/g) ?? []).length
+ ).toBe(1);
+ }, 20000);
+
+ test("X-3 declared async chunk is rejected, but the valid sibling remains registered", async () => {
+ const code = `export default [
+ {apiVersion:1,id:"bad",unsafe:true,raw:{async providerChunk(ctx){ctx.delta.content="CORRUPTED"}}},
+ {apiVersion:1,id:"good",on:{responseRewrite:{handle(){return [{type:"appendText",text:"-GOOD"}]}}}}
+ ];`;
+ const f = await fixture(code);
+ expect(textOf(await f.read())).toBe("original-GOOD");
+ const check = await f.ws.cli([
+ "hooks",
+ "check",
+ f.ws.config.hooks ? (f.ws.config.hooks as { modules: string[] }).modules[0]! : "",
+ ]);
+ expect(check.code).toBe(1);
+ expect(check.stdout + check.stderr).toContain("raw.providerChunk must be synchronous");
+ expect(f.process.stderr).toContain("raw.providerChunk must be synchronous");
+ const result = await f.ws.cli(["hooks", "list", "--json"]);
+ expect(result.code).toBe(0);
+ const listed = JSON.parse(result.stdout) as { hooks: Array<{ id: string }> };
+ expect(listed.hooks.filter((h) => h.id.startsWith("hook:sample/")).map((h) => h.id)).toEqual([
+ "hook:sample/good",
+ ]);
+ }, 30000);
+
+ for (const severity of ["fix", "warn"]) {
+ test(`X-4 ${severity} governs committed delta deletion, text replacement and finish_reason`, async () => {
+ const url = replayProvider([
+ { delta: { role: "assistant", content: "" } },
+ { delta: { reasoning_content: "R" } },
+ { delta: { content: "original" } },
+ { delta: {}, finish: "length" },
+ ]);
+ const code = rawHook(
+ 'providerChunk(ctx){if(ctx.delta){delete ctx.delta.reasoning_content;if("content" in ctx.delta && ctx.delta.content)ctx.delta.content="rewritten"}if(ctx.chunk.choices?.[0]?.finish_reason==="length")ctx.chunk.choices[0].finish_reason="stop"}'
+ );
+ const f = await fixture(code, {
+ endpointUrl: url,
+ hooks: { severity: { "hook:sample/*": severity } },
+ });
+ const raw = await f.read();
+ expect({
+ text: textOf(raw),
+ reasoning: thinkingOf(raw),
+ stop: events(raw).find((e) => e.type === "message_delta")?.delta?.stop_reason,
+ }).toEqual(
+ severity === "fix"
+ ? { text: "rewritten", reasoning: "", stop: "end_turn" }
+ : { text: "original", reasoning: "R", stop: "max_tokens" }
+ );
+ expect(
+ events(raw).filter(
+ (e) => e.type === "content_block_start" && e.content_block?.type === "thinking"
+ )
+ ).toHaveLength(severity === "fix" ? 0 : 1);
+ if (severity === "warn")
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.event === "raw" && r.decision === "warned"
+ );
+ }, 20000);
+ }
+});
+
+describe("FR-6 / FR-8 raw request clone-and-commit and response atomicity", () => {
+ test("RAW-1 emptied provider messages followed by throw leaves transport request unchanged", async () => {
+ const f = await fixture(
+ rawHook(
+ 'providerRequest(ctx){ctx.messages.length=0;ctx.claudeRequest.messages.length=0;throw new Error("RAW-FAIL")}'
+ )
+ );
+ expect(textOf(await f.read())).toBe("original");
+ expect(userMessage(f)).toEqual([{ role: "user", content: "HELLO" }]);
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.event === "raw" && r.decision === "error"
+ );
+ }, 20000);
+
+ test("RAW-2 timeout and post-timeout mutation cannot reach the transport", async () => {
+ const code = `${imports}${rawHook('providerRequest(ctx){ctx.messages.length=0;return new Promise(resolve=>setTimeout(()=>{ctx.messages.push({role:"user",content:"LATE"});writeFileSync(join(process.env.HOME,"late-mutation"),"YES");resolve()},200))}', "timeoutMs:50,")}`;
+ const f = await fixture(code);
+ expect(textOf(await f.read())).toBe("original");
+ await until(
+ () => existsSync(join(f.ws.layout.home, "late-mutation")),
+ "a mutation after the raw timeout"
+ );
+ expect(userMessage(f)).toEqual([{ role: "user", content: "HELLO" }]);
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "timeout");
+ }, 20000);
+
+ for (const severity of ["fix", "warn", "off"]) {
+ test(`RAW-3 ${severity} determines whether raw provider edits reach the transport`, async () => {
+ const f = await fixture(
+ rawHook('providerRequest(ctx){ctx.messages.find(m=>m.role==="user").content="CHANGED"}'),
+ { hooks: { severity: { "hook:sample/*": severity } } }
+ );
+ await f.read();
+ expect(userMessage(f)).toEqual([
+ { role: "user", content: severity === "fix" ? "CHANGED" : "HELLO" },
+ ]);
+ if (severity !== "off")
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.decision === (severity === "warn" ? "warned" : "raw")
+ );
+ expect(f.process.stderr).toContain("UNSAFE (raw middleware)");
+ }, 20000);
+ }
+
+ test("RAW-4 a replacement that errors after a valid first chunk forwards only original bytes", async () => {
+ const replacement = stubEvents("anthropic-sse", { parts: [{ text: "CORRUPTED" }] }).join("");
+ const bad = rawHook(
+ `response(){return new Response(new ReadableStream({start(c){c.enqueue(new TextEncoder().encode(${JSON.stringify(replacement)}));setTimeout(()=>c.error(new Error("replacement failed")),20)}}),{headers:{"content-type":"text/event-stream"}})}`
+ );
+ const f = await startProxy({
+ modules: [
+ { name: "capture.ts", code: captureOriginal },
+ { name: "sample.ts", code: bad },
+ ],
+ });
+ fixtures.push(f);
+ const raw = await f.read();
+ const original = readFileSync(join(f.ws.layout.home, "original.sse"), "utf8");
+ expect(withoutPings(raw)).toBe(withoutPings(original));
+ expect(textOf(raw)).toBe("original");
+ expect(raw).not.toContain("CORRUPTED");
+ expect(events(raw).filter((e) => e.type === "error")).toEqual([]);
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "error");
+ }, 20000);
+
+ for (const readTwo of [false, true]) {
+ test(`X-6/X-7 ${readTwo ? "partly read" : "ignored"} replay plus never-closing replacement times out atomically`, async () => {
+ const firstChunk = stubEvents("anthropic-sse", { parts: [{ text: "CORRUPTED" }] }).join("");
+ const code = `${imports}${rawHook(
+ `async response(ctx){${readTwo ? "const r=ctx.response.body.getReader();await r.read();await r.read();" : ""}
+ return new Response(new ReadableStream({start(c){c.enqueue(new TextEncoder().encode(${JSON.stringify(firstChunk)}))},cancel(){appendFileSync(join(process.env.HOME,"cancelled"),"CANCEL\\n")}}),{headers:{"content-type":"text/event-stream"}})
+ }`,
+ "timeoutMs:1500,"
+ )}`;
+ const f = await startProxy({
+ modules: [
+ { name: "capture.ts", code: captureOriginal },
+ { name: "sample.ts", code },
+ ],
+ script: [{ parts: [{ text: "abcdefgh" }], deltaChars: 1 }],
+ });
+ fixtures.push(f);
+ const raw = await f.read();
+ expect(textOf(raw)).toBe("abcdefgh");
+ expect(withoutPings(raw)).toBe(
+ withoutPings(readFileSync(join(f.ws.layout.home, "original.sse"), "utf8"))
+ );
+ expect(events(raw).some((e) => e.type === "ping")).toBe(true);
+ expect(events(raw).filter((e) => e.type === "error")).toEqual([]);
+ expect(raw).not.toContain("CORRUPTED");
+ await until(
+ () => existsSync(join(f.ws.layout.home, "cancelled")),
+ "replacement cancellation"
+ );
+ expect(readFileSync(join(f.ws.layout.home, "cancelled"), "utf8")).toBe("CANCEL\n");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "timeout");
+ }, 20000);
+ }
+
+ test("X-8 unread replay returning nothing permits incremental original delivery", async () => {
+ const gate = gatedProvider();
+ const f = await fixture(rawHook("response(){return undefined}"), { endpointUrl: gate.url });
+ let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+ try {
+ const response = await f.fetch();
+ expect(response.status).toBe(200);
+ reader = response.body!.getReader();
+ const prefix = await readUntil(reader, (raw) => textOf(raw) === "FIRST");
+ expect(gate.released).toBe(false);
+ gate.release();
+ let tail = "";
+ const decoder = new TextDecoder();
+ for (;;) {
+ const next = await reader.read();
+ if (next.done) break;
+ tail += decoder.decode(next.value, { stream: true });
+ }
+ expect(textOf(prefix + tail + decoder.decode())).toBe("FIRSTSECOND");
+ await until(() => f.ws.debug().includes("mode=none raw=1 tap=0"), "raw-only seam diagnostic");
+ expect(f.ws.debug()).toContain("mode=none raw=1 tap=0");
+ expect(
+ userRows(f.ws).filter((r) => ["error", "invalid", "timeout"].includes(r.decision))
+ ).toEqual([]);
+ } finally {
+ gate.release();
+ await reader?.cancel().catch(() => {});
+ gate.stop();
+ }
+ }, 20000);
+
+ for (const severity of ["fix", "warn"]) {
+ test(`RAW-5/RAW-6 ${severity} raw replacement controls client bytes and responseEnd view`, async () => {
+ const replacement = stubEvents("anthropic-sse", { parts: [{ text: "REPLACEMENT" }] }).join(
+ ""
+ );
+ const code = `${imports}export default {apiVersion:1,id:"test",unsafe:true,raw:{response(){return new Response(${JSON.stringify(replacement)},{headers:{"content-type":"text/event-stream"}})}},on:{responseEnd(ctx){writeFileSync(join(process.env.HOME,"end-text"),ctx.response.text)}}};`;
+ const f = await fixture(code, { hooks: { severity: { "hook:sample/*": severity } } });
+ const raw = await f.read();
+ const expected = severity === "fix" ? "REPLACEMENT" : "original";
+ expect(textOf(raw)).toBe(expected);
+ await until(
+ () => existsSync(join(f.ws.layout.home, "end-text")),
+ "responseEnd after a raw replacement"
+ );
+ expect(readFileSync(join(f.ws.layout.home, "end-text"), "utf8")).toBe(expected);
+ if (severity === "warn")
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.event === "raw" && r.decision === "warned"
+ );
+ }, 20000);
+ }
+
+ test("RAW-7 a thrown raw response handler fails open with original text", async () => {
+ const f = await fixture(rawHook('response(){throw new Error("RAW-RESPONSE-FAIL")}'));
+ const raw = await f.read();
+ expect(textOf(raw)).toBe("original");
+ expect(events(raw).filter((e) => e.type === "error")).toEqual([]);
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "error");
+ }, 20000);
+});
diff --git a/packages/cli/src/hooks/blind/request-actions.blind.test.ts b/packages/cli/src/hooks/blind/request-actions.blind.test.ts
new file mode 100644
index 00000000..0ca94ac3
--- /dev/null
+++ b/packages/cli/src/hooks/blind/request-actions.blind.test.ts
@@ -0,0 +1,524 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+ type ProxyFixture,
+ hook,
+ startProxy,
+ textOf,
+ until,
+ userRows,
+ waitJournal,
+} from "./support.ts";
+
+const fixtures: ProxyFixture[] = [];
+afterEach(async () => {
+ for (const f of fixtures.splice(0)) await f.close();
+});
+
+const snapshotModule = `import {writeFileSync} from "node:fs";import {join} from "node:path";
+export default {apiVersion:1,id:"snapshot",unsafe:true,raw:{providerRequest(ctx){
+ writeFileSync(join(process.env.HOME,"request-snapshot.json"),JSON.stringify(ctx.claudeRequest));
+}}};`;
+const disabledBuiltins = { "plan-mode/*": "off", "session-context/*": "off" };
+
+async function setup(actions: unknown[], fields = "", severity: Record<string, string> = {}) {
+ const f = await startProxy({
+ modules: [
+ { name: "sample.ts", code: hook(`request(){return ${JSON.stringify(actions)}}`, fields) },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: { ...disabledBuiltins, ...severity } },
+ });
+ fixtures.push(f);
+ return f;
+}
+function snapshot(f: ProxyFixture): { system?: unknown; messages: unknown; tools?: unknown } {
+ return JSON.parse(readFileSync(join(f.ws.layout.home, "request-snapshot.json"), "utf8"));
+}
+const readTool = {
+ name: "Read",
+ description: "reads files",
+ input_schema: { type: "object", properties: { file_path: { type: "string" } } },
+};
+const writeTool = {
+ name: "Write",
+ description: "writes files",
+ input_schema: { type: "object", properties: { file_path: { type: "string" } } },
+};
+
+describe("FR-2 / FR-6 request actions through config and real provider path (§4.4–4.6)", () => {
+ test("R-1 injectSystemNote sets an absent system prompt", async () => {
+ const f = await setup([{ type: "injectSystemNote", text: "SYSTEM-NOTE" }]);
+ expect(textOf(await f.read())).toBe("original");
+ expect(snapshot(f).system).toBe("SYSTEM-NOTE");
+ }, 20000);
+
+ test("R-2 identical system notes become one new paragraph", async () => {
+ const f = await setup([
+ { type: "injectSystemNote", text: "NOTE" },
+ { type: "injectSystemNote", text: "NOTE" },
+ ]);
+ await f.read({ system: "BASE" });
+ expect(snapshot(f).system).toBe("BASE\n\nNOTE");
+ }, 20000);
+
+ test("R-2 array system retains existing blocks and appends one note block", async () => {
+ const f = await setup([{ type: "injectSystemNote", text: "NOTE" }]);
+ await f.read({ system: [{ type: "text", text: "BASE" }] });
+ // R-2: asserted on what the provider received — the existing system content is kept and the
+ // note appears once, after it. The raw claudeRequest shape on a converting route is not fixed
+ // by the contract.
+ const sys = (
+ f.stub.requests[0]!.body as { messages: Array<{ role: string; content: unknown }> }
+ ).messages
+ .filter((m) => m.role === "system")
+ .map((m) => (typeof m.content === "string" ? m.content : JSON.stringify(m.content)))
+ .join("\n");
+ expect(sys).toContain("BASE");
+ expect(sys.split("NOTE").length - 1).toBe(1);
+ expect(sys.indexOf("NOTE")).toBeGreaterThan(sys.indexOf("BASE"));
+ }, 20000);
+
+ test("R-3 appendUserText normalizes string content and deduplicates text", async () => {
+ const f = await setup([
+ { type: "appendUserText", text: "TAIL" },
+ { type: "appendUserText", text: "TAIL" },
+ ]);
+ await f.read({ messages: [{ role: "user", content: "BASE" }] });
+ expect(snapshot(f).messages).toEqual([
+ {
+ role: "user",
+ content: [
+ { type: "text", text: "BASE" },
+ { type: "text", text: "TAIL" },
+ ],
+ },
+ ]);
+ }, 20000);
+
+ test("R-4 appendUserText lands after the final user's tool_result without editing it", async () => {
+ const f = await setup([{ type: "appendUserText", text: "TAIL" }]);
+ const messages = [
+ { role: "user", content: "HEAD" },
+ {
+ role: "assistant",
+ content: [{ type: "tool_use", id: "t1", name: "Read", input: { file_path: "notes" } }],
+ },
+ { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "UNCHANGED" }] },
+ ];
+ await f.read({ tools: [readTool], messages });
+ expect(snapshot(f).messages).toEqual([
+ messages[0],
+ messages[1],
+ {
+ role: "user",
+ content: [...(messages[2]!.content as object[]), { type: "text", text: "TAIL" }],
+ },
+ ]);
+ }, 20000);
+
+ test("R-5 literal replacement inserts $500 verbatim, defaults to user, and replaces all matches", async () => {
+ const f = await setup([{ type: "replaceMessageText", find: "PRICE", replace: "$500" }]);
+ await f.read({
+ messages: [
+ { role: "user", content: "PRICE PRICE" },
+ { role: "assistant", content: "PRICE" },
+ { role: "user", content: "PRICE" },
+ ],
+ });
+ expect(snapshot(f).messages).toEqual([
+ { role: "user", content: "$500 $500" },
+ { role: "assistant", content: "PRICE" },
+ { role: "user", content: "$500" },
+ ]);
+ }, 20000);
+
+ test("R-6 regex replacement expands captures and explicit assistant role", async () => {
+ const f = await setup([
+ {
+ type: "replaceMessageText",
+ find: "item:(\\d+)",
+ replace: "<$1>",
+ regex: true,
+ roles: ["assistant"],
+ },
+ ]);
+ await f.read({
+ messages: [
+ { role: "user", content: "item:3" },
+ { role: "assistant", content: "item:5 item:6" },
+ { role: "user", content: "NEXT" },
+ ],
+ });
+ expect(snapshot(f).messages).toEqual([
+ { role: "user", content: "item:3" },
+ { role: "assistant", content: "<5> <6>" },
+ { role: "user", content: "NEXT" },
+ ]);
+ }, 20000);
+
+ test("R-7 text edits preserve tool, thinking and media blocks byte-for-byte", async () => {
+ const f = await setup([
+ {
+ type: "replaceMessageText",
+ find: "SECRET",
+ replace: "EDITED",
+ roles: ["user", "assistant"],
+ },
+ ]);
+ const protectedAssistant = [
+ { type: "thinking", thinking: "SECRET", signature: "c2ln" },
+ { type: "tool_use", id: "t1", name: "Read", input: { file_path: "SECRET" } },
+ ];
+ const protectedUser = [
+ { type: "tool_result", tool_use_id: "t1", content: "SECRET" },
+ { type: "image", source: { type: "base64", media_type: "image/png", data: "U0VDUkVU" } },
+ ];
+ await f.read({
+ tools: [readTool],
+ messages: [
+ { role: "user", content: "SECRET" },
+ { role: "assistant", content: [{ type: "text", text: "SECRET" }, ...protectedAssistant] },
+ { role: "user", content: [...protectedUser, { type: "text", text: "SECRET" }] },
+ ],
+ });
+ expect(snapshot(f).messages).toEqual([
+ { role: "user", content: "EDITED" },
+ { role: "assistant", content: [{ type: "text", text: "EDITED" }, ...protectedAssistant] },
+ { role: "user", content: [...protectedUser, { type: "text", text: "EDITED" }] },
+ ]);
+ }, 20000);
+
+ test("R-8 removal that empties a whole message is reverted and journaled invalid", async () => {
+ const f = await setup([{ type: "removeMessageText", find: "ONLY" }]);
+ await f.read({ messages: [{ role: "user", content: "ONLY" }] });
+ expect(snapshot(f).messages).toEqual([{ role: "user", content: "ONLY" }]);
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.decision === "invalid" &&
+ (r.detail ?? "").includes("empty_message")
+ );
+ }, 20000);
+
+ // REQ R-9 (Revision 2.2, hook chain). §4.4.1 rule 3: "its non-`warn` actions are applied in the
+ // order the hook returned them, each over the working state every earlier action produced".
+ // §4.6 replaceToolSchema: "Several apply in chain order, each replacing the current schema".
+ // §4.6 tool-description sequence: "Every description action on a tool applies, in chain order,
+ // each over the description the earlier ones produced: an append extends it, a replace replaces
+ // it". §4.8: `superseded` "occurs only for a duplicate note or appended user text, an action on a
+ // tool an earlier step removed, a second removal, and a description action on a tool a later step
+ // removed" — none of which applies here, so every action is `matched`.
+ test("R-9 schema and description actions apply in order, each over the last, on both tool copies", async () => {
+ const firstSchema = {
+ type: "object",
+ properties: { count: { type: "integer" } },
+ required: ["count"],
+ };
+ const secondSchema = {
+ type: "object",
+ properties: { path: { type: "string" } },
+ required: ["path"],
+ };
+ const f = await setup([
+ { type: "replaceToolSchema", tool: "Read", inputSchema: firstSchema },
+ { type: "replaceToolSchema", tool: "Read", inputSchema: secondSchema },
+ { type: "replaceToolDescription", tool: "Read", description: "FIRST" },
+ { type: "rewriteToolDescription", tool: "Read", append: "-APPENDED" },
+ ]);
+ await f.read({ tools: [readTool] });
+ expect(snapshot(f).tools).toEqual([
+ { ...readTool, input_schema: secondSchema, description: "FIRST-APPENDED" },
+ ]);
+ const body = f.stub.requests[0]!.body as {
+ tools: Array<{ function: { description: string; parameters: unknown } }>;
+ };
+ expect(body.tools[0]!.function).toMatchObject({
+ description: "FIRST-APPENDED",
+ parameters: secondSchema,
+ });
+ const matched = () =>
+ userRows(f.ws)
+ .filter((r) => r.decision === "matched")
+ .map((r) => r.action)
+ .sort();
+ await until(() => matched().length >= 4, "four matched journal rows for R-9");
+ expect(matched()).toEqual([
+ "replaceToolDescription",
+ "replaceToolSchema",
+ "replaceToolSchema",
+ "rewriteToolDescription",
+ ]);
+ expect(userRows(f.ws).filter((r) => r.decision === "superseded")).toEqual([]);
+ }, 20000);
+
+ test("R-10 removeTool is refused for a tool_use in conversation history", async () => {
+ const f = await setup([{ type: "removeTool", tool: "Read" }]);
+ await f.read({
+ tools: [readTool],
+ messages: [
+ { role: "user", content: "READ" },
+ { role: "assistant", content: [{ type: "tool_use", id: "t1", name: "Read", input: {} }] },
+ { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "OK" }] },
+ ],
+ });
+ expect(snapshot(f).tools).toEqual([readTool]);
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.decision === "invalid" &&
+ (r.detail ?? "").includes("tool_in_history")
+ );
+ }, 20000);
+
+ test("R-11 removing an unused tool supersedes later description changes", async () => {
+ const f = await setup([
+ { type: "removeTool", tool: "Write" },
+ { type: "replaceToolDescription", tool: "Write", description: "LATE" },
+ ]);
+ await f.read({ tools: [readTool, writeTool] });
+ expect(snapshot(f).tools).toEqual([readTool]);
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.action === "replaceToolDescription" &&
+ r.decision === "superseded"
+ );
+ }, 20000);
+
+ for (const action of [
+ { type: "appendText", text: "WRONG-EVENT" },
+ { type: "replaceToolDescription", tool: "Missing", description: "NEW" },
+ { type: "replaceToolSchema", tool: "Read", inputSchema: { type: "array" } },
+ { type: "replaceMessageText", find: "HELLO", replace: "WRONG", flags: "g" },
+ { type: "replaceMessageText", find: "[", replace: "WRONG", regex: true },
+ ]) {
+ test(`R-12 invalid ${JSON.stringify(action)} is ignored and attributed in schema-2 journal`, async () => {
+ const f = await setup([action]);
+ expect(textOf(await f.read({ tools: [readTool] }))).toBe("original");
+ expect(snapshot(f).messages).toEqual([{ role: "user", content: "HELLO" }]);
+ expect(snapshot(f).tools).toEqual([readTool]);
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "invalid");
+ expect(userRows(f.ws).filter((r) => r.decision === "invalid")).toContainEqual(
+ expect.objectContaining({
+ schema: 2,
+ hookId: "hook:sample/test",
+ ruleId: "hook:sample/test",
+ event: "request",
+ action: action.type,
+ })
+ );
+ }, 20000);
+ }
+});
+
+describe("FR-6 / FR-8 / FR-9 severity, isolation and ordering", () => {
+ test("R-18 a successful handler resets the consecutive-failure breaker", async () => {
+ const code = `import {appendFileSync} from "node:fs";import {join} from "node:path";
+ let calls=0;${hook('request(){calls++;appendFileSync(join(process.env.HOME,"calls"),String(calls)+"\\n");if(calls===5)return [];throw new Error("FAIL")}')}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ for (let n = 0; n < 9; n++) expect(textOf(await f.read())).toBe("original");
+ expect(userRows(f.ws).filter((r) => r.decision === "disabled")).toEqual([]);
+ for (let n = 0; n < 2; n++) expect(textOf(await f.read())).toBe("original");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "disabled");
+ expect(readFileSync(join(f.ws.layout.home, "calls"), "utf8").trim().split("\n")).toEqual(
+ Array.from({ length: 10 }, (_, n) => String(n + 1))
+ );
+ expect(userRows(f.ws).filter((r) => r.decision === "error")).toHaveLength(9);
+ }, 30000);
+
+ for (const [name, severity, expected] of [
+ [
+ "model scope beats unscoped exact",
+ { "hook:sample/test": "fix", "fake-*:hook:sample/*": "warn" },
+ "",
+ ],
+ [
+ "model-scoped exact beats model-scoped glob",
+ {
+ "hook:sample/test": "off",
+ "fake-*:hook:sample/*": "warn",
+ "fake-model:hook:sample/test": "fix",
+ },
+ "NOTE",
+ ],
+ ] as const) {
+ test(`R-19 ${name} uses the bare routed model`, async () => {
+ const f = await setup([{ type: "injectSystemNote", text: "NOTE" }], "", severity);
+ await f.read();
+ expect(snapshot(f).system ?? "").toBe(expected);
+ if (!expected)
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "warned");
+ }, 20000);
+ }
+
+ test("R-20 frozen request view cannot reorder what reaches the provider", async () => {
+ const f = await startProxy({
+ modules: [
+ { name: "sample.ts", code: hook("request(ctx){ctx.request.messages.reverse()}") },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: disabledBuiltins },
+ });
+ fixtures.push(f);
+ const messages = [
+ { role: "user", content: "FIRST" },
+ { role: "assistant", content: "MIDDLE" },
+ { role: "user", content: "LAST" },
+ ];
+ expect(textOf(await f.read({ messages }))).toBe("original");
+ expect(snapshot(f).messages).toEqual(messages);
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "error");
+ }, 20000);
+ for (const severity of ["off", "warn", "fix"]) {
+ test(`R-13 ${severity} controls invocation, request changes and warn journal`, async () => {
+ const code = `import {appendFileSync} from "node:fs";import {join} from "node:path";
+ ${hook('request(){appendFileSync(join(process.env.HOME,"calls"),"CALL\\n");return [{type:"injectSystemNote",text:"NOTE"}]}')}`;
+ const f = await startProxy({
+ modules: [
+ { name: "sample.ts", code },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: { ...disabledBuiltins, "hook:sample/*": severity } },
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ expect(snapshot(f).system ?? "").toBe(severity === "fix" ? "NOTE" : "");
+ const calls = join(f.ws.layout.home, "calls");
+ expect(existsSync(calls)).toBe(severity !== "off");
+ if (severity === "warn")
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.action === "injectSystemNote" &&
+ r.decision === "warned"
+ );
+ }, 20000);
+ }
+
+ test("R-14 throwing request handler preserves upstream request and client response", async () => {
+ const f = await startProxy({
+ modules: [
+ { name: "sample.ts", code: hook('request(){throw new Error("REQUEST-FAIL")}') },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: disabledBuiltins },
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ expect(snapshot(f).messages).toEqual([{ role: "user", content: "HELLO" }]);
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.event === "request" && r.decision === "error"
+ );
+ }, 20000);
+
+ test("R-15 request timeout aborts signal and discards an action returned afterwards", async () => {
+ const code = `import {writeFileSync} from "node:fs";import {join} from "node:path";
+ ${hook('request(ctx){return new Promise(resolve=>{ctx.signal.addEventListener("abort",()=>{writeFileSync(join(process.env.HOME,"aborted"),"YES");setTimeout(()=>resolve([{type:"injectSystemNote",text:"LATE"}]),30)},{once:true})})}', "timeoutMs:50,")}`;
+ const f = await startProxy({
+ modules: [
+ { name: "sample.ts", code },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: disabledBuiltins },
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ expect(snapshot(f).system ?? "").toBe("");
+ await until(() => existsSync(join(f.ws.layout.home, "aborted")), "aborted timeout signal");
+ expect(readFileSync(join(f.ws.layout.home, "aborted"), "utf8")).toBe("YES");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "timeout");
+ }, 20000);
+
+ test("R-16 five consecutive failures disable the hook and the sixth request still succeeds", async () => {
+ const code = `import {appendFileSync} from "node:fs";import {join} from "node:path";
+ ${hook('request(){appendFileSync(join(process.env.HOME,"calls"),"CALL\\n");throw new Error("FAIL")}')}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ for (let n = 0; n < 6; n++) expect(textOf(await f.read())).toBe("original");
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "disabled");
+ expect(readFileSync(join(f.ws.layout.home, "calls"), "utf8").trim().split("\n")).toEqual(
+ Array(5).fill("CALL")
+ );
+ expect(userRows(f.ws).filter((r) => r.decision === "error")).toHaveLength(5);
+ expect(
+ (f.ws.diagnostics(f.process).match(/disabled after 5 consecutive failures/g) ?? []).length
+ ).toBe(1);
+ }, 30000);
+
+ // REQ R-17 (Revision 2.2, hook chain). §4.4.1: "The applicable hooks of a dispatch run as a
+ // hook chain: one at a time, in effective order (§6)". Rule 2: "Hook N is called only after hook
+ // N−1's step has ended (returned, thrown, rejected, timed out, or been skipped). Its context is
+ // built at that moment, from the dispatch's working state: the event's input plus every action
+ // steps 0…N−1 applied." Rule 5: `ctx.prior` "lists, in order and with their hook ids, the actions
+ // earlier steps of this dispatch applied". hooks-user-guide.md Order: "`order` (`pre`, then
+ // `normal`, then `post`), then built-in hooks before yours, then the order of `hooks.modules`,
+ // then export order." chain-test-targets.md 12: "the `post` hook starts only after the `pre` hook
+ // returns". The post hook is exported first, so only `order` can put pre ahead of it.
+ test("R-17 a post hook starts only after the held pre hook returns, and sees its note", async () => {
+ const code = `import {appendFileSync,existsSync,writeFileSync} from "node:fs";import {join} from "node:path";
+ const home=process.env.HOME;
+ const mark=s=>appendFileSync(join(home,"marks"),s+" "+Date.now()+"\\n");
+ export default [
+ {apiVersion:1,id:"post",order:"post",on:{request(ctx){mark("POST-START");writeFileSync(join(home,"post-view.json"),JSON.stringify({systemText:ctx.request.systemText,prior:ctx.prior}));return [{type:"injectSystemNote",text:"POST"}]}}},
+ {apiVersion:1,id:"pre",order:"pre",timeoutMs:5000,on:{async request(ctx){mark("PRE-START");writeFileSync(join(home,"pre-view.json"),JSON.stringify({prior:ctx.prior}));while(!existsSync(join(home,"release")))await Bun.sleep(5);mark("PRE-RETURN");return [{type:"injectSystemNote",text:"PRE"}]}}}
+ ];`;
+ const f = await startProxy({
+ modules: [
+ { name: "ordered.ts", code },
+ { name: "snapshot.ts", code: snapshotModule },
+ ],
+ hooks: { severity: disabledBuiltins },
+ });
+ fixtures.push(f);
+ const home = f.ws.layout.home;
+ const marksFile = join(home, "marks");
+ const marks = () =>
+ existsSync(marksFile)
+ ? readFileSync(marksFile, "utf8")
+ .trim()
+ .split("\n")
+ .map((line) => {
+ const [name, at] = line.split(" ");
+ return { name: name!, at: Number(at) };
+ })
+ : [];
+ const request = f.read({ system: "BASE" });
+ try {
+ await until(() => marks().some((m) => m.name === "PRE-START"), "the pre hook to start");
+ // Hold pre for a full second (well inside the 5,000 ms budget): post must not start meanwhile.
+ await Bun.sleep(1000);
+ expect(marks().map((m) => m.name)).toEqual(["PRE-START"]);
+ } finally {
+ writeFileSync(join(home, "release"), "GO");
+ }
+ expect(textOf(await request)).toBe("original");
+ const seen = marks();
+ expect(seen.map((m) => m.name)).toEqual(["PRE-START", "PRE-RETURN", "POST-START"]);
+ expect(seen[2]!.at).toBeGreaterThanOrEqual(seen[1]!.at);
+ const pre = JSON.parse(readFileSync(join(home, "pre-view.json"), "utf8")) as {
+ prior: Array<{ hookId: string }>;
+ };
+ expect(pre.prior.filter((p) => p.hookId.startsWith("hook:"))).toEqual([]);
+ const post = JSON.parse(readFileSync(join(home, "post-view.json"), "utf8")) as {
+ systemText: string;
+ prior: Array<{ hookId: string; action: { type: string; text?: string } }>;
+ };
+ expect(post.systemText).toContain("BASE");
+ expect(post.systemText).toContain("PRE");
+ expect(post.prior).toContainEqual(
+ expect.objectContaining({
+ hookId: "hook:ordered/pre",
+ action: expect.objectContaining({ type: "injectSystemNote", text: "PRE" }),
+ })
+ );
+ expect(snapshot(f).system).toBe("BASE\n\nPRE\n\nPOST");
+ }, 30000);
+});
diff --git a/packages/cli/src/hooks/blind/response.blind.test.ts b/packages/cli/src/hooks/blind/response.blind.test.ts
new file mode 100644
index 00000000..9e3d5add
--- /dev/null
+++ b/packages/cli/src/hooks/blind/response.blind.test.ts
@@ -0,0 +1,464 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { StubPart } from "../../test-helpers/stub-upstream.ts";
+import {
+ events,
+ type ProxyFixture,
+ gatedProvider,
+ hook,
+ readUntil,
+ startProxy,
+ textOf,
+ thinkingOf,
+ toolInputs,
+ until,
+ waitJournal,
+} from "./support.ts";
+
+const fixtures: ProxyFixture[] = [];
+afterEach(async () => {
+ for (const f of fixtures.splice(0)) await f.close();
+});
+
+async function rewrite(
+ actions: unknown[],
+ parts: StubPart[] = [{ text: "KEEP REMOVE-ME KEEP" }],
+ fields = ""
+) {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook(`responseRewrite:{handle(){return ${JSON.stringify(actions)}}}`, fields),
+ },
+ ],
+ script: [{ parts }],
+ });
+ fixtures.push(f);
+ return f;
+}
+async function remainder(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<string> {
+ const decoder = new TextDecoder();
+ let raw = "";
+ for (;;) {
+ const next = await reader.read();
+ if (next.done) return raw + decoder.decode();
+ raw += decoder.decode(next.value, { stream: true });
+ }
+}
+
+describe("FR-2 / FR-4 response edits received by a Claude client (§4.4–4.6)", () => {
+ test("S-1 add/remove/replace actions execute sequentially before the client receives text", async () => {
+ const f = await rewrite([
+ { type: "removeText", find: " REMOVE-ME" },
+ { type: "replaceText", find: "KEEP", replace: "SAFE" },
+ { type: "appendText", text: " HOOK-ADDED" },
+ { type: "prependText", text: "START " },
+ ]);
+ const raw = await f.read();
+ expect(textOf(raw)).toBe("START SAFE SAFE HOOK-ADDED");
+ expect(raw).not.toContain("REMOVE-ME");
+ // S-1: the contract (§4.8) assigns no specific decision value to an applied responseRewrite
+ // action, so assert each action was journaled and none was refused, overridden or failed.
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.event === "responseRewrite" &&
+ r.action === "prependText"
+ );
+ const rows = f.ws
+ .journal()
+ .filter((r) => r.hookId === "hook:sample/test" && r.event === "responseRewrite");
+ expect(rows.map((r) => r.action).sort()).toEqual([
+ "appendText",
+ "prependText",
+ "removeText",
+ "replaceText",
+ ]);
+ expect(
+ rows.filter((r) =>
+ ["warned", "invalid", "error", "timeout", "superseded", "disabled", "dropped"].includes(
+ r.decision
+ )
+ )
+ ).toEqual([]);
+ }, 20000);
+
+ test("S-2 append and prepend wrap existing text without changing reasoning", async () => {
+ const f = await rewrite(
+ [
+ { type: "prependText", text: "<" },
+ { type: "appendText", text: ">" },
+ ],
+ [{ thinking: "PRIVATE" }, { text: "ANSWER" }]
+ );
+ const raw = await f.read();
+ expect({ text: textOf(raw), reasoning: thinkingOf(raw) }).toEqual({
+ text: "<ANSWER>",
+ reasoning: "PRIVATE",
+ });
+ }, 20000);
+
+ for (const [name, action, original, expected] of [
+ [
+ "literal dollar value",
+ { type: "replaceText", find: "PRICE", replace: "$500" },
+ "PRICE PRICE",
+ "$500 $500",
+ ],
+ [
+ "regex capture expansion",
+ { type: "replaceText", find: "item:(\\d+)", replace: "<$1>", regex: true },
+ "item:1 item:2",
+ "<1> <2>",
+ ],
+ [
+ "regex removal",
+ { type: "removeText", find: "\\s*REMOVE-ME", regex: true },
+ "KEEP REMOVE-ME KEEP",
+ "KEEP KEEP",
+ ],
+ ] as const) {
+ test(`S-3 ${name} produces exact client text`, async () => {
+ const f = await rewrite([action], [{ text: original }]);
+ expect(textOf(await f.read())).toBe(expected);
+ }, 20000);
+ }
+
+ test("S-4 dropping empty text reindexes the following tool to zero", async () => {
+ const f = await rewrite(
+ [{ type: "removeText", find: "ERASE" }],
+ [{ text: "ERASE" }, { toolCall: { name: "Read", args: { file_path: "notes" } } }]
+ );
+ const raw = await f.read();
+ expect(
+ events(raw)
+ .filter((e) => e.type === "content_block_start")
+ .map((e) => ({ index: e.index, type: e.content_block?.type }))
+ ).toEqual([{ index: 0, type: "tool_use" }]);
+ expect(toolInputs(raw)).toEqual([{ name: "Read", input: { file_path: "notes" } }]);
+ }, 20000);
+
+ for (const action of ["appendText", "prependText"]) {
+ test(`S-5/S-6 ${action} in a thinking/tool-only response inserts text at index 1`, async () => {
+ const f = await rewrite(
+ [{ type: action, text: "HOOK-ADDED" }],
+ [
+ { thinking: "THINK" },
+ { toolCall: { name: "Read", args: { file_path: "a" } } },
+ { toolCall: { name: "Write", args: { file_path: "b" } } },
+ ]
+ );
+ const raw = await f.read();
+ expect(
+ events(raw)
+ .filter((e) => e.type === "content_block_start")
+ .map((e) => ({ index: e.index, type: e.content_block?.type }))
+ ).toEqual([
+ { index: 0, type: "thinking" },
+ { index: 1, type: "text" },
+ { index: 2, type: "tool_use" },
+ { index: 3, type: "tool_use" },
+ ]);
+ expect({ text: textOf(raw), reasoning: thinkingOf(raw), tools: toolInputs(raw) }).toEqual({
+ text: "HOOK-ADDED",
+ reasoning: "THINK",
+ tools: [
+ { name: "Read", input: { file_path: "a" } },
+ { name: "Write", input: { file_path: "b" } },
+ ],
+ });
+ }, 20000);
+ }
+
+ test("S-6 append to thinking-only inserts text after the leading thinking block", async () => {
+ const f = await rewrite([{ type: "appendText", text: "ANSWER" }], [{ thinking: "THINK" }]);
+ const raw = await f.read();
+ expect(
+ events(raw)
+ .filter((e) => e.type === "content_block_start")
+ .map((e) => ({ index: e.index, type: e.content_block?.type }))
+ ).toEqual([
+ { index: 0, type: "thinking" },
+ { index: 1, type: "text" },
+ ]);
+ expect(textOf(raw)).toBe("ANSWER");
+ }, 20000);
+
+ test("S-7 complete named tool arguments are repaired; other tool and text are unchanged", async () => {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook(
+ 'toolCall:{tools:["Read"],handle(ctx){if(ctx.tool.args.file_path!=="wrong")throw new Error("incomplete args");return [{type:"repairToolArgs",args:{file_path:"correct"},reason:"normalise"}]}}'
+ ),
+ },
+ ],
+ script: [
+ {
+ parts: [
+ { text: "UNCHANGED" },
+ { toolCall: { name: "Read", args: { file_path: "wrong" } } },
+ { toolCall: { name: "Write", args: { file_path: "other", content: "UNTOUCHED" } } },
+ ],
+ deltaChars: 2,
+ },
+ ],
+ });
+ fixtures.push(f);
+ const raw = await f.read();
+ expect({ text: textOf(raw), tools: toolInputs(raw) }).toEqual({
+ text: "UNCHANGED",
+ tools: [
+ { name: "Read", input: { file_path: "correct" } },
+ { name: "Write", input: { file_path: "other", content: "UNTOUCHED" } },
+ ],
+ });
+ await waitJournal(f.ws, (r) => r.hookId === "hook:sample/test" && r.decision === "repaired");
+ const rows = f.ws
+ .journal()
+ .filter((r) => r.hookId === "hook:sample/test" && r.action === "repairToolArgs");
+ expect(rows.map((r) => ({ tool: r.toolName, keys: r.argKeys }))).toEqual([
+ { tool: "Read", keys: ["file_path"] },
+ ]);
+ expect(JSON.stringify(rows)).not.toContain("correct");
+ }, 20000);
+
+ for (const condition of ["unarmed", "observe", "warn"]) {
+ test(`S-8 ${condition} tool hook never commits repairToolArgs`, async () => {
+ const opts =
+ condition === "unarmed"
+ ? "armed(){return false},"
+ : condition === "observe"
+ ? "observe:true,"
+ : "";
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook(
+ `toolCall:{tools:["Read"],${opts}handle(){return [{type:"repairToolArgs",args:{file_path:"WRONG"},reason:"must not commit"}]}}`
+ ),
+ },
+ ],
+ hooks: condition === "warn" ? { severity: { "hook:sample/*": "warn" } } : {},
+ script: [{ parts: [{ toolCall: { name: "Read", args: { file_path: "original" } } }] }],
+ });
+ fixtures.push(f);
+ expect(toolInputs(await f.read())).toEqual([
+ { name: "Read", input: { file_path: "original" } },
+ ]);
+ }, 20000);
+ }
+
+ test("S-9 responseEnd receives the final rewritten normalized response", async () => {
+ const code = `import {writeFileSync} from "node:fs";import {join} from "node:path";
+ ${hook('responseRewrite:{handle(){return [{type:"appendText",text:"-EDIT"}]}},responseEnd(ctx){writeFileSync(join(process.env.HOME,"end.json"),JSON.stringify(ctx.response))}')}`;
+ const f = await startProxy({
+ modules: [{ name: "sample.ts", code }],
+ script: [{ parts: [{ thinking: "THINK" }, { text: "ANSWER" }] }],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("ANSWER-EDIT");
+ const file = join(f.ws.layout.home, "end.json");
+ await until(() => existsSync(file), "responseEnd normalized output");
+ const view = JSON.parse(readFileSync(file, "utf8"));
+ expect({
+ text: view.text,
+ reasoning: view.reasoning,
+ toolNames: view.toolNames,
+ stopReason: view.stopReason,
+ }).toEqual({ text: "ANSWER-EDIT", reasoning: "THINK", toolNames: [], stopReason: "end_turn" });
+ }, 20000);
+
+ for (const condition of ["throw", "timeout"]) {
+ test(`S-10/S-11 ${condition} during rewrite forwards original text and another hook still applies`, async () => {
+ const bad =
+ condition === "throw"
+ ? 'handle(){throw new Error("REWRITE-FAIL")}'
+ : "handle(){return new Promise(()=>{})}";
+ const f = await startProxy({
+ modules: [
+ { name: "bad.ts", code: hook(`responseRewrite:{${bad}}`, "timeoutMs:50,") },
+ {
+ name: "good.ts",
+ code: hook('responseRewrite:{handle(){return [{type:"appendText",text:"-GOOD"}]}}'),
+ },
+ ],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original-GOOD");
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:bad/test" &&
+ r.decision === (condition === "throw" ? "error" : "timeout")
+ );
+ }, 20000);
+ }
+
+ test("S-12 async responseEnd cannot delay message_stop reaching the client", async () => {
+ const code = `import {writeFileSync,existsSync} from "node:fs";import {join} from "node:path";
+ ${hook('async responseEnd(){writeFileSync(join(process.env.HOME,"end-started"),"YES");while(!existsSync(join(process.env.HOME,"release-end")))await Bun.sleep(10);writeFileSync(join(process.env.HOME,"end-finished"),"YES")}', "timeoutMs:5000,")}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ try {
+ expect(textOf(await f.read())).toBe("original");
+ await until(() => existsSync(join(f.ws.layout.home, "end-started")), "responseEnd start");
+ expect(existsSync(join(f.ws.layout.home, "end-finished"))).toBe(false);
+ } finally {
+ writeFileSync(join(f.ws.layout.home, "release-end"), "GO");
+ }
+ await until(() => existsSync(join(f.ws.layout.home, "end-finished")), "released responseEnd");
+ }, 20000);
+});
+
+describe("FR-4 streaming untouched unless a fix hook claims it", () => {
+ const unheld = [
+ ["no modules", undefined, {}],
+ [
+ "claims false",
+ hook(
+ 'responseRewrite:{claims(){return false},handle(){return [{type:"appendText",text:"BAD"}]}}'
+ ),
+ {},
+ ],
+ [
+ "claims throws",
+ hook(
+ 'responseRewrite:{claims(){throw new Error("CLAIM-FAIL")},handle(){return [{type:"appendText",text:"BAD"}]}}'
+ ),
+ {},
+ ],
+ [
+ "warn severity",
+ hook('responseRewrite:{handle(){return [{type:"appendText",text:"BAD"}]}}'),
+ { severity: { "hook:sample/*": "warn" } },
+ ],
+ ] as const;
+ for (const [condition, code, hooks] of unheld) {
+ test(`S-13 ${condition} delivers FIRST while the upstream is still held open`, async () => {
+ const gate = gatedProvider();
+ const f = await startProxy({
+ endpointUrl: gate.url,
+ modules: code ? [{ name: "sample.ts", code }] : [],
+ hooks,
+ });
+ fixtures.push(f);
+ let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+ try {
+ const res = await f.fetch();
+ expect(res.status).toBe(200);
+ reader = res.body!.getReader();
+ const prefix = await readUntil(reader, (raw) => textOf(raw) === "FIRST");
+ expect(gate.released).toBe(false);
+ expect(textOf(prefix)).toBe("FIRST");
+ gate.release();
+ const raw = prefix + (await remainder(reader));
+ expect(textOf(raw)).toBe("FIRSTSECOND");
+ if (condition === "no modules") {
+ await until(
+ () => f.ws.debug().includes("mode=none raw=0 tap=0"),
+ "identity seam diagnostic"
+ );
+ expect(f.ws.debug()).toContain("mode=none raw=0 tap=0");
+ }
+ if (condition === "warn severity")
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.decision === "warned"
+ );
+ } finally {
+ gate.release();
+ await reader?.cancel().catch(() => {});
+ gate.stop();
+ }
+ }, 20000);
+ }
+
+ test("S-14 claimed buffer forwards pings but no text before the provider completes", async () => {
+ const gate = gatedProvider();
+ const f = await startProxy({
+ endpointUrl: gate.url,
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook('responseRewrite:{handle(){return [{type:"appendText",text:"-EDIT"}]}}'),
+ },
+ ],
+ });
+ fixtures.push(f);
+ let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+ try {
+ const res = await f.fetch();
+ expect(res.status).toBe(200);
+ reader = res.body!.getReader();
+ const prefix = await readUntil(reader, (raw) => events(raw).some((e) => e.type === "ping"));
+ expect({ text: textOf(prefix), released: gate.released }).toEqual({
+ text: "",
+ released: false,
+ });
+ gate.release();
+ const raw = prefix + (await remainder(reader));
+ expect(textOf(raw)).toBe("FIRSTSECOND-EDIT");
+ await until(() => f.ws.debug().includes("mode=buffer"), "buffer seam diagnostic");
+ expect(f.ws.debug()).toContain("mode=buffer");
+ } finally {
+ gate.release();
+ await reader?.cancel().catch(() => {});
+ gate.stop();
+ }
+ }, 20000);
+
+ test("S-15 seam emits a ping while awaiting rewrite after the upstream already closed", async () => {
+ const code = `import {existsSync,writeFileSync} from "node:fs";import {join} from "node:path";
+ ${hook('responseRewrite:{async handle(){writeFileSync(join(process.env.HOME,"rewrite-started"),"YES");while(!existsSync(join(process.env.HOME,"release-rewrite")))await Bun.sleep(5);return [{type:"appendText",text:"-EDIT"}]}}', "timeoutMs:5000,")}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ const res = await f.fetch();
+ expect(res.status).toBe(200);
+ const reader = res.body!.getReader();
+ try {
+ await until(
+ () => existsSync(join(f.ws.layout.home, "rewrite-started")),
+ "rewrite called after provider end"
+ );
+ const prefix = await readUntil(reader, (raw) => events(raw).some((e) => e.type === "ping"));
+ expect(textOf(prefix)).toBe("");
+ writeFileSync(join(f.ws.layout.home, "release-rewrite"), "GO");
+ expect(textOf(prefix + (await remainder(reader)))).toBe("original-EDIT");
+ } finally {
+ writeFileSync(join(f.ws.layout.home, "release-rewrite"), "GO");
+ await reader.cancel().catch(() => {});
+ }
+ }, 20000);
+
+ test("S-16 multi-byte network split preserves emoji and CJK through rewrite", async () => {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook('responseRewrite:{handle(){return [{type:"appendText",text:" ✓"}]}}'),
+ },
+ ],
+ script: [{ parts: [{ text: "答え 🍐 東京" }], splitMultibyte: true, deltaChars: 1 }],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("答え 🍐 東京 ✓");
+ }, 20000);
+
+ test("S-17 no-modules negative control retains REMOVE-ME and never adds the marker", async () => {
+ const f = await startProxy({
+ modules: [],
+ script: [{ parts: [{ text: "KEEP REMOVE-ME KEEP" }] }],
+ });
+ fixtures.push(f);
+ const raw = await f.read();
+ expect(textOf(raw)).toBe("KEEP REMOVE-ME KEEP");
+ expect(raw).not.toContain("HOOK-ADDED");
+ expect(f.ws.journal().filter((r) => r.hookId.startsWith("hook:"))).toEqual([]);
+ }, 20000);
+});
diff --git a/packages/cli/src/hooks/blind/session-unavailable.blind.test.ts b/packages/cli/src/hooks/blind/session-unavailable.blind.test.ts
new file mode 100644
index 00000000..f535c1bd
--- /dev/null
+++ b/packages/cli/src/hooks/blind/session-unavailable.blind.test.ts
@@ -0,0 +1,163 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+ type ProxyFixture,
+ hook,
+ startProxy,
+ textOf,
+ until,
+ userRows,
+ waitJournal,
+} from "./support.ts";
+
+const fixtures: ProxyFixture[] = [];
+afterEach(async () => {
+ for (const f of fixtures.splice(0)) await f.close();
+});
+const imports = 'import {writeFileSync} from "node:fs";import {join} from "node:path";';
+
+// This file intentionally does not claim a delivered turn, idle/dialog safety, or any H-row.
+describe("FR-3 / FR-5 no-surface session and injection failure paths (§4.4–4.7)", () => {
+ test("N-1 sessionStart fires at spawn even when proxy model/route filters do not match", async () => {
+ const code = `${imports}${hook('sessionStart(ctx){writeFileSync(join(process.env.HOME,"start.json"),JSON.stringify({event:ctx.event,session:ctx.session}));return [{type:"warn",message:"STARTED"}]}', 'models:"not-the-test-model",routes:"native",')}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ const file = join(f.ws.layout.home, "start.json");
+ await until(() => existsSync(file), "no-surface sessionStart");
+ const ctx = JSON.parse(readFileSync(file, "utf8"));
+ expect({
+ event: ctx.event,
+ kind: ctx.session.kind,
+ role: ctx.session.role,
+ cwd: ctx.session.cwd,
+ injection: ctx.session.injection,
+ }).toEqual({
+ event: "sessionStart",
+ kind: "interactive",
+ role: null,
+ cwd: f.ws.layout.cwd,
+ injection: "unavailable",
+ });
+ expect(textOf(await f.read())).toBe("original");
+ await waitJournal(
+ f.ws,
+ (r) => r.hookId === "hook:sample/test" && r.event === "sessionStart" && r.action === "warn"
+ );
+ }, 20000);
+
+ test("N-2 responseEnd injection without a surface is dropped, never blocks, and warns once", async () => {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook('responseEnd(){return [{type:"injectUserTurn",text:"HOOK-PING"}]}'),
+ },
+ ],
+ });
+ fixtures.push(f);
+ for (let n = 0; n < 2; n++) expect(textOf(await f.read())).toBe("original");
+ await until(
+ () =>
+ userRows(f.ws).filter(
+ (r) =>
+ r.action === "injectUserTurn" &&
+ r.decision === "dropped" &&
+ (r.detail ?? "").includes("unavailable")
+ ).length === 2,
+ "both unavailable injections"
+ );
+ const diagnostic =
+ "hook injection dropped: this claudish process has no Claude Code session to deliver it to";
+ expect(f.ws.diagnostics(f.process).split(diagnostic)).toHaveLength(2);
+ expect(f.stub.requests).toHaveLength(2);
+ expect(f.process.stdout).not.toContain("HOOK-PING");
+ }, 20000);
+
+ for (const [name, text, detail] of [
+ ["leading-whitespace slash command", " \t/clear", "slash_command"],
+ ["empty text", "", ""],
+ ["more than 100000 chars", "x".repeat(100001), ""],
+ ]) {
+ test(`N-3 ${name} is invalid before an injection can be queued`, async () => {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook(
+ `responseEnd(){return [{type:"injectUserTurn",text:${JSON.stringify(text)}}]}`
+ ),
+ },
+ ],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.action === "injectUserTurn" &&
+ r.decision === "invalid"
+ );
+ const rows = userRows(f.ws).filter((r) => r.action === "injectUserTurn");
+ expect(rows.some((r) => r.decision === "queued" || r.decision === "delivered")).toBe(false);
+ if (detail) expect(rows.some((r) => (r.detail ?? "").includes(detail!))).toBe(true);
+ }, 20000);
+ }
+
+ test("N-4 unavailable annotation is journaled without a user-facing injection warning", async () => {
+ const f = await startProxy({
+ modules: [
+ {
+ name: "sample.ts",
+ code: hook('responseEnd(){return [{type:"annotateTurn",key:"ran-command",value:true}]}'),
+ },
+ ],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.action === "annotateTurn" &&
+ r.decision === "dropped" &&
+ (r.detail ?? "").includes("unavailable")
+ );
+ expect(f.ws.diagnostics(f.process)).not.toContain("hook injection dropped:");
+ }, 20000);
+
+ for (const condition of ["throw", "hang"]) {
+ test(`N-4 ${condition} in sessionStart cannot prevent a proxy request from succeeding`, async () => {
+ const body =
+ condition === "throw" ? 'throw new Error("START-FAIL")' : "return new Promise(()=>{})";
+ const f = await startProxy({
+ modules: [{ name: "sample.ts", code: hook(`sessionStart(){${body}}`, "timeoutMs:50,") }],
+ });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ await waitJournal(
+ f.ws,
+ (r) =>
+ r.hookId === "hook:sample/test" &&
+ r.event === "sessionStart" &&
+ r.decision === (condition === "throw" ? "error" : "timeout")
+ );
+ }, 20000);
+ }
+
+ test("N-5 sessionEnd fires when the fake Claude exits and exposes exitCode zero", async () => {
+ const code = `${imports}${hook('sessionEnd(ctx){writeFileSync(join(process.env.HOME,"end-session.json"),JSON.stringify({event:ctx.event,session:ctx.session,outcome:ctx.outcome}))}')}`;
+ const f = await startProxy({ modules: [{ name: "sample.ts", code }] });
+ fixtures.push(f);
+ expect(textOf(await f.read())).toBe("original");
+ f.process.write("/exit\r");
+ expect(await f.process.finish()).toBe(0);
+ const ctx = JSON.parse(readFileSync(join(f.ws.layout.home, "end-session.json"), "utf8"));
+ expect({ event: ctx.event, kind: ctx.session.kind, exitCode: ctx.outcome.exitCode }).toEqual({
+ event: "sessionEnd",
+ kind: "interactive",
+ exitCode: 0,
+ });
+ }, 20000);
+});
diff --git a/packages/cli/src/hooks/blind/support.ts b/packages/cli/src/hooks/blind/support.ts
new file mode 100644
index 00000000..f9cf8c37
--- /dev/null
+++ b/packages/cli/src/hooks/blind/support.ts
@@ -0,0 +1,521 @@
+import { expect } from "bun:test";
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import {
+ type PaneTestEnv,
+ makePaneTestEnv,
+ waitNoOrphans,
+ writeFakeClaudeWrapper,
+} from "../../pane/test-helpers/hermetic-env.ts";
+import {
+ type StubScript,
+ type StubUpstream,
+ startStubUpstream,
+ stubEndpointConfig,
+} from "../../test-helpers/stub-upstream.ts";
+
+export const ENTRY = resolve(import.meta.dir, "../../index.ts");
+export const OUTPUT_CAPTURE = resolve(import.meta.dir, "../output-capture.ts");
+export const PUBLIC = resolve(import.meta.dir, "../public.ts");
+
+export function deferred<T>() {
+ let resolve!: (value: T) => void;
+ let reject!: (reason: unknown) => void;
+ const promise = new Promise<T>((yes, no) => {
+ resolve = yes;
+ reject = no;
+ });
+ return { promise, resolve, reject };
+}
+
+export async function until(check: () => boolean, label: string, ms = 10000): Promise<void> {
+ const deadline = Date.now() + ms;
+ while (!check()) {
+ if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${label}`);
+ await Bun.sleep(15);
+ }
+}
+
+export class ProcessCapture {
+ readonly child: ChildProcessWithoutNullStreams;
+ readonly exit: Promise<number>;
+ stdout = "";
+ stderr = "";
+ closed = false;
+
+ constructor(command: string[], layout: PaneTestEnv, extra: Record<string, string> = {}) {
+ this.child = spawn(command[0]!, command.slice(1), {
+ cwd: layout.cwd,
+ env: { ...layout.env, ...extra },
+ stdio: ["pipe", "pipe", "pipe"],
+ });
+ this.child.stdout.setEncoding("utf8");
+ this.child.stderr.setEncoding("utf8");
+ this.child.stdout.on("data", (s: string) => {
+ this.stdout += s;
+ });
+ this.child.stderr.on("data", (s: string) => {
+ this.stderr += s;
+ });
+ this.exit = new Promise<number>((yes, no) => {
+ this.child.once("error", no);
+ this.child.once("close", (code, signal) => {
+ this.closed = true;
+ yes(code ?? (signal ? 128 : -1));
+ });
+ });
+ }
+
+ write(text: string): void {
+ this.child.stdin.write(text);
+ }
+
+ async stop(): Promise<void> {
+ if (this.closed) return;
+ this.child.kill("SIGTERM");
+ const timer = setTimeout(() => {
+ if (!this.closed) this.child.kill("SIGKILL");
+ }, 2000);
+ try {
+ await this.exit;
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+
+ async finish(ms = 15000): Promise<number> {
+ const timer = setTimeout(() => {
+ if (!this.closed) this.child.kill("SIGKILL");
+ }, ms);
+ try {
+ return await this.exit;
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+}
+
+export interface ModuleSource {
+ name: string;
+ code: string;
+}
+
+export class Workspace {
+ readonly layout: PaneTestEnv;
+ readonly configFile: string;
+ readonly processes: ProcessCapture[] = [];
+ readonly sessionIds: string[] = [];
+ config: Record<string, unknown> = {};
+
+ constructor(extra: Record<string, string> = {}) {
+ this.layout = makePaneTestEnv(extra);
+ this.configFile = join(this.layout.tmp, "config", "config.json");
+ mkdirSync(dirname(this.configFile), { recursive: true });
+ mkdirSync(join(this.layout.home, ".claudish"), { recursive: true });
+ }
+
+ file(relative: string, content: string): string {
+ const path = join(this.layout.tmp, relative);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, content);
+ return path;
+ }
+
+ module(name: string, code: string): string {
+ return this.file(`modules/${name}`, code);
+ }
+
+ save(config: Record<string, unknown>): void {
+ this.config = config;
+ writeFileSync(this.configFile, JSON.stringify(config));
+ }
+
+ spawn(args: string[], extra: Record<string, string> = {}): ProcessCapture {
+ return this.track([process.execPath, "--no-env-file", ENTRY, ...args], extra);
+ }
+
+ track(command: string[], extra: Record<string, string> = {}): ProcessCapture {
+ const p = new ProcessCapture(command, this.layout, extra);
+ this.processes.push(p);
+ return p;
+ }
+
+ async cli(args: string[]): Promise<{ code: number; stdout: string; stderr: string }> {
+ const p = this.spawn(["--config", this.configFile, ...args]);
+ const code = await p.finish();
+ return { code, stdout: p.stdout, stderr: p.stderr };
+ }
+
+ journal(): JournalRow[] {
+ const path = join(this.layout.home, ".claudish", "behavior-journal.jsonl");
+ if (!existsSync(path)) return [];
+ return readFileSync(path, "utf8")
+ .split("\n")
+ .filter(Boolean)
+ .map((s) => JSON.parse(s));
+ }
+
+ debug(): string {
+ const dir = join(this.layout.cwd, "logs");
+ if (!existsSync(dir)) return "";
+ const texts: string[] = [];
+ const visit = (root: string) => {
+ for (const entry of readdirSync(root, { withFileTypes: true })) {
+ const path = join(root, entry.name);
+ if (entry.isDirectory()) visit(path);
+ else if (entry.isFile()) texts.push(readFileSync(path, "utf8"));
+ }
+ };
+ visit(dir);
+ return texts.join("\n");
+ }
+
+ diagnostics(p: ProcessCapture): string {
+ const dir = join(this.layout.home, ".claudish");
+ const logs = existsSync(dir)
+ ? readdirSync(dir)
+ .filter((name) => /^diag-\d+\.log$/.test(name))
+ .map((name) => readFileSync(join(dir, name), "utf8"))
+ : [];
+ return [p.stderr, ...logs].join("\n");
+ }
+
+ async close(): Promise<void> {
+ try {
+ for (const p of this.processes) await p.stop();
+ const leftovers = await waitNoOrphans({
+ sockRoot: this.layout.sockRoot,
+ ids: this.sessionIds,
+ });
+ expect(leftovers).toEqual({ processes: [], files: [] });
+ } finally {
+ this.layout.cleanup();
+ }
+ }
+}
+
+export interface JournalRow {
+ schema: number;
+ hookId: string;
+ ruleId?: string;
+ event: string;
+ action?: string;
+ decision: string;
+ detail?: string;
+ toolName?: string;
+ argKeys?: string[];
+}
+
+export function hook(on: string, fields = ""): string {
+ return `export default { apiVersion: 1, id: "test", ${fields} on: { ${on} } };`;
+}
+
+export interface SseEvent {
+ type: string;
+ index?: number;
+ content_block?: {
+ type: string;
+ text?: string;
+ thinking?: string;
+ name?: string;
+ input?: unknown;
+ };
+ delta?: {
+ type?: string;
+ text?: string;
+ thinking?: string;
+ signature?: string;
+ partial_json?: string;
+ stop_reason?: string;
+ };
+ [key: string]: unknown;
+}
+
+export function events(raw: string): SseEvent[] {
+ return raw
+ .split(/\r?\n\r?\n/)
+ .slice(0, -1)
+ .flatMap((frame) => {
+ const data = frame
+ .split(/\r?\n/)
+ .filter((s) => s.startsWith("data:"))
+ .map((s) => s.slice(5).trim())
+ .join("\n");
+ if (!data || data === "[DONE]") return [];
+ return [JSON.parse(data) as SseEvent];
+ });
+}
+
+export function textOf(raw: string): string {
+ return events(raw)
+ .map((e) => {
+ if (e.type === "content_block_start" && e.content_block?.type === "text")
+ return e.content_block.text ?? "";
+ return e.delta?.type === "text_delta" ? (e.delta.text ?? "") : "";
+ })
+ .join("");
+}
+
+export function thinkingOf(raw: string): string {
+ return events(raw)
+ .map((e) => (e.delta?.type === "thinking_delta" ? (e.delta.thinking ?? "") : ""))
+ .join("");
+}
+
+export function toolInputs(raw: string): Array<{ name: string; input: unknown }> {
+ const byIndex = new Map<number, { name: string; input: unknown; json: string }>();
+ for (const e of events(raw)) {
+ if (e.type === "content_block_start" && e.content_block?.type === "tool_use") {
+ byIndex.set(e.index!, {
+ name: e.content_block.name!,
+ input: e.content_block.input,
+ json: "",
+ });
+ }
+ if (e.delta?.type === "input_json_delta") {
+ const tool = byIndex.get(e.index!);
+ if (tool) tool.json += e.delta.partial_json ?? "";
+ }
+ }
+ return [...byIndex.values()].map((t) => ({
+ name: t.name,
+ input: t.json ? JSON.parse(t.json) : t.input,
+ }));
+}
+
+export interface ProxyFixture {
+ ws: Workspace;
+ process: ProcessCapture;
+ stub: StubUpstream;
+ sessionId: string;
+ fetch(body?: Record<string, unknown>): Promise<Response>;
+ read(body?: Record<string, unknown>): Promise<string>;
+ close(): Promise<void>;
+}
+
+export async function startProxy(
+ opts: {
+ modules?: ModuleSource[];
+ hooks?: Record<string, unknown>;
+ config?: Record<string, unknown>;
+ script?: StubScript;
+ endpointUrl?: string;
+ } = {}
+): Promise<ProxyFixture> {
+ const ws = new Workspace();
+ const stub = startStubUpstream({
+ format: "openai-sse",
+ script: opts.script ?? [{ parts: [{ text: "original" }] }],
+ });
+ try {
+ const modules = (opts.modules ?? []).map((m) => ws.module(m.name, m.code));
+ const config = stubEndpointConfig(stub);
+ if (opts.endpointUrl) {
+ const endpoints = config.customEndpoints as Record<string, { url: string }>;
+ endpoints.stub!.url = `${opts.endpointUrl}/v1`;
+ }
+ ws.save({ ...config, ...opts.config, hooks: { modules, ...opts.hooks } });
+ const dump = join(ws.layout.tmp, "claude-env.json");
+ const wrapper = writeFakeClaudeWrapper(ws.layout.tmp);
+ const sessionId = randomUUID();
+ ws.sessionIds.push(sessionId);
+ const p = ws.spawn(
+ [
+ "--config",
+ ws.configFile,
+ "-i",
+ "--model",
+ "stub@fake-model",
+ "-y",
+ "--quiet",
+ "--session-id",
+ sessionId,
+ "--debug-claudish",
+ ],
+ {
+ CLAUDE_PATH: wrapper,
+ FAKE_CLAUDE_DUMP: dump,
+ CONTRACT_FAKE_MAX_MS: "60000",
+ }
+ );
+ await until(() => existsSync(dump) || p.closed, "the fake Claude environment");
+ if (!existsSync(dump))
+ throw new Error(`Launcher exited before Claude started: ${p.stderr}\n${p.stdout}`);
+ // The dump file can exist before the fake Claude has finished writing it. Poll until it parses
+ // (bounded) rather than reading a half-written file.
+ const parsed: { value?: { env: Record<string, string> } } = {};
+ await until(
+ () => {
+ try {
+ parsed.value = JSON.parse(readFileSync(dump, "utf8")) as { env: Record<string, string> };
+ return true;
+ } catch {
+ return false;
+ }
+ },
+ "the fake Claude environment dump to be complete JSON",
+ 10000
+ );
+ const snapshot = parsed.value;
+ if (!snapshot) throw new Error(`Fake Claude dump never parsed: ${dump}`);
+ const base = snapshot.env.ANTHROPIC_BASE_URL;
+ if (!base || !/^http:\/\/(127\.0\.0\.1|localhost):\d+/.test(base)) {
+ throw new Error(`Expected a loopback child proxy, got ${String(base)}`);
+ }
+ const send = async (body: Record<string, unknown> = {}) =>
+ fetch(`${base.replace(/\/$/, "")}/v1/messages`, {
+ method: "POST",
+ signal: AbortSignal.timeout(15000),
+ headers: {
+ "content-type": "application/json",
+ "anthropic-version": "2023-06-01",
+ "x-api-key": snapshot.env.ANTHROPIC_API_KEY ?? "test-placeholder",
+ },
+ body: JSON.stringify({
+ model: "stub@fake-model",
+ max_tokens: 1024,
+ stream: true,
+ messages: [{ role: "user", content: "HELLO" }],
+ metadata: { user_id: JSON.stringify({ session_id: sessionId }) },
+ ...body,
+ }),
+ });
+ return {
+ ws,
+ process: p,
+ stub,
+ sessionId,
+ fetch: send,
+ async read(body) {
+ const res = await send(body);
+ const raw = await res.text();
+ expect({
+ status: res.status,
+ text: res.headers.get("content-type")?.includes("text/event-stream"),
+ }).toEqual({ status: 200, text: true });
+ expect(events(raw).filter((e) => e.type === "message_stop")).toHaveLength(1);
+ return raw;
+ },
+ async close() {
+ stub.stop();
+ await ws.close();
+ },
+ };
+ } catch (error) {
+ stub.stop();
+ await ws.close();
+ throw error;
+ }
+}
+
+export function userRows(ws: Workspace, id = "hook:sample/test"): JournalRow[] {
+ return ws.journal().filter((r) => r.hookId === id);
+}
+
+export async function waitJournal(
+ ws: Workspace,
+ match: (row: JournalRow) => boolean
+): Promise<JournalRow[]> {
+ await until(() => ws.journal().some(match), "the expected hook journal decision");
+ return ws.journal();
+}
+
+/** Hold the provider after its first text delta until the test releases it. */
+export function gatedProvider(prefix = "FIRST", suffix = "SECOND") {
+ const release = deferred<void>();
+ const reached = deferred<void>();
+ let released = false;
+ const base = {
+ id: "chatcmpl-gate",
+ object: "chat.completion.chunk",
+ created: 0,
+ model: "fake-model",
+ };
+ const frame = (delta: object, finish: string | null = null) =>
+ `data: ${JSON.stringify({ ...base, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`;
+ const server = Bun.serve({
+ hostname: "127.0.0.1",
+ port: 0,
+ fetch(req) {
+ if (req.method !== "POST") return Response.json({ data: [] });
+ const encoder = new TextEncoder();
+ const body = new ReadableStream<Uint8Array>({
+ async start(c) {
+ c.enqueue(encoder.encode(frame({ role: "assistant", content: prefix })));
+ reached.resolve();
+ await release.promise;
+ released = true;
+ c.enqueue(encoder.encode(frame({ content: suffix })));
+ c.enqueue(encoder.encode(frame({}, "stop")));
+ c.enqueue(encoder.encode("data: [DONE]\n\n"));
+ c.close();
+ },
+ });
+ return new Response(body, { headers: { "content-type": "text/event-stream" } });
+ },
+ });
+ return {
+ url: `http://127.0.0.1:${server.port}`,
+ reached: reached.promise,
+ get released() {
+ return released;
+ },
+ release() {
+ release.resolve();
+ },
+ stop() {
+ release.resolve();
+ server.stop(true);
+ },
+ };
+}
+
+export async function readUntil(
+ reader: ReadableStreamDefaultReader<Uint8Array>,
+ predicate: (raw: string) => boolean,
+ ms = 4000
+): Promise<string> {
+ let raw = "";
+ const decoder = new TextDecoder();
+ const deadline = Date.now() + ms;
+ while (!predicate(raw)) {
+ const remaining = deadline - Date.now();
+ if (remaining <= 0) throw new Error(`Client did not receive the expected SSE: ${raw}`);
+ const read = reader.read();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ const next = await Promise.race([
+ read,
+ new Promise<never>((_, no) => {
+ timer = setTimeout(() => no(new Error("Client SSE read timed out")), remaining);
+ }),
+ ]);
+ if (next.done) throw new Error(`Client ended before the expected SSE: ${raw}`);
+ raw += decoder.decode(next.value, { stream: true });
+ } finally {
+ clearTimeout(timer);
+ }
+ }
+ return raw;
+}
+
+export function rpc(proc: ProcessCapture, id: number, method: string, params?: unknown): void {
+ proc.write(
+ `${JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) })}\n`
+ );
+}
+
+export function rpcLines(stdout: string): Array<{
+ jsonrpc?: string;
+ id?: number | string | null;
+ result?: unknown;
+ error?: unknown;
+ method?: string;
+}> {
+ return stdout
+ .split("\n")
+ .filter(Boolean)
+ .map((line) => JSON.parse(line));
+}