pi-famulus 0.1.3 → 0.1.4

package/src/subagent/tool.ts

@@ -22,9 +22,10 @@ import { realClock, type Clock, type ClockTimer } from "../clock";
 import type { NotifyCenter } from "../notify";
 import { statusGlyph, toolComponent } from "../tui/tool-component";
 import type { WorkIndex } from "../work-index";
+import { fill, PROMPTS } from "../prompts.generated";
 import { runChain, runTasks, validateChainSteps } from "./pool";
 import type { RunRecord, SubagentRegistry } from "./registry";
-import type { AgentDefinition, ChildHandle, ChildResult, ChildRunRequest } from "./types";
+import { AGENT_WORK_KINDS, type AgentDefinition, type AgentWorkKind, type ChildHandle, type ChildResult, type ChildRunRequest } from "./types";
 
 
 /** Overall result text cap (§4.6: truncateTail 512 lines / 48KB). */
@@ -38,54 +39,48 @@ const MIN_TIMEOUT_MS = 1_000;
 // Schema (§4.6 field-name contract)
 // ---------------------------------------------------------------------------
 
+const workKindSchema = Type.Union(AGENT_WORK_KINDS.map((kind) => Type.Literal(kind)), {
+  description: PROMPTS["tools.subagent.param.work_kind"],
+});
+
 const taskItem = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Agent definition name (default: worker)" })),
-  prompt: Type.String({ description: "Task prompt for this subagent" }),
-  name: Type.Optional(Type.String({ description: "Display name (default: agent name + ordinal)" })),
+  agent: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.tasks.agent"] })),
+  prompt: Type.String({ description: PROMPTS["tools.subagent.param.tasks.prompt"] }),
+  name: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.tasks.name"] })),
+  work_kind: Type.Optional(workKindSchema),
 });
 
 const chainItem = Type.Object({
-  agent: Type.Optional(Type.String({ description: "Agent definition name (default: worker)" })),
-  prompt: Type.String({
-    description: "Prompt for this step; {previous} and {outputs.<label>} interpolate earlier results",
-  }),
-  label: Type.Optional(Type.String({ description: "Label for referencing this step's output later" })),
+  agent: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.chain.agent"] })),
+  prompt: Type.String({ description: PROMPTS["tools.subagent.param.chain.prompt"] }),
+  label: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.chain.label"] })),
+  work_kind: Type.Optional(workKindSchema),
 });
 
 const subagentParameters = Type.Object({
   tasks: Type.Optional(
-    Type.Array(taskItem, { minItems: 1, maxItems: 10, description: "Subagents to run in parallel" }),
+    Type.Array(taskItem, { minItems: 1, maxItems: 10, description: PROMPTS["tools.subagent.param.tasks"] }),
   ),
   chain: Type.Optional(
-    Type.Array(chainItem, { minItems: 1, description: "Steps to run sequentially (always awaited)" }),
+    Type.Array(chainItem, { minItems: 1, description: PROMPTS["tools.subagent.param.chain"] }),
   ),
   async: Type.Optional(
-    Type.Boolean({ description: "Return immediately with a run_id; completion arrives via notification" }),
+    Type.Boolean({ description: PROMPTS["tools.subagent.param.async"] }),
   ),
   concurrency: Type.Optional(
-    Type.Number({ minimum: 1, maximum: 8, description: "Max parallel subagents for tasks (default 4)" }),
+    Type.Number({ minimum: 1, maximum: 8, description: PROMPTS["tools.subagent.param.concurrency"] }),
   ),
   fail_fast: Type.Optional(
-    Type.Boolean({
-      description: "Cancel not-yet-started subagents on first failure (already-started ones finish)",
-    }),
+    Type.Boolean({ description: PROMPTS["tools.subagent.param.fail_fast"] }),
   ),
   model: Type.Optional(
     Type.String({
-      description:
-        'Model override for all subagents: fuzzy ("haiku"), qualified ("provider/id"), ' +
-        `optionally with ":<thinking>" suffix (${VALID_THINKING_LEVELS.join(", ")}; ` +
-        'an unknown suffix is dropped with a warning when the base resolves; ' +
-        'an unknown base still errors). Default: current model. ' +
-        'Use action:"models" to list selectable values.',
+      description: fill("tools.subagent.param.model", { thinkingLevels: VALID_THINKING_LEVELS.join(", ") }),
     }),
   ),
   timeout_ms: Type.Optional(
     Type.Number({
-      description:
-        `Time budget per subagent turn in ms (default 1800000, max ${MAX_TIMEOUT_MS}). ` +
-        'Passing it does not stop the subagent: you get <pi-famulus-wake kind="subagent-overrun"> ' +
-        "and choose extend, steer, or interrupt. With resume: the resumed turn's budget. With extend: the new budget from now.",
+      description: fill("tools.subagent.param.timeout_ms", { maxMs: MAX_TIMEOUT_MS }),
       maximum: MAX_TIMEOUT_MS,
     }),
   ),
@@ -101,19 +96,19 @@ const subagentParameters = Type.Object({
         Type.Literal("extend"),
         Type.Literal("models"),
       ],
-      { description: "Manage an existing run (or list selectable models) instead of starting a new one" },
+      { description: PROMPTS["tools.subagent.param.action"] },
     ),
   ),
-  run_id: Type.Optional(Type.String({ description: "Target run for action" })),
+  run_id: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.run_id"] })),
   child_id: Type.Optional(
-    Type.String({ description: "Target child (id or name) for steer/interrupt/resume/extend" }),
+    Type.String({ description: PROMPTS["tools.subagent.param.child_id"] }),
   ),
-  message: Type.Optional(Type.String({ description: "Message content for steer/resume" })),
+  message: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.message"] })),
 });
 
 type SubagentParams = {
-  tasks?: { agent?: string; prompt: string; name?: string }[];
-  chain?: { agent?: string; prompt: string; label?: string }[];
+  tasks?: { agent?: string; prompt: string; name?: string; work_kind?: AgentWorkKind }[];
+  chain?: { agent?: string; prompt: string; label?: string; work_kind?: AgentWorkKind }[];
   async?: boolean;
   concurrency?: number;
   fail_fast?: boolean;
@@ -156,8 +151,7 @@ export interface SubagentToolDeps {
 /** M3 stopgap resolver until M5 wires the real agent loader (§4.8). */
 const BUILTIN_WORKER: AgentDefinition = {
   name: "worker",
-  description: "General-purpose subagent with the full default tool set",
-  tools: ["read", "bash", "edit", "write"],
+  description: "General-purpose subagent with user-configured tools",
   systemPrompt: "",
   source: "builtin",
 };
@@ -373,12 +367,12 @@ export function createSubagentTool(
       const label = "name" in item ? item.name : undefined;
       const chainLabel = "label" in item ? item.label : undefined;
       const name = label ?? chainLabel ?? `${agent.name}-${i + 1}`;
-      return { agent, name, prompt: item.prompt };
+      return { agent, name, prompt: item.prompt, workKind: item.work_kind ?? "other" };
     });
 
     const run = registry.createRun(kind);
     const childIds = resolved.map((r) =>
-      registry.addChild(run.runId, { name: r.name, agent: r.agent.name }),
+      registry.addChild(run.runId, { name: r.name, agent: r.agent.name, workKind: r.workKind }),
     );
 
     const makeRequest = (ordinal: number, prompt: string): ChildRunRequest => ({
@@ -389,6 +383,7 @@ export function createSubagentTool(
       taskPrompt: prompt,
       agent: resolved[ordinal].agent,
       model: params.model,
+      workKind: resolved[ordinal].workKind,
       timeoutMs,
       depth: 1,
     });
@@ -452,13 +447,7 @@ export function createSubagentTool(
       content: [
         {
           type: "text",
-          text:
-            `Started ${items.length} subagent(s) in run ${run.runId}. ${reason}\n` +
-            `While others are still running, each finished subagent arrives as <pi-famulus-wake kind="subagent-handover"> ` +
-            `with that child's prompt and result. Read it and continue: subagent({action:"resume", run_id, child_id, message}) for that child, ` +
-            `or agent_message to steer the ones still running. Do not wait for the whole run. Do not poll. ` +
-            `<pi-famulus-wake kind="subagent-done"> arrives when every subagent in the run has finished. ` +
-            `Use subagent({action:"get", run_id:"${run.runId}"}) if you need the full record.`,
+          text: fill("tools.subagent.result.backgrounded", { count: items.length, runId: run.runId, reason }),
         },
       ],
       details: { run_id: run.runId, status: "backgrounded" },
@@ -624,15 +613,18 @@ export function createSubagentTool(
       const hard =
         hardDeadlineAt === null
           ? ""
-          : ` The configured hard ceiling (hardTimeoutMs) is not moved: it stops this subagent in ${formatDurationMs(Math.max(0, hardDeadlineAt - now))}.`;
+          : ` ${fill("tools.subagent.result.extended.hard-ceiling", { remaining: formatDurationMs(Math.max(0, hardDeadlineAt - now)) })}`;
       return {
         content: [
           {
             type: "text",
             text:
-              `Extended subagent ${child?.name ?? handle.childId} (${handle.childId}) in run ${record.runId}: ` +
-              `the next <pi-famulus-wake kind="subagent-overrun"> comes in ${formatDurationMs(deadlineAt - now)} if it is still running. ` +
-              `Its result arrives as a wake when it finishes; do not poll.${hard}`,
+              fill("tools.subagent.result.extended", {
+                name: child?.name ?? handle.childId,
+                childId: handle.childId,
+                runId: record.runId,
+                next: formatDurationMs(deadlineAt - now),
+              }) + hard,
           },
         ],
         details: { run_id: record.runId, child_id: handle.childId, deadline_at: deadlineAt, hard_deadline_at: hardDeadlineAt },
@@ -662,11 +654,12 @@ export function createSubagentTool(
       content: [
         {
           type: "text",
-          text:
-            `Resumed subagent ${child.name} (${child.childId}) in run ${record.runId}. ` +
-            queuedText(queuedBehind) +
-            "You will be notified via <pi-famulus-wake kind=\"subagent-handover\"> if others are still running, " +
-            "otherwise via <pi-famulus-wake kind=\"subagent-done\"> when it completes. Do not poll.",
+          text: fill("tools.subagent.result.resumed", {
+            name: child.name,
+            childId: child.childId,
+            runId: record.runId,
+            queued: queuedText(queuedBehind),
+          }),
         },
       ],
       details: { run_id: record.runId, child_id: child.childId, queued_behind: queuedBehind },
@@ -676,22 +669,9 @@ export function createSubagentTool(
   return {
     name: "subagent",
     label: "Subagent",
-    description:
-      "Run subagents in parallel (tasks) or sequentially (chain with {previous}/{outputs.<label>} " +
-      "interpolation). By default the call waits up to a foreground budget (default 45s); longer runs " +
-      "continue in the background. Each child that finishes while others are still running wakes you with " +
-      "<pi-famulus-wake kind=\"subagent-handover\"> (its prompt and result). The whole run wakes you with <pi-famulus-wake kind=\"subagent-done\">. " +
-      "Never poll or sleep to wait. " +
-      "A subagent still running past its timeout_ms is not stopped; it wakes you with " +
-      "<pi-famulus-wake kind=\"subagent-overrun\"> so you can extend, steer, or interrupt it. " +
-      "Use action=list/get/status/interrupt/resume/steer/extend to manage existing runs.",
-    promptSnippet: "Fan out subagents in parallel or sequence them in a chain",
-    promptGuidelines: [
-      'When a <pi-famulus-wake kind="subagent-handover"> arrives, read <prompt> and <result> immediately and continue: subagent({action:"resume", run_id, child_id, message}) for that child, or agent_message to steer children that are still running. Do not wait for the rest of the run.',
-      "Subagent runs that exceed the foreground budget continue in the background; you are notified per finished child and again when the run completes — do not poll.",
-      "A failed subagent does not fail the whole run; inspect per-subagent sections in the result.",
-      "<pi-famulus-wake> is a system wake, not a user reply. kind=subagent-handover is one child; kind=subagent-done is the whole run.",
-    ],
+    description: PROMPTS["tools.subagent.description"],
+    promptSnippet: PROMPTS["tools.subagent.snippet"],
+    promptGuidelines: [...PROMPTS["tools.subagent.rules"]],
     parameters: subagentParameters,
     renderResult(result, { expanded }, theme, context) {
       const details = result.details as { run_id?: string; status?: string } | undefined;
@@ -796,10 +776,7 @@ function resolveSingleTerminalChild(record: RunRecord, childIdOrName: string | u
     if (child.status === "pending") {
       // Queued for an admission slot (a launch or an earlier resume): steer
       // would fail too, and a second resume adds nothing.
-      throw new Error(
-        `subagent ${child.name} (${child.childId}) is already queued and starts when a subagent slot frees; ` +
-          "its result arrives as a wake when it finishes. Do not resume it again.",
-      );
+      throw new Error(fill("tools.subagent.error.resume-queued", { name: child.name, childId: child.childId }));
     }
     if (!matches(child)) {
       throw new Error(`subagent ${child.name} (${child.childId}) is still ${child.status}; use steer instead`);

package/src/subagent/types.ts

@@ -6,6 +6,8 @@
  * consumer stays testable with plain fakes.
  */
 
+import type { OverrunTick } from "./overrun";
+
 /**
  * Mirror of the M5 `AgentDefinition` (design doc Appendix B, src/agents/).
  * Structurally compatible with the M5 definition, so the real agent loader
@@ -14,7 +16,7 @@
 export interface AgentDefinition {
   name: string; // ^[a-z][a-z0-9-]*$
   description: string; // required, non-empty
-  tools: string[]; // default ["read","bash","edit","write"]
+  tools?: string[]; // omitted: inherit user config; explicit list: allowlist; []: no user-configured tools (injected communication tools remain)
   model?: string; // "provider:id" | bare id
   // Mirror of src/agents/definition.ts — keep in sync with
   // src/thinking-levels.ts (VALID_THINKING_LEVELS), the single source.
@@ -26,6 +28,17 @@ export interface AgentDefinition {
 
 export type ChildStatus = "pending" | "running" | "completed" | "failed" | "interrupted";
 
+export const AGENT_WORK_KINDS = [
+  "test-suite",
+  "test",
+  "build",
+  "lint/type",
+  "other",
+  "git",
+  "read/search",
+] as const;
+export type AgentWorkKind = (typeof AGENT_WORK_KINDS)[number];
+
 export interface ChildResult {
   status: "completed" | "failed" | "interrupted";
   text: string; // getLastAssistantText() or "(no output)"
@@ -43,6 +56,8 @@ export interface ChildResult {
   /** Stall detections in the user turn that produced this result. */
   stalls?: number;
   durationMs: number;
+  /** Time waiting for local and machine-wide admission in this turn. */
+  queueMs?: number;
 }
 
 /** One turn of a child session, for the /tasks conversation view. */
@@ -60,11 +75,36 @@ export interface ChildRunRequest {
   taskPrompt?: string;
   agent: AgentDefinition; // already resolved
   model?: string; // subagent() parameter-level override
+  /** Explicit planned workload class; natural-language prompts are not classified. */
+  workKind?: AgentWorkKind;
   /** Soft budget per turn: reaching it wakes the parent; it does not abort. */
   timeoutMs: number;
   depth: number; // main session = 0, child = 1
 }
 
+export interface ChildTokenUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+export interface ChildWallUsage {
+  llmMs: number;
+  toolMs: number;
+  queueMs: number;
+  otherMs: number;
+  approximate: boolean;
+}
+
+export interface ChildSessionEvent {
+  type: string;
+  role?: string;
+  /** Pi's stable tool-call id, used to pair execution start/end events. */
+  toolCallId?: string;
+  usage?: ChildTokenUsage;
+}
+
 export interface ChildHandle {
   readonly childId: string;
   readonly result: Promise<ChildResult>; // resolves exactly once per generation;
@@ -85,8 +125,16 @@ export interface ChildHandle {
   lastEventAt(): number; // for the stall watchdog / status display
   /** Resolved `provider/id` once the child session has been constructed. */
   resolvedModel(): string | undefined;
+  /** Effective thinking level applied when the child session was constructed. */
+  effectiveThinkingLevel?(): string | undefined;
+  /** Collect and reschedule a reminder if this child is overdue at the given time. */
+  collectDueOverrun?(now: number): OverrunTick | undefined;
   /** Live child transcript. Empty when the session never started. */
   conversation(): ConversationTurn[];
+  /** Cumulative provider input/output and cache counts for this child. */
+  tokenUsage(): ChildTokenUsage;
+  /** Cumulative observed LLM, tool, admission-queue and approximate wall time. */
+  wallUsage(): ChildWallUsage;
 }
 
 /**
@@ -101,6 +149,8 @@ export interface ChildSessionAdapter {
    * Used for fleet/ls persistence and so the child prompt can name its model.
    */
   readonly resolvedModel?: string;
+  /** Effective thinking level passed to createAgentSession, after model fallbacks. */
+  readonly effectiveThinkingLevel?: string;
   prompt(text: string): Promise<void>;
   steer(text: string): Promise<void>;
   followUp(text: string): Promise<void>;
@@ -110,18 +160,22 @@ export interface ChildSessionAdapter {
   /** Provider/model failure outcome of the last assistant turn, when any. */
   getLastAssistantFailure?(): { stopReason: "error" | "aborted"; errorMessage?: string } | undefined;
   getConversation(): ConversationTurn[];
+  tokenUsage(): ChildTokenUsage;
   /** Introspection for child-session orchestration and contract tests. */
   getActiveToolNames?(): string[];
   getSystemPrompt?(): string;
   isStreaming(): boolean;
-  subscribe(listener: (event: { type: string }) => void): () => void;
-  dispose(): void;
+  /** Current queued steering drain mode, when supported by the runtime. */
+  getSteeringMode?(): "all" | "one-at-a-time";
+  subscribe(listener: (event: ChildSessionEvent) => void): () => void;
+  /** Await extension cleanup before releasing the underlying session. */
+  dispose(): void | Promise<void>;
 }
 
 export type CreateSessionFn = (req: ChildRunRequest) => Promise<ChildSessionAdapter>;
 
 export interface ChildRunner {
-  start(req: ChildRunRequest): Promise<ChildHandle>;
+  start(req: ChildRunRequest, onHandle?: (handle: ChildHandle) => void): Promise<ChildHandle>;
 }
 
 /**
@@ -130,5 +184,6 @@ export interface ChildRunner {
  * duck-types this to release sessions in disposeRun().
  */
 export interface DisposableChildHandle extends ChildHandle {
-  dispose(): void;
+  /** Settles immediately; an optional promise tracks asynchronous session cleanup. */
+  dispose(): void | Promise<void>;
 }

package/src/subagent/usage.ts

@@ -0,0 +1,48 @@
+export interface TokenUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** Normalize provider usage counts while keeping missing values at zero. */
+export function normalizedTokenUsage(usage: {
+  input?: unknown;
+  output?: unknown;
+  cacheRead?: unknown;
+  cacheWrite?: unknown;
+}): TokenUsage {
+  const count = (value: unknown): number => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+  };
+  return {
+    input: count(usage.input),
+    output: count(usage.output),
+    cacheRead: count(usage.cacheRead),
+    cacheWrite: count(usage.cacheWrite),
+  };
+}
+
+/** Add a provider message's usage to the child's cumulative totals. */
+export function accumulateTokenUsage(total: TokenUsage, delta: TokenUsage): TokenUsage {
+  return {
+    input: total.input + delta.input,
+    output: total.output + delta.output,
+    cacheRead: total.cacheRead + delta.cacheRead,
+    cacheWrite: total.cacheWrite + delta.cacheWrite,
+  };
+}
+
+export function createTokenUsageAccumulator() {
+  let total: TokenUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  return {
+    add(usage: { input?: unknown; output?: unknown; cacheRead?: unknown; cacheWrite?: unknown }): TokenUsage {
+      total = accumulateTokenUsage(total, normalizedTokenUsage(usage));
+      return { ...total };
+    },
+    snapshot(): TokenUsage {
+      return { ...total };
+    },
+  };
+}

package/src/task-tools.ts

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import { realClock, type Clock } from "./clock";
 import type { ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { ManagerClient, TaskRecord } from "./manager-client";
+import { fill, PROMPTS } from "./prompts.generated";
 import {
   formatAgentCommand,
   isAgentStatusActive,
@@ -85,14 +86,12 @@ function formatTaskLine(task: TaskRecord, now: number): string {
   );
 }
 
-const END_TURN_HINT =
-  'The task is still running. Reply to the user now with no tool call; a <pi-famulus-wake> arrives when it finishes.';
-const LIST_END_TURN_HINT =
-  "Running work wakes you with a <pi-famulus-wake> when it finishes. Reply to the user now with no tool call instead of checking again.";
+const END_TURN_HINT = PROMPTS["tools.task_output.hint.still-running"];
+const LIST_END_TURN_HINT = PROMPTS["tools.task_list.hint.running"];
 
 const taskListParameters = Type.Object({
   all: Type.Optional(
-    Type.Boolean({ description: "Also include finished work (default: running only). Always limited to this session." }),
+    Type.Boolean({ description: PROMPTS["tools.task_list.param.all"] }),
   ),
 });
 
@@ -102,10 +101,8 @@ export function createTaskListTool(
   return {
     name: "task_list",
     label: "Task List",
-    description:
-      "List background work this session started: shell/monitor tasks and subagent children. " +
-      "Work from other pi sessions is never shown.",
-    promptSnippet: "List background shell/monitor tasks and subagents",
+    description: PROMPTS["tools.task_list.description"],
+    promptSnippet: PROMPTS["tools.task_list.snippet"],
     parameters: taskListParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const client = await requireClient(deps);
@@ -180,15 +177,12 @@ export function createTaskListTool(
 }
 
 const taskOutputParameters = Type.Object({
-  task_id: Type.String({ description: "Task id, e.g. sh_a1b2c3d4" }),
+  task_id: Type.String({ description: PROMPTS["tools.task_output.param.task_id"] }),
   cursor: Type.Optional(
-    Type.Number({
-      description:
-        "Byte offset to read from (for incremental reads). Omit to read the tail of the output.",
-    }),
+    Type.Number({ description: PROMPTS["tools.task_output.param.cursor"] }),
   ),
   max_bytes: Type.Optional(
-    Type.Number({ description: "Maximum bytes to return (default 65536)" }),
+    Type.Number({ description: PROMPTS["tools.task_output.param.max_bytes"] }),
   ),
 });
 
@@ -211,7 +205,7 @@ export function createTaskOutputTool(
   const lastRunningSize = new Map<string, number>();
   const guardPoll = (id: string, running: boolean, size: number) => {
     if (running && lastRunningSize.get(id) === size) {
-      throw new Error(`No new output from ${id} since your last read. ${END_TURN_HINT}`);
+      throw new Error(fill("tools.task_output.error.no-new-output", { taskId: id, hint: END_TURN_HINT }));
     }
     if (running) lastRunningSize.set(id, size);
     else lastRunningSize.delete(id);
@@ -219,11 +213,8 @@ export function createTaskOutputTool(
   return {
     name: "task_output",
     label: "Task Output",
-    description:
-      "Read output of a background task. Without a cursor, returns the tail of the output " +
-      "plus the current file pointer; pass the returned next_cursor as cursor for incremental reads. " +
-      "Not a way to wait: a running task wakes you when it finishes, so reply with no tool call instead of calling this again.",
-    promptSnippet: "Read background task output",
+    description: PROMPTS["tools.task_output.description"],
+    promptSnippet: PROMPTS["tools.task_output.snippet"],
     parameters: taskOutputParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const agentText = agentTextFor(deps, params.task_id);
@@ -280,7 +271,7 @@ export function createTaskOutputTool(
 }
 
 const taskStopParameters = Type.Object({
-  task_id: Type.String({ description: "Task id to stop, e.g. sh_a1b2c3d4" }),
+  task_id: Type.String({ description: PROMPTS["tools.task_stop.param.task_id"] }),
 });
 
 export function createTaskStopTool(
@@ -289,9 +280,8 @@ export function createTaskStopTool(
   return {
     name: "task_stop",
     label: "Task Stop",
-    description:
-      "Stop a running background task (SIGTERM to the process group, SIGKILL after a 2s grace).",
-    promptSnippet: "Stop a background task",
+    description: PROMPTS["tools.task_stop.description"],
+    promptSnippet: PROMPTS["tools.task_stop.snippet"],
     parameters: taskStopParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx: ExtensionContext) {
       const agent = deps.getRegistry?.()?.handle(params.task_id);

package/src/tui/message-renderers.ts

@@ -102,7 +102,8 @@ function collapsedText(details: FamulusWake, theme: Theme): string {
       const shell = details.shell
         ? ` · shell ${formatDuration(details.shell.elapsedMs)}${details.shell.growing === null ? "" : details.shell.growing ? " (output growing)" : " (output idle)"}`
         : "";
-      return `${theme.fg("warning", "!")} ${theme.fg("muted", "overrun")} ${details.name} ${formatDuration(details.elapsedMs)} / ${formatDuration(details.budgetMs)} budget · still running${shell}`;
+      const additional = details.additional?.length ? ` · +${details.additional.length} more overdue` : "";
+      return `${theme.fg("warning", "!")} ${theme.fg("muted", "overrun")} ${details.name} ${formatDuration(details.elapsedMs)} / ${formatDuration(details.budgetMs)} budget · still running${additional}${shell}`;
     }
     case "supervisor-request":
       return [
@@ -168,6 +169,21 @@ export function expandedWakeText(details: FamulusWake | undefined, content: stri
         ...(details.hardCeilingMs === undefined || details.nextReminderMs < details.hardCeilingMs
           ? [`Next reminder in ${formatDuration(details.nextReminderMs)} unless you extend, steer, or interrupt it.`]
           : []),
+        ...(details.additional?.length
+          ? [
+              `Also overdue (${details.additional.length}):`,
+              ...details.additional.map((child) => [
+                `${child.name} (${child.childId}) · run ${child.runId}`,
+                `Elapsed this turn: ${formatDuration(child.elapsedMs)} of ${formatDuration(child.budgetMs)}`,
+                `Last activity (${formatDuration(child.lastActivity.agoMs)} ago): ${child.lastActivity.text}`,
+                ...(child.shell ? [`Shell ${child.shell.taskId} · ${formatDuration(child.shell.elapsedMs)}\n$ ${child.shell.command}\nOutput: ${child.shell.outputPath}`] : []),
+                ...(child.hardCeilingMs !== undefined ? [`Hard ceiling stops it in ${formatDuration(child.hardCeilingMs)}.`] : []),
+                ...(child.hardCeilingMs === undefined || child.nextReminderMs < child.hardCeilingMs
+                  ? [`Next reminder in ${formatDuration(child.nextReminderMs)}.`]
+                  : []),
+              ].join("\n")),
+            ]
+          : []),
       ].join("\n\n");
     }
     case "supervisor-request":