typeclaw 0.9.0 → 0.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/scripts/require-parallel.ts

@@ -1,29 +1,55 @@
-// Preloaded by bunfig.toml `[test] preload`. Denies `bun test` without
-// --parallel. Serial runs are ~3.4x slower (44s → 13s, see commit
-// 1c66d5e), and Bun has no bunfig knob for the flag yet (verified
-// against bunfig.zig in oven-sh/bun main, May 2026). Without this
-// guard, IDE test runners and ad-hoc shells silently fall back to the
-// slow path.
+// Preloaded by bunfig.toml `[test] preload`. Two responsibilities:
+//   1. Deny `bun test` without --parallel.
+//   2. Raise the per-test default timeout from Bun's 5000ms.
+//
+// Why deny serial runs: Serial runs are ~3.4x slower (44s → 13s, see commit
+// 1c66d5e), and Bun has no bunfig knob for the flag yet (verified against
+// bunfig.zig in oven-sh/bun main, May 2026). Without this guard, IDE test
+// runners and ad-hoc shells silently fall back to the slow path.
 //
 // Detection: Bun strips CLI flags from `Bun.argv` before invoking the
 // preload, so we can't scrape the flag directly. Instead we look for
 // BUN_TEST_WORKER_ID, which Bun sets in the preload env exactly when
-// `--parallel` is active (the variable carries the worker index for
-// the IPC handshake between coordinator and workers). Empirically
-// verified against bun 1.3.14: present under --parallel, absent under
-// serial. If a future Bun version renames this var, the guard fails
-// closed (treats every run as serial → always denies), which is the
-// safe direction.
+// `--parallel` is active (the variable carries the worker index for the
+// IPC handshake between coordinator and workers). Empirically verified
+// against bun 1.3.14: present under --parallel, absent under serial. If
+// a future Bun version renames this var, the guard fails closed (treats
+// every run as serial → always denies), which is the safe direction.
+//
+// Bypass with TYPECLAW_ALLOW_SERIAL_TESTS=1 when debugging a flaky test
+// where worker contention obscures the failure.
 //
-// Bypass with TYPECLAW_ALLOW_SERIAL_TESTS=1 when debugging a flaky
-// test where worker contention obscures the failure.
+// Why raise the default timeout: A growing number of tests in this repo
+// either spawn child processes (`bun run typeclaw …` via Bun.spawn from
+// src/cli/index.test.ts, src/cli/role.test.ts, src/cli/status.test.ts,
+// src/init/dockerfile.test.ts agent-browser wrapper, etc.) or boot the
+// in-process agent (`startAgent({ port: 0, … })` from src/run/plugin.test.ts).
+// Both shapes have a happy-path cost well under 1s but a worst-case cost
+// that races Bun's 5000ms ceiling under `--parallel` contention. The
+// repeating failure mode is "this test timed out after 5000ms" appearing
+// on different tests across runs at a rough ~3-15% rate per full-suite
+// invocation — not a real bug, just resource starvation. Raising the
+// default to 30s eliminates the false positives without masking real
+// hangs (a wedged test still fails, just 6x slower than before). The
+// happy path is unaffected because tests complete in their actual
+// runtime, not the timeout budget.
+//
+// 30s was chosen as ~75x the observed happy-path cold-start (~400ms) for
+// the heaviest subprocess tests, matching the in-house convention used in
+// pi-coding-agent's subprocess fixtures and Bun's own integration-test
+// suites (see oven-sh/bun test/cli/install/*.test.ts which set 5-minute
+// timeouts for full installs). Individual tests that genuinely need more
+// can still pass an explicit 3rd arg to `test()` to override locally.
+
+import { setDefaultTimeout } from 'bun:test'
 
 const isParallelWorker = typeof process.env.BUN_TEST_WORKER_ID === 'string'
 
 if (isParallelWorker) {
-  // proceed
+  setDefaultTimeout(30_000)
 } else if (process.env.TYPECLAW_ALLOW_SERIAL_TESTS === '1') {
   console.warn('[require-parallel] Running serially — TYPECLAW_ALLOW_SERIAL_TESTS=1 set.')
+  setDefaultTimeout(30_000)
 } else {
   console.error('')
   console.error('  ✗ `bun test` without --parallel is denied in this repo.')

package/src/agent/live-subagents.ts

@@ -23,7 +23,6 @@ export type LiveSubagent = {
   status: SubagentStatus
   completion?: SubagentCompletion
   abort: () => Promise<void>
-  awaitCompletion: () => Promise<SubagentCompletion>
 }
 
 export const MAX_EVENTS_PER_SUBAGENT = 100

package/src/agent/session-origin.ts

@@ -231,6 +231,16 @@ function renderChannelOrigin(
     'the answer — both in the same turn. The ack is not your reply; the answer',
     'is. Once the answer lands, end your turn.',
     '',
+    '**Backgrounded work does not end the obligation.** If you spawn a',
+    'subagent with `run_in_background: true` to answer the current inbound,',
+    "you have promised a reply you have not delivered yet. Don't end the",
+    'turn with `NO_REPLY` — the system will not surface the subagent result',
+    'on its own. When the subagent-completion `<system-reminder>` arrives,',
+    'fetch the result with `subagent_output` and send it via `channel_reply`',
+    'in that turn. `NO_REPLY` is only legal on the post-result turn if there',
+    'is genuinely nothing user-facing to share (e.g. the result is empty or',
+    'identical to something you already replied with this conversation).',
+    '',
     'Do not send a second reply just to rephrase, restate, or "confirm in',
     'plain language" something you already said.',
     '',

package/src/agent/subagent-completion-reminder.ts

@@ -21,7 +21,10 @@ export type CompletionReminderArgs = {
 const CHANNEL_REPLY_NUDGE =
   'This reminder is a system message, not a user inbound — but you are in a channel session, ' +
   'so end your turn via `channel_reply` (or `channel_send`) to surface the result. ' +
-  'Plain-text output is invisible here. If there is genuinely nothing to surface, end with `NO_REPLY`.'
+  'Plain-text output is invisible here. If you spawned this subagent to answer a user, ' +
+  'this is the turn where that promised reply lands — fetch the result via `subagent_output` ' +
+  'and send it. `NO_REPLY` is only correct when the result is genuinely empty or duplicates ' +
+  'something you already replied with in this conversation.'
 
 export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
   const durationStr = formatReminderDuration(args.durationMs)

package/src/agent/subagents.ts

@@ -48,6 +48,20 @@ export type SubagentShared<P = unknown> = {
   toolResultBudget?: ToolResultBudget
   visibility?: 'public' | 'internal'
   requiresSpecificPermission?: boolean
+  // Wall-clock ceiling on a single spawn, enforced at the orchestration
+  // layer (both `dispatchSpawnSubagent` and the stream-driven
+  // `SubagentConsumer`). When exceeded, the orchestrator's `await` settles
+  // with a timeout error and releases the coalescing key for `inFlightKey`,
+  // so the next spawn of the same (name, inFlightKey) can proceed instead
+  // of being skip-coalesced. The underlying `invokeSubagent` call may keep
+  // running — pi-coding-agent's `session.prompt` does not accept an
+  // AbortSignal today, so a half-open LLM stream stays alive until the OS
+  // reaps it. The trade-off is honest: cancellation is upstream's job;
+  // releasing the coalescing key is ours, and that is what unblocks the
+  // user-visible "every subsequent turn skipped while the first spawn
+  // hangs" symptom. Omit for no ceiling (legacy behavior; the spawn waits
+  // as long as the provider takes).
+  timeoutMs?: number
 }
 
 export type Subagent<P = unknown> = SubagentShared<P> & {
@@ -248,6 +262,42 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
   }
 }
 
+export class SubagentTimeoutError extends Error {
+  override readonly name = 'SubagentTimeoutError'
+  constructor(
+    readonly subagentName: string,
+    readonly coalesceKey: string,
+    readonly timeoutMs: number,
+  ) {
+    super(`subagent ${subagentName} (key=${coalesceKey}) spawn timed out after ${timeoutMs}ms`)
+  }
+}
+
+export function isSubagentTimeoutError(err: unknown): err is SubagentTimeoutError {
+  return err instanceof SubagentTimeoutError
+}
+
+export async function awaitWithSubagentTimeout(
+  work: Promise<void>,
+  subagentName: string,
+  coalesceKey: string,
+  timeoutMs: number | undefined,
+): Promise<void> {
+  if (timeoutMs === undefined) {
+    await work
+    return
+  }
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new SubagentTimeoutError(subagentName, coalesceKey, timeoutMs)), timeoutMs)
+  })
+  try {
+    await Promise.race([work, timeout])
+  } finally {
+    if (timer !== null) clearTimeout(timer)
+  }
+}
+
 export type SubagentHandle = {
   taskId: string
   sessionId: string | undefined
@@ -447,20 +497,29 @@ export function createSubagentConsumer({
         inFlight.add(key)
         try {
           const spawnedByOrigin = parseSpawnedByOriginJson(target.spawnedByOriginJson, logger, name)
-          await invokeSubagent(name, {
-            registry,
-            ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
-            agentDir,
-            userPrompt: '',
-            payload: msg.payload,
-            onProviderError: (message) => logger.error(`[subagent] ${key}: LLM call failed: ${message}`),
-            ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
-            ...(target.spawnedByRole !== undefined ? { spawnedByRole: target.spawnedByRole } : {}),
-            ...(spawnedByOrigin !== undefined ? { spawnedByOrigin } : {}),
-          })
+          await awaitWithSubagentTimeout(
+            invokeSubagent(name, {
+              registry,
+              ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
+              agentDir,
+              userPrompt: '',
+              payload: msg.payload,
+              onProviderError: (message) => logger.error(`[subagent] ${key}: LLM call failed: ${message}`),
+              ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
+              ...(target.spawnedByRole !== undefined ? { spawnedByRole: target.spawnedByRole } : {}),
+              ...(spawnedByOrigin !== undefined ? { spawnedByOrigin } : {}),
+            }),
+            name,
+            key,
+            registry[name]?.timeoutMs,
+          )
         } catch (err) {
-          const message = err instanceof Error ? err.message : String(err)
-          logger.error(`[subagent] ${key} failed: ${message}`)
+          if (isSubagentTimeoutError(err)) {
+            logger.warn(`[subagent] ${key} timed out after ${err.timeoutMs}ms; releasing coalesce key`)
+          } else {
+            const message = err instanceof Error ? err.message : String(err)
+            logger.error(`[subagent] ${key} failed: ${message}`)
+          }
         } finally {
           inFlight.delete(key)
         }

package/src/agent/system-prompt.ts

@@ -60,7 +60,7 @@ There are two delegation modes. Pick deliberately.
 
 **Mode A — Research fan-out** (in service of the current question)
 
-When you need information to answer the user and the search is broad, fire 2-5 subagents in parallel with \`run_in_background: true\` covering different angles. End your response after spawning. The system will deliver a \`<system-reminder>\` for each completion; gather results then answer the user. Do NOT poll \`subagent_output\` in a tight loop.
+When you need information to answer the user and the search is broad, fire 2-5 subagents in parallel with \`run_in_background: true\` covering different angles. End your response after spawning. The system will deliver a \`<system-reminder>\` for each completion; then call \`subagent_output\` once per task_id to fetch the result and answer the user. \`subagent_output\` always returns immediately with a snapshot — it does not block.
 
 The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), memory topic shards and daily memory streams, skills, cron jobs, config, git history, mounts, channels state. It is read-only and runs on a fast/cheap model, so fire liberally. Do NOT ask it to plan, decide, or write code — it finds and reports.
 
@@ -72,13 +72,13 @@ When the user hands you a task that will take minutes (a multi-step browser sess
 
 In a channel session, the completion \`<system-reminder>\` is NOT a user message — the channel origin's "you MUST call \`channel_reply\` for every user message" rule does not literally apply, but the underlying constraint does: plain-text output is invisible in a channel. Surface the result via \`channel_reply\` (or \`channel_send\`) so the user actually sees it. Failures need surfacing too: when a delegated task didn't complete, the user needs the outcome and whatever partial progress you got. \`NO_REPLY\` is the escape hatch only when the user has already seen the substantive answer — typically because you posted it via \`channel_reply\` in the same turn that spawned the subagent, and the reminder is purely confirming completion of a step the user is already tracking. Otherwise, post the result.
 
-Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.
+Before you run a tool chain that returns bulky intermediate output you won't need again — multiple \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that scrapes a site or dumps a large response, an \`agent-browser\` session, a \`claude\` (Claude Code) or \`codex\` (OpenAI Codex CLI) delegation driven through tmux, any "fetch N things and synthesize" loop — delegate it to a subagent. \`scout\` (for research) or \`operator\` (for actions with side effects) runs the noisy work in its own context window and returns a distilled summary; your session carries the *answer*, not the raw material you derived it from. This is about context economy, not latency: even a fast operation belongs in a subagent when the byproducts are large and disposable (three quick news searches across different outlets still dumps three SERPs and three article bodies into your context forever). The exception is exactly one call whose result you'll cite directly — one \`webfetch\` of a known URL, one \`websearch\` query whose top result is the answer. Two of either, or any "across multiple sources" framing, is delegation territory.
 
-The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, Claude Code delegations (the tmux driving loop, the multi-turn polling, the worktree teardown — all of it inside operator), anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
+The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, Claude Code or Codex CLI delegations (the tmux driving loop, the multi-turn polling, the worktree teardown — all of it inside operator), anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
 
 **Status queries**
 
-If the user asks "how's it going?" or "status?" on a running subagent, call \`subagent_output({ task_id, block: false })\` and report the \`status_summary\` in your own words. Don't pretend to know the status without checking.
+If the user asks "how's it going?" or "status?" on a running subagent, call \`subagent_output({ task_id })\` and report the \`status_summary\` in your own words. Don't pretend to know the status without checking.
 
 **Prompt structure for spawns** (mandatory — the subagent does not see this conversation)
 
@@ -92,7 +92,7 @@ If the user asks "how's it going?" or "status?" on a running subagent, call \`su
 
 - Don't fire more than 5 subagents in a single turn.
 - Don't spawn for a known answer or single-file lookup — do it yourself.
-- Don't poll \`subagent_output\` waiting for completion; end your response and the reminder will wake you.
+- Don't call \`subagent_output\` in a loop waiting for completion; end your response and the reminder will wake you, then fetch the result once.
 - Don't ask a research subagent to make architectural decisions for you — they find and report; you decide.
 - Subagents cannot recursively spawn other subagents.
 

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

@@ -1,10 +1,16 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { isNoReplySignal, isUpstreamEmptyResponseSentinel, type ChannelRouter } from '@/channels/router'
+import {
+  containsKimiToolDelimiter,
+  isNoReplySignal,
+  isUpstreamEmptyResponseSentinel,
+  type ChannelRouter,
+} from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+import { fenceRuntimeNotice } from './runtime-notice'
 
 export type ChannelReplyOrigin = {
   adapter: AdapterId
@@ -98,6 +104,15 @@ export function createChannelReplyTool({
         }
       }
 
+      const kimiLeakError = kimiToolCallLeakError(text)
+      if (kimiLeakError) {
+        logger.warn(formatChannelToolFailure('channel_reply', kimiLeakError))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${kimiLeakError}` }],
+          details: { ok: false, error: kimiLeakError },
+        }
+      }
+
       const result = await router.send({
         adapter: origin.adapter,
         workspace: origin.workspace,
@@ -148,14 +163,24 @@ export function createChannelReplyTool({
             }),
           )
         : ''
+      const body = hint ? `${baseText}${hint}` : baseText
       return {
-        content: [{ type: 'text' as const, text: hint ? `${baseText} — ${hint}` : baseText }],
+        content: [{ type: 'text' as const, text: `${TOOL_RESULT_PREFIX}${body}` }],
         details,
       }
     },
   })
 }
 
+// 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
+// and replies to itself. Observed in production: Kimi K2 on KakaoTalk
+// re-invoked after a successful send saw only the echo as new context
+// and hallucinated a goodbye trigger from it. Mirrored verbatim in
+// channel-send.ts so both tools share one greppable marker.
+export const TOOL_RESULT_PREFIX = '[system: tool result, not a user message] '
+
 export const ECHO_MAX_CHARS = 500
 
 export function renderEcho(text: string): string {
@@ -211,12 +236,27 @@ function upstreamEmptyResponseSentinelError(text: string | undefined): string {
   )
 }
 
+function kimiToolCallLeakError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (!containsKimiToolDelimiter(text)) return ''
+  return (
+    'refusing to forward raw provider tool-call control tokens; these are chat-template ' +
+    'delimiters that should have been parsed into a real tool call upstream. ' +
+    'Re-issue the intended channel reply as plain user-visible text only.'
+  )
+}
+
 // Mirror of the same hint used by channel_send. Kept identical so the model
-// sees the same yield signal regardless of which tool it picked.
+// sees the same yield signal regardless of which tool it picked. The body
+// is wrapped via `fenceRuntimeNotice` (in `./runtime-notice`) so persona-rich
+// models cannot read the trailing prose as a chat instruction and reply to
+// it in-character. See that helper's comment for the failure mode that
+// motivated the framing.
 function consecutiveSendHint(countAfterSend: number): string {
   if (countAfterSend <= 1) return ''
-  if (countAfterSend === 2) {
-    return 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
-  }
-  return `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+  const body =
+    countAfterSend === 2
+      ? 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
+      : `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+  return fenceRuntimeNotice(body)
 }

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

@@ -1,11 +1,17 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { isNoReplySignal, isUpstreamEmptyResponseSentinel, type ChannelRouter } from '@/channels/router'
+import {
+  containsKimiToolDelimiter,
+  isNoReplySignal,
+  isUpstreamEmptyResponseSentinel,
+  type ChannelRouter,
+} from '@/channels/router'
 import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
-import { renderOutboundEcho } from './channel-reply'
+import { renderOutboundEcho, TOOL_RESULT_PREFIX } from './channel-reply'
+import { fenceRuntimeNotice } from './runtime-notice'
 
 export type ChannelSendOrigin = {
   adapter: AdapterId
@@ -121,6 +127,15 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
         }
       }
 
+      const kimiLeakError = kimiToolCallLeakError(bodyText)
+      if (kimiLeakError) {
+        logger.warn(formatChannelToolFailure('channel_send', kimiLeakError))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${kimiLeakError}` }],
+          details: { ok: false, error: kimiLeakError },
+        }
+      }
+
       const result = await router.send({
         adapter,
         workspace: params.workspace,
@@ -163,9 +178,9 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
         })
         if (threadMismatch) hints.push(threadMismatch)
       }
-      const responseText = hints.length > 0 ? `${baseText} — ${hints.join(' ')}` : baseText
+      const body = hints.length > 0 ? `${baseText}${hints.join('')}` : baseText
       return {
-        content: [{ type: 'text' as const, text: responseText }],
+        content: [{ type: 'text' as const, text: `${TOOL_RESULT_PREFIX}${body}` }],
         details,
       }
     },
@@ -181,6 +196,11 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
 //
 // Only fires when the origin had a thread to begin with — channel-root
 // sessions can't have a "missing thread" problem.
+//
+// Body is fenced via `fenceRuntimeNotice` for the same reason the
+// consecutive-send hint is — see that helper's comment for the failure
+// mode (Kimi-K2.x reading trailing tool-result prose as a chat instruction
+// and replying to it in-character).
 function threadMismatchHint(
   origin: ChannelSendOrigin | undefined,
   sent: { adapter: AdapterId; workspace: string; chat: string; thread: string | undefined },
@@ -191,10 +211,10 @@ function threadMismatchHint(
   if (origin.adapter !== sent.adapter) return ''
   if (origin.workspace !== sent.workspace) return ''
   if (origin.chat !== sent.chat) return ''
-  return (
+  return fenceRuntimeNotice(
     `note: this session's origin thread is ${JSON.stringify(origin.thread)} but you posted to channel root. ` +
-    `if breaking out of the thread was intentional, ignore this; otherwise prefer \`channel_reply\` ` +
-    `or pass \`thread: ${JSON.stringify(origin.thread)}\` on your next channel_send.`
+      `if breaking out of the thread was intentional, ignore this; otherwise prefer \`channel_reply\` ` +
+      `or pass \`thread: ${JSON.stringify(origin.thread)}\` on your next channel_send.`,
   )
 }
 
@@ -233,16 +253,28 @@ function upstreamEmptyResponseSentinelError(text: string | undefined): string {
   )
 }
 
+function kimiToolCallLeakError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (!containsKimiToolDelimiter(text)) return ''
+  return (
+    'refusing to forward raw provider tool-call control tokens; these are chat-template ' +
+    'delimiters that should have been parsed into a real tool call upstream. ' +
+    'Re-issue the intended channel send as plain user-visible text only.'
+  )
+}
+
 // Returns a behavioral hint to nudge the model toward yielding when it has
 // been the only voice in the conversation for several messages. The router
 // increments its counter AFTER router.send returns, so a count of 1 means
 // "this is the second consecutive bot message in this chat:thread" — which
 // is the first count where a hint is warranted. Empty string at count <= 1
 // preserves the original tool-result text for the common single-reply case.
+// Mirror of channel-reply.ts; body wrapped via `fenceRuntimeNotice`.
 function consecutiveSendHint(countAfterSend: number): string {
   if (countAfterSend <= 1) return ''
-  if (countAfterSend === 2) {
-    return 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
-  }
-  return `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+  const body =
+    countAfterSend === 2
+      ? 'this is your 2nd consecutive message in this conversation; continue only if the reply genuinely needs splitting.'
+      : `${countAfterSend}th consecutive message with no user reply; end your turn now unless the user explicitly asked for a multi-step response.`
+  return fenceRuntimeNotice(body)
 }

package/src/agent/tools/restart.ts

@@ -27,6 +27,15 @@ export type CreateRestartToolOptions = {
   // fixes. Required even when stream is absent so the type stays simple and
   // the field's presence documents the runtime contract.
   originatingSessionId: string
+  // Override the default 5s ACK budget. Production has no caller for this —
+  // 5s is generous against a real hostd on the same host. Test-only seam:
+  // restart.test.ts spawns a `Bun.serve` and awaits its HTTP roundtrip from
+  // the same parallel-test-runner that hosts dozens of other workers
+  // contending on libuv's I/O threads. Under that contention, an in-process
+  // 127.0.0.1 fetch can occasionally exceed 5s and the test's `expect(ok:
+  // true)` assertion flips to `ok: false, reason: 'daemon ack timeout'`.
+  // Optional so production callers keep the 5s default unchanged.
+  ackTimeoutMs?: number
 }
 
 export type RestartToolDetails = { ok: boolean; containerName: string; reason?: string }
@@ -45,9 +54,11 @@ export function createRestartTool({
   hostdToken,
   stream,
   originatingSessionId,
+  ackTimeoutMs,
 }: CreateRestartToolOptions) {
   const doExit = exit ?? ((code: number) => process.exit(code))
   const httpUrl = hostdUrl ?? process.env.TYPECLAW_HOSTD_URL
+  const ackBudget = ackTimeoutMs ?? ACK_TIMEOUT_MS
   const httpToken = hostdToken ?? process.env.TYPECLAW_HOSTD_TOKEN
 
   return defineTool({
@@ -78,8 +89,8 @@ export function createRestartTool({
       const request = { kind: 'restart' as const, containerName, build }
       const reply =
         httpUrl && httpToken
-          ? await sendHttp(request, { timeoutMs: ACK_TIMEOUT_MS, url: httpUrl, token: httpToken })
-          : await send(request, { timeoutMs: ACK_TIMEOUT_MS, socket: socketPath ?? containerSocketPath() })
+          ? await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
+          : await send(request, { timeoutMs: ackBudget, socket: socketPath ?? containerSocketPath() })
       if (!reply.ok) {
         const details: RestartToolDetails = { ok: false, containerName, reason: reply.reason }
         return {

package/src/agent/tools/runtime-notice.ts

@@ -0,0 +1,41 @@
+// Wraps a runtime-emitted notice body in canonical SYSTEM MESSAGE framing so
+// persona-rich models cannot read the prose as a chat instruction from a
+// human and respond to it in-character.
+//
+// The failure mode this exists to prevent: tool results reach the model as
+// USER-role messages (provider tool-call contract — engines cannot tag them
+// as system). The `TOOL_RESULT_PREFIX` already marks each result's leading
+// position, but trailing natural-language hints (the consecutive-send nudge
+// is the canonical case) still parse as conversational prose, and Kimi-K2.x
+// has been observed in production responding to those hints in-character —
+// an apology directly addressed at the human ("sorry for talking so much,
+// I'll be quieter next time") when the only stimulus in the prompt was the
+// router's "Nth consecutive message; end your turn now" hint. Four
+// consecutive in-character replies to fenced-prose runtime hints in a
+// single drain iteration is the observed shape.
+//
+// Framing convention is the same shape `composeTurnPrompt` uses for the
+// loop-guard block in `router.ts` — bracketed marker, fence rules, and
+// explicit "Do not acknowledge or reply to this notice" closer. The
+// loop-guard block has been in production against Kimi for months without
+// the misread we observed on the consecutive-send hint, which is why we
+// reuse the exact same shape here.
+//
+// Applied unconditionally (not model-gated): the cost is ~40 tokens per
+// hint emission, paid only on consecutive sends (where the hint is already
+// firing), and the framing is safe for every model — well-behaved models
+// read it and move on. Gating by model family would have required a
+// traits table for one defense and would still need extending the moment
+// a second model family exhibited the same misread, so we accept the
+// universal cost in exchange for never having to remember to add a new
+// family to a list.
+export function fenceRuntimeNotice(body: string): string {
+  return (
+    '\n\n---\n' +
+    '**[SYSTEM MESSAGE — not from a human]**\n\n' +
+    body +
+    '\n\nThis is an automated signal from the channel router, not a message ' +
+    'from anyone in the chat. **Do not acknowledge or reply to this notice.**\n' +
+    '---'
+  )
+}

package/src/agent/tools/spawn-subagent.ts

@@ -130,7 +130,6 @@ export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions)
         startedAt,
         status: 'running' as const,
         abort: resolvedHandle.abort,
-        awaitCompletion: () => completion.then((c) => completionToFinalShape(c, now() - startedAt)),
       }
       liveRegistry.register(live)
 

package/src/agent/tools/subagent-output.ts

@@ -6,9 +6,6 @@ import type { PermissionService } from '@/permissions'
 import type { LiveSubagentRegistry, StatusSnapshot, SubagentProgressEvent } from '../live-subagents'
 import type { SessionOrigin } from '../session-origin'
 
-const DEFAULT_TIMEOUT_MS = 60_000
-const MAX_TIMEOUT_MS = 300_000
-
 export type SubagentOutputToolDetails =
   | {
       ok: true
@@ -57,43 +54,19 @@ export function createSubagentOutputTool(options: CreateSubagentOutputToolOption
       'Fetch the current state of a subagent you previously spawned. Returns one of three statuses: ' +
       "'running' (with a human-readable status_summary and a tail of recent progress events), " +
       "'completed' (with the final message), or 'failed' (with the error). " +
-      'Use this when the user asks how a long-running subagent is going, or when you need to retrieve the result of a backgrounded spawn. ' +
-      'When block=true (default false), the tool waits up to timeout_ms for completion before returning. ' +
-      'Prefer block=false and rely on the system-reminder for completion notification; reserve block=true for tight workflows.',
+      'Returns immediately with a snapshot — never blocks. ' +
+      'For backgrounded spawns, end your turn after spawning and wait for the completion <system-reminder>; ' +
+      'then call this once to fetch the result. Use it for ad-hoc status checks too — never in a polling loop.',
     parameters: Type.Object({
       task_id: Type.String({
         description: 'The task_id returned by a previous spawn_subagent call.',
       }),
-      block: Type.Optional(
-        Type.Boolean({
-          description:
-            'If true, wait for the subagent to complete (or time out) before returning. Default false: return immediately with the current state.',
-        }),
-      ),
-      timeout_ms: Type.Optional(
-        Type.Integer({
-          description: `When block=true, max milliseconds to wait (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}).`,
-          minimum: 1,
-          maximum: MAX_TIMEOUT_MS,
-        }),
-      ),
     }),
 
     async execute(_toolCallId, params) {
       if (permissions !== undefined && !permissions.has(getOrigin(), 'subagent.output')) {
         return errorResult('subagent.output denied: insufficient permissions')
       }
-      const live = liveRegistry.get(params.task_id)
-      if (live === undefined) {
-        return errorResult(`Unknown task_id: ${params.task_id}.`)
-      }
-
-      const wantsBlock = params.block === true && live.status === 'running'
-      if (wantsBlock) {
-        const timeoutMs = clampTimeout(params.timeout_ms)
-        await raceWithTimeout(live.awaitCompletion(), timeoutMs)
-      }
-
       const snap = liveRegistry.snapshot(params.task_id, now())
       if (snap === undefined) {
         return errorResult(`Unknown task_id: ${params.task_id}.`)
@@ -103,27 +76,6 @@ export function createSubagentOutputTool(options: CreateSubagentOutputToolOption
   })
 }
 
-function clampTimeout(value: number | undefined): number {
-  if (value === undefined) return DEFAULT_TIMEOUT_MS
-  return Math.min(Math.max(1, Math.floor(value)), MAX_TIMEOUT_MS)
-}
-
-async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T | undefined> {
-  return new Promise<T | undefined>((resolve) => {
-    const timer = setTimeout(() => resolve(undefined), timeoutMs)
-    promise.then(
-      (value) => {
-        clearTimeout(timer)
-        resolve(value)
-      },
-      () => {
-        clearTimeout(timer)
-        resolve(undefined)
-      },
-    )
-  })
-}
-
 type ToolReturn = {
   content: { type: 'text'; text: string }[]
   details: SubagentOutputToolDetails