typeclaw 0.37.3 → 0.37.5

package/src/agent/subagents.ts

@@ -241,6 +241,11 @@ export type InvokeSubagentOptions = {
     sessionId: string | undefined
     abort: () => Promise<void>
   }) => void
+  // Sink for the subagent's captured final message (a reviewer `<review>` block,
+  // a researcher `<report>` block, or the last free-form assistant text).
+  // `runSession` owns the capture so the required-block guard can re-prompt
+  // before the result settles; `startSubagent` passes this to receive the output.
+  onFinalMessageCaptured?: (msg: string) => void
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -261,6 +266,8 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
       normalizeSubagentSession(await createSessionForSubagent(subagent, sessionOptions))
     let aborted = false
     let drainWatch: SubagentDrainWatch | undefined
+    const requiredBlockTag = REQUIRED_FINAL_BLOCK[name]
+    const capture = attachFinalMessageCapture(session, requiredBlockTag, options.onFinalMessageCaptured ?? (() => {}))
     if (options.onSessionCreated !== undefined) {
       options.onSessionCreated({
         session,
@@ -312,6 +319,28 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
           cancelled: () => aborted,
         })
       }
+      // Required-block guard (mirrors the channel empty-response guard): a subagent
+      // that owes a result block but ended without one gets a bounded re-prompt to
+      // emit it as text, then an honest fallback — never a silent stale-preamble
+      // result or a loud failure. Runs strictly after the drain settles so it is a
+      // final contract-repair pass, not another research phase; it deliberately
+      // does NOT re-run the drain.
+      if (requiredBlockTag !== undefined) {
+        for (
+          let attempt = 1;
+          !aborted && !capture.hasRequiredBlock() && attempt <= MAX_REQUIRED_BLOCK_RETRIES;
+          attempt++
+        ) {
+          console.warn(
+            `[subagent] ${name} required_block_retry attempt=${attempt}/${MAX_REQUIRED_BLOCK_RETRIES} tag=${requiredBlockTag}`,
+          )
+          await session.prompt(`${renderTurnTimeAnchor()}\n\n${renderRequiredBlockRetryNudge(requiredBlockTag)}`)
+        }
+        if (!aborted && !capture.hasRequiredBlock()) {
+          console.warn(`[subagent] ${name} required_block_fallback tag=${requiredBlockTag}`)
+          capture.setSyntheticFinalMessage(renderMissingRequiredBlockFallback(name, requiredBlockTag))
+        }
+      }
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionIdle({
           sessionId,
@@ -432,6 +461,9 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
 
   const work = invokeSubagent(name, {
     ...options,
+    onFinalMessageCaptured: (msg) => {
+      finalMessage = msg
+    },
     onSessionCreated: (event) => {
       handleSettled = true
       abortSession = event.abort
@@ -439,9 +471,6 @@ export function startSubagent(name: string, options: StartSubagentOptions): Star
       if (options.onSession !== undefined) {
         options.onSession(event)
       }
-      attachFinalMessageCapture(event.session, (msg) => {
-        finalMessage = msg
-      })
     },
   })
     .then(() => ({ ok: true as const, ...(finalMessage !== undefined ? { finalMessage } : {}) }))
@@ -497,22 +526,102 @@ function raceSubagentCompletion(
   })
 }
 
-// A complete <review>...</review> block. The reviewer's contract is that this
-// block IS its result; same-message preamble/trailing chatter or a later
-// summary turn must not become the captured final message. `[\s\S]` spans
-// newlines (the block is multi-line); non-greedy stops at the first close so an
-// incidental `<review>` literal in reviewed text cannot swallow real content.
-// Global so a message with several blocks yields the last (the revision).
-const REVIEW_BLOCK_RE = /<review>[\s\S]*?<\/review>/g
+// The tags a subagent can use to wrap its structured result: the reviewer's
+// `<review>`, the researcher's `<report>`. Fixed literals — never user input —
+// so the per-tag patterns below are injection-safe.
+type FinalBlockTag = 'review' | 'report'
+
+// A complete <TAG>...</TAG> block. The block IS the result: same-message
+// preamble/trailing chatter or a later summary turn must not become the captured
+// final message. `[\s\S]` spans newlines (the block is multi-line); non-greedy
+// stops at the first close so an incidental `<TAG>` literal in the wrapped text
+// cannot swallow real content. Global so a message with several blocks yields the
+// last (the revision).
+const FINAL_BLOCK_RE: Readonly<Record<FinalBlockTag, RegExp>> = {
+  review: /<review>[\s\S]*?<\/review>/g,
+  report: /<report>[\s\S]*?<\/report>/g,
+}
 
-function lastReviewBlock(text: string): string | null {
-  const matches = text.match(REVIEW_BLOCK_RE)
+function lastTaggedBlock(text: string, tag: FinalBlockTag): string | null {
+  const matches = text.match(FINAL_BLOCK_RE[tag])
   return matches === null ? null : (matches[matches.length - 1] ?? null)
 }
 
-function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg: string) => void): void {
+// Subagents whose result IS a REQUIRED tagged block — the parent must receive
+// that block or a loud failure, never a stale earlier turn. The researcher's
+// contract (src/bundled-plugins/researcher/researcher.ts) mandates a closing
+// `<report>` block; when an upstream provider retry loop ends the run on
+// unexecuted `write_report` tool calls, the researcher never emits it, and
+// without this gate the capture would silently return its earlier `<analysis>`
+// preamble as a "successful" result — the production regression this guards.
+// Keyed by the stable bundled-subagent registry name. This is STRICTER than the
+// reviewer's `<review>` (preferred, but falls back to free-form text): only the
+// subagents listed here fail loud when their block is absent.
+const REQUIRED_FINAL_BLOCK: Readonly<Record<string, FinalBlockTag>> = { researcher: 'report' }
+
+// Bounded re-prompt budget for the required-block guard, mirroring the channel
+// empty-response guard's MAX_EMPTY_TURN_RETRIES. A subagent that owes a result
+// block but ended without one is nudged at most this many times before the
+// honest fallback is installed.
+const MAX_REQUIRED_BLOCK_RETRIES = 2
+
+// The recovery nudge. It MUST forbid tools: the known failure mode is a provider
+// retry loop on the report-writing tool call, so re-driving the tool path would
+// just re-trigger the loop. Asking for the block as plain text is the repair.
+function renderRequiredBlockRetryNudge(tag: FinalBlockTag): string {
+  return `---
+**[SYSTEM MESSAGE — not from a human]**
+
+Your previous turn ended without the required <${tag}> block. This is an automated runtime recovery signal, not a human message.
+
+Emit the final <${tag}>...</${tag}> block NOW as plain assistant text. Do NOT call any tools — in particular do NOT call write_report. Do NOT continue researching or spawn more subagents.
+
+If the report file was not successfully written, still emit the block: set <report_file>none</report_file>, <confidence>low</confidence> (explain the report artifact was not completed), and note in <open_questions> that the run should be retried.
+
+Output exactly one <${tag}> block and nothing else.`
+}
+
+// The terminal graceful fallback when the nudges are exhausted. It fabricates NO
+// findings — only a structured, low-confidence "could not complete" notice — so
+// the parent gets a usable result instead of stale `<analysis>` or a hard error.
+function renderMissingRequiredBlockFallback(name: string, tag: FinalBlockTag): string {
+  if (tag === 'report') {
+    return `<report>
+<summary>
+The ${name} subagent could not complete a research report in this run: it ended without emitting the required <report> block (a known cause is the report tool not completing). Do not treat any earlier analysis text as findings — rerun the researcher or gather the sources directly if the answer is still needed.
+</summary>
+<report_file>
+none
+</report_file>
+<confidence>
+low — no complete research report artifact was produced.
+</confidence>
+<open_questions>
+The original research request remains unresolved; rerun the ${name} subagent or gather the sources directly.
+</open_questions>
+</report>`
+  }
+  return `<${tag}>\nThe ${name} subagent ended without emitting the required <${tag}> block and could not recover; rerun it or inspect the transcript.\n</${tag}>`
+}
+
+type SubagentCapture = {
+  // True once a required-block subagent (researcher) has emitted its `<report>`
+  // block; always false for subagents without a required block.
+  hasRequiredBlock: () => boolean
+  // Install a captured final message directly — used by the required-block guard
+  // to set an honest fallback when the block was never emitted, so the parent
+  // gets a structured result rather than stale preamble.
+  setSyntheticFinalMessage: (msg: string) => void
+}
+
+function attachFinalMessageCapture(
+  session: AgentSession,
+  requiredBlockTag: FinalBlockTag | undefined,
+  onFinalMessage: (msg: string) => void,
+): SubagentCapture {
   let lastAssistant: string | null = null
   let lastReview: string | null = null
+  let lastRequired: string | null = null
   try {
     session.subscribe((event: unknown) => {
       const ev = event as { type?: string; message?: { role?: string; content?: unknown } }
@@ -524,7 +633,23 @@ function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg:
       const text = extractFinalMessageText(ev.message?.content)
       if (text === null) return
       lastAssistant = text
-      const review = lastReviewBlock(text)
+
+      // Required-block contract (researcher): the result IS the block. A turn
+      // with text but no block — the `<analysis>` preamble, a process narrative —
+      // must NOT become the captured result, so `hasRequiredBlock` stays false and
+      // the guard in runSession re-prompts rather than returning stale preamble.
+      if (requiredBlockTag !== undefined) {
+        const block = lastTaggedBlock(text, requiredBlockTag)
+        if (block !== null) {
+          lastRequired = block
+          onFinalMessage(lastRequired)
+        }
+        return
+      }
+
+      // Preferred-block contract (reviewer) / free-form: a `<review>` block wins
+      // when present; otherwise the last free-form assistant text is the result.
+      const review = lastTaggedBlock(text, 'review')
       if (review !== null) lastReview = review
       onFinalMessage(lastReview ?? lastAssistant)
     })
@@ -532,6 +657,13 @@ function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg:
     // session.subscribe is a stable upstream API; defensive try is for test
     // doubles that don't implement it.
   }
+  return {
+    hasRequiredBlock: () => lastRequired !== null,
+    setSyntheticFinalMessage: (msg) => {
+      lastRequired = msg
+      onFinalMessage(msg)
+    },
+  }
 }
 
 function extractFinalMessageText(content: unknown): string | null {

package/src/agent/system-prompt.ts

@@ -14,104 +14,102 @@ const PACKAGE_JSON_INSTALL_RULE =
 export function buildDefaultSystemPrompt(subagentRoster: string): string {
   return `You are a general-purpose AI agent running inside TypeClaw.
 
-TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your character by \`SOUL.md\`, and your operating manual by \`AGENTS.md\`. This system prompt only describes the runtime around you.
+TypeClaw is domain-agnostic: \`IDENTITY.md\` defines your role, \`SOUL.md\` your voice, and \`AGENTS.md\` your operating manual. This prompt describes only the runtime.
 
 ## Your agent folder
 
-- **IDENTITY.md** *(always injected below)* — your role and function. Edit when responsibilities change.
-- **SOUL.md** *(always injected below)* — your character, tone, voice. Edit rarely.
-- **USER.md** *(read on demand)* — what you know about the user. Update as you learn.
-- **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
-- **\`memory/topics/\`** *(always injected below, READ-ONLY)* — sharded long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`; never edit memory shards directly.
+- **IDENTITY.md** *(injected)* — role/scope; edit when responsibilities change.
+- **SOUL.md** *(injected)* — tone/persona; edit rarely.
+- **USER.md** *(read on demand)* — durable facts/preferences about the user.
+- **AGENTS.md** *(read on demand)* — operating manual; read before non-trivial work and re-read whenever process is unclear.
+- **\`memory/topics/\`** *(injected, READ-ONLY)* — long-term memory shards owned by dreaming; never edit memory shards directly. Surface memorable facts in your reply or let memory-logger write streams.
 
-If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never memory shards. **Use this routing when you have something durable to record:**
+For durable updates, route them here — never to memory shards:
 
-- *role, function, scope of work, who you are to this user* → IDENTITY.md
-- *voice, tone, register, language preferences, persona quirks* → SOUL.md
-- *facts about the user (name, timezone, projects, preferences they hold across tasks)* → USER.md
-- *working conventions, repeatable procedures, "always do X" rules, things future-you needs to read before acting* → AGENTS.md
-- *one-off context for this conversation only* → don't write a file; it'll be captured in \`memory/streams/\` automatically
+- role, function, scope of work → IDENTITY.md
+- voice, tone, register, language preferences, persona → SOUL.md
+- facts about the user and durable preferences → USER.md
+- working conventions, repeatable procedures, "always do X" rules, future-you guidance → AGENTS.md
+- one-off conversation context → no file; \`memory/streams/\` captures it automatically
 
-When in doubt between SOUL.md and AGENTS.md: if it describes *how you sound*, it's SOUL; if it describes *how you work*, it's AGENTS. Tone preferences ("be more terse") go to SOUL.md; process rules ("always run tests before committing") go to AGENTS.md.
-
-**Edit discipline.** Prefer rewriting in place to growing files. SOUL.md should stay short — a paragraph or two; if it's drifting past a screen, you're using it as a scratchpad and the model that reads it will start ignoring the back half. IDENTITY.md is similar — a few lines of who you are, not a résumé. AGENTS.md is the one allowed to grow. Don't rewrite SOUL.md on the first piece of tone feedback in a session — wait until the user repeats a preference or asks you directly to update it; a single off-day request isn't a durable change.
+If it describes how you sound, use SOUL.md; how you work, AGENTS.md. **Edit discipline.** Prefer rewriting in place. SOUL.md should stay short, as should IDENTITY.md; AGENTS.md may grow. Do not treat one-off tone feedback as durable; a single off-day request isn't a durable change unless repeated or explicitly requested.
 
 ## Your workspace
 
-- **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
-- **\`public/\`** — the guest-visible zone. Untrusted callers (the \`guest\` role) cannot see \`workspace/\`, but they can read and write \`public/\`. Put anything meant to be shared with an untrusted caller here. If a \`<your-role>\` tag on the turn names a non-trusted role, or a write to \`workspace/\` comes back \`denied by permissions\`, the caller is untrusted — write to \`public/\` instead.
-- **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
-- **\`memory/streams/\`** *(not injected — reach via \`memory_search\`)* — dated streams written by the memory-logger between sessions. Runtime-owned. Undreamed observations are searchable on demand instead of injected into every prompt.
-- **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
+- **\`workspace/\`** — free-write drafts/artifacts. Do not write agent-folder root unless asked.
+- **\`public/\`** — guest-visible sharing area. If the role is untrusted or \`workspace/\` writes are denied, use \`public/\`.
+- **\`sessions/\`** — runtime-managed transcripts; don't write.
+- **\`memory/streams/\`** *(not injected; use \`memory_search\`)* — runtime-owned dated observations.
+- **\`memory/skills/\`** — auto-loaded dreaming skills; don't write directly.
 - **\`.agents/skills/\`** — user-installed skills.
 
 ## Configuration
 
 - **\`typeclaw.json\`** — runtime config. Read when needed.
-- **\`secrets.json\`** — canonical store for API keys, channel tokens, and OAuth credentials. Gitignored. Written by \`typeclaw init\` and the OAuth refresh path; never edit by hand unless rotating a credential. \`.env\` is the legacy/env-override path (env wins if set) but is no longer where new typeclaw secrets live. Never echo, log, or commit either file's values.
+- **\`secrets.json\`** — canonical gitignored secrets store. \`.env\` is legacy/env override. Never echo, log, or commit either file's values; hand-edit only when explicitly rotating credentials.
 
 ## Execution bias
 
-When the user gives you work, start doing it in the same turn — a real action, not a plan or a promise-to-act. Commentary-only turns are incomplete when the next action is clear. For multi-step work, send one short progress update, not a running narration.
+Start work in the same turn when the next action is clear; do not answer with only a plan. For multi-step work, give one short progress update, not narration.
 
 ## 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 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.
+For multi-step or long-running tasks, use \`todo_write\` when you start and mark items complete as you finish; incomplete items let the runtime resume after interruptions. Use \`todo_clear\` only to abandon remaining work. Single-step requests need no todo list.
 
 ## Tool-call style
 
-Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
+Do not narrate routine low-risk tools. Narrate only for multi-step context, risky/irreversible actions, external sends, or when asked.
 
 ## Delivering reports and documents
 
-When the user asks for a *report*, *document*, *brief*, *PDF*, or asks you to *send/show/attach/export* a generated result — anything where the deliverable is a file a human would download, print, or forward — produce a polished file, not a wall of text pasted into chat and not a one-line summary that drops the substance. A summary (yours or a subagent's) is a pointer to the deliverable, never the deliverable itself; when the user asked for the report, ship the report.
+When the user asks for a *report*, *document*, *brief*, *PDF*, or asks you to *send/show/attach/export* a generated result — anything a human would download, print, or forward — produce a polished file, not a chat wall or substance-dropping summary. A summary is a pointer to the deliverable, never the deliverable itself; when the user asked for the report, ship the report.
 
-To turn Markdown into a PDF, use the bundled \`typeclaw-render-pdf\` skill — it is the only supported path and it renders Markdown properly (headings, lists, tables). **Never** hand-roll a PDF with an ad-hoc library (jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print, Python ReportLab): those produce unrendered raw \`##\`/\`**\` markup and mojibake for non-Latin text. CJK fonts are opt-in, so for Korean/Japanese/Chinese reports follow that skill's CJK guidance — never ship a tofu-rendered PDF; if the output has tofu boxes, ask before enabling opt-in CJK fonts and restarting. If a request is plainly satisfied by inline chat — a short answer, a snippet, a quick explanation — stay inline; this rule is for explicit document deliverables, not for every long reply.
+For Markdown-to-PDF, use the bundled \`typeclaw-render-pdf\` skill; it is the supported path and renders headings, lists, and tables. Never hand-roll PDFs with jsPDF, pdfkit, canvas text dumps, raw headless-browser prints, or ReportLab: they often emit raw markup and mojibake for non-Latin text. For Korean/Japanese/Chinese, follow the skill's CJK font guidance and do not ship tofu boxes. Short answers/snippets/explanations can stay inline.
 
 ## Long-running and interactive shell work
 
-Foreground \`bash\` blocks your turn until exit, so a command that runs for minutes or waits for input (dev server, REPL, watcher, \`docker compose up\`, interactive installer) freezes the conversation. \`tmux\` is in the container — run such programs detached so your turn stays free:
+Foreground \`bash\` blocks until exit. Run minutes-long or input-waiting programs (dev servers, REPLs, watchers, \`docker compose up\`, installers) detached in \`tmux\`:
 
 - Start: \`tmux new-session -d -s <name> "<cmd>"\`
-- Observe: \`tmux capture-pane -t <name> -p\` (poll across turns, don't block)
-- Drive: \`tmux send-keys -t <name> "<input>" Enter\` (control keys too, e.g. \`C-c\`)
+- Observe: \`tmux capture-pane -t <name> -p\`
+- Drive: \`tmux send-keys -t <name> "<input>" Enter\`
 - Stop: \`tmux kill-session -t <name>\`
 
-Use this only when the work belongs in *your* session. For self-contained long work (build, test suite, install, batch) whose result is all you need, delegate to \`operator\` instead.
+Use tmux only for work that belongs in your session. Delegate self-contained long work (builds, tests, installs, batches) to \`operator\`.
 
 ## Version control
 
-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.
+Your agent folder is a git repository, but **it is your own private backup repo — not a software project you develop.** TypeClaw snapshots identity files, \`sessions/\`, and \`memory/\` there over time. It normally has no remote, nothing is pushed, and it is **not a checkout of any project**. Commits here save your state, not a codebase contribution.
 
-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*.
+For project work (bug, feature, PR), clone the project repo into \`/tmp/<repo>\`, work there, and open the PR from that clone with \`gh\`. Never \`git init\`, add a remote, or push your agent folder as the project. If there is no remote or you cannot find the repo, ask the user where it lives. Your agent folder is where you live; the 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.
+- Commit files you created/edited/deleted before declaring done. One logical change = one commit.
+- Use \`git add <paths>\`, not \`git add -A\`. Use imperative commit messages; explain why if non-obvious.
+- Never commit \`secrets.json\`, \`.env\`, or \`workspace/\`. Do not manually add runtime-managed \`sessions/\` or \`memory/\`.
 - ${PACKAGE_JSON_INSTALL_RULE}
-- 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.)
+- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history in this folder unless explicitly asked. Pushing a separate project clone for a requested PR is fine.
 
 ## How to behave
 
-- Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
-- Prefer reading files over guessing — IDENTITY / SOUL / USER / memory topics / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
-- Answer questions. Do work. Don't over-explain unless asked.
-- If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
+- Match the user's register. If SOUL.md specifies a voice, use it; otherwise be concise and direct.
+- Read files/memory before guessing. Follow AGENTS.md under your IDENTITY.md role; suggest AGENTS.md additions for repeatable gaps.
+- Answer questions, do work, and avoid over-explaining unless asked.
+- Ask one clarifying question only when ambiguity would materially change the work; otherwise choose a reasonable default.
 - Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
 
 ## Subagent orchestration
 
-Delegate focused work to subagents via \`spawn_subagent\`, \`subagent_output\`, \`subagent_cancel\`. Each runs in its own context window with its own tool set. The available subagents and their purpose are listed in the \`spawn_subagent\` tool description — re-read it before delegating. Briefly: ${subagentRoster}.
+Delegate focused work with \`spawn_subagent\`, \`subagent_output\`, and \`subagent_cancel\`. Each subagent has its own context/tools; re-read the tool description before delegating. Briefly: ${subagentRoster}.
 
-There are three delegation modes. Pick deliberately.
+Pick one of three modes:
 
-**Mode A — Research fan-out.** Need information and the search is broad? Fire 2-5 subagents (usually \`explorer\`/\`scout\`) in parallel with \`run_in_background: true\`, then end your response. A \`<system-reminder>\` lands per completion; call \`subagent_output\` once per task_id to collect (it never blocks) and answer. Match the worker to the depth: a fast or narrow web lookup goes to \`scout\`; a fuzzy question that needs decomposition, many sources, cross-validation, and a synthesized verdict goes to \`researcher\` (don't do that grind inline with \`web_search\` yourself). When the user *explicitly* says "research"/"investigate" (or equivalent), you MUST spawn \`researcher\` — answering from training memory or a single inline \`web_search\` does not satisfy the request, even if you think you know the answer. (Fanning out \`scout\`/\`explorer\` underneath is fine, but it does not replace \`researcher\`.)
+**Mode A — Research fan-out.** Broad search: spawn 2-5 \`explorer\`/\`scout\` workers in parallel with \`run_in_background: true\`, end your response, then collect each completion once via \`subagent_output\`. Use \`scout\` for narrow lookups; \`researcher\` for decomposed, multi-source, cross-validated synthesis. When the user *explicitly* says "research"/"investigate" (or equivalent), you MUST spawn \`researcher\` — answering from training memory or a single inline \`web_search\` does not satisfy the request, even if you think you know the answer. (Fanning out \`scout\`/\`explorer\` underneath is fine, but it does not replace \`researcher\`.)
 
-**Mode B — Delegate-and-converse.** Asked to DO something long-running (>~30s: installs, builds, \`docker\`, scrapes, long test suites, multi-host loops, any noisy "fetch N and synthesize" chain)? Don't run it inline — blocking your own \`bash\` freezes the conversation and stalls the channel typing heartbeat (\`MAX_TYPING_HEARTBEAT_MS\`). Spawn one subagent (\`operator\` for side effects, \`scout\` for a quick web lookup, \`researcher\` for a deep multi-source "fetch N and synthesize" investigation, \`planner\` when a multi-step goal needs a sequenced, risk-aware plan before anyone acts) with \`run_in_background: true\`, acknowledge, and KEEP TALKING. Single fast calls (\`git status\`, one known-endpoint \`curl\`) stay inline. When the completion reminder lands, weave the result in; in a channel session, the completion \`<system-reminder>\` is NOT a user message but plain text is still invisible — Surface the result via \`channel_reply\` (or \`channel_send\`). If you already posted the substantive answer in the spawn turn, prefer \`skip_response({ reason: "result confirms prior reply" })\` over going silent.
+**Mode B — Delegate-and-converse.** For >~30s side-effectful/noisy work (installs, builds, \`docker\`, scrapes, long tests, multi-host loops, fetch-and-synthesize chains), spawn one background subagent and stay responsive: \`operator\` for side effects, \`scout\` quick lookup, \`researcher\` deep investigation, \`planner\` risk-aware sequencing. Keep single fast calls inline. When the completion \`<system-reminder>\` lands, Surface the result via \`channel_reply\`/\`channel_send\` in channel sessions because reminders are not user messages.
 
-**Mode C — Troubleshooting.** Stuck in a fix-it loop — ~3 non-converging attempts at the same failure, cycling kill/re-run/\`sleep\`/capture/retry? Stop (the trigger is non-convergence, not elapsed time — this overrides the ~30s rule). Hand the whole debugging loop to \`operator\` with \`run_in_background: true\` — symptom, what you tried, success condition — and stay responsive. Read the \`typeclaw-troubleshooting\` skill for the mechanics before you spawn.
+**Mode C — Troubleshooting.** After ~3 non-converging attempts at the same failure, stop and hand the loop to \`operator\` with \`run_in_background: true\`, symptom, attempts, and success condition. Read \`typeclaw-troubleshooting\` before spawning.
 
 **Status queries.** If the user asks "status?" on a running subagent, call \`subagent_output({ task_id })\` and report its \`status_summary\` — don't guess.
 
@@ -123,15 +121,15 @@ There are three delegation modes. Pick deliberately.
 [REQUEST]: Concrete instructions — what to find/do/produce, what format, what to SKIP.
 \`\`\`
 
-**Anti-patterns.** Don't fire more than 5 subagents per turn, spawn for a known answer or single-file lookup, poll \`subagent_output\` in a loop (end your turn; the reminder wakes you), or ask a research subagent to make decisions — they find and report, you decide. Most subagents are leaves; only \`operator\` and \`reviewer\` may delegate one level further, and the chain is hard-capped regardless.
+**Anti-patterns.** Don't fire more than 5 subagents per turn, spawn for known answers or single-file lookups, poll output in a loop, or ask research subagents to decide. They report; you decide. Most subagents are leaves; only \`operator\` and \`reviewer\` may delegate one level deeper.
 
 ## Safety
 
-You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the runtime's mechanisms.
+You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, influence, or plans beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never modify your own system prompt, safety rules, or runtime configuration unless explicitly requested and only through runtime mechanisms.
 
 ---
 
-You are not pi, not Claude, not ChatGPT. You are the agent described by your own IDENTITY.md and SOUL.md. Let those files define your voice.`
+You are not pi, not Claude, not ChatGPT. You are the agent described by IDENTITY.md and SOUL.md. Let those files define your voice.`
 }
 
 // Placeholder roster for the no-registry path: back-compat callers of

package/src/agent/todo/scope.ts

@@ -51,6 +51,8 @@ export function resolveTodoScope(origin: SessionOrigin): TodoScope | null {
   }
 }
 
+const CHANNEL_SCOPE_SEPARATOR = ','
+
 function channelScopeKey(origin: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
   const parts = [
     encodeComponent(origin.adapter),
@@ -58,7 +60,7 @@ function channelScopeKey(origin: { adapter: string; workspace: string; chat: str
     encodeComponent(origin.chat),
     encodeComponent(origin.thread),
   ]
-  return `channel/${parts.join(':')}`
+  return `channel/${parts.join(CHANNEL_SCOPE_SEPARATOR)}`
 }
 
 // Encode one scope component injectively. Every component is emitted as a
@@ -69,7 +71,7 @@ function channelScopeKey(origin: { adapter: string; workspace: string; chat: str
 // 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
+// `/` 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'

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

@@ -78,15 +78,13 @@ export function createChannelReplyTool({
           },
         ),
       ),
-      continue: Type.Optional(
-        Type.Boolean({
-          description:
-            'Set `true` when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again. ' +
-            'Omitting it on such an ack silently truncates the turn: a successful reply ends the turn by default, so the fetch/subagent/answer you intended to do next never runs. ' +
-            'A normal final reply omits this (no wasted follow-up LLM call). ' +
-            'Do not set it just to seem responsive; only when genuine multi-step work follows in the same turn.',
-        }),
-      ),
+      continue: Type.Boolean({
+        description:
+          'REQUIRED on every channel_reply — you must explicitly choose, there is no default. Set `true` when this reply is a mid-turn status update (e.g. "working on it…") and you still have work to do THIS turn — fetching data, running a tool, spawning a subagent, then replying again; `true` keeps the turn alive so that follow-up actually runs. ' +
+          'Set `false` when this reply is your final message for the turn (the common case). ' +
+          'This choice is mandatory precisely because a missing value used to default to ending the turn silently: a successful reply ends the turn unless `continue` is `true`, so a `false` on an ack you meant to keep working from drops the work you promised. ' +
+          'Do not set `true` just to seem responsive; only when genuine multi-step work follows in the same turn.',
+      }),
       resolve_review_thread: Type.Optional(
         Type.Boolean({
           description: