pi-gauntlet 8.4.4 → 8.4.5

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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).

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;
@@ -1660,7 +1747,7 @@ test("nested dispatch: allowed without flow entry", async () => {
 });
 
 for (const malformed of [false, true]) {
-  test(`nested dispatch: management passes and its result consumes queued warnings; malformed=${malformed}`, async () => {
+  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() });
@@ -1668,13 +1755,27 @@ for (const malformed of [false, true]) {
     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 [warning] = await h.emitEvent("tool_result", result) as ({ content: { text: string }[] } | undefined)[];
+    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);
-    if (warning) {
-      assert.match(warning.content[0].text, /gauntlet settings load error \(using defaults\)/);
-      assert.deepEqual(warning.content.slice(1), content);
+    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", result), [undefined]);
+    assert.deepEqual(await h.emitEvent("tool_result", parent), [undefined]);
   });
 }
 
@@ -2433,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 {
@@ -497,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");
@@ -554,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;
@@ -672,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;
     };
@@ -721,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));
           }
         }
       }
@@ -753,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;
     }
 
@@ -848,7 +845,7 @@ 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;
   });
 
@@ -868,26 +865,14 @@ export default function (pi: ExtensionAPI) {
           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 (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;
   });
 
@@ -1349,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.4",
+  "version": "8.4.5",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",