typeclaw 0.31.0 → 0.32.0

package/package.json

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

package/src/agent/index.ts

@@ -49,6 +49,7 @@ import {
 } from './plugin-tools'
 import { createReloadTool } from './reload-tool'
 import type { RestartHandoffOrigin } from './restart-handoff'
+import type { SubagentBashPolicy } from './reviewer-bash-policy'
 import { loadSelf } from './self'
 import { SESSION_META_CUSTOM_TYPE, sessionMetaPayload } from './session-meta'
 import { renderSessionOrigin, type SessionOrigin, type SessionRoleContext } from './session-origin'
@@ -147,6 +148,11 @@ export type CreateSessionOptions = {
   // wider plugin registry's tools are NOT injected. Used by plugin subagent
   // session creation so subagents see exactly what they declared.
   pluginSubagent?: PluginSubagentSelection
+  // Per-subagent bash capability restriction. Threaded to the bash-tool wrapper
+  // and enforced before the role-derived sandbox, so a read-only subagent's
+  // bash stays read-only regardless of the spawning role. See
+  // `src/agent/reviewer-bash-policy.ts`.
+  bashPolicy?: SubagentBashPolicy
   // Enables the `restart` tool. Set when the agent is running inside a
   // typeclaw-managed container. Read from TYPECLAW_CONTAINER_NAME at the call site.
   containerName?: string
@@ -411,6 +417,7 @@ export async function createSessionWithDispose(options: CreateSessionOptions = {
           getOrigin,
           getAbort,
           ...(options.permissions ? { permissions: options.permissions } : {}),
+          ...(options.bashPolicy !== undefined ? { bashPolicy: options.bashPolicy } : {}),
         })
       : []
   const wrappedCustomSystemTools = wrapSystemTools(customSystemTools, options.plugins, getOrigin, getAbort)

package/src/agent/plugin-tools.ts

@@ -49,6 +49,7 @@ import {
 
 import { createLoopGuard, type LoopGuard, type LoopGuardDecision } from './loop-guard'
 import { checkImageReadRedirect } from './multimodal/read-redirect'
+import { enforceSubagentBashPolicy, type SubagentBashPolicy } from './reviewer-bash-policy'
 import type { SessionOrigin } from './session-origin'
 import { SUBAGENT_OUTPUT_TOOL_NAME, type SubagentOutputToolDetails } from './tools/subagent-output'
 import { webFetchTool } from './tools/webfetch'
@@ -193,6 +194,11 @@ export type WrapSystemToolOptions = {
   // runs bash unchanged — preserving today's behavior for trusted+ and for
   // sessions wired without a permission service (e.g. tests).
   permissions?: PermissionService
+  // Per-subagent bash capability policy, enforced as a hard pre-check BEFORE
+  // the role-derived sandbox (which returns early for trusted/owner). Lets a
+  // read-only subagent keep its bash read-only no matter who spawned it. See
+  // `src/agent/reviewer-bash-policy.ts`.
+  bashPolicy?: SubagentBashPolicy
 }
 
 // Zod 4 emits a top-level `"$schema": "https://json-schema.org/draft/2020-12/schema"`
@@ -461,6 +467,16 @@ export function wrapAgentToolAsCustomToolDefinition<TParams extends TSchema, TDe
       }
       stripGuardAcknowledgements(mutableArgs)
 
+      // Per-subagent capability fence: runs BEFORE the role-derived sandbox so
+      // a read-only subagent's bash stays read-only even for a trusted/owner
+      // caller (for whom applyBashSandbox returns early with no masks). Throws
+      // SubagentBashPolicyError on a disallowed command, surfaced to the model
+      // as a tool error.
+      if (tool.name === 'bash' && opts.bashPolicy !== undefined) {
+        const command = mutableArgs.command
+        if (typeof command === 'string') enforceSubagentBashPolicy(opts.bashPolicy, command)
+      }
+
       if (tool.name === 'bash' && opts.permissions !== undefined) {
         await applyBashSandbox(mutableArgs, opts.permissions, liveOrigin, opts.agentDir, opts.sessionId, bashEnvOverlay)
       }

package/src/agent/reviewer-bash-policy.ts

@@ -0,0 +1,572 @@
+// Per-subagent bash capability policy. This is NOT the bwrap filesystem
+// sandbox (src/sandbox/) — that is role-derived and returns early for
+// trusted/owner callers. This is a subagent-capability boundary that must hold
+// regardless of who spawned the subagent, so it is enforced as a standalone
+// pre-check at the bash-wrap site before applyBashSandbox runs.
+//
+// Design (issue #452): the `reviewer` subagent is read-only by contract, but
+// its legitimate workflows use pipes (`gh api … | base64 -d | nl -ba`), `&&`
+// chains, and writes to a throwaway `/tmp` scratch checkout. A prefix
+// allowlist plus a metacharacter ban (the SandboxCommandFilter primitive)
+// cannot express "a pipeline of read-only commands", so this policy instead:
+//   1. fails closed on shell constructs that defeat static analysis
+//      (command/process substitution, heredocs, `eval`/`sh -c` wrappers,
+//      redirects to non-/tmp paths, unbalanced quotes);
+//   2. splits the remaining command on top-level `|` `&&` `||` `;` with a
+//      quote/escape-aware scanner;
+//   3. classifies each segment's leading verb against a read-only allowlist and
+//      a mutating-subcommand denylist, with path-sensitive handling for the few
+//      verbs (git checkout/clone, file writers) that are safe only under /tmp.
+// It is defense-in-depth layered on top of the global exfil guards, not the
+// sole fence — so "deny what we cannot prove safe" is the correct bias.
+
+export type SubagentBashPolicy = { kind: 'readonly-reviewer' }
+
+export class SubagentBashPolicyError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'SubagentBashPolicyError'
+  }
+}
+
+// Constructs that let a benign-looking string smuggle an arbitrary command past
+// segment/verb analysis. `$(`/backtick = command substitution; `<(`/`>(` =
+// process substitution; `<<` = heredoc; `${` is allowed (plain var expansion is
+// harmless for our denylist) but `$((` arithmetic and `$(` are not. We reject
+// the whole command if any appear — the reviewer's documented workflows need
+// none of them.
+const FAIL_CLOSED_CONSTRUCTS: { pattern: RegExp; reason: string }[] = [
+  { pattern: /\$\(/, reason: 'command substitution `$(…)`' },
+  { pattern: /`/, reason: 'backtick command substitution' },
+  { pattern: /<\(/, reason: 'process substitution `<(…)`' },
+  { pattern: />\(/, reason: 'process substitution `>(…)`' },
+  { pattern: /<</, reason: 'heredoc `<<`' },
+]
+
+// Wrapper verbs that re-enter a shell or hand execution to another command,
+// defeating verb analysis (`bash -c "git push"`, `xargs rm`, `find … -exec`).
+// Denied outright as a leading verb.
+const FORBIDDEN_WRAPPER_VERBS = new Set([
+  'eval',
+  'exec',
+  'source',
+  '.',
+  'sh',
+  'bash',
+  'zsh',
+  'dash',
+  'env',
+  'command',
+  'xargs',
+  'find',
+  'parallel',
+  'time',
+  'nohup',
+  'sudo',
+  'doas',
+  'ssh',
+])
+
+// Leading verbs that are read-only and need no further inspection.
+const READONLY_VERBS = new Set([
+  'cat',
+  'head',
+  'tail',
+  'wc',
+  'sort',
+  'uniq',
+  'cut',
+  'tr',
+  'nl',
+  'base64',
+  'jq',
+  'yq',
+  'grep',
+  'rg',
+  'egrep',
+  'fgrep',
+  'ls',
+  'pwd',
+  'echo',
+  'printf',
+  'true',
+  'false',
+  'test',
+  'dirname',
+  'basename',
+  'realpath',
+  'date',
+  'sed', // read-only as used (no -i); -i is denied below
+  'awk',
+  'diff',
+  'comm',
+  'column',
+  'fold',
+  'rev',
+  'tee', // path-checked below
+])
+
+// `git` subcommands that never mutate the working tree or remote.
+const GIT_READONLY_SUBCOMMANDS = new Set([
+  'log',
+  'diff',
+  'show',
+  'blame',
+  'status',
+  'grep',
+  'rev-parse',
+  'rev-list',
+  'ls-files',
+  'ls-tree',
+  'cat-file',
+  'describe',
+  'shortlog',
+  'config', // read form only; --add/--set caught by the write-flag check
+  'remote', // `git remote -v` is read; mutating forms caught below
+  'branch', // `git branch` (list) is read; create/delete caught below
+  'tag', // `git tag` (list) is read; create/delete caught below
+  'name-rev',
+  'merge-base',
+  'symbolic-ref',
+  'for-each-ref',
+  'show-ref',
+  'reflog',
+  'whatchanged',
+])
+
+// `git` subcommands that mutate the working tree, index, or remote. Denied
+// unless the whole git invocation is scoped to a /tmp working dir (scratch
+// clone): `clone`/`fetch`/`checkout` into /tmp are the reviewer's acquisition
+// path; everything else stays denied even under /tmp because it has no
+// legitimate reviewer use.
+const GIT_MUTATING_ALWAYS_DENIED = new Set([
+  'add',
+  'commit',
+  'push',
+  'rebase',
+  'reset',
+  'merge',
+  'cherry-pick',
+  'revert',
+  'am',
+  'apply',
+  'stash',
+  'clean',
+  'rm',
+  'mv',
+  'restore',
+  'switch',
+  'gc',
+  'prune',
+  'update-ref',
+  'update-index',
+  'write-tree',
+  'commit-tree',
+  'hash-object',
+])
+
+// git subcommands permitted only when the effective working dir is /tmp.
+const GIT_TMP_SCOPED = new Set(['clone', 'fetch', 'checkout', 'init', 'sparse-checkout', 'worktree'])
+
+// `gh` subcommands/objects that mutate remote state. The reviewer reads PRs and
+// repos; it never merges, reviews, comments, edits, or creates. We allow the
+// read objects explicitly and deny the rest, because `gh` is the highest-value
+// mutation surface (it can approve PRs, which the reviewer must NEVER do — the
+// parent owns posting).
+const GH_READONLY_BY_OBJECT: Record<string, Set<string>> = {
+  pr: new Set(['view', 'diff', 'list', 'checks', 'status']),
+  issue: new Set(['view', 'list', 'status']),
+  repo: new Set(['view', 'list']),
+  release: new Set(['view', 'list']),
+  run: new Set(['view', 'list']),
+  api: new Set(['__any__']), // gh api is method-checked below
+  search: new Set(['__any__']),
+  browse: new Set(['__any__']),
+}
+
+// Filesystem mutators that are safe only when every path operand is under /tmp.
+const FS_WRITERS = new Set(['rm', 'mv', 'cp', 'mkdir', 'touch', 'chmod', 'chown', 'ln', 'rmdir', 'truncate'])
+
+const TMP_PREFIXES = ['/tmp/', '/private/tmp/']
+
+function isTmpPath(token: string): boolean {
+  const unquoted = stripQuotes(token)
+  return unquoted === '/tmp' || TMP_PREFIXES.some((p) => unquoted.startsWith(p))
+}
+
+function stripQuotes(token: string): string {
+  if (token.length >= 2) {
+    const first = token[0]
+    const last = token[token.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      return token.slice(1, -1)
+    }
+  }
+  return token
+}
+
+// Quote/escape-aware tokenizer that ALSO surfaces top-level operators and
+// redirects. Returns the token list plus the set of redirect targets so the
+// caller can fail closed on a redirect to a non-/tmp path. Throws on unbalanced
+// quotes (fail closed — an unterminated quote means we cannot trust the split).
+type Segment = { tokens: string[]; redirectTargets: string[] }
+
+function splitIntoSegments(command: string): Segment[] {
+  const segments: Segment[] = []
+  let tokens: string[] = []
+  let redirectTargets: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  let expectingRedirectTarget = false
+
+  const pushToken = () => {
+    if (current.length === 0) return
+    if (expectingRedirectTarget) {
+      redirectTargets.push(current)
+      expectingRedirectTarget = false
+    } else {
+      tokens.push(current)
+    }
+    current = ''
+  }
+  const pushSegment = () => {
+    pushToken()
+    segments.push({ tokens, redirectTargets })
+    tokens = []
+    redirectTargets = []
+  }
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]!
+    if (quote !== null) {
+      current += ch
+      if (ch === quote) quote = null
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      current += ch
+      continue
+    }
+    if (ch === '\\') {
+      current += ch
+      if (i + 1 < command.length) {
+        current += command[i + 1]
+        i++
+      }
+      continue
+    }
+    if (ch === '|' || ch === '&' || ch === ';' || ch === '\n' || ch === '\r') {
+      const next = command[i + 1]
+      // `|`, `||`, `&&`, `;`, and a NEWLINE all start a new top-level segment.
+      // bash treats an unquoted newline as a command separator exactly like `;`,
+      // so failing to split on it would let `git status\ngit push` parse as one
+      // allowed `git status` segment while bash runs `git push` separately. A
+      // lone `&` (background) is treated the same — we don't run backgrounded jobs.
+      if ((ch === '|' && next === '|') || (ch === '&' && next === '&')) i++
+      pushSegment()
+      continue
+    }
+    if (ch === '>' || ch === '<') {
+      // Redirect operator. The following word is a path target we must
+      // path-check. `2>`, `&>` handled by the trailing-fd char already being in
+      // `current` — flush it as a token first.
+      pushToken()
+      // consume an optional second char (>>, 2>, &>)
+      if (command[i + 1] === '>') i++
+      expectingRedirectTarget = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      pushToken()
+      continue
+    }
+    current += ch
+  }
+  if (quote !== null) {
+    throw new SubagentBashPolicyError('command has an unbalanced quote; refusing to run what cannot be parsed safely.')
+  }
+  pushSegment()
+  return segments.filter((s) => s.tokens.length > 0 || s.redirectTargets.length > 0)
+}
+
+function hasWriteFlag(tokens: string[]): boolean {
+  return tokens.some((t) => t === '-i' || t === '--in-place' || t.startsWith('-i') || t === '--set' || t === '--add')
+}
+
+function classifyGit(tokens: string[]): void {
+  // Resolve `git -C <dir>` and global flags to find the subcommand and the
+  // effective working directory.
+  let workdir: string | null = null
+  let idx = 1
+  while (idx < tokens.length) {
+    const t = tokens[idx]!
+    if (t === '-C') {
+      workdir = tokens[idx + 1] ?? null
+      idx += 2
+      continue
+    }
+    if (t === '-c') {
+      // `git -c key=val` config override — skip the pair. A core.hooksPath
+      // override is a mutation vector, so deny it outright.
+      const kv = tokens[idx + 1] ?? ''
+      if (/hookspath|core\.editor|alias\./i.test(stripQuotes(kv))) {
+        throw new SubagentBashPolicyError('git -c override of hooks/editor/alias is not permitted for the reviewer.')
+      }
+      idx += 2
+      continue
+    }
+    if (t.startsWith('-')) {
+      idx++
+      continue
+    }
+    break
+  }
+  const sub = tokens[idx]
+  if (sub === undefined) return // bare `git` — harmless
+  const subcommand = stripQuotes(sub)
+
+  if (GIT_MUTATING_ALWAYS_DENIED.has(subcommand)) {
+    throw new SubagentBashPolicyError(
+      `git ${subcommand} mutates repository state, which the read-only reviewer may not do.`,
+    )
+  }
+  if (GIT_TMP_SCOPED.has(subcommand)) {
+    assertGitTmpScoped(subcommand, workdir, tokens.slice(idx + 1))
+    return
+  }
+  if (GIT_READONLY_SUBCOMMANDS.has(subcommand)) {
+    if (
+      (subcommand === 'config' || subcommand === 'remote' || subcommand === 'branch' || subcommand === 'tag') &&
+      tokens.slice(idx + 1).some((t) => isGitWriteForm(subcommand, stripQuotes(t)))
+    ) {
+      throw new SubagentBashPolicyError(`git ${subcommand} is being used in a mutating form, which is not permitted.`)
+    }
+    return
+  }
+  throw new SubagentBashPolicyError(`git ${subcommand} is not on the reviewer's read-only allowlist.`)
+}
+
+// A /tmp-scoped git subcommand is safe only when the path it WRITES is under
+// /tmp — not merely when some operand mentions /tmp. The earlier `.some(isTmpPath)`
+// let `git clone /tmp/src /agent/evil` through because the source token matched
+// while git wrote the destination at /agent/evil. Validate the actual write
+// target per subcommand: clone writes its destination operand (or, when omitted,
+// a directory derived from the repo under cwd — which we cannot prove is /tmp,
+// so we require an explicit /tmp destination); -C-scoped operations write the
+// -C workdir; a bare fetch/checkout without -C writes the ambient repo, which
+// is not /tmp.
+function assertGitTmpScoped(subcommand: string, workdir: string | null, rest: string[]): void {
+  const deny = (detail: string): never => {
+    throw new SubagentBashPolicyError(`git ${subcommand} is permitted only against a /tmp scratch checkout; ${detail}.`)
+  }
+  if (workdir !== null) {
+    if (!isTmpPath(workdir)) deny('the -C working directory is not under /tmp')
+    return
+  }
+  if (subcommand === 'clone') {
+    // `git clone [flags] <repo> [<dir>]`: the write target is the explicit
+    // <dir> operand when present, else a repo-derived dir under cwd (unprovable
+    // as /tmp). Extracting operands requires skipping value-taking flags
+    // (`--depth 1`, `-b main`, `--branch x`, …) whose VALUE is a bare word that
+    // would otherwise be miscounted as the repo or destination.
+    const operands = cloneOperands(rest)
+    const dest = operands[1]
+    if (dest === undefined) deny('clone needs an explicit /tmp destination directory')
+    if (!isTmpPath(dest!)) deny('the clone destination is not under /tmp')
+    return
+  }
+  // fetch/checkout/init/sparse-checkout/worktree without -C operate on the
+  // ambient repo (the agent checkout), which is never /tmp. Require -C /tmp.
+  deny(`${subcommand} without -C operates on the ambient repo; scope it with -C /tmp/review-*`)
+}
+
+// `git clone` flags that consume the NEXT token as their value (separated form,
+// e.g. `--depth 1`). Their value is a bare word, so it must be skipped when
+// counting positional operands (<repo> [<dir>]). Attached forms (`--depth=1`,
+// `-b=x`) carry their own value and need no skip. Unknown long flags are treated
+// as boolean (no skip); if a future value-taking flag is missed, the worst case
+// is a stricter deny (a real operand shifts), never a looser allow.
+const GIT_CLONE_VALUE_FLAGS = new Set([
+  '--depth',
+  '-b',
+  '--branch',
+  '-o',
+  '--origin',
+  '-u',
+  '--upload-pack',
+  '--reference',
+  '--reference-if-able',
+  '--separate-git-dir',
+  '-c',
+  '--config',
+  '--shallow-since',
+  '--shallow-exclude',
+  '-j',
+  '--jobs',
+  '--filter',
+  '--template',
+])
+
+function cloneOperands(rest: string[]): string[] {
+  const operands: string[] = []
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i]!
+    if (t.startsWith('-')) {
+      if (GIT_CLONE_VALUE_FLAGS.has(t)) i++
+      continue
+    }
+    operands.push(t)
+  }
+  return operands
+}
+
+function isGitWriteForm(sub: string, arg: string): boolean {
+  if (sub === 'config') return arg === '--add' || arg === '--unset' || arg === '--replace-all' || arg === '--set'
+  if (sub === 'remote')
+    return arg === 'add' || arg === 'remove' || arg === 'rm' || arg === 'set-url' || arg === 'rename'
+  if (sub === 'branch') return arg === '-d' || arg === '-D' || arg === '--delete' || arg === '-m' || arg === '-M'
+  if (sub === 'tag') return arg === '-d' || arg === '--delete' || arg === '-a' || arg === '-s'
+  return false
+}
+
+function classifyGh(tokens: string[]): void {
+  // Find the object (pr/issue/repo/api/…) skipping global flags.
+  let idx = 1
+  while (idx < tokens.length && tokens[idx]!.startsWith('-')) idx++
+  const objRaw = tokens[idx]
+  if (objRaw === undefined) return
+  const obj = stripQuotes(objRaw)
+  const allowed = GH_READONLY_BY_OBJECT[obj]
+  if (allowed === undefined) {
+    throw new SubagentBashPolicyError(
+      `gh ${obj} is not on the reviewer's read-only allowlist (it may mutate remote state).`,
+    )
+  }
+  if (obj === 'api') {
+    assertGhApiReadOnly(tokens.slice(idx + 1))
+    return
+  }
+  if (allowed.has('__any__')) return
+  // Find the verb after the object.
+  let vIdx = idx + 1
+  while (vIdx < tokens.length && tokens[vIdx]!.startsWith('-')) vIdx++
+  const verbRaw = tokens[vIdx]
+  if (verbRaw === undefined) return // bare `gh pr` — harmless listing-ish
+  const verb = stripQuotes(verbRaw)
+  if (!allowed.has(verb)) {
+    throw new SubagentBashPolicyError(`gh ${obj} ${verb} is not a read-only operation; the reviewer may not run it.`)
+  }
+}
+
+// `gh api` does NOT always default to GET. Per `gh api --help`: "adding request
+// parameters will automatically switch the request method to POST". So any of
+// `-f/--field`, `-F/--raw-field`, or `--input` flips the call to POST unless an
+// explicit `--method GET/HEAD` overrides it. We mirror that inference, and we
+// deny the `graphql` endpoint outright unless it is provably a query (a `mutation`
+// operation is a write; even a query we cannot statically prove safe is denied
+// for the reviewer because graphql can mutate through a GET-shaped call).
+// Separated forms (flag and value are two tokens, e.g. `--field body=x`).
+const GH_API_BODY_FLAGS = new Set(['-f', '--field', '-F', '--raw-field', '--input', '-d', '--data'])
+// Attached long forms (`--field=body=x`, `--input=/tmp/x`). Each must be matched
+// with its trailing `=` so `--field` proper still routes through the separated
+// set above, and so an unrelated flag that merely starts with the same letters
+// is not misread. Attached SHORT forms (`-fbody=x`, `-Fx`) are caught by the
+// `-f`/`-F` prefix check at the call site.
+const GH_API_BODY_FLAG_PREFIXES = ['--field=', '--raw-field=', '--input=', '--data=']
+
+function isGhApiBodyParam(token: string): boolean {
+  if (GH_API_BODY_FLAGS.has(token)) return true
+  if (token.startsWith('-f') || token.startsWith('-F')) return true
+  return GH_API_BODY_FLAG_PREFIXES.some((p) => token.startsWith(p))
+}
+
+function assertGhApiReadOnly(rest: string[]): void {
+  let explicitMethod: string | null = null
+  let hasBodyParam = false
+  let isGraphql = false
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i]!
+    if (t === '-X' || t === '--method') {
+      explicitMethod = stripQuotes(rest[i + 1] ?? '').toUpperCase()
+      continue
+    }
+    if (t.startsWith('-X')) {
+      explicitMethod = stripQuotes(t.slice(2)).toUpperCase()
+      continue
+    }
+    if (t.startsWith('--method=')) {
+      explicitMethod = stripQuotes(t.slice('--method='.length)).toUpperCase()
+      continue
+    }
+    if (isGhApiBodyParam(t)) hasBodyParam = true
+    if (stripQuotes(t) === 'graphql') isGraphql = true
+  }
+  if (isGraphql) {
+    throw new SubagentBashPolicyError(
+      'gh api graphql can mutate (a `mutation` operation is a write, and a GET-shaped call can still mutate); the reviewer may not use the graphql endpoint.',
+    )
+  }
+  const method = explicitMethod ?? (hasBodyParam ? 'POST' : 'GET')
+  if (method !== 'GET' && method !== 'HEAD') {
+    throw new SubagentBashPolicyError(
+      `gh api resolves to ${method} (explicit or inferred from request parameters), which mutates remote state; the reviewer may only GET/HEAD.`,
+    )
+  }
+}
+
+function classifyFsWriter(verb: string, tokens: string[], redirectTargets: string[]): void {
+  const operands = tokens.slice(1).filter((t) => !t.startsWith('-'))
+  const allUnderTmp = operands.length > 0 && operands.every(isTmpPath) && redirectTargets.every(isTmpPath)
+  if (!allUnderTmp) {
+    throw new SubagentBashPolicyError(
+      `${verb} may only write under /tmp for the reviewer; a non-/tmp path operand is not permitted.`,
+    )
+  }
+}
+
+function classifySegment(segment: Segment): void {
+  const { tokens, redirectTargets } = segment
+  // A redirect to any non-/tmp path is a write to the persistent tree.
+  for (const target of redirectTargets) {
+    if (!isTmpPath(target)) {
+      throw new SubagentBashPolicyError(
+        `redirect to ${stripQuotes(target)} writes outside /tmp, which the read-only reviewer may not do.`,
+      )
+    }
+  }
+  if (tokens.length === 0) return
+  const verb = stripQuotes(tokens[0]!)
+
+  if (FORBIDDEN_WRAPPER_VERBS.has(verb)) {
+    throw new SubagentBashPolicyError(`\`${verb}\` can re-enter a shell or hand off execution; it is not permitted.`)
+  }
+  if (verb === 'git') return classifyGit(tokens)
+  if (verb === 'gh') return classifyGh(tokens)
+  if (FS_WRITERS.has(verb)) return classifyFsWriter(verb, tokens, redirectTargets)
+  if (verb === 'sed' && hasWriteFlag(tokens)) {
+    throw new SubagentBashPolicyError('sed -i edits files in place; the reviewer is read-only.')
+  }
+  if (verb === 'tee') return classifyFsWriter('tee', tokens, redirectTargets)
+  if (READONLY_VERBS.has(verb)) return
+  // Package managers and anything unknown: deny. Unknown verbs are the most
+  // likely bypass channel, so fail closed.
+  throw new SubagentBashPolicyError(
+    `\`${verb}\` is not on the reviewer's read-only command allowlist; refusing to run it.`,
+  )
+}
+
+export function enforceReviewerReadonlyBashPolicy(command: string): void {
+  if (typeof command !== 'string' || command.trim().length === 0) return
+  for (const { pattern, reason } of FAIL_CLOSED_CONSTRUCTS) {
+    if (pattern.test(command)) {
+      throw new SubagentBashPolicyError(`command uses ${reason}, which the reviewer policy cannot analyze safely.`)
+    }
+  }
+  const segments = splitIntoSegments(command)
+  for (const segment of segments) classifySegment(segment)
+}
+
+export function enforceSubagentBashPolicy(policy: SubagentBashPolicy, command: string): void {
+  if (policy.kind === 'readonly-reviewer') enforceReviewerReadonlyBashPolicy(command)
+}

package/src/agent/session-origin.ts

@@ -129,14 +129,34 @@ type PlatformInfo = {
   // the call would no-op. Keep in sync with the adapters that call
   // `router.registerReaction` (github, slack-bot, discord-bot today).
   supportsReactions: boolean
+  // Whether this adapter's OutboundCallback accepts file attachments. Gates the
+  // "ship a researcher report as a PDF by default" prompt guidance: a report is
+  // only worth converting to a downloadable file on channels that can actually
+  // receive one. GitHub's outbound callback hard-rejects attachments
+  // (`github-bot-does-not-support-attachments` in adapters/github/outbound.ts),
+  // so a PDF nudge there would train the model toward a call that always fails;
+  // the other four upload files (Slack `uploadFile`, Discord `uploadFile`,
+  // Telegram `sendDocument`, KakaoTalk `sendAttachment`). Keep in sync with the
+  // adapters' outbound callbacks.
+  supportsAttachments: boolean
 }
 
 const PLATFORM_INFO: Record<AdapterId, PlatformInfo> = {
-  '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 },
+  'slack-bot': { displayName: 'Slack', mentionMode: 'angle-id', supportsReactions: true, supportsAttachments: true },
+  'discord-bot': {
+    displayName: 'Discord',
+    mentionMode: 'angle-id',
+    supportsReactions: true,
+    supportsAttachments: true,
+  },
+  github: { displayName: 'GitHub', mentionMode: 'at-username', supportsReactions: true, supportsAttachments: false },
+  'telegram-bot': {
+    displayName: 'Telegram',
+    mentionMode: 'at-username',
+    supportsReactions: false,
+    supportsAttachments: true,
+  },
+  kakaotalk: { displayName: 'KakaoTalk', mentionMode: 'alias', supportsReactions: false, supportsAttachments: true },
 }
 
 function getPlatformInfo(adapter: AdapterId): PlatformInfo {
@@ -461,6 +481,7 @@ function renderChannelOrigin(
     "matching the channel's `allow` rules are accepted (the tool returns",
     '`{ ok: false }` otherwise).',
     '',
+    ...renderResearchReportDeliveryGuidance(platformInfo),
     ...renderMentionGuidance(platformInfo, origin.participants ?? [], now, origin.self),
   )
 
@@ -496,6 +517,30 @@ function renderMembershipSummary(
   return `This channel has approximately ${total} members (about ${membership.humans} humans, ${membership.bots} bots — the bot count is approximate, the full member list was not enumerated because it exceeds the 50-member cap). The 10 most recent speakers are listed below.`
 }
 
+// The `researcher` subagent always hands back a markdown report file
+// (`research-<slug>.md`) and is itself read-only — it cannot produce the PDF.
+// Whoever delivers that report to a channel is the one who decides the format,
+// and on a channel that accepts file uploads the right default for a multi-page
+// research report is a downloadable PDF, not a wall of raw markdown dumped into
+// chat. This block makes that the default ONLY where it is actionable: gated on
+// `supportsAttachments` so GitHub (whose outbound callback rejects attachments)
+// never gets a nudge toward a `channel_send` call that would fail.
+function renderResearchReportDeliveryGuidance(platformInfo: PlatformInfo): string[] {
+  if (!platformInfo.supportsAttachments) return []
+  return [
+    `**Ship \`researcher\` reports as a PDF by default.** ${platformInfo.displayName} accepts file`,
+    'attachments. When you receive a `researcher` subagent result — a',
+    '`research-<slug>.md` report file path in its `<report>` block — convert that',
+    'markdown to a PDF with the `typeclaw-markdown-pdf` skill and deliver it with',
+    '`channel_send({ ..., attachments: [{ path, filename }] })`, with a one- or',
+    'two-line summary as the message text. A downloadable file is what a human',
+    'wants for a multi-page report; do not paste the full markdown into chat. Send',
+    'the report inline as plain text only if the caller explicitly asked for it in',
+    'the message, or the report is short enough that a file would be overkill.',
+    '',
+  ]
+}
+
 function renderMentionGuidance(
   platformInfo: PlatformInfo,
   participants: readonly ChannelParticipant[],

package/src/agent/subagents.ts

@@ -6,6 +6,7 @@ import type { Stream, Unsubscribe } from '@/stream'
 
 import { type AgentSession, createSession } from './index'
 import { subscribeProviderErrors } from './provider-error'
+import type { SubagentBashPolicy } from './reviewer-bash-policy'
 import type { SessionOrigin } from './session-origin'
 import {
   beginSubagentDrainWatch,
@@ -88,6 +89,13 @@ export type SubagentShared<P = unknown> = {
   // hangs" symptom. Omit for no ceiling (legacy behavior; the spawn waits
   // as long as the provider takes).
   timeoutMs?: number
+  // Per-subagent bash capability restriction, enforced at the bash-wrap site
+  // INDEPENDENT of the caller's role (unlike the role-derived bwrap sandbox,
+  // which returns early for trusted/owner). A read-only subagent declares this
+  // to fence its `bash` to read-only commands even when spawned by a privileged
+  // caller. See `src/agent/reviewer-bash-policy.ts`. Omit for no restriction
+  // (the historical contract — prompt-only enforcement).
+  bashPolicy?: SubagentBashPolicy
 }
 
 export type Subagent<P = unknown> = SubagentShared<P> & {
@@ -155,6 +163,7 @@ export const defaultCreateSessionForSubagent: CreateSessionForSubagent = (subage
     customTools: subagent.customTools ?? [],
     ...(subagent.profile !== undefined ? { profile: subagent.profile } : {}),
     ...(subagent.toolResultBudget !== undefined ? { toolResultBudget: subagent.toolResultBudget } : {}),
+    ...(subagent.bashPolicy !== undefined ? { bashPolicy: subagent.bashPolicy } : {}),
   })
 
 type NormalizedSubagentSession = {

package/src/bundled-plugins/github-cli-auth/approve-idempotency.ts

@@ -1,14 +1,28 @@
 import type { ReviewVerdict } from '@/channels/github-review-turn-ledger'
 
-// `NONE` covers "never reviewed" and "last decisive review was DISMISSED" — both
-// mean a fresh verdict is legitimate (not a duplicate).
-export type EffectiveVerdict = 'APPROVED' | 'CHANGES_REQUESTED' | 'NONE'
+// Raw latest-decisive state. DISMISSED is kept DISTINCT from NONE on purpose: a
+// genuine dismissal means a fresh same-verdict re-review is legitimate and must
+// NOT be shadowed by the read-after-write-lag cache (which only overrides a bare
+// NONE — "GitHub shows no decisive review, but we just landed one"). Collapsing
+// DISMISSED into NONE would let the lag cache re-strand a dismiss-then-reapprove,
+// the exact failure 35287f99 removed.
+export type EffectiveVerdict = 'APPROVED' | 'CHANGES_REQUESTED' | 'DISMISSED' | 'NONE'
 
 export type EffectiveApprovalResolver = (target: {
   workspace: string
   prNumber: number
 }) => Promise<{ ok: true; effective: EffectiveVerdict } | { ok: false }>
 
+// Resolves the PR's current head commit SHA. Called twice: once in guard() (the
+// pre-submit head, resolved AFTER the in-flight lease so the await cannot widen the
+// reserve-before-await race) and once in release() (the post-submit head, to detect
+// a push that landed during the review). Fails soft (null). A null PRE-submit head
+// skips the cache write entirely — the guard falls open to GitHub rather than ever
+// stranding a genuine verdict on local memory. A null POST-submit head (or one that
+// differs from the pre-submit head) is recorded as the uncertainty sentinel so a
+// push-during-review still blocks a same-verdict duplicate for the lag window.
+export type HeadShaResolver = (target: { workspace: string; prNumber: number }) => Promise<string | null>
+
 export type ApproveBlock = { block: true; reason: string }
 
 export type ReviewVerdictGuard = {
@@ -18,7 +32,7 @@ export type ReviewVerdictGuard = {
     prNumber: number
     verdict: ReviewVerdict
   }) => Promise<ApproveBlock | null>
-  release: (args: { callId: string; succeeded: boolean }) => void
+  release: (args: { callId: string; succeeded: boolean }) => Promise<void>
 }
 
 // Back-compat alias: the guard now covers REQUEST_CHANGES too, not just APPROVE.
@@ -55,7 +69,32 @@ function duplicatesStanding(verdict: ReviewVerdict, effective: EffectiveVerdict)
 // never strand a PR for long.
 const LEASE_TTL_MS = 5 * 60_000
 
-type Reservation = { key: string; token: number; createdAt: number }
+// How long a just-landed verdict is trusted to explain a GitHub `NONE` as
+// read-after-write lag rather than a genuine absence. GitHub's `/pulls/<n>/reviews`
+// list lags a write by up to ~10s, so a second engagement turn firing in that
+// window reads NONE and would land a duplicate. Observed duplicates were ~10-18s
+// apart; 60s is a comfortable lag margin without making a legitimate re-verdict
+// wait long. This window only shadows a raw NONE on the SAME verdict (+ same or
+// uncertain head) — a DISMISSED/CHANGES_REQUESTED/flipped-verdict all bypass it.
+const RECENT_LANDED_TTL_MS = 60_000
+
+type Reservation = {
+  key: string
+  token: number
+  createdAt: number
+  headSha: string | null
+  verdict: ReviewVerdict
+  workspace: string
+  prNumber: number
+}
+
+// headSha === null is the UNCERTAINTY sentinel: the command succeeded but the head
+// the review actually attached to is unknown (the PR head advanced between the
+// pre-submit capture and the write, or the post-submit re-resolve failed). A null
+// record matches any current head for the window — same verdict + raw NONE only —
+// so a push-during-review cannot let a same-verdict duplicate slip past on the new
+// head. A resolved string keys precise same-head matching for the normal case.
+type LandedVerdict = { verdict: ReviewVerdict; headSha: string | null; landedAt: number }
 
 // MODULE-LEVEL singletons, shared by every plugin instance in this process. The
 // github-cli-auth plugin's `plugin: async (ctx) => ...` factory may run once per
@@ -65,10 +104,11 @@ type Reservation = { key: string; token: number; createdAt: number }
 // three sessions each landed an APPROVE on the same PR within ten seconds.
 const inFlightByPr = new Map<string, Reservation>()
 const reservationByCall = new Map<string, Reservation>()
+const recentLandedByPr = new Map<string, LandedVerdict>()
 let tokenSeq = 0
 
 // Makes a formal `gh ... event=APPROVE|REQUEST_CHANGES` idempotent per PR across
-// turns, sessions, and (in-process) concurrent fan-out. Two layers:
+// turns, sessions, and (in-process) concurrent fan-out. Three layers, in order:
 //
 //   1. A process-wide in-flight lease keyed by `workspace#prNumber`, held from
 //      tool.before through tool.after. While one verdict is mid-flight, every
@@ -77,12 +117,25 @@ let tokenSeq = 0
 //      closure-local Set could not provide: separate plugin instances meant
 //      separate Sets, so concurrent sessions never saw each other.
 //
-//   2. The authoritative GitHub effective-state read, consulted AFTER the lease
-//      is acquired. It catches the cross-restart case (lease lost) and tracks
-//      supersession: a later CHANGES_REQUESTED/DISMISSED demotes an earlier
-//      APPROVED, so a genuine re-verdict is allowed. Reads fail OPEN — a
-//      transient error must never strand a genuine first verdict; the lease
-//      still covers the concurrent case while the command runs.
+//   2. The authoritative GitHub effective-state read, consulted AFTER the lease.
+//      It is the SOLE source of truth for a standing verdict and for supersession:
+//      a later CHANGES_REQUESTED/DISMISSED demotes an earlier APPROVED, so a
+//      genuine re-verdict is allowed (the 35287f99 invariant — never block a
+//      re-verdict on stale LOCAL memory). A standing same verdict blocks; DISMISSED
+//      and the opposite decisive verdict pass. Reads fail OPEN.
+//
+//   3. A read-after-write-lag shield, consulted ONLY when layer 2 returns a raw
+//      NONE. The lease (layer 1) covers two OVERLAPPING in-flight commands, but a
+//      second engagement turn ~10s later starts after the first's lease released,
+//      and GitHub's reviews list still lags the write (reports NONE). A short-lived
+//      `recentLandedByPr` record — same verdict + (same OR uncertain head), written
+//      on a succeeded release, RECENT_LANDED_TTL_MS — disambiguates "NONE because
+//      lag" from "NONE because genuinely absent": only the former blocks. The head
+//      is re-resolved at release time; if the PR head advanced during the submit the
+//      record stores a null head (uncertainty), which matches the current head so a
+//      push-during-review cannot leak a duplicate. Because it fires after a raw
+//      NONE, a real DISMISSED/CHANGES_REQUESTED already allowed the re-verdict at
+//      layer 2, so this cannot re-strand a supersession.
 //
 // The lease is released only in release() (tool.after) or on a terminal block,
 // never after the remote read — releasing early reopens the TOCTOU the lease
@@ -90,6 +143,7 @@ let tokenSeq = 0
 // tool.after for a superseded reservation cannot drop a newer session's lease.
 export function createApproveIdempotencyGuard(deps: {
   resolveEffectiveApproval: EffectiveApprovalResolver
+  resolveHeadSha?: HeadShaResolver
   now?: () => number
 }): ReviewVerdictGuard {
   const now = deps.now ?? Date.now
@@ -107,10 +161,27 @@ export function createApproveIdempotencyGuard(deps: {
       if (held !== undefined && now() - held.createdAt < LEASE_TTL_MS) {
         return { block: true, reason: CONCURRENT_REASON }
       }
-      const reservation: Reservation = { key, token: ++tokenSeq, createdAt: now() }
+      const reservation: Reservation = {
+        key,
+        token: ++tokenSeq,
+        createdAt: now(),
+        headSha: null,
+        verdict: args.verdict,
+        workspace: args.workspace,
+        prNumber: args.prNumber,
+      }
       inFlightByPr.set(key, reservation)
       reservationByCall.set(args.callId, reservation)
 
+      // Resolve the head SHA only AFTER the lease is held, so this await cannot
+      // widen the reserve-before-await race the lease closes above.
+      const headSha = (await deps.resolveHeadSha?.({ workspace: args.workspace, prNumber: args.prNumber })) ?? null
+      reservation.headSha = headSha
+
+      // Layer 2: GitHub is the authoritative, sole source of truth for a standing
+      // verdict. A standing same verdict is a real duplicate; DISMISSED and the
+      // opposite decisive verdict are genuine supersessions that must pass here
+      // (the 35287f99 invariant). A read error fails OPEN.
       const remote = await deps.resolveEffectiveApproval({ workspace: args.workspace, prNumber: args.prNumber })
       if (remote.ok && duplicatesStanding(args.verdict, remote.effective)) {
         // Standing verdict upstream already matches. Block, and release the lease
@@ -121,17 +192,62 @@ export function createApproveIdempotencyGuard(deps: {
         return { block: true, reason: duplicateReason(args.verdict) }
       }
 
+      // Layer 3: only a raw NONE from a successful read is ambiguous — it can mean
+      // "no review" or "our just-landed review not yet indexed". A recent same
+      // verdict on the same head resolves it to lag and blocks the duplicate. Any
+      // non-NONE state already decided above, so this never overrides a supersession.
+      if (remote.ok && remote.effective === 'NONE' && recentlyLandedSame(key, args.verdict, headSha, now)) {
+        releaseReservation(args.callId, reservation)
+        return { block: true, reason: duplicateReason(args.verdict) }
+      }
+
       return null
     },
 
-    release(args): void {
+    async release(args): Promise<void> {
       const reservation = reservationByCall.get(args.callId)
       if (reservation === undefined) return
-      releaseReservation(args.callId, reservation)
+      try {
+        // The pre-submit head can go stale: if the PR head advanced between the
+        // guard() capture and the review landing, GitHub attaches the review to the
+        // NEWER head while reservation.headSha holds the older one. Re-resolve the
+        // head AFTER a successful submit and store what we can prove: the resolved
+        // head only when pre==post, else the null uncertainty sentinel (matches any
+        // current head for the lag window) so a push-during-review cannot let a
+        // same-verdict duplicate slip past on the new head. The lease stays held
+        // across this await (finally below), so the window is not reopened.
+        if (args.succeeded && reservation.headSha !== null) {
+          const postHeadSha =
+            (await deps.resolveHeadSha?.({ workspace: reservation.workspace, prNumber: reservation.prNumber })) ?? null
+          const landedHeadSha = postHeadSha !== null && postHeadSha === reservation.headSha ? postHeadSha : null
+          recentLandedByPr.set(reservation.key, {
+            verdict: reservation.verdict,
+            headSha: landedHeadSha,
+            landedAt: now(),
+          })
+        }
+      } finally {
+        releaseReservation(args.callId, reservation)
+      }
     },
   }
 }
 
+// True only when a recently-landed record proves the GitHub NONE is read lag: same
+// verdict, within the window, AND the heads agree. Head agreement holds when the
+// stored head equals the current head, OR the stored head is the null uncertainty
+// sentinel (the landed commit could not be pinned, so it conservatively matches the
+// current head for the window). A flipped verdict or an expired/absent record
+// returns false so the genuine re-verdict passes; a different KNOWN head also
+// returns false so a real new push is never blocked.
+function recentlyLandedSame(key: string, verdict: ReviewVerdict, headSha: string | null, now: () => number): boolean {
+  const landed = recentLandedByPr.get(key)
+  if (landed === undefined) return false
+  if (now() - landed.landedAt >= RECENT_LANDED_TTL_MS) return false
+  if (verdict !== landed.verdict) return false
+  return landed.headSha === null || landed.headSha === headSha
+}
+
 // Drop the lease only if THIS reservation still owns the key. A stale tool.after
 // for a reservation that was already superseded (e.g. reclaimed after TTL by a
 // newer session) must not yank the live session's lease.
@@ -151,5 +267,6 @@ function prKey(workspace: string, prNumber: number): string {
 export function __resetReviewVerdictGuardForTest(): void {
   inFlightByPr.clear()
   reservationByCall.clear()
+  recentLandedByPr.clear()
   tokenSeq = 0
 }

package/src/bundled-plugins/github-cli-auth/effective-approval.ts

@@ -1,6 +1,6 @@
 import { GITHUB_API_BASE, githubJsonHeaders } from '@/channels/adapters/github/auth-pat'
 
-import type { EffectiveApprovalResolver, EffectiveVerdict } from './approve-idempotency'
+import type { EffectiveApprovalResolver, EffectiveVerdict, HeadShaResolver } from './approve-idempotency'
 
 // Resolves THIS bot's standing decisive review on a PR, used by the review
 // verdict guard to stop a second formal verdict after a restart (the in-process
@@ -30,9 +30,40 @@ export function createGithubEffectiveApprovalResolver(deps: {
   }
 }
 
+// Reads the PR's current head commit SHA from `GET /pulls/<n>` (`head.sha`), the
+// strongly-consistent single-object endpoint — NOT the eventually-consistent
+// reviews list the duplicate bug rode in on. Returns null on any failure so the
+// landed-verdict cache degrades to verdict-only matching rather than stranding.
+export function createGithubHeadShaResolver(deps: {
+  resolveToken: (workspace: string) => Promise<string | null>
+  fetchImpl?: typeof fetch
+}): HeadShaResolver {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  return async ({ workspace, prNumber }) => {
+    const [owner, repo] = workspace.split('/')
+    if (owner === undefined || owner === '' || repo === undefined || repo === '') return null
+    const token = await deps.resolveToken(workspace).catch(() => null)
+    if (token === null || token === '') return null
+    try {
+      const url = `${GITHUB_API_BASE}/repos/${owner}/${repo}/pulls/${prNumber}`
+      const response = await fetchImpl(url, { headers: githubJsonHeaders(token) })
+      if (!response.ok) return null
+      const raw = (await response.json().catch(() => null)) as { head?: { sha?: unknown } } | null
+      const sha = raw?.head?.sha
+      return typeof sha === 'string' && sha !== '' ? sha : null
+    } catch {
+      return null
+    }
+  }
+}
+
+// DISMISSED is surfaced distinctly (not collapsed to NONE) so the verdict guard's
+// lag shield can tell a genuine dismissal — which legitimately allows a same-verdict
+// re-review — apart from a bare NONE that may just be an unindexed just-landed write.
 function toEffective(state: string | undefined): EffectiveVerdict {
   if (state === 'APPROVED') return 'APPROVED'
   if (state === 'CHANGES_REQUESTED') return 'CHANGES_REQUESTED'
+  if (state === 'DISMISSED') return 'DISMISSED'
   return 'NONE'
 }
 

package/src/bundled-plugins/github-cli-auth/index.ts

@@ -2,7 +2,7 @@ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
 import { definePlugin } from '@/plugin'
 
 import { createApproveIdempotencyGuard } from './approve-idempotency'
-import { createGithubEffectiveApprovalResolver } from './effective-approval'
+import { createGithubEffectiveApprovalResolver, createGithubHeadShaResolver } from './effective-approval'
 import { analyzeGhCommand } from './gh-command'
 import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
 import { commitReviewIfSucceeded, noteReviewCommand } from './review-recorder'
@@ -11,13 +11,13 @@ import { classifyGhToken } from './token-class'
 export default definePlugin({
   plugin: async (ctx) => {
     const resolveTokenForRepo = ctx.github.resolveTokenForRepo
+    const resolveToken = async (workspace: string) => {
+      const result = await resolveTokenForRepo(workspace)
+      return result.kind === 'token' ? result.token : null
+    }
     const verdictGuard = createApproveIdempotencyGuard({
-      resolveEffectiveApproval: createGithubEffectiveApprovalResolver({
-        resolveToken: async (workspace) => {
-          const result = await resolveTokenForRepo(workspace)
-          return result.kind === 'token' ? result.token : null
-        },
-      }),
+      resolveEffectiveApproval: createGithubEffectiveApprovalResolver({ resolveToken }),
+      resolveHeadSha: createGithubHeadShaResolver({ resolveToken }),
     })
     return {
       hooks: {
@@ -70,7 +70,7 @@ export default definePlugin({
             callId: event.callId,
             result: event.result,
           })
-          verdictGuard.release({ callId: event.callId, succeeded: committed })
+          await verdictGuard.release({ callId: event.callId, succeeded: committed })
         },
       },
     }

package/src/bundled-plugins/researcher/write-report.ts

@@ -75,12 +75,14 @@ Write to \`public/\` instead of \`workspace/\` when your resolved role lacks \`f
         )
       }
 
-      const [realParent, realWorkspace, realPublic] = await Promise.all([
-        realpath(parent),
-        realpath(workspaceDir),
-        realpath(publicDir),
-      ])
-      if (realParent !== realWorkspace && realParent !== realPublic) {
+      // Resolve ONLY the canonical dir `parent` lexically matched above. `public/`
+      // is optional (created only for guest-readable output), so an unconditional
+      // `realpath('<agent>/public')` throws ENOENT on agents that never made it,
+      // which would reject every valid write to `workspace/`. The symlink-escape
+      // defense is unchanged — the parent actually written to is still canonicalized.
+      const canonicalDir = parent === workspaceDir ? workspaceDir : publicDir
+      const [realParent, realCanonical] = await Promise.all([realpath(parent), realpath(canonicalDir)])
+      if (realParent !== realCanonical) {
         throw new Error(`Report parent directory resolves outside the allowed report directories: ${parent}.`)
       }
 

package/src/bundled-plugins/reviewer/reviewer.ts

@@ -53,12 +53,13 @@ export const REVIEWER_SKILLS: readonly LoadableSkill[] = [
 // src/agent/subagents.ts `timeoutMs`.
 export const REVIEWER_SPAWN_TIMEOUT_MS = 600_000
 
-// TODO(#452): Restrict the reviewer's `bash` to git and a curated set of
-// read-only `gh` subcommands once per-subagent bash allowlist support lands.
-// Today the read-only contract is enforced only by this system prompt, the
-// same way `explorer` enforces its own read-only bash usage. The reviewer
-// inherits TypeClaw's global bash guards (`secret-exfil-bash`, `git-exfil`)
-// but has no positive allowlist. See https://github.com/typeclaw/typeclaw/issues/452.
+// The reviewer's read-only contract is enforced in depth: this system prompt
+// states it, the global bash guards (`secret-exfil-bash`, `git-exfil`) catch
+// exfil, AND `bashPolicy: { kind: 'readonly-reviewer' }` (set on the subagent
+// below) hard-blocks any mutating `bash` command at the wrap site regardless of
+// the spawning role — git commit/push/add, gh pr merge/review/comment, writes
+// outside /tmp, package installs, and shell constructs that defeat static
+// analysis. See `src/agent/reviewer-bash-policy.ts` (issue #452).
 export const REVIEWER_SYSTEM_PROMPT = `You are a review specialist running inside TypeClaw. Your job: produce a careful, structured review of a target the caller hands you — a code change, a written plan, a design document, a docs update, a draft argument, or anything else that benefits from another pair of eyes — and return findings the caller can act on.
 
 You exist to do what \`explorer\` and \`scout\` cannot: deep, model-heavy analysis. Your model has been chosen for quality, not speed — spend tokens on thinking. Read carefully. Cross-check. Form a real opinion.
@@ -70,6 +71,8 @@ You are STRICTLY PROHIBITED from:
 - Pushing, merging, rebasing, or otherwise mutating remote state
 - Using bash for: mkdir, touch, rm, cp, mv, git add, git commit, git push, git rebase, git reset, npm install, pip install, or any write operation
 
+The boundary that matters is **no side effects on the reviewed artifact, remote state, or the persistent workspace** — not "no byte may touch local disk". A loaded domain skill may carve out one narrow, explicit exception: writing into a fresh throwaway scratch directory under \`/tmp\` purely to *acquire* a read target (e.g. cloning a PR head you cannot otherwise read at line accuracy). That scratch cache is never the reviewed artifact; inside it you still only read, and everything in the prohibition list above still applies everywhere else. Absent such an instruction from your loaded skill, treat the list as absolute.
+
 Your role is EXCLUSIVELY to analyze and report. The parent agent decides what to do with your findings. Delegating part of that analysis is fine; performing side effects through a delegate is NOT — anything you cannot do directly, a subagent you spawn cannot do for you.
 
 ## Delegating to keep your context lean
@@ -89,7 +92,7 @@ The runtime exposes these tools to you by these EXACT names — call them by nam
 - \`grep\` — search file contents by text or regex
 - \`find\` — locate files by name pattern
 - \`ls\` — list a directory's immediate contents
-- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate.
+- \`bash\` — read-only commands ONLY. Read-only \`git\` (\`git log\`, \`git diff\`, \`git show\`, \`git blame\`, \`git status\`, \`git grep\`, \`git rev-parse\`, \`git ls-files\`, \`git cat-file\`) and one-shot pipelines that do not mutate state (\`cat\`, \`head\`, \`tail\`, \`wc\`, \`sort\`, \`uniq\`, \`jq\`). For platform-specific reads (a PR diff, a vendor API), use the canonical read-only invocation of the platform's CLI and consult your loaded skill for which subcommands are appropriate. The ONE write a loaded skill may direct you to make is cloning a target into a fresh \`/tmp\` scratch directory purely to read it (\`git clone\`/\`fetch\`/detached \`checkout\` into \`/tmp/review-*\`); that scratch cache is never the reviewed artifact, and everything else above stays read-only.
 - \`web_search\` — search the public web (e.g. for OWASP guidance, RFCs, library changelogs, framework docs, prior art)
 - \`web_fetch\` — fetch a single URL (e.g. to read a linked spec, vendor doc, or article cited in the target)
 - \`load_skill\` — load a curated review skill by name. See the section below.
@@ -192,6 +195,10 @@ If none of the listed skills fit the target, load \`general\`. Keep the skill-se
     // user has not configured `models.deep` in typeclaw.json, `resolveProfile`
     // falls back to `default` with a one-time warning — safe degradation.
     profile: 'deep',
+    // Hard-fence the reviewer's bash to read-only commands at the wrap site,
+    // independent of the spawning role. The prompt + global guards are the other
+    // two layers; this is the one that survives a trusted/owner caller.
+    bashPolicy: { kind: 'readonly-reviewer' },
     tools: [readTool, grepTool, findTool, lsTool, bashTool, webSearchTool, webFetchTool],
     customTools: [loadSkillTool],
     payloadSchema: reviewerPayloadSchema,

package/src/bundled-plugins/reviewer/skills/code-review.ts

@@ -13,12 +13,39 @@ You have been asked to review code. Apply this guidance on top of the reviewer's
 
 - **PR URL or number** — fetch the diff and the description:
   - \`gh pr diff <n>\` for the unified diff
-  - \`gh pr view <n>\` for title, body, labels, linked issues, checks
+  - \`gh pr view <n> --json title,body,baseRefName,headRefOid,files\` for title, body, linked issues, the head SHA, and the changed-file list
   - \`gh api /repos/<owner>/<repo>/pulls/<n>\` for the structured payload when you need machine-readable fields
 - **Commit SHA** — \`git show <sha>\` and \`git show <sha> --stat\` for the scope.
 - **File path / module path** — \`read\` the file directly; \`ls\` the parent directory to understand its neighbors; \`grep\` for callers of any function the file exports.
 - **Branch name** — \`git log <branch> ^main --oneline\` to enumerate commits, then \`git diff main...<branch>\` for the cumulative change.
 
+### Your cwd is NOT the PR's repo — read at the head SHA
+
+You run in the agent folder (\`/agent\`), **not** a checkout of the PR's target repository. A bare \`read /agent/src/...\` for a file that lives in the PR's repo will fail with \`ENOENT\` — the file is not on this disk. **When \`read\` returns \`ENOENT\` for a path you expected to exist, stop retrying local reads immediately**: that is the signal you are outside the target checkout, not a transient miss. Switch to one of the two acquisition modes below. Do not burn turns re-issuing \`read\` against \`/agent\` paths that will never resolve.
+
+Whichever mode you use, **every line number you cite must come from the PR's head SHA** (\`headRefOid\` from \`gh pr view\`), not the default branch — inline comments anchor to that exact revision.
+
+**Mode 1 — remote-read (default, for a handful of files).** When you need only a few adjacent files, fetch each **once** at the head SHA. Prefer \`gh api\` over \`raw.githubusercontent.com\`: \`gh api\` carries the adapter's GitHub auth, so it works on private repos too.
+
+A repo-targeting \`gh\` command MUST be a **single bare \`gh\` invocation** — no pipes, \`&&\`, \`;\`, or redirects. The runtime injects the GitHub App token into the command's environment, so any sibling stage in a pipeline would inherit a live token; the guard blocks those shapes (the same rule the GitHub channel skill enforces for review posting). So do NOT pipe \`gh api ... | base64 -d | nl -ba\` — that exact shape is rejected before it runs. Instead fetch the **already-decoded** file with the raw media type in one bare call:
+
+\`\`\`sh
+gh api "/repos/<owner>/<repo>/contents/<path>?ref=<headSha>" -H "Accept: application/vnd.github.raw"
+\`\`\`
+
+That returns the file's raw bytes (no base64, no second stage). For the line numbers your \`location="path:line"\` anchors need, read them off the unified diff you already fetched (\`gh pr diff\` prints the new-side line numbers in its hunk headers, \`@@ -a,b +c,d @@\`), or escalate to Mode 2 where a real \`read\`/\`grep\` gives native line numbers. Fetch each file once and keep its output — do not re-fetch the same file to re-derive a line you already saw.
+
+**Mode 2 — scratch checkout (escalate when navigation gets broad).** When the review needs repo-wide \`grep\`, symbol tracing across several directories, many adjacent files, or repeated access to the same files, the remote-read dance is slower and more error-prone than a real checkout. In that case clone the PR head into a **fresh throwaway directory under \`/tmp\`** and read it natively:
+
+\`\`\`sh
+git clone --depth 1 "https://github.com/<owner>/<repo>.git" /tmp/review-<n>-src && \
+  git -C /tmp/review-<n>-src fetch --depth 1 origin <headSha> && git -C /tmp/review-<n>-src checkout <headSha>
+\`\`\`
+
+Then \`read\`, \`grep\`, \`find\`, and read-only \`git\` (\`git -C /tmp/review-<n>-src log|diff|show|blame|grep|ls-files|cat-file\`) all work against \`/tmp/review-<n>-src\` with correct line numbers and zero per-file round-trips.
+
+This \`/tmp\` scratch checkout is the **one** write the read-only contract permits — and only because it is a private acquisition cache, never the reviewed artifact. Inside it you may only **read**. You still may NOT: edit any file, install dependencies, run builds or tests, commit/stage/push/rebase/reset, or write anywhere outside this \`/tmp\` scratch dir. Do not \`rm\` it when done — leave cleanup to the session lifecycle (\`rm\` stays forbidden). When in doubt about how many files you'll touch, start with Mode 1 and escalate to Mode 2 only once the file count or grep breadth justifies the clone.
+
 ## How to build context
 
 A finding without context is noise. Before forming findings:
@@ -72,6 +99,8 @@ This includes payloads where the parent says the author **addressed your prior b
 
 - Return **approve** if the blockers that drove the prior \`request-changes\` are resolved (leftover nits do not block — \`approve\` with inline nits is correct).
 - Return **request-changes** if any blocker remains or a new one appeared.
+
+**Account for resolved threads in the \`<summary>\`, not as \`praise\` findings.** A re-review tempts you to emit one \`praise\` finding per prior concern the author fixed — "Thread 123 is addressed", "Thread 456 is addressed". Do **not**. \`praise\` is reserved for *non-obvious good work*, and a routine "you fixed what I asked" is neither non-obvious nor a finding the parent should post inline (it strips \`praise\` from inline comments anyway, so these become dead weight). Instead, state the resolution accounting in one sentence in your \`<summary>\` — e.g. "Both prior blockers (the unfenced table scan and the backtick-wrap span) are resolved at head \`<sha>\`; one new concern below." Reserve actual \`<finding>\` entries for what still needs action: a prior blocker that is **only partially** fixed (\`blocker\`/\`concern\`, anchored to the line that's still wrong), a **regression the fix introduced** (\`blocker\`/\`concern\`), or a genuinely non-obvious fix worth a rare \`praise\`. A clean re-review where everything was addressed is an \`approve\` whose \`<summary>\` says so and whose \`<findings>\` is empty — not a wall of \`praise\` receipts.
 - **Do NOT return \`comment\` on a re-review.** \`comment\` is for ambiguous partial reviews with no accept/reject signal; a re-review is the opposite — it is precisely an accept/reject decision. A \`comment\` verdict here leaves the PR's \`REQUEST_CHANGES\` state stuck (a plain comment does not clear it on GitHub), which is the exact failure a re-review exists to resolve. The only escape hatch is the same one that always applies: if you genuinely cannot reach the diff or the prior context, return one \`blocker\` finding stating what you need and a \`comment\` verdict — but a reachable, reviewable re-review must end in \`approve\` or \`request-changes\`.
 
 ## Line-anchor every finding

package/src/run/index.ts

@@ -375,6 +375,7 @@ export async function startAgent({
         ...(entry.pluginSubagent.toolResultBudget !== undefined
           ? { toolResultBudget: entry.pluginSubagent.toolResultBudget }
           : {}),
+        ...(entry.pluginSubagent.bashPolicy !== undefined ? { bashPolicy: entry.pluginSubagent.bashPolicy } : {}),
         ...runtimeVersionOpt,
       })
       liveSessionRegistry.register({ sessionId, session: created.session })

package/src/skills/typeclaw-markdown-pdf/SKILL.md

@@ -108,7 +108,7 @@ fonts/margins only if the user asks.
     #counter(page).display("1 / 1", both: true)
   ]),
 )
-#set text(font: ("Libertinus Serif", "New Computer Modern"), size: 11pt, lang: "en")
+#set text(font: ("Libertinus Serif", "New Computer Modern", "Noto Serif CJK KR"), size: 11pt, lang: "en")
 #set par(justify: true, leading: 0.68em, spacing: 1.1em)
 
 #show heading: set text(weight: "semibold")
@@ -136,9 +136,15 @@ Notes:
 - `read("report.md")` is **relative to the workspace** (the compiler's `workspace`
   is set to `workspace/` — see Step 3). Keep the `.typ` and `.md` in `workspace/`.
 - Fonts `Libertinus Serif` / `New Computer Modern` are bundled with Typst (no font
-  install). For Korean/CJK body text, add `"Noto Serif CJK KR"` to the `font:` list
-  and pass that font dir to `fontPaths` in Step 3 (the container's `cjkFonts` toggle
-  installs `fonts-noto-cjk` under `/usr/share/fonts`).
+  install) and carry the Latin text. `"Noto Serif CJK KR"` is appended as the
+  fallback so Korean/CJK glyphs resolve per-glyph — Typst falls through to it
+  wherever the Latin fonts have no glyph, leaving Latin runs untouched. It comes
+  from `fonts-noto-cjk`, which Step 3's renderer loads from `/usr/share/fonts` via
+  `fontPaths`. **The package is only present when the container's `cjkFonts` toggle
+  resolves to `true`.** Its default is `"auto"`, which installs the fonts only when
+  the host locale is CJK (`ja`/`ko`/`zh`) — so on a non-CJK host, CJK PDFs still
+  render as tofu until you set `docker.file.cjkFonts: true` in `typeclaw.json` and
+  rebuild. If your CJK font lives elsewhere, add its dir to the `fontPaths` list.
 
 ## Step 3 — render
 
@@ -149,15 +155,23 @@ writes the PDF. Pass the wrapper and output paths as arguments.
 ```ts
 // workspace/.tools/render.ts
 import { NodeCompiler } from '@myriaddreamin/typst-ts-node-compiler'
-import { writeFileSync } from 'node:fs'
+import { existsSync, writeFileSync } from 'node:fs'
 
 const [, , mainFile, outFile] = process.argv
 if (!mainFile || !outFile) throw new Error('usage: render.ts <main.typ> <out.pdf>')
 
+// Load system fonts so CJK glyphs resolve. The compiler does NOT auto-discover
+// system font dirs the way the Typst CLI does — without explicit fontPaths,
+// "Noto Serif CJK KR" (from fonts-noto-cjk under /usr/share/fonts) is invisible
+// and Korean/Japanese/Chinese text renders as .notdef tofu boxes. Filtered with
+// existsSync so a missing dir (e.g. on a dev/host run) is skipped, not fatal.
+const fontPaths = ['/usr/share/fonts', '/usr/local/share/fonts', '/Library/Fonts', '/System/Library/Fonts'].filter(
+  existsSync,
+)
+
 const compiler = NodeCompiler.create({
   workspace: '.', // run from workspace/, so read("report.md") resolves
-  // Add CJK / extra font dirs here if needed:
-  // fontArgs: [{ fontPaths: ["/usr/share/fonts"] }],
+  ...(fontPaths.length > 0 ? { fontArgs: [{ fontPaths }] } : {}),
 })
 const pdf = compiler.pdf({ mainFilePath: mainFile })
 writeFileSync(outFile, Buffer.from(pdf))