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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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));+}