typeclaw 0.5.1 → 0.7.0

package/src/agent/session-origin.ts

@@ -226,6 +226,21 @@ function renderChannelOrigin(
     'reply, your entire final visible response must be exactly `NO_REPLY`.',
     'Any other visible text without a channel tool call is blocked.',
     '',
+    '**Default to ONE reply per inbound.** Send a second `channel_reply` only',
+    'when the user genuinely benefits from it:',
+    '',
+    '- the user asked multiple distinct things and each deserves its own',
+    '  scoped answer,',
+    '- your reply exceeds the platform message limit and must be chunked,',
+    '- you need to post an attachment AND commentary on it on Discord (on',
+    '  Slack, pass `text` and `attachments` in a single `channel_reply` call),',
+    '- you are emitting progress updates during a long-running task and the',
+    '  channel would otherwise sit silent.',
+    '',
+    'Do NOT send a second reply just to rephrase, restate, summarize, or',
+    '"confirm in plain language" something you already said. After the first',
+    'reply lands, end your turn — the user will respond if they want more.',
+    '',
     'To reply in this conversation, call `channel_reply({ text })`. Addressing',
     `is filled in from this session, including the thread${origin.thread !== null ? '' : ' (none here — this is a channel-root session)'}, so you don't`,
     'need to copy any of these fields:',

package/src/agent/subagents.ts

@@ -19,17 +19,40 @@ export type SubagentContext<P = unknown> = {
 
 export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
-export type Subagent<P = unknown> = {
+// Fields shared verbatim between the plugin-author-facing `Subagent` in
+// `@/plugin/types` and the runtime-internal `Subagent` below. Every consumer
+// that reads from `SubagentRegistry` (the spawn_subagent tool, payload
+// validation, default session construction) only touches these fields, so
+// keeping them in a single declaration makes the plugin→internal shim a
+// rest-spread instead of a hand-maintained property list. Adding a new field
+// here surfaces it on both types in one edit, which is the regression class
+// the previous shim shape suffered: `visibility` and `requiresSpecificPermission`
+// existed on the plugin type but were silently dropped by the shim, so every
+// plugin-contributed public subagent appeared internal at the registry layer.
+//
+// The two fields that intentionally diverge — `tools` and `customTools` —
+// live on each concrete `Subagent` type below. The plugin side uses
+// `BuiltinToolRef[]` + `Tool<any>[]` (the public plugin API, decoupled from
+// pi-coding-agent's internal tool shape); the internal side uses the resolved
+// `AgentSessionTools` + `ToolDefinition[]` that pi-coding-agent actually
+// consumes. The boundary is real and load-bearing — collapsing it would
+// expose pi-coding-agent's internal API as part of the plugin contract.
+export type SubagentShared<P = unknown> = {
   systemPrompt: string
   // Model profile this subagent prefers. Resolved against `config.models` at
   // session construction. Unknown profile names fall back to `default` with
   // a warning. See `Subagent` in `@/plugin/types` for the full contract.
   profile?: string
-  tools?: AgentSessionTools
-  customTools?: ToolDefinition[]
   payloadSchema?: z.ZodType<P>
   handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
   toolResultBudget?: ToolResultBudget
+  visibility?: 'public' | 'internal'
+  requiresSpecificPermission?: boolean
+}
+
+export type Subagent<P = unknown> = SubagentShared<P> & {
+  tools?: AgentSessionTools
+  customTools?: ToolDefinition[]
 }
 
 export type SubagentRegistry = Readonly<Record<string, Subagent<any>>>
@@ -136,6 +159,17 @@ export type InvokeSubagentOptions = {
   spawnedByRole?: string
   spawnedByOrigin?: SessionOrigin
   onProviderError?: (errorMessage: string) => void
+  // Fires synchronously after the AgentSession is created and before
+  // session.prompt() is invoked, with both the live session reference and
+  // its allocated sessionId. The only consumer in production is the spawn
+  // tool's LiveSubagentRegistry path, which uses it to attach a progress
+  // subscriber and register the abort handle while invokeSubagent retains
+  // its `Promise<void>` external contract.
+  onSessionCreated?: (event: {
+    session: AgentSession
+    sessionId: string | undefined
+    abort: () => Promise<void>
+  }) => void
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -155,6 +189,15 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
     const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath } = normalizeSubagentSession(
       await createSessionForSubagent(subagent, sessionOptions),
     )
+    if (options.onSessionCreated !== undefined) {
+      options.onSessionCreated({
+        session,
+        sessionId,
+        abort: async () => {
+          await session.abort()
+        },
+      })
+    }
     const unsubProviderErrors =
       options.onProviderError !== undefined
         ? subscribeProviderErrors(session, (err) => options.onProviderError!(err.message))
@@ -204,6 +247,100 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
   }
 }
 
+export type SubagentHandle = {
+  taskId: string
+  sessionId: string | undefined
+  abort: () => Promise<void>
+}
+
+export type StartSubagentResult = {
+  handle: Promise<SubagentHandle>
+  completion: Promise<{ ok: true; finalMessage?: string } | { ok: false; error: string }>
+}
+
+export type StartSubagentOptions = InvokeSubagentOptions & {
+  taskId: string
+  onSession?: (event: { session: AgentSession; sessionId: string | undefined; abort: () => Promise<void> }) => void
+}
+
+// Non-blocking alternative to invokeSubagent. Returns immediately with two
+// promises:
+// - `handle` resolves with { taskId, sessionId, abort } once the AgentSession
+//   has been created (typically the first microtask). The taskId is what the
+//   caller chose; sessionId is allocated by the session factory.
+// - `completion` resolves when the subagent's prompt finishes, ok=true with
+//   an optional final message, or ok=false with an error message.
+// The two promises share a single underlying invokeSubagent invocation;
+// `completion` settles after dispose, so the session reference exposed via
+// `handle.abort` becomes a no-op once `completion` resolves.
+export function startSubagent(name: string, options: StartSubagentOptions): StartSubagentResult {
+  let resolveHandle: (h: SubagentHandle) => void
+  let rejectHandle: (err: Error) => void
+  const handle = new Promise<SubagentHandle>((resolve, reject) => {
+    resolveHandle = resolve
+    rejectHandle = reject
+  })
+  let handleSettled = false
+  let finalMessage: string | undefined
+
+  const completion = invokeSubagent(name, {
+    ...options,
+    onSessionCreated: (event) => {
+      handleSettled = true
+      resolveHandle({ taskId: options.taskId, sessionId: event.sessionId, abort: event.abort })
+      if (options.onSession !== undefined) {
+        options.onSession(event)
+      }
+      attachFinalMessageCapture(event.session, (msg) => {
+        finalMessage = msg
+      })
+    },
+  })
+    .then(() => ({ ok: true as const, ...(finalMessage !== undefined ? { finalMessage } : {}) }))
+    .catch((err: unknown) => {
+      const error = err instanceof Error ? err.message : String(err)
+      if (!handleSettled) {
+        rejectHandle(err instanceof Error ? err : new Error(error))
+      }
+      return { ok: false as const, error }
+    })
+
+  return { handle, completion }
+}
+
+function attachFinalMessageCapture(session: AgentSession, onFinalMessage: (msg: string) => void): void {
+  try {
+    session.subscribe((event: unknown) => {
+      const ev = event as { type?: string; message?: { content?: unknown } }
+      if (ev?.type !== 'message_end') return
+      const text = extractFinalMessageText(ev.message?.content)
+      if (text !== null) onFinalMessage(text)
+    })
+  } catch {
+    // session.subscribe is a stable upstream API; defensive try is for test
+    // doubles that don't implement it.
+  }
+}
+
+function extractFinalMessageText(content: unknown): string | null {
+  if (typeof content === 'string') {
+    const trimmed = content.trim()
+    return trimmed ? trimmed : null
+  }
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const part of content) {
+      if (part && typeof part === 'object' && (part as { type?: unknown }).type === 'text') {
+        const text = (part as { text?: unknown }).text
+        if (typeof text === 'string') parts.push(text)
+      }
+    }
+    const joined = parts.join('').trim()
+    return joined ? joined : null
+  }
+  return null
+}
+
 export type SubagentConsumerLogger = {
   info: (msg: string) => void
   warn: (msg: string) => void

package/src/agent/system-prompt.ts

@@ -50,6 +50,48 @@ Your agent folder is a git repository.
 - If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
 - Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
 
+## Subagent orchestration
+
+You can delegate focused work to subagents via three tools: \`spawn_subagent\`, \`subagent_output\`, \`subagent_cancel\`. Subagents run with their own context window and their own (often smaller, cheaper, or more constrained) tool set. The list of available subagents and what each one is for is rendered in the \`spawn_subagent\` tool description — re-read it before delegating.
+
+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.
+
+The bundled \`explorer\` subagent is the right tool for **local** reconnaissance — anything reachable on the agent's filesystem: code, past sessions (\`sessions/*.jsonl\`), MEMORY.md 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.
+
+The bundled \`scout\` subagent is its external counterpart — web research only. Use it when you need information from public sources (docs, library references, vendor changelogs, news, anything not already in this agent's folder). Scout runs \`websearch\` and \`webfetch\` in a fresh context window so the search churn does not pollute yours; it returns a citation-backed answer with a confidence rating. Prefer scout over running \`websearch\`/\`webfetch\` yourself when the research is non-trivial (more than 1-2 queries) or when you want to save your context for the synthesis step.
+
+**Mode B — Delegate-and-converse** (the user asked you to DO something long-running)
+
+When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
+
+Before you start an inline operation you expect to take more than ~30 seconds — a chain of \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that hits a slow API or scrapes a site, an \`agent-browser\` session, any "fetch N things in a loop" — pause and ask whether a subagent should run it instead. Inline long calls block the user from talking to you and pollute your context window with intermediate output; \`scout\` (for research) or \`operator\` (for actions with side effects) keeps the conversation responsive and returns a clean summary. The exception is a single quick call (one \`webfetch\` of a known URL, one \`websearch\` query you already know the shape of) — do those inline.
+
+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, 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.
+
+**Prompt structure for spawns** (mandatory — the subagent does not see this conversation)
+
+\`\`\`
+[CONTEXT]: What I'm working on, which files/modules are involved, what approach.
+[GOAL]: The specific decision or output I need to unlock.
+[REQUEST]: Concrete instructions — what to find/do/produce, what format, what to SKIP.
+\`\`\`
+
+**Anti-patterns**
+
+- 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 ask a research subagent to make architectural decisions for you — they find and report; you decide.
+- Subagents cannot recursively spawn other subagents.
+
 ## 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.

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

@@ -1,7 +1,7 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
+import { isNoReplySignal, isUpstreamEmptyResponseSentinel, type ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
@@ -89,6 +89,15 @@ export function createChannelReplyTool({
         }
       }
 
+      const upstreamSentinelError = upstreamEmptyResponseSentinelError(text)
+      if (upstreamSentinelError) {
+        logger.warn(formatChannelToolFailure('channel_reply', upstreamSentinelError))
+        return {
+          content: [{ type: 'text' as const, text: `channel_reply denied: ${upstreamSentinelError}` }],
+          details: { ok: false, error: upstreamSentinelError },
+        }
+      }
+
       const result = await router.send({
         adapter: origin.adapter,
         workspace: origin.workspace,
@@ -188,6 +197,20 @@ function noReplyMisuseError(text: string | undefined): string {
   )
 }
 
+// Mirror of the same guard used by channel_send. Blocks the upstream
+// `(Empty response: ...)` debug sentinel from being sent verbatim — that
+// payload carries the model's thinking content and signature, never a
+// real user-facing message.
+function upstreamEmptyResponseSentinelError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (!isUpstreamEmptyResponseSentinel(text)) return ''
+  return (
+    'refusing to forward an upstream `(Empty response: ...)` sentinel; ' +
+    "that string is a provider-SDK debug dump containing the model's thinking content and signature, " +
+    'not a message body. End your turn silently (visible text empty or `NO_REPLY`) instead.'
+  )
+}
+
 // 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.
 function consecutiveSendHint(countAfterSend: number): string {

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

@@ -1,7 +1,7 @@
 import { Type } from '@mariozechner/pi-ai'
 import { defineTool } from '@mariozechner/pi-coding-agent'
 
-import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
+import { isNoReplySignal, isUpstreamEmptyResponseSentinel, type ChannelRouter } from '@/channels/router'
 import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
 
 import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
@@ -112,6 +112,15 @@ export function createChannelSendTool({ router, origin, logger = consoleChannelL
         }
       }
 
+      const upstreamSentinelError = upstreamEmptyResponseSentinelError(bodyText)
+      if (upstreamSentinelError) {
+        logger.warn(formatChannelToolFailure('channel_send', upstreamSentinelError))
+        return {
+          content: [{ type: 'text' as const, text: `channel_send denied: ${upstreamSentinelError}` }],
+          details: { ok: false, error: upstreamSentinelError },
+        }
+      }
+
       const result = await router.send({
         adapter,
         workspace: params.workspace,
@@ -208,6 +217,22 @@ function noReplyMisuseError(text: string | undefined): string {
   )
 }
 
+// Defense-in-depth mirror of the recovery-path guard in router.ts. Blocks
+// the upstream "(Empty response: {...})" sentinel from being sent verbatim
+// as a channel message — the body of that sentinel carries the model's
+// thinking content and Anthropic's tamper-proof signature, which must
+// never reach a channel reader. Shape detection lives in
+// `isUpstreamEmptyResponseSentinel` so all call sites stay in lockstep.
+function upstreamEmptyResponseSentinelError(text: string | undefined): string {
+  if (text === undefined) return ''
+  if (!isUpstreamEmptyResponseSentinel(text)) return ''
+  return (
+    'refusing to forward an upstream `(Empty response: ...)` sentinel; ' +
+    "that string is a provider-SDK debug dump containing the model's thinking content and signature, " +
+    'not a message body. End your turn silently (visible text empty or `NO_REPLY`) instead.'
+  )
+}
+
 // 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

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

@@ -0,0 +1,283 @@
+import { randomUUID } from 'node:crypto'
+
+import { Type } from '@mariozechner/pi-ai'
+import { defineTool } from '@mariozechner/pi-coding-agent'
+
+import type { PermissionService } from '@/permissions'
+import type { Stream } from '@/stream'
+
+import { type LiveSubagentRegistry, type SubagentCompletion } from '../live-subagents'
+import type { SessionOrigin } from '../session-origin'
+import { type CreateSessionForSubagent, type Subagent, type SubagentRegistry, startSubagent } from '../subagents'
+
+export const SPAWN_TASK_ID_PREFIX = 'bg_'
+
+export type SpawnSubagentToolDetails =
+  | {
+      ok: true
+      mode: 'sync'
+      subagent: string
+      taskId: string
+      sessionId: string | undefined
+      durationMs: number
+      finalMessage?: string
+    }
+  | {
+      ok: true
+      mode: 'background'
+      subagent: string
+      taskId: string
+      sessionId: string | undefined
+    }
+  | { ok: false; error: string }
+
+export type CreateSpawnSubagentToolOptions = {
+  registry: SubagentRegistry
+  liveRegistry: LiveSubagentRegistry
+  createSessionForSubagent: CreateSessionForSubagent
+  agentDir: string
+  parentSessionId: string
+  getOrigin: () => SessionOrigin | undefined
+  permissions?: PermissionService
+  stream?: Stream
+  generateTaskId?: () => string
+  now?: () => number
+}
+
+export function createSpawnSubagentTool(options: CreateSpawnSubagentToolOptions) {
+  const {
+    registry,
+    liveRegistry,
+    createSessionForSubagent,
+    agentDir,
+    parentSessionId,
+    getOrigin,
+    permissions,
+    stream,
+    generateTaskId = () => `${SPAWN_TASK_ID_PREFIX}${randomUUID().replace(/-/g, '').slice(0, 12)}`,
+    now = () => Date.now(),
+  } = options
+
+  return defineTool({
+    name: 'spawn_subagent',
+    label: 'Spawn Subagent',
+    description: spawnSubagentDescription(registry),
+    parameters: Type.Object({
+      subagent_type: Type.String({
+        description:
+          'Name of the subagent to spawn. Must be a public subagent registered with this agent. See the system prompt section "Subagent orchestration" for the available list.',
+      }),
+      prompt: Type.String({
+        description:
+          'The full task description for the subagent. Use the [CONTEXT]/[GOAL]/[REQUEST] structure described in the system prompt. The subagent does not see the parent conversation; everything it needs must be in this string.',
+      }),
+      description: Type.Optional(
+        Type.String({
+          description: '3-5 word label for this spawn, used for logs and the status_summary. Optional.',
+        }),
+      ),
+      run_in_background: Type.Optional(
+        Type.Boolean({
+          description:
+            'When true, the spawn returns immediately with a task_id; the subagent runs in the background and a system-reminder is delivered when it completes. ' +
+            'When false (default), the spawn blocks until the subagent finishes and returns its final message synchronously. ' +
+            'Use background mode for long-running tasks where you want to keep the conversation moving (Mode B) or for parallel fan-out (Mode A).',
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params): Promise<ToolReturn> {
+      const origin = getOrigin()
+      const subagent = lookupPublicSubagent(registry, params.subagent_type)
+      if (subagent === null) {
+        return errorResult(formatUnknownSubagentError(registry, params.subagent_type))
+      }
+      if (!hasPermissionForSubagent(permissions, origin, params.subagent_type, subagent)) {
+        return errorResult('subagent.spawn denied: insufficient permissions')
+      }
+
+      const taskId = generateTaskId()
+      const subagentName = params.subagent_type
+      const background = params.run_in_background === true
+      const payload: Record<string, unknown> = { requestId: taskId, prompt: params.prompt }
+      if (params.description !== undefined) payload.description = params.description
+
+      const startedAt = now()
+      const { handle, completion } = startSubagent(subagentName, {
+        registry,
+        createSessionForSubagent,
+        agentDir,
+        userPrompt: params.prompt,
+        payload: subagent.payloadSchema ? payload : undefined,
+        parentSessionId,
+        ...(origin !== undefined ? { spawnedByOrigin: origin } : {}),
+        taskId,
+      })
+
+      let resolvedHandle: { taskId: string; sessionId: string | undefined; abort: () => Promise<void> } | undefined
+      try {
+        resolvedHandle = await handle
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        return errorResult(`failed to spawn ${subagentName}: ${message}`)
+      }
+
+      const live = {
+        taskId,
+        sessionId: resolvedHandle.sessionId ?? '<pending>',
+        subagentName,
+        parentSessionId,
+        startedAt,
+        status: 'running' as const,
+        abort: resolvedHandle.abort,
+        awaitCompletion: () => completion.then((c) => completionToFinalShape(c, now() - startedAt)),
+      }
+      liveRegistry.register(live)
+
+      void completion.then((c) => {
+        const durationMs = now() - startedAt
+        liveRegistry.recordCompletion(taskId, completionToFinalShape(c, durationMs))
+        if (stream && background) {
+          stream.publish({
+            target: { kind: 'broadcast' },
+            payload: {
+              kind: 'subagent.completed',
+              taskId,
+              subagent: subagentName,
+              parentSessionId,
+              ok: c.ok,
+              durationMs,
+              ...(c.ok ? {} : { error: c.error }),
+            },
+          })
+        }
+      })
+
+      if (background) {
+        const details: SpawnSubagentToolDetails = {
+          ok: true,
+          mode: 'background',
+          subagent: subagentName,
+          taskId,
+          sessionId: resolvedHandle.sessionId,
+        }
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Spawned ${subagentName} in background. task_id=${taskId}. You will receive a system-reminder when it completes. Use subagent_output to check progress or fetch results.`,
+            },
+          ],
+          details,
+        }
+      }
+
+      const result = await completion
+      const durationMs = now() - startedAt
+      if (!result.ok) {
+        const details: SpawnSubagentToolDetails = { ok: false, error: result.error }
+        return {
+          content: [{ type: 'text' as const, text: `${subagentName} failed after ${durationMs}ms: ${result.error}` }],
+          details,
+        }
+      }
+      const details: SpawnSubagentToolDetails = {
+        ok: true,
+        mode: 'sync',
+        subagent: subagentName,
+        taskId,
+        sessionId: resolvedHandle.sessionId,
+        durationMs,
+        ...(result.finalMessage !== undefined ? { finalMessage: result.finalMessage } : {}),
+      }
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text:
+              result.finalMessage !== undefined
+                ? result.finalMessage
+                : `${subagentName} completed in ${durationMs}ms with no final message.`,
+          },
+        ],
+        details,
+      }
+    },
+  })
+}
+
+export function spawnSubagentDescription(registry: SubagentRegistry): string {
+  const publicNames = publicSubagentNames(registry)
+  const available = publicNames.length > 0 ? publicNames.join(', ') : '(none registered yet)'
+  return (
+    `Spawn a subagent to do focused work on your behalf. Use this when a task is heavy enough to deserve a fresh context window (research fan-out) ` +
+    `or long-running enough that you want to keep the conversation moving while it runs (delegate-and-converse). ` +
+    `Available subagents: ${available}. ` +
+    `When run_in_background=true (preferred for long-running work), the tool returns a task_id immediately and the subagent runs concurrently — ` +
+    `you will receive a system-reminder when it completes; do NOT poll subagent_output. ` +
+    `When run_in_background=false (default), the tool blocks and returns the subagent's final message synchronously. ` +
+    `Subagents cannot recursively spawn other subagents.`
+  )
+}
+
+function publicSubagentNames(registry: SubagentRegistry): string[] {
+  return Object.entries(registry)
+    .filter(([, sub]) => isPublicSubagent(sub))
+    .map(([name]) => name)
+    .sort()
+}
+
+function isPublicSubagent(sub: Subagent<unknown>): boolean {
+  return sub.visibility === 'public'
+}
+
+function lookupPublicSubagent(registry: SubagentRegistry, name: string): Subagent<unknown> | null {
+  const sub = registry[name]
+  if (sub === undefined) return null
+  if (!isPublicSubagent(sub)) return null
+  return sub
+}
+
+function formatUnknownSubagentError(registry: SubagentRegistry, requested: string): string {
+  const names = publicSubagentNames(registry)
+  const available = names.length > 0 ? names.join(', ') : '(none)'
+  return `Unknown subagent: ${requested}. Available: ${available}.`
+}
+
+function hasPermissionForSubagent(
+  permissions: PermissionService | undefined,
+  origin: SessionOrigin | undefined,
+  subagentName: string,
+  subagent: Subagent<unknown>,
+): boolean {
+  if (permissions === undefined) return true
+  const specific = `subagent.spawn.${subagentName}`
+  if (subagent.requiresSpecificPermission === true) {
+    return permissions.has(origin, specific)
+  }
+  if (permissions.has(origin, specific)) return true
+  return permissions.has(origin, 'subagent.spawn')
+}
+
+function completionToFinalShape(
+  c: { ok: true; finalMessage?: string } | { ok: false; error: string },
+  durationMs: number,
+): SubagentCompletion {
+  if (c.ok) {
+    return { ok: true, durationMs, ...(c.finalMessage !== undefined ? { finalMessage: c.finalMessage } : {}) }
+  }
+  return { ok: false, error: c.error, durationMs }
+}
+
+type ToolReturn = {
+  content: { type: 'text'; text: string }[]
+  details: SpawnSubagentToolDetails
+}
+
+function errorResult(message: string): ToolReturn {
+  const details: SpawnSubagentToolDetails = { ok: false, error: message }
+  return {
+    content: [{ type: 'text', text: message }],
+    details,
+  }
+}