pi-gauntlet 8.4.3 → 8.4.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v8.4.5 - 2026-11-08
+
+- Guard, ship-verification, and post-ship spec warnings preserve tool `structuredContent`; nested-call warnings reach the parent codemode result once without changing the child's value or re-arming warn-once guards. (#133)
+
+## v8.4.4 - 2026-11-08
+
+- Block scripted `subagent` dispatches in every entered gauntlet phase and exclude nested results from closure latch, fix-round counter, and cadence updates. Use direct tool calls instead; disable with `closureReview.enforce: false`. The configuration guide documents codemode `on` support with direct-only dispatch, why `only` is unsupported in an entered flow, and how to read literal skill dispatch examples (#132, #134).
+- Dev dependencies move to current: `@anthropic-ai/claude-code` 2.1.319 (the Claude Code loading smoke runs against it) and `typebox` ^1.4.6 (the pi 1.5.0 host serves 1.3.27 at runtime; both validate the extension schemas identically).
+
 ## v8.4.3 - 2026-11-08
 
 - Telemetry publishes and reads `refs/telemetry/records` outside branch namespaces. The migration guide orders machine upgrades, repeatable record carry with `--migrate-branch`, verified remote retirement with `--retire-branch`, local cleanup and removal of the old CI exclusion. (#130)

package/README.md

@@ -142,7 +142,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) >= 1.5.0 - supports model-only tracker exposure and sequential tracker execution, so updates persist as transcript tool results rather than nested calls.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.6.7 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.6.8 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 

package/extensions/lib/tool-result-warnings.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createPendingWarnings, prependWarning } from "./tool-result-warnings.ts";
+import { mergeToolResult } from "../test-support/merge-tool-result.mjs";
+
+for (const [name, toolName, structuredContent] of [
+  ["bash payload", "bash", { output: "ok", exit_code: 0 }],
+  ["write null", "write", null],
+  ["edit false", "edit", false],
+  ["zero", "codemode", 0],
+  ["empty string", "read", ""],
+  ["absent", "read", undefined],
+] as const) {
+  test(`prependWarning preserves the runner-merged result (${name})`, () => {
+    const event = {
+      toolName, toolCallId: "c1", input: {}, isError: true,
+      ...(structuredContent !== undefined ? { structuredContent } : {}),
+      content: [{ type: "text", text: "original" }, { type: "image", data: "AA==", mimeType: "image/png" }],
+      details: { sentinel: "details" }, usage: { sentinel: "usage" },
+    };
+    const original = structuredClone(event);
+    const ret = prependWarning(event as any, "warning");
+    assert.deepEqual(ret, { content: [{ type: "text", text: "warning" }, ...event.content], structuredContent });
+    assert.deepEqual(mergeToolResult(event, ret), { ...event, content: ret.content });
+    assert.deepEqual(event, original);
+  });
+}
+
+test("nested warning re-keys without changing the child or the fired latch, then delivers once", () => {
+  const store = createPendingWarnings();
+  const firedGuards = new Map([["guard", true]]);
+  const child = {
+    toolName: "bash", toolCallId: "c1/0", parentToolCallId: "c1", input: {}, isError: false,
+    content: [{ type: "text", text: "ok" }], structuredContent: { output: "ok", exit_code: 0 },
+  };
+  const original = structuredClone(child);
+  store.add(child.toolCallId, "warning");
+  const ret = store.deliver(child as any, store.take(child.toolCallId)!);
+  assert.equal(ret, undefined);
+  assert.deepEqual(mergeToolResult(child, ret), original);
+  assert.deepEqual(child, original);
+  assert.equal(firedGuards.get("guard"), true);
+  assert.equal(store.take(child.toolCallId), undefined);
+
+  const parent = { ...child, toolName: "codemode", toolCallId: "c1", parentToolCallId: undefined, structuredContent: { value: 0 } };
+  const text = store.take(parent.toolCallId)!;
+  assert.equal(text, "warning");
+  const delivered = store.deliver(parent as any, text)!;
+  assert.deepEqual(mergeToolResult(parent, delivered), { ...parent, content: [{ type: "text", text }, ...parent.content] });
+  assert.equal(store.take(parent.toolCallId), undefined);
+});
+
+test("two nested guards reach one parent once in arrival order", () => {
+  const store = createPendingWarnings();
+  for (const [id, text] of [["c1/0", "first guard"], ["c1/1", "second guard"]]) {
+    store.add(id, text);
+    assert.equal(store.deliver({ toolCallId: id, parentToolCallId: "c1" } as any, store.take(id)!), undefined);
+    assert.equal(store.take(id), undefined);
+  }
+  const parent = { toolName: "codemode", toolCallId: "c1", isError: false, content: [], structuredContent: null };
+  const ret = store.deliver(parent as any, store.take("c1")!)!;
+  const merged = mergeToolResult(parent, ret);
+  assert.deepEqual(merged.content, [{ type: "text", text: "first guard\n\nsecond guard" }]);
+  assert.deepEqual(merged.structuredContent, parent.structuredContent);
+  assert.equal(store.take("c1"), undefined);
+});
+
+test("depth-two nesting re-keys c1/0/2 -> c1/0 -> c1", () => {
+  const store = createPendingWarnings();
+  store.add("c1/0/2", "warning");
+  for (const [toolCallId, parentToolCallId] of [["c1/0/2", "c1/0"], ["c1/0", "c1"]]) {
+    const event = { toolName: "codemode", toolCallId, parentToolCallId, content: [], structuredContent: { value: 0 } };
+    const ret = store.deliver(event as any, store.take(toolCallId)!);
+    assert.equal(ret, undefined);
+    assert.deepEqual(mergeToolResult(event, ret), event);
+    assert.equal(store.take(toolCallId), undefined);
+  }
+  const parent = { toolCallId: "c1", content: [], structuredContent: { value: 0 } };
+  const ret = store.deliver(parent as any, store.take("c1")!);
+  const merged = mergeToolResult(parent, ret);
+  assert.deepEqual(merged.content, [{ type: "text", text: "warning" }]);
+  assert.deepEqual(merged.structuredContent, parent.structuredContent);
+  assert.equal(store.take("c1"), undefined);
+});
+
+test("warning delivery tolerates missing content and preserves structuredContent", () => {
+  const store = createPendingWarnings();
+  const event = { toolName: "bash", toolCallId: "c1", isError: false, structuredContent: { output: "ok", exit_code: 0 } };
+  store.add(event.toolCallId, "warning");
+  const ret = store.deliver(event as any, store.take(event.toolCallId)!);
+  assert.deepEqual(mergeToolResult(event, ret), { ...event, content: [{ type: "text", text: "warning" }] });
+  assert.equal(store.take(event.toolCallId), undefined);
+});
+
+test("add concatenates warnings and clear discards all entries", () => {
+  const store = createPendingWarnings();
+  store.add("c1", "first");
+  store.add("c1", "second");
+  assert.equal(store.take("c1"), "first\n\nsecond");
+  store.add("c1", "pending");
+  store.add("c2", "another");
+  store.clear();
+  assert.equal(store.take("c1"), undefined);
+  assert.equal(store.take("c2"), undefined);
+});

package/extensions/lib/tool-result-warnings.ts

@@ -0,0 +1,35 @@
+import type { ToolResultEvent, ToolResultEventResult } from "@earendil-works/pi-coding-agent";
+
+export function prependWarning(event: ToolResultEvent, text: string): ToolResultEventResult {
+  return {
+    content: [{ type: "text", text }, ...(event.content ?? [])],
+    // Pi drops structuredContent when a content replacement omits it.
+    structuredContent: event.structuredContent,
+  };
+}
+
+export function createPendingWarnings() {
+  const pending = new Map<string, string>();
+  const add = (id: string, text: string) => {
+    const prior = pending.get(id);
+    pending.set(id, prior ? `${prior}\n\n${text}` : text);
+  };
+  return {
+    add,
+    take(id: string): string | undefined {
+      const text = pending.get(id);
+      pending.delete(id);
+      return text;
+    },
+    deliver(event: ToolResultEvent, text: string): ToolResultEventResult | undefined {
+      if (event.parentToolCallId) {
+        add(event.parentToolCallId, text);
+        return undefined;
+      }
+      return prependWarning(event, text);
+    },
+    clear() {
+      pending.clear();
+    },
+  };
+}

package/extensions/phase-tracker.test.ts

@@ -9,6 +9,7 @@ import { tmpdir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import registerPhaseTracker from "./phase-tracker.ts";
 import registerPlanTracker from "./plan-tracker.ts";
+import { mergeToolResult } from "./test-support/merge-tool-result.mjs";
 
 const originalSubagentDepth = process.env.PI_SUBAGENT_DEPTH;
 process.env.PI_SUBAGENT_DEPTH = "0";
@@ -391,19 +392,105 @@ test("implement-write guard: silent when unarmed, when enforce is false, and in
   }
 });
 
-test("brainstorm write guard is unchanged by the implement guard", async () => {
-  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
-  delete process.env.PI_SUBAGENT_DEPTH;
-  try {
-    const h = harness({ cwd: tempCwd(), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
-    await h.emit("session_start");
-    await h.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
-    const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] };
-    assert.match(warned.content[0].text, /brainstorm/);
-  } finally {
-    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+for (const toolName of ["bash", "write", "edit"]) {
+  for (const nested of [false, true]) {
+    test(`brainstorm ${toolName} warning preserves results (${nested ? "nested" : "direct"}) and stays fired`, async () => {
+      const h = harness({ branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+      await h.emit("session_start");
+      const toolCallId = nested ? "parent/0" : "direct";
+      const nesting = nested ? { parentToolCallId: "parent" } : {};
+      const call = {
+        toolName, toolCallId, ...nesting,
+        input: toolName === "bash" ? { command: "echo x > src/a.ts" } : { path: "src/a.ts" },
+      };
+      await h.emitEvent("tool_call", call);
+      const event = {
+        ...writeResult(toolCallId), toolName, ...nesting, isError: true,
+        details: { sentinel: "guard details" }, usage: { sentinel: "guard usage" },
+        structuredContent: toolName === "bash" ? { output: "ok", exit_code: 0 } : toolName === "write" ? null : { edited: true },
+      };
+      const original = structuredClone(event);
+      const [ret] = await h.emitEvent("tool_result", event);
+      let delivered = event;
+      let merged = mergeToolResult(event, ret);
+      if (nested) {
+        assert.equal(ret, undefined);
+        assert.deepEqual(merged, original);
+        const parent = {
+          ...event, toolName: "codemode", toolCallId: "parent", parentToolCallId: undefined,
+          content: [{ type: "text", text: "script value: 0" }], structuredContent: { value: 0 },
+        };
+        delivered = parent;
+        const [parentRet] = await h.emitEvent("tool_result", parent);
+        merged = mergeToolResult(parent, parentRet);
+      }
+      assert.deepEqual(event, original);
+      assert.match(merged.content[0].text, /Writing outside the spec directory/);
+      assert.equal(merged.content[0].text.split("Writing outside the spec directory").length - 1, 1);
+      assert.deepEqual(merged, { ...delivered, content: [merged.content[0], ...delivered.content] });
+      assert.equal((await h.emitEvent("tool_result", delivered))[0], undefined);
+      await h.emitEvent("tool_call", writeCall("later", "src/b.ts"));
+      assert.equal((await h.emitEvent("tool_result", writeResult("later")))[0], undefined);
+    });
   }
-});
+}
+
+for (const toolName of ["bash", "write", "edit"]) {
+  for (const nested of [false, true]) {
+    test(`implement-write and cadence warnings preserve ${toolName} results (${nested ? "nested" : "direct"})`, async () => {
+      const h = harness({ branch: implementBranch([subagentResult(["implementer"])]) });
+      await h.emit("session_start");
+      const nesting = nested ? { parentToolCallId: "parent" } : {};
+      const write = { ...writeCall("write", "src/a.ts"), toolName: toolName === "edit" ? "edit" : "write" };
+      for (const [index, call] of [write, commitCall("commit")].entries()) {
+        const toolCallId = nested ? `parent/${index}` : call.toolCallId;
+        await h.emitEvent("tool_call", { ...call, toolCallId, ...nesting });
+        // Deferred cadence delivery is keyed by call ID, not the result's tool name.
+        const event = { ...writeResult(toolCallId), toolName: index === 0 ? write.toolName : toolName, ...nesting, structuredContent: { exit_code: 0 } };
+        const [ret] = await h.emitEvent("tool_result", event);
+        if (nested) {
+          assert.equal(ret, undefined);
+          assert.deepEqual(mergeToolResult(event, ret), event);
+        } else {
+          const merged = mergeToolResult(event, ret);
+          assert.match(merged.content[0].text, index === 0 ? /Parent write/ : /no wave-reviewer observed/);
+          assert.deepEqual(merged, { ...event, content: [merged.content[0], ...event.content] });
+        }
+      }
+      if (nested) {
+        const parent = { ...commitResult("parent"), toolName: "codemode", structuredContent: { value: "done" } };
+        const [ret] = await h.emitEvent("tool_result", parent);
+        const merged = mergeToolResult(parent, ret);
+        assert.match(merged.content[0].text, /Parent write[\s\S]*no wave-reviewer observed/);
+        assert.equal(merged.content[0].text.split("Parent write").length - 1, 1);
+        assert.equal(merged.content[0].text.split("no wave-reviewer observed").length - 1, 1);
+        assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] });
+        assert.equal((await h.emitEvent("tool_result", parent))[0], undefined);
+      }
+      await h.emitEvent("tool_call", writeCall("later", "src/b.ts"));
+      assert.equal((await h.emitEvent("tool_result", writeResult("later")))[0], undefined);
+    });
+  }
+}
+
+for (const transition of ["reset", "session_start"]) {
+  test(`${transition} clears a deferred nested guard warning before the parent result`, async () => {
+    const h = harness({ branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", { ...writeCall("parent/0", "src/a.ts"), parentToolCallId: "parent" });
+    assert.equal((await h.emitEvent("tool_result", { ...writeResult("parent/0"), parentToolCallId: "parent" }))[0], undefined);
+    if (transition === "reset") {
+      const tool = h.tools.find((t) => t.name === "phase_tracker")!;
+      await tool.execute("reset", { action: "reset" }, undefined, undefined, h.ctx);
+    } else {
+      await h.emit("session_start");
+    }
+    const parent = { ...writeResult("parent"), toolName: "codemode", structuredContent: { value: 0 } };
+    const [ret] = await h.emitEvent("tool_result", parent);
+    assert.equal(ret, undefined);
+    assert.deepEqual(mergeToolResult(parent, ret), parent);
+  });
+}
 
 test("brainstorm write confinement: a docs/specs write under the default dirs does not warn", async () => {
   const priorDepth = process.env.PI_SUBAGENT_DEPTH;
@@ -1551,6 +1638,153 @@ const implementerWave = (n = 1, agent = "implementer") => ({
 const firstCallResult = async (h: ReturnType<typeof harness>, id: string, input: unknown) =>
   (await h.emitEvent("tool_call", subagentCall(id, input)))[0] as { block?: boolean; reason?: string } | undefined;
 
+const nestedCall = (id: string, input: unknown) => ({ ...subagentCall(id, input), parentToolCallId: "script" });
+
+for (const phase of PHASES) {
+  test(`nested dispatch: blocked in ${phase}; reason names direct call, only-mode, and the switches`, async () => {
+    const h = harness({ hasUI: true, branch: enteredBranch(phases({ [phase]: "in_progress" })) });
+    await h.emit("session_start");
+    const widget = h.widgets.at(-1);
+    for (const [i, input] of [loneImplementer(), implementerWave(), { agent: "conformance-reviewer" }].entries()) {
+      const [blocked] = await h.emitEvent("tool_call", nestedCall(`script/${i}`, input)) as { block: boolean; reason: string }[];
+      assert.equal(blocked?.block, true);
+      assert.match(blocked.reason, /call subagent as a direct tool call/i);
+      assert.match(blocked.reason, /codemode only mode is unsupported while a gauntlet flow is entered/);
+      assert.match(blocked.reason, /codemode\.mode: on/);
+      assert.match(blocked.reason, /piGauntlet\.closureReview\.enforce: false/);
+      assert.equal(h.widgets.at(-1), widget);
+    }
+    assert.equal(await firstCallResult(h, "direct", { agent: "conformance-reviewer" }), undefined);
+    assert.ok(h.widgets.at(-1)!.includes(`${phase}(conformance)`));
+    assert.doesNotMatch(h.widgets.at(-1)!, /#2/);
+  });
+}
+
+const blockedNestedDispatchFixture = async (malformed = false) => {
+  const cwd = tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 5 } } });
+  const h = harness({ hasUI: true, cwd, branch: verifyBranch([
+    subagentResult(["conformance-reviewer"]),
+    subagentResult(["wave-reviewer"]),
+    ...Array.from({ length: 5 }, () => subagentResult(["implementer"])),
+  ]) });
+  await h.emit("session_start");
+  const before = await firstCallResult(h, "cap-before", implementerWave());
+  assert.equal(before?.block, true);
+  assert.match(before?.reason ?? "", /5 fix round\(s\) used against a cap of 5/);
+  if (malformed) writeFileSync(join(cwd, ".pi/settings.json"), "{");
+  const widget = h.widgets.at(-1);
+  const [blocked] = await h.emitEvent("tool_call", nestedCall("script/1", implementerWave())) as { block: boolean; reason: string }[];
+  assert.equal(blocked?.block, true);
+  assert.match(blocked.reason, /call subagent as a direct tool call/i);
+  assert.equal(h.widgets.at(-1), widget);
+  return { cwd, h, before, widget };
+};
+
+const assertBlockedNestedStateUntouched = async ({ cwd, h, before, widget }: Awaited<ReturnType<typeof blockedNestedDispatchFixture>>) => {
+  assert.equal(h.widgets.at(-1), widget);
+  assert.deepEqual(await firstCallResult(h, "cap-after", implementerWave()), before);
+  const tool = h.tools.find(t => t.name === "phase_tracker")!;
+  const status = await tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+  assert.equal(status.details.phases.verify.substep, undefined);
+  assert.equal((await completePhase(h, "verify")).details.error, undefined);
+
+  // Re-enter implement without replay so the commit guard observes the live cadence.
+  writeFileSync(join(cwd, ".pi/settings.json"), JSON.stringify({ piGauntlet: { flowGuards: { enforce: false } } }));
+  const started = await tool.execute("restart", { action: "start", phase: "implement", force: true }, undefined, undefined, h.ctx) as any;
+  assert.equal(started.details.error, undefined);
+  writeFileSync(join(cwd, ".pi/settings.json"), "{}");
+  await h.emitEvent("tool_call", commitCall("commit"));
+  const [warning] = await h.emitEvent("tool_result", commitResult("commit")) as { content: { text: string }[] }[];
+  assert.match(warning.content[0].text, /no wave-reviewer observed since the last implementer/);
+  assert.equal(await firstCallResult(h, "direct", { agent: "wave-reviewer" }), undefined);
+  assert.match(h.widgets.at(-1)!, /implement\(wave-review\)/);
+  assert.deepEqual(await h.emitEvent("tool_result", waveResult("direct", [{ agent: "wave-reviewer", exitCode: 0 }])), [undefined]);
+  assert.doesNotMatch(h.widgets.at(-1)!, /implement\(/);
+};
+
+for (const malformed of [false, true]) {
+  test(`nested dispatch: latch, counter, cadence, and liveDispatch unchanged after a block; malformed=${malformed}`, async () => {
+    await assertBlockedNestedStateUntouched(await blockedNestedDispatchFixture(malformed));
+  });
+}
+
+for (const isError of [true, false]) {
+  test(`nested result: replay-mirrored state untouched; isError=${isError}`, async () => {
+    const fixture = await blockedNestedDispatchFixture();
+    await fixture.h.emitEvent("tool_result", {
+      ...waveResult("script/1", [
+        { agent: "conformance-reviewer", exitCode: 0 },
+        { agent: "implementer", exitCode: 0 },
+        { agent: "wave-reviewer", exitCode: 0 },
+      ], isError),
+      parentToolCallId: "script",
+    });
+    await assertBlockedNestedStateUntouched(fixture);
+  });
+}
+
+for (const entered of [false, true]) {
+  test(`nested dispatch: child follows replayed flow entry=${entered}`, async () => {
+    const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+    let h: ReturnType<typeof harness>;
+    try {
+      process.env.PI_SUBAGENT_DEPTH = "1";
+      h = harness({ branch: entered ? verifyBranch() : [] });
+    } finally {
+      if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+      else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+    }
+    await h.emit("session_fork");
+    const [result] = await h.emitEvent("tool_call", nestedCall("script/1", loneImplementer())) as ({ block?: boolean } | undefined)[];
+    assert.equal(result?.block, entered ? true : undefined);
+  });
+}
+
+test("nested dispatch: allowed without flow entry", async () => {
+  const h = harness({ cwd: tempCwd() });
+  await h.emit("session_start");
+  assert.deepEqual(await h.emitEvent("tool_call", nestedCall("script/1", implementerWave())), [undefined]);
+});
+
+for (const malformed of [false, true]) {
+  test(`nested dispatch: management passes and its parent consumes queued warnings; malformed=${malformed}`, async () => {
+    const cwd = tempCwd({});
+    if (malformed) writeFileSync(join(cwd, ".pi/settings.json"), "{");
+    const h = harness({ cwd, branch: verifyBranch() });
+    await h.emit("session_start");
+    assert.deepEqual(await h.emitEvent("tool_call", nestedCall("script/status", { action: "status" })), [undefined]);
+    const content = [{ type: "text", text: "status result" }];
+    const result = { ...waveResult("script/status", []), parentToolCallId: "script", content };
+    const original = structuredClone(result);
+    const [ret] = await h.emitEvent("tool_result", result);
+    assert.equal(ret, undefined);
+    assert.deepEqual(result, original);
+    assert.deepEqual(mergeToolResult(result, ret), original);
+    assert.deepEqual(await h.emitEvent("tool_result", result), [undefined]);
+    const parent = {
+      ...result, toolName: "codemode", toolCallId: "script", parentToolCallId: undefined,
+      content: [{ type: "text", text: "script status result" }], structuredContent: { value: "status" },
+    };
+    const [warning] = await h.emitEvent("tool_result", parent);
+    assert.equal(warning !== undefined, malformed);
+    const merged = mergeToolResult(parent, warning);
+    if (malformed) {
+      assert.match(merged.content[0].text, /gauntlet settings load error \(using defaults\)/);
+      assert.equal(merged.content[0].text.split("gauntlet settings load error").length - 1, 1);
+      assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] });
+    } else {
+      assert.deepEqual(merged, parent);
+    }
+    assert.deepEqual(await h.emitEvent("tool_result", parent), [undefined]);
+  });
+}
+
+test("nested dispatch: dormant when closureReview.enforce is false", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: verifyBranch() });
+  await h.emit("session_start");
+  assert.deepEqual(await h.emitEvent("tool_call", nestedCall("script/1", loneImplementer())), [undefined]);
+});
+
 for (const agent of ["implementer", "loop-implementer"]) {
 test(`shape guard: lone ${agent} blocked in verify after the audit, with and without closureReview.model, async or not`, async () => {
   for (const settings of [
@@ -1685,6 +1919,94 @@ for (const delivery of ["live", "session_start", "session_switch", "session_fork
   });
 }
 
+for (const isError of [false, true]) {
+for (const enforce of [true, false]) {
+  test(`nested results: closure latch stays replay-equivalent with enforce=${enforce}, isError=${isError}`, async () => {
+    const cwd = tempCwd({ piGauntlet: { closureReview: { enforce } } });
+    const h = harness({ hasUI: true, cwd, branch: verifyBranch() });
+    await h.emit("session_start");
+    const widget = h.widgets.at(-1);
+    await h.emitEvent("tool_result", {
+      ...waveResult("nested", [{ agent: "conformance-reviewer", exitCode: 0 }], isError),
+      parentToolCallId: "script",
+    });
+    assert.equal(h.widgets.at(-1), widget);
+    const status = await h.tools.find(t => t.name === "phase_tracker")!.execute("status", { action: "status" }, undefined, undefined, h.ctx) as any;
+    assert.equal(status.details.phases.verify.substep, undefined);
+    writeFileSync(join(cwd, ".pi/settings.json"), "{}");
+    assert.equal((await completePhase(h, "verify")).details.error, "no conformance-reviewer dispatch observed");
+    await h.emit("session_switch");
+    assert.equal((await completePhase(h, "verify")).details.error, "no conformance-reviewer dispatch observed");
+    await h.emitEvent("tool_result", waveResult("direct", [{ agent: "conformance-reviewer", exitCode: 0 }]));
+    assert.equal((await completePhase(h, "verify")).details.error, undefined);
+  });
+}
+
+for (const agent of ["implementer", "loop-implementer"]) {
+  test(`nested results: ${agent} preserves rounds and granted credits; isError=${isError}`, async () => {
+    const h = guardedHarness({ piGauntlet: { closureReview: { maxFixRounds: 1 } } });
+    await h.emit("session_start");
+    const result = waveResult("wave", [{ agent, exitCode: 0 }]);
+    await h.emitEvent("tool_result", { ...result, isError, parentToolCallId: "script" });
+    assert.equal(await firstCallResult(h, "first", implementerWave(1, agent)), undefined);
+    await h.emitEvent("tool_result", result);
+    assert.equal((await firstCallResult(h, "capped", implementerWave(1, agent)))?.block, true);
+    assert.equal((await grant(h, "grant", { rounds: 1, reason: "one more repair" })).details.error, undefined);
+    await h.emitEvent("tool_result", { ...result, isError, parentToolCallId: "script" });
+    assert.equal(await firstCallResult(h, "funded", implementerWave(1, agent)), undefined);
+    await h.emitEvent("tool_result", result);
+    const spent = await firstCallResult(h, "spent", implementerWave(1, agent));
+    assert.equal(spent?.block, true);
+    assert.match(spent?.reason ?? "", /2 fix round\(s\) used against a cap of 1/);
+  });
+}
+
+for (const row of [
+  { agent: "implementer", prior: [], warns: false },
+  { agent: "wave-reviewer", prior: [subagentResult(["implementer"])], warns: true },
+]) {
+  test(`nested results: ${row.agent} leaves cadence unchanged but finishes the registered nested dispatch; isError=${isError}`, async () => {
+    const h = harness({ hasUI: true, cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: implementBranch(row.prior) });
+    await h.emit("session_start");
+    assert.deepEqual(await h.emitEvent("tool_call", nestedCall("work", { agent: row.agent })), [undefined]);
+    assert.match(h.widgets.at(-1)!, /implement\(/);
+    const tool = h.tools.find(t => t.name === "phase_tracker")!;
+    const status = () => tool.execute("status", { action: "status" }, undefined, undefined, h.ctx) as Promise<any>;
+    assert.equal((await status()).details.phases.implement.substep, row.agent === "implementer" ? "implement" : "wave-review");
+    await h.emitEvent("tool_result", {
+      ...waveResult("work", [{ agent: row.agent, exitCode: 0 }], isError),
+      parentToolCallId: "script",
+    });
+    assert.doesNotMatch(h.widgets.at(-1)!, /implement\(/);
+    assert.equal((await status()).details.phases.implement.substep, undefined);
+    for (const delivery of ["live", "session_switch"]) {
+      if (delivery !== "live") await h.emit(delivery);
+      await h.emitEvent("tool_call", commitCall("commit"));
+      const [warning] = await h.emitEvent("tool_result", commitResult("commit"));
+      assert.equal(warning !== undefined, row.warns, delivery);
+    }
+    await h.emitEvent("tool_result", waveResult("direct", [{ agent: row.agent, exitCode: 0 }]));
+    await h.emitEvent("tool_call", commitCall("direct-commit"));
+    const [warning] = await h.emitEvent("tool_result", commitResult("direct-commit"));
+    assert.equal(warning !== undefined, !row.warns);
+  });
+}
+
+}
+
+test("nested result: open-task nudge is skipped while the same direct result nudges", async () => {
+  const h = harness({ branch: verifyBranch([
+    subagentResult(["conformance-reviewer"]),
+    taskSnapshot([{ name: "repair", status: "in_progress" }]),
+  ]) });
+  await h.emit("session_start");
+  const result = okWave("repair");
+  const [nested] = await h.emitEvent("tool_result", { ...result, parentToolCallId: "script" });
+  assert.equal(nested, undefined);
+  const [direct] = await h.emitEvent("tool_result", result) as { content: { text: string }[] }[];
+  assert.match(direct.content[0].text, /0: repair \(in_progress\)/);
+});
+
 test("interrupted implementer waves still spend rounds and granted credits and nudge open tasks live and on replay", async () => {
   const cwd = tempCwd({ piGauntlet: { closureReview: { maxFixRounds: 1 } } });
   const interrupted = waveResult("paused", [{ agent: "implementer", exitCode: 0, interrupted: true }]);
@@ -2212,18 +2534,26 @@ test("open-task nudge: fires on every qualifying wave and leaves fix-round count
 });
 
 // The closure-model mismatch warning is stashed at tool_call; it must render first.
-test("open-task nudge: a stashed tool_call warning stays ahead of the nudge on the same result", async () => {
+test("open-task nudge and mismatch preserve results and warning order (direct)", async () => {
   const h = harness({
-    cwd: tempCwd({ piGauntlet: { closureReview: { enforce: true, model: "p/configured" } } }),
-    branch: verifyBranch([taskSnapshot(eightTasks([3]))]),
+    cwd: tempCwd({ piGauntlet: { closureReview: { enforce: true, model: "p/configured", maxFixRounds: 1 } } }),
+    branch: verifyBranch([taskSnapshot(eightTasks([3])), subagentResult(["conformance-reviewer"])]),
   });
   await h.emit("session_start");
   const call = { tasks: [{ agent: "conformance-reviewer", model: "p/other", task: "audit" }, { agent: "implementer", task: "fix", worktree: true }] };
-  assert.equal(await firstCallResult(h, "m1", call), undefined);
-  const text = (await resultText(h, "m1")) ?? "";
-  const warningAt = text.indexOf("p/other");
-  const nudgeAt = text.indexOf("Plan tasks still open after this repair wave:");
-  assert.ok(warningAt >= 0 && nudgeAt > warningAt, `warning first, nudge second: ${text}`);
+  const toolCallId = "m1";
+  assert.equal((await h.emitEvent("tool_call", { toolName: "subagent", toolCallId, input: call }))[0], undefined);
+  const event = {
+    ...waveResult(toolCallId, [{ agent: "implementer", exitCode: 0 }]),
+    structuredContent: { results: [{ value: "repair" }] }, usage: { sentinel: "subagent usage" },
+  };
+  const original = structuredClone(event);
+  const [ret] = await h.emitEvent("tool_result", event);
+  const merged = mergeToolResult(event, ret);
+  assert.deepEqual(event, original);
+  assert.match(merged.content[0].text, /p\/other[\s\S]*Plan tasks still open after this repair wave:/);
+  assert.deepEqual(merged, { ...event, content: [merged.content[0], ...event.content] });
+  assert.equal((await firstCallResult(h, "next", implementerWave(1)))?.block, true, "repair still spends one fix round");
 });
 
 test("open-task nudge: silent outside the verify window and without open rows", async () => {

package/extensions/phase-tracker.ts

@@ -28,6 +28,7 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+import { createPendingWarnings } from "./lib/tool-result-warnings.ts";
 import { checkoutOf, gitSync } from "./lib/checkout.ts";
 import { checkPlan, renderManifest, legOwnership, sha256, type FsPort, type PlanCheckFinding } from "./lib/plan-check.ts";
 import {
@@ -259,6 +260,13 @@ const fixRoundCapBlockReason = (used: number, cap: number, settingsPath: string)
   "a repo closureReview block replaces the preset's whole block, so restate model and maxFixRounds alongside). " +
   "Start the escalation message with the line: gauntlet: gate=verification-before-completion/step-6";
 
+const nestedDispatchBlockReason = (): string =>
+  "Call subagent as a direct tool call, not from inside a codemode script; " +
+  "codemode only mode is unsupported while a gauntlet flow is entered, because a scripted dispatch's result " +
+  "is not replayed on reload or fork and the fix-round counter, closure-review latch, and cadence would reset. " +
+  "Switch codemode.mode: on and issue the call directly. " +
+  "Last resort: set piGauntlet.closureReview.enforce: false (disables all closure guards).";
+
 const closureModelBlockReason = (model: string, missing: number, total: number): string =>
   `Blocked: ${missing} of ${total} conformance-reviewer ${total === 1 ? "dispatch" : "entries"} ` +
   `omitted a model while piGauntlet.closureReview.model is set to "${model}".\n` +
@@ -490,11 +498,7 @@ export default function (pi: ExtensionAPI) {
   const firedGuards = new Map<string, boolean>();
   // Warnings stashed at tool_call, prepended at tool_result (verify-before-ship pattern).
   // Relies on tool_result firing for every tool_call; reconstructState clears any stragglers.
-  const pendingGuardWarnings = new Map<string, string>();
-  const addGuardWarning = (id: string, text: string) => {
-    const prior = pendingGuardWarnings.get(id);
-    pendingGuardWarnings.set(id, prior ? prior + "\n\n" + text : text);
-  };
+  const pendingWarnings = createPendingWarnings();
 
   const activeGuardPhase = (): Phase | undefined =>
     GUARD_PHASES.find((p) => phases[p].status === "in_progress");
@@ -547,7 +551,7 @@ export default function (pi: ExtensionAPI) {
     planCheckStamp = undefined;
     attemptedRecoveryEdges.clear();
     firedGuards.clear();
-    pendingGuardWarnings.clear();
+    pendingWarnings.clear();
     cadenceSeq = 0;
     cadenceLastSeen.implementer = 0;
     cadenceLastSeen["wave-reviewer"] = 0;
@@ -665,7 +669,7 @@ export default function (pi: ExtensionAPI) {
     const g = () => {
       if (!gauntletCache) {
         gauntletCache = loadGauntletSettings(ctx.cwd);
-        if (gauntletCache.errors.length > 0) addGuardWarning(event.toolCallId, settingsErrorWarning(gauntletCache.errors));
+        if (gauntletCache.errors.length > 0) pendingWarnings.add(event.toolCallId, settingsErrorWarning(gauntletCache.errors));
       }
       return gauntletCache.gauntlet;
     };
@@ -683,6 +687,9 @@ export default function (pi: ExtensionAPI) {
       // Only execution-mode dispatches carry a model or run agents; management/control
       // modes (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
       const hasAction = !!(event.input as { action?: unknown })?.action;
+      if (event.parentToolCallId && !hasAction) {
+        return { block: true, reason: nestedDispatchBlockReason() };
+      }
       // Fix-loop window: verify in progress and the R0 audit observed. Read directly,
       // not via activeGuardPhase() - verify is not a GUARD_PHASES member.
       const fixLoopWindow = !isSubagentChild && !hasAction && phases.verify.status === "in_progress" && conformanceDispatched;
@@ -711,7 +718,7 @@ export default function (pi: ExtensionAPI) {
           }
           const mismatched = [...new Set((models as string[]).filter((m) => m !== configured))];
           if (mismatched.length > 0) {
-            addGuardWarning(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
+            pendingWarnings.add(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
           }
         }
       }
@@ -743,13 +750,13 @@ export default function (pi: ExtensionAPI) {
         if (firedGuards.get("brainstorm-write")) return undefined;
         if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
         firedGuards.set("brainstorm-write", true);
-        addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
+        pendingWarnings.add(event.toolCallId, brainstormWriteWarning(specDirs()));
         return undefined;
       }
       if (firedGuards.get("implement-write")) return undefined;
       if (typeof p !== "string" || pathInSpecDirs(p, implementExemptDirs(specDirs()))) return undefined;
       firedGuards.set("implement-write", true);
-      addGuardWarning(event.toolCallId, implementWriteWarning());
+      pendingWarnings.add(event.toolCallId, implementWriteWarning());
       return undefined;
     }
 
@@ -838,44 +845,34 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    if (warnings.length > 0) addGuardWarning(event.toolCallId, warnings.join("\n\n"));
+    if (warnings.length > 0) pendingWarnings.add(event.toolCallId, warnings.join("\n\n"));
     return undefined;
   });
 
   pi.on("tool_result", async (event, ctx) => {
     if (finishDispatch(event.toolName, event.toolCallId, event.isError, event.details)) updateWidget(ctx);
     if (event.toolName === "subagent") {
-      observeFixWave(event.details, event.isError, ctx);
-      if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
-      observeCadence(event.details);
-      if (
-        !isSubagentChild &&
-        gauntletEntered &&
-        phases.verify.status === "in_progress" &&
-        isImplementerWave(event.details, event.isError)
-      ) {
-        const loaded = loadGauntletSettings(ctx.cwd);
-        if (loaded.errors.length === 0 && resolveFlowGuards(loaded.gauntlet).enforce) {
-          const open = unfinishedTaskLines(latestPlanSnapshot(ctx));
-          if (open.length) addGuardWarning(event.toolCallId, openTaskNudge(open));
+      if (!event.parentToolCallId) {
+        observeFixWave(event.details, event.isError, ctx);
+        if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
+        observeCadence(event.details);
+        if (
+          !isSubagentChild &&
+          gauntletEntered &&
+          phases.verify.status === "in_progress" &&
+          isImplementerWave(event.details, event.isError)
+        ) {
+          const loaded = loadGauntletSettings(ctx.cwd);
+          if (loaded.errors.length === 0 && resolveFlowGuards(loaded.gauntlet).enforce) {
+            const open = unfinishedTaskLines(latestPlanSnapshot(ctx));
+            if (open.length) pendingWarnings.add(event.toolCallId, openTaskNudge(open));
+          }
         }
       }
-      const warning = pendingGuardWarnings.get(event.toolCallId);
-      if (warning) {
-        pendingGuardWarnings.delete(event.toolCallId);
-        return { content: [{ type: "text" as const, text: warning }, ...event.content] };
-      }
-      return undefined;
-    }
-
-    // Guards 2/3 — prepend the stashed advisory warning to the bash/write/edit result.
-    if (event.toolName === "bash" || event.toolName === "write" || event.toolName === "edit") {
-      const warning = pendingGuardWarnings.get(event.toolCallId);
-      if (!warning) return undefined;
-      pendingGuardWarnings.delete(event.toolCallId);
-      return { content: [{ type: "text" as const, text: warning }, ...event.content] };
     }
 
+    const text = pendingWarnings.take(event.toolCallId);
+    if (text) return pendingWarnings.deliver(event, text);
     return undefined;
   });
 
@@ -1337,6 +1334,7 @@ export default function (pi: ExtensionAPI) {
           fixRoundCredits = 0;
           gauntletEntered = nextGauntletEntered(gauntletEntered, "reset", phases.brainstorm.status);
           firedGuards.clear();
+          pendingWarnings.clear();
           updateWidget(ctx);
           return {
             content: [{ type: "text", text: "Phase tracker reset. All phases pending." }],

package/extensions/telemetry.test.ts

@@ -7,6 +7,7 @@
   import { DEFAULT_TELEMETRY_BUCKETS, planDirsFor, resolveFlowGuards } from "./lib/gauntlet-settings.ts";
   import { emptyAccumulators, parseRecord, serializeRecord } from "./lib/telemetry-record.ts";
   import { guardReason } from "./lib/telemetry-ship.ts";
+  import { mergeToolResult } from "./test-support/merge-tool-result.mjs";
 
 
   const originalDepth = process.env.PI_SUBAGENT_DEPTH;
@@ -35,6 +36,7 @@
     const specDirs = resolveFlowGuards({}).specDirs;
     const fetchedRecords = new Map<string, string>();
     let clock = Date.parse("2026-09-17T10:00:00Z");
+    let enabled = o.enabled ?? true;
     const deps: Deps = {
       telemetryRepo: () => "test/repo",
       readTelemetryBranch: () => ({ records: [...fetchedRecords].map(([path, bytes]) => ({ path, bytes })) }),
@@ -61,7 +63,7 @@
         if (args[0] === "ls-files") return { code: 0, stdout: "", stderr: "" };
         return { code: 0, stdout: "", stderr: "" };
       },
-      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled: o.enabled ?? true, buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
+      settings: () => ({ specDirs, planDirs: planDirsFor(specDirs), telemetry: { enabled, buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
       // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
       jj: async (args, cwd) => {
         jjCalls.push(args);
@@ -100,7 +102,7 @@
       await emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: rel, content: body } });
       return emit("tool_result", { toolName: "write", toolCallId: "w", input: { path: rel, content: body }, content: [], isError: false, details: undefined });
     };
-    return { fetchedRecords, root, handlers, emit, gitCalls, gitCwds, jjCalls, readFileCalls, gitWrites, excludeFile, bash, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
+    return { setEnabled: (value: boolean) => (enabled = value), fetchedRecords, root, handlers, emit, gitCalls, gitCwds, jjCalls, readFileCalls, gitWrites, excludeFile, bash, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
   }
 
   const P = (over: Record<string, string> = {}) => Object.fromEntries(["brainstorm", "plan", "implement", "verify", "ship"].map((p) => [p, { status: over[p] ?? "pending" }]));
@@ -1222,6 +1224,69 @@
     return h;
   }
 
+  for (const toolName of ["write", "edit"]) {
+    for (const nested of [false, true]) {
+      test(`post-ship ${toolName} warning preserves results (${nested ? "nested" : "direct"})`, async () => {
+        const h = await boundInJjShip();
+        const before = readFileSync(h.recordPath(), "utf8");
+        const event = {
+          toolName, toolCallId: nested ? "parent/0" : "direct",
+          ...(nested ? { parentToolCallId: "parent" } : {}),
+          input: { path: "doc/specs/a.md", content: "# Spec\n", newText: "updated" },
+          content: [{ type: "text", text: "spec updated" }], isError: false,
+          structuredContent: toolName === "write" ? { written: true } : null,
+          details: { sentinel: "telemetry details" }, usage: { sentinel: "telemetry usage" },
+        };
+        const original = structuredClone(event);
+        const [ret] = await h.emit("tool_result", event);
+        let delivered = event;
+        let merged = mergeToolResult(event, ret);
+        if (nested) {
+          assert.equal(ret, undefined);
+          assert.deepEqual(merged, original);
+          const parent = {
+            ...event, toolName: "codemode", toolCallId: "parent", parentToolCallId: undefined,
+            content: [{ type: "text", text: "script complete" }], structuredContent: { value: true },
+          };
+          delivered = parent;
+          const [parentRet] = await h.emit("tool_result", parent);
+          merged = mergeToolResult(parent, parentRet);
+          assert.equal((await h.emit("tool_result", parent))[0], undefined);
+        }
+        assert.deepEqual(event, original);
+        assert.match(merged.content[0].text, /spec shipped at .*write a follow-up spec/);
+        assert.equal(merged.content[0].text.split("spec shipped at").length - 1, 1);
+        assert.deepEqual(merged, { ...delivered, content: [merged.content[0], ...delivered.content] });
+        assert.equal(readFileSync(h.recordPath(), "utf8"), before, "sealed record stays frozen");
+      });
+    }
+  }
+
+  for (const transition of ["disabled", "session_tree"] as const) {
+    test(`deferred shipped-spec warning survives ${transition} before its parent result`, async () => {
+      const h = await boundInJjShip();
+      const before = readFileSync(h.recordPath(), "utf8");
+      const child = {
+        toolName: "edit", toolCallId: "parent/0", parentToolCallId: "parent",
+        input: { path: "doc/specs/a.md", newText: "updated" },
+        content: [{ type: "text", text: "updated" }], structuredContent: { edited: true }, isError: false,
+      };
+      assert.equal((await h.emit("tool_result", child))[0], undefined);
+      if (transition === "disabled") h.setEnabled(false);
+      else await h.emit("session_tree", { type: "session_tree" });
+      const parent = {
+        toolName: "codemode", toolCallId: "parent", input: {}, isError: false,
+        content: [{ type: "text", text: "done" }], structuredContent: { value: 0 },
+      };
+      const [ret] = await h.emit("tool_result", parent);
+      const merged = mergeToolResult(parent, ret);
+      assert.match(merged.content[0].text, /spec shipped at .*write a follow-up spec/);
+      assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] });
+      assert.equal((await h.emit("tool_result", parent))[0], undefined);
+      assert.equal(readFileSync(h.recordPath(), "utf8"), before, "sealed record stays frozen");
+    });
+  }
+
   const diffWarnings = (h: { readRecord: () => ReturnType<typeof parseRecord> }) =>
     h.readRecord()!.events.filter((e) => e.kind === "warning").map((e: any) => e.message as string).filter((m) => m.startsWith("diff omitted"));
 
@@ -1234,7 +1299,7 @@
     assert.equal(rec.derived.gates.ship_option, "keep");
     const beforeWrite = readFileSync(h.recordPath(), "utf8");
     const out = await h.writeSpec("doc/specs/a.md");
-    assert.deepEqual(out.filter(Boolean), [{ content: [{ type: "text", text: `⚠️ spec shipped at ${rec.shipped_at}; write a follow-up spec that supersedes it` }] }]);
+    assert.deepEqual(out.filter(Boolean), [{ content: [{ type: "text", text: `⚠️ spec shipped at ${rec.shipped_at}; write a follow-up spec that supersedes it` }], structuredContent: undefined }]);
     assert.equal(readFileSync(h.recordPath(), "utf8"), beforeWrite);
     assert.equal(h.readRecord().derived.spec_edits_after_ship, 0);
     assert.deepEqual(rec.derived.modified_files, ["src/a.ts", "test/a.test.ts"]);

package/extensions/telemetry.ts

@@ -14,9 +14,10 @@
   import { dirname, isAbsolute, join, posix, resolve } from "node:path";
   import * as piRuntime from "@earendil-works/pi-coding-agent";
   import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
-  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+  import type { ExtensionAPI, ExtensionContext, ToolResultEvent } from "@earendil-works/pi-coding-agent";
   import { DEFAULT_TELEMETRY_DIR, DEFAULT_TEST_COMMANDS, planDirsFor, resolveFlowGuards, resolveTelemetry, settingsErrorWarning, type TelemetryResolved } from "./lib/gauntlet-settings.ts";
   import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+  import { createPendingWarnings } from "./lib/tool-result-warnings.ts";
   import { checkoutOf } from "./lib/checkout.ts";
   import { CONTEXT_DRAFT_MARKER, nextGauntletEntered } from "./lib/phase-tracker-helpers.ts";
   import { sha256 } from "./lib/plan-check.ts";
@@ -544,6 +545,8 @@
     });
 
     pi.on("tool_result", async (event, ctx) => {
+      const text = pendingWarnings.take(event.toolCallId);
+      if (text) return pendingWarnings.deliver(event, text);
       lastCtx = ctx;
       const snap = enabledSettings(ctx);
       if (!snap) return undefined;
@@ -605,7 +608,7 @@
     });
 
     // Binding + spec-write bookkeeping; the bound-spec hooks are defined in block 2.
-    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string; via: "git" | "jj" }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string; via: "git" | "jj" }, event: ToolResultEvent, snap: SettingsSnapshot): Promise<unknown> => {
       const rel = loc.rel;
       if (!boundSpec) {
         if ((tool === "write" || tool === "edit") && isSpecPath(rel, snap.specDirs)) {
@@ -655,12 +658,13 @@
     };
 
     // Defined in block 2.
-    let onBoundSpecWrite: (tool: "write" | "edit", rel: string, event: { input: unknown; content: unknown[] }) => unknown;
+    let onBoundSpecWrite: (tool: "write" | "edit", rel: string, event: ToolResultEvent) => unknown;
     let onOtherSpecEdit: (rel: string, event: { input: unknown }, specDirs: string[]) => void;
 
     let amendmentOpen = false;
     let lastPlanTasks: { name?: string; status: string }[] | undefined;
     const pendingTest = new Map<string, string>(); // toolCallId -> matched statement
+    const pendingWarnings = createPendingWarnings();
 
     const phaseAcc = (k: PhaseKey = phaseNow()): PhaseAcc => (live().phases[k] ??= {});
 
@@ -877,7 +881,7 @@
       refreshLinks();
       if (record.shipped_at) {
         const warning = `⚠️ spec shipped at ${record.shipped_at}; write a follow-up spec that supersedes it`;
-        return { content: [{ type: "text" as const, text: warning }, ...(event.content as { type: string }[])] };
+        return pendingWarnings.deliver(event, warning);
       }
       if (record.approved_at && !amendmentOpen) {
         acc.amendments += 1;

package/extensions/test-support/merge-tool-result.mjs

@@ -0,0 +1,9 @@
+// Mirror the runner's replacement rule so a raw hook return cannot hide data loss.
+export function mergeToolResult(event, ret) {
+  if (ret === undefined) return event;
+  const merged = { ...event, ...ret };
+  if (ret.content !== undefined && ret.structuredContent === undefined) {
+    delete merged.structuredContent;
+  }
+  return merged;
+}

package/extensions/verify-before-ship.test.ts

@@ -4,6 +4,7 @@ import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import registerVerifyBeforeShip from "./verify-before-ship.ts";
+import { mergeToolResult } from "./test-support/merge-tool-result.mjs";
 import { execFileSync } from "node:child_process";
 
 const tempDirs: string[] = [];
@@ -57,12 +58,78 @@ test("git commit is not watched: no warning even when unverified", async () => {
   assert.equal((await h.emitEvent("tool_result", bashResult("c1")))[0], undefined);
 });
 
-test("git push warns when unverified", async () => {
+for (const { name, toolName, resultFields } of [
+  { name: "bash", toolName: "bash", resultFields: { structuredContent: { output: "ok", exit_code: 0 } } },
+  { name: "write", toolName: "write", resultFields: { structuredContent: null } },
+  { name: "edit", toolName: "edit", resultFields: { structuredContent: { sentinel: "edit payload" } } },
+  { name: "edit without structuredContent", toolName: "edit", resultFields: {} },
+]) {
+  test(`direct ${name} ship warning preserves the result fields`, async () => {
+    const h = harness();
+    await editSource(h);
+    await h.emitEvent("tool_call", bashCall("p1", "git push origin main"));
+    // Synthetic write/edit results exercise the tool-independent pending drain.
+    const event = {
+      ...bashResult("p1", true), toolName,
+      ...resultFields,
+      details: { sentinel: "ship details" }, usage: { sentinel: "ship usage" },
+    };
+    const [ret] = await h.emitEvent("tool_result", event);
+    const merged = mergeToolResult(event, ret);
+    assert.match(merged.content[0].text, /ran without verification/);
+    assert.deepEqual(merged.content.slice(1), event.content);
+    assert.deepEqual(merged, { ...event, content: [merged.content[0], ...event.content] });
+    assert.equal((await h.emitEvent("tool_result", event))[0], undefined);
+  });
+}
+
+for (const toolName of ["bash", "write", "edit"]) {
+  test(`nested ${toolName} ship warning leaves the child clean and reaches its parent once`, async () => {
+    const h = harness();
+    await editSource(h);
+    await h.emitEvent("tool_call", { ...bashCall("parent/0", "git push origin main"), parentToolCallId: "parent" });
+    const child = {
+      ...bashResult("parent/0"), toolName, parentToolCallId: "parent",
+      structuredContent: { output: "ok", exit_code: 0 },
+    };
+    const [childRet] = await h.emitEvent("tool_result", child);
+    assert.deepEqual(mergeToolResult(child, childRet), child);
+    assert.equal(childRet, undefined);
+    const parent = {
+      ...bashResult("parent"), toolName: "codemode",
+      content: [{ type: "text", text: "script value: 0" }], structuredContent: { value: 0 },
+    };
+    const [parentRet] = await h.emitEvent("tool_result", parent);
+    const merged = mergeToolResult(parent, parentRet);
+    assert.match(merged.content[0].text, /ran without verification/);
+    assert.equal(merged.content[0].text.split("ran without verification").length - 1, 1);
+    assert.deepEqual(merged.content.slice(1), parent.content);
+    assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] });
+    assert.equal((await h.emitEvent("tool_result", parent))[0], undefined);
+  });
+}
+
+test("nested ship warnings aggregate in arrival order without crediting the parent as a test", async () => {
   const h = harness();
-  await editSource(h);
-  await h.emitEvent("tool_call", bashCall("p1", "git push origin main"));
-  const warning = warningOf(await h.emitEvent("tool_result", bashResult("p1")));
-  assert.match(warning ?? "", /ran without verification/);
+  for (const [index, command] of ["git push origin first", "git push origin second"].entries()) {
+    const toolCallId = `parent/${index}`;
+    await h.emitEvent("tool_call", { ...bashCall(toolCallId, command), parentToolCallId: "parent" });
+    const child = { ...bashResult(toolCallId), parentToolCallId: "parent", structuredContent: { exit_code: 0 } };
+    assert.equal((await h.emitEvent("tool_result", child))[0], undefined);
+  }
+  const parent = { ...bashResult("parent", true), toolName: "codemode", structuredContent: null };
+  const [ret] = await h.emitEvent("tool_result", parent);
+  const merged = mergeToolResult(parent, ret);
+  assert.match(merged.content[0].text, /origin first[\s\S]*origin second/);
+  assert.equal(merged.content[0].text.split("ran without verification").length - 1, 2);
+  assert.deepEqual(merged, { ...parent, content: [merged.content[0], ...parent.content] });
+  assert.equal((await h.emitEvent("tool_result", parent))[0], undefined);
+
+  await h.emitEvent("tool_call", { ...bashCall("test-parent/0", "npm test"), parentToolCallId: "test-parent" });
+  await h.emitEvent("tool_result", { ...bashResult("test-parent/0"), parentToolCallId: "test-parent" });
+  await h.emitEvent("tool_result", { ...bashResult("test-parent", true), toolName: "codemode" });
+  await h.emitEvent("tool_call", bashCall("verified", "git push"));
+  assert.equal((await h.emitEvent("tool_result", bashResult("verified")))[0], undefined);
 });
 
 test("gh pr create warns when unverified", async () => {

package/extensions/verify-before-ship.ts

@@ -36,6 +36,7 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+import { createPendingWarnings } from "./lib/tool-result-warnings.ts";
 import { matchShipStatement } from "./lib/telemetry-paths.ts";
 import { checkoutOfSync, gitSync } from "./lib/checkout.ts";
 import { parseLegs } from "./lib/plan-check.ts";
@@ -214,7 +215,7 @@ export default function (pi: ExtensionAPI) {
     });
   };
   const pendingTests = new Map<string, Set<string>>();
-  const pendingShipWarnings = new Map<string, string>();
+  const pendingWarnings = createPendingWarnings();
 
   const getCommand = (event: { input: unknown }): string => {
     const input = event.input as { command?: unknown } | undefined;
@@ -236,11 +237,6 @@ export default function (pi: ExtensionAPI) {
     const command = getCommand(event);
     if (!command) return undefined;
 
-    const addShipWarning = (id: string, text: string) => {
-      const prior = pendingShipWarnings.get(id);
-      pendingShipWarnings.set(id, prior ? prior + "\n\n" + text : text);
-    };
-
     const targets = new Set<string>();
     let settingsErrShown = false;
     for (const statement of statements(command, ctx.cwd)) {
@@ -255,11 +251,11 @@ export default function (pi: ExtensionAPI) {
       const isTest = buildTestCmdRegex(testCommands).test(statement.testCommand) && !/^(?:echo|printf|rg|grep)\b/.test(statement.command);
       if (isTest && statement.trusted) targets.add(statement.target);
       if ((isTest || matchShipStatement(statement.command)) && errors.length && !settingsErrShown) {
-        addShipWarning(event.toolCallId, settingsErrorWarning(errors));
+        pendingWarnings.add(event.toolCallId, settingsErrorWarning(errors));
         settingsErrShown = true;
       }
       if (matchShipStatement(statement.command) && (!statement.trusted || !verified.has(statement.target))) {
-        addShipWarning(event.toolCallId, formatWarning(command, testCommands, warningReference));
+        pendingWarnings.add(event.toolCallId, formatWarning(command, testCommands, warningReference));
       }
     }
     if (targets.size) pendingTests.set(event.toolCallId, targets);
@@ -268,18 +264,14 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("tool_result", async (event, ctx) => {
     rememberPlan(event, ctx.cwd);
-    if (event.toolName !== "bash") return undefined;
-
-    const targets = pendingTests.get(event.toolCallId);
-    pendingTests.delete(event.toolCallId);
-    if (!event.isError) for (const target of targets ?? []) verified.add(target);
-
-    const warning = pendingShipWarnings.get(event.toolCallId);
-    if (!warning) return undefined;
-    pendingShipWarnings.delete(event.toolCallId);
+    if (event.toolName === "bash") {
+      const targets = pendingTests.get(event.toolCallId);
+      pendingTests.delete(event.toolCallId);
+      if (!event.isError) for (const target of targets ?? []) verified.add(target);
+    }
 
-    return {
-      content: [{ type: "text" as const, text: warning }, ...event.content],
-    };
+    const text = pendingWarnings.take(event.toolCallId);
+    if (text) return pendingWarnings.deliver(event, text);
+    return undefined;
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "8.4.3",
+  "version": "8.4.5",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,14 +62,14 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.6.7"
+    "pi-cohort": ">=7.6.8"
   },
   "dependencies": {
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@anthropic-ai/claude-code": "2.1.309",
+    "@anthropic-ai/claude-code": "2.1.319",
     "esbuild": "0.28.2",
-    "typebox": "^1.3.11"
+    "typebox": "^1.4.6"
   }
 }