typeclaw 0.9.0 → 0.9.2

package/src/init/dockerfile.ts

@@ -755,6 +755,136 @@ RUN chmod +x ${TYPECLAW_CC_SESSION_START_HOOK_PATH} ${TYPECLAW_CC_STOP_HOOK_PATH
  && printf '%s\\n' '${CLAUDE_CODE_ONBOARDING_SEED}' > "$HOME/.claude.json"`
 }
 
+// Codex CLI's official distribution channel is the npm package
+// \`@openai/codex\` (https://www.npmjs.com/package/@openai/codex). Unlike
+// Claude Code's \`curl | bash\` install, Codex installs cleanly via the same
+// bun-global path agent-browser uses, so we layer it under the existing
+// \`bun install -g\` invariant: cache-mount keyed install, no \$HOME/.local/bin
+// symlink dance, no installer scratch.
+//
+// Hook architecture: Codex CLI ships a hook system with the SAME event names
+// as Claude Code (SessionStart, Stop, PreToolUse, PostToolUse, etc.) and the
+// SAME JSON shape (\`{ session_id, transcript_path, cwd, hook_event_name }\` on
+// stdin). The two CLIs are NOT interoperable — Codex's config file is
+// \`~/.codex/hooks.json\` (or inline \`[hooks]\` in \`config.toml\`), and the trust
+// model differs (Codex prompts for hook trust on first run, gated by
+// \`--dangerously-bypass-hook-trust\`). But the hook script body, the
+// per-session filenames (\`.done-<sid>\`, \`sentinel-<sid>.json\`), the
+// \`.session-id\` fast path, and the \`malformed\` fallback are byte-for-byte
+// reusable. We deliberately use distinct paths (\`typeclaw-cx-*\` instead of
+// \`typeclaw-cc-*\`) and a distinct settings file (\`~/.codex/hooks.json\` vs
+// \`~/.claude/settings.json\`) so an agent with BOTH toggles on doesn't have
+// the two CLIs racing on the same sentinel files. The skill side
+// (\`typeclaw-codex-cli\`) documents which UUID-bearing artifacts belong to
+// which CLI.
+//
+// Onboarding: Codex has NO theme picker, NO telemetry consent dialog, NO
+// terms-of-service prompt — verified against
+// codex-rs/tui/src/onboarding/onboarding_screen.rs in the upstream repo.
+// The TUI's onboarding state machine has exactly three steps: Welcome,
+// Auth, TrustDirectory. We CAN'T pre-seed past Welcome (it's an animation,
+// not a prompt), and we DELIBERATELY don't pre-seed past Auth (the user
+// must paste their OPENAI_API_KEY or run \`codex login\` themselves) or past
+// TrustDirectory (trusting an arbitrary worktree silently widens the trust
+// surface in ways the operator hasn't consented to — exact same reasoning
+// as Claude Code's "don't preseed hasTrustDialogAccepted"). The
+// \`typeclaw-codex-cli\` skill handles all three at runtime via dialog
+// polling, the same shape Claude Code's skill uses for its post-seed
+// modals.
+//
+// Smoke test: \`codex --version\` is supported per codex-rs/cli/src/main.rs
+// (clap \`version\` attribute), so we use it as the build-time install check.
+const TYPECLAW_CX_STOP_HOOK_PATH = '/usr/local/bin/typeclaw-cx-stop-hook'
+const TYPECLAW_CX_SESSION_START_HOOK_PATH = '/usr/local/bin/typeclaw-cx-session-start-hook'
+
+const TYPECLAW_CX_SESSION_START_HOOK_SCRIPT = `#!/bin/sh
+# typeclaw SessionStart-hook for Codex CLI. Stdin carries the SessionStart
+# event JSON. Writes \$PWD/.session-id with the session UUID as a fast-path
+# optimization (the operator falls back to discovering session_id from the
+# first Stop sentinel if .session-id never appears). Rationale lives in
+# src/init/dockerfile.ts.
+set -eu
+tmp_out="\${PWD}/.session-id.\$\$.tmp"
+trap 'rm -f "\$tmp_out"' EXIT
+sid=\$(bun -e 'try { const j = await new Response(Bun.stdin.stream()).json(); process.stdout.write(String(j.session_id ?? "")) } catch { process.stdout.write("") }')
+case "\$sid" in
+  [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]) ;;
+  *) sid=malformed ;;
+esac
+printf '%s\\n' "\$sid" > "\$tmp_out"
+mv "\$tmp_out" "\${PWD}/.session-id"
+trap - EXIT
+`
+
+const TYPECLAW_CX_STOP_HOOK_SCRIPT = `#!/bin/sh
+# typeclaw Stop-hook for Codex CLI. Stdin carries the Stop event JSON.
+# Writes per-session sentinel/.done files into \$PWD. Rationale (the
+# security model, \$PWD semantics, and why bun-not-sed for JSON
+# extraction) lives in src/init/dockerfile.ts.
+set -eu
+tmp_in="\${PWD}/.cx-stop-hook-in.\$\$"
+trap 'rm -f "\$tmp_in"' EXIT
+cat > "\$tmp_in"
+sid=\$(bun -e 'try { const j = await Bun.file(process.argv[1]).json(); process.stdout.write(String(j.session_id ?? "")) } catch { process.stdout.write("") }' "\$tmp_in")
+case "\$sid" in
+  [0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f]-[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]) ;;
+  *) sid=malformed ;;
+esac
+mv "\$tmp_in" "\${PWD}/sentinel-\${sid}.json"
+trap - EXIT
+touch "\${PWD}/.done-\${sid}"
+`
+
+// Codex CLI's hook config file lives at ~/.codex/hooks.json. The JSON shape
+// mirrors Claude Code's settings.json hooks block exactly — same nesting,
+// same matcher syntax, same exec-form via \`args: []\`. Built via
+// JSON.stringify so a shape edit fails the JSON.parse regression test, not
+// the docker build (or the first failed delegation).
+//
+// SessionStart matcher \`startup|resume\`: Codex documents \`startup\` and
+// \`resume\` as the two SessionStart sources (vs Claude Code's
+// \`startup|resume|clear|compact\` — Codex has no \`/clear\` command and no
+// auto-compaction in the same shape). Claude's broader matcher would not
+// be wrong but would match against events Codex never fires.
+const TYPECLAW_CX_GLOBAL_HOOKS = JSON.stringify({
+  hooks: {
+    SessionStart: [
+      {
+        matcher: 'startup|resume',
+        hooks: [{ type: 'command', command: TYPECLAW_CX_SESSION_START_HOOK_PATH, args: [] }],
+      },
+    ],
+    Stop: [
+      {
+        matcher: '*',
+        hooks: [{ type: 'command', command: TYPECLAW_CX_STOP_HOOK_PATH, args: [] }],
+      },
+    ],
+  },
+})
+
+function renderCodexCliInstallLayer(enabled: boolean): string {
+  if (!enabled) return ''
+  return `# Layer 5.7 (toggle): install OpenAI's Codex CLI. Opt-in via
+# typeclaw.json#docker.file.codexCli. The skill \`typeclaw-codex-cli\`
+# documents the auth + usage flow. Codex ships as the npm package
+# \`@openai/codex\`, so we install via \`bun install -g\` reusing the same
+# cache mount agent-browser uses. Hook scripts and ~/.codex/hooks.json
+# are pre-written at build time so the operator subagent never has to
+# construct that JSON itself — same load-bearing reason as the Claude
+# Code layer above.
+RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
+    bun install -g @openai/codex \\
+ && codex --version > /dev/null \\
+ && cat > ${TYPECLAW_CX_SESSION_START_HOOK_PATH} <<'TYPECLAW_CX_SESSION_START_HOOK_EOF'
+${TYPECLAW_CX_SESSION_START_HOOK_SCRIPT}TYPECLAW_CX_SESSION_START_HOOK_EOF
+RUN cat > ${TYPECLAW_CX_STOP_HOOK_PATH} <<'TYPECLAW_CX_STOP_HOOK_EOF'
+${TYPECLAW_CX_STOP_HOOK_SCRIPT}TYPECLAW_CX_STOP_HOOK_EOF
+RUN chmod +x ${TYPECLAW_CX_SESSION_START_HOOK_PATH} ${TYPECLAW_CX_STOP_HOOK_PATH} \\
+ && mkdir -p "$HOME/.codex" \\
+ && printf '%s\\n' '${TYPECLAW_CX_GLOBAL_HOOKS}' > "$HOME/.codex/hooks.json"`
+}
+
 // 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:
@@ -833,10 +963,18 @@ export function buildDockerfile(
   const baseImageVersion = options.baseImageVersion ?? null
 
   const claudeCodeLayer = renderClaudeCodeInstallLayer(config.claudeCode)
+  const codexCliLayer = renderCodexCliInstallLayer(config.codexCli)
   const fromAndHeavyLayers =
     baseImageVersion !== null
-      ? renderVersionedHead(baseImageVersion, ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer)
+      ? renderVersionedHead(
+          baseImageVersion,
+          ghKeyringLayer,
+          toggleAptArgs,
+          cloudflaredLayer,
+          claudeCodeLayer,
+          codexCliLayer,
+        )
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer, codexCliLayer)
 
   return `${BUILDKIT_HEADER}
 # AUTOGENERATED by typeclaw — do not edit.
@@ -884,17 +1022,19 @@ function renderVersionedHead(
   toggleAptArgs: string[],
   cloudflaredLayer: string,
   claudeCodeLayer: string,
+  codexCliLayer: string,
 ): string {
   const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
   const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
+  const codexCliBlock = codexCliLayer === '' ? '' : `${codexCliLayer}\n\n`
   return `FROM ${GHCR_BASE_IMAGE_REPO}:${baseImageVersion}
 
 WORKDIR /agent
 
 ARG TARGETARCH
 
-${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
+${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -908,10 +1048,12 @@ function renderInlineHead(
   toggleAptArgs: string[],
   cloudflaredLayer: string,
   claudeCodeLayer: string,
+  codexCliLayer: string,
 ): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
   const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
+  const codexCliBlock = codexCliLayer === '' ? '' : `${codexCliLayer}\n\n`
   return `${FROM_AND_WORKDIR}
 
 # Layers are ordered most-stable first to maximize Docker layer cache hits on
@@ -954,7 +1096,7 @@ ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
+${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -1223,6 +1365,7 @@ function defaultConfig(): DockerfileConfig {
     cloudflared: true,
     xvfb: true,
     claudeCode: false,
+    codexCli: false,
     append: [],
   }
 }

package/src/inspect/live.ts

@@ -21,6 +21,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   let pendingError: string | null = null
 
   const accumulators = new Map<string, string>()
+  const thinkingAccumulators = new Map<string, string>()
 
   const wake = (): void => {
     if (resolveNext !== null) {
@@ -55,7 +56,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
       return
     }
     if (msg.type !== 'frame') return
-    const event = frameToEvent(msg.payload, msg.ts, accumulators)
+    const event = frameToEvent(msg.payload, msg.ts, accumulators, thinkingAccumulators)
     if (event !== null) {
       buffer.push(event)
       wake()
@@ -134,6 +135,7 @@ function frameToEvent(
   payload: InspectFramePayload,
   ts: number,
   accumulators: Map<string, string>,
+  thinkingAccumulators: Map<string, string>,
 ): InspectEvent | null {
   switch (payload.kind) {
     case 'text_delta': {
@@ -141,6 +143,18 @@ function frameToEvent(
       accumulators.set(payload.sessionId, existing + payload.delta)
       return null
     }
+    case 'thinking_delta': {
+      const existing = thinkingAccumulators.get(payload.sessionId) ?? ''
+      thinkingAccumulators.set(payload.sessionId, existing + payload.delta)
+      return null
+    }
+    case 'thinking_end': {
+      const accumulated = thinkingAccumulators.get(payload.sessionId) ?? ''
+      thinkingAccumulators.delete(payload.sessionId)
+      const text = accumulated !== '' ? accumulated : payload.text
+      if (text === '' && payload.redacted !== true) return null
+      return { cat: 'thinking', ts, text, ...(payload.redacted === true ? { redacted: true } : {}) }
+    }
     case 'tool_start':
       return {
         cat: 'tool',
@@ -172,6 +186,23 @@ function frameToEvent(
       }
     case 'cron-fire':
       return { cat: 'cron-fire', ts, jobId: payload.jobId, payload: payload.payload }
+    case 'channel_inbound':
+      return {
+        cat: 'inbound',
+        ts: payload.ts > 0 ? payload.ts : ts,
+        adapter: payload.adapter,
+        workspace: payload.workspace,
+        chat: payload.chat,
+        thread: payload.thread,
+        authorId: payload.authorId,
+        authorName: payload.authorName,
+        authorIsBot: payload.authorIsBot,
+        isDm: payload.isDm,
+        isBotMention: payload.isBotMention,
+        text: payload.text,
+        externalMessageId: payload.externalMessageId,
+        decision: payload.decision,
+      }
     default:
       return null
   }

package/src/inspect/render.ts

@@ -34,6 +34,8 @@ function renderTag(event: InspectEvent, opts: RenderOptions): string {
       return tint(opts, 'cyan', padEnd('user', 9))
     case 'assistant':
       return tint(opts, 'green', padEnd('assist', 9))
+    case 'thinking':
+      return tint(opts, 'gray', padEnd('think', 9))
     case 'tool':
       return tint(opts, 'yellow', padEnd(event.phase === 'start' ? 'tool ▸' : 'tool ◂', 9))
     case 'error':
@@ -44,6 +46,8 @@ function renderTag(event: InspectEvent, opts: RenderOptions): string {
       return tint(opts, 'magenta', padEnd('bcast', 9))
     case 'cron-fire':
       return tint(opts, 'magenta', padEnd('cron', 9))
+    case 'inbound':
+      return tint(opts, 'cyan', padEnd('inbound', 9))
   }
 }
 
@@ -55,6 +59,11 @@ function renderBody(event: InspectEvent, opts: RenderOptions): string {
       return truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
     case 'assistant':
       return truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+    case 'thinking': {
+      const prefix = event.redacted === true ? `${tint(opts, 'dim', '[redacted]')} ` : ''
+      const body = event.text === '' ? '' : truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+      return `${prefix}${tint(opts, 'dim', body)}`
+    }
     case 'tool': {
       if (event.phase === 'start') {
         return `${event.name}(${renderArgs(event.args)})`
@@ -72,6 +81,29 @@ function renderBody(event: InspectEvent, opts: RenderOptions): string {
       return renderBroadcastBody(event.payload, opts.maxTextLength ?? DEFAULT_MAX_TEXT)
     case 'cron-fire':
       return `${event.jobId} fired`
+    case 'inbound':
+      return renderInboundBody(event, opts)
+  }
+}
+
+function renderInboundBody(event: Extract<InspectEvent, { cat: 'inbound' }>, opts: RenderOptions): string {
+  const coord = `${event.adapter}:${event.workspace}/${event.chat}${event.thread === null ? '' : `#${event.thread}`}`
+  const who = event.authorName !== '' ? event.authorName : event.authorId
+  const decisionTag = tint(opts, decisionColor(event.decision), `[${event.decision}]`)
+  const text = truncate(singleLine(event.text), opts.maxTextLength ?? DEFAULT_MAX_TEXT)
+  return `${decisionTag} ${tint(opts, 'dim', coord)} ${who}: ${text}`
+}
+
+function decisionColor(decision: Extract<InspectEvent, { cat: 'inbound' }>['decision']): ColorName {
+  switch (decision) {
+    case 'engage':
+      return 'green'
+    case 'observe':
+      return 'dim'
+    case 'denied':
+      return 'red'
+    case 'claim':
+      return 'magenta'
   }
 }
 

package/src/inspect/replay.ts

@@ -76,6 +76,36 @@ function* eventsFromEntry(
     yield* assistantEvents(message as AssistantMessage, ts, pending)
     return
   }
+  if (role === 'toolResult') {
+    const ev = toolResultMessageEvent(message, ts, pending)
+    if (ev !== null) yield ev
+    return
+  }
+}
+
+function toolResultMessageEvent(
+  message: { role: string; [k: string]: unknown },
+  ts: number,
+  pending: Map<string, { name: string; startTs: number }>,
+): InspectEvent | null {
+  const toolCallId = typeof message.toolCallId === 'string' ? message.toolCallId : null
+  if (toolCallId === null) return null
+  const entry = pending.get(toolCallId)
+  pending.delete(toolCallId)
+  const name = entry?.name ?? (typeof message.toolName === 'string' ? message.toolName : 'unknown')
+  const durationMs = entry !== undefined ? Math.max(0, ts - entry.startTs) : 0
+  const isError = message.isError === true
+  const text = readTextContent(message.content)
+  return {
+    cat: 'tool',
+    ts,
+    phase: 'end',
+    toolCallId,
+    name,
+    ...(text !== null && text !== '' ? { result: text } : {}),
+    isError,
+    durationMs,
+  }
 }
 
 function* assistantEvents(
@@ -83,6 +113,7 @@ function* assistantEvents(
   ts: number,
   pending: Map<string, { name: string; startTs: number }>,
 ): Iterable<InspectEvent> {
+  yield* readThinkingEvents(message.content, ts)
   const text = readTextContent(message.content)
   if (text !== null && text !== '') {
     const ev: InspectEvent = {
@@ -188,6 +219,19 @@ function readUsage(value: unknown): {
   }
 }
 
+function* readThinkingEvents(content: unknown, ts: number): Iterable<InspectEvent> {
+  if (!Array.isArray(content)) return
+  for (const block of content) {
+    if (typeof block !== 'object' || block === null) continue
+    const b = block as Record<string, unknown>
+    if (b.type !== 'thinking') continue
+    const text = typeof b.thinking === 'string' ? b.thinking : ''
+    const redacted = b.redacted === true
+    if (text === '' && !redacted) continue
+    yield { cat: 'thinking', ts, text, ...(redacted ? { redacted: true } : {}) }
+  }
+}
+
 function readTextContent(content: unknown): string | null {
   if (typeof content === 'string') return content
   if (!Array.isArray(content)) return null

package/src/inspect/types.ts

@@ -4,18 +4,28 @@ export const INSPECT_CATEGORIES = [
   'meta',
   'user',
   'assistant',
+  'thinking',
   'tool',
   'error',
   'done',
   'broadcast',
   'cron-fire',
+  'inbound',
 ] as const
 export type InspectCategory = (typeof INSPECT_CATEGORIES)[number]
 
+export type InboundDecision = 'engage' | 'observe' | 'denied' | 'claim'
+
 export type InspectEvent =
   | { cat: 'meta'; ts: number; origin: MinimalSessionOrigin }
   | { cat: 'user'; ts: number; text: string }
   | { cat: 'assistant'; ts: number; text: string; provider?: string; model?: string }
+  // Reasoning trace from the model (Claude extended thinking, OpenAI reasoning
+  // summary, Gemini thoughts, etc.). Surfaced for debugging — why the model
+  // picked the next tool / wrote the next thing. `redacted` is true when the
+  // upstream provider hid the content behind a safety filter and only the
+  // opaque continuation payload survives; in that case `text` is empty.
+  | { cat: 'thinking'; ts: number; text: string; redacted?: boolean }
   | {
       cat: 'tool'
       ts: number
@@ -41,6 +51,22 @@ export type InspectEvent =
     }
   | { cat: 'broadcast'; ts: number; payload: unknown; meta?: Record<string, string> }
   | { cat: 'cron-fire'; ts: number; jobId: string; payload: unknown }
+  | {
+      cat: 'inbound'
+      ts: number
+      adapter: string
+      workspace: string
+      chat: string
+      thread: string | null
+      authorId: string
+      authorName: string
+      authorIsBot: boolean
+      isDm: boolean
+      isBotMention: boolean
+      text: string
+      externalMessageId: string
+      decision: InboundDecision
+    }
 
 export type InspectFilter = {
   include?: ReadonlySet<InspectCategory>

package/src/run/index.ts

@@ -5,9 +5,11 @@ import { LiveSessionRegistry } from '@/agent/live-sessions'
 import { LiveSubagentRegistry } from '@/agent/live-subagents'
 import type { SessionOrigin } from '@/agent/session-origin'
 import {
+  awaitWithSubagentTimeout,
   createSubagentConsumer,
   defaultCreateSessionForSubagent,
   invokeSubagent,
+  isSubagentTimeoutError,
   type Subagent as InternalSubagent,
   type SubagentConsumer,
   type SubagentRegistry,
@@ -212,6 +214,7 @@ export async function startAgent({
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
+    stream,
   })
 
   const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (
@@ -469,17 +472,31 @@ export async function startAgent({
         options?.spawnedByOrigin !== undefined
           ? pluginsLoaded.permissions.resolveRole(options.spawnedByOrigin)
           : undefined
-      await invokeSubagent(name, {
-        registry: pluginRuntime.get().subagents,
-        createSessionForSubagent,
-        agentDir: cwd,
-        userPrompt: '',
-        payload,
-        onProviderError: (message) => console.error(`[subagent] ${name}: LLM call failed: ${message}`),
-        ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
-        ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
-        ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
-      })
+      const registry = pluginRuntime.get().subagents
+      try {
+        await awaitWithSubagentTimeout(
+          invokeSubagent(name, {
+            registry,
+            createSessionForSubagent,
+            agentDir: cwd,
+            userPrompt: '',
+            payload,
+            onProviderError: (message) => console.error(`[subagent] ${name}: LLM call failed: ${message}`),
+            ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
+            ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
+            ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
+          }),
+          name,
+          coalesceKey,
+          registry[name]?.timeoutMs,
+        )
+      } catch (err) {
+        if (isSubagentTimeoutError(err)) {
+          console.warn(`[subagent] ${coalesceKey} timed out after ${err.timeoutMs}ms; releasing coalesce key`)
+          return
+        }
+        throw err
+      }
     } finally {
       directSpawnInFlight.delete(coalesceKey)
     }

package/src/server/index.ts

@@ -1062,15 +1062,7 @@ function handleInspectMessage(
 
   if (stream !== undefined && typeof msg.sinceMs === 'number') {
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'broadcast' } })) {
-      sendInspect(ws, {
-        type: 'frame',
-        ts: event.ts,
-        payload: {
-          kind: 'broadcast',
-          payload: event.payload,
-          ...(event.meta !== undefined ? { meta: event.meta } : {}),
-        },
-      })
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
     }
     for (const event of stream.scan({ sinceTs: msg.sinceMs, target: { kind: 'cron' } })) {
       sendInspect(ws, {
@@ -1092,15 +1084,7 @@ function handleInspectMessage(
 
   if (stream !== undefined) {
     ws.data.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (event) => {
-      sendInspect(ws, {
-        type: 'frame',
-        ts: event.ts,
-        payload: {
-          kind: 'broadcast',
-          payload: event.payload,
-          ...(event.meta !== undefined ? { meta: event.meta } : {}),
-        },
-      })
+      sendInspect(ws, { type: 'frame', ts: event.ts, payload: broadcastEventToFrame(event) })
     })
     ws.data.unsubCron = stream.subscribe({ target: { kind: 'cron' } }, (event) => {
       sendInspect(ws, {
@@ -1118,6 +1102,52 @@ function extractJobId(target: StreamMessage['target']): string {
   return target.kind === 'cron' ? target.jobId : ''
 }
 
+function broadcastEventToFrame(event: StreamMessage): InspectFramePayload {
+  const inbound = readChannelInboundBroadcast(event.payload)
+  if (inbound !== null) return inbound
+  return {
+    kind: 'broadcast',
+    payload: event.payload,
+    ...(event.meta !== undefined ? { meta: event.meta } : {}),
+  }
+}
+
+function readChannelInboundBroadcast(payload: unknown): InspectFramePayload | null {
+  if (typeof payload !== 'object' || payload === null) return null
+  const p = payload as Record<string, unknown>
+  if (p.kind !== 'channel-inbound') return null
+  if (typeof p.adapter !== 'string') return null
+  if (typeof p.workspace !== 'string') return null
+  if (typeof p.chat !== 'string') return null
+  if (!(p.thread === null || typeof p.thread === 'string')) return null
+  if (typeof p.authorId !== 'string') return null
+  if (typeof p.authorName !== 'string') return null
+  if (typeof p.authorIsBot !== 'boolean') return null
+  if (typeof p.isDm !== 'boolean') return null
+  if (typeof p.isBotMention !== 'boolean') return null
+  if (typeof p.text !== 'string') return null
+  if (typeof p.externalMessageId !== 'string') return null
+  if (typeof p.ts !== 'number') return null
+  const decision = p.decision
+  if (decision !== 'engage' && decision !== 'observe' && decision !== 'denied' && decision !== 'claim') return null
+  return {
+    kind: 'channel_inbound',
+    adapter: p.adapter,
+    workspace: p.workspace,
+    chat: p.chat,
+    thread: p.thread,
+    authorId: p.authorId,
+    authorName: p.authorName,
+    authorIsBot: p.authorIsBot,
+    isDm: p.isDm,
+    isBotMention: p.isBotMention,
+    text: p.text,
+    externalMessageId: p.externalMessageId,
+    ts: p.ts,
+    decision,
+  }
+}
+
 function forwardAgentEventToInspect(
   ws: InspectWs,
   event: unknown,
@@ -1128,10 +1158,20 @@ function forwardAgentEventToInspect(
   const e = event as { type?: unknown }
   const now = Date.now()
   if (e.type === 'message_update') {
-    const ev = event as { assistantMessageEvent?: { type?: unknown; delta?: unknown } }
+    const ev = event as { assistantMessageEvent?: { type?: unknown; delta?: unknown; content?: unknown } }
     const ame = ev.assistantMessageEvent
     if (ame?.type === 'text_delta' && typeof ame.delta === 'string') {
       sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'text_delta', sessionId, delta: ame.delta } })
+      return
+    }
+    if (ame?.type === 'thinking_delta' && typeof ame.delta === 'string') {
+      sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'thinking_delta', sessionId, delta: ame.delta } })
+      return
+    }
+    if (ame?.type === 'thinking_end') {
+      const text = typeof ame.content === 'string' ? ame.content : ''
+      sendInspect(ws, { type: 'frame', ts: now, payload: { kind: 'thinking_end', sessionId, text } })
+      return
     }
     return
   }

package/src/shared/protocol.ts

@@ -57,6 +57,12 @@ export type InspectClientMessage = {
 
 export type InspectFramePayload =
   | { kind: 'text_delta'; sessionId: string; delta: string }
+  // Reasoning trace from the model, streamed as deltas like text. `thinking_end`
+  // closes a thinking block; `text` is the joined deltas (empty when redacted).
+  // `redacted: true` means the upstream provider hid the content behind a
+  // safety filter and only the opaque continuation payload survives.
+  | { kind: 'thinking_delta'; sessionId: string; delta: string }
+  | { kind: 'thinking_end'; sessionId: string; text: string; redacted?: boolean }
   | { kind: 'tool_start'; sessionId: string; toolCallId: string; name: string; args: unknown }
   | {
       kind: 'tool_end'
@@ -87,6 +93,30 @@ export type InspectFramePayload =
     }
   | { kind: 'broadcast'; payload: unknown; meta?: Record<string, string> }
   | { kind: 'cron-fire'; jobId: string; payload: unknown }
+  // Channel inbound message observed by the router. Surfaced regardless
+  // of the engagement decision so inspect can show what the agent saw,
+  // not just what it chose to act on. `decision` mirrors the router's
+  // EngagementDecision plus 'denied' (channel.respond gate) and 'claim'
+  // (role-claim intercept) for completeness. `text` is the raw inbound
+  // text — no batching, no compose-prompt wrapping.
+  | {
+      kind: 'channel_inbound'
+      adapter: string
+      workspace: string
+      chat: string
+      thread: string | null
+      authorId: string
+      authorName: string
+      authorIsBot: boolean
+      isDm: boolean
+      isBotMention: boolean
+      text: string
+      externalMessageId: string
+      // 0 = platform timestamp unknown; the renderer uses the frame's
+      // wall-clock ts instead.
+      ts: number
+      decision: 'engage' | 'observe' | 'denied' | 'claim'
+    }
 
 export type InspectServerMessage =
   | { type: 'subscribed'; sessionId: string; sessionLive: boolean }