fix(subagent): narrow late send_input redirect by terminal status

Completed names summary plus report_uri and resume, interrupted resumes without a false report claim, shutdown points at trace or spawn.

Author: TheGreatAxios

src/subagent/lifecycle-tools.test.ts

@@ -955,6 +955,98 @@ describe("send_input", () => {
     expect(sessions.get(closed.id)?.lifecycleStatus).toBe("shutdown");
   });
 
+  test("completed send_input error redirects to resume_agent and mailbox mail", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetMailbox(sessions);
+    const sendInput = createSendInputTool({ sessions, fleetRecords });
+
+    const completed = startSession(sessions, {
+      description: "done",
+      retained: true,
+    });
+    sessions.markRunning(completed.id);
+    sessions.registerDeliver(completed.id, () => {
+      throw new Error("must not deliver to a completed session");
+    });
+    sessions.complete(completed.id, "## Summary\nDone.");
+    const err = await callFleetToolRaw(sendInput, {
+      target: completed.id,
+      message: "late steer",
+    });
+    expect(err.isError).toBe(true);
+    expect(err.content).toContain(`cannot send_input to "${completed.id}"`);
+    expect(err.content).toContain("status: completed");
+    expect(err.content).toContain("resume_agent");
+    expect(err.content).toContain("mailbox mail");
+    expect(err.content).toContain("do not retry send_input");
+    expect(err.content).toContain("Summary: Done.");
+    expect(err.content).toContain(
+      `report_uri: tool-output:///fleet-dry:${completed.id}:report`,
+    );
+    expect(err.content).toContain("read_file");
+  });
+
+  test("interrupted send_input error resumes without a false report-delivered claim", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetMailbox(sessions);
+    const sendInput = createSendInputTool({ sessions, fleetRecords });
+
+    const worker = startSession(sessions, {
+      description: "paused",
+      retained: true,
+    });
+    sessions.markRunning(worker.id);
+    sessions.registerInterrupt(worker.id, () => undefined);
+    sessions.registerDeliver(worker.id, () => {
+      throw new Error("must not deliver to an interrupted session");
+    });
+    await callTool(createInterruptAgentTool({ sessions, fleetRecords }), {
+      target: worker.id,
+    });
+    const err = await callFleetToolRaw(sendInput, {
+      target: worker.id,
+      message: "late steer",
+    });
+    expect(err.isError).toBe(true);
+    expect(err.content).toContain(`cannot send_input to "${worker.id}"`);
+    expect(err.content).toContain("status: interrupted");
+    expect(err.content).toContain("resume_agent");
+    expect(err.content).toContain("do not retry send_input");
+    expect(err.content).toContain("no report delivered");
+    expect(err.content).not.toContain("report was delivered");
+    expect(err.content).not.toContain("mailbox mail");
+  });
+
+  test("shutdown send_input error points at trace/spawn, never resume_agent", async () => {
+    const sessions = createSubAgentSessionStore();
+    const fleetRecords = createFleetMailbox(sessions);
+    const sendInput = createSendInputTool({ sessions, fleetRecords });
+
+    const worker = startSession(sessions, {
+      description: "closed",
+      retained: true,
+    });
+    sessions.markRunning(worker.id);
+    sessions.registerClose(worker.id, async () => undefined);
+    sessions.registerDeliver(worker.id, () => {
+      throw new Error("must not deliver to a closed session");
+    });
+    await callTool(createCloseAgentTool({ sessions, fleetRecords }), {
+      target: worker.id,
+    });
+    expect(sessions.get(worker.id)?.lifecycleStatus).toBe("shutdown");
+    const err = await callFleetToolRaw(sendInput, {
+      target: worker.id,
+      message: "late steer",
+    });
+    expect(err.isError).toBe(true);
+    expect(err.content).toContain(`cannot send_input to "${worker.id}"`);
+    expect(err.content).toContain("status: shutdown");
+    expect(err.content).toContain("read_agent_trace");
+    expect(err.content).not.toContain("use resume_agent for another turn");
+    expect(err.content).not.toContain("report was delivered");
+  });
+
   test("enforces nested orchestrator descendant authority", async () => {
     const sessions = createSubAgentSessionStore();
     const nested = startSession(sessions, {

src/subagent/lifecycle-tools.ts

@@ -16,6 +16,12 @@ import type { ToolDefinition, ToolResult } from "@intx/types/runtime";
 import { DEFAULT_CLOSE_DEADLINE_MS } from "./dispose.js";
 import { errorMessage } from "../agent/error-message.js";
 import type { FleetMailboxHandle } from "./agent-fleet.js";
+import {
+  fleetDrySpillKey,
+  MAILBOX_DIGEST_SECTION_CHARS,
+  UNSTRUCTURED_DIGEST_CHARS,
+} from "./fleet-dry-drive.js";
+import { parseSubAgentReport } from "./report.js";
 import {
   DEFAULT_MAX_ENTRY_CHARS,
   type AgentLifecycleStatus,
@@ -136,6 +142,73 @@ export type ResumeAgentToolDeps = LifecycleToolDeps & {
   fleetRecords: FleetMailboxHandle;
 };
 
+/**
+ * Clip a late-send summary the same way digestCollectedReport clips its inline
+ * digest section: structured reports keep up to MAILBOX_DIGEST_SECTION_CHARS,
+ * unstructured (no envelope sections) keep a short teaser — the blob holds
+ * the rest.
+ */
+function clipLateSendSummary(text: string, unstructured: boolean): string {
+  const max = unstructured
+    ? UNSTRUCTURED_DIGEST_CHARS
+    : MAILBOX_DIGEST_SECTION_CHARS;
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1).trimEnd()}…`;
+}
+
+/**
+ * Late-send_input redirect per terminal status. Only `completed` delivered a
+ * report (via mailbox mail); `interrupted` never did, and `shutdown` sessions
+ * are gone for good (resumeOne after closeOne fails), so only `completed`
+ * names resume_agent. Shutdown/evicted point at read_agent_trace / a fresh
+ * spawn instead.
+ */
+function lateSendRedirect(
+  target: string,
+  status: AgentLifecycleStatus,
+  gone: boolean,
+  report: string | undefined,
+): string {
+  if (status === "completed" && !gone) {
+    let digest = "";
+    if (report !== undefined && report.length > 0) {
+      const parsed = parseSubAgentReport(report);
+      const unstructured =
+        parsed.findings.length === 0 &&
+        parsed.blockers.length === 0 &&
+        parsed.paths.length === 0;
+      const summary =
+        parsed.summary.length > 0
+          ? clipLateSendSummary(parsed.summary, unstructured)
+          : "";
+      const reportUri = `tool-output:///${fleetDrySpillKey(target, "report")}`;
+      digest =
+        summary.length > 0
+          ? ` Summary: ${summary} report_uri: ${reportUri} — use read_file with that URI (offset/limit supported) to see the rest.`
+          : ` report_uri: ${reportUri} — use read_file with that URI (offset/limit supported) to see the rest.`;
+    }
+    return (
+      " Worker already finished (completed) — summary below; full report via " +
+      "report_uri / mailbox mail; use resume_agent for another turn, do not retry send_input." +
+      digest
+    );
+  }
+  if (status === "interrupted" && !gone) {
+    return (
+      " Worker is interrupted (no report delivered) — " +
+      "use resume_agent for another turn, do not retry send_input."
+    );
+  }
+  if (status === "shutdown" || gone) {
+    return (
+      " Worker is shut down — the session is gone and cannot be resumed; " +
+      "inspect via read_agent_trace or spawn a new worker, " +
+      "do not use resume_agent or retry send_input."
+    );
+  }
+  return "";
+}
+
 function gateTarget(
   deps: LifecycleToolDeps,
   toolName: string,
@@ -366,7 +439,7 @@ const SendInputArgs = type({
 export const sendInputToolDefinition: ToolDefinition = {
   name: "send_input",
   description:
-    "Message a running worker, or answer its pending ask_director. interrupt:true stops the current turn first and queues message as the next turn.",
+    "Message a running worker only (check list_agents for status) — completed or interrupted workers need resume_agent instead; shutdown workers are gone (see read_agent_trace or spawn anew). Answers a pending ask_director; interrupt:true stops the current turn first and queues message as the next turn.",
   inputSchema: {
     type: "object",
     properties: {
@@ -435,10 +508,21 @@ export function createSendInputTool(deps: LifecycleToolDeps): AgentTool {
       if (!outcome.ok) {
         // CL-8016: name the teardown when one is recorded — after a stop the
         // session is gone, and a bare status would read as "never existed".
+        // Late-send redirect is scoped per terminal status: only `completed`
+        // delivered a report (summary + report_uri below, resume for more);
+        // `interrupted` never delivered one; `shutdown`/evicted sessions are
+        // gone for good, so they point at read_agent_trace / a fresh spawn.
+        const session = deps.sessions.get(target);
+        const redirect = lateSendRedirect(
+          target,
+          outcome.status,
+          session === undefined && outcome.status !== "not_found",
+          session?.report,
+        );
         const hint = outcome.hint !== undefined ? ` ${outcome.hint}` : "";
         return lifecycleResult(
           call.id,
-          `Error: cannot send_input to "${target}" (status: ${outcome.status}).${hint}`,
+          `Error: cannot send_input to "${target}" (status: ${outcome.status}).${hint}${redirect}`,
         );
       }
       // CL-7331: an interrupt-with-followup is transitional, not terminal.