typeclaw 0.28.2 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.28.2",
+  "version": "0.30.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'
@@ -208,6 +213,7 @@ export type CreateSessionOptions = {
   liveSubagentRegistry?: LiveSubagentRegistry
   subagentRegistry?: SubagentRegistry
   createSessionForSubagent?: CreateSessionForSubagent
+  allowBackgroundFromSubagent?: boolean
 }
 
 export type CreateSessionResult = {
@@ -256,6 +262,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 =
@@ -351,6 +358,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
               getOrigin,
               permissions: options.permissions,
               stream: options.stream,
+              allowBackgroundFromSubagent: options.allowBackgroundFromSubagent,
             }),
           ]
         : [
@@ -580,7 +588,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.
@@ -720,6 +728,7 @@ export function buildSubagentOrchestrationTools(opts: {
   getOrigin: () => SessionOrigin | undefined
   permissions: PermissionService | undefined
   stream: Stream | undefined
+  allowBackgroundFromSubagent?: boolean
 }): ToolDefinition[] {
   if (
     opts.liveRegistry === undefined ||
@@ -739,6 +748,9 @@ export function buildSubagentOrchestrationTools(opts: {
       getOrigin: opts.getOrigin,
       ...(opts.permissions ? { permissions: opts.permissions } : {}),
       ...(opts.stream ? { stream: opts.stream } : {}),
+      ...(opts.allowBackgroundFromSubagent !== undefined
+        ? { allowBackgroundFromSubagent: opts.allowBackgroundFromSubagent }
+        : {}),
     }),
     createSubagentOutputTool({
       liveRegistry: opts.liveRegistry,
@@ -899,6 +911,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 +975,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 +1013,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 +1039,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 +1114,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/live-subagents.ts

@@ -23,6 +23,11 @@ export type LiveSubagent = {
   // subagent_output/subagent_cancel. Absent when no permission service was
   // active at spawn, in which case the cap fails closed.
   spawnedByRole?: string
+  // True when spawned with run_in_background. Only background spawns deliver
+  // their result out-of-band (via the subagent.completed broadcast and the
+  // parent's drain); synchronous spawns return their result inline as the tool
+  // result, so the drain MUST NOT re-prompt for them. See runSubagentDrain.
+  background?: boolean
   startedAt: number
   status: SubagentStatus
   completion?: SubagentCompletion

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)
     },
   }
 }