typeclaw 0.22.0 → 0.24.0

package/src/agent/todo/continuation.ts

@@ -0,0 +1,71 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+import { type ContinuationLimits, DEFAULT_CONTINUATION_LIMITS, decideContinuation } from './continuation-policy'
+import { consumeRestartKickSuppression, readContinuationState, writeContinuationState } from './continuation-state'
+import { resolveTodoScope, type TodoScope } from './scope'
+import { readTodos } from './store'
+
+export const TODO_CONTINUATION_SOURCE = 'todo-continuation'
+
+export const CONTINUATION_PROMPT = [
+  '---',
+  '**[SYSTEM MESSAGE — not from a human]**',
+  '',
+  'Incomplete todo items remain in your list. Continue working on the next',
+  'pending item now, without asking for permission. Mark each item complete (or',
+  'cancelled) as you finish it by calling `todo_write` with the updated list. If',
+  'you believe all the work is already done, do not just assert it — re-examine',
+  'each remaining item skeptically, verify the work actually landed, and update',
+  'the list accordingly. When everything is genuinely complete, call',
+  '`todo_clear`. Do not acknowledge or reply to this notice; just continue the',
+  'work.',
+  '',
+  '---',
+  '',
+].join('\n')
+
+export type ContinuationInjectResult =
+  | { kind: 'injected'; scope: TodoScope; text: string }
+  | { kind: 'skipped'; reason: string }
+
+export type MaybeInjectContinuationArgs = {
+  agentDir: string
+  origin: SessionOrigin | undefined
+  now?: number
+  limits?: ContinuationLimits
+  newEpisodeId?: () => string
+}
+
+// Decide-and-persist entry point called from the idle path of each origin's
+// drain loop. On `injected`, the caller is responsible for actually delivering
+// `text` into the session (TUI: stream.publish; channel: pendingSystemReminders
+// + drain). The episode mutation is persisted BEFORE returning so a crash
+// between persist and deliver can only UNDER-count (fail-safe: a missed
+// delivery costs one wasted budget slot, never an unbounded loop).
+//
+// The restart-kick one-shot is consumed here even on skip, so the first
+// post-restart idle always burns the suppressor exactly once.
+export async function maybeInjectContinuation(args: MaybeInjectContinuationArgs): Promise<ContinuationInjectResult> {
+  if (args.origin === undefined) return { kind: 'skipped', reason: 'no-origin' }
+  const scope = resolveTodoScope(args.origin)
+  if (scope === null) return { kind: 'skipped', reason: 'no-scope' }
+
+  const now = args.now ?? Date.now()
+  const limits = args.limits ?? DEFAULT_CONTINUATION_LIMITS
+  const newEpisodeId = args.newEpisodeId ?? (() => crypto.randomUUID())
+
+  const todos = await readTodos(args.agentDir, scope)
+  const state = await readContinuationState(args.agentDir, scope)
+
+  const decision = decideContinuation({ state, todos, limits, now, newEpisodeId })
+
+  if (decision.kind === 'skip') {
+    if (state.suppressNextIdleNudgeReason !== null) {
+      await writeContinuationState(args.agentDir, scope, consumeRestartKickSuppression(state))
+    }
+    return { kind: 'skipped', reason: decision.reason }
+  }
+
+  await writeContinuationState(args.agentDir, scope, { ...state, episode: decision.episode })
+  return { kind: 'injected', scope, text: CONTINUATION_PROMPT }
+}

package/src/agent/todo/scope.ts

@@ -0,0 +1,77 @@
+import type { SessionOrigin } from '@/agent/session-origin'
+
+// A todo scope is the durable identity a todo list hangs off. It is
+// deliberately NOT the raw sessionId: sessionIds churn across TUI reconnects
+// and every cron fire, and a channel session can roll to a fresh sessionId on
+// stale-rollover (see src/channels/router.ts SESSION_FRESHNESS_TTL_MS). Keying
+// on origin identity instead lets a todo list survive those transitions so
+// interrupted work can be resumed.
+//
+// `key` is a filesystem-safe relative path segment (no leading slash, no `..`).
+// `kind` mirrors the originating `SessionOrigin['kind']` so the continuation
+// injector can enforce that a nudge only fires into a live session whose origin
+// matches the scope (the eligible-session invariant).
+export type TodoScope = {
+  kind: 'tui' | 'channel' | 'cron'
+  key: string
+}
+
+// Resolve the durable todo scope for a session origin, or `null` when the
+// origin owns no todo list.
+//
+// - tui      → singleton `tui`. There is no stable per-operator identity (the
+//              sessionId churns on every reconnect and the restart handoff is
+//              once-per-boot), so TUI is modeled as one global workstream per
+//              agent. Concurrent TUI attaches therefore share a scope; this is
+//              an accepted, documented limitation.
+// - channel  → keyed by the adapter/workspace/chat/thread tuple, matching how
+//              channels/sessions.json already identifies a conversation. This
+//              survives both container restart and stale-rollover.
+// - cron     → keyed by jobId. The sessionId is useless here (fresh every
+//              fire); the job is the durable identity.
+// - subagent → null. Subagents do not own continuation; their parent does.
+// - system   → null. Runtime infrastructure (memory/backup) is not
+//              user-delegated work and must never auto-continue.
+export function resolveTodoScope(origin: SessionOrigin): TodoScope | null {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui', key: 'tui' }
+    case 'channel':
+      return { kind: 'channel', key: channelScopeKey(origin) }
+    case 'cron':
+      return { kind: 'cron', key: `cron/${encodeComponent(origin.jobId)}` }
+    case 'subagent':
+    case 'system':
+      return null
+    default: {
+      const _exhaustive: never = origin
+      void _exhaustive
+      return null
+    }
+  }
+}
+
+function channelScopeKey(origin: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
+  const parts = [
+    encodeComponent(origin.adapter),
+    encodeComponent(origin.workspace),
+    encodeComponent(origin.chat),
+    encodeComponent(origin.thread),
+  ]
+  return `channel/${parts.join(':')}`
+}
+
+// Encode one scope component injectively. Every component is emitted as a
+// discriminant prefix plus its `encodeURIComponent` form:
+//   - null          → `n`        (the channel-root / no-thread case)
+//   - any string s  → `s<encoded>`
+// The prefix makes the three cases pairwise distinguishable that lossy schemes
+// confused: a null thread vs a literal "n" string, an empty string vs a
+// literal "_empty" string, and any value vs another whose unsafe chars happen
+// to map together. `encodeURIComponent` is itself injective and never emits
+// `/` or `:`, so the joined key is both a single filesystem-safe path segment
+// and a collision-free identity for the conversation whose todo file it names.
+function encodeComponent(value: string | null): string {
+  if (value === null) return 'n'
+  return `s${encodeURIComponent(value)}`
+}

package/src/agent/todo/store.ts

@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join, relative } from 'node:path'
+
+import type { TodoScope } from './scope'
+
+export const TODO_STATUSES = ['pending', 'in_progress', 'completed', 'cancelled'] as const
+export type TodoStatus = (typeof TODO_STATUSES)[number]
+
+export const TODO_PRIORITIES = ['high', 'medium', 'low'] as const
+export type TodoPriority = (typeof TODO_PRIORITIES)[number]
+
+export type Todo = {
+  content: string
+  status: TodoStatus
+  priority?: TodoPriority
+  id?: string
+}
+
+type TodoFile = {
+  version: 1
+  todos: Todo[]
+}
+
+export function todoDir(agentDir: string): string {
+  return join(agentDir, 'todo')
+}
+
+// Defense-in-depth: the resolved file must stay inside todo/. Scope keys from
+// resolveTodoScope are already collision- and traversal-safe, but this function
+// is an exported primitive — a future caller passing a hand-built scope like
+// `{ key: '../sessions/x' }` would otherwise escape. We assert here rather than
+// trust every caller to use resolveTodoScope.
+export function todoContentPath(agentDir: string, scope: TodoScope): string {
+  const dir = todoDir(agentDir)
+  const path = join(dir, `${scope.key}.json`)
+  const rel = relative(dir, path)
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`todo scope key escapes the todo directory: ${JSON.stringify(scope.key)}`)
+  }
+  return path
+}
+
+export async function readTodos(agentDir: string, scope: TodoScope): Promise<Todo[]> {
+  const path = todoContentPath(agentDir, scope)
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (err) {
+    if (isEnoent(err)) return []
+    throw err
+  }
+  let parsed: Partial<TodoFile>
+  try {
+    parsed = JSON.parse(raw) as Partial<TodoFile>
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed.todos)) return []
+  // The file is force-committed and hand-editable, so a corrupt or partially
+  // edited entry can appear. Drop anything that is not a well-formed Todo
+  // rather than let a `null`/malformed item crash incompleteTodos (`t.status`)
+  // or surface as trusted state to the model.
+  return parsed.todos.filter(isValidTodo)
+}
+
+function isValidTodo(value: unknown): value is Todo {
+  if (typeof value !== 'object' || value === null) return false
+  const t = value as Record<string, unknown>
+  if (typeof t.content !== 'string' || t.content.length === 0) return false
+  if (typeof t.status !== 'string' || !(TODO_STATUSES as readonly string[]).includes(t.status)) return false
+  if (t.priority !== undefined && !(TODO_PRIORITIES as readonly string[]).includes(t.priority as string)) return false
+  if (t.id !== undefined && typeof t.id !== 'string') return false
+  return true
+}
+
+// Write is atomic (temp file + rename) so a crash mid-write can never leave a
+// half-serialized JSON file that the next read would throw on. Mirrors the
+// channels/sessions.json writer. A scope is normally owned by a single live
+// session (see resolveTodoScope), so the only concurrent writers are the rare
+// duplicate-attach case, where last-writer-wins on the rename is acceptable —
+// the alternative (lost-update detection) is not worth a lock for a todo list.
+export async function writeTodos(agentDir: string, scope: TodoScope, todos: Todo[]): Promise<void> {
+  const path = todoContentPath(agentDir, scope)
+  const payload: TodoFile = { version: 1, todos }
+  await mkdir(dirname(path), { recursive: true })
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
+  await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
+  await rename(tmp, path)
+}
+
+export function incompleteTodos(todos: readonly Todo[]): Todo[] {
+  return todos.filter((t) => t.status !== 'completed' && t.status !== 'cancelled')
+}
+
+function isEnoent(err: unknown): boolean {
+  return typeof err === 'object' && err !== null && (err as { code?: unknown }).code === 'ENOENT'
+}

package/src/agent/tool-not-found-nudge.ts

@@ -0,0 +1,119 @@
+// Minimal structural view of the pieces of pi's AgentSession this module
+// touches. Declared locally (not imported) so the pure nudge logic stays
+// testable with a hand-rolled fake and does not drag in the full session type.
+export type NudgeableSession = {
+  subscribe: (listener: (event: unknown) => void) => () => void
+  steer: (text: string) => Promise<void>
+}
+
+const NOT_FOUND_RE = /^Tool (.+?) not found$/
+
+// Levenshtein distance ceiling for a name to count as "did you mean". A typo
+// like web_search -> websearch is distance 1 (one '_' removed); read_file ->
+// read is larger but still a clear prefix relationship. Keeping the ceiling
+// small avoids suggesting an unrelated tool for a genuinely unknown name.
+const MAX_SUGGESTION_DISTANCE = 4
+
+export function extractNotFoundToolName(resultText: string): string | null {
+  const match = NOT_FOUND_RE.exec(resultText.trim())
+  return match?.[1] ?? null
+}
+
+export function closestToolName(requested: string, known: readonly string[]): string | null {
+  let best: string | null = null
+  let bestDistance = Number.POSITIVE_INFINITY
+  for (const candidate of known) {
+    if (candidate === requested) return candidate
+    const distance = boundedLevenshtein(requested, candidate, MAX_SUGGESTION_DISTANCE)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = candidate
+    }
+  }
+  return bestDistance <= MAX_SUGGESTION_DISTANCE ? best : null
+}
+
+export function renderToolNotFoundNudge(requested: string, suggestion: string): string {
+  return (
+    `<system-reminder>\n` +
+    `You called the tool \`${requested}\`, which does not exist. ` +
+    `Did you mean \`${suggestion}\`? Re-issue the call using the exact name \`${suggestion}\`.\n` +
+    `</system-reminder>`
+  )
+}
+
+export function buildToolNotFoundNudge(resultText: string, known: readonly string[]): string | null {
+  const requested = extractNotFoundToolName(resultText)
+  if (requested === null) return null
+  const suggestion = closestToolName(requested, known)
+  if (suggestion === null || suggestion === requested) return null
+  return renderToolNotFoundNudge(requested, suggestion)
+}
+
+function firstTextChunk(result: unknown): string | null {
+  const content = (result as { content?: unknown })?.content
+  if (!Array.isArray(content)) return null
+  for (const part of content) {
+    if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+      const text = (part as { text?: unknown }).text
+      if (typeof text === 'string') return text
+    }
+  }
+  return null
+}
+
+// Watches a session's tool-execution events and, when the model calls a tool
+// name that does not exist but is a near-miss of a real one, steers a
+// "did you mean" reminder into the running turn so the model self-corrects.
+//
+// This lives here, on the session event stream, because pi-agent-core's
+// `prepareToolCall` returns the `Tool X not found` result BEFORE any
+// `beforeToolCall`/`afterToolCall` hook runs — so TypeClaw's tool.before/after
+// buses never see an unknown tool name. The emitted `tool_execution_end` event
+// is the only seam reachable without forking pi. `steer` (not `followUp`)
+// delivers the reminder after the current assistant turn's tool calls settle,
+// which is exactly when the model is ready to retry.
+//
+// The model re-issues the call under the suggested (canonical) name, so every
+// security guard, budget, and loop-guard keyed on that real name applies
+// normally — unlike a silent alias, this rescue path cannot bypass policy.
+export function attachToolNotFoundNudge(session: NudgeableSession, knownToolNames: readonly string[]): () => void {
+  const known = [...new Set(knownToolNames)]
+  return session.subscribe((event) => {
+    const e = event as { type?: unknown; isError?: unknown; result?: unknown }
+    if (e?.type !== 'tool_execution_end' || e.isError !== true) return
+    const text = firstTextChunk(e.result)
+    if (text === null) return
+    const nudge = buildToolNotFoundNudge(text, known)
+    if (nudge === null) return
+    void session.steer(nudge)
+  })
+}
+
+// Wagner–Fischer with an early bail-out once every cell in a row exceeds the
+// ceiling: a name far from every candidate never produces a suggestion, and
+// the bound keeps the scan cheap when the known-tool list is large.
+function boundedLevenshtein(a: string, b: string, ceiling: number): number {
+  if (a === b) return 0
+  if (Math.abs(a.length - b.length) > ceiling) return ceiling + 1
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  let curr = Array.from({ length: b.length + 1 }, () => 0)
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i
+    let rowMin = i
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1
+      const deletion = (prev[j] ?? 0) + 1
+      const insertion = (curr[j - 1] ?? 0) + 1
+      const substitution = (prev[j - 1] ?? 0) + cost
+      const cell = Math.min(deletion, insertion, substitution)
+      curr[j] = cell
+      if (cell < rowMin) rowMin = cell
+    }
+    if (rowMin > ceiling) return ceiling + 1
+    ;[prev, curr] = [curr, prev]
+  }
+  return prev[b.length] ?? ceiling + 1
+}

package/src/agent/tools/channel-reply.ts

@@ -80,6 +80,14 @@ export function createChannelReplyTool({
             'Do not set it just to seem responsive; only when genuine multi-step work follows in the same turn.',
         }),
       ),
+      resolve_review_thread: Type.Optional(
+        Type.Boolean({
+          description:
+            'GitHub only. Set `true` when this reply acknowledges that a review-comment thread YOU authored has been addressed, to resolve (close) that thread atomically with the reply. ' +
+            'The thread is resolved BEFORE the acknowledgement is posted, and only if its root comment is yours — so it never closes a human reviewer\'s thread, and a failed resolve blocks the misleading "looks resolved" reply. ' +
+            'Valid only on a github session replying inside a thread (the origin must carry a `thread`). Ignored elsewhere.',
+        }),
+      ),
     }),
 
     async execute(_toolCallId, params) {
@@ -123,6 +131,22 @@ export function createChannelReplyTool({
         }
       }
 
+      // Resolve BEFORE posting: a successful channel_reply ends the turn, so a
+      // resolve attempted "after" the ack would never run (the exact bug this
+      // flag fixes). Resolve-failure blocks the reply so the agent never posts
+      // a "looks resolved" ack next to a still-open thread; the router enforces
+      // that only the bot's own threads can be resolved.
+      if (params.resolve_review_thread === true) {
+        const resolveError = await resolveReviewThreadBeforeReply(router, origin)
+        if (resolveError !== null) {
+          logger.warn(formatChannelToolFailure('channel_reply', resolveError))
+          return {
+            content: [{ type: 'text' as const, text: `channel_reply denied: ${resolveError}` }],
+            details: { ok: false, error: resolveError },
+          }
+        }
+      }
+
       const result = await router.send({
         adapter: origin.adapter,
         workspace: origin.workspace,
@@ -192,6 +216,33 @@ export function createChannelReplyTool({
   })
 }
 
+// Returns an error string when the resolve should block the reply, or null
+// when it's safe to proceed. Only `no-match` (the thread is already gone, so
+// there's nothing to close) joins success as non-blocking; every hard failure
+// — wrong author, permission denial, HTTP 404 on a misdirected lookup,
+// transient API error — blocks, so the agent never claims a thread is settled
+// when the resolve did not actually run.
+async function resolveReviewThreadBeforeReply(
+  router: ChannelRouter,
+  origin: ChannelReplyOrigin,
+): Promise<string | null> {
+  if (origin.adapter !== 'github') {
+    return 'resolve_review_thread is only supported on github sessions.'
+  }
+  if (origin.thread === null) {
+    return 'resolve_review_thread requires replying inside a review thread (no thread on this origin).'
+  }
+  const result = await router.resolveReviewThread({
+    adapter: origin.adapter,
+    workspace: origin.workspace,
+    chat: origin.chat,
+    rootCommentId: origin.thread,
+  })
+  if (result.ok) return null
+  if (result.code === 'no-match') return null
+  return `could not resolve review thread: ${result.error}`
+}
+
 // Tool results reach the model as USER-role messages (OpenAI / Anthropic
 // tool-API contract — the engine cannot tag them as system). Without this
 // marker a persona-rich model reads its own echo as a fresh user inbound

package/src/agent/tools/restart.ts

@@ -2,6 +2,7 @@ import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
 import { requestContainerRestart } from '@/agent/restart'
+import type { RestartHandoffOrigin } from '@/agent/restart-handoff'
 import type { Stream } from '@/stream'
 
 const EXIT_DELAY_MS = 500
@@ -47,11 +48,15 @@ export type CreateRestartToolOptions = {
   // so the `typeclaw.restart-self` custom message entry that was just
   // appended is part of the LLM context on the next turn. When omitted,
   // no handoff is written — the new container cold-starts and no
-  // "I'm back" greeting fires. Gates the handoff on the origin being a
-  // TUI session: channel/cron/subagent origins should pass undefined so
-  // the next boot does not produce a stray channel post or unattended
-  // greeting (see issue #291's scoping concerns).
+  // "I'm back" greeting fires. Written for persisted TUI and channel
+  // origins; cron/subagent/system origins pass undefined so the next boot
+  // does not resume an unattended session.
   originatingSessionFile?: string
+  // Which subsystem owns resuming the originating session on the next boot
+  // (tui → websocket open handler; channel → channel router startup). Required
+  // alongside `originatingSessionFile` for the handoff to be written; omit to
+  // skip the handoff. See buildRestartHandoffWiring in src/agent/index.ts.
+  handoffOrigin?: RestartHandoffOrigin
 }
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
@@ -69,6 +74,7 @@ export function createRestartTool({
   ackTimeoutMs,
   agentDir,
   originatingSessionFile,
+  handoffOrigin,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
 
@@ -114,6 +120,7 @@ export function createRestartTool({
         ...(stream !== undefined ? { stream } : {}),
         ...(agentDir !== undefined ? { agentDir } : {}),
         ...(originatingSessionFile !== undefined ? { originatingSessionFile } : {}),
+        ...(handoffOrigin !== undefined ? { handoffOrigin } : {}),
       })
       if (!result.ok) {
         const details: RestartToolDetails = { ok: false, containerName, reason: result.reason }

package/src/agent/tools/todo/index.ts

@@ -0,0 +1,119 @@
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { SessionOrigin } from '@/agent/session-origin'
+import { resolveTodoScope, type TodoScope } from '@/agent/todo/scope'
+import { incompleteTodos, type Todo, TODO_PRIORITIES, TODO_STATUSES, readTodos, writeTodos } from '@/agent/todo/store'
+
+export type CreateTodoToolsOptions = {
+  agentDir: string
+  getOrigin: () => SessionOrigin | undefined
+}
+
+const NO_SCOPE_NOTICE =
+  'Todos are owned by the originating session. This session (a subagent, system task, or one ' +
+  'with no resolvable origin) does not own a todo list, so the call was a no-op.'
+
+type TodoToolDetails = {
+  ok: boolean
+  reason?: string
+  total?: number
+  remaining?: number
+}
+
+// Resolve the scope for the current origin, or null when this session owns no
+// todo list. An UNDEFINED origin is treated as no-scope, NOT defaulted to the
+// shared TUI scope — defaulting would fail open, silently routing an unknown
+// actor's todos into the operator's global `tui` list.
+function scopeForOrigin(getOrigin: () => SessionOrigin | undefined): TodoScope | null {
+  const origin = getOrigin()
+  return origin === undefined ? null : resolveTodoScope(origin)
+}
+
+const TODO_ITEM = Type.Object({
+  content: Type.String({ minLength: 1, description: 'What the task is.' }),
+  status: Type.Union(
+    TODO_STATUSES.map((s) => Type.Literal(s)),
+    { description: 'One of: pending, in_progress, completed, cancelled.' },
+  ),
+  priority: Type.Optional(Type.Union(TODO_PRIORITIES.map((p) => Type.Literal(p)))),
+  id: Type.Optional(Type.String()),
+})
+
+export function createTodoTools({ agentDir, getOrigin }: CreateTodoToolsOptions) {
+  const writeTool = defineTool({
+    name: 'todo_write',
+    label: 'Write Todos',
+    description:
+      'Replace your entire todo list for this session with the provided items. Maintain a todo ' +
+      'list for any multi-step or long-running task so that if this session is interrupted ' +
+      '(restart, crash, or a later turn), you can resume the remaining work instead of silently ' +
+      'dropping it. Mark items `completed` (or `cancelled`) as you finish them by writing the full ' +
+      'list again with updated statuses. This is a full replace, not a merge: include every item ' +
+      'you still care about on each call.',
+    parameters: Type.Object({
+      todos: Type.Array(TODO_ITEM, { description: 'The complete todo list. Replaces any prior list.' }),
+    }),
+    async execute(_toolCallId, params) {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      const todos = params.todos as Todo[]
+      await writeTodos(agentDir, scope, todos)
+      const remaining = incompleteTodos(todos).length
+      const details: TodoToolDetails = { ok: true, total: todos.length, remaining }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Saved ${todos.length} todo(s); ${remaining} remaining (${todos.length - remaining} done).`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+
+  const readTool = defineTool({
+    name: 'todo_read',
+    label: 'Read Todos',
+    description: 'Return your current todo list for this session. Use it to re-sync after an interruption.',
+    parameters: Type.Object({}),
+    async execute() {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      const todos = await readTodos(agentDir, scope)
+      const details: TodoToolDetails = { ok: true, total: todos.length }
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(todos, null, 2) }],
+        details,
+      }
+    },
+  })
+
+  const clearTool = defineTool({
+    name: 'todo_clear',
+    label: 'Clear Todos',
+    description:
+      'Empty your todo list for this session. Call this when all work is genuinely done or the ' +
+      'task was abandoned, so the runtime stops tracking pending work.',
+    parameters: Type.Object({}),
+    async execute() {
+      const scope = scopeForOrigin(getOrigin)
+      if (scope === null) {
+        const details: TodoToolDetails = { ok: false, reason: 'no-scope' }
+        return { content: [{ type: 'text' as const, text: NO_SCOPE_NOTICE }], details }
+      }
+      await writeTodos(agentDir, scope, [])
+      const details: TodoToolDetails = { ok: true }
+      return { content: [{ type: 'text' as const, text: 'Todo list cleared.' }], details }
+    },
+  })
+
+  return [writeTool, readTool, clearTool]
+}

package/src/bundled-plugins/backup/runner.ts

@@ -5,7 +5,7 @@ export const COMMIT_TIMEOUT_MS = 30_000
 export const NETWORK_TIMEOUT_MS = 60_000
 
 const RUNTIME_OWNED_PREFIXES = ['memory/'] as const
-const FORCE_ADD_PREFIXES = ['sessions/'] as const
+const FORCE_ADD_PREFIXES = ['sessions/', 'todo/'] as const
 
 const NONINTERACTIVE_ENV = {
   GIT_TERMINAL_PROMPT: '0',