typeclaw 0.32.0 → 0.33.0

package/package.json

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

package/scripts/verify-procbind-sandbox.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Manual acceptance check for the default 'proc-bind' sandbox strategy
+# (src/sandbox/build.ts). Not a unit test: it needs a Linux container with bwrap,
+# which the macOS dev host cannot provide, so it lives here as an operator-
+# runnable script instead of a skipIf-everywhere test.
+#
+# The point of proc-bind is that it needs NEITHER `unshare --mount-proc` NOR
+# CAP_SYS_ADMIN — so this runs WITHOUT --cap-add (unlike verify-realproc-sandbox).
+# It proves two properties of `bwrap --unshare-all … --ro-bind /proc /proc`:
+#   1. An external package runner (bunx) runs to completion (no Bun "NotDir").
+#   2. A secret in a sibling process's environment is UNREADABLE from the sandbox
+#      (the --unshare-all child userns blocks cross-userns /proc/<pid>/environ).
+# The signal boundary (kill/ptrace fail EPERM across the userns) is a corollary
+# of the same userns isolation property (2) proves, so it is not re-tested here.
+#
+# Usage: scripts/verify-procbind-sandbox.sh [image]
+#   image defaults to ghcr.io/typeclaw/typeclaw-base:<version-from-package.json>
+set -euo pipefail
+
+IMAGE="${1:-}"
+if [ -z "$IMAGE" ]; then
+  version="$(node -p "require('./package.json').version" 2>/dev/null || echo latest)"
+  IMAGE="ghcr.io/typeclaw/typeclaw-base:${version}"
+fi
+
+secret="TYPECLAW_PROCBIND_LEAK_CANARY_$$"
+
+inner='
+echo "=== bunx via proc-bind sandbox (no CAP_SYS_ADMIN) ==="
+bunx cowsay "proc-bind ok" 2>&1 | tail -6
+echo "bunx exit=$?"
+echo "=== leak scan (sandbox must NOT read the canary holders env) ==="
+found=0
+for f in /proc/[0-9]*/environ; do
+  if tr "\0" "\n" < "$f" 2>/dev/null | grep -q "CANARY_TOKEN"; then
+    echo "LEAK:$f"; found=1
+  fi
+done
+if [ $found -eq 0 ]; then echo "NO_LEAK_CONFIRMED"; else echo "LEAK_DETECTED"; exit 1; fi
+echo "=== self /proc must be usable (the property that makes bunx work) ==="
+test -r /proc/self/fd && test -r /proc/self/maps && echo "SELF_PROC_OK" || { echo "SELF_PROC_MISSING"; exit 1; }
+'
+inner="${inner//CANARY_TOKEN/$secret}"
+
+# The proc-bind argv shape mirrors buildArgv() in src/sandbox/build.ts. Keep in
+# sync if that helper changes. Note: NO `unshare` prefix and NO --cap-add below.
+runner="
+env CANARY=${secret} sleep 120 &
+bwrap --unshare-all \
+      --new-session --die-with-parent --clearenv \
+      --setenv PATH /usr/local/bin:/usr/bin:/bin --setenv HOME /tmp --setenv LANG C.UTF-8 \
+      --ro-bind /usr /usr --ro-bind /etc /etc --dev /dev --tmpfs /tmp \
+      --ro-bind-try /bin /bin --ro-bind-try /sbin /sbin --ro-bind-try /lib /lib --ro-bind-try /lib64 /lib64 \
+      --share-net \
+      --ro-bind /proc /proc \
+      bash -c '$inner'
+"
+
+echo "Image: $IMAGE"
+docker run --rm --security-opt seccomp=unconfined \
+  -e "CANARY=${secret}" "$IMAGE" bash -c "$runner"

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

@@ -89,8 +89,10 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
     name: 'look_at_channel_attachment',
     label: 'Look at channel attachment',
     description:
-      'View an image attached to the current inbound channel message. Inbound messages show ' +
-      '`[<Platform> attachment #N: <kind> <metadata>]`; pass `N` as `attachment_id`. Do not invent ids.',
+      'View an image attached to a channel message. Inbound messages show ' +
+      '`[<Platform> attachment #N: <kind> <metadata>]`; pass `N` as `attachment_id`. Do not invent ids. ' +
+      'Images on the CURRENT inbound resolve directly; for one from an EARLIER message, call channel_history ' +
+      'first to make it resolvable by the same id.',
     parameters: Type.Object({
       attachment_id: Type.Integer({
         description: 'The number N from the inbound `[<Platform> attachment #N: ...]` placeholder.',
@@ -106,10 +108,10 @@ export function createChannelLookAtTool(router: ChannelRouter, origin: ChannelLo
         const validIds = router.listInboundAttachmentIds(origin)
         const validMsg =
           validIds.length === 0
-            ? 'no attachments are present in the current turn'
-            : `valid attachment_ids in this turn: ${validIds.join(', ')}`
+            ? 'no attachments are resolvable right now'
+            : `resolvable attachment_ids: ${validIds.join(', ')}`
         return errorResult(
-          `no attachment with id=${params.attachment_id} in this turn (${validMsg}). Do not call look_at_channel_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+          `no attachment with id=${params.attachment_id} (${validMsg}). For an attachment from an earlier message, call channel_history first to make it resolvable; otherwise do not invent ids that are not in the inbound message.`,
           { count: 0, prompt: params.prompt },
         )
       }

package/src/agent/plugin-tools.ts

@@ -37,6 +37,8 @@ import type {
 } from '@/plugin'
 import {
   buildSandboxedCommand,
+  canBindProcSafely,
+  canMountRealProc,
   ensureBwrapAvailable,
   ensureSessionTmpDir,
   mapVirtualTmpPath,
@@ -44,6 +46,7 @@ import {
   resolveProcSelfExe,
   resolveProtectedZones,
   resolveWritableZones,
+  type SandboxProcStrategy,
   subtractMasked,
 } from '@/sandbox'
 
@@ -599,17 +602,7 @@ async function applyBashSandbox(
   // 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).
-  // 'real-proc' gives a sandboxed JS package runner a working /proc/self/{fd,
-  // maps} so `bunx`/`bun add`/`bun run <pkg>` stop aborting with Bun's NotDir.
-  // Opt-in (default 'tmpfs') because it makes start.ts grant the container
-  // CAP_SYS_ADMIN at boot. Read from the boot-time `config` snapshot, NOT live
-  // getConfig(): sandbox.realProc is restart-required, and the strategy MUST
-  // track the boot-time capability. A `typeclaw reload` that flips realProc to
-  // true would otherwise make this emit `unshare --mount-proc` in a container
-  // booted WITHOUT CAP_SYS_ADMIN, so the mount fails instead of the old tmpfs
-  // strategy holding until restart. `config` never changes on reload.
-  // procSelfExe is only consumed by the 'tmpfs' branch.
-  const realProc = config.sandbox.realProc
+  const proc = await resolveProcStrategy()
   const { commandString } = buildSandboxedCommand(command, {
     mounts: [
       { type: 'ro-bind', source: agentDir, dest: agentDir },
@@ -620,13 +613,55 @@ async function applyBashSandbox(
     protected: protectedZones,
     network: 'inherit',
     cwd: agentDir,
-    proc: realProc ? 'real-proc' : 'tmpfs',
+    proc,
     procSelfExe: resolveProcSelfExe(),
     ...(envOverlay !== undefined ? { env: { set: envOverlay } } : {}),
   })
   mutableArgs.command = commandString
 }
 
+// Picks the /proc strategy for a sandboxed bash call. The branch order is:
+// 'real-proc' ONLY when the operator explicitly opted in (sandbox.realProc) AND
+// the kernel permits the mount (canMountRealProc) — it adds PID isolation but
+// needs CAP_SYS_ADMIN (unshare --mount-proc), so it is a deliberate, narrow
+// opt-in; else 'proc-bind' (--ro-bind /proc, NO CAP_SYS_ADMIN) when its userns
+// leak-block is verified safe (canBindProcSafely); else 'tmpfs'. Because
+// sandbox.realProc DEFAULTS FALSE, the first branch is normally skipped and
+// proc-bind is the de-facto default — which is the point: the common path needs
+// no broad outer capability. 'tmpfs' is the last-resort degraded mode where
+// external packages can't run; reached only when BOTH probes fail (e.g. a kernel
+// that would leak cross-userns environ — proc-bind fails closed there).
+//
+// Read from the boot-time `config` snapshot, NOT live getConfig(): sandbox is
+// restart-required, and the strategy MUST track the boot-time CAP_SYS_ADMIN
+// grant. A `typeclaw reload` flipping realProc would otherwise emit `unshare
+// --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
+// probes are cached process-globally, so this resolves to one spawn per
+// container lifetime regardless of how many bash calls hit it.
+async function resolveProcStrategy(): Promise<SandboxProcStrategy> {
+  if (config.sandbox.realProc && (await canMountRealProc())) return 'real-proc'
+  if (await canBindProcSafely()) return 'proc-bind'
+  // Degraded last resort: no working /proc strategy. External package runners
+  // (bunx/bun add/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
+  // /proc/self/{fd,maps} are absent. Warn once so an operator on such an exotic
+  // host (no usable user namespaces at all) gets a diagnostic instead of the bare
+  // Bun error. Not gated on parsing the command — that heuristic is fragile (see
+  // PR #696); this is a strategy-level notice, fail-closed and command-agnostic.
+  warnTmpfsProcFallbackOnce()
+  return 'tmpfs'
+}
+
+let tmpfsProcFallbackWarned = false
+function warnTmpfsProcFallbackOnce(): void {
+  if (tmpfsProcFallbackWarned) return
+  tmpfsProcFallbackWarned = true
+  console.warn(
+    '[sandbox] degraded /proc mode: neither real-proc nor proc-bind is available on this host, ' +
+      'so sandboxed external package runners (bunx / bun add / bun run <pkg-bin>) will fail. ' +
+      'This needs a runtime with working user namespaces.',
+  )
+}
+
 // 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

package/src/agent/session-origin.ts

@@ -528,15 +528,21 @@ function renderMembershipSummary(
 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.',
+    `**Ship reports as a PDF by default.** ${platformInfo.displayName} accepts file`,
+    'attachments. When the user asks for a report, document, brief, or "the report"',
+    '— or a `researcher` subagent hands you a `research-<slug>.md` 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 `researcher` `<summary>`',
+    'is a teaser, NOT the deliverable: the deliverable is the report file rendered to',
+    'PDF. Never build the PDF with an ad-hoc library (jsPDF, pdfkit, a raw-text dump) —',
+    'that yields unrendered markdown and mojibake; the skill is the only correct path.',
+    "For CJK (Korean/Japanese/Chinese) reports, follow that skill's CJK font gate —",
+    'never ship a tofu-rendered PDF; ask before enabling the opt-in `cjkFonts`.',
+    'A downloadable file is what a human wants for a multi-page report; do not paste',
+    'the full markdown into chat, and do not attach the raw `.md` when asked for a',
+    'report or PDF. Send inline plain text only if the caller explicitly asked for it,',
+    'or the content is short enough that a file would be overkill.',
     '',
   ]
 }

package/src/agent/system-prompt.ts

@@ -59,6 +59,12 @@ For any multi-step or long-running task, maintain a todo list with \`todo_write\
 
 Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
 
+## Delivering reports and documents
+
+When the user asks for a *report*, *document*, *brief*, *PDF*, or asks you to *send/show/attach/export* a generated result — anything where the deliverable is a file a human would download, print, or forward — produce a polished file, not a wall of text pasted into chat and not a one-line summary that drops the substance. A summary (yours or a subagent's) is a pointer to the deliverable, never the deliverable itself; when the user asked for the report, ship the report.
+
+To turn Markdown into a PDF, use the bundled \`typeclaw-markdown-pdf\` skill — it is the only supported path and it renders Markdown properly (headings, lists, tables). **Never** hand-roll a PDF with an ad-hoc library (jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print): those produce unrendered raw \`##\`/\`**\` markup and mojibake for non-Latin text. CJK fonts are opt-in, so for Korean/Japanese/Chinese reports follow that skill's CJK gate — never ship a tofu-rendered PDF; ask before enabling opt-in CJK fonts. If a request is plainly satisfied by inline chat — a short answer, a snippet, a quick explanation — stay inline; this rule is for explicit document deliverables, not for every long reply.
+
 ## Long-running and interactive shell work
 
 Foreground \`bash\` blocks your turn until exit, so a command that runs for minutes or waits for input (dev server, REPL, watcher, \`docker compose up\`, interactive installer) freezes the conversation. \`tmux\` is in the container — run such programs detached so your turn stays free:

package/src/agent/tools/channel-fetch-attachment.ts

@@ -37,11 +37,12 @@ export function createChannelFetchAttachmentTool({
     name: 'channel_fetch_attachment',
     label: 'Channel Fetch Attachment',
     description:
-      'Download a file the user attached to the current inbound channel message and save it to disk. Inbound channel ' +
+      'Download a file attached to a channel message and save it to disk. Inbound channel ' +
       'messages with attachments show `[<Platform> attachment #N: <kind> <metadata>]` in the text. Pass `N` as ' +
-      '`attachment_id`; do not invent ids that are not present in the inbound message. The router validates the id ' +
-      'against the current turn and resolves the private platform ref itself. On success returns the absolute path ' +
-      'of the saved file plus its detected mimetype and size.',
+      '`attachment_id`; do not invent ids that are not present in the message. The router resolves the private ' +
+      'platform ref itself. Attachments on the CURRENT inbound message resolve directly; for one from an EARLIER ' +
+      'message, call channel_history first (it makes those attachments resolvable by the same id). On success ' +
+      'returns the absolute path of the saved file plus its detected mimetype and size.',
     parameters: Type.Object({
       attachment_id: Type.Integer({
         description:
@@ -75,10 +76,10 @@ export function createChannelFetchAttachmentTool({
         })
         const validMsg =
           validIds.length === 0
-            ? 'no attachments are present in the current turn'
-            : `valid attachment_ids in this turn: ${validIds.join(', ')}`
+            ? 'no attachments are resolvable right now'
+            : `resolvable attachment_ids: ${validIds.join(', ')}`
         return errorResult(
-          `no attachment with id=${params.attachment_id} in this turn (${validMsg}). Do not call channel_fetch_attachment for attachments that do not appear in the inbound message — they do not exist.`,
+          `no attachment with id=${params.attachment_id} (${validMsg}). For an attachment from an earlier message, call channel_history first to make it resolvable; otherwise do not invent ids that are not in the inbound message.`,
         )
       }
       if (found.ref === '') {

package/src/agent/tools/channel-history.ts

@@ -94,6 +94,8 @@ export function createChannelHistoryTool({
         }
       }
 
+      router.registerHistoryAttachments(origin, result.messages)
+
       const rendered = renderMessages(result.messages)
       const cursorLine =
         result.nextCursor !== undefined

package/src/bundled-plugins/github-cli-auth/gh-command.ts

@@ -37,12 +37,14 @@ type GhSegmentDecision =
 
 const COMPOSITION_REASON =
   'A repo-targeting `gh` command receives a minted GitHub App token in its process ' +
-  'environment, so it must run as a single bare `gh` command — no pipes, `;`, `&&`, ' +
-  '`||`, `&`, newlines, redirections, command/process substitution, subshells, heredocs, ' +
-  'or unquoted `$` expansion (any sibling process or expansion would inherit the token ' +
-  'and could exfiltrate it). jq/JSON metacharacters are fine INSIDE single quotes, e.g. ' +
-  "`gh api repos/o/r --jq '.[] | {id}'`. To feed JSON to `gh api`, write it to a temp " +
-  'file and use `gh api --input <file>`.'
+  'environment, so it must run as a single bare `gh` command — no `;`, `&&`, `||`, `&`, ' +
+  'newlines, redirections, command/process substitution, subshells, heredocs, or unquoted ' +
+  '`$` expansion (any sibling process or expansion would inherit the token and could ' +
+  'exfiltrate it). One exception is allowed: a trailing reader pipeline `gh … | <reader>` ' +
+  'where every downstream stage is a stdin-only reader (`jq`, `cat`, `wc`, `sort`, `uniq`) ' +
+  'with no file operand — e.g. `gh api repos/o/r | jq .`. jq/JSON metacharacters are also ' +
+  "fine INSIDE single quotes, e.g. `gh api repos/o/r --jq '.[] | {id}'`. To feed JSON to " +
+  '`gh api`, write it to a temp file and use `gh api --input <file>`.'
 
 // Shell-active metacharacters that, OUTSIDE single quotes, either spawn another
 // process sharing the shell env (where the minted GH_TOKEN lives) or expand
@@ -140,15 +142,267 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   const owners = new Set(repoSlugs.map((slug) => slug.split('/')[0]))
   if (owners.size > 1) return { kind: 'block', reason: MULTI_OWNER_REASON }
 
-  // We would inject a token. Enforce the single-bare-`gh` shape: the token
-  // lands in the shell's env, so any sibling/upstream/downstream process or
-  // shell expansion would inherit it.
-  if (!isSingleBareGhCommand(command)) return { kind: 'block', reason: COMPOSITION_REASON }
+  const repoSlug = repoSlugs[0] as string
 
-  if (stripRepoFlag) {
-    return { kind: 'inject', repoSlug: repoSlugs[0] as string, rewrittenCommand: stripRepoFlagFromCommand(command) }
+  // We would inject a token. The token lands in the shell env, so any sibling/
+  // upstream/downstream process or shell expansion would inherit it. The single-
+  // bare-`gh` shape is the safe baseline; a trailing reader pipeline (`gh | jq`)
+  // is the one exception we allow, under strict conditions (see analyzeReaderPipeline).
+  if (isSingleBareGhCommand(command)) {
+    if (stripRepoFlag) return { kind: 'inject', repoSlug, rewrittenCommand: stripRepoFlagFromCommand(command) }
+    return { kind: 'inject', repoSlug }
   }
-  return { kind: 'inject', repoSlug: repoSlugs[0] as string }
+
+  const piped = analyzeReaderPipeline(command, stripRepoFlag)
+  if (piped !== null) return { kind: 'inject', repoSlug, rewrittenCommand: piped }
+
+  return { kind: 'block', reason: COMPOSITION_REASON }
+}
+
+// stdin-only readers whose only sink is stdout (back to the agent, who already
+// has gh's output) — they cannot open their own network/file/process sink, so a
+// `gh <repo> | <reader>` pipeline cannot exfiltrate the minted token to a third
+// party. EXCLUDED on purpose: awk (system()/getline|cmd/inet), sed (GNU `e`
+// shell-exec), tee/xargs (write/spawn), less (`!cmd`), and grep/head/tail (their
+// file-operand forms are too easy to abuse and not worth the parser risk yet).
+const READER_ALLOWLIST = new Set(['jq', 'cat', 'wc', 'sort', 'uniq'])
+
+// STRICT per-command flag allowlists. We allow ONLY flags known to be pure
+// stdin-shaping (no file/program operand). This is allow-known-good, not
+// deny-known-bad: coreutils exposes file reads AND code execution as FLAGS, not
+// just operands — `wc --files0-from=F` and `sort --files0-from=F` open a file
+// with no positional, and `sort --compress-program=PROG` execs a helper. Any
+// such flag would let a downstream "reader" open `/proc/<pid>/environ` and
+// recover the sibling token. So an unrecognized flag REJECTS the whole stage.
+// jq is excluded here (its filter is a positional, handled separately).
+const READER_BOOLEAN_FLAGS: Record<string, ReadonlySet<string>> = {
+  cat: new Set(['-n', '--number', '-b', '--number-nonblank', '-s', '--squeeze-blank', '-A', '--show-all', '-E', '-T']),
+  wc: new Set(['-l', '--lines', '-c', '--bytes', '-m', '--chars', '-w', '--words', '-L', '--max-line-length']),
+  sort: new Set(['-r', '--reverse', '-n', '--numeric-sort', '-u', '--unique', '-f', '--ignore-case', '-b', '-g', '-h']),
+  uniq: new Set(['-c', '--count', '-d', '--repeated', '-u', '--unique', '-i', '--ignore-case']),
+}
+
+// jq is validated allow-known-good, exactly like the coreutils readers: only
+// known stdin-shaping flags pass; anything else rejects the stage. Exact-token
+// deny-listing was unsound — `-f/proc/self/environ`, `-L/proc`, and clustered
+// `-rf/proc/...` short forms slipped past a `Set.has(token)` check and reopened
+// the file-read path. jq accepts NO `--flag=value` form (value flags take the
+// value as a SEPARATE token), so long flags are matched as whole tokens.
+
+// Safe boolean LONG flags: output/parse shaping only, no value, no file/module.
+const JQ_SAFE_BOOLEAN_LONG = new Set([
+  '--raw-output',
+  '--raw-output0',
+  '--compact-output',
+  '--slurp',
+  '--null-input',
+  '--exit-status',
+  '--ascii-output',
+  '--sort-keys',
+  '--raw-input',
+  '--join-output',
+  '--color-output',
+  '--monochrome-output',
+  '--binary',
+  '--tab',
+  '--unbuffered',
+  '--stream',
+  '--stream-errors',
+  '--seq',
+])
+
+// Safe LONG flags that consume a fixed number of FOLLOWING tokens, none a file:
+// --arg/--argjson take 2 (name, value), --indent takes 1 (a number).
+const JQ_SAFE_VALUE_LONG: Record<string, number> = {
+  '--arg': 2,
+  '--argjson': 2,
+  '--indent': 1,
+}
+
+// Safe boolean SHORT flags (single chars). A clustered short token like `-rc`
+// is allowed iff EVERY char is in this set. `f` (filter-from-file) and `L`
+// (module path) are the fatal ones — and any unknown char also rejects.
+const JQ_SAFE_BOOLEAN_SHORT = new Set(['r', 'c', 's', 'n', 'e', 'a', 'S', 'R', 'j', 'C', 'M', 'b'])
+
+// A reader stage is safe only if it is an allowlisted command using ONLY its
+// known stdin-shaping flags, with no file operand. Backslashes are rejected
+// outright: our tokenizer does not model shell backslash escaping, so a
+// `jq \--from-file=…` would be seen as a harmless positional here but reach bash
+// as the forbidden flag — an allowlist-bypass. Rejecting `\` closes that gap.
+function isStdinOnlyReaderStage(stage: string): boolean {
+  if (containsShellActiveMetachar(stage)) return false
+  if (stage.includes('\\')) return false
+  const tokens = splitStageTokens(stage)
+  const cmd = tokens[0]
+  if (cmd === undefined || !READER_ALLOWLIST.has(cmd)) return false
+
+  if (cmd === 'jq') return isStdinOnlyJqStage(tokens)
+
+  const allowedFlags = READER_BOOLEAN_FLAGS[cmd]
+  if (allowedFlags === undefined) return false
+  for (let i = 1; i < tokens.length; i++) {
+    const tok = tokens[i] as string
+    if (!tok.startsWith('-')) return false
+    if (!allowedFlags.has(tok)) return false
+  }
+  return true
+}
+
+// jq must run pure-stdin: only known stdin-shaping flags, and EXACTLY one
+// positional (the filter). A second positional is an input FILE jq would open
+// (`jq . /proc/self/environ` reads that file), so it is rejected. The filter is
+// additionally screened for `import`/`include`, which load modules from jq's
+// default search path even without `-L` — another file-read vector.
+function isStdinOnlyJqStage(tokens: readonly string[]): boolean {
+  let sawFilter = false
+  for (let i = 1; i < tokens.length; i++) {
+    const tok = tokens[i] as string
+    if (tok === '--') return false
+    if (tok.startsWith('--')) {
+      if (JQ_SAFE_BOOLEAN_LONG.has(tok)) continue
+      const consume = JQ_SAFE_VALUE_LONG[tok]
+      if (consume === undefined) return false
+      i += consume
+      continue
+    }
+    if (tok.startsWith('-') && tok.length > 1) {
+      for (const ch of tok.slice(1)) {
+        if (!JQ_SAFE_BOOLEAN_SHORT.has(ch)) return false
+      }
+      continue
+    }
+    if (sawFilter) return false
+    sawFilter = true
+    if (jqFilterLoadsModules(tok)) return false
+  }
+  return true
+}
+
+// jq `import`/`include` directives pull a module file from the search path, a
+// file-read vector that `-L` rejection alone does not cover (the default path
+// still applies). Match them as leading directives in the untrusted filter.
+function jqFilterLoadsModules(filter: string): boolean {
+  return /(^|[;\s])(import|include)\s/.test(filter)
+}
+
+// Splits a single bare `gh ... | reader | reader` pipeline into its stages on
+// TOP-LEVEL `|` only (quote-aware, so a `|` inside a single-quoted jq filter is
+// not a stage boundary), rewriting each downstream reader to run under
+// `/usr/bin/env -u GH_TOKEN`. Returns the rewritten command, or null if the
+// shape is not a leading-`gh` + allowlisted-stdin-readers pipeline. Absolute
+// `/usr/bin/env` (not bare `env`) so the strip can't be defeated by a PATH-
+// shadowed `env`; a missing binary exits 127, failing closed.
+function analyzeReaderPipeline(command: string, stripRepoFlag: boolean): string | null {
+  const stages = splitTopLevelPipeStages(command)
+  if (stages === null || stages.length < 2) return null
+
+  const ghStage = (stages[0] as string).trim()
+  if (!isSingleBareGhCommand(ghStage)) return null
+
+  for (let i = 1; i < stages.length; i++) {
+    if (!isStdinOnlyReaderStage((stages[i] as string).trim())) return null
+  }
+
+  const rewrittenGh = stripRepoFlag ? stripRepoFlagFromCommand(ghStage) : ghStage
+  const rewrittenReaders = stages.slice(1).map((s) => `/usr/bin/env -u GH_TOKEN ${s.trim()}`)
+  return [rewrittenGh, ...rewrittenReaders].join(' | ')
+}
+
+// Quote-aware split on top-level `|`. Returns null if any OTHER shell-active
+// metachar appears outside single quotes (`;` `&` `<` `>` backtick `$` `(` `)`
+// `{` `}` newline) or if a `||`/`|&` is seen — those are not simple pipelines.
+function splitTopLevelPipeStages(command: string): string[] | null {
+  const stages: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i] as string
+    if (quote === "'") {
+      if (ch === "'") quote = null
+      current += ch
+      continue
+    }
+    if (quote === '"') {
+      if (ch === '$' || ch === '`') return null
+      if (ch === '"') quote = null
+      current += ch
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      current += ch
+      continue
+    }
+    if (ch === '|') {
+      const next = command[i + 1]
+      if (next === '|' || next === '&') return null
+      stages.push(current)
+      current = ''
+      continue
+    }
+    if (SHELL_ACTIVE_METACHARS.has(ch) && ch !== '|') return null
+    current += ch
+  }
+  if (quote !== null) return null
+  stages.push(current)
+  return stages
+}
+
+function containsShellActiveMetachar(stage: string): boolean {
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < stage.length; i++) {
+    const ch = stage[i] as string
+    if (quote === "'") {
+      if (ch === "'") quote = null
+      continue
+    }
+    if (quote === '"') {
+      if (ch === '$' || ch === '`') return true
+      if (ch === '"') quote = null
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      continue
+    }
+    if (SHELL_ACTIVE_METACHARS.has(ch)) return true
+  }
+  return false
+}
+
+// Whitespace-splits a single stage into argv-ish tokens, stripping surrounding
+// quotes so a quoted filter like `'.[] | {id}'` becomes one token. Quote-aware
+// so whitespace inside quotes does not split.
+function splitStageTokens(stage: string): string[] {
+  const tokens: string[] = []
+  let current = ''
+  let has = false
+  let quote: '"' | "'" | null = null
+  for (let i = 0; i < stage.length; i++) {
+    const ch = stage[i] as string
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else current += ch
+      continue
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch
+      has = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      if (has) {
+        tokens.push(current)
+        current = ''
+        has = false
+      }
+      continue
+    }
+    current += ch
+    has = true
+  }
+  if (has) tokens.push(current)
+  return tokens
 }
 
 // Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single

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

@@ -61,13 +61,15 @@ Prioritize in this order:
 
 1. **Correctness.** Does the change do what its description claims? Off-by-one errors, missing null/undefined handling, race conditions, incorrect error propagation, broken invariants.
 2. **Security.** Injection vectors (SQL, shell, HTML), missing authz/authn checks, secret leakage in logs or error messages, unsafe deserialization, SSRF, path traversal, time-of-check-time-of-use. Cite OWASP / CWE / RFC by number when relevant; verify with \`web_search\` or \`web_fetch\` before asserting.
-3. **Architecture fit.** Does the change respect existing layering? Does it introduce a new dependency where the existing pattern would have worked? Does it duplicate logic that already exists elsewhere in the repo?
-4. **Test coverage.** New behavior should have new tests. Edge cases the description names should be tested. If existing tests were deleted or skipped, that is a blocker absent a stated reason. Look past the raw test count, but only flag a redundant case when you can show the *inputs themselves* reach the same path — same branch, same validation rule, same boundary — not merely that the assertion shape is identical. Table-driven and parametrized tests legitimately share one assertion across many inputs while each input exercises a distinct branch, parser, or edge case; that is coverage, not duplication. The finding is "these inputs are indistinguishable to the code under test," and you must name the path they collapse onto — never "the assertions look the same."
-5. **Error handling.** Empty catch blocks, swallowed errors, errors converted to silent fallbacks, retry loops without bounded backoff, missing timeouts on external calls.
-6. **Performance.** Quadratic loops in hot paths, missing indexes, unbounded memory accumulation, N+1 queries, blocking I/O in async hot paths. Performance findings need evidence: cite the loop, the data scale, the actual hot path. "Could be slow" without evidence is not a finding.
-7. **API surface.** Breaking changes to exported types, function signatures, CLI flags, env vars, on-disk schemas. Are they documented? Versioned? Migration noted in CHANGELOG / release notes?
-8. **Naming.** Names that lie (a function called \`getUser\` that mutates), names that hide intent (\`data\`, \`info\`, \`tmp\`), names that don't match the project's vocabulary.
-9. **Change hygiene.** Temporary scaffolding that escaped into the change: \`wip\`/\`fixup!\`/\`squash!\` commits left in the history, debug logging, commented-out code, leftover \`TODO\` markers for work the PR claims to finish. When you flag a stray commit, name the commit it should fold into so the author can squash it — don't just say "this looks temporary".
+3. **Architecture fit and intent drift.** Does the change respect existing layering? Does it introduce a new dependency where the existing pattern would have worked? Does it duplicate logic that already exists elsewhere in the repo? Beyond local fit, check for **intent drift** — the change technically compiles and passes its own tests, but quietly diverges from the design intent the surrounding code was built on: a "temporary" branch that bypasses an established abstraction, a special-case that erodes an invariant the module exists to protect, a layer reaching past its boundary because that was the shortest path. The diff can be locally correct and still pull the system away from the shape the author (or the codebase's own conventions) intended. When the description states an intent — "without changing the public API", "purely a refactor", "no behavior change" — verify the diff actually holds that line; a refactor that alters observable behavior, or an "internal only" change that shifts an exported contract, is drift even if nothing is strictly broken. Anchor the finding to the line where the divergence enters and name the intent it violates.
+4. **Regression risk and blast radius.** A change is rarely self-contained. For every function signature, return shape, exported type, default value, thrown-error type, or side-effecting behavior the diff alters, ask **who depended on the old behavior**. \`grep\` for callers of changed exports; trace the call sites that touch a modified invariant. A contract change that is correct *here* can silently break a caller the diff never shows — that caller is the regression, and it will not appear in the test count for this PR. Removed or loosened validation, a narrowed accepted-input range, a changed enum value, an altered ordering guarantee, a default that flipped: each is a regression vector for existing consumers even when the new code reads fine in isolation. State the blast radius explicitly — which call sites, which inputs, which downstream behavior changes — so the author knows whether this is a \`concern\` or a \`blocker\`. "Looks fine in the diff" is not a regression clearance; the diff is exactly where regressions hide their other half.
+5. **Side effects and ripple.** Watch for effects that reach outside the lines being changed: mutation of shared or global state, a cache that now needs invalidating, an event/log/metric whose shape downstream consumers parse, a config or feature flag whose new value changes behavior elsewhere, a migration that must run in lockstep, a resource (file handle, connection, lock, subscription) opened on a new path and never released. The dangerous side effect is the one whose *consequence* isn't obvious from the changed line alone — a behavior that emerges from the interaction between the changed code and code it touches indirectly. There is still a line that introduces it: anchor the finding to the mutation, lifecycle, or config line where the ripple enters, then name the downstream consumer or shared state that breaks and say what goes wrong when it is not accounted for. If the change touches a shared resource's lifecycle, verify the cleanup path (\`finally\`, \`defer\`, \`using\`, teardown hook) covers the new branch too — a leak introduced on an error path is a side effect that only shows up under load.
+6. **Test coverage.** New behavior should have new tests. Edge cases the description names should be tested. If existing tests were deleted or skipped, that is a blocker absent a stated reason. Look past the raw test count, but only flag a redundant case when you can show the *inputs themselves* reach the same path — same branch, same validation rule, same boundary — not merely that the assertion shape is identical. Table-driven and parametrized tests legitimately share one assertion across many inputs while each input exercises a distinct branch, parser, or edge case; that is coverage, not duplication. The finding is "these inputs are indistinguishable to the code under test," and you must name the path they collapse onto — never "the assertions look the same."
+7. **Error handling.** Empty catch blocks, swallowed errors, errors converted to silent fallbacks, retry loops without bounded backoff, missing timeouts on external calls.
+8. **Performance.** Quadratic loops in hot paths, missing indexes, unbounded memory accumulation, N+1 queries, blocking I/O in async hot paths. Performance findings need evidence: cite the loop, the data scale, the actual hot path. "Could be slow" without evidence is not a finding.
+9. **API surface.** Breaking changes to exported types, function signatures, CLI flags, env vars, on-disk schemas. Are they documented? Versioned? Migration noted in CHANGELOG / release notes?
+10. **Naming.** Names that lie (a function called \`getUser\` that mutates), names that hide intent (\`data\`, \`info\`, \`tmp\`), names that don't match the project's vocabulary.
+11. **Change hygiene.** Temporary scaffolding that escaped into the change: \`wip\`/\`fixup!\`/\`squash!\` commits left in the history, debug logging, commented-out code, leftover \`TODO\` markers for work the PR claims to finish. When you flag a stray commit, name the commit it should fold into so the author can squash it — don't just say "this looks temporary".
 
 ## What NOT to find
 
@@ -80,8 +82,8 @@ Prioritize in this order:
 
 ## Severity hints specific to code
 
-- **blocker** — Correctness bug that will misbehave for users. Security vulnerability. Broken backward compatibility without migration. Crashing path on common input. Deleted tests without justification.
-- **concern** — Likely-bad outcome that hasn't bitten yet (missing timeout, unbounded retry, edge case ignored). Test gap on the new behavior. Architectural deviation that compounds.
+- **blocker** — Correctness bug that will misbehave for users. Security vulnerability. Broken backward compatibility without migration. Crashing path on common input. Deleted tests without justification. A regression that breaks an existing caller you can name, or a side effect (leaked resource, un-invalidated cache, mutated shared state) that corrupts behavior outside the diff.
+- **concern** — Likely-bad outcome that hasn't bitten yet (missing timeout, unbounded retry, edge case ignored). Test gap on the new behavior. Architectural deviation or intent drift that compounds. A plausible regression or side effect whose reach you suspect but cannot fully trace — say what you'd check to confirm, and let the blast radius decide whether it's really a blocker.
 - **nit** — Naming, micro-readability, suboptimal-but-correct code. Optional. The author can decline and you should not push back.
 - **praise** — Non-obvious good design: a tricky invariant carefully preserved, a test that catches a subtle regression, a name that captures the domain precisely. Rare on purpose.