typeclaw 0.9.1 → 0.10.0

package/src/init/dockerfile.ts

@@ -281,6 +281,56 @@ set -eu
 #   -nolisten tcp           refuse TCP connections (Unix socket only).
 #                           Defense-in-depth — we are in a netns with
 #                           no inbound exposure anyway.
+# link_persistent_home_files symlinks credential files that tools write
+# to $HOME into a bind-mounted location so they survive container
+# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
+# rewrites the file in place to rotate OAuth tokens, and the official
+# CI/CD guidance is to persist auth.json so refresh-token state
+# compounds across runs. The container's $HOME (/root by default) lives
+# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
+# cycle, so without this symlink the operator would have to re-paste
+# auth.json after every restart.
+#
+# The persist root lives under /agent/.typeclaw/home/ (bind-mounted
+# from the agent folder via the -v <cwd>:/agent flag in start.ts).
+# Namespacing under .typeclaw/ keeps the agent's top-level layout clean and reserves
+# a system-owned subtree we can extend later (e.g. ~/.gemini/,
+# ~/.config/<tool>/) without colliding with user files. The directory
+# is gitignored by buildGitignore() so credentials never enter history.
+#
+# Three invariants this function enforces:
+#
+# 1. Symlink is unconditional and idempotent. We never check whether
+#    auth.json exists before linking — \`ln -sfn\` creates a dangling
+#    symlink on first boot, and the first \`codex login\` write goes
+#    through it to land at the persistent location. -f replaces an
+#    existing symlink; -n stops ln from dereferencing into a directory
+#    if a previous container life happened to write a real ~/.codex/
+#    dir before this code shipped.
+#
+# 2. We symlink the FILE, not the directory. Codex writes other state
+#    to ~/.codex/ over time (history.jsonl, log/, config.toml). Linking
+#    only auth.json keeps the persistence scope tight to credentials;
+#    history/logs stay ephemeral by design. Future credentials get
+#    added file-by-file here, not by widening to a directory link.
+#
+# 3. We mkdir -p the target's parent on every boot. /agent is bind-
+#    mounted, so the host-side path may exist or not depending on
+#    whether the operator ever started the container before this code
+#    shipped. mkdir -p is idempotent and cheap.
+#
+# 4. The root is overridable via TYPECLAW_PERSIST_HOME_ROOT, which only
+#    the shim's executable tests set. Production never sets it, so the
+#    in-container path is always /agent/.typeclaw/home/. The override
+#    lets the shim's behavioral tests verify symlink semantics against
+#    a real tmpdir on the host without touching /agent (which doesn't
+#    exist on developer machines and CI runners).
+link_persistent_home_files() {
+  persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
+  mkdir -p "$persist_root/.codex" "$HOME/.codex"
+  ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+}
+
 start_xvfb() {
   if ! command -v Xvfb >/dev/null 2>&1; then
     return 0
@@ -314,6 +364,7 @@ start_xvfb() {
 }
 
 if [ "\${TYPECLAW_NETWORK_BLOCK_INTERNAL:-0}" != "1" ]; then
+  link_persistent_home_files
   start_xvfb
   exec bun run typeclaw "$@"
 fi
@@ -359,6 +410,7 @@ ip6tables -A OUTPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
 ip6tables -A OUTPUT -o lo -j ACCEPT
 ${ipv6Rules.join('\n')}
 
+link_persistent_home_files
 start_xvfb
 exec setpriv --bounding-set -net_admin --inh-caps -net_admin --ambient-caps -net_admin -- bun run typeclaw "$@"
 `
@@ -755,6 +807,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 +1015,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 +1074,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 +1100,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 +1148,7 @@ ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
 ${LAYER_5_CHROME_FOR_TESTING}
 
-${cloudflaredBlock}${claudeCodeBlock}${renderEntrypointShimLayer()}
+${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
 `
 }
@@ -1223,6 +1417,7 @@ function defaultConfig(): DockerfileConfig {
     cloudflared: true,
     xvfb: true,
     claudeCode: false,
+    codexCli: false,
     append: [],
   }
 }

package/src/init/gitignore.ts

@@ -17,10 +17,18 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 # as a safety net so an agent folder cloned from a pre-rename machine never
 # stages credentials by accident, even if its agent boot hasn't yet run the
 # auth.json -> secrets.json migration.
+#
+# .typeclaw/home/ is the persistent-$HOME overlay populated by the
+# entrypoint shim's \`link_persistent_home_files\` (see
+# src/init/dockerfile.ts). It mirrors selected files from the container's
+# $HOME (e.g. ~/.codex/auth.json) into the bind-mounted agent folder so
+# tool credentials survive container restarts. Always credentials; never
+# commit.
 .env
 .env.local
 secrets.json
 auth.json
+.typeclaw/home/
 node_modules/
 packages/*/node_modules/
 workspace/

package/src/inspect/index.ts

@@ -16,6 +16,8 @@ export { replayJsonl } from './replay'
 export { streamLive } from './live'
 export { parseDuration, parseFilter } from './types'
 export type { InspectCategory, InspectEvent, InspectFilter } from './types'
+export { runInspectLoop } from './loop'
+export type { RunInspectLoopOptions } from './loop'
 
 export type RunInspectOptions = {
   agentDir: string
@@ -29,6 +31,10 @@ export type RunInspectOptions = {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
+  // Aborting escSignal (and only escSignal) returns escToPicker=true so a
+  // caller-side loop can re-open the picker; signal still means process exit.
+  escSignal?: AbortSignal
+  liveHint?: string
 }
 
 export type SelectSession = (sessions: SessionSummary[]) => Promise<SessionSummary | null>
@@ -40,7 +46,9 @@ export type LiveSourceFactory = (opts: {
   onSubscribed?: (sessionLive: boolean) => void
 }) => AsyncIterable<InspectEvent>
 
-export type RunInspectResult = { ok: true; exitCode: 0 } | { ok: false; exitCode: number; reason: string }
+export type RunInspectResult =
+  | { ok: true; exitCode: 0; escToPicker?: boolean }
+  | { ok: false; exitCode: number; reason: string }
 
 export async function runInspect(opts: RunInspectOptions): Promise<RunInspectResult> {
   const filterResult = parseFilter(opts.filter)
@@ -59,7 +67,7 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
   const summary = await chooseSession(opts, sessionsDir, sinceMs)
   if (!summary.ok) return summary
 
-  await streamSession({
+  const streamResult = await streamSession({
     summary: summary.summary,
     filter,
     sinceMs,
@@ -69,7 +77,10 @@ export async function runInspect(opts: RunInspectOptions): Promise<RunInspectRes
     stderr: opts.stderr,
     ...(opts.liveSource !== undefined ? { liveSource: opts.liveSource } : {}),
     ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    ...(opts.escSignal !== undefined ? { escSignal: opts.escSignal } : {}),
+    ...(opts.liveHint !== undefined ? { liveHint: opts.liveHint } : {}),
   })
+  if (streamResult.escToPicker) return { ok: true, exitCode: 0, escToPicker: true }
   return { ok: true, exitCode: 0 }
 }
 
@@ -132,7 +143,9 @@ async function streamSession(opts: {
   stderr: (line: string) => void
   liveSource?: LiveSourceFactory
   signal?: AbortSignal
-}): Promise<void> {
+  escSignal?: AbortSignal
+  liveHint?: string
+}): Promise<{ escToPicker: boolean }> {
   if (!opts.json) writeHeader(opts.summary, opts.color, opts.stdout)
   const emit = (event: InspectEvent): void => {
     if (opts.sinceMs !== undefined && event.ts > 0 && event.ts < opts.sinceMs) return
@@ -144,20 +157,26 @@ async function streamSession(opts: {
     }
   }
 
+  const escAborted = (): boolean => opts.escSignal?.aborted === true
+
   for await (const event of replayJsonl(opts.summary.sessionFile, { onWarn: opts.stderr })) {
+    if (escAborted()) return { escToPicker: true }
     emit(event)
   }
 
   if (opts.liveSource === undefined) {
     if (!opts.json) opts.stdout('─── end of transcript ───')
-    return
+    return { escToPicker: escAborted() }
   }
 
+  if (escAborted()) return { escToPicker: true }
+
+  const combinedSignal = combineSignals(opts.signal, opts.escSignal)
   let sessionLive = false
   const liveIter = opts.liveSource({
     sessionId: opts.summary.sessionId,
     ...(opts.sinceMs !== undefined ? { sinceMs: opts.sinceMs } : {}),
-    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+    ...(combinedSignal !== undefined ? { signal: combinedSignal } : {}),
     onSubscribed: (live) => {
       sessionLive = live
     },
@@ -170,6 +189,9 @@ async function streamSession(opts: {
         opts.stdout(
           divider(opts.color, sessionLive ? '─── live ───' : '─── live (session not in registry; broadcasts only) ───'),
         )
+        if (opts.liveHint !== undefined && opts.liveHint !== '') {
+          opts.stdout(divider(opts.color, opts.liveHint))
+        }
         liveAnnounced = true
       }
       emit(event)
@@ -178,6 +200,21 @@ async function streamSession(opts: {
     opts.stderr(`live tail ended: ${err instanceof Error ? err.message : String(err)}`)
   }
   if (!opts.json) opts.stdout('─── end of transcript ───')
+  return { escToPicker: escAborted() && opts.signal?.aborted !== true }
+}
+
+function combineSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined {
+  if (a === undefined) return b
+  if (b === undefined) return a
+  if (a.aborted) return a
+  if (b.aborted) return b
+  const ctrl = new AbortController()
+  const onAbort = (): void => {
+    ctrl.abort()
+  }
+  a.addEventListener('abort', onAbort, { once: true })
+  b.addEventListener('abort', onAbort, { once: true })
+  return ctrl.signal
 }
 
 function divider(color: boolean, text: string): string {

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/loop.ts

@@ -0,0 +1,20 @@
+import { runInspect, type RunInspectOptions, type RunInspectResult } from './index'
+
+export type RunInspectLoopOptions = Omit<RunInspectOptions, 'escSignal'> & {
+  newEscSignal: () => AbortSignal
+}
+
+export async function runInspectLoop(opts: RunInspectLoopOptions): Promise<RunInspectResult> {
+  let sessionArg = opts.sessionIdOrPrefix
+  while (true) {
+    const escSignal = opts.newEscSignal()
+    const callOpts: RunInspectOptions = { ...opts, escSignal }
+    if (sessionArg !== undefined) callOpts.sessionIdOrPrefix = sessionArg
+    else delete (callOpts as { sessionIdOrPrefix?: string }).sessionIdOrPrefix
+
+    const result = await runInspect(callOpts)
+    if (!result.ok) return result
+    if (result.escToPicker !== true) return result
+    sessionArg = undefined
+  }
+}

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

@@ -113,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 = {
@@ -218,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>