Skip to content

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

19.3 KB
Raw Blame
import { describe, expect, it } from "bun:test";
import {
  type MutableClaudeRequest,
  type PlannedAction,
  applyStageA,
  applyStageB,
  applyToolCallActions,
  requestChainState,
  validateAction,
} from "./actions.js";
import { type RequestAction, type ToolCallAction, act } from "./public.js";

const plan = (hookId: string, action: RequestAction): PlannedAction<RequestAction> => ({
  hookId,
  action,
});

function request(overrides: Partial<MutableClaudeRequest> = {}): MutableClaudeRequest {
  return {
    system: "base",
    messages: [
      { role: "user", content: "first question" },
      {
        role: "assistant",
        content: [
          { type: "thinking", thinking: "secret plan", signature: "sig" },
          { type: "text", text: "let me check" },
          { type: "tool_use", id: "toolu_1", name: "Read", input: { path: "plan" } },
        ],
      },
      {
        role: "user",
        content: [{ type: "tool_result", tool_use_id: "toolu_1", content: "plan contents" }],
      },
    ],
    tools: [
      { name: "Read", description: "Read a file", input_schema: { type: "object" } },
      { name: "Write", description: "Write a file", input_schema: { type: "object" } },
      { name: "ExitPlanMode", description: "Exit.", input_schema: { type: "object" } },
    ],
    ...overrides,
  };
}

/**
 * One stage-A step over `req` as a chain's first step: the step's state is
 * written back onto `req`, so the assertions read the request as it would be sent.
 */
function stageA(req: MutableClaudeRequest, items: ReadonlyArray<PlannedAction<RequestAction>>) {
  const step = applyStageA(requestChainState(req), items);
  req.system = step.state.system;
  req.messages = step.state.messages;
  req.tools = step.state.tools;
  return { ...step, held: step.state.held, removedTools: step.state.removedTools };
}

describe("validateAction", () => {
  it("allows only the event's actions", () => {
    expect(validateAction("request", act.injectSystemNote("x")).ok).toBe(true);
    expect(validateAction("request", act.appendText("x"))).toEqual({
      ok: false,
      reason: "not_allowed:appendText",
    });
    expect(validateAction("responseEnd", act.injectUserTurn("go")).ok).toBe(true);
    expect(validateAction("sessionBlocked", act.injectUserTurn("go")).ok).toBe(false);
    expect(validateAction("sessionEnd", act.warn("w")).ok).toBe(true);
  });

  it("restricts an observe-mode toolCall hook to warn", () => {
    expect(
      validateAction("toolCall", act.repairToolArgs({ a: 1 }, "r"), { observe: true })
    ).toEqual({ ok: false, reason: "observe_only" });
    expect(validateAction("toolCall", act.warn("w"), { observe: true }).ok).toBe(true);
  });

  it("rejects non-actions and unknown types", () => {
    expect(validateAction("request", null)).toEqual({ ok: false, reason: "not_an_action" });
    expect(validateAction("request", { type: "launchMissiles" })).toEqual({
      ok: false,
      reason: "not_allowed:launchMissiles",
    });
  });

  it("refuses an injectUserTurn starting with a slash once leading whitespace is ignored", () => {
    expect(validateAction("sessionIdle", act.injectUserTurn(" /clear"))).toEqual({
      ok: false,
      reason: "slash_command",
    });
    expect(validateAction("sessionIdle", act.injectUserTurn("\n\t/compact"))).toEqual({
      ok: false,
      reason: "slash_command",
    });
    expect(validateAction("sessionIdle", act.injectUserTurn("run a/b")).ok).toBe(true);
  });

  it("enforces text limits", () => {
    expect(validateAction("request", act.injectSystemNote(""))).toEqual({
      ok: false,
      reason: "empty_text",
    });
    expect(validateAction("request", act.injectSystemNote("x".repeat(20_000))).ok).toBe(true);
    expect(validateAction("request", act.injectSystemNote("x".repeat(20_001))).ok).toBe(false);
    expect(validateAction("request", act.rewriteToolDescription("T", "x".repeat(4_001))).ok).toBe(
      false
    );
    expect(validateAction("sessionIdle", act.injectUserTurn("x".repeat(100_001))).ok).toBe(false);
  });

  it("checks replaceToolSchema shape and size", () => {
    expect(
      validateAction("request", {
        type: "replaceToolSchema",
        tool: "Write",
        inputSchema: { type: "array" },
      })
    ).toEqual({ ok: false, reason: "schema_not_object" });
    expect(
      validateAction(
        "request",
        act.replaceToolSchema("Write", { type: "object", description: "x".repeat(70_000) })
      )
    ).toEqual({ ok: false, reason: "schema_too_large" });
    expect(
      validateAction("request", act.replaceToolSchema("Write", { type: "object", f: () => 1 }))
    ).toEqual({ ok: false, reason: "schema_not_json" });
  });

  it("checks annotateTurn key and value", () => {
    expect(validateAction("responseEnd", act.annotateTurn("files.read", ["a", 1])).ok).toBe(true);
    expect(validateAction("responseEnd", act.annotateTurn("Bad Key", 1))).toEqual({
      ok: false,
      reason: "invalid_key",
    });
    expect(validateAction("responseEnd", act.annotateTurn("k", "x".repeat(17_000)))).toEqual({
      ok: false,
      reason: "value_too_large",
    });
  });

  it("checks repairToolArgs and a regex find", () => {
    expect(validateAction("toolCall", act.repairToolArgs({ a: 1 }, "why")).ok).toBe(true);
    expect(validateAction("toolCall", { type: "repairToolArgs", args: [1], reason: "r" })).toEqual({
      ok: false,
      reason: "args_not_object",
    });
    expect(validateAction("request", act.replaceMessageText("(", "x", { regex: true }))).toEqual({
      ok: false,
      reason: "invalid_regex",
    });
    expect(
      validateAction("request", {
        type: "replaceMessageText",
        find: "a",
        replace: "b",
        roles: ["system"],
      })
    ).toEqual({ ok: false, reason: "invalid_roles" });
  });
});

describe("applyStageA — system notes", () => {
  it("appends to a string system as a new paragraph, once per identical text", () => {
    const req = request();
    const { results } = stageA(req, [
      plan("a", act.injectSystemNote("NOTE")),
      plan("b", act.injectSystemNote("NOTE")),
    ]);
    expect(req.system).toBe("base\n\nNOTE");
    expect(results.map((r) => [r.hookId, r.decision])).toEqual([
      ["a", "matched"],
      ["b", "superseded"],
    ]);
  });

  it("appends a text block to an array system without mutating the original array", () => {
    const original = [{ type: "text", text: "base" }];
    const req = request({ system: original });
    stageA(req, [plan("a", act.injectSystemNote("NOTE"))]);
    expect(req.system).toEqual([
      { type: "text", text: "base" },
      { type: "text", text: "NOTE" },
    ]);
    expect(original.length).toBe(1);
  });

  it("sets the system prompt when the request has none", () => {
    const req = request({ system: undefined });
    stageA(req, [plan("a", act.injectSystemNote("NOTE"))]);
    expect(req.system).toBe("NOTE");
  });
});

describe("applyStageA — message text", () => {
  it("appendUserText lands at the end of the last user message, after tool_result", () => {
    const req = request();
    stageA(req, [plan("a", act.appendUserText("REMINDER"))]);
    const last = req.messages?.[2];
    expect(last.content).toEqual([
      { type: "tool_result", tool_use_id: "toolu_1", content: "plan contents" },
      { type: "text", text: "REMINDER" },
    ]);
  });

  it("appendUserText normalises a string content to blocks first", () => {
    const req = request({ messages: [{ role: "user", content: "hi" }] });
    stageA(req, [plan("a", act.appendUserText("there"))]);
    expect(req.messages?.[0].content).toEqual([
      { type: "text", text: "hi" },
      { type: "text", text: "there" },
    ]);
  });

  it("appendUserText with no user message is invalid", () => {
    const req = request({ messages: [{ role: "assistant", content: "x" }] });
    const { results } = stageA(req, [plan("a", act.appendUserText("x"))]);
    expect(results[0]).toMatchObject({ decision: "invalid", detail: "no_user_message" });
  });

  it("identical appended texts are applied once", () => {
    const req = request({ messages: [{ role: "user", content: "q" }] });
    const { results } = stageA(req, [
      plan("a", act.appendUserText("same")),
      plan("b", act.appendUserText("same")),
    ]);
    expect(req.messages?.[0].content.length).toBe(2);
    expect(results.map((r) => r.decision)).toEqual(["matched", "superseded"]);
  });

  it("a duplicate in a later step's list is superseded too", () => {
    const req = request({ messages: [{ role: "user", content: "q" }] });
    const first = applyStageA(requestChainState(req), [
      plan("a", act.appendUserText("same")),
      plan("a", act.injectSystemNote("NOTE")),
    ]);
    const second = applyStageA(first.state, [
      plan("b", act.appendUserText("same")),
      plan("b", act.injectSystemNote("NOTE")),
    ]);
    expect(second.state.messages?.[0].content.length).toBe(2);
    expect(second.state.system).toBe("base\n\nNOTE");
    expect(second.results.map((r) => [r.hookId, r.decision, r.detail])).toEqual([
      ["b", "superseded", "duplicate"],
      ["b", "superseded", "duplicate"],
    ]);
    // A step never mutates the state it was given.
    expect(first.state.messages?.[0].content.length).toBe(2);
    expect(req.messages?.[0].content).toBe("q");
  });

  it("never touches tool_use, tool_result or thinking, and defaults roles to user", () => {
    const req = request();
    const before = structuredClone(req.messages);
    stageA(req, [plan("a", act.replaceMessageText("plan", "PLAN"))]);
    // User string content was edited; the assistant turn (default roles) was not.
    expect(req.messages?.[0].content).toBe("first question");
    expect(req.messages?.[1]).toEqual(before?.[1]);
    // tool_result content is never edited even though it contains "plan".
    expect(req.messages?.[2]).toEqual(before?.[2]);

    stageA(req, [plan("a", act.replaceMessageText("check", "verify", { roles: ["assistant"] }))]);
    const blocks = req.messages?.[1].content;
    expect(blocks[0]).toEqual({ type: "thinking", thinking: "secret plan", signature: "sig" });
    expect(blocks[1]).toEqual({ type: "text", text: "let me verify" });
    expect(blocks[2].input).toEqual({ path: "plan" });
  });

  it("inserts a literal $500 verbatim and expands $1 in regex mode", () => {
    const req = request({ messages: [{ role: "user", content: "cost N, name: Ada Lovelace" }] });
    stageA(req, [
      plan("a", act.replaceMessageText("N", "$500")),
      plan("b", act.replaceMessageText("(\\w+) (\\w+)$", "$2 $1", { regex: true })),
    ]);
    expect(req.messages?.[0].content).toBe("cost $500, name: Lovelace Ada");
  });

  it("drops an emptied text block, and reverts an edit that would empty a message", () => {
    const req = request({
      messages: [
        {
          role: "user",
          content: [
            { type: "text", text: "DROP" },
            { type: "text", text: "keep" },
          ],
        },
        { role: "assistant", content: "ok" },
        { role: "user", content: "DROP" },
      ],
    });
    const { results } = stageA(req, [plan("a", act.removeMessageText("DROP"))]);
    expect(req.messages?.[0].content).toEqual([{ type: "text", text: "keep" }]);
    expect(req.messages?.[2].content).toBe("DROP");
    expect(results[0]).toMatchObject({ decision: "matched", detail: "empty_message_reverted:1" });
  });

  it("reports invalid empty_message when every changed message was reverted", () => {
    const req = request({ messages: [{ role: "user", content: "only" }] });
    const { results } = stageA(req, [plan("a", act.removeMessageText("only"))]);
    expect(req.messages?.[0].content).toBe("only");
    expect(results[0]).toMatchObject({ decision: "invalid", detail: "empty_message" });
  });

  it("applies message edits sequentially in effective order", () => {
    const req = request({ messages: [{ role: "user", content: "a" }] });
    stageA(req, [
      plan("a", act.replaceMessageText("a", "b")),
      plan("b", act.replaceMessageText("b", "c")),
      plan("c", act.appendUserText("d")),
    ]);
    expect(req.messages?.[0].content).toEqual([
      { type: "text", text: "c" },
      { type: "text", text: "d" },
    ]);
  });

  it("does not mutate the original message objects", () => {
    const original = { role: "user", content: [{ type: "text", text: "x" }] };
    const req = request({ messages: [original] });
    stageA(req, [plan("a", act.replaceMessageText("x", "y"))]);
    expect(original.content[0]?.text).toBe("x");
    expect(req.messages?.[0]).not.toBe(original);
  });
});

describe("applyStageA — tools", () => {
  it("removeTool is refused while a message holds a tool_use of that tool", () => {
    const req = request();
    const { results } = stageA(req, [plan("a", act.removeTool("Read"))]);
    expect(results[0]).toMatchObject({ decision: "invalid", detail: "tool_in_history" });
    expect(req.tools?.map((t) => t.name)).toEqual(["Read", "Write", "ExitPlanMode"]);
  });

  it("removes a tool at its place; an action before it stays matched, later ones are superseded", () => {
    const req = request();
    const stage = stageA(req, [
      plan("a", act.replaceToolSchema("Write", { type: "object", properties: {} })),
      plan("b", act.removeTool("Write")),
      plan("c", act.removeTool("Write")),
      plan("d", act.rewriteToolDescription("Write", " more")),
    ]);
    expect(req.tools?.map((t) => t.name)).toEqual(["Read", "ExitPlanMode"]);
    expect(stage.results.map((r) => [r.hookId, r.decision, r.detail])).toEqual([
      ["a", "matched", undefined],
      ["b", "matched", undefined],
      ["c", "superseded", "already_removed"],
    ]);
    const stageB = applyStageB(req.tools ?? [], null, stage.held, stage.removedTools);
    expect(stageB[0]).toMatchObject({
      hookId: "d",
      decision: "superseded",
      detail: "tool_removed",
    });
  });

  it("replaceToolSchema: each replaces the current schema; an unknown tool is invalid", () => {
    const original = request().tools?.[1];
    const req = request();
    const { results } = stageA(req, [
      plan("a", act.replaceToolSchema("Write", { type: "object", properties: { a: {} } })),
      plan("b", act.replaceToolSchema("Write", { type: "object", properties: { b: {} } })),
      plan("c", act.replaceToolSchema("Nope", { type: "object" })),
    ]);
    expect(req.tools?.[1].input_schema).toEqual({ type: "object", properties: { b: {} } });
    expect(original?.input_schema).toEqual({ type: "object" });
    expect(results.map((r) => [r.hookId, r.decision, r.detail])).toEqual([
      ["a", "matched", undefined],
      ["b", "matched", undefined],
      ["c", "invalid", "unknown_tool"],
    ]);
  });

  it("removeTool on an unknown tool is invalid", () => {
    const { results } = stageA(request(), [plan("a", act.removeTool("Nope"))]);
    expect(results[0]).toMatchObject({ decision: "invalid", detail: "unknown_tool" });
  });

  it("holds description actions for stage B in chain order", () => {
    const { held } = stageA(request(), [
      plan("a", act.rewriteToolDescription("Write", " A")),
      plan("b", act.injectSystemNote("x")),
      plan("c", act.replaceToolDescription("Read", "R")),
      plan("d", act.warn("ignored here")),
    ]);
    expect(held.map((h) => h.hookId)).toEqual(["a", "c"]);
  });
});

describe("applyStageB — tool descriptions", () => {
  const claudeTools = () => [
    { name: "ExitPlanMode", description: "Exit plan mode." },
    { name: "Write", description: "Write." },
  ];
  // Chat Completions shape wraps in `function`; Responses shape does not.
  const chatTools = () => [
    { type: "function", function: { name: "ExitPlanMode", description: "Exit plan mode." } },
    { type: "function", function: { name: "Write", description: "Write." } },
  ];

  it("applies to both representations, after conversion", () => {
    const claude = claudeTools();
    const converted = chatTools();
    const results = applyStageB(claude, converted, [
      plan("plan", act.rewriteToolDescription("ExitPlanMode", " Write to /p.md first.")),
    ]);
    expect(claude[0]?.description).toBe("Exit plan mode. Write to /p.md first.");
    expect(converted[0]?.function.description).toBe("Exit plan mode. Write to /p.md first.");
    expect(results[0]).toMatchObject({ decision: "matched" });
  });

  it("appends after a summarised converted description, keeping the full append", () => {
    const claude = [{ name: "ExitPlanMode", description: "Long. Very long description." }];
    // What --summarize-tools left on the converted side: the first sentence.
    const converted = [{ name: "ExitPlanMode", description: "Long." }];
    const append = " IMPORTANT: the plan file is /exact/path.md; write it there.";
    applyStageB(claude, converted, [plan("p", act.rewriteToolDescription("ExitPlanMode", append))]);
    expect(converted[0]?.description).toBe(`Long.${append}`);
  });

  it("replays description actions in order, each over the description before it", () => {
    const claude = claudeTools();
    const converted = chatTools();
    const results = applyStageB(claude, converted, [
      plan("a", act.replaceToolDescription("Write", "NEW")),
      plan("b", act.rewriteToolDescription("Write", " more")),
    ]);
    expect(claude[1]?.description).toBe("NEW more");
    expect(converted[1]?.function.description).toBe("NEW more");
    expect(results.map((r) => r.decision)).toEqual(["matched", "matched"]);
  });

  it("an unknown tool is invalid; a capped tool changes the Claude copy only", () => {
    const claude = claudeTools();
    const converted = [chatTools()[0]];
    const results = applyStageB(claude, converted, [
      plan("a", act.rewriteToolDescription("Nope", " x")),
      plan("b", act.rewriteToolDescription("Write", " x")),
    ]);
    expect(results.map((r) => [r.decision, r.detail])).toEqual([
      ["invalid", "unknown_tool"],
      ["matched", "capped"],
    ]);
    expect(claude[1]?.description).toBe("Write. x");
  });

  it("applies once when both representations are the same array (native)", () => {
    const tools = claudeTools();
    applyStageB(tools, tools, [plan("a", act.rewriteToolDescription("Write", " x"))]);
    expect(tools[1]?.description).toBe("Write. x");
    const solo = claudeTools();
    applyStageB(solo, null, [plan("a", act.rewriteToolDescription("Write", " x"))]);
    expect(solo[1]?.description).toBe("Write. x");
  });

  it("replaces array elements instead of mutating tool objects", () => {
    const claude = claudeTools();
    const original = claude[1];
    applyStageB(claude, null, [plan("a", act.rewriteToolDescription("Write", " x"))]);
    expect(original?.description).toBe("Write.");
    expect(claude[1]).not.toBe(original);
  });
});

describe("applyToolCallActions", () => {
  it("each repairToolArgs replaces the current arguments; every one is matched", () => {
    const items: PlannedAction<ToolCallAction>[] = [
      { hookId: "a", action: act.repairToolArgs({ file_path: "/a" }, "a") },
      { hookId: "b", action: act.repairToolArgs({ file_path: "/b" }, "b") },
    ];
    const model = { file_path: "/model" };
    const out = applyToolCallActions(model, items);
    expect(out.args).toEqual({ file_path: "/b" });
    expect(out.repaired).toBe(true);
    expect(out.results.map((r) => r.decision)).toEqual(["matched", "matched"]);
    expect(model).toEqual({ file_path: "/model" });
  });

  it("returns the arguments it was given when nothing repaired", () => {
    const model = { file_path: "/model" };
    expect(applyToolCallActions(model, [{ hookId: "a", action: act.warn("w") }])).toEqual({
      args: model,
      repaired: false,
      results: [],
    });
  });
});