rovecode 0.3.2

package/src/tools/task.ts

@@ -0,0 +1,250 @@
+/** `task` + `task_status` tools (port #26): the model's door to background subagents over
+ *  core/tasks.ts TaskManager. Children run through orchestrator.ts runChild (the ONE
+ *  agentLoop); these tools never run a loop themselves.
+ *
+ *  Source shape: opencode packages/opencode/src/tool/task.ts (MIT, snapshot
+ *  research/source_snapshots/opencode-2026 @ ebece6e) — parameters description/prompt/
+ *  subagent_type + background flag (:43-62), "started" text that tells the model NOT to
+ *  poll and to keep working or end its turn (:31-35), depth walk refusal (:104-117),
+ *  result rendered as a tagged block with the child's final text (:64-79, :341-345).
+ *  Departures: TWO tools split by policy class instead of background:true on a foreground
+ *  tool — `task` (kind spawn: start|cancel — creating a child, or destroying its work) and
+ *  `task_status` (kind read: status|result|list — registry reads; `result` is an explicit
+ *  bounded wait). Refusals come from the orchestrator's preflight (depth cap / spawn
+ *  policy) as tool output, never exceptions.
+ *
+ *  Policy: `task` kind "spawn" → action "spawn" (core/tools.ts actionFor): the default gated
+ *  rules PROMPT for it (cli/runtime.ts buildCfg) — once per start, since "once" is never
+ *  cached — yolo allows, plan mode denies (core/modes.ts); children derive prompt→deny
+ *  (orchestrator deriveChildRules), so nested starts exist only under an allow rule.
+ *  `task_status` kind "read" → action "file.read", which the gated rules ALLOW: collecting a
+ *  result never prompts, headless surfaces (run/serve/acp) and children read it, plan mode
+ *  keeps it. Its schema declares no path/command/url, so the policy resource is the tool
+ *  NAME and a smuggled `path` cannot re-aim a `deny file.read task_status` rule (tools.ts
+ *  describeResource honors declared keys only). Fix-wave MED-2: one action-agnostic
+ *  spawn-kind tool prompted for status/result/list too (≥2 prompts per task) and failed
+ *  them closed on headless surfaces. */
+
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+import { formatTaskList, isTerminal, type TaskId, type TaskInfo, type TaskManager } from "../core/tasks.ts";
+import type { SteeringQueue } from "../core/loop.ts";
+import { ADAPTER_IDS } from "../lanes/types.ts";
+import { LANES_ALLOW_ENV } from "../lanes/registry.ts";
+
+export const DEFAULT_WAIT_MS = 60_000;
+export const MAX_WAIT_MS = 600_000;
+
+export interface TaskToolOptions {
+  /** depth of the loop this tool serves (root = 0); children start at depth + 1 */
+  parentDepth?: number;
+  /** completion notes for tasks started here (default: the manager's attached queue) */
+  notify?: SteeringQueue;
+  /** the task id of the child this tool serves (nested); enables slot lending */
+  caller?: TaskId;
+  /** owner signal for tasks started here (nested: the serving task's own run signal, so
+   *  cancelling a task cancels its children). Root tools leave it unset — the manager's
+   *  bindRun() signal owns root tasks; ToolContext.signal is NOT usable (loop.ts:91). */
+  owner?: AbortSignal;
+  /** agent name used when `agent` is omitted */
+  defaultAgent?: string;
+  /** the custom subagent definitions loaded at boot (core/agents.ts agentRows) — enumerated in the schema so the model
+   *  knows which `agent` names exist; absent/empty = only the default */
+  agents?: readonly { name: string; description: string }[];
+  /** nested tools: the tool names of the registry THIS tool serves, read lazily at each start (the registry is filled
+   *  after the tool is built) → StartOptions.parentTools, so a child started from a restricted agent is clamped to that
+   *  agent's set (the allow-list is transitive). Root tools leave it unset. */
+  parentTools?: () => ReadonlySet<string>;
+  /** nested tools: the working tree of the child THIS tool serves (ChildContext.dir — its worktree when
+   *  it is isolated) → StartOptions.parentDir. An external lane started from here builds its worktree
+   *  from that directory and merges its patch back into it, so a nested lane's work travels up through
+   *  its parent's patch instead of landing in the user's live tree behind the parent's back. Root tools
+   *  leave it unset: there the manager's rootDir IS the working tree. */
+  parentDir?: string;
+}
+
+export interface TaskStatusToolOptions {
+  /** the task id of the child this tool serves (nested): a `result` wait lends its slot to
+   *  the waited-on queued task (TaskManager.result slot lending) */
+  caller?: TaskId;
+}
+
+const NOT_POLLING =
+  "You will be notified in this conversation when it finishes — do NOT poll or sleep: " +
+  "continue other non-overlapping work or end your turn. Use `task_status result` to wait for it when you need its output.";
+/** one-shot policy (cli/main.ts cmdRun exit): tasks never outlive the process that started them */
+const ONE_SHOT =
+  "In a one-shot run (`rovecode run`) background tasks do not outlive the run: collect what you need with " +
+  "`task_status result` before ending your turn.";
+
+interface Args {
+  action?: unknown; goal?: unknown; agent?: unknown; isolated?: unknown; label?: unknown; id?: unknown; timeout_ms?: unknown;
+}
+
+const err = (output: string): ToolOutput => ({ ok: false, output: `Error: ${output}` });
+const need = (tool: string, what: string): ToolOutput => err(`${tool} ${what} requires a string \`id\` (see \`task_status list\`)`);
+
+function describe(t: TaskInfo, now: number): string {
+  const secs = t.startedAt !== undefined ? Math.max(0, Math.round(((t.finishedAt ?? now) - t.startedAt) / 1000)) : 0;
+  const usage = t.usage ? `, tokens ${t.usage.input}in/${t.usage.output}out` : "";
+  return `task ${t.id} (${t.label}) ${t.status} — agent ${t.agent}, ${t.isolated ? "isolated, " : ""}${secs}s${usage}`;
+}
+
+function renderResult(t: TaskInfo, now: number): ToolOutput {
+  const head = describe(t, now);
+  if (t.status === "done") {
+    const patch = t.patchLines !== undefined ? `\n[isolated: ${t.patchLines === 0 ? "no file changes" : `patch of ${t.patchLines} lines merged back`}]` : "";
+    // #47: a lane's permissions were the CLI's own flags — the ones the approval card stated. Repeating
+    // them on the result is not decoration: it is the only place the model can see what the lane was
+    // actually allowed to do, which is rarely what our own children are allowed to do.
+    const lane = t.kind === "external"
+      ? `\n[external ${t.agent} lane — permissions: ${t.permissions ?? "(unknown)"}${t.laneExit !== undefined ? `; exit ${t.laneExit}` : ""}${t.laneModel ? `; model ${t.laneModel}` : ""}]`
+      : "";
+    return { ok: true, output: `${head}${lane}${patch}\n${t.summary ?? "(no output)"}`, data: t };
+  }
+  if (t.status === "failed") return { ok: false, output: `${head}\n${t.error ?? "unknown error"}`, data: t };
+  if (t.status === "cancelled") return { ok: false, output: head, data: t };
+  return { ok: true, output: `${head}. ${NOT_POLLING}`, data: t };
+}
+
+/** `timeout_ms`: numbers and numeric strings ("5000" — models quote integers) clamp to
+ *  [0, MAX_WAIT_MS]; absent → the default; anything else is a clear error, never a silent
+ *  default (fix-wave L6: a quoted "5000" used to become the 60s default). */
+function parseTimeout(v: unknown): number | { error: string } {
+  if (v === undefined || v === null) return DEFAULT_WAIT_MS;
+  const n = typeof v === "number" ? v : typeof v === "string" && v.trim() !== "" ? Number(v) : NaN;
+  if (!Number.isFinite(n)) return { error: `task_status result: \`timeout_ms\` must be a number of milliseconds (got ${JSON.stringify(v) ?? String(v)})` };
+  return Math.min(MAX_WAIT_MS, Math.max(0, Math.floor(n)));
+}
+
+/** kind spawn: `start` (a new child) and `cancel` (destroys the child's work) — the two
+ *  actions a gated policy should ask about. Reads live on `task_status`. */
+export function createTaskTool(tasks: TaskManager, opts: TaskToolOptions = {}): Tool {
+  const defaultAgent = opts.defaultAgent ?? "main";
+  // custom definitions, enumerated (bounded per row) so the model can pick one by name
+  const custom = (opts.agents ?? []).filter((a) => a.name !== defaultAgent);
+  const clipRow = (s: string): string => (s.length > 120 ? s.slice(0, 119) + "…" : s);
+  const customNote = custom.length > 0
+    ? `Custom agent definitions (.rovecode/agents/<name>.md — own system prompt, model, mode and tool allow-list): ${custom.map((a) => `${a.name} — ${clipRow(a.description)}`).join("; ")}. `
+    : "";
+  return {
+    schema: {
+      name: "task",
+      description:
+        "Run subagents as background tasks. `start` launches a child agent session on `goal` and returns " +
+        "at once with a task id; the child works while you continue, and a note lands in this conversation " +
+        "when it finishes (do not poll). Read its state or output with the `task_status` tool (status/result/list " +
+        "— never prompts); `cancel` aborts a task. Children see only `goal` (write it self-contained). " +
+        `At most ${tasks.maxConcurrent} run concurrently; extra starts queue FIFO. ` +
+        "`isolated` runs the child in a git worktree copy and merges its file changes back as a patch on success. " +
+        `\`agent\` may also name an EXTERNAL agentic-CLI lane — ${ADAPTER_IDS.join(" | ")} — which runs \`goal\` in that CLI ` +
+        "instead of in one of our agents. A lane always works in its own worktree, its diff merges back like any " +
+        `isolated child, and it runs with the flags stated on the approval card. Lanes are OFF unless ${LANES_ALLOW_ENV} lists the id. ` +
+        "Policy: under gated rules each `start` needs approval and the child runs read-only (prompt-gated actions " +
+        "are denied for children) unless allow rules cover them; under yolo it inherits allow-all. " + customNote + ONE_SHOT,
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["start", "cancel"] },
+          goal: { type: "string", description: "start: the child's task, self-contained (it has no access to this conversation)" },
+          agent: { type: "string", description: `start: agent definition to run (default "${defaultAgent}"${custom.length > 0 ? `; custom: ${custom.map((a) => a.name).join(", ")}` : ""}), or an external CLI lane: ${ADAPTER_IDS.join(" | ")} (needs ${LANES_ALLOW_ENV})` },
+          isolated: { type: "boolean", description: "start: run in an isolated worktree copy; file changes merge back as a patch when the task finishes ok" },
+          label: { type: "string", description: "start: short label (3-5 words) shown in task lists and completion notes" },
+          id: { type: "string", description: "cancel: task id (e.g. t1)" },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "spawn",
+    sequential: true,
+    async execute(args: unknown): Promise<ToolOutput> {
+      const a = (args ?? {}) as Args;
+      const id = typeof a.id === "string" ? a.id.trim() : "";
+      switch (a.action) {
+        case "start": {
+          if (typeof a.goal !== "string" || a.goal.trim() === "") return err("task start requires a non-empty string `goal`");
+          const agent = typeof a.agent === "string" && a.agent.trim() !== "" ? a.agent.trim() : defaultAgent;
+          const r = tasks.start(
+            { agent, goal: a.goal, isolated: a.isolated === true, background: true },
+            { label: typeof a.label === "string" ? a.label : undefined, parentDepth: opts.parentDepth ?? 0, notify: opts.notify, caller: opts.caller, owner: opts.owner, ...(opts.parentTools ? { parentTools: opts.parentTools() } : {}), ...(opts.parentDir !== undefined ? { parentDir: opts.parentDir } : {}) },
+          );
+          if (!r.ok) return err(`task refused: ${r.reason}`);
+          const t = tasks.status(r.id)!;
+          const state = t.status === "running" ? "running" : `queued (${tasks.counts().running} running, bound ${tasks.maxConcurrent})`;
+          // the approver/model must know what the child CAN do (deriveChildRules: prompt → deny); an
+          // external lane's permissions are the CLI's OWN flags (#47) — the ones the approval card
+          // stated — and they are not ours to describe in our own words
+          const policy = t.kind === "external"
+            ? `External ${t.agent} lane — permissions: ${t.permissions ?? "(unknown)"}; its worktree patch merges back when it finishes ok.`
+            : r.childPolicy === "gated"
+            ? "Policy: gated — the child runs read-only (prompt-gated actions are DENIED for children) unless allow rules cover them."
+            : "Policy: the child inherits your allow rules.";
+          return { ok: true, output: `task ${t.id} (${t.label}) started: ${state}. ${policy} ${NOT_POLLING}`, data: t };
+        }
+        case "cancel": {
+          if (id === "") return need("task", "cancel");
+          const before = tasks.status(id);
+          if (!before) return err(`unknown task '${id}'`);
+          if (isTerminal(before.status)) return { ok: true, output: `task ${id} already ${before.status}`, data: before };
+          const t = tasks.cancel(id)!;
+          return { ok: true, output: `task ${t.id} (${t.label}) cancelled`, data: t };
+        }
+        default:
+          return err(`task requires action start|cancel (got ${JSON.stringify(a.action ?? null)}); status|result|list live on task_status`);
+      }
+    },
+  };
+}
+
+/** kind read: `status` | `result` (bounded wait, aborts with the run) | `list`. Auto-allowed by
+ *  the gated rules (file.read) and plan mode; no path/command/url in the schema, so the policy
+ *  resource is always the tool name. */
+export function createTaskStatusTool(tasks: TaskManager, opts: TaskStatusToolOptions = {}): Tool {
+  return {
+    schema: {
+      name: "task_status",
+      description:
+        "Read background tasks started with `task` (never prompts, never mutates). `status` shows one task's " +
+        "state; `result` waits (bounded by `timeout_ms`, default 60s) for a task to finish and returns the " +
+        "child's final output — call it when you need the output, otherwise wait for the completion note; " +
+        "`list` shows every task. " + ONE_SHOT,
+      args: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["status", "result", "list"] },
+          id: { type: "string", description: "status/result: task id (e.g. t1)" },
+          timeout_ms: { type: "integer", description: `result: max wait in ms (default ${DEFAULT_WAIT_MS}, max ${MAX_WAIT_MS}); 0 = report the current state at once` },
+        },
+        required: ["action"],
+      },
+    },
+    kind: "read",
+    sequential: true,
+    async execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const a = (args ?? {}) as Args;
+      const now = Date.now();
+      const id = typeof a.id === "string" ? a.id.trim() : "";
+      switch (a.action) {
+        case "status": {
+          if (id === "") return need("task_status", "status");
+          const t = tasks.status(id);
+          return t ? { ok: true, output: describe(t, now), data: t } : err(`unknown task '${id}'`);
+        }
+        case "result": {
+          if (id === "") return need("task_status", "result");
+          if (!tasks.status(id)) return err(`unknown task '${id}'`);
+          const timeoutMs = parseTimeout(a.timeout_ms);
+          if (typeof timeoutMs !== "number") return err(timeoutMs.error);
+          const t = await tasks.result(id, { timeoutMs, signal: ctx.signal, caller: opts.caller });
+          if (!t) return err(`unknown task '${id}'`);
+          if (!isTerminal(t.status) && ctx.signal.aborted) return err(`wait for task ${id} aborted`);
+          if (!isTerminal(t.status)) return { ok: true, output: `${describe(t, Date.now())} — still running after ${Math.round(timeoutMs / 1000)}s. ${NOT_POLLING}`, data: t };
+          return renderResult(t, Date.now());
+        }
+        case "list":
+          return { ok: true, output: formatTaskList(tasks.list(), now), data: tasks.counts() };
+        default:
+          return err(`task_status requires action status|result|list (got ${JSON.stringify(a.action ?? null)}); start|cancel live on task`);
+      }
+    },
+  };
+}

package/src/tools/todo.ts

@@ -0,0 +1,320 @@
+/** Session todo / plan tool (PORT #32): `todo_write` + `todo_read` over one
+ *  JSON file per session, plus pure render helpers for the TUI surface.
+ *
+ *  Ported from opencode (MIT, snapshot ebece6e):
+ *  - tool contract — ONE `todos` array argument that REPLACES the whole list
+ *    (packages/opencode/src/tool/todo.ts:6-8, :31-34; packages/core/src/tool/
+ *    todowrite.ts:14-16, :49); the store's update is delete-all + insert in
+ *    list order (packages/opencode/src/session/todo.ts:29-51), reads come back
+ *    in that order (:53-66);
+ *  - item shape content / status / priority with the status and priority sets
+ *    (packages/schema/src/session-todo.ts:7-15);
+ *  - the when-to-use / when-not / rules guidance folded into the tool
+ *    description (packages/opencode/src/tool/todowrite.txt:3-16, :24-30, :44).
+ *  Validation follows gemini-cli (Apache-2.0, snapshot 0bd1d43)
+ *  packages/core/src/tools/write-todos.ts:100-129 validateToolParamValues —
+ *  array check, per-item object / non-empty description / status-enum checks,
+ *  and the at-most-ONE-in_progress rule (:120-126); "Cleared todo list" is
+ *  gemini's wording (:52, :68). Both upstreams reject an invalid list whole.
+ *
+ *  Deviations: items carry a caller-chosen `id` (whole-list replace needs a
+ *  stable handle the model can quote back; opencode is position-keyed, gemini
+ *  has none); three statuses only (no cancelled/blocked — drop the item
+ *  instead); bounds (≤50 items, id ≤64 chars, content ≤500 chars) so tool output
+ *  stays bounded; storage is `<sessionDir>/todos.json` written tmp+rename
+ *  (session.ts persistLeaf pattern; opencode uses SQLite, gemini is in-memory).
+ *  No in-memory cache: every read hits disk, so a second tool instance, a
+ *  resumed session and the TUI `/todos` surface all see the same truth. A
+ *  corrupt file is reported as empty + note — loading never throws.
+ *
+ *  Policy: todo_write is kind "memory" — a disk write of agent-private,
+ *  session-scoped metadata, the same class as memory_edit (BlockStore under
+ *  <session>/memory). core/tools.ts actionFor() maps it to memory.write, which
+ *  the runtime's default gated rules ALLOW (runtime.ts buildCfg), so the list
+ *  never prompts; kind "read" would also auto-run but would let read-only rule
+ *  sets write to disk unseen — the mirror of recall.ts's argument against
+ *  mislabeling kinds. The schemas declare no `path`/`command`, so the policy
+ *  resource is the tool name: `memory.write todo_write` targets it precisely —
+ *  which is how plan mode (modes.ts planModeRules) denies memory.write wholesale
+ *  and then re-allows exactly todo_write: the list is the plan's own artifact
+ *  (agent-private session metadata, not workspace state), while memory_edit,
+ *  file.write and shell.exec stay denied there; todo_read (kind "read" →
+ *  file.read) is always available. Not in checkpoints.ts MUTATING_KINDS, so
+ *  todo writes never trigger snapshots. */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { Tool, ToolContext, ToolOutput } from "../core/types.ts";
+
+// ---------- schema ----------
+
+export type TodoStatus = "pending" | "in_progress" | "completed";
+export type TodoPriority = "high" | "medium" | "low";
+export interface TodoItem { id: string; content: string; status: TodoStatus; priority?: TodoPriority }
+
+export const TODO_STATUSES: readonly TodoStatus[] = ["pending", "in_progress", "completed"];
+export const TODO_PRIORITIES: readonly TodoPriority[] = ["high", "medium", "low"];
+export const MAX_TODOS = 50;
+export const MAX_ID_CHARS = 64;
+export const MAX_CONTENT_CHARS = 500;
+export const TODOS_FILE = "todos.json";
+const FILE_VERSION = 1;
+const RENDER_CONTENT_CHARS = 200; // per-line render clip (content is ≤500 on disk; the TUI note stays scannable)
+
+function isStatus(v: unknown): v is TodoStatus { return (TODO_STATUSES as readonly unknown[]).includes(v); }
+function isPriority(v: unknown): v is TodoPriority { return (TODO_PRIORITIES as readonly unknown[]).includes(v); }
+
+/** Bounded echo of a rejected value — a 200k-char status must not reflect into the error. */
+function show(v: unknown): string {
+  let s: string;
+  try { s = JSON.stringify(v) ?? String(v); } catch { s = String(v); }
+  return s.length > 40 ? s.slice(0, 40).replace(/[\uD800-\uDBFF]$/, "") + "…" : s;
+}
+
+export type TodoValidation = { ok: true; items: TodoItem[] } | { ok: false; error: string };
+
+/** Whole-list validation (gemini-cli write-todos.ts:100-129 shape, plus ids and
+ *  bounds). Returns NORMALIZED items — ids/content trimmed, unknown keys
+ *  dropped, `priority` omitted when absent — or the first precise error. */
+export function validateTodos(raw: unknown): TodoValidation {
+  const err = (error: string): TodoValidation => ({ ok: false, error });
+  if (!Array.isArray(raw)) return err("`todos` must be an array of {id, content, status, priority?}");
+  if (raw.length > MAX_TODOS) return err(`too many todos: ${raw.length} (max ${MAX_TODOS})`);
+  const items: TodoItem[] = [];
+  const seen = new Set<string>();
+  const inProgress: string[] = [];
+  for (let i = 0; i < raw.length; i++) {
+    const t: unknown = raw[i];
+    const at = `todos[${i}]`;
+    if (!t || typeof t !== "object" || Array.isArray(t)) return err(`${at} must be an object {id, content, status, priority?}`);
+    const o = t as Record<string, unknown>;
+    if (typeof o.id !== "string" || o.id.trim().length === 0) return err(`${at}.id must be a non-empty string`);
+    const id = o.id.trim();
+    if (id.length > MAX_ID_CHARS) return err(`${at}.id exceeds ${MAX_ID_CHARS} chars`);
+    if (seen.has(id)) return err(`duplicate id "${id}" at ${at} — ids must be unique`);
+    seen.add(id);
+    if (typeof o.content !== "string" || o.content.trim().length === 0) return err(`${at} ("${id}"): content must be a non-empty string`);
+    const content = o.content.trim();
+    if (content.length > MAX_CONTENT_CHARS) return err(`${at} ("${id}"): content exceeds ${MAX_CONTENT_CHARS} chars`);
+    if (!isStatus(o.status)) return err(`${at} ("${id}"): status must be one of ${TODO_STATUSES.join(", ")} (got ${show(o.status)})`);
+    const item: TodoItem = { id, content, status: o.status };
+    if (o.priority !== undefined && o.priority !== null) {
+      if (!isPriority(o.priority)) return err(`${at} ("${id}"): priority must be one of ${TODO_PRIORITIES.join(", ")} (got ${show(o.priority)})`);
+      item.priority = o.priority;
+    }
+    if (item.status === "in_progress") inProgress.push(id);
+    items.push(item);
+  }
+  // gemini-cli write-todos.ts:120-126: only one task can be in_progress at a time
+  if (inProgress.length > 1) return err(`only one todo may be in_progress at a time (found ${inProgress.length}: ${inProgress.join(", ")})`);
+  return { ok: true, items };
+}
+
+// ---------- persistence (<sessionDir>/todos.json) ----------
+
+export interface LoadedTodos { items: TodoItem[]; note?: string }
+
+/** Read the session's list. Missing file = empty (the normal initial state, no
+ *  note). Unreadable / malformed / schema-invalid content = empty + a note
+ *  saying so — never throws; the next todo_write replaces the file. */
+export function loadTodos(sessionDir: string): LoadedTodos {
+  const file = join(sessionDir, TODOS_FILE);
+  const tail = "treating the list as empty; the next todo_write replaces it";
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    if ((e as { code?: unknown } | null)?.code === "ENOENT") return { items: [] };
+    return { items: [], note: `${TODOS_FILE} could not be read (${e instanceof Error ? e.message : String(e)}) — ${tail}` };
+  }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch { return { items: [], note: `${TODOS_FILE} is not valid JSON — ${tail}` }; }
+  const o = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : null;
+  if (!o || o.version !== FILE_VERSION || !Array.isArray(o.items)) {
+    return { items: [], note: `${TODOS_FILE} has an unexpected shape (expected {version: ${FILE_VERSION}, items: [...]}) — ${tail}` };
+  }
+  const v = validateTodos(o.items);
+  if (!v.ok) return { items: [], note: `${TODOS_FILE} failed validation (${v.error}) — ${tail}` };
+  return { items: v.items };
+}
+
+/** Atomic replace: write `todos.json.tmp`, then rename over the target (session.ts
+ *  persistLeaf). Creates the session dir if needed. IO errors propagate — the
+ *  tool turns them into ok:false. */
+export function saveTodos(sessionDir: string, items: readonly TodoItem[]): void {
+  mkdirSync(sessionDir, { recursive: true });
+  const file = join(sessionDir, TODOS_FILE);
+  const tmp = file + ".tmp";
+  writeFileSync(tmp, JSON.stringify({ version: FILE_VERSION, items }, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+/** A session id must be a plain directory name: `<root>/<id>/todos.json` may never
+ *  resolve outside the sessions root (listSessions identity = directory name). */
+function sessionDirFor(root: string, sessionId: string): string | null {
+  // both slashes are refused on every host: a backslash is a legal file-name byte on POSIX, but an id
+  // that would be a path on Windows is not a plain directory name anywhere
+  if (!sessionId || sessionId === "." || sessionId === ".." || /[\\/]/.test(sessionId) || basename(sessionId) !== sessionId) return null;
+  return join(root, sessionId);
+}
+
+// ---------- rendering (pure; shared by tool output and the TUI) ----------
+
+export interface TodoCounts { total: number; pending: number; inProgress: number; completed: number }
+
+export function todoCounts(items: readonly TodoItem[]): TodoCounts {
+  const c: TodoCounts = { total: items.length, pending: 0, inProgress: 0, completed: 0 };
+  for (const t of items) {
+    if (t.status === "completed") c.completed++;
+    else if (t.status === "in_progress") c.inProgress++;
+    else c.pending++;
+  }
+  return c;
+}
+
+const GLYPH: Record<TodoStatus, string> = { pending: "[ ]", in_progress: "[>]", completed: "[x]" };
+
+/** Single-line content: whitespace collapsed, clipped with an ellipsis (surrogate-safe). */
+function oneLine(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > RENDER_CONTENT_CHARS
+    ? flat.slice(0, RENDER_CONTENT_CHARS).replace(/[\uD800-\uDBFF]$/, "") + "…"
+    : flat;
+}
+
+/** Checkbox rendering: a summary line, then one `[glyph] id: content (priority)`
+ *  row per item in list order. Bounded: ≤MAX_TODOS rows, content clipped, and the
+ *  id flattened too (a trimmed id may still carry an inner newline — one row per item). */
+export function renderTodos(items: readonly TodoItem[]): string {
+  if (items.length === 0) return "todos: (empty)";
+  const c = todoCounts(items);
+  const lines = [`todos: ${c.total} total · ${c.completed} completed · ${c.inProgress} in progress · ${c.pending} pending`];
+  for (const t of items.slice(0, MAX_TODOS)) {
+    lines.push(`${GLYPH[t.status]} ${oneLine(t.id)}: ${oneLine(t.content)}${t.priority ? ` (${t.priority})` : ""}`);
+  }
+  if (items.length > MAX_TODOS) lines.push(`(+${items.length - MAX_TODOS} more not shown)`);
+  return lines.join("\n");
+}
+
+/** The re-send the loop makes while a plan is open (loop.ts LoopDeps.planReminder).
+ *
+ *  A list written twenty turns ago is buried under tool results: the model stops marking items done,
+ *  starts a second item without finishing the first, or forgets the tail of the plan entirely. This is
+ *  the same shape as the tool's own output, plus the one instruction that matters right now — so the
+ *  plan is always the most recent thing in the request, not the oldest.
+ *
+ *  null when there is nothing to chase (no list, or everything completed): a finished plan must not
+ *  keep nagging, and an empty one has nothing to say. */
+export function planReminder(items: readonly TodoItem[]): string | null {
+  const c = todoCounts(items);
+  if (c.total === 0 || c.completed === c.total) return null;
+  return [
+    "<plan-reminder>",
+    "Your own todo list for this task, still open — not a message from the user.",
+    renderTodos(items),
+    c.inProgress === 0
+      ? "Nothing is in progress. Mark the next item in_progress with todo_write before you start it."
+      : "Mark the in_progress item completed with todo_write the moment it is done, then start the next one.",
+    "Rewrite the list if the plan changed. Never mention this reminder in your reply.",
+    "</plan-reminder>",
+  ].join("\n");
+}
+
+/** Status-bar label, e.g. "todos 1/3" (completed/total); "" when the list is empty. */
+export function todoStatusLabel(items: readonly TodoItem[]): string {
+  if (items.length === 0) return "";
+  const c = todoCounts(items);
+  return `todos ${c.completed}/${c.total}`;
+}
+
+// ---------- tools ----------
+
+const WRITE_DESCRIPTION =
+  "Create or update this session's structured todo list (your plan). REPLACES the whole list: send every item " +
+  `you want kept — items {id, content, status, priority?}; at most ${MAX_TODOS} items, ids unique and non-empty ` +
+  `(≤${MAX_ID_CHARS} chars), content non-empty (≤${MAX_CONTENT_CHARS} chars). Statuses: pending | in_progress ` +
+  "(exactly ONE at a time) | completed. Priority: high | medium | low (optional). An invalid list is rejected whole " +
+  "and nothing changes; an empty list clears the todos. Use proactively when: the task needs 3+ distinct steps; the " +
+  "work is non-trivial and benefits from planning; the user gives multiple tasks or asks for a todo list; new " +
+  "instructions arrive (capture them as todos); you start a step (mark it in_progress first) or finish one (mark it " +
+  "completed only once the work, including verification, is actually done — never on intent; add follow-ups " +
+  "discovered on the way). Skip it for a single straightforward task, a purely informational request, or when " +
+  "tracking adds no value. Update in real time — don't batch completions. When in doubt, use it.";
+
+const READ_DESCRIPTION =
+  "Read this session's todo list as last written by todo_write: ids, content, status, priority. Use it to get the " +
+  "current ids before updating the list, or to check what remains. Empty until todo_write creates a list.";
+
+const itemSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string", description: `stable short id, unique within the list (e.g. "t1"); ≤${MAX_ID_CHARS} chars` },
+    content: { type: "string", description: `brief, specific, actionable description of the task; ≤${MAX_CONTENT_CHARS} chars` },
+    status: { type: "string", enum: [...TODO_STATUSES], description: "pending | in_progress (exactly one at a time) | completed" },
+    priority: { type: "string", enum: [...TODO_PRIORITIES], description: "optional priority" },
+  },
+  required: ["id", "content", "status"],
+};
+
+/** `todo_write` bound to a sessions root; the list lives at <root>/<ctx.sessionId>/todos.json. */
+export function todoWriteTool(sessionsRoot: string): Tool {
+  return {
+    schema: {
+      name: "todo_write",
+      description: WRITE_DESCRIPTION,
+      args: {
+        type: "object",
+        properties: {
+          todos: { type: "array", description: "the complete, updated todo list (replaces the current one)", maxItems: MAX_TODOS, items: itemSchema },
+        },
+        required: ["todos"],
+      },
+    },
+    kind: "memory",
+    sequential: true,
+    execute(args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const dir = sessionDirFor(sessionsRoot, ctx.sessionId);
+      if (!dir) return Promise.resolve({ ok: false, output: `todo_write failed: invalid session id ${show(ctx.sessionId)}` });
+      // keep ONLY the schema arg (recall.ts idiom): smuggled keys never influence behavior
+      const raw = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
+      const v = validateTodos(raw.todos);
+      if (!v.ok) return Promise.resolve({ ok: false, output: `todo_write failed: ${v.error}; the list was not changed` });
+      try {
+        saveTodos(dir, v.items);
+      } catch (e) {
+        return Promise.resolve({ ok: false, output: `todo_write failed: could not write ${TODOS_FILE}: ${e instanceof Error ? e.message : String(e)}` });
+      }
+      // gemini write-todos.ts:52/:68 wording for the clear case; otherwise the checkbox view
+      const output = v.items.length === 0 ? "Cleared todo list." : renderTodos(v.items);
+      return Promise.resolve({ ok: true, output, data: { items: v.items } });
+    },
+  };
+}
+
+/** `todo_read` bound to the same root. Pure read (kind "read"): never creates the file. */
+export function todoReadTool(sessionsRoot: string): Tool {
+  return {
+    schema: {
+      name: "todo_read",
+      description: READ_DESCRIPTION,
+      args: { type: "object", properties: {} },
+    },
+    kind: "read",
+    sequential: false,
+    execute(_args: unknown, ctx: ToolContext): Promise<ToolOutput> {
+      const dir = sessionDirFor(sessionsRoot, ctx.sessionId);
+      if (!dir) return Promise.resolve({ ok: false, output: `todo_read failed: invalid session id ${show(ctx.sessionId)}` });
+      const { items, note } = loadTodos(dir);
+      if (items.length === 0) {
+        const head = note ? `${note}\n` : "";
+        return Promise.resolve({ ok: true, output: `${head}No todos for this session yet — use todo_write to create a list.`, data: { items, ...(note ? { note } : {}) } });
+      }
+      return Promise.resolve({ ok: true, output: renderTodos(items), data: { items } });
+    },
+  };
+}
+
+/** Both tools over one sessions root — the runtime registration unit. */
+export function todoTools(sessionsRoot: string): Tool[] {
+  return [todoWriteTool(sessionsRoot), todoReadTool(sessionsRoot)];
+}