typeclaw 0.5.1 → 0.7.0

package/src/cron/schema.ts

@@ -151,6 +151,26 @@ function describeCronStep(step: CronMigrationStep): string {
   }
 }
 
+export type ParseCronJsonOptions = ParseCronOptions & {
+  // Apply `migrateLegacyCronShape` before schema validation. Defaults to true
+  // so the guard accepts the same legacy shapes `loadCron` would auto-migrate
+  // on disk; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+}
+
+export function parseCronJson(raw: string, options: ParseCronJsonOptions = {}): ParseCronResult {
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (err) {
+    return { ok: false, reason: `cron.json is not valid JSON: ${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate ? migrateLegacyCronShape(json) : { json, changed: false, applied: [] }
+  return parseCronFile(migrated.json, options.subagents !== undefined ? { subagents: options.subagents } : {})
+}
+
 export function parseCronFile(raw: unknown, options: ParseCronOptions = {}): ParseCronResult {
   const parsed = cronFileSchema.safeParse(raw)
   if (!parsed.success) {

package/src/init/dockerfile.ts

@@ -377,6 +377,33 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
  && chmod +x ${TYPECLAW_ENTRYPOINT_PATH}`
 }
 
+// Claude Code's official installer is `curl | bash`, not apt — can't live
+// in APT_FEATURES. Layer placed after the toggle apt install (so curl + ca-
+// certificates from the baseline are guaranteed present) and before the
+// entrypoint shim (which is always last). Omitted entirely when disabled.
+//
+// The Anthropic installer drops `claude` at `$HOME/.local/bin/claude` and
+// emits a "~/.local/bin is not in your PATH" warning on every install on
+// bun:1-slim (PATH out of the box is `/usr/local/sbin:/usr/local/bin:/usr/
+// sbin:/usr/bin:/sbin:/bin:/usr/local/bun-node-fallback-bin`, no
+// `~/.local/bin`). Without intervention, every `which claude` from the
+// agent (and from the typeclaw-claude-code skill's verification step)
+// returns empty. Symlink into `/usr/local/bin/` — already on PATH, matches
+// what `cloudflared` does, survives `/root/.local/bin` getting rewritten
+// by the installer's "update" path. The symlink resolves to the
+// `~/.local/bin/claude` shim, which itself dereferences to the versioned
+// binary under `~/.local/share/claude/versions/<ver>/`, so upgrades via
+// `claude update` keep working without re-running this layer.
+function renderClaudeCodeInstallLayer(enabled: boolean): string {
+  if (!enabled) return ''
+  return `# Layer 5.6 (toggle): install Anthropic's Claude Code CLI. Opt-in via
+# typeclaw.json#docker.file.claudeCode. The skill \`typeclaw-claude-code\`
+# documents the auth + usage flow.
+RUN curl -fsSL https://claude.ai/install.sh | bash \\
+ && ln -sf "$HOME/.local/bin/claude" /usr/local/bin/claude \\
+ && claude --version > /dev/null`
+}
+
 // Shared-library runtime deps Chrome for Testing needs to launch on amd64
 // Debian trixie (base of `oven/bun:1-slim`). `agent-browser install
 // --with-deps` (v0.27.0) is supposed to install these but silently no-ops:
@@ -454,10 +481,11 @@ export function buildDockerfile(
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
+  const claudeCodeLayer = renderClaudeCodeInstallLayer(config.claudeCode)
   const fromAndHeavyLayers =
     baseImageVersion !== null
-      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer)
+      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -504,15 +532,18 @@ function renderVersionedHead(
   ghKeyringLayer: string,
   toggleAptArgs: string[],
   cloudflaredLayer: string,
+  claudeCodeLayer: string,
 ): string {
   const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
+  const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
+  const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
 
 WORKDIR /agent
 
 ARG TARGETARCH
 
-${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer()}
+${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -521,8 +552,15 @@ ${ghKeyringLayer}${toggleAptLayer}${cloudflaredLayer}${renderEntrypointShimLayer
 // dev-mode runs (typeclaw installed via file: / link: spec) where the
 // matching :version GHCR tag does not yet exist, and by the test suite to
 // keep coverage of the full-stack layers independent of GHCR availability.
-function renderInlineHead(ghKeyringLayer: string, toggleAptArgs: string[], cloudflaredLayer: string): string {
+function renderInlineHead(
+  ghKeyringLayer: string,
+  toggleAptArgs: string[],
+  cloudflaredLayer: string,
+  claudeCodeLayer: string,
+): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
+  const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
+  const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   return `${FROM_AND_WORKDIR}
 
 # Layers are ordered most-stable first to maximize Docker layer cache hits on
@@ -565,7 +603,7 @@ ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${cloudflaredLayer}${renderEntrypointShimLayer()}
+${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -833,6 +871,7 @@ function defaultConfig(): DockerfileConfig {
     cjkFonts: true,
     cloudflared: true,
     xvfb: true,
+    claudeCode: false,
     append: [],
   }
 }

package/src/init/models-dev.ts

@@ -13,6 +13,7 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // (Codex is a backend, not a separate provider in their taxonomy). Curated
   // entries are surfaced regardless of upstream membership.
   'openai-codex': 'openai',
+  anthropic: 'anthropic',
   fireworks: 'fireworks-ai',
   zai: 'zai',
   // zai-coding (GLM Coding Plan) is a billing surface, not a separate model

package/src/permissions/builtins.ts

@@ -12,6 +12,10 @@ export const CORE_PERMISSIONS = {
   channelRespond: 'channel.respond',
   cronSchedule: 'cron.schedule',
   cronModify: 'cron.modify',
+  subagentSpawn: 'subagent.spawn',
+  subagentCancel: 'subagent.cancel',
+  subagentOutput: 'subagent.output',
+  subagentSpawnOperator: 'subagent.spawn.operator',
 } as const
 
 // Sentinel that `expandOwnerWildcard` swaps for the concrete union of
@@ -47,6 +51,10 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
       CORE_PERMISSIONS.channelRespond,
       CORE_PERMISSIONS.cronSchedule,
       CORE_PERMISSIONS.cronModify,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+      CORE_PERMISSIONS.subagentSpawnOperator,
       'security.bypass.low',
       'security.bypass.medium',
       OWNER_SECURITY_WILDCARD,
@@ -54,11 +62,24 @@ export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> =
   },
   trusted: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.low'],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.cronSchedule,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+      CORE_PERMISSIONS.subagentSpawnOperator,
+      'security.bypass.low',
+    ],
   },
   member: {
     match: [],
-    permissions: [CORE_PERMISSIONS.channelRespond],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.subagentSpawn,
+      CORE_PERMISSIONS.subagentCancel,
+      CORE_PERMISSIONS.subagentOutput,
+    ],
   },
   guest: {
     match: [],

package/src/plugin/define.ts

@@ -78,3 +78,5 @@ export const writeTool: BuiltinToolRef = { __builtinTool: 'write' }
 export const grepTool: BuiltinToolRef = { __builtinTool: 'grep' }
 export const findTool: BuiltinToolRef = { __builtinTool: 'find' }
 export const lsTool: BuiltinToolRef = { __builtinTool: 'ls' }
+export const websearchTool: BuiltinToolRef = { __builtinTool: 'websearch' }
+export const webfetchTool: BuiltinToolRef = { __builtinTool: 'webfetch' }

package/src/plugin/index.ts

@@ -9,6 +9,8 @@ export {
   grepTool,
   lsTool,
   readTool,
+  webfetchTool,
+  websearchTool,
   writeTool,
 } from './define'
 

package/src/plugin/types.ts

@@ -1,7 +1,7 @@
 import type { z } from 'zod'
 
 import type { SessionOrigin } from '@/agent/session-origin'
-import type { ToolResultBudget } from '@/agent/tool-result-budget'
+import type { SubagentShared } from '@/agent/subagents'
 import type { PermissionService } from '@/permissions'
 
 export type ContentPart = { type: 'text'; text: string } | { type: 'image'; mimeType: string; data: string }
@@ -40,35 +40,28 @@ export type SubagentContext<P = unknown> = {
 
 export type RunSession = (override?: { userPrompt?: string }) => Promise<void>
 
-export type Subagent<P = unknown> = {
-  systemPrompt: string
-  // Model profile this subagent prefers. Resolved against `models` in
-  // typeclaw.json at session construction. Unknown profile names fall back to
-  // `default` with a warning. Well-known names: `default`, `fast`, `deep`,
-  // `vision`. Subagents that want a specific tier (e.g. memory-logger wants
-  // `fast`, dreaming wants `deep`) declare it here so the user only has to
-  // map tier → model in config rather than wire each subagent individually.
-  profile?: string
+// The plugin-author-facing subagent declaration. Differs from
+// `@/agent/subagents`'s `Subagent` only in the shape of `tools`/`customTools`:
+// plugins reference builtin tools via tagged `BuiltinToolRef` strings (the
+// stable plugin API) and contribute their own `Tool<any>[]`; the runtime
+// resolves those refs to pi-coding-agent's wrapped tool shapes before the
+// session sees them. Every other field is inherited from `SubagentShared`
+// so a new shared field surfaces on both types in one edit. See
+// `SubagentShared`'s doc-comment for the regression history.
+//
+// `inFlightKey` lives here only (not on the shared shape) because it is
+// consumed exclusively by the `SubagentConsumer` via the
+// `pluginSubagentByName` map, which holds the original plugin reference —
+// the registry-flowing shim never needs to carry it.
+export type Subagent<P = unknown> = SubagentShared<P> & {
   tools?: BuiltinToolRef[]
   customTools?: Tool<any>[]
-  payloadSchema?: z.ZodType<P>
-  handler?: (ctx: SubagentContext<P>, runSession: RunSession) => Promise<void>
   // Coalescing key for the SubagentConsumer's in-flight set. Default is the
   // subagent name alone (only one instance of the subagent runs at a time).
   // Override to allow per-payload concurrency, e.g. memory-logger keyed by
   // parentSessionId so different parent sessions run in parallel while
   // duplicate runs against the same session deduplicate.
   inFlightKey?: (payload: P) => string
-  // Defensive ceiling on cumulative bytes of tool-result text per subagent
-  // run, applied to the named tools only. Once exceeded, subsequent calls to
-  // those tools short-circuit with a fixed message instructing the agent to
-  // stop reading. See `src/agent/tool-result-budget.ts` for the full
-  // rationale; the short version is: a single broken tool (e.g. find_entry
-  // failing because of a schema mismatch) can cause an agent to fall back to
-  // chunked reads of huge files, ballooning subagent token cost. The budget
-  // bounds the blast radius without changing per-call semantics for healthy
-  // runs.
-  toolResultBudget?: ToolResultBudget
 }
 
 // Cron job map keys are local; the runtime prefixes with `__plugin_<plugin-name>_`

package/src/run/bundled-plugins.ts

@@ -1,7 +1,10 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
+import explorerPlugin from '@/bundled-plugins/explorer'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
+import operatorPlugin from '@/bundled-plugins/operator'
+import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
 import toolResultCapPlugin from '@/bundled-plugins/tool-result-cap'
 import type { ResolvedPlugin } from '@/plugin'
@@ -36,4 +39,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
   { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
+  { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
+  { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
+  { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]

package/src/run/channel-session-factory.ts

@@ -1,6 +1,8 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession as defaultCreateSession } from '@/agent'
+import type { LiveSubagentRegistry } from '@/agent/live-subagents'
+import type { CreateSessionForSubagent, SubagentRegistry } from '@/agent/subagents'
 import { capJsonlFileInPlace } from '@/bundled-plugins/tool-result-cap/cap-jsonl'
 import type { CapOptions } from '@/bundled-plugins/tool-result-cap/cap-result'
 import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
@@ -48,6 +50,18 @@ export type BuildChannelSessionFactoryDeps = {
   // can assert exactly which CreateSessionOptions the factory builds without
   // needing a live LLM, plugin runtime, or session manager on disk.
   createSession?: typeof defaultCreateSession
+  // Subagent orchestration plumbing. All three (or none) are forwarded to
+  // createSession so the TUI/channel session exposes spawn_subagent,
+  // subagent_output, subagent_cancel. Subagent sessions never receive these
+  // — that branch is gated by pluginSubagent in createSessionWithDispose.
+  //
+  // `getCreateSessionForSubagent` is late-bound to break the construction
+  // cycle: channelManager owns the channel-session factory, which needs
+  // createSessionForSubagent, which needs channelManager.router. Same shape
+  // as `getChannelRouter` above.
+  liveSubagentRegistry?: LiveSubagentRegistry
+  subagentRegistry?: SubagentRegistry
+  getCreateSessionForSubagent?: () => CreateSessionForSubagent
 }
 
 // Tight basename validation so a tampered or corrupt channels/sessions.json
@@ -108,6 +122,11 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
       ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
+      ...(deps.liveSubagentRegistry !== undefined ? { liveSubagentRegistry: deps.liveSubagentRegistry } : {}),
+      ...(deps.subagentRegistry !== undefined ? { subagentRegistry: deps.subagentRegistry } : {}),
+      ...(deps.getCreateSessionForSubagent !== undefined
+        ? { createSessionForSubagent: deps.getCreateSessionForSubagent() }
+        : {}),
     })
 
     return {

package/src/run/index.ts

@@ -1,6 +1,7 @@
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession, createSessionWithDispose } from '@/agent'
+import { LiveSubagentRegistry } from '@/agent/live-subagents'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
   createSubagentConsumer,
@@ -9,6 +10,7 @@ import {
   type Subagent as InternalSubagent,
   type SubagentConsumer,
   type SubagentRegistry,
+  type SubagentShared,
 } from '@/agent/subagents'
 import { resolveCapOptionsFromConfig } from '@/bundled-plugins/tool-result-cap'
 import { createChannelManager, createChannelsReloadable, type ChannelManager } from '@/channels'
@@ -176,6 +178,8 @@ export async function startAgent({
     },
   })
 
+  const liveSubagentRegistry = new LiveSubagentRegistry()
+
   const channelManager = createChannelManagerFor({
     agentDir: cwd,
     channelsConfigRef: () => getConfig().channels,
@@ -191,6 +195,9 @@ export async function startAgent({
       getChannelRouter: () => channelManager.router,
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
+      liveSubagentRegistry,
+      subagentRegistry: pluginRuntime.get().subagents,
+      getCreateSessionForSubagent: () => createSessionForSubagent,
       ...containerNameOpt,
       ...runtimeVersionOpt,
     }),
@@ -347,6 +354,9 @@ export async function startAgent({
               },
             }
           : {}),
+        liveSubagentRegistry,
+        subagentRegistry: pluginRuntime.get().subagents,
+        createSessionForSubagent,
         ...containerNameOpt,
         ...runtimeVersionOpt,
       })
@@ -465,6 +475,8 @@ export async function startAgent({
     claimController,
     commandRunnerFactory,
     tunnelManager,
+    liveSubagentRegistry,
+    createSessionForSubagent,
     ...containerNameOpt,
     ...runtimeVersionOpt,
     ...tuiTokenOpt,
@@ -593,7 +605,15 @@ function makeDefaultSchedulerFactory(internalJobs: () => CronJob[]): SchedulerFa
   return ({ file, onFire }) => createScheduler({ jobs: [...file.jobs, ...internalJobs()], onFire })
 }
 
-function mergeSubagents(pluginRegistry: PluginRegistry): {
+// Exported for the regression test in `merge-subagents.test.ts`. The shim
+// layer between the plugin-author-facing `Subagent` (`@/plugin/types`) and
+// the runtime-internal `Subagent` (`@/agent/subagents`) is the load-bearing
+// translation point for visibility, payload-schema, and permission gating —
+// fields that flow through the `SubagentRegistry` without going through the
+// `pluginSubagentByShim` recovery path. Previous regressions silently
+// dropped fields here, hiding every public bundled subagent (scout,
+// explorer, operator) from the `spawn_subagent` tool surface.
+export function mergeSubagents(pluginRegistry: PluginRegistry): {
   registry: SubagentRegistry
   pluginSubagentByShim: WeakMap<InternalSubagent<any>, PluginSubagentEntry>
   pluginSubagentByName: Map<string, PluginSubagentEntry>
@@ -620,10 +640,40 @@ function mergeSubagents(pluginRegistry: PluginRegistry): {
   return { registry: merged, pluginSubagentByShim, pluginSubagentByName }
 }
 
+// Compile-time proof that every plugin-only key on `@/plugin`'s `Subagent`
+// (i.e. every key NOT inherited from `SubagentShared`) has been classified
+// for the shim. When a future maintainer introduces a new field on plugin-side
+// `Subagent` that isn't on `SubagentShared`, the `satisfies` clause on
+// `PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM` below fails at compile time until the
+// new key is listed there — and the destructuring in `pluginSubagentShim`
+// is updated to discard it. Without this guard, the shim's rest-spread
+// would silently leak future plugin-only fields into the internal registry —
+// the opposite-direction drift from the bug this PR fixes for shared fields.
+type PluginOnlySubagentKeys = Exclude<keyof import('@/plugin').Subagent<any>, keyof SubagentShared<any>>
+const PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM = {
+  tools: true,
+  customTools: true,
+  inFlightKey: true,
+} satisfies Record<PluginOnlySubagentKeys, true>
+// Reference the table so it's not dead code. The value is a runtime no-op;
+// the load-bearing work is the `satisfies` clause above which forces
+// exhaustive classification of plugin-only keys at compile time.
+void PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM
+
 function pluginSubagentShim(subagent: import('@/plugin').Subagent<any>): InternalSubagent<any> {
-  return {
-    systemPrompt: subagent.systemPrompt,
-    ...(subagent.payloadSchema ? { payloadSchema: subagent.payloadSchema } : {}),
-    ...(subagent.handler ? { handler: subagent.handler as InternalSubagent<any>['handler'] } : {}),
-  }
+  // The two diverging fields (`tools` is `BuiltinToolRef[]` plugin-side vs
+  // `AgentSessionTools` internal-side; `customTools` similarly differs) are
+  // resolved later in `createSessionForSubagent` via the
+  // `pluginSubagentByShim` lookup, which recovers the original plugin
+  // reference. `inFlightKey` is consumed only by the SubagentConsumer via
+  // `pluginSubagentByName`, not through this shim's registry path. Every
+  // other plugin-side field lives on `SubagentShared` and is structurally
+  // assignable to the internal `Subagent`, so a rest-spread carries them
+  // verbatim — including `visibility` and `requiresSpecificPermission`,
+  // whose silent drop in the previous shim made every plugin-contributed
+  // public subagent (scout, explorer, operator) invisible to the
+  // `spawn_subagent` tool. The list of keys removed here is enforced
+  // exhaustive at compile time by `PLUGIN_ONLY_KEYS_DROPPED_BY_SHIM` above.
+  const { tools: _tools, customTools: _customTools, inFlightKey: _inFlightKey, ...shared } = subagent
+  return shared
 }

package/src/server/index.ts

@@ -7,8 +7,10 @@ import {
   type CreateSessionResult,
 } from '@/agent'
 import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
+import type { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { detectProviderError } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
+import type { CreateSessionForSubagent } from '@/agent/subagents'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
 import type { HookBus } from '@/plugin'
@@ -79,6 +81,27 @@ export type ServerOptions = {
   // without it the four `exec_command`-family messages are answered with
   // `command_error` so the host CLI sees a clean failure.
   commandRunnerFactory?: (outbound: CommandOutbound) => CommandRunner
+  // Subagent orchestration plumbing for TUI sessions. Both fields must be
+  // present together for the spawn_subagent / subagent_output / subagent_cancel
+  // tools to surface; `createSession` gates registration on all three of
+  // (liveSubagentRegistry, subagentRegistry, createSessionForSubagent), and
+  // we derive subagentRegistry per WS connection from the same `pluginRuntime`
+  // snapshot that already feeds `plugins.registry` — so a reload landing
+  // mid-connection keeps using the snapshot the session opened with, matching
+  // the existing per-session lifecycle invariant.
+  //
+  // `createSessionForSubagent` is passed eagerly (not late-bound) because the
+  // TUI server is constructed AFTER the channel manager in `startAgent`,
+  // breaking the construction cycle that forces the channel session factory's
+  // `getCreateSessionForSubagent` late-binding.
+  //
+  // Channel and cron sessions get the same plumbing through
+  // `buildChannelSessionFactory` / `createSessionForCron` (see src/run/). The
+  // three top-level callers must stay aligned; otherwise the agent's tool
+  // surface diverges across origin kinds — exactly the gap PR #281 flagged
+  // as out-of-scope follow-up.
+  liveSubagentRegistry?: LiveSubagentRegistry
+  createSessionForSubagent?: CreateSessionForSubagent
 }
 
 const consoleLogger: ServerLogger = {
@@ -176,6 +199,8 @@ export function createServer({
   logger = consoleLogger,
   claimController,
   commandRunnerFactory,
+  liveSubagentRegistry,
+  createSessionForSubagent,
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
   const callIdToWs = new Map<string, AnyOwnerWs>()
@@ -351,6 +376,15 @@ export function createServer({
                   }
                 : undefined
             const origin: SessionOrigin = { kind: 'tui', sessionId: sessionFileId }
+            // Derive subagentRegistry from the same runtimeSnapshot that
+            // populates `plugins.registry`. createSession gates the orchestration
+            // tools on (liveRegistry, subagentRegistry, createSessionForSubagent,
+            // agentDir) being all-present; threading the registry alongside the
+            // two server-owned fields gives the gate a complete tuple for TUI
+            // sessions whenever the host plumbed in plugin runtime + subagent
+            // wiring (production), while keeping every existing test that omits
+            // either side at exactly its current tool surface.
+            const subagentRegistry = runtimeSnapshot?.subagents
             const result = await createSession({
               reloadRegistry,
               sessionManager,
@@ -360,6 +394,9 @@ export function createServer({
               ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
               ...(containerName !== undefined ? { containerName } : {}),
               ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
+              ...(liveSubagentRegistry !== undefined ? { liveSubagentRegistry } : {}),
+              ...(subagentRegistry !== undefined ? { subagentRegistry } : {}),
+              ...(createSessionForSubagent !== undefined ? { createSessionForSubagent } : {}),
             })
             const session = 'session' in result ? result.session : result
             const dispose = 'session' in result && result.dispose ? result.dispose : async () => {}
@@ -392,6 +429,7 @@ export function createServer({
               )
 
               state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
+                routeSubagentCompletionReminder(state, msg, stream)
                 const payload: ServerMessage = {
                   type: 'notification',
                   payload: msg.payload,
@@ -712,6 +750,71 @@ function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, s
   send(ws, { type: 'error', message: detected.message })
 }
 
+function routeSubagentCompletionReminder(state: SessionState, msg: StreamMessage, stream: Stream): void {
+  const payload = msg.payload
+  if (payload === null || typeof payload !== 'object') return
+  const p = payload as {
+    kind?: unknown
+    taskId?: unknown
+    subagent?: unknown
+    parentSessionId?: unknown
+    ok?: unknown
+    durationMs?: unknown
+    error?: unknown
+  }
+  if (p.kind !== 'subagent.completed') return
+  if (typeof p.parentSessionId !== 'string' || p.parentSessionId !== state.sessionFileId) return
+
+  const subagent = typeof p.subagent === 'string' ? p.subagent : 'subagent'
+  const taskId = typeof p.taskId === 'string' ? p.taskId : '<unknown>'
+  const ok = p.ok === true
+  const durationMs = typeof p.durationMs === 'number' ? p.durationMs : 0
+  const error = typeof p.error === 'string' ? p.error : undefined
+
+  const idle = state.drainQueue.length === 0 && !state.draining
+  const delivery = idle ? 'interrupt' : 'queue'
+  const text = renderCompletionReminder({ subagent, taskId, ok, durationMs, error })
+  stream.publish({
+    target: { kind: 'session', sessionId: state.sessionFileId },
+    payload: { kind: 'prompt', text, delivery },
+    meta: { source: 'subagent-completion' },
+  })
+}
+
+function renderCompletionReminder(args: {
+  subagent: string
+  taskId: string
+  ok: boolean
+  durationMs: number
+  error?: string
+}): string {
+  const durationStr = formatReminderDuration(args.durationMs)
+  if (args.ok) {
+    return (
+      `<system-reminder>\n` +
+      `Subagent \`${args.subagent}\` (${args.taskId}) completed in ${durationStr}. ` +
+      `Use subagent_output to fetch the result.\n` +
+      `</system-reminder>`
+    )
+  }
+  const err = args.error ?? 'unknown error'
+  return (
+    `<system-reminder>\n` +
+    `Subagent \`${args.subagent}\` (${args.taskId}) FAILED after ${durationStr}: ${err}. ` +
+    `Use subagent_output to inspect.\n` +
+    `</system-reminder>`
+  )
+}
+
+function formatReminderDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const totalSec = Math.floor(ms / 1000)
+  if (totalSec < 60) return `${totalSec}s`
+  const min = Math.floor(totalSec / 60)
+  const sec = totalSec % 60
+  return `${min}m${sec}s`
+}
+
 function enqueuePrompt(
   ws: Ws,
   state: SessionState,