rovecode 0.3.3 → 0.4.0-beta.2

package/src/tools/task.ts

@@ -1,250 +0,0 @@
-/** `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

@@ -1,320 +0,0 @@
-/** 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)];
-}