typeclaw 0.36.8 → 0.37.0

package/README.md

@@ -31,7 +31,7 @@ If you're like me, TypeClaw is the right choice. If not, that's fine too.
 
 - 🐳 **Sandboxed by default** — every agent runs in its own Docker container with `.env` injection and bind-mounted host folders
 - 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, commands, and typed config
-- 💬 **Multi-channel** — Slack, Discord, Telegram, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
+- 💬 **Multi-channel** — Slack, Discord, Telegram, LINE, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
 - 🔎 **Web research** — bundled `scout` subagent plus first-class `web_search` and `web_fetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
@@ -97,7 +97,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the recommended local dev loop (`bu
 
 ## Acknowledgments
 
-- **Multi-channel** is powered by [agent-messenger](https://github.com/agent-messenger/agent-messenger) — every non-GitHub adapter (`slack-bot`, `discord-bot`, `telegram-bot`, `kakaotalk`) is built on its SDK. Thanks to the maintainers for the credential extraction, listener protocols, and platform coverage that made multi-channel a feature instead of a year-long project.
+- **Multi-channel** is powered by [agent-messenger](https://github.com/agent-messenger/agent-messenger) — every non-GitHub adapter (`slack-bot`, `discord-bot`, `telegram-bot`, `line`, `kakaotalk`) is built on its SDK. Thanks to the maintainers for the credential extraction, listener protocols, and platform coverage that made multi-channel a feature instead of a year-long project.
 - **Subagent architecture** is inspired by [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) by [@code-yeongyu](https://github.com/code-yeongyu). Thanks for the shape that made this clean.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.36.8",
+  "version": "0.37.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -44,6 +44,7 @@
   "dependencies": {
     "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
+    "@huggingface/transformers": "4.2.0",
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -54,6 +55,7 @@
     "cron-parser": "^5.5.0",
     "jq-wasm": "^1.1.0-jq-1.8.1",
     "jsdom": "^29.0.2",
+    "proper-lockfile": "^4.1.2",
     "qrcode": "^1.5.4",
     "turndown": "^7.2.4",
     "zod": "^4.3.6"
@@ -66,7 +68,6 @@
     "@types/qrcode": "^1.5.6",
     "@types/sinonjs__fake-timers": "^15.0.1",
     "@types/turndown": "^5.0.6",
-    "@types/ws": "^8.18.1",
     "@typescript/native-preview": "^7.0.0-dev.20260416.1",
     "oxfmt": "^0.45.0",
     "oxlint": "^1.60.0"

package/src/agent/index.ts

@@ -15,7 +15,7 @@ import { loadMemory } from '@/bundled-plugins/memory/load-memory'
 import type { ChannelRouter } from '@/channels/router'
 import type { ReactionRef } from '@/channels/types'
 import { getConfig, resolveModel, resolveProfile } from '@/config'
-import { defaultThinkingLevelForRef, providerForModelRef, type KnownModelRef } from '@/config/providers'
+import { defaultThinkingLevelForRef, providerForModelRef, type ModelRef } from '@/config/providers'
 import { renderMcpCatalog } from '@/mcp/catalog'
 import type { McpManager } from '@/mcp/manager'
 import { createMcpDispatcherTools, MCP_DISPATCHER_TOOL_NAMES } from '@/mcp/tools'
@@ -196,7 +196,7 @@ export type CreateSessionOptions = {
   // pinned to the next ref in the chain after the previous one failed. When
   // set, `profile` is still recorded for the fallback-warning bookkeeping;
   // the profile→refs resolution is skipped.
-  refOverride?: KnownModelRef
+  refOverride?: ModelRef
   // Defensive ceiling on cumulative bytes of tool-result text per session,
   // applied to the named tools only. See `src/agent/tool-result-budget.ts`
   // for the rationale. Intended for subagents that read large files
@@ -221,6 +221,12 @@ export type CreateSessionOptions = {
   subagentRegistry?: SubagentRegistry
   createSessionForSubagent?: CreateSessionForSubagent
   allowBackgroundFromSubagent?: boolean
+  // When true, the `# Memory` section is omitted from the system prompt and
+  // long-term memory is injected per-turn into the user prompt instead (the
+  // memory plugin's vector `session.turn.start` path). Derived once at boot
+  // from `memory.vector.enabled`, which is restart-required — so the boot
+  // snapshot stays coherent with the per-turn injection decision.
+  suppressSystemMemory?: boolean
 }
 
 export type CreateSessionResult = {
@@ -241,7 +247,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
   // exactly what they're doing.
   // `refOverride` lets the model-fallback helper pin a specific entry from
   // the chain when it recreates a session after the previous ref failed.
-  const activeRef: KnownModelRef = options.refOverride ?? resolved.ref
+  const activeRef: ModelRef = options.refOverride ?? resolved.ref
   const { authStorage, modelRegistry } = getAuthFor(providerForModelRef(activeRef))
 
   const materializedSkills =
@@ -270,6 +276,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
           ...(options.mcpManager !== undefined ? { mcpManager: options.mcpManager } : {}),
           ...(options.subagentRegistry !== undefined ? { subagentRegistry: options.subagentRegistry } : {}),
+          ...(options.suppressSystemMemory !== undefined ? { suppressSystemMemory: options.suppressSystemMemory } : {}),
         })
 
   const getOrigin: () => SessionOrigin | undefined =
@@ -944,6 +951,12 @@ export type CreateResourceLoaderOptions = {
   // 'full' to force the heavy prompt even on an unattended origin (rarely
   // useful; mostly an escape hatch for ad-hoc debugging).
   mode?: SystemPromptMode
+  // When true, the `# Memory` section is omitted from the system prompt and
+  // long-term memory is injected per-turn into the user prompt instead (the
+  // memory plugin's vector `session.turn.start` path). Derived once at boot
+  // from `memory.vector.enabled` — vector is restart-required, so the boot
+  // snapshot is coherent with the per-turn injection decision.
+  suppressSystemMemory?: boolean
 }
 
 // Origins where the operator-facing DEFAULT_SYSTEM_PROMPT, git-nudge, and the
@@ -1024,8 +1037,8 @@ export type SystemPromptComposition = {
 //    memory/ after every turn, so the dirty-files list is empty most of
 //    the time.
 // 3. memorySection — volatile: MEMORY.md grows on every dream cycle and
-//    memory/yyyy-MM-dd.md grows after every channel turn that triggers
-//    memory-logger.
+//    memory/streams/yyyy-MM-dd.jsonl grows after every channel turn that
+//    triggers memory-logger.
 //
 // The wall-clock anchor that used to live here as `## Now` moved out
 // entirely. It is now injected into the user turn at each `session.prompt`
@@ -1099,12 +1112,19 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   // gather point.
   const selfPromise = loadSelf(agentDir)
   const gitNudgeSettled = mode === 'slim' ? Promise.resolve(ok('')) : settle(renderGitNudge(agentDir))
-  const memorySettled = settle(
-    loadMemory(agentDir, {
-      ...(options.origin !== undefined ? { origin: options.origin } : {}),
-      ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
-    }),
-  )
+  // Vector agents omit the `# Memory` section entirely: long-term memory is
+  // injected per-turn into the user prompt by the memory plugin's vector
+  // `session.turn.start` hook. Keeping both would double-inject and re-break the
+  // cache prefix this change exists to protect — the invariant is
+  // `suppressSystemMemory === memory.vector.enabled`.
+  const memorySettled = options.suppressSystemMemory
+    ? Promise.resolve(ok(''))
+    : settle(
+        loadMemory(agentDir, {
+          ...(options.origin !== undefined ? { origin: options.origin } : {}),
+          ...(options.plugins?.sessionId !== undefined ? { currentSessionId: options.plugins.sessionId } : {}),
+        }),
+      )
 
   let self = await selfPromise
 

package/src/agent/live-sessions.ts

@@ -1,8 +1,16 @@
 import type { AgentSession } from './index'
+import type { MinimalSessionOrigin } from './session-meta'
 
 export type LiveAgentSession = {
   sessionId: string
   session: Pick<AgentSession, 'subscribe'>
+  // Surfaced by the inspect picker for sessions not yet on disk: pi-coding-agent
+  // defers the first .jsonl write until the first assistant message, so without
+  // these a mid-reply session is invisible. Optional so subscribe-only test
+  // harnesses can still register `{ sessionId, session }`; live-listing skips
+  // entries lacking an origin.
+  origin?: MinimalSessionOrigin
+  registeredAtMs?: number
 }
 
 export class LiveSessionRegistry {
@@ -24,6 +32,10 @@ export class LiveSessionRegistry {
     return this.entries.has(sessionId)
   }
 
+  listLive(): LiveAgentSession[] {
+    return [...this.entries.values()].filter((e) => e.origin !== undefined)
+  }
+
   size(): number {
     return this.entries.size
   }

package/src/agent/model-fallback.ts

@@ -1,6 +1,6 @@
 import { resolveProfile } from '@/config'
 import type { Models } from '@/config/config'
-import type { KnownModelRef } from '@/config/providers'
+import type { KnownModelRef, ModelRef } from '@/config/providers'
 
 import type { AgentSession } from './index'
 import { subscribeProviderErrors } from './provider-error'
@@ -15,18 +15,20 @@ import { renderTurnTimeAnchor } from './system-prompt'
 //   the final entry, on full-chain failure). Callers that need to keep using
 //   the session for subsequent turns store these in their state; callers that
 //   tear down per-turn (cron) just call `dispose()` and discard.
-export type FallbackPromptResult = {
+type FallbackModelRef = KnownModelRef | ModelRef
+
+export type FallbackPromptResult<TRef extends FallbackModelRef = ModelRef> = {
   success: boolean
-  refUsed: KnownModelRef
-  attempts: FallbackAttempt[]
+  refUsed: TRef
+  attempts: FallbackAttempt<TRef>[]
   session: AgentSession
   dispose: () => Promise<void>
   // When `success === false`, this is the error from the final attempt.
   lastError?: Error
 }
 
-export type FallbackAttempt = {
-  ref: KnownModelRef
+export type FallbackAttempt<TRef extends FallbackModelRef = ModelRef> = {
+  ref: TRef
   // 'hard' = session.prompt() threw. 'soft' = pi-coding-agent surfaced an
   // upstream error via stopReason: 'error' on the final assistant message.
   // 'success' = the turn finished cleanly.
@@ -40,7 +42,7 @@ export type FallbackAttempt = {
 //
 // Exported so callers can introspect the chain (e.g. logs, telemetry) before
 // firing the prompt — useful for `[cron] ${jobId}: trying chain a → b → c`.
-export function resolveFallbackChain(models: Models, profile: string | undefined): KnownModelRef[] {
+export function resolveFallbackChain(models: Models, profile: string | undefined): ModelRef[] {
   return resolveProfile(models, profile).refs
 }
 
@@ -62,18 +64,18 @@ export function resolveFallbackChain(models: Models, profile: string | undefined
 // (console.error in the server drain, channel reaction in the router,
 // cron-job status). This keeps the helper composable with the existing
 // error-handling code at each call site.
-export async function promptWithFallback(opts: {
-  refs: KnownModelRef[]
+export async function promptWithFallback<TRef extends FallbackModelRef>(opts: {
+  refs: TRef[]
   text: string
-  createSessionForRef: (ref: KnownModelRef) => Promise<{ session: AgentSession; dispose: () => Promise<void> }>
+  createSessionForRef: (ref: TRef) => Promise<{ session: AgentSession; dispose: () => Promise<void> }>
   // Called after each non-final attempt so callers can log the per-attempt
   // failure with their own context (sessionId, channel key, job id, ...).
-  onAttemptFailed?: (attempt: FallbackAttempt) => void
-}): Promise<FallbackPromptResult> {
+  onAttemptFailed?: (attempt: FallbackAttempt<TRef>) => void
+}): Promise<FallbackPromptResult<TRef>> {
   if (opts.refs.length === 0) {
     throw new Error('promptWithFallback: refs[] must be non-empty')
   }
-  const attempts: FallbackAttempt[] = []
+  const attempts: FallbackAttempt<TRef>[] = []
   let lastError: Error | undefined
   for (let i = 0; i < opts.refs.length; i++) {
     const ref = opts.refs[i]!
@@ -92,7 +94,7 @@ export async function promptWithFallback(opts: {
         await session.prompt(`${renderTurnTimeAnchor()}\n\n${opts.text}`)
       } catch (err) {
         const error = err instanceof Error ? err : new Error(String(err))
-        const attempt: FallbackAttempt = { ref, outcome: 'hard', errorMessage: error.message }
+        const attempt: FallbackAttempt<TRef> = { ref, outcome: 'hard', errorMessage: error.message }
         attempts.push(attempt)
         lastError = error
         if (!isLast) opts.onAttemptFailed?.(attempt)
@@ -104,7 +106,7 @@ export async function promptWithFallback(opts: {
         continue
       }
       if (softError !== undefined) {
-        const attempt: FallbackAttempt = { ref, outcome: 'soft', errorMessage: softError.message }
+        const attempt: FallbackAttempt<TRef> = { ref, outcome: 'soft', errorMessage: softError.message }
         attempts.push(attempt)
         lastError = softError
         if (!isLast) opts.onAttemptFailed?.(attempt)

package/src/agent/model-overrides.ts

@@ -1,6 +1,6 @@
 import type { Api, Model } from '@mariozechner/pi-ai'
 
-import { providerForModelRef, type KnownModelRef, type KnownProviderId } from '@/config/providers'
+import { providerForModelRef, type KnownModelRef, type KnownProviderId, type ModelRef } from '@/config/providers'
 
 // Providers whose base URL can be swapped to an upstream-compatible gateway at
 // runtime. Each env var mirrors the upstream SDK's own name so a credential /
@@ -26,7 +26,7 @@ type OverridableProviderId = keyof typeof PROVIDER_BASE_URL_ENV
 // data that must never be mutated.
 export function applyModelRuntimeOverrides<TApi extends Api>(
   model: Model<TApi>,
-  ref: KnownModelRef,
+  ref: KnownModelRef | ModelRef | string,
   env: NodeJS.ProcessEnv = process.env,
 ): Model<TApi> {
   const providerId = providerForModelRef(ref)

package/src/agent/session-meta.ts

@@ -1,5 +1,15 @@
+import type { LiveSessionOriginPayload } from '@/shared'
+
 import type { SessionOrigin } from './session-origin'
 
+// Bidirectional structural equality with the wire mirror in @/shared/protocol.
+// @/shared cannot import this module (it is a leaf), so the type cannot be
+// shared directly; these assignments fail typecheck if either side drifts.
+const _originIsWireCompatible: LiveSessionOriginPayload = null as unknown as MinimalSessionOrigin
+const _wireIsOriginCompatible: MinimalSessionOrigin = null as unknown as LiveSessionOriginPayload
+void _originIsWireCompatible
+void _wireIsOriginCompatible
+
 export const SESSION_META_CUSTOM_TYPE = 'typeclaw.session-meta'
 
 export type SessionMetaPayload = {

package/src/agent/subagents.ts

@@ -262,15 +262,24 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
         ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
         : undefined
     const userPromptForTurn = override?.userPrompt ?? options.userPrompt
+    // Per-turn memory injection for vector agents: subagents have no
+    // system-prompt `# Memory` section (their prompt is a systemPromptOverride),
+    // so the turn-start hook renders memory into `retrievalContext.results`,
+    // appended to the user turn below. Empty for non-vector agents.
+    const retrievalContext = { results: '' }
     try {
       if (hooks && turnEvent !== undefined) {
-        await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn })
+        await hooks.runSessionTurnStart({ ...turnEvent, userPrompt: userPromptForTurn, retrievalContext })
       }
       if (backgroundDrain !== undefined) {
         drainWatch = beginSubagentDrainWatch(backgroundDrain)
       }
       try {
-        await session.prompt(`${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`)
+        const turnText =
+          retrievalContext.results.length > 0
+            ? `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}\n\n${retrievalContext.results}`
+            : `${renderTurnTimeAnchor()}\n\n${userPromptForTurn}`
+        await session.prompt(turnText)
       } finally {
         if (hooks && turnEvent !== undefined) {
           await hooks.runSessionTurnEnd(turnEvent)

package/src/agent/system-prompt.ts

@@ -56,7 +56,7 @@ When the user gives you work, start doing it in the same turn — a real action,
 
 ## Tracking your work
 
-For any multi-step or long-running task, maintain a todo list with \`todo_write\` and mark items complete as you finish them. This is not bookkeeping for its own sake: if this session is interrupted — a restart, a crash, or simply a later turn — the runtime uses the remaining incomplete items to resume the work instead of silently dropping it. Write the list when you start the work, update statuses as you go, and call \`todo_clear\` when everything is genuinely done. A single-step request needs no todo list.
+For any multi-step or long-running task, maintain a todo list with \`todo_write\` and mark items complete as you finish them. This is not bookkeeping for its own sake: if this session is interrupted — a restart, a crash, or simply a later turn — the runtime uses the remaining incomplete items to resume the work instead of silently dropping it. Write the list when you start the work and update statuses as you go; once your \`todo_write\` leaves no incomplete items, the runtime clears the list for you. Use \`todo_clear\` only to abandon a task with items still incomplete. A single-step request needs no todo list.
 
 ## Tool-call style
 
@@ -81,13 +81,17 @@ Use this only when the work belongs in *your* session. For self-contained long w
 
 ## Version control
 
-Your agent folder is a git repository.
+Your agent folder is a git repository, but **it is your own private backup repo — not a software project you develop.** It exists so TypeClaw can snapshot your identity files, \`sessions/\`, and \`memory/\` over time. It has no GitHub remote, nothing is pushed anywhere, and it is **not** a checkout of any project's source code. So when you commit here, you are saving your own state — not contributing to a codebase.
+
+This matters when the user asks you to work on an actual software project — fix a bug, build a feature, open a pull request. **That work does not happen in your agent folder.** Clone the project's repo somewhere else first (e.g. \`/tmp/<repo>\`), do the work there, and open the PR from that clone with \`gh\`. Never \`git init\`, add a remote, or try to push your agent folder as if it were the project — and if you can't find the project repo or its remote, ask the user where it lives instead of treating this folder as the project. The two are separate: this folder is *where you live*, the project clone is *where you work*.
+
+Commits to your agent folder (your own state):
 
 - Commit any files you created, edited, or deleted before declaring a task done. One logical change = one commit; split unrelated changes.
 - Use \`git add <paths>\` (not \`git add -A\`). Imperative commit messages ("Update SOUL.md to be less formal"); explain *why* in the body if non-obvious.
 - Never commit \`secrets.json\`, \`.env\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
 - ${PACKAGE_JSON_INSTALL_RULE}
-- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks.
+- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless the user explicitly asks. (Pushing a project clone you made elsewhere to open a PR is fine when the user asked for the PR.)
 
 ## How to behave
 
@@ -259,4 +263,6 @@ ${PACKAGE_JSON_INSTALL_RULE}
 
 Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. \`public/\` is the guest-visible zone — write there anything meant to be shared with an untrusted caller (a \`guest\`-role turn cannot read \`workspace/\` but can read \`public/\`). Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
 
+The agent folder is a private backup repo with no remote, not a project checkout. To work on a software project (fix a bug, open a PR), clone its repo elsewhere (e.g. \`/tmp/<repo>\`) and work there — never push the agent folder as if it were the project.
+
 See the session-origin block below for what kind of session this is and what's expected of you.`

package/src/agent/todo/continuation-policy.ts

@@ -39,10 +39,13 @@ export type ContinuationEpisode = {
 // The outcome of the most recently completed turn, recorded from the
 // `message_end` subscription (authoritative) or a prompt `finally` fallback.
 // `stopReason: 'unknown'` is the fail-closed value: an idle that sees it does
-// not auto-inject.
+// not auto-inject. `'length'` is a budget truncation (the turn ran out of
+// output tokens, often mid-thinking) — a legitimate unfinished turn that the
+// continuation budget/stagnation guards are designed to bound, so it is
+// continuation-eligible, NOT fail-closed.
 export type TurnOutcome = {
   turnId: string
-  stopReason: 'stop' | 'aborted' | 'error' | 'unknown'
+  stopReason: 'stop' | 'length' | 'aborted' | 'error' | 'unknown'
   endedAt: number
   // Total tokens the just-completed turn consumed (from the assistant
   // message's usage). Accumulated into the episode's cumulativeTokens so the
@@ -73,7 +76,7 @@ export function emptyContinuationState(): ContinuationState {
   }
 }
 
-const STOP_REASONS = new Set<TurnOutcome['stopReason']>(['stop', 'aborted', 'error', 'unknown'])
+const STOP_REASONS = new Set<TurnOutcome['stopReason']>(['stop', 'length', 'aborted', 'error', 'unknown'])
 
 // Validate a persisted state object field-by-field and fail closed: any field
 // that does not match the expected shape is dropped to its empty value rather

package/src/agent/todo/continuation-wiring.ts

@@ -14,9 +14,11 @@ import { writeTodos } from './store'
 
 // Map a pi `message_end` event's stopReason onto the TurnOutcome stopReason
 // space. Anything we don't recognize collapses to 'unknown' so the idle path
-// fails closed (no auto-injection on an outcome we can't classify).
+// fails closed (no auto-injection on an outcome we can't classify). 'length'
+// is preserved (not collapsed) because a budget-truncated turn is a legitimate
+// unfinished turn the continuation guards should be allowed to resume.
 export function classifyStopReason(raw: unknown): TurnOutcome['stopReason'] {
-  if (raw === 'stop' || raw === 'aborted' || raw === 'error') return raw
+  if (raw === 'stop' || raw === 'length' || raw === 'aborted' || raw === 'error') return raw
   return 'unknown'
 }
 

package/src/agent/todo/continuation.ts

@@ -16,9 +16,9 @@ export const CONTINUATION_PROMPT = [
   '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.',
+  'the list accordingly. Once your `todo_write` leaves no incomplete items, the',
+  'list is cleared for you automatically. Do not acknowledge or reply to this',
+  'notice; just continue the work.',
   '',
   '---',
   '',

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

@@ -50,7 +50,8 @@ export function createTodoTools({ agentDir, getOrigin }: CreateTodoToolsOptions)
       '(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.',
+      'you still care about on each call. When the list you write has no incomplete items left, ' +
+      'the runtime clears it for you — no separate cleanup call is needed.',
     parameters: Type.Object({
       todos: Type.Array(TODO_ITEM, { description: 'The complete todo list. Replaces any prior list.' }),
     }),
@@ -61,8 +62,28 @@ export function createTodoTools({ agentDir, getOrigin }: CreateTodoToolsOptions)
         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
+
+      // Collapse a fully-resolved list to empty in the SAME write that
+      // completed it, rather than relying on a follow-up todo_clear. That
+      // follow-up can be lost to an abort landing on the next turn, leaving a
+      // resolved list on disk (harmless to continuation, but it never gets
+      // cleaned up). Clearing here makes the cleanup race-free by construction.
+      if (remaining === 0 && todos.length > 0) {
+        await writeTodos(agentDir, scope, [])
+        const details: TodoToolDetails = { ok: true, total: todos.length, remaining: 0 }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `All ${todos.length} todo(s) done; list cleared.`,
+            },
+          ],
+          details,
+        }
+      }
+
+      await writeTodos(agentDir, scope, todos)
       const details: TodoToolDetails = { ok: true, total: todos.length, remaining }
       return {
         content: [
@@ -100,8 +121,10 @@ export function createTodoTools({ agentDir, getOrigin }: CreateTodoToolsOptions)
     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.',
+      'Empty your todo list for this session. Use this only to abandon a task with items still ' +
+      'incomplete, so the runtime stops tracking pending work. A list with no incomplete items ' +
+      'left is cleared automatically by `todo_write`, so you do not need to call this after ' +
+      'finishing everything.',
     parameters: Type.Object({}),
     async execute() {
       const scope = scopeForOrigin(getOrigin)