typeclaw 0.24.0 → 0.26.0

package/README.md

@@ -34,7 +34,7 @@ If you're like me, TypeClaw is the right choice. If not, that's fine too.
 - 💬 **Multi-channel** — Slack, Discord, Telegram, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
-- 🔎 **Web research** — bundled `scout` subagent plus first-class `websearch` and `webfetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
+- 🔎 **Web research** — bundled `scout` subagent plus first-class `web_search` and `web_fetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
 - 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, tainted git remotes, and silent privilege escalation (role/cron promotion) before they fire
 - 📊 **Usage, inspect, doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw inspect` replays a session transcript and tails live activity; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/index.ts

@@ -35,6 +35,7 @@ import { getAuthFor } from './auth'
 import { createCompactionSettingsManager } from './compaction'
 import { renderGitNudge } from './git-nudge'
 import type { LiveSubagentRegistry } from './live-subagents'
+import { sanitizeMessagesForLlmReplay } from './llm-replay-sanitizer'
 import { applyModelRuntimeOverrides } from './model-overrides'
 import { createChannelLookAtTool, lookAtTool } from './multimodal'
 import {
@@ -72,8 +73,8 @@ import { createStreamSnapshotTool } from './tools/stream-snapshot'
 import { createSubagentCancelTool } from './tools/subagent-cancel'
 import { createSubagentOutputTool } from './tools/subagent-output'
 import { createTodoTools } from './tools/todo'
-import { webfetchTool } from './tools/webfetch'
-import { websearchTool } from './tools/websearch'
+import { webFetchTool } from './tools/webfetch'
+import { webSearchTool } from './tools/websearch'
 
 export type { SessionOrigin } from './session-origin'
 
@@ -327,14 +328,33 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     }
   }
 
+  // Plugin subagents (operator/reviewer) see ONLY their declared builtins plus
+  // the orchestration tools — never the full main-session tool surface. The
+  // orchestration tools self-omit unless `liveSubagentRegistry`/
+  // `subagentRegistry`/`createSessionForSubagent` are wired (see
+  // buildSubagentOrchestrationTools); `spawn_subagent` enforces MAX_SUBAGENT_DEPTH
+  // at execute time so a depth-capped subagent's spawn fails closed even though
+  // the tool is present.
   const customSystemTools =
     options.customTools !== undefined
       ? options.customTools
       : options.pluginSubagent
-        ? resolvedSubagentBuiltins.toolDefinitions
+        ? [
+            ...resolvedSubagentBuiltins.toolDefinitions,
+            ...buildSubagentOrchestrationTools({
+              liveRegistry: options.liveSubagentRegistry,
+              registry: options.subagentRegistry,
+              createSessionForSubagent: options.createSessionForSubagent,
+              agentDir: options.plugins?.agentDir,
+              parentSessionId: sessionManager.getSessionId(),
+              getOrigin,
+              permissions: options.permissions,
+              stream: options.stream,
+            }),
+          ]
         : [
-            websearchTool,
-            webfetchTool,
+            webSearchTool,
+            webFetchTool,
             lookAtTool,
             ...(options.mcpManager ? buildMcpDispatcherToolDefinitions(options.mcpManager) : []),
             ...(options.reloadRegistry ? [createReloadTool({ registry: options.reloadRegistry })] : []),
@@ -405,6 +425,21 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
     ...(thinkingLevel ? { thinkingLevel } : {}),
   })
 
+  // Layer the replay sanitizer over pi's convertToLlm so a transcript with an
+  // orphaned toolResult (e.g. a torn-down restart turn) can't wedge the session
+  // with an Anthropic 400 on every replay. Runs on every provider call path
+  // that goes through the agent. Honors pi's contract that convertToLlm must
+  // not throw: on any failure it falls back to the unsanitized output.
+  const innerConvertToLlm = session.agent.convertToLlm
+  session.agent.convertToLlm = async (messages) => {
+    const converted = await innerConvertToLlm(messages)
+    try {
+      return sanitizeMessagesForLlmReplay(converted).messages
+    } catch {
+      return converted
+    }
+  }
+
   abortHolder.abort = () => {
     if (session.agent.signal?.aborted !== true) session.agent.abort()
   }
@@ -686,11 +721,13 @@ export function buildSubagentOrchestrationTools(opts: {
     createSubagentOutputTool({
       liveRegistry: opts.liveRegistry,
       getOrigin: opts.getOrigin,
+      callerSessionId: opts.parentSessionId,
       ...(opts.permissions ? { permissions: opts.permissions } : {}),
     }),
     createSubagentCancelTool({
       liveRegistry: opts.liveRegistry,
       getOrigin: opts.getOrigin,
+      callerSessionId: opts.parentSessionId,
       ...(opts.permissions ? { permissions: opts.permissions } : {}),
     }),
   ]

package/src/agent/llm-replay-sanitizer.ts

@@ -0,0 +1,120 @@
+// Defensive projection applied to the LLM message array right before each
+// provider call, layered on top of pi-coding-agent's `convertToLlm`. It exists
+// to un-wedge sessions whose persisted transcript contains a `toolResult` with
+// no live preceding `toolCall` — the exact shape Anthropic rejects with
+// "unexpected `tool_use_id` found in `tool_result` blocks" (HTTP 400).
+//
+// How a transcript gets poisoned: the self-`restart` tool exits the container
+// mid-turn. The assistant turn carrying the restart `toolCall` can land in the
+// JSONL with `stopReason: "error"/"aborted"` (or be torn down), while its
+// `toolResult` is persisted. On replay, pi-ai's provider-side `transformMessages`
+// DROPS error/aborted assistant turns but passes the `toolResult` through
+// unchanged, leaving a true orphan that the API rejects on every subsequent
+// turn — the session is permanently stuck.
+//
+// pi-ai's `transformMessages` already handles the inverse cases (a `toolCall`
+// with no result → synthetic "No result provided" result; error/aborted
+// assistant turns → dropped). The one gap is an orphaned `toolResult`. This
+// sanitizer fills exactly that gap and nothing more.
+//
+// Invariant (local pending-window, NOT a global id union — Anthropic requires
+// tool results to belong to the immediately preceding tool-use turn):
+//   1. Assistant turns with stopReason "error"/"aborted" are dropped here, so
+//      orphan detection sees the same message set the provider will after its
+//      own drop pass. Without this, a result tied to a dropped assistant would
+//      survive us and be orphaned downstream — the original bug.
+//   2. A `toolResult` is kept only if its `toolCallId` was declared by the most
+//      recent kept assistant tool-use turn AND has not already been emitted in
+//      that window. Any user or assistant message closes the window.
+//   3. Missing results are NOT synthesized here — pi-ai's existing pass inserts
+//      the synthetic placeholder, so dropping an orphan that leaves a bare
+//      `toolCall` is safe and self-healing.
+//
+// This is a read-only projection: it never mutates the persisted JSONL, so an
+// already-poisoned session becomes usable without destructive migration.
+
+import type { Message } from '@mariozechner/pi-ai'
+
+export type ReplaySanitizerStats = {
+  droppedOrphans: number
+  droppedDuplicates: number
+  droppedErrorAssistants: number
+}
+
+export type SanitizeResult = {
+  messages: Message[]
+  stats: ReplaySanitizerStats
+}
+
+function isErroredAssistant(message: Message): boolean {
+  return message.role === 'assistant' && (message.stopReason === 'error' || message.stopReason === 'aborted')
+}
+
+function toolCallIdsOf(message: Extract<Message, { role: 'assistant' }>): string[] {
+  return message.content
+    .filter((block): block is Extract<typeof block, { type: 'toolCall' }> => block.type === 'toolCall')
+    .map((block) => block.id)
+    .filter((id): id is string => typeof id === 'string' && id.length > 0)
+}
+
+export function sanitizeMessagesForLlmReplay(messages: Message[]): SanitizeResult {
+  const output: Message[] = []
+  const stats: ReplaySanitizerStats = {
+    droppedOrphans: 0,
+    droppedDuplicates: 0,
+    droppedErrorAssistants: 0,
+  }
+
+  let pendingToolCallIds = new Set<string>()
+  let emittedResultIds = new Set<string>()
+
+  const closeWindow = () => {
+    pendingToolCallIds = new Set()
+    emittedResultIds = new Set()
+  }
+
+  for (const message of messages) {
+    if (message.role === 'assistant') {
+      closeWindow()
+
+      // Mirror pi-ai's provider-side drop of incomplete turns so orphan
+      // detection matches the message set the provider will actually send.
+      if (isErroredAssistant(message)) {
+        stats.droppedErrorAssistants += 1
+        continue
+      }
+
+      const callIds = toolCallIdsOf(message)
+      if (callIds.length > 0) pendingToolCallIds = new Set(callIds)
+      output.push(message)
+      continue
+    }
+
+    if (message.role === 'user') {
+      closeWindow()
+      output.push(message)
+      continue
+    }
+
+    if (message.role === 'toolResult') {
+      const id = message.toolCallId
+      if (!pendingToolCallIds.has(id)) {
+        // Orphan: true orphan, stale late result, or result for a dropped
+        // error/aborted assistant turn.
+        stats.droppedOrphans += 1
+        continue
+      }
+      if (emittedResultIds.has(id)) {
+        stats.droppedDuplicates += 1
+        continue
+      }
+      emittedResultIds.add(id)
+      output.push(message)
+      continue
+    }
+
+    output.push(message)
+  }
+
+  return { messages: output, stats }
+}

package/src/agent/loop-guard.ts

@@ -63,6 +63,14 @@ export type LoopGuard = {
   check: (sessionId: string, tool: string, args: unknown) => LoopGuardDecision
   reset: (sessionId: string) => void
   forget: (sessionId: string) => void
+  // Clears only the residue a single tool left behind in a session: its entries
+  // in the windowed history and, if the current consecutive streak belongs to
+  // that tool, the streak itself. Used when a state-change boundary makes a
+  // tool's prior calls irrelevant — e.g. a backgrounded subagent finishing
+  // makes the next `subagent_output` fetch legitimate even though earlier
+  // premature polls poisoned the window. Narrower than `forget`, so an
+  // unrelated tool's accumulating loop on the same session is preserved.
+  forgetTool: (sessionId: string, tool: string) => void
 }
 
 type SessionState = {
@@ -215,9 +223,35 @@ export function createLoopGuard(options: CreateLoopGuardOptions = {}): LoopGuard
     forget(sessionId) {
       sessions.delete(sessionId)
     },
+    forgetTool(sessionId, tool) {
+      const state = sessions.get(sessionId)
+      if (state === undefined) return
+      const retained: string[] = []
+      for (const sig of state.window) {
+        if (signatureBelongsToTool(sig, tool)) {
+          state.windowWarned.delete(sig)
+        } else {
+          retained.push(sig)
+        }
+      }
+      state.window = retained
+      if (signatureBelongsToTool(state.signature, tool)) {
+        state.signature = ''
+        state.count = 0
+        state.warned = false
+      }
+    },
   }
 }
 
+// Both signature builders prefix the tool name: exact signatures as `tool:...`
+// and path-coarsened ones as `tool#path:...`. A tool's residue is therefore any
+// signature starting with `tool:` or `tool#`, never a different tool whose name
+// merely shares this one as a prefix (the delimiter rules that out).
+function signatureBelongsToTool(signature: string, tool: string): boolean {
+  return signature.startsWith(`${tool}:`) || signature.startsWith(`${tool}#`)
+}
+
 function formatWarnMessage(tool: string, count: number): string {
   return (
     `\n\n[loop-guard] You have called \`${tool}\` ${count} times in a row with identical arguments. ` +

package/src/agent/multimodal/look-at.ts

@@ -161,7 +161,7 @@ async function runLookAtImages(imageContents: ImageContent[], prompt: string | u
     origin,
     profile: 'vision',
     // Both knobs are required to fully disarm the subagent's tool surface:
-    // `customTools: []` blocks typeclaw's system tools (websearch/webfetch/
+    // `customTools: []` blocks typeclaw's system tools (web_search/web_fetch/
     // look_at/restart/...) — without it, the look_at tool would recurse
     // into itself. `tools: []` blocks pi-coding-agent's defaults
     // (read/bash/edit/write) — without it, a vision model could be talked

package/src/agent/plugin-tools.ts

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
+import { join } from 'node:path'
 
 import type { AgentTool } from '@mariozechner/pi-agent-core'
 import {
@@ -36,7 +37,10 @@ import type {
 import {
   buildSandboxedCommand,
   ensureBwrapAvailable,
+  ensureSessionTmpDir,
+  mapVirtualTmpPath,
   resolveHiddenPaths,
+  resolveProtectedZones,
   resolveWritableZones,
   subtractMasked,
 } from '@/sandbox'
@@ -44,8 +48,8 @@ import {
 import { createLoopGuard, type LoopGuard } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
 import type { SessionOrigin } from './session-origin'
-import { webfetchTool } from './tools/webfetch'
-import { websearchTool } from './tools/websearch'
+import { webFetchTool } from './tools/webfetch'
+import { webSearchTool } from './tools/websearch'
 
 // Process-wide loop guard. State is keyed by sessionId so concurrent sessions
 // don't interfere; the guard's own LRU bound keeps it from growing without
@@ -112,7 +116,7 @@ const ACKNOWLEDGE_GUARDS_SCHEMA = Type.Optional(
 // name-filter path); the wrapped customTools just replace the implementation
 // underneath so subagent and channel sessions share the same hook coverage.
 type PiAgentToolName = 'read' | 'bash' | 'edit' | 'write' | 'grep' | 'find' | 'ls'
-type TypeclawToolName = 'websearch' | 'webfetch'
+type TypeclawToolName = 'web_search' | 'web_fetch'
 
 const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
   read: piReadTool,
@@ -125,8 +129,8 @@ const PI_AGENT_TOOL_MAP: Record<PiAgentToolName, AgentTool<any, any>> = {
 }
 
 const TYPECLAW_TOOL_DEFINITION_MAP: Record<TypeclawToolName, ToolDefinition<any, any, any>> = {
-  websearch: websearchTool,
-  webfetch: webfetchTool,
+  web_search: webSearchTool,
+  web_fetch: webFetchTool,
 }
 
 function isPiAgentToolName(name: string): name is PiAgentToolName {
@@ -458,7 +462,11 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       stripGuardAcknowledgements(mutableArgs)
 
       if (tool.name === 'bash' && opts.permissions !== undefined) {
-        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, bashEnvOverlay)
+        await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId, bashEnvOverlay)
+      }
+
+      if (TMP_REDIRECT_TOOLS.has(tool.name) && opts.permissions !== undefined) {
+        await applyTmpPathRedirect(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId)
       }
 
       const result = await bashEnvStore.run(bashEnvOverlay, () =>
@@ -505,6 +513,7 @@ async function applyBashSandbox(
   permissions: PermissionService,
   origin: SessionOrigin | undefined,
   agentDir: string,
+  sessionId: string,
   envOverlay: BashEnvOverlay | undefined,
 ): Promise<void> {
   const command = mutableArgs.command
@@ -514,21 +523,46 @@ async function applyBashSandbox(
   if (dirs.length === 0 && files.length === 0) return
 
   await ensureBwrapAvailable()
+  // Per-session /tmp: bind this session's scratch dir over the default
+  // --tmpfs /tmp so writes survive across the role's sandboxed bash calls AND
+  // match what the write/edit wrapper redirected a /tmp path to. The bind is
+  // emitted via policy.mounts (after the hardcoded --tmpfs /tmp), so last-op-
+  // wins makes it the live /tmp. Unsandboxed roles (empty masks, returned
+  // above) keep sharing the real container /tmp between write and bash.
+  const sessionTmp = await ensureSessionTmpDir(sessionId)
   // Write-confined jail for low-trust roles: bind the whole project read-only,
   // hide private/secret paths, then re-expose only the free-write scratch zones
-  // RW. Anything else under agentDir (.git/, node_modules/, agentDir root) is
-  // EROFS, so bash cannot sidestep the non-workspace-write guard. Trusted/owner
-  // never reach here (their masks are empty) and keep full unsandboxed access.
-  // subtractMasked drops any writable zone masked for this role so an RW bind
-  // never re-exposes a hidden path (e.g. a guest's masked workspace/).
+  // (workspace + root allowlist + .git) RW. The WORKING TREE outside those zones
+  // (node_modules/, agentDir root, non-allowlisted tracked files) stays EROFS, so
+  // bash cannot sidestep the non-workspace-write guard — and `git checkout` of a
+  // protected worktree path fails at the kernel. .git is RW so members can
+  // commit; .git/hooks + .git/config (and any writable core.hooksPath target)
+  // are re-protected RO (protected, rendered after writable, ensured to exist so
+  // an absent path can't be created+executed) so a hook-plant / core.hooksPath
+  // never becomes code execution in the unsandboxed runtime git ops. Trusted/owner never reach here
+  // (their masks are empty) and keep full unsandboxed access. subtractMasked
+  // drops any writable zone masked for this role so an RW bind never re-exposes a
+  // hidden path (e.g. a guest's masked workspace/).
   const writable = subtractMasked(await resolveWritableZones(agentDir), { dirs, files })
+  // subtractMasked again on the protected set: a protected RO bind renders after
+  // the masks (last-op-wins), so an unfiltered protected path nested under a
+  // masked dir (e.g. a guest's workspace/ when core.hooksPath=workspace/hooks)
+  // would re-expose the hidden real dir. A masked path is already non-writable
+  // for this role, so it needs no protection anyway.
+  const protectedZones = writable.dirs.includes(join(agentDir, '.git'))
+    ? subtractMasked(await resolveProtectedZones(agentDir), { dirs, files })
+    : { dirs: [], files: [] }
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
   const { commandString } = buildSandboxedCommand(command, {
-    mounts: [{ type: 'ro-bind', source: agentDir, dest: agentDir }],
+    mounts: [
+      { type: 'ro-bind', source: agentDir, dest: agentDir },
+      { type: 'bind', source: sessionTmp, dest: '/tmp' },
+    ],
     masks: { dirs, files },
     writable,
+    protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
@@ -536,11 +570,55 @@ async function applyBashSandbox(
   mutableArgs.command = commandString
 }
 
+// The builtin file tools that take a single filesystem `path` arg. For a
+// sandboxed role they all run UNSANDBOXED in the main process (only bash is
+// bwrap-wrapped), so each must apply the same /tmp -> session-dir mapping that
+// applyBashSandbox binds for bash — otherwise a `read` of /tmp/foo hits the
+// real container /tmp while sandboxed bash wrote the session backing dir.
+const TMP_REDIRECT_TOOLS = new Set(['read', 'write', 'edit', 'grep', 'find', 'ls'])
+
+// Sandboxed roles read /tmp through bwrap's per-session bind (applyBashSandbox),
+// but the path-based file tools run unsandboxed against the real container /tmp.
+// Without this redirect a guest/member that touches /tmp/foo through bash (bound
+// to the session dir) and through a file tool (real /tmp) would see two
+// different files. Rewriting the file tool's on-disk path to the same session
+// backing dir makes every layer resolve /tmp/foo to one file. Unsandboxed roles
+// (empty masks) are left untouched: their bash already shares the real /tmp.
+async function applyTmpPathRedirect(
+  mutableArgs: Record<string, unknown>,
+  permissions: PermissionService,
+  origin: SessionOrigin | undefined,
+  agentDir: string,
+  sessionId: string,
+): Promise<void> {
+  const rawPath = mutableArgs.path
+  if (typeof rawPath !== 'string') return
+
+  const { dirs, files } = resolveHiddenPaths(permissions, origin, agentDir)
+  if (dirs.length === 0 && files.length === 0) return
+
+  const backing = mapVirtualTmpPath(agentDir, sessionId, rawPath)
+  if (backing === undefined) return
+
+  await ensureSessionTmpDir(sessionId)
+  mutableArgs.path = backing
+}
+
 function appendLoopWarning(result: ToolResult, message: string): ToolResult {
   const content: ContentPart[] = [...(result.content as ContentPart[]), { type: 'text', text: message }]
   return { content, details: result.details }
 }
 
+// Clears one tool's loop-guard residue for a session on the process-wide shared
+// guard. The completion-reminder bridges (channel router + TUI server) call this
+// for `subagent_output` when a backgrounded subagent finishes, so the next fetch
+// the reminder asks for isn't blocked by the window the agent's premature polling
+// poisoned. Exposed as a narrow function rather than the guard itself so callers
+// can't reach `check`/`forget` and widen the blast radius.
+export function forgetSharedLoopGuardTool(sessionId: string, tool: string): void {
+  sharedLoopGuard.forgetTool(sessionId, tool)
+}
+
 // Test-only seam: swaps the shared loop guard for a fresh instance so tests
 // that reuse sessionIds across cases don't see cross-test streak counts.
 // Production code never calls this; the guard's LRU bound handles

package/src/agent/session-origin.ts

@@ -69,6 +69,36 @@ export type SessionOrigin =
       triggeredBy?: SessionOrigin
     }
 
+// Hard ceiling on the subagent delegation chain. Bounds chain LENGTH, not
+// fan-out breadth: the deepest reachable chain is main (depth 0) →
+// operator/reviewer (depth 1) → nested worker (depth 2). `spawn_subagent`
+// refuses to spawn from a session already at this depth.
+export const MAX_SUBAGENT_DEPTH = 2
+
+// Counts subagent links from the root by walking the `spawnedByOrigin`
+// ancestry. A non-subagent (or undefined) origin is depth 0; each nested
+// subagent origin adds one. Fails CLOSED on ambiguous ancestry: if a subagent
+// origin has no `spawnedByOrigin` (the serialized path in
+// parseSpawnedByOriginJson drops it), the true depth is unknowable, so we
+// return MAX_SUBAGENT_DEPTH rather than assume it sits at the root — a
+// truncated grandchild must not read as a child and earn an extra spawn. A
+// cyclic chain is bounded by the same cap.
+export function subagentDepth(origin: SessionOrigin | undefined): number {
+  let depth = 0
+  let current: SessionOrigin | undefined = origin
+  while (current !== undefined && current.kind === 'subagent') {
+    depth += 1
+    if (current.spawnedByOrigin === undefined) {
+      return MAX_SUBAGENT_DEPTH
+    }
+    if (depth >= MAX_SUBAGENT_DEPTH) {
+      return depth
+    }
+    current = current.spawnedByOrigin
+  }
+  return depth
+}
+
 export const PARTICIPANTS_TOP_K = 10
 export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 
@@ -93,14 +123,20 @@ export const PARTICIPANTS_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000
 type PlatformInfo = {
   displayName: string
   mentionMode: 'angle-id' | 'at-username' | 'alias'
+  // Whether this adapter registers a ReactionCallback, i.e. whether
+  // `channel_react` actually does anything here. Gates the proactive-reaction
+  // prompt guidance so we never tell a KakaoTalk/Telegram agent to react when
+  // the call would no-op. Keep in sync with the adapters that call
+  // `router.registerReaction` (github, slack-bot, discord-bot today).
+  supportsReactions: boolean
 }
 
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
-  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id' },
-  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id' },
-  github: { displayName: 'GitHub', mentionMode: 'at-username' },
-  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username' },
-  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias' },
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id', supportsReactions: true },
+  'discord-bot': { displayName: 'Discord', mentionMode: 'angle-id', supportsReactions: true },
+  github: { displayName: 'GitHub', mentionMode: 'at-username', supportsReactions: true },
+  'telegram-bot': { displayName: 'Telegram', mentionMode: 'at-username', supportsReactions: false },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false },
 }
 
 function getPlatformInfo(adapter: AdapterId): PlatformInfo {
@@ -318,6 +354,23 @@ function renderChannelOrigin(
   const conversationLine = renderConversationLine(origin)
   if (conversationLine !== null) lines.push('', conversationLine)
 
+  if (platformInfo.supportsReactions) {
+    lines.push(
+      '',
+      '**React like a teammate would.** You can drop an emoji on the message that',
+      'triggered this turn with `channel_react({ emoji })` — it posts no comment,',
+      'just a reaction. Read the message and pick what genuinely fits its tone:',
+      '`+1` to agree or approve, `rocket` for something shipping or exciting,',
+      '`tada` to celebrate, `heart` to show appreciation, `laugh` for something',
+      'funny, `eyes` to signal you are looking. Reach for it when a reaction adds',
+      'real warmth or signal — not on every message, and not just because you can.',
+      'A reaction does NOT satisfy the reply obligation below: when the message',
+      'needs a substantive answer, still send it via `channel_reply`. Think of',
+      'reactions as the lightweight, human layer on top of your words, not a',
+      'replacement for them.',
+    )
+  }
+
   lines.push(
     '',
     '**For every user message in this session, you MUST call `channel_reply`',

package/src/agent/subagent-completion-reminder.ts

@@ -16,6 +16,7 @@ export type CompletionReminderArgs = {
   durationMs: number
   error?: string
   channel?: boolean
+  adapter?: string
 }
 
 const CHANNEL_REPLY_NUDGE =
@@ -28,9 +29,23 @@ const CHANNEL_REPLY_NUDGE =
   'can see why the post-completion turn was silent. `NO_REPLY` is the legacy fallback only when ' +
   '`skip_response` is unavailable.'
 
+// Conditional carve-out for github channel sessions. The base nudge above
+// steers EVERY completion to `channel_reply`, which on github is a plain PR
+// comment — fine for most subagents, but wrong for a finished `reviewer`:
+// a verdict delivered as a comment leaves the PR "awaiting review" with no
+// formal approval. This reminder cannot tell a review turn from any other
+// completion, so the carve-out is phrased conditionally ("if this was a PR
+// review") to redirect only the review case without misleading the rest.
+const GITHUB_REVIEW_NUDGE =
+  'If this was a PR review, the verdict is a formal review, not a `channel_reply`: ' +
+  'post it via `gh api -X POST /repos/owner/repo/pulls/<N>/reviews` (APPROVE/REQUEST_CHANGES/COMMENT) ' +
+  'and end the turn with `skip_response`. A `channel_reply` that merely says "Approved" posts a ' +
+  'comment and leaves the PR awaiting review.'
+
 export function renderSubagentCompletionReminder(args: CompletionReminderArgs): string {
   const durationStr = formatReminderDuration(args.durationMs)
-  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}` : ''
+  const githubTail = args.channel === true && args.adapter === 'github' ? ` ${GITHUB_REVIEW_NUDGE}` : ''
+  const channelTail = args.channel === true ? ` ${CHANNEL_REPLY_NUDGE}${githubTail}` : ''
   if (args.ok) {
     return (
       `<system-reminder>\n` +
@@ -59,6 +74,13 @@ export function formatReminderDuration(ms: number): string {
   return `${min}m${sec}s`
 }
 
+export type SubagentCompletedChannelKey = {
+  adapter: string
+  workspace: string
+  chat: string
+  thread: string | null
+}
+
 export type SubagentCompletedPayload = {
   taskId: string
   subagent: string
@@ -66,6 +88,11 @@ export type SubagentCompletedPayload = {
   ok: boolean
   durationMs: number
   error?: string
+  // Present when the parent was a channel session. Lets the router fall back
+  // to the live successor session for the same channel key when the parent
+  // rolled over (SESSION_FRESHNESS_TTL_MS) or was idle-evicted while the
+  // subagent ran — otherwise the completion is silently dropped.
+  channelKey?: SubagentCompletedChannelKey
 }
 
 // Type guard for the `subagent.completed` broadcast payload. Subscribers
@@ -82,9 +109,11 @@ export function parseSubagentCompletedPayload(payload: unknown): SubagentComplet
     ok?: unknown
     durationMs?: unknown
     error?: unknown
+    channelKey?: unknown
   }
   if (p.kind !== 'subagent.completed') return null
   if (typeof p.parentSessionId !== 'string') return null
+  const channelKey = parseChannelKey(p.channelKey)
   return {
     taskId: typeof p.taskId === 'string' ? p.taskId : '<unknown>',
     subagent: typeof p.subagent === 'string' ? p.subagent : 'subagent',
@@ -92,5 +121,14 @@ export function parseSubagentCompletedPayload(payload: unknown): SubagentComplet
     ok: p.ok === true,
     durationMs: typeof p.durationMs === 'number' ? p.durationMs : 0,
     ...(typeof p.error === 'string' ? { error: p.error } : {}),
+    ...(channelKey !== null ? { channelKey } : {}),
   }
 }
+
+function parseChannelKey(value: unknown): SubagentCompletedChannelKey | null {
+  if (value === null || typeof value !== 'object') return null
+  const k = value as { adapter?: unknown; workspace?: unknown; chat?: unknown; thread?: unknown }
+  if (typeof k.adapter !== 'string' || typeof k.workspace !== 'string' || typeof k.chat !== 'string') return null
+  if (k.thread !== null && typeof k.thread !== 'string') return null
+  return { adapter: k.adapter, workspace: k.workspace, chat: k.chat, thread: k.thread }
+}