pi-famulus 0.1.2 → 0.1.4

package/src/subagent/tool.ts

@@ -15,15 +15,17 @@
  */
 import { Type } from "typebox";
 import type { AgentToolResult, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { VALID_THINKING_LEVELS } from "../thinking-levels";
 import { formatSubagentHandover, formatSubagentNotification, truncateTail } from "../format";
 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). */
@@ -37,49 +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. 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: `Hard timeout per subagent in ms (default 1800000, max ${MAX_TIMEOUT_MS})`,
+      description: fill("tools.subagent.param.timeout_ms", { maxMs: MAX_TIMEOUT_MS }),
       maximum: MAX_TIMEOUT_MS,
     }),
   ),
@@ -92,25 +93,28 @@ const subagentParameters = Type.Object({
         Type.Literal("interrupt"),
         Type.Literal("resume"),
         Type.Literal("steer"),
+        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" })),
-  child_id: Type.Optional(Type.String({ description: "Target child (id or name) for steer/interrupt/resume" })),
-  message: Type.Optional(Type.String({ description: "Message content for steer/resume" })),
+  run_id: Type.Optional(Type.String({ description: PROMPTS["tools.subagent.param.run_id"] })),
+  child_id: Type.Optional(
+    Type.String({ description: PROMPTS["tools.subagent.param.child_id"] }),
+  ),
+  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;
   model?: string;
   timeout_ms?: number;
-  action?: "list" | "get" | "status" | "interrupt" | "resume" | "steer" | "models";
+  action?: "list" | "get" | "status" | "interrupt" | "resume" | "steer" | "extend" | "models";
   run_id?: string;
   child_id?: string;
   message?: string;
@@ -147,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",
 };
@@ -222,6 +225,7 @@ function toNotificationInfo(record: RunRecord, now: number) {
       status: c.status,
       text: c.result?.text ?? "",
       error: c.result?.error,
+      ...(c.result?.warning !== undefined ? { warning: c.result.warning } : {}),
       ...(c.prompt !== undefined ? { prompt: c.prompt } : {}),
     })),
   };
@@ -285,9 +289,23 @@ export function createSubagentTool(
     return registry;
   };
 
+  /** Last terminal state a subagent-done was sent for, per run. */
+  const runDoneSent = new Map<string, string>();
   const notifyRunCompleted = (registry: SubagentRegistry, runId: string): void => {
     const record = registry.get(runId);
-    if (!record) return;
+    if (!record) {
+      runDoneSent.delete(runId);
+      return;
+    }
+    // A resumed child can outlive the run's first-launch completion. The
+    // run is not done while it runs; its own settle sends this wake.
+    if (record.children.some((c) => c.status === "pending" || c.status === "running")) return;
+    // Several observers (first-launch completion, each resumed turn's settle)
+    // can see the same all-terminal state. One subagent-done per terminal
+    // state, identified by every child's turn number.
+    const terminalKey = record.children.map((c) => `${c.childId}:${c.turn ?? 1}`).join("|");
+    if (runDoneSent.get(runId) === terminalKey) return;
+    runDoneSent.set(runId, terminalKey);
     deps.getNotifyCenter()?.notify(formatSubagentNotification(toNotificationInfo(record, clock.now())));
   };
 
@@ -320,6 +338,7 @@ export function createSubagentTool(
         prompt: child.prompt ?? "",
         text: child.result?.text ?? "",
         ...(child.result?.error !== undefined ? { error: child.result.error } : {}),
+        ...(child.result?.warning !== undefined ? { warning: child.result.warning } : {}),
         stillRunning,
       }),
     );
@@ -348,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 => ({
@@ -364,6 +383,7 @@ export function createSubagentTool(
       taskPrompt: prompt,
       agent: resolved[ordinal].agent,
       model: params.model,
+      workKind: resolved[ordinal].workKind,
       timeoutMs,
       depth: 1,
     });
@@ -427,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" },
@@ -590,12 +604,44 @@ export function createSubagentTool(
       };
     }
 
+    if (action === "extend") {
+      const handle = resolveSingleActiveChild(registry, record, params.child_id, "extend");
+      const child = record.children.find((c) => c.childId === handle.childId);
+      const ms = params.timeout_ms === undefined ? undefined : clampTimeout(params.timeout_ms, deps.defaultTimeoutMs);
+      const { deadlineAt, hardDeadlineAt } = handle.extend(ms);
+      const now = clock.now();
+      const hard =
+        hardDeadlineAt === null
+          ? ""
+          : ` ${fill("tools.subagent.result.extended.hard-ceiling", { remaining: formatDurationMs(Math.max(0, hardDeadlineAt - now)) })}`;
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              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 },
+      };
+    }
+
     // resume
     if (!params.message) throw new Error("message is required for resume");
     const child = resolveSingleTerminalChild(record, params.child_id);
-    const handle = registry.handle(child.childId);
-    if (!handle) throw new Error(`subagent ${child.childId} has no live session to resume`);
-    await handle.resume(params.message);
+    // A resume is a new turn with its own soft budget: timeout_ms when given,
+    // else the child's spawn budget (the runner's default). Returns once the
+    // request is accepted; it never waits for an admission slot.
+    const { queuedBehind } = await registry.resumeChild(
+      child.childId,
+      params.message,
+      params.timeout_ms === undefined ? {} : { timeoutMs: clampTimeout(params.timeout_ms, deps.defaultTimeoutMs) },
+    );
     // Resume is asynchronous. If siblings are still running, hand this child
     // back as soon as it finishes; otherwise the run-complete wake covers it.
     const handedOver = new Set<string>();
@@ -608,32 +654,24 @@ export function createSubagentTool(
       content: [
         {
           type: "text",
-          text:
-            `Resumed subagent ${child.name} (${child.childId}) in run ${record.runId}. ` +
-            "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 },
+      details: { run_id: record.runId, child_id: child.childId, queued_behind: queuedBehind },
     };
   };
 
   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. Use action=list/get/status/interrupt/resume/steer 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;
@@ -694,6 +732,13 @@ export function createSubagentTool(
   };
 }
 
+/** Resume result clause for a turn waiting for an admission slot ("" when it started at once). */
+function queuedText(queuedBehind: number | null): string {
+  if (queuedBehind === null) return "";
+  const ahead = queuedBehind === 0 ? "" : ` and ${queuedBehind} subagent(s) are waiting ahead of it`;
+  return `Every subagent slot is busy${ahead}, so it is queued and starts when a slot frees. `;
+}
+
 function resolveSingleActiveChild(
   registry: SubagentRegistry,
   record: RunRecord,
@@ -728,6 +773,11 @@ function resolveSingleTerminalChild(record: RunRecord, childIdOrName: string | u
       const known = record.children.map((c) => `${c.name} (${c.childId})`).join(", ");
       throw new Error(`no child "${childIdOrName}" in run ${record.runId} (children: ${known})`);
     }
+    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(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,9 +16,11 @@
 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
-  thinking?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  // Mirror of src/agents/definition.ts — keep in sync with
+  // src/thinking-levels.ts (VALID_THINKING_LEVELS), the single source.
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
   systemPrompt: string; // frontmatter body, trimmed
   source: "builtin" | "user" | "project";
   path?: string; // builtins have no path
@@ -24,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)"
@@ -41,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. */
@@ -58,10 +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;
@@ -70,14 +113,28 @@ export interface ChildHandle {
   // current generation's promise).
   steer(message: string): Promise<void>; // while running; terminal -> throw
   followUp(message: string): Promise<void>; // same, queued delivery
-  resume(message: string): Promise<void>; // terminal -> continue running
+  /** terminal -> continue running; opts.timeoutMs is the new turn's soft budget (default: spawn budget). */
+  resume(message: string, opts?: { timeoutMs?: number }): Promise<void>;
+  /**
+   * running -> soft deadline = now + timeoutMs (default: spawn budget);
+   * otherwise throws. Returns the new deadline and the unmoved hard ceiling.
+   */
+  extend(timeoutMs?: number): { deadlineAt: number; hardDeadlineAt: number | null };
   interrupt(): Promise<void>; // abort; result resolves as interrupted
   status(): ChildStatus;
   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;
 }
 
 /**
@@ -92,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>;
@@ -101,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>;
 }
 
 /**
@@ -121,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/thinking-levels.ts

@@ -0,0 +1,26 @@
+/**
+ * Thinking levels pi core accepts — the single source of truth for the
+ * extension. The pi SDK does not export its list (pi's internal
+ * VALID_THINKING_LEVELS), so this is a maintained copy; parity tests pin
+ * every level (impl-model-spec.test.ts, impl-agents.test.ts).
+ *
+ * Pure module: zero pi dependencies, zero npm dependencies. Both src/agents/
+ * and src/subagent/ consume this — neither layer imports the other (see
+ * design doc Appendix B).
+ */
+
+export const VALID_THINKING_LEVELS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+
+export type ThinkingLevel = (typeof VALID_THINKING_LEVELS)[number];
+
+export function isValidThinkingLevel(level: string): level is ThinkingLevel {
+  return (VALID_THINKING_LEVELS as readonly string[]).includes(level);
+}