@akanjs/devkit 3.0.0-beta.19 → 3.0.0-beta.20

package/codeAgent/agent/SubagentPool.ts

@@ -8,42 +8,29 @@ export interface SubagentPoolOptions {
   cwd: string;
   parent: CodeAgentProfile;
   depth: number;
-  /** Progress and refusals reach the parent's host through this rather than through a new event kind. */
+  /** What the tree above this pool has spent and has running; a root pool starts its own. */
+  spend?: SubagentSpend;
   onNotice?: (message: string) => void;
   /** The running children, whole, for a host that draws them as a rail beside the prompt. */
   onAgents?: (agents: CodeAgentSubagent[]) => void;
 }
 
+/** One object shared down a sub-agent tree, so a single token budget and a single concurrency limit bound it. */
+export interface SubagentSpend {
+  tokens: number;
+  running: number;
+}
+
 const maxResultChars = 8_000;
 
-/**
- * How often the running children are re-reported while none of them starts or finishes.
- *
- * A child spends tokens for minutes between the two frames its lifetime would otherwise produce, and the
- * number that decides whether to let it keep going is the one climbing in between. One frame a second for at
- * most a handful of rows is far below what a single streaming turn already puts on the wire.
- */
+// Children are re-reported every second: their token counts climb between start and finish.
 const tickMs = 1_000;
 
 export type SubagentKind = keyof typeof SubagentPool.kinds;
 
-/**
- * The `task` tool: run a narrowed copy of the agent on one question and bring back a summary.
- *
- * **Only the summary crosses back.** A subagent's whole transcript in the parent's context is the fastest way
- * to spend a window, and the reason to spawn one is precisely that its reading should not become the parent's
- * reading.
- *
- * **The budget is not optional.** Depth, concurrency and token ceilings are checked before a child exists,
- * because a recursive `task` with no ceiling is a fork bomb that bills per token.
- */
+// Only a child's answer crosses back, never its transcript. Depth, concurrency and token ceilings are checked
+// before a child exists, because an unbounded recursive `task` is a fork bomb that bills per token.
 export class SubagentPool {
-  /**
-   * What a sub-agent is allowed to be, and the only axis that matters: whether it can change the tree.
-   *
-   * A reader can be spawned for anything — the worst it costs is tokens. A writer works unwatched on the same
-   * checkout as its parent, so it is the one the parent has to ask for by name rather than get by default.
-   */
   static readonly kinds = {
     explore: {
       readOnly: true,
@@ -55,20 +42,20 @@ export class SubagentPool {
     },
   } as const;
 
+  // A writer works unwatched on the parent's checkout, so it has to be asked for by name, never defaulted.
   static readonly defaultKind: SubagentKind = "explore";
 
   readonly #options: SubagentPoolOptions;
-  /** Keyed by the `task` call that opened each child. `agent` lands once it exists, and reports live tokens. */
   readonly #children = new Map<
     string,
     { kind: SubagentKind; description: string; startedAt: number; agent?: { tokensUsed: number } }
   >();
-  #running = 0;
-  #spent = 0;
+  readonly #spend: SubagentSpend;
   #ticker: ReturnType<typeof setInterval> | null = null;
 
   constructor(options: SubagentPoolOptions) {
     this.#options = options;
+    this.#spend = options.spend ?? { tokens: 0, running: 0 };
   }
 
   static extensionFor(options: SubagentPoolOptions): InlineExtension | undefined {
@@ -103,17 +90,16 @@ export class SubagentPool {
         const kind = (params.type ?? SubagentPool.defaultKind) as SubagentKind;
         const refusal = this.#refuse();
         if (refusal) return { content: [{ type: "text", text: refusal }], details: undefined, isError: true };
-        this.#running += 1;
+        this.#spend.running += 1;
         this.#children.set(id, { kind, description: params.description, startedAt: Date.now() });
         this.#report();
-        // Said before it starts, not only when it ends: a turn that goes quiet for a minute while a child
-        // reads the repo is otherwise indistinguishable from a turn that has stopped responding.
+        // Announced at start: a turn quiet for a minute while a child reads looks like one that stopped responding.
         this.#options.onNotice?.(`${kind} sub-agent · ${params.description}`);
         try {
           const text = await this.#run(id, kind, params.prompt, signal);
           return { content: [{ type: "text", text }], details: undefined };
         } finally {
-          this.#running -= 1;
+          this.#spend.running -= 1;
           this.#children.delete(id);
           this.#report();
         }
@@ -124,20 +110,15 @@ export class SubagentPool {
   #refuse() {
     const budget = this.#options.parent.tools.subagent;
     if (!budget) return "Sub-agents are disabled by this profile.";
-    if (this.#running >= budget.maxConcurrent)
-      return `Too many sub-agents are already running (limit ${budget.maxConcurrent}). Wait for one to finish.`;
-    if (this.#spent >= budget.budget)
+    // Refused, never queued: every ancestor keeps its slot while it waits on its child, so a queued child deadlocks.
+    if (this.#spend.running >= budget.maxConcurrent)
+      return `Too many sub-agents are already running (limit ${budget.maxConcurrent} at once, counted across the whole task tree). ${this.#children.size ? "Wait for one of yours to finish, or do" : "Do"} this part yourself.`;
+    if (this.#spend.tokens >= budget.budget)
       return `The sub-agent token budget (${budget.budget}) is spent. Do the rest of this work yourself.`;
     return undefined;
   }
 
-  /**
-   * The child is the parent profile **narrowed** and never widened: in-memory sessions so nothing it does
-   * shows up in the workspace's session tree, no `AGENTS.md` — a sub-agent is asked one narrow question and
-   * the guide is 26k tokens of its budget — and no ability to ask a human, there being nobody on the other
-   * end of a nested turn. The skills stay: they are descriptions until one is needed, and the child writes
-   * code too.
-   */
+  /** The parent profile narrowed, never widened: no session file, no `AGENTS.md`, nobody to ask; skills stay. */
   static childOf(parent: CodeAgentProfile, kind: SubagentKind): CodeAgentProfile {
     const budget = parent.tools.subagent;
     return {
@@ -145,8 +126,7 @@ export class SubagentPool {
       name: `${parent.name}:${kind}`,
       tools: {
         ...parent.tools,
-        // Filtered rather than replaced, so a kind can only ever take tools away from the parent: a child of
-        // a read-only session must not become the one thing in the tree that can write.
+        // Filtered, not replaced: a child of a read-only session must never gain a write tool.
         builtin: SubagentPool.kinds[kind].readOnly
           ? parent.tools.builtin.filter((tool) => codeAgentReadOnlyBuiltins.includes(tool))
           : parent.tools.builtin,
@@ -158,13 +138,7 @@ export class SubagentPool {
     };
   }
 
-  /**
-   * The running children as a list, and the ticker that keeps it moving.
-   *
-   * The ticker is owned by the report rather than by the tool call: two children overlapping must not each
-   * start one, and the last one to finish is what stops it. It is unref'd because a pool with a child still
-   * registered is a bug that should end the process, not hold it open.
-   */
+  // One ticker per pool, unref'd: a child left registered is a bug that must not hold the process open.
   #report() {
     const onAgents = this.#options.onAgents;
     if (!onAgents) return;
@@ -196,28 +170,44 @@ export class SubagentPool {
       profile: child,
       apps: [],
       depth: this.#options.depth + 1,
+      subagentSpend: this.#spend,
     });
     const running = this.#children.get(id);
     if (running) running.agent = agent;
-    const abort = () => void agent.abort();
+    let stopped = false;
+    const abort = () => {
+      stopped = true;
+      void agent.abort();
+    };
     signal?.addEventListener("abort", abort, { once: true });
+    // A listener added to an already-aborted signal never fires: this child was stopped while it was being created.
+    if (signal?.aborted) stopped = true;
+    let finished = false;
     try {
       let answer = "";
       agent.on((event) => {
         if (event.type === "message" && event.role === "assistant") answer = event.text;
+        // The engine drops an abort that lands before its run is live, so a stopped child is stopped again there.
+        if (event.type === "turn_start" && stopped) void agent.abort();
       });
-      await agent.prompt(prompt);
-      await agent.waitForIdle();
-      this.#spent += agent.tokensUsed;
-      const ceiling = budget ? budget.budget : 0;
-      this.#options.onNotice?.(
-        `${kind} sub-agent finished, ${agent.tokensUsed} tokens (${this.#spent} of ${ceiling} spent)`,
-      );
+      if (!stopped) {
+        await agent.prompt(prompt);
+        await agent.waitForIdle();
+      }
+      finished = true;
       return answer.length > maxResultChars
         ? `${answer.slice(0, maxResultChars)}\n…(truncated)`
         : answer || "(no answer)";
     } finally {
       signal?.removeEventListener("abort", abort);
+      // Whatever the outcome: a failed or stopped child was billed too, and its own children are counted by its pool.
+      const tokens = agent.tokensUsed;
+      this.#spend.tokens += tokens;
+      const outcome = stopped ? "stopped" : finished ? "finished" : "failed";
+      const ceiling = budget ? budget.budget : 0;
+      this.#options.onNotice?.(
+        `${kind} sub-agent ${outcome}, ${tokens} tokens (${this.#spend.tokens} of ${ceiling} spent)`,
+      );
       agent.dispose();
     }
   }

package/codeAgent/agent/akanCodeModel.ts

@@ -1,10 +1,6 @@
 import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 
-/**
- * The engine's `Model` type lives in `@earendil-works/pi-ai` and is not re-exported from the package we depend
- * on, so it is recovered from the one public function that returns it rather than by adding a dependency on a
- * transitive package whose version we do not control.
- */
+// The engine's `Model` type (from `pi-ai`) is not re-exported, so it is recovered from `getModel`.
 export type CodeAgentModel = NonNullable<ReturnType<ModelRuntime["getModel"]>>;
 
 export interface CodeAgentModelRef {
@@ -15,18 +11,8 @@ export interface CodeAgentModelRef {
 /** DeepSeek's million-token window is what makes a 26k-token `AGENTS.md` affordable on every turn. */
 export const akanCodeDefaultModel: CodeAgentModelRef = { provider: "deepseek", id: "deepseek-flash" };
 
-/**
- * Models the catalogue declares text-only that take a picture anyway.
- *
- * `input` is the catalogue's claim, and a stale one is expensive in one direction only: with `image` missing
- * the `read` tool refuses to hand the model a picture and a paste is refused before it is ever sent, so
- * nothing ever finds out. Measured 2026-09-20 against the provider — `deepseek-v4-flash` answered "A red
- * star." to `apps/akan/public/icon-192x192.png` and "Red" to the colour, over two requests.
- *
- * ⚠️ `deepseek-v4-pro` is **not** on this list. It answers 200 to the same request and then says it cannot
- * view the image, which is not the same evidence, and guessing the family from one member is how the
- * catalogue got it wrong in the first place.
- */
+// Declared text-only by the catalogue, yet verified against the provider to see images.
+// `deepseek-v4-pro` is deliberately absent: it accepts an image and then says it cannot view it.
 const catalogueMissesImages = new Set(["deepseek/deepseek-v4-flash"]);
 
 const correctInputs = (model: CodeAgentModel | undefined) => {
@@ -35,13 +21,7 @@ const correctInputs = (model: CodeAgentModel | undefined) => {
   return { ...model, input: [...model.input, "image" as const] };
 };
 
-/**
- * Resolves the model to run with, preferring an explicit request, then the default, then anything the user has
- * credentials for.
- *
- * An empty API key produces a request that succeeds with no content rather than an error, so a provider with no
- * configured auth is skipped here instead of answering with nothing three seconds later.
- */
+// An empty API key yields a successful empty response rather than an error, so unauthorized providers are skipped.
 export const akanCodeModel = async (runtime: ModelRuntime, ref?: CodeAgentModelRef) => {
   if (ref) {
     const requested = runtime.getModel(ref.provider, ref.id);
@@ -55,23 +35,9 @@ export const akanCodeModel = async (runtime: ModelRuntime, ref?: CodeAgentModelR
   return correctInputs((await runtime.getAvailable())[0]);
 };
 
-/** A screenshot is worth attaching only to a model that can see it — after the catalogue has been corrected. */
 export const akanCodeModelSupportsImages = (model: CodeAgentModel | undefined) => !!model?.input.includes("image");
 
-/**
- * Says so when the chosen model's window is too small for the compaction policy to leave room for a
- * conversation.
- *
- * This is deliberately the **only** descriptor check. Two more obvious ones are wrong here: `maxTokens >=
- * contextWindow` matches 153 of the engine's own 1,057 catalogue entries (`gpt-4` is declared 8192/8192, and
- * several qwen models 262000/262000), and `reserveTokens > maxTokens` matches 145 — every model with a small
- * output cap, which is normal, because the reserve is context headroom and the cap is output length. Both
- * would cry wolf on one model in seven.
- *
- * ⚠️ **A wrong descriptor that is internally consistent cannot be detected here at all.** A custom model
- * declaring a 65k window for a provider that serves 1M is coherent and simply false, and the only thing that
- * catches it is a person seeing the number — which is why the session line prints it.
- */
+// Deliberately the only check: `maxTokens >= contextWindow` or `reserveTokens > maxTokens` flag 1 model in 7.
 export const akanCodeModelWarnings = (model: CodeAgentModel | undefined, compactionFloor: number) => {
   if (!model) return [];
   if (model.contextWindow >= compactionFloor) return [];

package/codeAgent/agent/akanCodePaths.ts

@@ -2,30 +2,16 @@ import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 
-/**
- * Where the shipped akan skills sit, which differs between the source tree and the bundle: the CLI's entry
- * chunks are flattened into the package root, so `skills/` is a sibling of the caller there and one level up
- * here, beside this folder. Same two-candidate shape the guidelines lookup uses.
- */
+// Two candidates: the CLI bundle flattens entry chunks into the package root, where `skills/` is a sibling.
 const builtinSkillsDir = () => {
   const candidates = [path.join(import.meta.dir, "skills"), path.join(import.meta.dir, "..", "skills")];
   return candidates.find((candidate) => existsSync(candidate));
 };
 
-/**
- * Where `akan code` keeps what belongs to the person rather than to the repo.
- *
- * `AKAN_CODE_HOME` moves the whole set. A container that mounts no home directory, a CI job that must not
- * write to one, and a second checkout that wants its own credentials all need the same thing, and moving the
- * files apart would let a `models.json` and the `auth.json` it names drift into different directories.
- */
+// One override for the whole set, so a `models.json` and the `auth.json` it names never drift apart.
 const globalDir = () => process.env.AKAN_CODE_HOME ?? path.join(homedir(), ".akan", "code");
 
-/**
- * Sessions live in the workspace — they are project history, and a second checkout of the same repo is a
- * different project. Credentials live in the home directory instead: a repo directory is the one place a key
- * must never be, because it is the place that gets committed, zipped and shared.
- */
+// Credentials live under the home directory, never the repo: a repo is what gets committed, zipped and shared.
 export const akanCodePaths = {
   workspaceDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code"),
   sessionsDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "sessions"),
@@ -34,13 +20,7 @@ export const akanCodePaths = {
   mailDir: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mail"),
   builtinSkillsDir,
   mcpFile: (workspaceRoot: string) => path.join(workspaceRoot, ".akan", "code", "mcp.json"),
-  /**
-   * The MCP servers that belong to the person rather than to one checkout.
-   *
-   * A server is an integration with an account — the credential for it is already global, in `mcpAuth.json` —
-   * so declaring it per repo means declaring it again in every repo and signing in again in each. The
-   * workspace file stays, for a server that is genuinely this repo's, and wins on a name they share.
-   */
+  /** Person-wide MCP servers; the workspace `mcpFile` wins on a name they share. */
   globalMcpFile: () => path.join(globalDir(), "mcp.json"),
   globalSkillsDir: () => path.join(globalDir(), "skills"),
   globalDir,

package/codeAgent/agent/akanContextFiles.test.ts

@@ -17,7 +17,6 @@ const workspace = (files: Record<string, string>) => {
   return root;
 };
 
-/** What the engine hands over: the one context file it took for that directory. */
 const loaded = (root: string, name = "AGENTS.md"): AkanContextFile[] => [
   { path: path.join(root, name), content: "the workspace guide" },
 ];
@@ -60,7 +59,6 @@ describe("workspace context files", () => {
     expect(files[1]?.content).toBe("never use any\n");
   });
 
-  /** Cursor's other three kinds are conditional; applying one always is applying a rule its author scoped. */
   test("a scoped cursor rule is left to cursor", () => {
     const root = workspace({
       ".cursor/rules/ui.mdc": "---\nglobs: ui/**/*.tsx\n---\nno inline colours\n",

package/codeAgent/agent/akanSystemPrompt.ts

@@ -1,12 +1,6 @@
 import type { CodeAgentProfile } from "akanjs/common";
 
-/**
- * What the agent has to know that `AGENTS.md` does not say.
- *
- * The workspace guide is already loaded whole — 104KB, roughly 26k tokens, on every turn — so this stays short
- * and carries only what is about *this* runtime: which tools exist, what the profile refuses, and the one rule
- * the guide states for editors but not for an agent that can run commands itself.
- */
+// Only what `AGENTS.md` does not say: the guide is already loaded whole on every turn.
 export const akanSystemPrompt = (profile: CodeAgentProfile) => {
   const lines = [
     "You are the akan coding agent, running inside an Akan.js workspace.",
@@ -40,8 +34,6 @@ export const akanSystemPrompt = (profile: CodeAgentProfile) => {
   lines.push(
     "- Secrets are refused at the tool boundary. If you need a value from `.env`, ask the user for it rather than looking for another way to read the file.",
     "",
-    // The answer lands in a terminal pane, not a document: a preamble scrolls the thing being read off the
-    // screen, and a summary of tool calls repeats rows the host already drew above the answer.
     "## How to answer",
     "",
     "- Answer in as few words as carry the answer. A short question gets one sentence with no heading.",

package/codeAgent/agent/codeAgent.test.ts

@@ -0,0 +1,178 @@
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type CodeAgentEvent, type CodeAgentProfile, codeAgentPresets } from "akanjs/common";
+import { WorkspaceExecutor } from "../../executors";
+import { isolateEnv, tempDirs } from "../../testHelpers";
+import { AkanCodePlugins } from "../tools/AkanCodePlugins";
+import { akanCodeDefaultModel } from "./akanCodeModel";
+import { akanCodePaths } from "./akanCodePaths";
+import { CodeAgent, type CodeAgentOptions } from "./CodeAgent";
+import { CodeAgentSuspended } from "./CodeAgentSuspended";
+import { SubagentPool } from "./SubagentPool";
+
+isolateEnv();
+const makeTempRoot = tempDirs("akan-code-agent-");
+
+const chunk = (delta: object, finish: string | null = null) =>
+  `data: ${JSON.stringify({
+    id: "c1",
+    object: "chat.completion.chunk",
+    created: 0,
+    model: akanCodeDefaultModel.id,
+    choices: [{ index: 0, delta, finish_reason: finish }],
+  })}\n\n`;
+
+let llm: ReturnType<typeof Bun.serve>;
+let llmCalls = 0;
+beforeAll(() => {
+  llm = Bun.serve({
+    port: 0,
+    fetch: () => {
+      llmCalls += 1;
+      return new Response(`${chunk({ role: "assistant", content: "ok" })}${chunk({}, "stop")}data: [DONE]\n\n`, {
+        headers: { "content-type": "text/event-stream" },
+      });
+    },
+  });
+});
+afterAll(() => llm.stop(true));
+
+const useProxy = (root: string) => {
+  process.env.AKAN_CODE_HOME = path.join(root, "home");
+  process.env.AKAN_CODE_PROXY_URL = `http://127.0.0.1:${llm.port}/llm/{provider}/v1`;
+  process.env.AKAN_CODE_PROXY_TOKEN = "test-token";
+};
+
+const quietProfile = (root: string): CodeAgentProfile => {
+  const web = codeAgentPresets.web(root);
+  return {
+    ...web,
+    tools: { builtin: [], akan: false, mcp: "off", subagent: false, web: { fetch: false, search: false } },
+    context: { projectFiles: false, skills: false },
+  };
+};
+
+const createAgent = async (root: string, options: Partial<CodeAgentOptions> = {}) => {
+  useProxy(root);
+  return await CodeAgent.create({
+    workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+    profile: quietProfile(root),
+    ...options,
+  });
+};
+
+describe("CodeAgent", () => {
+  test("a prompt typed instead of an answer drops the parked asks", async () => {
+    const root = await makeTempRoot();
+    const agent = await createAgent(root);
+    try {
+      await agent.ask({ prompt: "Which app?", kind: "select", options: [{ key: "a", label: "akan" }] });
+      const suspendedFile = CodeAgentSuspended.fileOf(akanCodePaths.sessionsDir(root), agent.sessionId) ?? "";
+      expect(existsSync(suspendedFile)).toBe(true);
+
+      await agent.prompt("Do something else instead.");
+
+      const events: CodeAgentEvent[] = [];
+      agent.on((event) => events.push(event));
+      agent.announce();
+      expect(events.filter((event) => event.type === "question")).toEqual([]);
+      expect(existsSync(suspendedFile)).toBe(false);
+    } finally {
+      agent.dispose();
+    }
+  });
+
+  test("a sub-agent hands its plugins the token tally of the tree that opened it", async () => {
+    const root = await makeTempRoot();
+    const build = AkanCodePlugins.build;
+    const seen: unknown[] = [];
+    const spy = spyOn(AkanCodePlugins, "build").mockImplementation(async (options) => {
+      seen.push(options.subagentSpend);
+      return await build.call(AkanCodePlugins, options);
+    });
+    const subagentSpend = { tokens: 7, running: 0 };
+    try {
+      const agent = await createAgent(root, { subagentSpend, depth: 1 });
+      agent.dispose();
+      expect(seen).toHaveLength(1);
+      expect(seen[0]).toBe(subagentSpend);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});
+
+describe("a sub-agent its parent stops before the sub-agent's run is live", () => {
+  type ToolExecute = (
+    id: string,
+    params: never,
+    signal?: AbortSignal,
+  ) => Promise<{ content: { text: string }[] } | undefined>;
+
+  const runTask = async (root: string, parent: AbortController, notices: string[]) => {
+    useProxy(root);
+    const profile = quietProfile(root);
+    const pool = SubagentPool.extensionFor({
+      workspace: new WorkspaceExecutor({ workspaceRoot: root, repoName: "repo" }),
+      cwd: root,
+      parent: { ...profile, tools: { ...profile.tools, subagent: { maxDepth: 2, maxConcurrent: 3, budget: 1_000 } } },
+      depth: 0,
+      onNotice: (message) => notices.push(message),
+    });
+    let execute: ToolExecute | undefined;
+    if (pool && "factory" in pool)
+      pool.factory({
+        registerTool: (tool: { execute: ToolExecute }) => {
+          execute = tool.execute;
+        },
+      } as never);
+    const result = await execute?.("c1", { description: "d", prompt: "p" } as never, parent.signal);
+    return result?.content[0]?.text;
+  };
+
+  test("stopped while it is being created, it never reaches the model and says it stopped", async () => {
+    const root = await makeTempRoot();
+    const parent = new AbortController();
+    const create = CodeAgent.create;
+    const spy = spyOn(CodeAgent, "create").mockImplementation(async (options) => {
+      const agent = await create.call(CodeAgent, options);
+      parent.abort();
+      return agent;
+    });
+    const notices: string[] = [];
+    try {
+      const calls = llmCalls;
+      expect(await runTask(root, parent, notices)).toBe("(no answer)");
+      expect(llmCalls).toBe(calls);
+      expect(notices.at(-1)).toBe("explore sub-agent stopped, 0 tokens (0 of 1000 spent)");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("stopped after it exists but before its run is live, it is stopped as soon as the run starts", async () => {
+    const root = await makeTempRoot();
+    const parent = new AbortController();
+    const stopBeforeTheRun: InlineExtension = {
+      name: "stop-before-the-run",
+      factory: (pi: ExtensionAPI) => {
+        pi.on("before_agent_start", () => {
+          parent.abort();
+        });
+      },
+    };
+    const create = CodeAgent.create;
+    const spy = spyOn(CodeAgent, "create").mockImplementation(
+      async (options) => await create.call(CodeAgent, { ...options, extensions: [stopBeforeTheRun] }),
+    );
+    const notices: string[] = [];
+    try {
+      expect(await runTask(root, parent, notices)).toBe("(no answer)");
+      expect(notices.at(-1)).toMatch(/^explore sub-agent stopped, /);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/codeAgent/agent/codeAgentContract.test.ts

@@ -34,6 +34,8 @@ class FakeTransport implements CodeAgentTransport {
 }
 
 const event = (seq: number, body: Partial<CodeAgentEvent> = {}) => ({ type: "idle", seq, ...body }) as CodeAgentEvent;
+const start = { type: "agent_start" } as never;
+const finished = (stopReason: string) => ({ type: "agent_end", messages: [{ stopReason }], willRetry: false }) as never;
 
 describe("CodeAgentClient", () => {
   test("correlates a reply with the command that asked for it", async () => {
@@ -207,8 +209,6 @@ describe("CodeAgentAsks", () => {
 });
 
 describe("CodeAgentEventMapper", () => {
-  const start = { type: "agent_start" } as never;
-
   test("a run becomes one turn, not one turn per round trip", () => {
     const mapper = new CodeAgentEventMapper();
     expect(mapper.map(start)).toEqual([{ type: "turn_start", turnId: "t1" }]);
@@ -231,10 +231,6 @@ describe("CodeAgentEventMapper", () => {
     expect(think).toEqual([{ type: "thinking_delta", turnId: "t1", text: "hmm" }]);
   });
 
-  /**
-   * `String({})` is `"[object Object]"`, and an `edit` call's argument is an array of them — so a row that
-   * should read "three replacements" read as two identical placeholders instead.
-   */
   test("a structured argument is described by its shape, not stringified", () => {
     const mapper = new CodeAgentEventMapper();
     mapper.map(start);
@@ -248,7 +244,6 @@ describe("CodeAgentEventMapper", () => {
     expect(title).not.toContain("[object Object]");
     expect(title).toContain("edits=2 items");
     expect(title).toContain("options={1 key}");
-    // A path still reads as itself: it is the one argument worth showing verbatim.
     expect(title).toContain("path=/repo/a.ts");
   });
 
@@ -289,8 +284,7 @@ describe("CodeAgentEventMapper", () => {
   test("reports an aborted run as aborted rather than done", () => {
     const mapper = new CodeAgentEventMapper();
     mapper.map(start);
-    const frames = mapper.map({ type: "agent_end", messages: [{ stopReason: "aborted" }], willRetry: false } as never);
-    expect(frames).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "aborted" }]);
+    expect(mapper.map(finished("aborted"))).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "aborted" }]);
   });
 
   test("a compaction that failed or was cancelled carries that, not just its reason", () => {
@@ -435,10 +429,6 @@ describe("codeAgentShouldPersist", () => {
 });
 
 describe("turn outcome", () => {
-  const start = { type: "agent_start" } as never;
-  const finished = (stopReason: string) =>
-    ({ type: "agent_end", messages: [{ stopReason }], willRetry: false }) as never;
-
   test("an abort is reported even though the engine calls it a normal stop", () => {
     const mapper = new CodeAgentEventMapper();
     mapper.map(start);
@@ -477,25 +467,17 @@ describe("turn outcome", () => {
 });
 
 describe("truncation", () => {
-  const start = { type: "agent_start" } as never;
-
   test("the engine's `length` is a partial success, not a completed turn", () => {
     const mapper = new CodeAgentEventMapper();
     mapper.map(start);
-    const frames = mapper.map({
-      type: "agent_end",
-      messages: [{ stopReason: "length" }],
-      willRetry: false,
-    } as never);
-    expect(frames).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "truncated" }]);
+    expect(mapper.map(finished("length"))).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "truncated" }]);
   });
 
   test("an abort still wins over the engine's report", () => {
     const mapper = new CodeAgentEventMapper();
     mapper.map(start);
     mapper.noteOutcome("aborted");
-    const frames = mapper.map({ type: "agent_end", messages: [{ stopReason: "length" }], willRetry: false } as never);
-    expect(frames).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "aborted" }]);
+    expect(mapper.map(finished("length"))).toEqual([{ type: "turn_end", turnId: "t1", stopReason: "aborted" }]);
   });
 
   test("the terminal says so, because a cut answer looks like a finished one", () => {
@@ -526,17 +508,12 @@ describe("akanCodeModelWarnings", () => {
 });
 
 describe("wire coverage", () => {
-  /**
-   * The audit that found `context` declared, rendered, and never emitted. A contract entry with no producer
-   * costs every host a branch for a frame that cannot arrive.
-   */
   test("every event type either has a producer in the core or is documented as host-supplied", async () => {
     const dir = import.meta.dir;
     const sources = await Promise.all(
       ["CodeAgent.ts", "CodeAgentEventMapper.ts"].map(async (file) => await Bun.file(`${dir}/${file}`).text()),
     );
     const core = sources.join("\n");
-    // `host` is the one frame the core never makes: it is the slot a host fills with its own vocabulary.
     const hostSupplied = new Set(["host"]);
     const missing = Object.keys(codeAgentEventPersistence).filter(
       (type) => !hostSupplied.has(type) && !core.includes(`type: "${type}"`),