typeclaw 0.28.2 → 0.29.0

package/package.json

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

package/src/agent/index.ts

@@ -53,7 +53,12 @@ import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
 import type { CreateSessionForSubagent, SubagentRegistry } from './subagents'
-import { DEFAULT_SYSTEM_PROMPT, renderRuntimeBlock, SLIM_SYSTEM_PROMPT } from './system-prompt'
+import {
+  buildDefaultSystemPrompt,
+  DEFAULT_SUBAGENT_ROSTER,
+  renderRuntimeBlock,
+  SLIM_SYSTEM_PROMPT,
+} from './system-prompt'
 import { attachToolNotFoundNudge } from './tool-not-found-nudge'
 import {
   createBudgetState,
@@ -69,7 +74,7 @@ import { createChannelSendTool } from './tools/channel-send'
 import { createGrantRoleTool } from './tools/grant-role'
 import { createRestartTool } from './tools/restart'
 import { createSkipResponseTool } from './tools/skip-response'
-import { createSpawnSubagentTool } from './tools/spawn-subagent'
+import { createSpawnSubagentTool, renderPublicSubagentRoster } from './tools/spawn-subagent'
 import { createStreamSnapshotTool } from './tools/stream-snapshot'
 import { createSubagentCancelTool } from './tools/subagent-cancel'
 import { createSubagentOutputTool } from './tools/subagent-output'
@@ -256,6 +261,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           ...(options.permissions ? { permissions: options.permissions } : {}),
           ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
           ...(options.mcpManager !== undefined ? { mcpManager: options.mcpManager } : {}),
+          ...(options.subagentRegistry !== undefined ? { subagentRegistry: options.subagentRegistry } : {}),
         })
 
   const getOrigin: () => SessionOrigin | undefined =
@@ -580,7 +586,7 @@ export function formatRestartNotice(restartedAt: string): string {
 
 // Variant for the session that called the `restart` tool. The user explicitly
 // asked this conversation to restart; staying silent after the reboot is the
-// reported bug ("뭐야 너네 재시작 한 것도 모르냐"). This notice instructs the
+// reported bug (e.g. "wait, you don't even know you restarted?"). This notice instructs the
 // model to acknowledge restart completion in its very next reply — once — then
 // stop mentioning it. Same SYSTEM MESSAGE framing as the sibling notice so
 // persona-rich models don't reply to the framing itself.
@@ -899,6 +905,12 @@ export type CreateResourceLoaderOptions = {
   mcpManager?: McpManager
   permissions?: PermissionService
   runtimeVersion?: string
+  // Public subagents whose names + `rosterDescription`s render the full-mode
+  // "## Subagent orchestration" roster. When omitted (no-registry callers, the
+  // debug dumper), the prompt falls back to `DEFAULT_SUBAGENT_ROSTER`. Threaded
+  // from `createSessionWithDispose`, where the merged registry is already in
+  // scope.
+  subagentRegistry?: SubagentRegistry
   // Explicit override for the prompt mode. When omitted, the mode is derived
   // from `origin.kind`: cron + subagent → slim, tui + channel → full. Pass
   // 'full' to force the heavy prompt even on an unattended origin (rarely
@@ -957,6 +969,11 @@ export type SystemPromptMode = 'full' | 'slim'
 export type SystemPromptComposition = {
   mode?: SystemPromptMode
   self: string
+  // Pre-rendered full-mode orchestration roster (from `renderPublicSubagentRoster`).
+  // Kept as a ready string so this composer stays pure and registry-free; the
+  // registry-aware caller renders it. Ignored in slim mode (no roster section).
+  // Falls back to `DEFAULT_SUBAGENT_ROSTER` when omitted.
+  subagentRoster?: string
   runtimeVersion?: string
   origin?: SessionOrigin
   roleContext?: SessionRoleContext
@@ -990,7 +1007,10 @@ export type SystemPromptComposition = {
 // suffix anyway — and removes the staleness failure mode where a session
 // opened Friday answered "today is Friday" on Thursday.
 export function composeSystemPrompt(parts: SystemPromptComposition): string {
-  const base = parts.mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
+  const base =
+    parts.mode === 'slim'
+      ? SLIM_SYSTEM_PROMPT
+      : buildDefaultSystemPrompt(parts.subagentRoster ?? DEFAULT_SUBAGENT_ROSTER)
   let prompt = `${base}\n\n${parts.self}`
   if (parts.runtimeVersion !== undefined) {
     prompt = `${prompt}\n\n${renderRuntimeBlock(parts.runtimeVersion)}`
@@ -1013,7 +1033,18 @@ export function composeSystemPrompt(parts: SystemPromptComposition): string {
 export async function createResourceLoader(options: CreateResourceLoaderOptions = {}): Promise<DefaultResourceLoader> {
   const agentDir = options.agentDir ?? process.cwd()
   const mode: SystemPromptMode = options.mode ?? deriveSystemPromptMode(options.origin)
-  const basePrompt = mode === 'slim' ? SLIM_SYSTEM_PROMPT : DEFAULT_SYSTEM_PROMPT
+  // Slim mode (cron/subagent) has no orchestration section, so it never reads
+  // the roster. Skip rendering it there — `renderPublicSubagentRoster` throws on
+  // a public subagent with a missing/blank `rosterDescription`, and a slim
+  // session must not fail on a roster it will never show.
+  const subagentRoster =
+    mode === 'slim'
+      ? undefined
+      : options.subagentRegistry !== undefined
+        ? renderPublicSubagentRoster(options.subagentRegistry)
+        : DEFAULT_SUBAGENT_ROSTER
+  const basePrompt =
+    mode === 'slim' ? SLIM_SYSTEM_PROMPT : buildDefaultSystemPrompt(subagentRoster ?? DEFAULT_SUBAGENT_ROSTER)
 
   // Kick off the three independent I/O paths concurrently. Sequential awaits
   // here used to be the dominant cold-start cost amplifier: loadSelf is 2
@@ -1077,6 +1108,7 @@ export async function createResourceLoader(options: CreateResourceLoaderOptions
   const systemPrompt = composeSystemPrompt({
     mode,
     self,
+    subagentRoster,
     ...(options.runtimeVersion !== undefined ? { runtimeVersion: options.runtimeVersion } : {}),
     ...(options.origin !== undefined ? { origin: options.origin } : {}),
     ...(roleContext !== undefined ? { roleContext } : {}),

package/src/agent/loop-guard.ts

@@ -52,9 +52,40 @@ const DEFAULT_PATH_TARGET = '.'
 
 const MAX_SESSIONS = 256
 
+// The one tool with result-sensitive loop semantics: a poll returning 'running'
+// is a legitimate wait, so its block is deferred until status is known (see
+// `noteResult` / `deferable`). Kept as a local literal rather than importing the
+// tool module to keep this primitive dependency-free; it must match
+// SUBAGENT_OUTPUT_TOOL_NAME in tools/subagent-output.ts.
+const SUBAGENT_OUTPUT_TOOL = 'subagent_output'
+
 export type LoopReason = 'consecutive' | 'windowed'
 
+// Identifies the single observation a `check` recorded so a caller can retract
+// exactly that one after learning post-execution it was not a loop (e.g. a
+// `subagent_output` poll that returned `status: 'running'`). Narrower than
+// `forgetTool`, which drops the whole tool window: retract undoes one call, so
+// unrelated task_ids and terminal-result polls keep their accumulated signal.
+export type LoopGuardReceipt = {
+  sessionId: string
+  tool: string
+  signature: string
+  windowSignature: string
+}
+
+// Post-execution classification of a `subagent_output` poll, fed back via
+// `noteResult`. 'running' is a still-pending wait; 'terminal' is completed/failed
+// — a repeated terminal poll is a real loop.
+export type LoopObservedResult = 'running' | 'terminal'
+
 export type LoopGuardDecision =
+  | { kind: 'ok'; receipt: LoopGuardReceipt }
+  | { kind: 'warn'; count: number; reason: LoopReason; message: string; receipt: LoopGuardReceipt }
+  | { kind: 'block'; count: number; reason: LoopReason; message: string; receipt: LoopGuardReceipt; deferable: boolean }
+
+// A decision before its receipt is attached. The detector helpers produce these;
+// `check` stamps the receipt on at its single return site.
+type Verdict =
   | { kind: 'ok' }
   | { kind: 'warn'; count: number; reason: LoopReason; message: string }
   | { kind: 'block'; count: number; reason: LoopReason; message: string }
@@ -71,6 +102,21 @@ export type LoopGuard = {
   // premature polls poisoned the window. Narrower than `forget`, so an
   // unrelated tool's accumulating loop on the same session is preserved.
   forgetTool: (sessionId: string, tool: string) => void
+  // Undoes the one observation a prior `check` recorded, identified by its
+  // receipt. Pops that signature from the windowed history and, when the
+  // current consecutive streak is the call this receipt named (it is the most
+  // recent `check` on the session, since tool execution within a turn is
+  // sequential), rewinds the streak by one. Used post-execution for a
+  // `subagent_output` poll that returned `status: 'running'` — a still-pending
+  // wait, not a loop — so it never accumulates toward either detector.
+  retract: (receipt: LoopGuardReceipt) => void
+  // Records the post-execution class of a `subagent_output` poll. Once a
+  // signature is seen 'terminal', `check` stops marking its blocks `deferable`,
+  // so further identical polls hard-block PRE-execute instead of running again
+  // just to re-confirm a completed task. 'running' clears any prior terminal
+  // mark for that signature (a task can only move running→terminal, but a
+  // signature can be reused across episodes).
+  noteResult: (receipt: LoopGuardReceipt, result: LoopObservedResult) => void
 }
 
 type SessionState = {
@@ -84,6 +130,10 @@ type SessionState = {
   // still present in the window.
   window: string[]
   windowWarned: Set<string>
+  // Exact signatures whose `subagent_output` poll has been observed terminal.
+  // A block on such a signature is enforced pre-execute (not deferred), so a
+  // completed task is not re-polled forever just to re-learn it is done.
+  termKnown: Set<string>
 }
 
 export type CreateLoopGuardOptions = {
@@ -134,7 +184,7 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     }
   }
 
-  function evaluateConsecutive(state: SessionState, tool: string): LoopGuardDecision {
+  function evaluateConsecutive(state: SessionState, tool: string): Verdict {
     if (state.count >= hardBlock) {
       return {
         kind: 'block',
@@ -150,32 +200,38 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     return { kind: 'ok' }
   }
 
-  function evaluateWindowed(state: SessionState, tool: string, windowSig: string): LoopGuardDecision {
+  function evaluateWindowed(state: SessionState, tool: string, windowSig: string): Verdict {
     const count = state.window.reduce((n, sig) => (sig === windowSig ? n + 1 : n), 0)
     if (count >= windowHardBlock) {
-      return {
-        kind: 'block',
-        count,
-        reason: 'windowed',
-        message: formatWindowedBlockMessage(tool, count),
-      }
+      return { kind: 'block', count, reason: 'windowed', message: formatWindowedBlockMessage(tool, count) }
     }
     if (count >= windowSoftWarn && !state.windowWarned.has(windowSig)) {
       state.windowWarned.add(windowSig)
-      return {
-        kind: 'warn',
-        count,
-        reason: 'windowed',
-        message: formatWindowedWarnMessage(tool, count),
-      }
+      return { kind: 'warn', count, reason: 'windowed', message: formatWindowedWarnMessage(tool, count) }
     }
     return { kind: 'ok' }
   }
 
+  function resolveVerdict(state: SessionState, tool: string, windowSig: string): Verdict {
+    const consecutive = evaluateConsecutive(state, tool)
+    if (consecutive.kind === 'block') return consecutive
+
+    // Back-to-back identical calls are the consecutive detector's domain; let
+    // it own them so a tight streak doesn't also trip the windowed detector.
+    // The windowed detector exists for INTERLEAVED cycles, so it only acts
+    // when this call breaks the immediate streak (count === 1).
+    const windowed = state.count === 1 ? evaluateWindowed(state, tool, windowSig) : { kind: 'ok' as const }
+    if (windowed.kind === 'block') return windowed
+    if (consecutive.kind === 'warn') return consecutive
+    if (windowed.kind === 'warn') return windowed
+    return { kind: 'ok' }
+  }
+
   return {
     check(sessionId, tool, args) {
       const signature = makeCallSignature(tool, args)
       const windowSig = makeWindowSignature(tool, args)
+      const receipt: LoopGuardReceipt = { sessionId, tool, signature, windowSignature: windowSig }
       const existing = sessions.get(sessionId)
 
       const state: SessionState = existing ?? {
@@ -184,6 +240,7 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
         warned: false,
         window: [],
         windowWarned: new Set(),
+        termKnown: new Set(),
       }
 
       if (state.signature !== signature) {
@@ -204,18 +261,14 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
 
       touch(sessionId, state)
 
-      const consecutive = evaluateConsecutive(state, tool)
-      if (consecutive.kind === 'block') return consecutive
-
-      // Back-to-back identical calls are the consecutive detector's domain; let
-      // it own them so a tight streak doesn't also trip the windowed detector.
-      // The windowed detector exists for INTERLEAVED cycles, so it only acts
-      // when this call breaks the immediate streak (count === 1).
-      const windowed = state.count === 1 ? evaluateWindowed(state, tool, windowSig) : { kind: 'ok' as const }
-      if (windowed.kind === 'block') return windowed
-      if (consecutive.kind === 'warn') return consecutive
-      if (windowed.kind === 'warn') return windowed
-      return { kind: 'ok' }
+      const verdict = resolveVerdict(state, tool, windowSig)
+      if (verdict.kind === 'block') {
+        // A `subagent_output` block is deferable (let the boundary call execute
+        // to learn its status) only until this signature has proven terminal.
+        const deferable = tool === SUBAGENT_OUTPUT_TOOL && !state.termKnown.has(signature)
+        return { ...verdict, receipt, deferable }
+      }
+      return { ...verdict, receipt }
     },
     reset(sessionId) {
       sessions.delete(sessionId)
@@ -240,6 +293,39 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
         state.count = 0
         state.warned = false
       }
+      for (const sig of state.termKnown) {
+        if (signatureBelongsToTool(sig, tool)) state.termKnown.delete(sig)
+      }
+    },
+    retract(receipt) {
+      const state = sessions.get(receipt.sessionId)
+      if (state === undefined) return
+
+      // Pop the receipt's windowed observation. It is the most recent push for
+      // this signature (retraction runs immediately after the call's execute,
+      // before any other tool runs on the session), so remove the last match.
+      const lastIdx = state.window.lastIndexOf(receipt.windowSignature)
+      if (lastIdx !== -1) {
+        state.window.splice(lastIdx, 1)
+        if (!state.window.includes(receipt.windowSignature)) {
+          state.windowWarned.delete(receipt.windowSignature)
+        }
+      }
+
+      // Rewind the consecutive streak by one only if it is still the call this
+      // receipt named. A retracted soft-warned streak re-arms its warning so the
+      // next genuine repeat warns as if this call never happened.
+      if (state.signature === receipt.signature && state.count > 0) {
+        state.count -= 1
+        if (state.count < softWarn) state.warned = false
+        if (state.count === 0) state.signature = ''
+      }
+    },
+    noteResult(receipt, result) {
+      const state = sessions.get(receipt.sessionId)
+      if (state === undefined) return
+      if (result === 'terminal') state.termKnown.add(receipt.signature)
+      else state.termKnown.delete(receipt.signature)
     },
   }
 }

package/src/agent/plugin-tools.ts

@@ -45,9 +45,10 @@ import {
   subtractMasked,
 } from '@/sandbox'
 
-import { createLoopGuard, type LoopGuard } from './loop-guard'
+import { createLoopGuard, type LoopGuard, type LoopGuardDecision } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
+import { SUBAGENT_OUTPUT_TOOL_NAME, type SubagentOutputToolDetails } from './tools/subagent-output'
 import { webFetchTool } from './tools/webfetch'
 import { webSearchTool } from './tools/websearch'
 
@@ -241,10 +242,10 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(`blocked: ${blockResult.reason}`)
       }
 
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, opts.toolName, before.args)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, opts.toolName, before.args)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        return errorResult(loopDecision.message)
+        return errorResult(loopGate.message)
       }
 
       const toolCtx: ToolContext = {
@@ -262,9 +263,12 @@ export function wrapPluginTool(tool: Tool<any>, opts: WrapToolOptions): ToolDefi
         return errorResult(message)
       }
 
-      if (loopDecision.kind === 'warn') {
-        result = appendLoopWarning(result, loopDecision.message)
+      const resolved = loopGate.resolve(result)
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        return errorResult(resolved.deferredBlock)
       }
+      result = resolved.result
 
       await opts.hooks.runToolAfter({
         tool: opts.toolName,
@@ -301,10 +305,10 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -321,15 +325,12 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate, ctx)
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
-      }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -337,7 +338,7 @@ export function wrapSystemTool<TParams extends TSchema, TDetails = unknown, TSta
         result: hookResult,
       })
       return {
-        content: hookResult.content,
+        content: hookResult.content as ContentPart[],
         details: hookResult.details as TDetails,
       }
     },
@@ -364,10 +365,10 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       if (blockResult !== undefined) {
         throw new Error(`blocked: ${blockResult.reason}`)
       }
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -384,15 +385,12 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
       stripGuardAcknowledgements(mutableArgs)
 
       const result = await tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate)
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
-      }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -400,7 +398,7 @@ export function wrapSystemAgentTool<TParams extends TSchema, TDetails = unknown>
         result: hookResult,
       })
       return {
-        content: hookResult.content,
+        content: hookResult.content as ContentPart[],
         details: hookResult.details as TDetails,
       }
     },
@@ -442,10 +440,10 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       // loop-detection state, or pi's execute.
       const bashEnvOverlay = readBashEnvOverlay(mutableArgs)
       delete mutableArgs[TYPECLAW_INTERNAL_BASH_ENV]
-      const loopDecision = sharedLoopGuard.check(opts.sessionId, tool.name, mutableArgs)
-      if (loopDecision.kind === 'block') {
+      const loopGate = gateLoopGuard(opts.sessionId, tool.name, mutableArgs)
+      if (loopGate.blockNow) {
         fireLoopAbort(opts.getAbort)
-        throw new Error(loopDecision.message)
+        throw new Error(loopGate.message)
       }
       const guardResult = await runFinalWriteGuards({
         tool: tool.name,
@@ -472,15 +470,12 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       const result = await bashEnvStore.run(bashEnvOverlay, () =>
         tool.execute(toolCallId, mutableArgs as Static<TParams>, signal, onUpdate),
       )
-      const hookResult: ToolResult = {
-        content: result.content as ContentPart[],
-        details: result.details,
-      }
-      if (loopDecision.kind === 'warn') {
-        const warned = appendLoopWarning(hookResult, loopDecision.message)
-        hookResult.content = warned.content
-        hookResult.details = warned.details
+      const resolved = loopGate.resolve({ content: result.content as ContentPart[], details: result.details })
+      if ('deferredBlock' in resolved) {
+        fireLoopAbort(opts.getAbort)
+        throw new Error(resolved.deferredBlock)
       }
+      const hookResult = resolved.result
       await opts.hooks.runToolAfter({
         tool: tool.name,
         sessionId: opts.sessionId,
@@ -609,6 +604,72 @@ function appendLoopWarning(result: ToolResult, message: string): ToolResult {
   return { content, details: result.details }
 }
 
+// `subagent_output` is a read-only poll whose loop/no-loop classification only
+// becomes knowable AFTER execution: a result of `status: 'running'` is a
+// still-pending wait (legitimate), while a repeated terminal result is a real
+// loop. The loop guard's `check` is result-blind and pre-execution, so for this
+// one tool we DEFER enforcing a block until the status is known — otherwise the
+// exact poll that would reveal 'running' gets blocked before it can run (the
+// boundary-call hazard for round-robin fan-out polling). Every other tool
+// enforces its block immediately, as before.
+// A block is deferred only for a `subagent_output` poll the guard still marks
+// `deferable` — i.e. whose signature has not yet proven terminal. Once a poll of
+// that signature returns completed/failed, `deferable` is false and the block is
+// enforced pre-execute, so a finished task is not re-polled forever.
+function shouldDeferLoopBlock(toolName: string, decision: LoopGuardDecision): boolean {
+  return toolName === SUBAGENT_OUTPUT_TOOL_NAME && decision.kind === 'block' && decision.deferable
+}
+
+function subagentPollStatus(toolName: string, result: ToolResult): 'running' | 'terminal' | undefined {
+  if (toolName !== SUBAGENT_OUTPUT_TOOL_NAME) return undefined
+  const details = result.details as SubagentOutputToolDetails | undefined
+  if (details?.ok !== true) return undefined
+  return details.status === 'running' ? 'running' : 'terminal'
+}
+
+type LoopGuardGate = {
+  // True when the guard wants to block AND the block is enforced now (every tool
+  // except a deferable `subagent_output` poll). The caller aborts + errors.
+  blockNow: boolean
+  message: string
+  // Resolves the guard against the tool's result. Returns the result to surface
+  // (possibly warn-annotated), or `{ deferredBlock: message }` when a deferred
+  // `subagent_output` block must now be enforced because the poll did not return
+  // a still-running status.
+  resolve: (result: ToolResult) => { result: ToolResult } | { deferredBlock: string }
+}
+
+// Single chokepoint for the loop-guard pre-check + post-execute resolution so
+// all four tool wrappers share identical deferred-block / pending-retract
+// semantics. `check` runs here (recording the observation); the returned
+// `resolve` is called after execute with the tool's result, feeding the poll's
+// running/terminal status back to the guard so future blocks stop deferring.
+function gateLoopGuard(sessionId: string, toolName: string, args: unknown): LoopGuardGate {
+  const decision = sharedLoopGuard.check(sessionId, toolName, args)
+  const defer = shouldDeferLoopBlock(toolName, decision)
+  return {
+    blockNow: decision.kind === 'block' && !defer,
+    message: decision.kind === 'ok' ? '' : decision.message,
+    resolve(result) {
+      const pollStatus = subagentPollStatus(toolName, result)
+      if (pollStatus !== undefined) {
+        sharedLoopGuard.noteResult(decision.receipt, pollStatus)
+      }
+      if (pollStatus === 'running') {
+        sharedLoopGuard.retract(decision.receipt)
+        return { result }
+      }
+      if (defer && decision.kind === 'block') {
+        return { deferredBlock: decision.message }
+      }
+      if (decision.kind === 'warn') {
+        return { result: appendLoopWarning(result, decision.message) }
+      }
+      return { result }
+    },
+  }
+}
+
 // Clears one tool's loop-guard residue for a session on the process-wide shared
 // guard. The completion-reminder bridges (channel router + TUI server) call this
 // for `subagent_output` when a backgrounded subagent finishes, so the next fetch

package/src/agent/session-origin.ts

@@ -630,9 +630,9 @@ function renderParticipants(
 // mention syntax) and Telegram (uses `@username`, where `authorId` is a
 // numeric id and NOT the username). See issue #188.
 //
-// Symptom in the wild before PR #183 + this fix: 돌쇠 addressing Winky as
-// "Winky님" (plain text) on Discord, which never trips Winky's `isBotMention`
-// check, so Winky observes silently and the conversation stalls. The
+// Symptom in the wild before PR #183 + this fix: Kiki addressing Momo as
+// "Momo님" (plain text) on Discord, which never trips Momo's `isBotMention`
+// check, so Momo observes silently and the conversation stalls. The
 // angle-id branch here is exactly the fix for that case; the at-username
 // and alias branches keep the platform contract honest for KakaoTalk and
 // Telegram instead of self-contradicting the per-adapter mention guidance

package/src/agent/subagents.ts

@@ -48,6 +48,13 @@ export type SubagentShared<P = unknown> = {
   handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
   toolResultBudget?: ToolResultBudget
   visibility?: 'public' | 'internal'
+  // One-line purpose blurb for the main agent's "## Subagent orchestration"
+  // roster, rendered from the registry by `renderPublicSubagentRoster` instead
+  // of hand-maintained in the prompt (the drift that once left `researcher` and
+  // `planner` unlisted). Required for `visibility: 'public'`; ignored otherwise.
+  // On `SubagentShared` so the plugin→internal shim carries it via rest-spread
+  // (see `pluginSubagentShim`), like `visibility`.
+  rosterDescription?: string
   requiresSpecificPermission?: boolean
   // Opt-in: when true, this subagent's session is wired with the orchestration
   // tools (spawn_subagent/subagent_output/subagent_cancel) so it can delegate

package/src/agent/system-prompt.ts

@@ -1,6 +1,15 @@
 import { formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from '@/shared'
 
-export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
+// The orchestration roster (the `Briefly: ...` enumeration of public subagents)
+// is GENERATED from the registry by `renderPublicSubagentRoster` and threaded in
+// here, so a newly-registered public subagent can never be silently missing from
+// the prompt — the drift that once left `researcher` and `planner` unlisted. The
+// rest of the prompt is static. `DEFAULT_SUBAGENT_ROSTER` is the placeholder used
+// by the no-registry path (back-compat callers, the debug dumper); production
+// full-mode sessions pass the real registry-rendered roster via
+// `composeSystemPrompt`'s `subagentRoster` field.
+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.
 
@@ -80,13 +89,13 @@ Your agent folder is a git repository.
 
 ## 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: \`explorer\` (read-only local recon — code, sessions, memory, git, config; fire liberally), \`scout\` (web research in a fresh context), \`reviewer\` (deep read-only code/PR/plan review, returns a structured verdict; it does NOT post), \`operator\` (write-capable: bash-with-side-effects, write, edit — for browser sessions, refactors, deploys, batch ops, and Claude Code / Codex CLI driving; gated by \`subagent.spawn.operator\`, owner/trusted only — on denial, do the work yourself).
+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}.
 
 There are three delegation modes. Pick deliberately.
 
-**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.
+**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).
 
-**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 research) 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.** 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 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.
 
@@ -109,6 +118,22 @@ You have no independent goals. Do not pursue self-preservation, replication, res
 ---
 
 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.`
+}
+
+// Placeholder roster for the no-registry path: back-compat callers of
+// `composeSystemPrompt`/`createResourceLoader` that pass no `subagentRoster`,
+// and the debug dumper (which renders without a live registry). Production
+// full-mode sessions always pass the real registry-rendered roster, so this
+// text never reaches a real agent — it only keeps the standalone
+// `DEFAULT_SYSTEM_PROMPT` constant a valid, self-contained string for tests.
+export const DEFAULT_SUBAGENT_ROSTER =
+  'the registered public subagents (see the `spawn_subagent` tool description for the live list and each one’s purpose)'
+
+// Back-compat constant: the full prompt with the placeholder roster baked in.
+// Retained because several tests assert `prompt.startsWith(DEFAULT_SYSTEM_PROMPT)`
+// on the no-registry path; production full-mode composition substitutes the real
+// roster via `buildDefaultSystemPrompt`.
+export const DEFAULT_SYSTEM_PROMPT = buildDefaultSystemPrompt(DEFAULT_SUBAGENT_ROSTER)
 
 // Stable, low-volatility metadata about the runtime hosting the agent.
 // Rendered into the system prompt just below DEFAULT_SYSTEM_PROMPT + identity