typeclaw 0.5.0 → 0.6.0

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
@@ -561,9 +599,11 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${cloudflaredLayer}${renderEntrypointShimLayer()}
+${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -638,6 +678,8 @@ ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
 
+${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
+
 ${LAYER_5_CHROME_FOR_TESTING}
 
 ${renderEntrypointShimLayer()}
@@ -699,6 +741,114 @@ const LAYER_4_AGENT_BROWSER_INSTALL = `# Layer 4 (volatile): install agent-brows
 RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
     bun install -g agent-browser`
 
+// Layer 4.5: shim the agent-browser binary with a wrapper that calls
+// \`agent-browser close\` before \`open\`/\`goto\`/\`navigate\` when headed
+// mode is requested. Works around vercel-labs/agent-browser issue #1083
+// ("headed silently ignored on existing session"): when a daemon is
+// already running with a headless browser, subsequent commands with
+// --headed / AGENT_BROWSER_HEADED reuse the existing headless browser
+// regardless of the requested mode. Three upstream fix PRs (#660, #370,
+// #387) have been open and unmerged for months as of 2026-05, so we
+// patch this locally rather than block on upstream.
+//
+// Allowlist, not denylist. The wrapper only pre-closes on the three
+// commands that explicitly start a new browsing session (\`open\`,
+// \`goto\`, \`navigate\`). Every other agent-browser subcommand — \`click\`,
+// \`snapshot\`, \`chat\`, \`connect\`, \`batch\`, \`tab\`, \`record\`, \`trace\`,
+// \`stream\`, \`cookies\`, \`network\`, ... — passes through untouched.
+// Rationale: those subcommands may operate on the live browser/page
+// state (cookies, in-progress recording, attached external CDP, etc.),
+// and a pre-close from us would silently destroy it. The user-reported
+// scenario for #1083 (\"\`agent-browser open <url> --headed\` after a
+// previous headless invocation\") is fully covered because the
+// follow-up commands inherit the now-headed browser the \`open\`
+// pre-close forced. An earlier draft used a deny-list approach that
+// pre-closed on every non-skip subcommand under headed env; oracle
+// self-review flagged the state-destruction risk for stateful commands,
+// and the allowlist fix is the resulting narrower contract.
+//
+// Truthy contract mirrors upstream's \`env_var_is_truthy\`
+// (cli/src/flags.rs:183): any non-empty value EXCEPT case-insensitive
+// "0" / "false" / "no" counts as truthy. So
+// \`AGENT_BROWSER_HEADED=yes\`, \`=y\`, \`=on\`, \`=anything-non-falsy\` all
+// trigger the workaround — matching what upstream's CLI parser would
+// see — instead of the original narrower 1|true match that left the
+// bug present for legitimate truthy values.
+//
+// Re-entrancy is defended at two layers. (1) The pre-close path is
+// \`open\`/\`goto\`/\`navigate\` only, and the close subcommand isn't in the
+// allowlist, so the pre-close never recurses through the wrapper into
+// another pre-close. (2) \`_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1\` is
+// set on the env passed to both the pre-close and the final exec; if a
+// future subcommand we don't recognize shells out to \`agent-browser\` as
+// a subprocess while headed env is still set, the child sees the guard
+// and bypasses straight to .real without recursing.
+const LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER = `# Layer 4.5 (cheap): wrap agent-browser to work around upstream issue
+# #1083 (--headed / AGENT_BROWSER_HEADED ignored on existing session).
+# See src/init/dockerfile.ts for the full rationale.
+RUN mv /usr/local/bin/agent-browser /usr/local/bin/agent-browser.real \\
+ && cat > /usr/local/bin/agent-browser <<'TYPECLAW_AGENT_BROWSER_WRAPPER_EOF' \\
+ && chmod +x /usr/local/bin/agent-browser
+#!/bin/sh
+# typeclaw wrapper for agent-browser — see src/init/dockerfile.ts.
+set -e
+real="\${TYPECLAW_AGENT_BROWSER_REAL:-/usr/local/bin/agent-browser.real}"
+# Re-entrancy guard: if the wrapper invoked us, skip straight to the real
+# binary. Prevents infinite recursion if a subcommand shells out to
+# agent-browser while AGENT_BROWSER_HEADED is still set.
+if [ "\${_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED:-}" = "1" ]; then
+  exec "$real" "$@"
+fi
+# Pre-close is only needed when the caller is requesting headed mode.
+# Match upstream's env_var_is_truthy contract (cli/src/flags.rs:183):
+# truthy = any non-empty value except case-insensitive "0", "false", "no".
+# Argv triggers: bare --headed, --headed=true, --headed=1. (A bare
+# --headed followed by a separate "false" argument is upstream-supported
+# to FORCE headless; the wrapper still pre-closes on the --headed match
+# and the real binary launches headless — wasted close, correct end
+# state. The narrower argv match keeps the wrapper from triggering on
+# unrelated --headed-prefixed flags that may exist in future upstream
+# versions.)
+headed=0
+val=\${AGENT_BROWSER_HEADED:-}
+lower=$(printf '%s' "$val" | tr '[:upper:]' '[:lower:]')
+case "$lower" in
+  ''|'0'|'false'|'no') ;;
+  *) headed=1 ;;
+esac
+for arg in "$@"; do
+  case "$arg" in
+    --headed|--headed=true|--headed=1) headed=1; break ;;
+  esac
+done
+if [ "$headed" != "1" ]; then
+  exec "$real" "$@"
+fi
+# Allowlist of commands where pre-close is safe and necessary. Only
+# user-visible "start a new browsing session" verbs go here. Everything
+# else (click, snapshot, chat, connect, batch, tab, record, trace,
+# stream, cookies, ...) may depend on live browser/page state and must
+# not be pre-closed by us.
+first=""
+for arg in "$@"; do
+  case "$arg" in
+    -*) continue ;;
+    *) first="$arg"; break ;;
+  esac
+done
+case "$first" in
+  open|goto|navigate) ;;
+  *) exec "$real" "$@" ;;
+esac
+# Best-effort pre-close. If the daemon is already gone, the real binary
+# prints "No active sessions" and exits 0 — safe to call unconditionally.
+# We discard its output so it never pollutes the caller's stdout/stderr,
+# and we tolerate failures (network blip, stale socket) by falling
+# through to the real command anyway.
+_TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" close >/dev/null 2>&1 || true
+exec env _TYPECLAW_AGENT_BROWSER_HEADED_HANDLED=1 "$real" "$@"
+TYPECLAW_AGENT_BROWSER_WRAPPER_EOF`
+
 // Layer 5: download the pinned Chrome for Testing build into
 // ~/.agent-browser/browsers/. NO cache mount on that path because the
 // runtime needs the binary in the image. System shared libraries are
@@ -721,6 +871,7 @@ function defaultConfig(): DockerfileConfig {
     cjkFonts: true,
     cloudflared: true,
     xvfb: true,
+    claudeCode: false,
     append: [],
   }
 }

package/src/init/index.ts

@@ -37,6 +37,14 @@ const CONFIG_FILE = 'typeclaw.json'
 const CRON_FILE = 'cron.json'
 const PACKAGE_FILE = 'package.json'
 
+// Seeded into `typeclaw.json#roles.member.match[]` whenever a chat adapter
+// (slack-bot, discord-bot, telegram-bot, kakaotalk) is wired. The "*" rule
+// matches every channel session on every platform, so the built-in `member`
+// role (which already carries `channel.respond`) covers any inbound the
+// router sees. Without this, freshly-hatched agents silently drop every
+// chat message — see scaffold() and ensureDefaultChatMemberMatch() below.
+const DEFAULT_CHAT_MEMBER_MATCH_RULE = '*'
+
 const MARKDOWN_FILES = ['AGENTS.md', 'IDENTITY.md', 'SOUL.md', 'USER.md'] as const
 
 // `packages/` is a bun workspace root (see `workspaces` in buildPackageJson).
@@ -543,6 +551,11 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   if (options.withTelegram) channels['telegram-bot'] = {}
   if (options.withKakaotalk) channels.kakaotalk = {}
   if (Object.keys(channels).length > 0) config.channels = channels
+  // See DEFAULT_CHAT_MEMBER_MATCH_RULE for why this is here. GitHub is wired
+  // separately (writeGithubChannelForInit) and seeds per-repo member.match
+  // entries instead of the wildcard, so a github-only init stays scoped to
+  // the repos the operator opted in to.
+  if (Object.keys(channels).length > 0) config.roles = { member: { match: [DEFAULT_CHAT_MEMBER_MATCH_RULE] } }
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
   const cron = {
@@ -965,6 +978,8 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   if (options.channel === 'github') {
     await appendGithubMatchRules(options.cwd, options.repos)
     await maybeInstallGithubWebhooks(options, emit)
+  } else {
+    await ensureDefaultChatMemberMatch(options.cwd)
   }
 
   // Commit the typeclaw.json change so the agent folder isn't silently
@@ -1209,6 +1224,24 @@ async function appendGithubMatchRules(cwd: string, repos: readonly string[]): Pr
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
+// Chat-adapter counterpart of appendGithubMatchRules. See
+// DEFAULT_CHAT_MEMBER_MATCH_RULE for the rationale. Set-union semantics: re-
+// running `typeclaw channel add` for additional chat adapters is a no-op on
+// the match list, and any pre-existing rules the operator hand-authored
+// (e.g. owner-claim's per-author entry on `owner`) are left intact.
+async function ensureDefaultChatMemberMatch(cwd: string): Promise<void> {
+  const path = join(cwd, CONFIG_FILE)
+  const parsed = JSON.parse(await readFile(path, 'utf8')) as Record<string, unknown>
+  const roles = isObjectRecord(parsed.roles) ? { ...parsed.roles } : {}
+  const member = isObjectRecord(roles.member) ? { ...roles.member } : {}
+  const existing = Array.isArray(member.match) ? member.match.filter((v): v is string => typeof v === 'string') : []
+  if (existing.includes(DEFAULT_CHAT_MEMBER_MATCH_RULE)) return
+  member.match = [...existing, DEFAULT_CHAT_MEMBER_MATCH_RULE]
+  roles.member = member
+  parsed.roles = roles
+  await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
+}
+
 // Writes per-adapter field values into `secrets.json#channels.<adapter>`.
 // Refuses to overwrite existing fields: if the user already has e.g.
 // `botToken` recorded (from a prior `channel add` whose follow-up steps

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
 }