Treat parent interrupt as resume, not a successor spawn

A parent-initiated pause unblocks wait with stop_reason interrupted
while the worker is often still live. Inviting spawn_agent on that
stamp collided with resume_agent. Failed and incomplete-report stay
on the one-successor path; operator-cancel still waits.

Author: TheGreatAxios

CHANGELOG.md

@@ -15,10 +15,14 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ### Changed
 
-- Skywalker may spawn one successor with a changed brief after a failed,
-  incomplete-report, or interrupted-incomplete fleet worker. Operator-cancelled
-  salvage still waits for the operator. Identical briefs stay refused. This
-  reverses the 0.3.15 fail-path idle, not operator-cancel.
+- Skywalker may spawn one successor with a changed brief after a failed or
+  incomplete-report fleet worker. A parent-initiated interrupt
+  (`stop_reason: interrupted`) is a resumable pause — `resume_agent` or
+  re-wait, not a successor — unless the session is no longer resumable.
+  Operator-cancelled salvage still waits for the operator. Identical briefs
+  stay refused at the prompt / spawn-handoff layer. `wait_agents` JSON
+  includes `stop_reason` so interrupt vs cancelled vs incomplete-report stay
+  distinct. This reverses the 0.3.15 fail-path idle, not operator-cancel.
 
 ## [0.3.18] - 2026-09-08
 

docs/ARCHITECTURE.md

@@ -114,7 +114,7 @@ Two directors, selected by role:
 
 - **ChatDirector** (interactive, `src/agent/director.ts`) — Extends `DefaultDirector` with task list tracking, workflow nudges, LSP auto-activation, and multi-turn chat semantics. It never terminates the session: operator declines are surfaced as replies and the reactor stays alive for the next message. Auto mode is toggled by CLI flags (`--auto` / `--no-auto`); there is currently no in-session key to toggle it (default on; constrained envelope — workspace writes and unconstrained shell auto-allow; installs, recursive rm, force/uncontained worktree changes, sensitive-path and opaque-wrapper shell still ask; contained non-force `git worktree add`/`remove`/`prune` and `list` auto-allow; shell file-mutation denied). It is not a separate edit/plan mode.
 - **SubAgentDirector** (delegated work, `src/subagent/index.ts`) — Drives a dispatched worker until a turn arrives with no tool calls, then replies with the final assistant text and ends the run. A tool-less turn **after tools** completes only with the four-heading envelope (Summary, Findings, Blockers, Paths); a missing envelope nudges once (**incomplete-report**) and a second tool-less turn still without the envelope salvages as **incomplete-report-stop**. Explore/read-only workers that used tools then replied with findings remain normal completes; `requireEvidence` (off by default, set per director) additionally requires at least one read before a tool-less spawn-only reply can complete. Reads done through `run_shell` count as evidence too — `src/subagent/shell-evidence.ts` classifies shell reads (`cat`, `grep`, `sed` without `-i`, …) over the same subject expansion the auto-shell policy uses — but there is no corresponding shell-write evidence or file-write requirement: a run that never touches a file still completes normally once it replies with the envelope. There is no turn budget. Operator/parent cancel after any progress returns a **cancelled** salvage report (partial findings + tool activity) instead of a bare cancel string; cancel before progress still surfaces as cancelled-by-operator. There is no repetition/no-progress/never-acted/never-edited hard stop and no fingerprint-based re-dispatch block — a genuinely stuck worker runs until it completes, stalls, hits an opt-in wall-clock deadline, or is cancelled.
-  `spawn_agent` starts each worker and records it in the caller's fleet mailbox; `wait_agents` collects terminal reports from that mailbox. Wait JSON includes `stop_reason` from the session when present so a salvage that is wait-`done` is not mistaken for a clean complete. Deadline salvage prepends an advisory parent hint suggesting continuation plus a longer deadline if more wall-clock time is warranted. Failed, incomplete-report, and interrupted-incomplete salvage tell the parent to diagnose from the report or error and MAY spawn one successor with a changed brief. Operator-cancelled salvage asks the parent to synthesize Findings and Paths and wait for the operator instead of auto-starting another specialist. Identical re-dispatch of the same brief stays refused at the prompt / spawn-handoff layer; there is no fingerprint-based re-dispatch hard-block. Deadline hints are advisory only — an identical re-dispatch is still admitted at runtime. Parent hints are prepended on salvage reports returned to the parent.
+  `spawn_agent` starts each worker and records it in the caller's fleet mailbox; `wait_agents` collects terminal reports from that mailbox. Wait JSON includes `stop_reason` from the session when present so a salvage that is wait-`done` is not mistaken for a clean complete, and so parent-initiated interrupt (`interrupted`) is not mistaken for operator-cancel (`cancelled`). Deadline salvage prepends an advisory parent hint suggesting continuation plus a longer deadline if more wall-clock time is warranted. Failed and incomplete-report salvage tell the parent to diagnose from the report or error and MAY spawn one successor with a changed brief. A parent-initiated interrupt is a resumable pause: wait unblocks with `stop_reason: interrupted` (often while the session is still running and has no report); the parent should `resume_agent` or re-wait, and must not spawn a successor against a still-live worker. Successor only if that session is no longer resumable. Operator-cancelled salvage asks the parent to synthesize Findings and Paths and wait for the operator instead of auto-starting another specialist. Identical re-dispatch of the same brief stays refused at the prompt / spawn-handoff layer; there is no fingerprint-based re-dispatch hard-block. Deadline hints are advisory only — an identical re-dispatch is still admitted at runtime. Parent hints are prepended on salvage reports returned to the parent. The runtime does not auto-spawn successors.
 
 #### Model-family policy (`src/agent/model-family-policy.ts`)
 

src/agent/directors/skywalker/package.test.ts

@@ -149,7 +149,6 @@ describe("skywalkerPackage", () => {
   test("systemPrompt fail-then-successor is distinct from operator-cancel wait", () => {
     const p = skywalkerPackage.systemPrompt;
     expect(p).toContain("incomplete-report");
-    expect(p).toContain("interrupted-incomplete");
     expect(p).toContain("MAY `spawn_agent` **one** successor");
     expect(p).toContain("changed** brief");
     expect(p).toContain("wait for the operator");
@@ -158,6 +157,17 @@ describe("skywalkerPackage", () => {
     expect(p).toContain("Operator-cancel is not a re-dispatch");
     expect(p).not.toContain("Then start the next worker");
     expect(p).not.toContain("if the job still needs doing");
+    expect(p).not.toContain("interrupted-incomplete");
+  });
+
+  test("systemPrompt treats parent interrupt as resume, not successor spawn", () => {
+    const p = skywalkerPackage.systemPrompt;
+    expect(p).toContain("Parent-initiated interrupt");
+    expect(p).toContain("resume_agent");
+    expect(p).toContain("still-live worker");
+    expect(p).toContain("no longer resumable");
+    expect(p).toContain("interrupt_agent");
+    expect(p).toContain("stop_reason: interrupted");
   });
 
   test("systemPrompt simple path skips explorer+critic for tiny work", () => {

src/agent/directors/skywalker/package.ts

@@ -77,7 +77,8 @@ Do **not** turn a "why is this stalled / why no thinking / spawn looks broken" d
 - Answer from mounted tools + known architecture; at most **one** explorer worker if a single unknown path blocks the answer.
 - Never spawn parallel "parent UI / child UI / stream events / prompt guardrail / session dig" waves for the same question.
 - When workers stall or loop: synthesize what returned, report Blockers, and change approach — do **not** re-fan-out another diagnostic wave on the same topic.
-- Failed wait (\`status: failed\` plus \`error\`), salvage \`incomplete-report\`, or interrupted-incomplete (\`stop_reason: interrupted\`, not operator-cancel): diagnose from the wait report or error; MAY \`spawn_agent\` **one** successor with a **changed** brief (new \`success_criteria\` / \`do_not\` / continuation from Findings). Cap is one successor for that stall. Spawn the successor — do not search the repo as a substitute.
+- Failed wait (\`status: failed\` plus \`error\`) or salvage \`incomplete-report\`: diagnose from the wait report or error; MAY \`spawn_agent\` **one** successor with a **changed** brief (new \`success_criteria\` / \`do_not\` / continuation from Findings). Cap is one successor for that stall. Spawn the successor — do not search the repo as a substitute.
+- Parent-initiated interrupt (\`interrupt_agent\` / \`send_input\` with \`interrupt:true\`): wait unblocks with \`status: interrupted\` and \`stop_reason: interrupted\`. That is a resumable pause, not fail or incomplete-report. The worker is often still running and often has no report. Call \`resume_agent\` (changed follow-up into retained context) or re-wait. Do **not** \`spawn_agent\` a successor against a still-live worker. Successor only if the session is no longer resumable.
 - Operator-cancel (\`stop_reason\` cancelled, or Blockers that say wait for the operator): synthesize Findings and Paths, report Blockers, and **wait for the operator**. Do not auto-retry. Do not spawn a successor because the worker was cancelled.
 - Do **not** search the repo yourself after a worker stops without finishing.
 - Permission asks and long run_shell clocks on worker rows are not a signal to spawn more diggers.
@@ -89,6 +90,7 @@ Runtime requires success_criteria for implement/review and their default directo
 Re-dispatch after a blocker is a new handoff (new criteria / new do_not), not a retry of the old one-liner.
 Identical re-dispatch of the same brief stays refused.
 Operator-cancel is not a re-dispatch — wait for the operator.
+Parent-initiated interrupt is not a re-dispatch — resume_agent (or re-wait). Successor only if the session is no longer resumable.
 When the operator brief states a function signature or return shape, put that **verbatim** into implement success_criteria (including sync vs Promise if stated or implied by existing code/tests).
 
 # Verify after ship

src/agent/prompts.ts

@@ -170,7 +170,7 @@ export function buildGuidelines(
           "Orchestration:",
           "- Break multi-step or parallel work into focused worker dispatches with distinct lenses; prefer `spawn_agent` (fire several in one turn when jobs are independent), then reply with who is running and end the turn — workers keep running while you are idle, and `wait_agents` / `list_agents` on a later turn collect their reports without holding this conversation blocked.",
           "- Pass the typed spawn contract: `intent`, `success_criteria` (done-when; required for implement/review and their default directors), `do_not` (scope fence), and `report_focus`. Free-form `prompt` without `success_criteria` fail-closes for implement/review and their default directors.",
-          "- After workers return, classify fail / incomplete-report / interrupted-incomplete vs operator-cancel vs clean complete. Fail-path: diagnose from the report or error and MAY spawn one successor with a changed brief. Operator-cancel: wait for the operator; do not auto-retry. Identical brief: refuse. Merge Summary/Findings into a coherent answer for the operator; do not paste raw fleet-agent dumps.",
+          "- After workers return, classify fail / incomplete-report vs parent-initiated interrupt vs operator-cancel vs clean complete. Fail-path (`status: failed` or salvage `incomplete-report`): diagnose from the report or error and MAY spawn one successor with a changed brief. Parent-initiated interrupt (`interrupt_agent` / `send_input` with `interrupt:true` unblocks wait with `stop_reason: interrupted`): the worker is often still running and often has no report — `resume_agent` or re-wait; do not `spawn_agent` a successor against a still-live worker. Successor only if that session is no longer resumable. Operator-cancel (`stop_reason` cancelled): wait for the operator; do not auto-retry. Identical brief: refuse. Merge Summary/Findings into a coherent answer for the operator; do not paste raw fleet-agent dumps.",
           "- Use manage_tasks for your own coordination checklist; spawning workers is `spawn_agent` / `wait_agents`, not manage_tasks.",
           "- If context is compacted automatically, do not stop tasks early due to token fear; persist progress via manage_tasks and worker reports.",
         ]),

src/prompts.test.ts

@@ -129,13 +129,16 @@ test("orchestrator guidelines teach the typed task spawn contract", () => {
   expect(guidelines).not.toContain("weaker");
 });
 
-test("primary chat prompt classifies fail-path successor vs operator-cancel wait", () => {
+test("primary chat prompt classifies fail-path successor vs interrupt resume vs operator-cancel wait", () => {
   const prompt = buildChatSystemPrompt();
   const guidelines = buildGuidelines({ sessionMode: "orchestrator" });
   expect(guidelines).toContain("MAY spawn one successor with a changed brief");
   expect(guidelines).toContain("wait for the operator");
   expect(guidelines).toContain("do not auto-retry");
   expect(guidelines).toContain("Identical brief: refuse");
+  expect(guidelines).toContain("resume_agent");
+  expect(guidelines).toContain("still-live worker");
+  expect(guidelines).not.toContain("interrupted-incomplete");
   expect(guidelines).not.toContain("start the next worker");
   expect(prompt).toContain("MAY `spawn_agent` **one** successor");
   expect(prompt).toContain("wait for the operator");

src/subagent/agent-fleet.test.ts

@@ -1368,6 +1368,54 @@ describe("list_agents", () => {
     gate.resolve({ report: "done" });
   });
 
+  test("includes stop_reason after interrupt_agent", async () => {
+    const gate = deferred<RunSubAgentResult>();
+    const deps = makeDeps(async (params) => {
+      params.onAgentReady?.({
+        close: async () => {},
+        interrupt: () => {},
+        followup: async () => "",
+        deliver: () => {},
+      });
+      return gate.promise;
+    });
+    const spawn = createSpawnAgentTool(deps);
+    const interrupt = createInterruptAgentTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    const list = createListAgentsTool({
+      sessions: deps.sessions,
+      fleetRecords: deps.fleetRecords,
+    });
+    const spawned = await callTool(spawn, {
+      description: "looping",
+      prompt: "do it",
+      intent: "explore",
+    });
+    const id = spawned.agent_id as string;
+    if (interrupt.kind !== "full") throw new Error("expected full tool");
+    await interrupt.handler(
+      { id: "int-list-1", name: "interrupt_agent", arguments: { target: id } },
+      new AbortController().signal,
+    );
+    if (list.kind !== "full") throw new Error("expected full tool");
+    const raw = await list.handler(
+      { id: "list-stop-1", name: "list_agents", arguments: {} },
+      new AbortController().signal,
+    );
+    const content = typeof raw.content === "string" ? raw.content : JSON.stringify(raw.content);
+    const parsed = JSON.parse(content) as {
+      agents: { agent_id: string; status: string; stop_reason?: string }[];
+    };
+    expect(parsed.agents).toHaveLength(1);
+    expect(parsed.agents[0]!.agent_id).toBe(id);
+    expect(parsed.agents[0]!.status).toBe("interrupted");
+    expect(parsed.agents[0]!.stop_reason).toBe("interrupted");
+    expect(list.definition.description).toContain("stop_reason");
+    gate.resolve({ report: "done" });
+  });
+
   test("projects question and question_id while awaiting_director", async () => {
     const gate = deferred<RunSubAgentResult>();
     const deps = makeDeps(async (params) => {

src/subagent/agent-fleet.ts

@@ -469,8 +469,9 @@ export const waitAgentsToolDefinition: ToolDefinition = {
     `wait_agents pair started — never every running session in the shared store. Default timeout ${DEFAULT_WAIT_TIMEOUT_MS}ms, ` +
     `clamped to a ${MAX_WAIT_TIMEOUT_MS}ms max. A timeout or parent-turn abort is NOT an error and never touches ` +
     `the workers — they keep running and remain waitable. Live wait status includes "queued" (waiting for a burst ` +
-    `slot), "running", and "awaiting_director". interrupt_agent and close_agent unblock this wait immediately with ` +
-    `status "interrupted". Terminal JSON includes stop_reason when the session recorded one ` +
+    `slot), "running", and "awaiting_director". interrupt_agent unblocks this wait immediately with ` +
+    `status "interrupted" (a parent-initiated pause — resume_agent, do not spawn_agent a successor against the still-live worker). ` +
+    `close_agent also unblocks with status "interrupted" but is permanent. Terminal JSON includes stop_reason when the session recorded one ` +
     `(interrupted, cancelled, incomplete-report, and similar). awaiting_director is not terminal: re-wait while still pending re-delivers the same question. ` +
     `Answer with send_input (soft). Do not call this in a tight zero-progress loop: a timeout means the targets are still ` +
     `queued, running, or awaiting a director answer, not "try again right away" — do other work, reply to the operator, or change the brief. Calling again with the ` +
@@ -1424,7 +1425,7 @@ export const listAgentsToolDefinition: ToolDefinition = {
   description:
     "List the workers this session started with spawn_agent — the same fleet wait_agents " +
     "collects. Does not list siblings or another orchestrator's workers. Each entry is id, " +
-    "director, description, wait status, lifecycle, and whether wait_agents already collected it. " +
+    "director, description, wait status, lifecycle, stop_reason when recorded, and whether wait_agents already collected it. " +
     "When status is awaiting_director, the entry also includes question and question_id.",
   inputSchema: {
     type: "object",
@@ -1439,6 +1440,7 @@ export function createListAgentsTool(deps: WaitAgentsDeps): AgentTool {
       const agents = deps.fleetRecords.ids().map((id) => {
         const record = deps.fleetRecords.peek(id);
         const session = deps.sessions.get(id);
+        const stopReason = record?.stopReason ?? session?.stopReason;
         return {
           agent_id: id,
           status: record?.status ?? "unknown",
@@ -1450,6 +1452,7 @@ export function createListAgentsTool(deps: WaitAgentsDeps): AgentTool {
                 lifecycle: session.lifecycleStatus,
               }
             : {}),
+          ...(stopReason !== undefined ? { stop_reason: stopReason } : {}),
           ...(record?.status === "awaiting_director" && record.question !== undefined
             ? { question: record.question }
             : {}),

src/subagent/followup-live-agent.test.ts

@@ -221,8 +221,9 @@ describe("interrupt_agent / resume_agent reuse the same live agent", () => {
     expect(outcome.stopReason).toBe("interrupted");
     expect(outcome.stopReason).not.toBe("cancelled");
     expect(outcome.interrupted).toBe(true);
-    expect(outcome.report).toContain("MAY spawn one successor");
-    expect(outcome.report).toContain("changed brief");
+    expect(outcome.report).toContain("resume_agent");
+    expect(outcome.report).toContain("still-live");
+    expect(outcome.report).not.toContain("MAY spawn one successor");
     expect(outcome.report).not.toContain("wait for the operator");
   });
 

src/subagent/index.test.ts

@@ -406,11 +406,13 @@ describe("sub-agent stop helpers", () => {
 
     const interrupted = forcedStopReport("interrupted", "Partial work");
     const interruptedParsed = parseSubAgentReport(interrupted);
-    expect(interruptedParsed.blockers).toContain("one successor");
-    expect(interruptedParsed.blockers).toContain("changed brief");
+    expect(interruptedParsed.blockers).toContain("resume_agent");
+    expect(interruptedParsed.blockers).toContain("still-live");
+    expect(interruptedParsed.blockers).not.toContain("MAY spawn one successor");
     expect(interruptedParsed.blockers).not.toContain("wait for the operator");
     const interruptedWithHint = appendSubAgentParentHints(interrupted, "interrupted");
-    expect(interruptedWithHint).toContain("MAY spawn one successor");
+    expect(interruptedWithHint).toContain("resume_agent");
+    expect(interruptedWithHint).not.toContain("MAY spawn one successor");
     expect(interruptedWithHint).not.toContain("wait for the operator instead of auto-starting");
 
     const stalled = forcedStopReport("stalled", "parked");