@yagni-app/code-staging 1.1.3-staging.1376.1 → 1.1.3-staging.1377.1

package/dist/extension/index.js

@@ -285,15 +285,23 @@ export async function registerYagni(pi, deps = {}) {
     }
     // Lock the interactive session to the `advanced` tier only. The backend
     // catalog returns all tiers, but only `advanced` is registered with the
-    // `yagni` provider, so /model and Ctrl+P show a single entry. Child
-    // processes (/go, subagents, advisor) fetch their own catalog and register
-    // their own provider, so they are unaffected by this filter.
+    // `yagni` provider, so /model and Ctrl+P show a single entry.
     //
-    // Eval mode is exempt: a headless harness (scoping sessions, code evals)
-    // names its tier explicitly — the backend's scoping sessions run `--model
-    // standard` — and there is no /model picker to keep tidy. Filtering there
-    // turns a valid tier request into "no models match".
-    const catalog = evalMode ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
+    // Two exemptions:
+    // - CHILD processes: the runner stamps YAGNI_CALLER on every /go, subagent,
+    //   and advisor spawn (`isDriverCaller` false). A child names its tier on
+    //   the command line (`--model standard` for a general subagent, `--model
+    //   efficient` for a searcher) and must resolve it EXACTLY against its own
+    //   catalog — the advanced-only filter used to leave those tier names
+    //   unresolved, so pi fell back to its custom-model-id path (a stderr
+    //   warning on every non-advanced child and default-shaped capability
+    //   metadata instead of the real context-window/token caps).
+    // - Eval mode: a headless harness (scoping sessions, code evals) names its
+    //   tier explicitly — the backend's scoping sessions run `--model standard`
+    //   — and there is no /model picker to keep tidy. Filtering there turns a
+    //   valid tier request into "no models match".
+    const driver = isDriverCaller(env);
+    const catalog = evalMode || !driver ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
     // YAG-471: the driver's own completions carry attribution headers read from
     // this process's env (YAGNI_SESSION_ID minted by the launcher; YAGNI_CALLER
     // defaults to "driver" when unset, i.e. every session that is not a /go

package/dist/extension/pipeline/resilience.d.ts

@@ -41,9 +41,19 @@ export type RunStageFn = (stage: PipelineStage, ctx: {
 export interface ResilienceAttemptRecord {
     stageId: string;
     lens?: ReviewLens;
+    /** The stage's agent name (a subagent child's agent, or the /go stage id). */
+    agent?: string;
+    /**
+     * Which task of a multi-task subagent call this attempt belongs to
+     * (0-based). Content-free — an index, never task text — so parallel
+     * same-agent failures are attributable without leaking content.
+     */
+    taskIndex?: number;
     /** 1-based attempt number. */
     attempt: number;
     outcome: "ok" | "transient" | "fatal" | "timeout" | "aborted";
+    /** Which timer fired, when the attempt timed out. */
+    timeoutKind?: "idle" | "wall";
     exitCode: number;
     stopReason?: string;
     elapsedMs: number;

package/dist/extension/pipeline/resilience.js

@@ -31,6 +31,8 @@
 const WRITE_STAGE_IDS = ["implement", "fix"];
 /** Honest message stamped on a stage we aborted for exceeding its time budget. */
 const TIMEOUT_MESSAGE = "stage exceeded its idle or wall-clock timeout";
+const WALL_TIMEOUT_MESSAGE = "stage exceeded its wall-clock timeout";
+const IDLE_TIMEOUT_MESSAGE = "stage exceeded its idle timeout";
 /** stderr fingerprints of a transient transport/provider blip worth retrying. */
 const TRANSIENT_STDERR = /\b429\b|\b5\d\d\b|ECONNRESET|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|socket hang up/i;
 /**
@@ -86,7 +88,12 @@ export function withResilience(base, policy, opts = {}) {
     const telemetry = opts.telemetry;
     return async (stage, ctx, deps) => {
         const callerSignal = deps.signal;
-        const isWriteStage = WRITE_STAGE_IDS.includes(stage.id);
+        // The write-gate keys on what the child can DO, not on the stage id: a
+        // subagent stage carries the synthetic id "implement" for /go-compat, so
+        // the subagent tool passes an explicit per-agent flag (a read-only
+        // verifier is retried freely; an edit-capable child keeps the no-re-run
+        // discipline). Absent, the /go stage-id vocabulary decides as before.
+        const isWriteStage = deps.stageWriteCapable ?? WRITE_STAGE_IDS.includes(stage.id);
         let last;
         for (let attempt = 1; attempt <= policy.maxAttempts; attempt++) {
             // A caller abort during a backoff window: stop before spending another attempt.
@@ -95,9 +102,11 @@ export function withResilience(base, policy, opts = {}) {
             const timeoutController = new AbortController();
             const composed = composeAbortSignal(callerSignal, timeoutController.signal);
             let timedOut = false;
+            let timeoutKind;
             let sawAnyEvent = false;
-            const fireTimeout = () => {
+            const fireTimeout = (kind) => {
                 timedOut = true;
+                timeoutKind = kind;
                 if (!timeoutController.signal.aborted)
                     timeoutController.abort();
             };
@@ -120,9 +129,9 @@ export function withResilience(base, policy, opts = {}) {
                     armIdle();
                     return;
                 }
-                fireTimeout();
+                fireTimeout("idle");
             };
-            const wallTimer = setTimeout(fireTimeout, policy.wallTimeoutMs);
+            const wallTimer = setTimeout(() => fireTimeout("wall"), policy.wallTimeoutMs);
             wallTimer.unref?.();
             armIdle();
             const originalOnEvent = deps.onEvent;
@@ -150,8 +159,11 @@ export function withResilience(base, policy, opts = {}) {
                 telemetry?.({
                     stageId: stage.id,
                     ...(ctx.lens ? { lens: ctx.lens } : {}),
+                    ...(stage.agent ? { agent: stage.agent } : {}),
+                    ...(deps.taskIndex !== undefined ? { taskIndex: deps.taskIndex } : {}),
                     attempt,
                     outcome,
+                    ...(timedOut && timeoutKind ? { timeoutKind } : {}),
                     exitCode: last.exitCode,
                     ...(last.stopReason ? { stopReason: last.stopReason } : {}),
                     elapsedMs,
@@ -167,12 +179,17 @@ export function withResilience(base, policy, opts = {}) {
                 record("ok", false);
                 return last;
             }
-            if (timedOut)
-                last.errorMessage = TIMEOUT_MESSAGE;
+            if (timedOut) {
+                last.errorMessage = timeoutKind === "wall" ? WALL_TIMEOUT_MESSAGE : timeoutKind === "idle" ? IDLE_TIMEOUT_MESSAGE : TIMEOUT_MESSAGE;
+            }
             const transient = classifyTransient(last, timedOut);
+            // A wall-clock exhaustion is a "task too big" signal, not a stall: a
+            // lane that opts out (subagents) fails honestly instead of re-burning
+            // the same 20 minutes per attempt. Idle stalls stay retryable.
+            const wallNotRetryable = timedOut && timeoutKind === "wall" && policy.retryWallTimeout === false;
             // No double-apply: a write stage that already started working is never re-run.
             const blockedByWriteGate = isWriteStage && sawAnyEvent;
-            const willRetry = transient && !blockedByWriteGate && attempt < policy.maxAttempts;
+            const willRetry = transient && !wallNotRetryable && !blockedByWriteGate && attempt < policy.maxAttempts;
             record(timedOut ? "timeout" : transient ? "transient" : "fatal", willRetry);
             if (!willRetry)
                 return last;

package/dist/extension/pipeline/runner.d.ts

@@ -54,6 +54,20 @@ export interface RunStageDeps {
      * subagent tool and the advisor pass their own label through this seam.
      */
     callerLabel?: string;
+    /**
+     * Write-gate override for the resilience wrapper: whether THIS child's tool
+     * list can mutate the workspace (edit/write). The subagent tool sets it per
+     * agent (read-only verifiers retry; edit-capable children do not); the /go
+     * pipeline leaves it absent so the stage-id vocabulary decides as before.
+     */
+    stageWriteCapable?: boolean;
+    /**
+     * Which task of a multi-task subagent call this child runs (0-based). Rides
+     * the resilience attempt record only — content-free attribution so parallel
+     * same-agent failures stay distinguishable in the telemetry. Absent for
+     * single-task /go stages.
+     */
+    taskIndex?: number;
     /**
      * Additive live tap: invoked once per parsed NDJSON event, in stream order,
      * right after it is buffered for the reducers. PURE side-channel for the

package/dist/extension/pipeline/types.d.ts

@@ -524,6 +524,14 @@ export interface ResiliencePolicy {
     backoffMaxMs: number;
     /** Jitter as a fraction of the computed delay, applied as +/- (0 = none). */
     jitterRatio: number;
+    /**
+     * Whether a WALL-clock exhaustion is retryable. Default true (the /go
+     * doctrine: a wedged stage is worth another attempt). A lane whose children
+     * run read-only, fast work (subagents) sets false: a 20-minute burn means
+     * the task is too big, and re-running it just multiplies the spend before
+     * the same honest fail. Idle-stall timeouts stay retryable either way.
+     */
+    retryWallTimeout?: boolean;
 }
 /**
  * Default resilience policy. Generous timeouts so a legitimately long but live

package/dist/extension/pipeline/types.js

@@ -29,6 +29,7 @@ export const DEFAULT_RESILIENCE_POLICY = {
     backoffBaseMs: 1_000,
     backoffMaxMs: 30_000,
     jitterRatio: 0.25,
+    retryWallTimeout: true,
 };
 /**
  * R3-a tool-failure health gate. A WRITE stage (implement / fix) that exits 0 is

package/dist/extension/subagentRender.d.ts

@@ -53,6 +53,8 @@ export interface SubagentTaskProgress {
 }
 export interface SubagentDetails {
     tasks: SubagentTaskProgress[];
+    /** True when every task in the call failed — keys the tool_result handler's isError override. */
+    allFailed?: boolean;
 }
 /** Bound on the retained action log so a chatty child cannot grow details unbounded. */
 export declare const ACTION_LOG_MAX = 120;

package/dist/extension/subagents.d.ts

@@ -21,9 +21,22 @@ import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-cod
 import { Type } from "typebox";
 import type { ChildUsageHandle } from "./childUsage.js";
 import type { WorkingLineHandle } from "./workingLine.js";
+import { type ResilienceAttemptRecord } from "./pipeline/resilience.js";
 import { runStage } from "./pipeline/runner.js";
-import { type ModelTier, type PipelineStage } from "./pipeline/types.js";
+import { type ModelTier, type PipelineStage, type ResiliencePolicy } from "./pipeline/types.js";
 import { renderSubagentCall, renderSubagentResult } from "./subagentRender.js";
+/**
+ * pi's tool contract signals an error by THROWING, and a normally-returned
+ * result is always isError=false — the `isError` field on an AgentToolResult
+ * is never read by the agent loop. But the `tool_result` EXTENSION event CAN
+ * override the flag (`{ isError: true }` from a handler is merged by
+ * agent-session's afterToolCall). A completed subagent call that failed ALL
+ * its tasks must keep the partial child output in the content (so throwing
+ * is wrong there), and this handler is the one seam that marks it as an
+ * error in session history. Registered by registerSubagents; fail-soft —
+ * a throw inside is swallowed by the runner anyway, but never rely on it.
+ */
+export declare function registerSubagentFailureFlag(pi: ExtensionAPI): void;
 export declare const SUBAGENT_TOOL_NAME = "subagent";
 export declare const GENERAL_AGENT_NAME = "general";
 export declare const MAX_PARALLEL_SUBAGENTS = 4;
@@ -93,6 +106,8 @@ export interface MakeSubagentToolDeps {
     runStageImpl?: typeof runStage;
     discover?: (deps: DiscoverDeps) => SubagentDef[];
     homeDir?: string;
+    /** Env seam for the telemetry sessionId read (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
     /** Live ultra-mode probe (/ultra): widens the per-call fan-out ceiling. */
     isUltra?: () => boolean;
     /**
@@ -116,6 +131,22 @@ export interface MakeSubagentToolDeps {
      */
     childUsage?: ChildUsageHandle;
 }
+/**
+ * The subagent lane's resilience policy: the /go defaults, except a wall-
+ * clock exhaustion is NOT retried (a 20-minute burn means the task is too
+ * big — fail honestly instead of re-burning it per attempt; idle stalls stay
+ * retryable). Exported so a test can pin the composed policy the production
+ * path actually runs (every unit test injects runStageImpl instead).
+ */
+export declare function subagentRunPolicy(): ResiliencePolicy;
+/**
+ * The per-attempt telemetry adapter: one content-free error-sink row per
+ * resilience attempt (agent, taskIndex, outcome, timeoutKind, exit code,
+ * elapsed, willRetry — never task text or stderr). Exported for the same
+ * reason as subagentRunPolicy: the default `run` composes it, and a test
+ * drives the exact production adapter rather than a parallel re-statement.
+ */
+export declare function subagentTelemetry(env: NodeJS.ProcessEnv): (rec: ResilienceAttemptRecord) => void;
 export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
     name: string;
     label: string;
@@ -139,20 +170,13 @@ export declare function makeSubagentTool(deps?: MakeSubagentToolDeps): {
         }>;
         details: unknown;
     }) => void, ctx?: ExtensionContext): Promise<{
-        content: {
-            type: "text";
-            text: string;
-        }[];
-        details: {};
-        isError: boolean;
-    } | {
-        isError?: boolean | undefined;
         content: {
             type: "text";
             text: string;
         }[];
         details: {
             tasks: import("./subagentRender.js").SubagentTaskProgress[];
+            allFailed: boolean;
         };
     }>;
 };
@@ -168,7 +192,7 @@ export interface RegisterSubagentsDeps {
     /** Session child-usage accumulator; see MakeSubagentToolDeps.childUsage. */
     childUsage?: ChildUsageHandle;
 }
-/** Wire the subagent tool and the /agents listing command. */
+/** Wire the subagent tool, the failure flag handler, and the /agents listing command. */
 export declare function registerSubagents(pi: ExtensionAPI, deps?: RegisterSubagentsDeps): void;
 export {};
 //# sourceMappingURL=subagents.d.ts.map

package/dist/extension/subagents.js

@@ -23,10 +23,39 @@ import { delimiter, join } from "node:path";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { sanitizeCallerSegment } from "./config.js";
+import { logEvent } from "./errorSink.js";
 import { withResilience } from "./pipeline/resilience.js";
 import { runStage } from "./pipeline/runner.js";
 import { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
 import { applyChildEvent, finalizeTask, formatWorkingMessage, newTaskProgress, progressSummaryText, renderSubagentCall, renderSubagentResult, } from "./subagentRender.js";
+/**
+ * pi's tool contract signals an error by THROWING, and a normally-returned
+ * result is always isError=false — the `isError` field on an AgentToolResult
+ * is never read by the agent loop. But the `tool_result` EXTENSION event CAN
+ * override the flag (`{ isError: true }` from a handler is merged by
+ * agent-session's afterToolCall). A completed subagent call that failed ALL
+ * its tasks must keep the partial child output in the content (so throwing
+ * is wrong there), and this handler is the one seam that marks it as an
+ * error in session history. Registered by registerSubagents; fail-soft —
+ * a throw inside is swallowed by the runner anyway, but never rely on it.
+ */
+export function registerSubagentFailureFlag(pi) {
+    pi.on("tool_result", async (event) => {
+        try {
+            if (event.toolName !== SUBAGENT_TOOL_NAME || event.isError)
+                return undefined;
+            const details = event.details;
+            if (!details || typeof details !== "object" || !Array.isArray(details.tasks))
+                return undefined;
+            if (!details.allFailed)
+                return undefined;
+            return { isError: true };
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
 /**
  * YAG-471 attribution: the `x-yagni-caller` prefix for a subagent invocation.
  * The sanitized agent name is capped so the WHOLE label (prefix + name) stays
@@ -274,6 +303,15 @@ function loadAgentsFromDir(dir, source) {
                 agents.push(def);
         }
         catch {
+            // A malformed file used to vanish silently — now it leaves a warn row in
+            // the sink so a broken definition is diagnosable. Content-free: dir +
+            // file name only, never the parse error text (unknown shape).
+            logEvent({
+                source: "subagent",
+                level: "warn",
+                event: "agent_file_unparseable",
+                fields: { dir, file: entry.name },
+            });
             continue;
         }
     }
@@ -419,19 +457,61 @@ const parameters = Type.Object({
     agent: Type.Optional(Type.String({ description: "Agent name (see /agents). Defaults to general." })),
     tasks: Type.Optional(Type.Array(Type.Object({
         task: Type.String(),
-        agent: Type.Optional(Type.String()),
+        agent: Type.Optional(Type.String({ description: "Agent name; defaults to the top-level `agent`, then general." })),
     }), {
-        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}; ${MAX_PARALLEL_SUBAGENTS_ULTRA} in ultra mode). Use INSTEAD of task.`,
+        description: `Run several independent tasks in parallel (max ${MAX_PARALLEL_SUBAGENTS}; ${MAX_PARALLEL_SUBAGENTS_ULTRA} in ultra mode). Use INSTEAD of task. Entries without their own agent run as the top-level agent.`,
     })),
 });
+/**
+ * The subagent lane's resilience policy: the /go defaults, except a wall-
+ * clock exhaustion is NOT retried (a 20-minute burn means the task is too
+ * big — fail honestly instead of re-burning it per attempt; idle stalls stay
+ * retryable). Exported so a test can pin the composed policy the production
+ * path actually runs (every unit test injects runStageImpl instead).
+ */
+export function subagentRunPolicy() {
+    return { ...DEFAULT_RESILIENCE_POLICY, retryWallTimeout: false };
+}
+/**
+ * The per-attempt telemetry adapter: one content-free error-sink row per
+ * resilience attempt (agent, taskIndex, outcome, timeoutKind, exit code,
+ * elapsed, willRetry — never task text or stderr). Exported for the same
+ * reason as subagentRunPolicy: the default `run` composes it, and a test
+ * drives the exact production adapter rather than a parallel re-statement.
+ */
+export function subagentTelemetry(env) {
+    return (rec) => logEvent({
+        source: "subagent",
+        level: rec.outcome === "ok" ? "info" : rec.outcome === "timeout" || rec.outcome === "fatal" ? "error" : "warn",
+        event: `attempt_${rec.outcome}`,
+        sessionId: env.YAGNI_SESSION_ID,
+        fields: {
+            ...(rec.agent ? { agent: rec.agent } : {}),
+            ...(rec.taskIndex !== undefined ? { taskIndex: rec.taskIndex } : {}),
+            attempt: rec.attempt,
+            ...(rec.timeoutKind ? { timeoutKind: rec.timeoutKind } : {}),
+            exitCode: rec.exitCode,
+            ...(rec.stopReason ? { stopReason: rec.stopReason } : {}),
+            elapsedMs: rec.elapsedMs,
+            willRetry: rec.willRetry,
+        },
+    });
+}
 export function makeSubagentTool(deps = {}) {
     // The default runner rides the /go pipeline's resilience wrapper, so a chat
     // subagent gets the same idle + wall-clock ceilings and transient-only retry
     // as a /go stage child (previously a hung subagent hung the tool call until
-    // the user pressed Esc). The synthetic stage id is "implement", so the
-    // wrapper's write-gate already refuses to re-run a child that may have
-    // landed a partial edit.
-    const run = deps.runStageImpl ?? withResilience(runStage, DEFAULT_RESILIENCE_POLICY);
+    // the user pressed Esc). Two subagent-specific knobs ride the wrapper:
+    // retryWallTimeout=false (a 20-minute burn means the task is too big — fail
+    // honestly instead of re-burning it per attempt) and per-attempt telemetry
+    // into the error sink (a subagent failure previously left NO trace outside
+    // the tool result text). The write-gate keys on the resolved agent's tools,
+    // passed per task below — the synthetic stage id is "implement" and would
+    // otherwise block retry of a read-only verifier forever.
+    const run = deps.runStageImpl ??
+        withResilience(runStage, subagentRunPolicy(), {
+            telemetry: subagentTelemetry(deps.env ?? process.env),
+        });
     const discover = deps.discover ?? discoverSubagents;
     const grounded = deps.grounded !== false;
     // Resolve the effective body for a spawned subagent: the grounding-free
@@ -442,6 +522,29 @@ export function makeSubagentTool(deps = {}) {
             return def.body;
         return BUILTIN_BLIND_BODIES[def.name] ?? def.body;
     };
+    // One-line-per-agent listing so the model never guesses a name (a
+    // hallucinated agent name is a hard error). Built at registration time —
+    // the list is current as of session launch; /agents shows the live set.
+    // Fails soft: discovery problems never block the tool.
+    let agentListBlock = "";
+    try {
+        const discovered = discover({ cwd: process.cwd(), homeDir: deps.homeDir });
+        if (discovered.length > 0) {
+            agentListBlock =
+                " Available agents (first sentence only; /agents lists them in full):\n" +
+                    discovered
+                        .map((a) => `- ${a.name}: ${a.description.split(/[.!?]/)[0]?.trim() || a.description}`)
+                        .join("\n");
+        }
+    }
+    catch {
+        // A discovery failure here silently ships the tool without the name
+        // enumeration — the model is back to guessing names (the failure class
+        // this listing exists to prevent) — so it must leave a trace. Content-
+        // free: no dir list, no error text (unknown shape).
+        logEvent({ source: "subagent", level: "warn", event: "agent_list_discovery_failed" });
+        agentListBlock = "";
+    }
     return {
         name: SUBAGENT_TOOL_NAME,
         label: "Subagent",
@@ -449,7 +552,9 @@ export function makeSubagentTool(deps = {}) {
             "a compressed report. Use it for context-heavy exploration you don't need blow-by-blow, or to " +
             "run independent tasks in parallel via `tasks`. The subagent shares NONE of your conversation: " +
             "spell out the task completely. Agents come from this repo's .claude/agents and .pi/agents " +
-            "(list them with /agents); omit `agent` for the general-purpose one.",
+            "(list them with /agents); omit `agent` for the general-purpose one. The list below was " +
+            "captured at session launch — if the session's cwd differs from the launch cwd it may be " +
+            "stale; an unknown name is a hard error, so trust /agents over this list when they differ." + agentListBlock,
         promptSnippet: "subagent: delegate a self-contained task (or parallel tasks) to a fresh-context agent; returns its report.",
         parameters,
         // Self-framed: the condensed transcript look has no tinted tool boxes.
@@ -457,11 +562,15 @@ export function makeSubagentTool(deps = {}) {
         renderCall: renderSubagentCall,
         renderResult: renderSubagentResult,
         async execute(toolCallId, params, signal, onUpdate, ctx) {
-            const fail = (text) => ({
-                content: [{ type: "text", text }],
-                details: {},
-                isError: true,
-            });
+            // pi's tool contract signals an error by THROWING: a normally-returned
+            // result is always isError=false (agent-loop.js stamps it), and the
+            // `isError` field on a returned AgentToolResult was never read — the
+            // old `fail()` helper's flag was inert, so the driver model saw these
+            // as normal text. Thrown Error messages become the tool result content
+            // verbatim with isError=true, which is exactly the old intent.
+            const fail = (text) => {
+                throw new Error(text);
+            };
             const requested = params.tasks && params.tasks.length > 0
                 ? params.tasks
                 : params.task
@@ -478,7 +587,10 @@ export function makeSubagentTool(deps = {}) {
             const agents = discover({ cwd, homeDir: deps.homeDir });
             const resolved = [];
             for (const req of requested) {
-                const name = (req.agent ?? GENERAL_AGENT_NAME).toLowerCase();
+                // A tasks[] entry names its own agent first; absent that, it inherits
+                // the call's top-level `agent` (previously silently dropped here, so
+                // `{agent: "verification", tasks: [{task}]}` ran as general).
+                const name = (req.agent ?? params.agent ?? GENERAL_AGENT_NAME).toLowerCase();
                 const def = agents.find((a) => a.name === name);
                 if (!def) {
                     return fail(`Error: unknown agent "${name}". Available agents:\n${formatAgentList(agents)}`);
@@ -518,6 +630,21 @@ export function makeSubagentTool(deps = {}) {
                     const result = await run(stage, stageCtx, {
                         cwd,
                         signal,
+                        // Write-gate input: whether the agent's DECLARED tool list has
+                        // edit/write. This is a retry-discipline heuristic, not a
+                        // capability claim — bash can still mutate, but it runs behind
+                        // the same sandbox + permission stack as the driver's, and the
+                        // gate's purpose is only to refuse re-running a child that may
+                        // have landed a partial edit. Read-only-by-declaration verifiers
+                        // retry freely; edit-capable children keep the discipline.
+                        // Computed from the tools the runner will actually pass the
+                        // child (`--tools`), so a custom definition cannot opt out by
+                        // name.
+                        stageWriteCapable: (stage.tools).some((t) => t === "edit" || t === "write"),
+                        // Content-free task discriminator: which entry of THIS call's
+                        // task list the attempt belongs to (parallel same-agent
+                        // failures stay attributable without leaking task text).
+                        taskIndex: index,
                         personaBody: () => bodyFor(def),
                         // YAG-471: attribute this child's completions to the specific
                         // subagent, not the generic /go stage label the runner would
@@ -535,7 +662,7 @@ export function makeSubagentTool(deps = {}) {
                     // identity — per invocation, so parallel tasks never collide).
                     deps.childUsage?.record("subagent", progressKey(toolCallId, progress, index), result.usage);
                     emit();
-                    return { agent: def.name, task, result };
+                    return { agent: def.name, task, result, def };
                 }));
             }
             finally {
@@ -548,29 +675,46 @@ export function makeSubagentTool(deps = {}) {
             const allFailed = outcomes.every((o) => o.result.exitCode !== 0);
             const sections = outcomes.map((o) => {
                 const output = o.result.finalOutput.trim();
+                // Honest failure framing: the child's partial text must never read as
+                // a completed report. The prefix says what happened; the failed note
+                // keeps the exit code + stderr tail for diagnosis. Plain text only
+                // (no emojis — this reaches the driver model's context).
+                const failureBanner = o.result.exitCode !== 0
+                    ? `SUBAGENT FAILED (exit ${o.result.exitCode}${o.result.errorMessage ? `, ${o.result.errorMessage}` : ""}) — the text below is PARTIAL output, not a completed report.`
+                    : "";
                 const failedNote = o.result.exitCode !== 0
                     ? `\n\n(subagent failed, exit ${o.result.exitCode}${o.result.stderr.trim() ? `: ${o.result.stderr.trim().slice(-500)}` : ""})`
                     : "";
                 const bodyText = output || (o.result.exitCode === 0 ? "(no output)" : "");
+                // The verification agent's contract is a `## Verdict` header; an
+                // output without it is not a verdict, and the driver must not treat
+                // a truncated probe log as "HOLDS".
+                const missingVerdict = o.def.source === "builtin" && o.agent === "verification" && o.result.exitCode === 0 && !output.includes("## Verdict")
+                    ? "\n\n(no verdict — the verification run did not produce its verdict section)"
+                    : "";
                 return outcomes.length === 1
-                    ? `${bodyText}${failedNote}`
-                    : `## ${o.agent}: ${o.task}\n\n${bodyText}${failedNote}`;
+                    ? `${failureBanner ? failureBanner + "\n\n" : ""}${bodyText}${missingVerdict}${failedNote}`
+                    : `## ${o.agent}: ${o.task}\n\n${failureBanner ? failureBanner + "\n\n" : ""}${bodyText}${missingVerdict}${failedNote}`;
             });
             return {
                 content: [{ type: "text", text: sections.join("\n\n") }],
                 // The folded progress records ARE the final details: a superset of the
                 // old {agent, task, exitCode, usage, toolCalls} shape, plus the action
-                // log and report that renderSubagentResult paints.
-                details: { tasks: progresses },
-                ...(allFailed ? { isError: true } : {}),
+                // log and report that renderSubagentResult paints. `allFailed` keys
+                // the tool_result handler's isError override (see
+                // registerSubagentFailureFlag) — the returned field itself is inert
+                // in pi's contract (errors are signaled by throwing, and here we keep
+                // the partial child output in the result instead).
+                details: { tasks: progresses, allFailed },
             };
         },
     };
 }
-/** Wire the subagent tool and the /agents listing command. */
+/** Wire the subagent tool, the failure flag handler, and the /agents listing command. */
 export function registerSubagents(pi, deps = {}) {
     const discover = deps.discover ?? discoverSubagents;
     pi.registerTool(makeSubagentTool(deps));
+    registerSubagentFailureFlag(pi);
     pi.registerCommand("agents", {
         description: "List the subagents available in this repo (.claude/agents, .pi/agents).",
         handler: async (_args, ctx) => {

package/dist/extension/todos.d.ts

@@ -194,16 +194,6 @@ export declare function makeTodoTool(get: () => TodoItem[], set: (todos: TodoIte
         details: {
             todos: TodoItem[];
         };
-        isError: boolean;
-    } | {
-        content: {
-            type: "text";
-            text: string;
-        }[];
-        details: {
-            todos: TodoItem[];
-        };
-        isError?: undefined;
     }>;
 };
 /**

package/dist/extension/todos.js

@@ -367,11 +367,11 @@ export function makeTodoTool(get, set, completedAt) {
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const normalized = normalizeTodos(params.todos);
             if (!normalized.ok) {
-                return {
-                    content: [{ type: "text", text: `Error: ${normalized.error}` }],
-                    details: { todos: get() },
-                    isError: true,
-                };
+                // pi signals tool errors by THROWING (a returned result is always
+                // isError=false; the returned `isError` field was never read), so the
+                // error text must ride the thrown message to reach the model as an
+                // error.
+                throw new Error(`Error: ${normalized.error}`);
             }
             set(normalized.todos);
             paintWidget(ctx, normalized.todos, completedAt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "1.1.3-staging.1376.1",
+  "version": "1.1.3-staging.1377.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -58,5 +58,5 @@
     "turndown": "^7.2.4",
     "typebox": "^1.3.15"
   },
-  "yagniSourceSha": "ad5363e506fdbfaa52dc79d778d3488661659426"
+  "yagniSourceSha": "2d36b38964c6959ed433421c6eb2502d5d351423"
 }