typeclaw 0.20.0 → 0.22.0

package/src/bundled-plugins/bun-hygiene/README.md

@@ -0,0 +1,82 @@
+# typeclaw-plugin-bun-hygiene
+
+The bundled bun-hygiene plugin. Registers a `tool.before` hook that blocks two classes of `bash` command:
+
+1. **Global package installs** — `npm install -g`, `pnpm add -g`, `yarn global add`, `bun add -g`, and their `--global` / bundled-flag variants.
+2. **Non-bun package managers** — any `npm`, `npx`, `pnpm`, `pnpx`, or `yarn` invocation.
+
+This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]` entry to add. Both guards carry an `acknowledgeGuards` escape hatch (below) for the cases where the agent genuinely needs the blocked command.
+
+## Why it exists
+
+**Global installs don't persist.** The agent folder is bind-mounted at `/agent`; everything else in the container — including `~/.bun`, `~/.npm`, and the global `node_modules` a global install writes to — is ephemeral and wiped on every `typeclaw restart`. An agent that runs `npm install -g some-cli` gets a tool that works for the rest of the session and silently vanishes on the next boot, leading to confusing "command not found" failures that look like regressions. The fix is to either add the dependency to `package.json` (`bun add <pkg>`, which lives in the bind-mounted folder and survives) or run it once without installing (`bunx <pkg>`).
+
+**The container standardizes on bun.** TypeClaw is Bun-native end to end (see the root README). Mixing in `npm`/`pnpm`/`yarn` produces competing lockfiles and install trees, and `npx` pulls a second package-execution path when `bunx` already covers it. Steering every package-manager call to bun keeps the dependency state coherent.
+
+Both guards **block with guidance** rather than silently rewriting the command — the agent sees exactly why the command was rejected and what to run instead, the same UX as the bundled `security` and `guard` policies.
+
+## Guards
+
+| Guard                  | Triggers on                                                                                       | Guidance in the block reason                                               |
+| ---------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `globalInstall`        | `npm`/`pnpm` install/add with `-g`/`--global`, `yarn global add`, `bun add -g` / `bun install -g` | Use `bun add <pkg>` (persists) or `bunx <pkg>` (ephemeral run).            |
+| `nonBunPackageManager` | `npm`, `npx`, `pnpm`, `pnpx`, `yarn` at a command boundary                                        | Use `bun install` / `bun add <pkg>`, and `bunx <pkg>` instead of npx/pnpx. |
+
+A global install (e.g. `npm install -g x`) trips **only** `globalInstall`, not both — the global install is the more specific violation, so acknowledging `globalInstall` lets the command through without a second acknowledgement for `nonBunPackageManager`.
+
+## Bypass
+
+Both guards follow the repo-wide `acknowledgeGuards` convention (shared with the `security` and `guard` plugins). To run a blocked command intentionally, pass the matching flag in the `bash` tool arguments:
+
+```jsonc
+// bash tool args
+{ "command": "npm install", "acknowledgeGuards": { "nonBunPackageManager": true } }
+{ "command": "npm install -g some-cli", "acknowledgeGuards": { "globalInstall": true } }
+```
+
+## How it works
+
+`checkBunHygieneGuard` in `policy.ts` does not regex the raw command. It runs a small single-pass tokenizer (`splitSegments`) that turns the command into a list of **segments**, each a list of **words**:
+
+- Segments break on real command separators — `;`, `&&`, `||`, `|`, `&`, newline, `\r` — and on subshell / command-substitution openers (`(`, `$(`, backtick), **including `$(`/backtick inside double quotes** (Bash executes those, e.g. `echo "$(npm install -g x)"`; the outer double-quote mode resumes when the substitution closes so a trailing command isn't swallowed). Single-quoted bodies stay literal, matching Bash.
+- The tokenizer is quote-aware (a separator inside `"..."`/`'...'` is literal) and escape-aware (`\x` is a literal `x`, so `\npm` resolves to `npm` and `\;` is not a separator). A `\<newline>` is a POSIX line continuation — it is removed and the surrounding text joined, so `npm install \⏎-g x` is one command (a global install), while a bare newline separates commands.
+
+For each segment, the guard strips leading **preamble wrappers** (`sudo`, `env`, `command`, `exec`, `nice`, `nohup`, `stdbuf`, `setsid`, `time`, `xargs`, and any `VAR=val` assignment) — including their options, and the argument a flag consumes (`sudo -u nobody`, `nice -n 10`, `env -i`) — to find the real command word, then classifies:
+
+1. command word is `npm`/`npx`/`pnpm`/`pnpx`/`yarn` (or `bun`) **and** the segment has an install subcommand **and** a global flag → `globalInstall` (for `yarn`, the `global add` sequence must appear adjacent and in command position, so `yarn add global foo` — a local install of a package named `global` — is not misflagged);
+2. command word is a non-bun manager (not via global) → `nonBunPackageManager`;
+3. otherwise → allowed.
+
+A `globalInstall` verdict on any segment wins over a plain non-bun verdict. This is a command-position detector, not a full shell parser — it doesn't interpret redirections or expansions beyond boundary marking — but it is linear-time and closes the structural gaps a single regex left open.
+
+## Scope: not a security boundary
+
+This guard is a **hygiene nudge**, not an isolation mechanism. It deliberately does not chase manager invocations hidden inside a wrapper's code payload — `sh -c 'npm install'`, `bash -lc "pnpm add foo"`, `python -c '...os.system("npx tsc")'`, `node -e`, `eval`, `base64 | sh`, etc. That set is unbounded (any interpreter can reach any binary), and inspecting arbitrary `-c`/`-e` payloads is an arms race with diminishing returns and rising false-positive risk. An agent that genuinely wants a package manager can always reach one; the guard's job is to steer the common, direct invocations toward bun and to stop accidental global installs. The real isolation boundary is the per-tool **bwrap sandbox** (see `/docs/internals/sandbox`), not this policy. Optioned preamble _wrappers_ (`env -i`, `sudo -u`, `nice -n`) are handled because they prefix a real command word that the tokenizer can still see; code-payload wrappers are not, by design.
+
+## Why a tokenizer, not a regex
+
+The earlier implementation matched boundary-anchored regexes against an escape/quote-normalized copy of the command. Review surfaced three structural gaps that are awkward to close with one regex but fall out naturally from the segment model:
+
+- **Escaped / quoted command words.** `\npm install`, `"npm" install`, `'npm' install`, `n\px …` all run the real binary; the tokenizer collapses escapes and quotes at the word level, so each resolves to its bare command word.
+- **Leading assignments.** `FOO=bar npm install` runs npm with `FOO` set. Stripping `VAR=val` (and `sudo`/`env`/`command`/`exec`/`nice`) preamble words finds the manager behind them.
+- **Newline = separate command.** `npm install\n-g typescript` is two commands; the `-g` does not make the install global. Per-segment scoping means a flag in one segment never combines with an install in another, so this classifies as `nonBunPackageManager` (the `npm install` line), not `globalInstall`.
+
+It also recognizes an explicit falsy global flag (`--global=false|0|no|off`) as **not** a global install, and detects managers inside subshells / command substitutions.
+
+## Option placement in global installs
+
+Because classification scans a segment's words as a set (after preamble stripping), options may sit anywhere relative to the subcommand and the global flag, in either order: `npm --prefix /tmp install -g x`, `npm install --foo bar -g x`, `npm -g install x`, `pnpm add --reporter silent -g foo`, and `bun --cwd /x add -g foo` all attribute to `globalInstall`.
+
+## What is NOT blocked
+
+- `bun`, `bunx`, `bun run`, `bun add`, `bun install` (local) — the intended package commands. (`bun add -g` / `bun install -g` are still blocked as global installs: bun globals live in `~/.bun`, outside `/agent`, and are wiped on restart.)
+- A non-bun manager name appearing as a substring or argument: `my-npm-wrapper`, `./npm`, `cat npm-debug.log`, `git commit -m "drop npm"`, `grep -rn npx src/`, `echo "npm install -g foo"`. Only the **command word** of a segment is classified, so a manager name inside an argument, path, quoted string, or longer token never trips the guard.
+
+## Ordering against other bundled plugins
+
+Registered after `guard` in `src/run/bundled-plugins.ts`. It guards a disjoint surface (package-manager bash commands), so its position only matters for precedence: keeping it after `security` and `guard` means any of their blocks wins first.
+
+## Tests
+
+- `policy.test.ts` — pure-function unit tests for the detection logic: every global-install form, every non-bun manager, the allowed-command set (bun/bunx, substrings, paths, quoted text), both bypasses, the global-install-takes-precedence rule, escaped/quoted evasions, leading-assignment preambles, newline-as-separator scoping, falsy `--global=`, option placement, and subshell/substitution detection.
+- `index.test.ts` — composition tests: the plugin registers the `tool.before` hook and wires it to the policy (block on global install, block on npx, allow bunx, honor the bypass).

package/src/bundled-plugins/bun-hygiene/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { checkBunHygieneGuard } from './policy'
+
+export default definePlugin({
+  plugin: async () => ({
+    hooks: {
+      'tool.before': (event) => checkBunHygieneGuard({ tool: event.tool, args: event.args }),
+    },
+  }),
+})

package/src/bundled-plugins/bun-hygiene/policy.ts

@@ -0,0 +1,318 @@
+import { ACKNOWLEDGE_GUARDS, type GuardBlock, isGuardAcknowledged } from '../guard/policy'
+
+export const GUARD_GLOBAL_INSTALL = 'globalInstall'
+export const GUARD_NON_BUN_PACKAGE_MANAGER = 'nonBunPackageManager'
+
+const NON_BUN_MANAGERS = new Set(['npm', 'npx', 'pnpm', 'pnpx', 'yarn'])
+const INSTALL_SUBCOMMANDS = new Set(['install', 'i', 'add'])
+
+export function checkBunHygieneGuard(options: { tool: string; args: Record<string, unknown> }): GuardBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'bash') return undefined
+
+  const command = args.command
+  if (typeof command !== 'string') return undefined
+
+  const verdict = classify(command)
+  if (verdict === undefined) return undefined
+  if (verdict.kind === 'global-install') return blockGlobalInstall(verdict.label, args)
+  return blockNonBunManager(verdict.manager, args)
+}
+
+type Verdict = { kind: 'global-install'; label: string } | { kind: 'non-bun'; manager: string }
+
+// Why a segment model instead of one big regex: every gap in a raw-string match
+// is a shell-structure gap. Splitting into segments first means a global flag on
+// a *different* command (`npm install\n-g x` — two commands) can never combine
+// with an install on another, leading assignment words (`FOO=bar npm ...`) are
+// stripped uniformly, and `--global=false` is inspected as a real token. The
+// global-install verdict wins over the plain non-bun verdict (it's the more
+// specific violation, and acknowledging it is meant to let the whole thing run).
+function classify(command: string): Verdict | undefined {
+  let fallback: Verdict | undefined
+  for (const segment of splitSegments(command)) {
+    const words = segment.map(normalizeWord)
+    const manager = leadingCommandWord(words)
+    if (manager === undefined) continue
+
+    // `bun` is the allowed manager, but a `bun add -g` still installs to ~/.bun
+    // (outside /agent) and is wiped on restart, so it is a global install too —
+    // just never a plain non-bun violation.
+    const isBun = manager === 'bun'
+    if (!isBun && !NON_BUN_MANAGERS.has(manager)) continue
+
+    const label = globalInstallLabel(manager, words)
+    if (label !== undefined) return { kind: 'global-install', label }
+    if (!isBun) fallback ??= { kind: 'non-bun', manager }
+  }
+  return fallback
+}
+
+// Split on real command separators (`;`, `&&`, `||`, `|`, `&`, newline, `\r`)
+// and on subshell / command-substitution openers (`(`, `$(`, backtick), then
+// tokenize each segment into whitespace-separated words. Quote-aware so a
+// separator inside quotes stays literal; backslash escapes the next character
+// (so `\;` and `\ ` are literal, not separators/breaks). Word-level only — it
+// does not interpret redirections or expansions beyond boundary marking.
+function splitSegments(command: string): string[][] {
+  const segments: string[][] = []
+  let words: string[] = []
+  let current = ''
+  let hasWord = false
+  let quote: '"' | "'" | null = null
+  // Tracks a command substitution entered from inside a double quote, so the
+  // outer double-quote mode is restored when the substitution closes. Bash runs
+  // `$(...)` and backtick substitutions inside double quotes (but not single),
+  // so `echo "$(npm install)"` must be scanned for a manager.
+  let commandSub: { kind: '`' | '$('; depth: number; resumeQuote: '"' } | null = null
+
+  const flushWord = (): void => {
+    if (hasWord) {
+      words.push(current)
+      current = ''
+      hasWord = false
+    }
+  }
+  const flushSegment = (): void => {
+    flushWord()
+    if (words.length > 0) {
+      segments.push(words)
+      words = []
+    }
+  }
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== null) {
+      // A `$(` or backtick inside a double quote opens a command substitution
+      // that Bash executes; scan its body as a fresh segment, remembering to
+      // resume double-quote mode when it closes.
+      if (quote === '"' && ch === '`') {
+        flushSegment()
+        commandSub = { kind: '`', depth: 0, resumeQuote: '"' }
+        quote = null
+        continue
+      }
+      if (quote === '"' && ch === '$' && command[i + 1] === '(') {
+        flushSegment()
+        commandSub = { kind: '$(', depth: 1, resumeQuote: '"' }
+        quote = null
+        i++
+        continue
+      }
+      if (ch === quote) quote = null
+      else {
+        current += ch
+        hasWord = true
+      }
+      continue
+    }
+    // Close of a command substitution opened from inside a double quote:
+    // restore the outer double-quote mode so the rest of the string (and any
+    // trailing `&&`/`;`) is parsed correctly rather than re-quoted.
+    if (commandSub?.kind === '`' && ch === '`') {
+      flushSegment()
+      quote = commandSub.resumeQuote
+      commandSub = null
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === '$' && command[i + 1] === '(') {
+      flushSegment()
+      commandSub.depth++
+      i++
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === '(') {
+      flushSegment()
+      commandSub.depth++
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === ')') {
+      flushSegment()
+      commandSub.depth--
+      if (commandSub.depth === 0) {
+        quote = commandSub.resumeQuote
+        commandSub = null
+      }
+      continue
+    }
+    if (ch === '\\') {
+      const next = command[i + 1]
+      if (next === undefined) break
+      // `\<newline>` (and `\<CR><newline>`) is a shell line continuation: the
+      // shell removes it entirely, joining the surrounding text. Dropping it
+      // here keeps `npm install \<nl>-g x` tokenized as `install`,`-g` (a global
+      // install) instead of producing a malformed `install\n-g` token.
+      if (next === '\n') {
+        i++
+        continue
+      }
+      if (next === '\r' && command[i + 2] === '\n') {
+        i += 2
+        continue
+      }
+      current += next
+      hasWord = true
+      i++
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      hasWord = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      flushWord()
+      continue
+    }
+    if (ch === '\n' || ch === '\r' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === '`') {
+      flushSegment()
+      continue
+    }
+    if (ch === '$' && command[i + 1] === '(') {
+      flushSegment()
+      i++
+      continue
+    }
+    current += ch
+    hasWord = true
+  }
+  flushSegment()
+  return segments
+}
+
+// A word is already quote/escape-collapsed by splitSegments (quotes consumed,
+// backslash-escapes literalized), so the only residue to strip is leftover
+// quote characters that appeared mid-token via concatenation. Keeping this
+// explicit makes `"npm"`, `n\px`, `'npm'` all resolve to their bare binary.
+function normalizeWord(word: string): string {
+  return word.replaceAll('"', '').replaceAll("'", '')
+}
+
+// Preamble wrappers that prefix a real command (`sudo npm …`, `env FOO=bar npm
+// …`, `nice -n 10 npm …`). The value is the set of SHORT option letters that
+// consume the FOLLOWING word as their argument, so `sudo -u nobody npm` skips
+// `nobody` too. Long `--opt=value` forms are self-contained (one token); bare
+// long `--opt` and unknown short flags are skipped as a single token (the safe
+// default — at worst we skip one extra token and still find the manager later).
+const PREAMBLE_WRAPPERS: Record<string, ReadonlySet<string>> = {
+  sudo: new Set(['u', 'g', 'h', 'p', 'C', 'r', 't', 'T', 'U']),
+  env: new Set(['u', 'C', 'S']),
+  nice: new Set(['n']),
+  command: new Set([]),
+  exec: new Set(['a']),
+  nohup: new Set([]),
+  stdbuf: new Set(['i', 'o', 'e']),
+  setsid: new Set([]),
+  time: new Set(['o', 'f']),
+  xargs: new Set([]),
+}
+
+// The command word is the first token that is not a shell preamble: a known
+// wrapper (with its options consumed), or a `VAR=val` assignment. This is what
+// makes `FOO=bar npm install` and `env -i npm install` / `sudo -u nobody pnpm
+// add` resolve to the real manager instead of evading the guard.
+function leadingCommandWord(words: string[]): string | undefined {
+  let i = 0
+  while (i < words.length) {
+    const word = words[i]
+    if (word === undefined) break
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+      i++
+      continue
+    }
+    const argTakingShortOpts = PREAMBLE_WRAPPERS[word]
+    if (argTakingShortOpts !== undefined) {
+      i = skipWrapperOptions(words, i + 1, argTakingShortOpts)
+      continue
+    }
+    return word
+  }
+  return undefined
+}
+
+// From the token after a wrapper, skip its option tokens. A long `--opt` is one
+// token. A short `-x` (or bundled `-xy`) consumes the next word only when its
+// LAST letter is in `argTaking` (e.g. `-n 10`, `-u nobody`). `VAR=val` between a
+// wrapper and its command (as `env` allows) is also skipped. Stops at the first
+// non-option, non-assignment token — that is the wrapped command word.
+function skipWrapperOptions(words: string[], start: number, argTaking: ReadonlySet<string>): number {
+  let i = start
+  while (i < words.length) {
+    const word = words[i]
+    if (word === undefined) break
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+      i++
+      continue
+    }
+    if (word.startsWith('--')) {
+      i++
+      continue
+    }
+    if (word.startsWith('-') && word.length > 1) {
+      const lastLetter = word[word.length - 1]
+      i++
+      if (lastLetter !== undefined && argTaking.has(lastLetter) && i < words.length) i++
+      continue
+    }
+    break
+  }
+  return i
+}
+
+function globalInstallLabel(manager: string, words: string[]): string | undefined {
+  if (manager === 'yarn') {
+    // Real syntax is `yarn global add <pkg>` — `global` immediately followed by
+    // `add` as a consecutive sequence. Checking for both tokens anywhere would
+    // false-positive on `yarn add global foo` (a local install of a package
+    // literally named `global`), which is not a global install at all.
+    return hasAdjacentSequence(words, 'global', 'add') ? 'yarn global add' : undefined
+  }
+  const hasInstall = words.some((w) => INSTALL_SUBCOMMANDS.has(w))
+  const hasGlobal = words.some(isGlobalFlag)
+  if (!hasInstall || !hasGlobal) return undefined
+  return manager === 'bun' ? 'bun global install (-g / --global)' : 'npm/pnpm global install (-g / --global)'
+}
+
+function hasAdjacentSequence(words: string[], first: string, second: string): boolean {
+  for (let i = 0; i + 1 < words.length; i++) {
+    if (words[i] === first && words[i + 1] === second) return true
+  }
+  return false
+}
+
+// `-g` / `--global`, including bundled short flags like `-gD` / `-Dg`. An
+// explicit falsy value (`--global=false|0|no|off`) is NOT a global install —
+// it disables the flag — so it must not match.
+function isGlobalFlag(word: string): boolean {
+  if (/^--global=(?:false|0|no|off)$/i.test(word)) return false
+  if (/^--global(?:=|$)/.test(word)) return true
+  return /^-[A-Za-z]*g[A-Za-z]*$/.test(word)
+}
+
+function blockGlobalInstall(label: string, args: Record<string, unknown>): GuardBlock | undefined {
+  if (isGuardAcknowledged(args, GUARD_GLOBAL_INSTALL)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_GLOBAL_INSTALL}\` blocked a global install: ${label}.`,
+      'Global installs live outside the bind-mounted /agent folder and are wiped on every container restart, so they never persist.',
+      'Use `bun add <pkg>` to add a dependency that survives restarts (it writes package.json), or `bunx <pkg>` to run a tool once without installing.',
+      `Retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_GLOBAL_INSTALL}: true\` only if a throwaway global install is genuinely what you want.`,
+    ].join(' '),
+  }
+}
+
+function blockNonBunManager(manager: string, args: Record<string, unknown>): GuardBlock | undefined {
+  if (isGuardAcknowledged(args, GUARD_NON_BUN_PACKAGE_MANAGER)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_NON_BUN_PACKAGE_MANAGER}\` blocked \`${manager}\`. This container standardizes on bun.`,
+      'Use `bun install` / `bun add <pkg>` instead of npm/pnpm/yarn, and `bunx <pkg>` instead of npx/pnpx.',
+      `Retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_NON_BUN_PACKAGE_MANAGER}: true\` if this package manager is genuinely required (e.g. a project pinned to a different lockfile).`,
+    ].join(' '),
+  }
+}

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

@@ -1,7 +1,11 @@
 export type GhCommandDecision =
   | { kind: 'pass-through' }
   | { kind: 'block'; reason: string }
-  | { kind: 'inject'; repoSlug: string }
+  // `rewrittenCommand`, when present, MUST replace the executed command: `gh api`
+  // rejects `-R/--repo` ("unknown shorthand flag"), so for a graphql endpoint the
+  // flag is consumed as our repo hint and stripped before exec. Other inject paths
+  // (REST, non-`api` subcommands) leave the command unchanged and omit it.
+  | { kind: 'inject'; repoSlug: string; rewrittenCommand?: string }
 
 const MISSING_REPO_REASON =
   'This GitHub App spans multiple owners, so `gh` has no single correct token. ' +
@@ -27,7 +31,9 @@ const API_REPO_CONFLICT_REASON =
 type GhSegmentDecision =
   | { kind: 'pass-through' }
   | { kind: 'block'; reason: string }
-  | { kind: 'inject'; repoSlugs: readonly string[] }
+  // `stripRepoFlag` marks a graphql inject whose `-R/--repo` is a TypeClaw-only
+  // hint that `gh api` would reject, so it must be removed from the command.
+  | { kind: 'inject'; repoSlugs: readonly string[]; stripRepoFlag?: boolean }
 
 const COMPOSITION_REASON =
   'A repo-targeting `gh` command receives a minted GitHub App token in its process ' +
@@ -117,13 +123,17 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   if (ghStarts.length === 0) return { kind: 'pass-through' }
 
   const repoSlugs: string[] = []
+  let stripRepoFlag = false
   for (let i = 0; i < ghStarts.length; i++) {
     const start = ghStarts[i] as number
     const end = ghStarts[i + 1] ?? tokens.length
     const args = tokens.slice(start + 1, end)
     const segment = classifyGhSegment(args)
     if (segment.kind === 'block') return segment
-    if (segment.kind === 'inject') repoSlugs.push(...segment.repoSlugs)
+    if (segment.kind === 'inject') {
+      repoSlugs.push(...segment.repoSlugs)
+      if (segment.stripRepoFlag === true) stripRepoFlag = true
+    }
   }
 
   if (repoSlugs.length === 0) return { kind: 'pass-through' }
@@ -135,9 +145,71 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   // shell expansion would inherit it.
   if (!isSingleBareGhCommand(command)) return { kind: 'block', reason: COMPOSITION_REASON }
 
+  if (stripRepoFlag) {
+    return { kind: 'inject', repoSlug: repoSlugs[0] as string, rewrittenCommand: stripRepoFlagFromCommand(command) }
+  }
   return { kind: 'inject', repoSlug: repoSlugs[0] as string }
 }
 
+// Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single
+// bare command, preserving everything else byte-for-byte. Quote-aware so a `-R`
+// inside a quoted `-f query='...'` value is never touched; a repo slug is
+// owner/name (no whitespace), so the value is always a single unquoted token.
+// Used only for graphql, where `gh api` rejects the flag we consumed as a hint.
+function stripRepoFlagFromCommand(command: string): string {
+  let out = ''
+  let i = 0
+  while (i < command.length) {
+    const ch = command[i] as string
+    if (ch === '"' || ch === "'") {
+      const close = command.indexOf(ch, i + 1)
+      const endQuote = close === -1 ? command.length : close
+      out += command.slice(i, endQuote + 1)
+      i = endQuote + 1
+      continue
+    }
+    const removed = matchRepoFlagAt(command, i)
+    if (removed !== null) {
+      out = out.replace(/[ \t]+$/, '')
+      i = removed
+      while (command[i] === ' ' || command[i] === '\t') i += 1
+      if (out !== '' && i < command.length) out += ' '
+      continue
+    }
+    out += ch
+    i += 1
+  }
+  return out
+}
+
+// If `command` has an unquoted `-R`/`--repo` repo-flag token starting at `start`
+// (at a word boundary), returns the index just past the flag and its value;
+// otherwise null. Handles `-R o/r`, `--repo o/r`, `-R=o/r`, `--repo=o/r`.
+function matchRepoFlagAt(command: string, start: number): number | null {
+  const before = start === 0 ? '' : (command[start - 1] as string)
+  if (before !== '' && before !== ' ' && before !== '\t') return null
+
+  for (const flag of ['--repo', '-R']) {
+    if (!command.startsWith(flag, start)) continue
+    let i = start + flag.length
+    const sep = command[i]
+    if (sep === '=') {
+      i += 1
+      while (i < command.length && command[i] !== ' ' && command[i] !== '\t') i += 1
+      return i
+    }
+    if (sep === ' ' || sep === '\t') {
+      let j = i
+      while (command[j] === ' ' || command[j] === '\t') j += 1
+      const valueStart = j
+      while (j < command.length && command[j] !== ' ' && command[j] !== '\t') j += 1
+      if (!isRepoSlug(command.slice(valueStart, j))) return null
+      return j
+    }
+  }
+  return null
+}
+
 function classifyGhSegment(args: readonly string[]): GhSegmentDecision {
   const subcommand = args.find((t) => !t.startsWith('-'))
   if (subcommand === undefined) return { kind: 'pass-through' }
@@ -159,8 +231,9 @@ function classifyGhSegment(args: readonly string[]): GhSegmentDecision {
 // Repo authority for `gh api`: the literal endpoint path wins. A `-R/--repo`
 // that names a DIFFERENT repo than the path is a mint-for-X-but-hit-Y attempt
 // and blocks. A placeholder endpoint (`repos/{owner}/{repo}`) has no literal
-// target, so -R fills it and is authoritative. A non-repo endpoint (`graphql`,
-// `/user`) passes through — -R does not make it repo-scoped, so no mint.
+// target, so -R fills it and is authoritative. A non-repo endpoint without a
+// `-R` (`graphql`, `/user`) passes through — the flag is what makes it
+// repo-scoped, so absent one there is nothing to mint for.
 function classifyGhApiSegment(args: readonly string[]): GhSegmentDecision {
   const pathRepos = extractReposFromApiPath(args)
   const flagRepo = extractRepoFlag(args)
@@ -176,9 +249,22 @@ function classifyGhApiSegment(args: readonly string[]): GhSegmentDecision {
     return { kind: 'inject', repoSlugs: [flagRepo] }
   }
 
+  // graphql encodes its repo in the query body / opaque node IDs, never an
+  // inspectable path, so `-R` is taken as the mint hint. Safe because there is
+  // no literal path to conflict with (cf. the API_REPO_CONFLICT_REASON guard
+  // above): the minted token's installation scope, not the flag, bounds reach.
+  // `gh api` rejects `-R`, so the flag must be stripped from the command.
+  if (flagRepo !== null && isGraphqlEndpoint(args)) {
+    return { kind: 'inject', repoSlugs: [flagRepo], stripRepoFlag: true }
+  }
+
   return { kind: 'pass-through' }
 }
 
+function isGraphqlEndpoint(args: readonly string[]): boolean {
+  return findApiEndpoint(args) === 'graphql'
+}
+
 function findGhInvocations(tokens: readonly string[]): number[] {
   const starts: number[] = []
   for (let i = 0; i < tokens.length; i++) {
@@ -249,6 +335,12 @@ const GH_API_VALUE_FLAGS = new Set([
   '--hostname',
 ])
 
+// `-R`/`--repo` are not real `gh api` flags, but TypeClaw accepts them as a repo
+// hint that can appear BEFORE the endpoint (`gh api -R o/r graphql`). They consume
+// the following token, so findApiEndpoint must skip both — otherwise the slug is
+// misread as the endpoint and the graphql path never runs.
+const REPO_HINT_VALUE_FLAGS = new Set(['-R', '--repo'])
+
 // The `gh api` endpoint is the first positional arg after `api` (skipping flags
 // and the tokens that bare value-flags consume). Returns null if there is none.
 function findApiEndpoint(args: readonly string[]): string | null {
@@ -257,7 +349,7 @@ function findApiEndpoint(args: readonly string[]): string | null {
   for (let i = apiIndex + 1; i < args.length; i++) {
     const arg = args[i] as string
     if (arg.startsWith('-')) {
-      if (!arg.includes('=') && GH_API_VALUE_FLAGS.has(arg)) i += 1
+      if (!arg.includes('=') && (GH_API_VALUE_FLAGS.has(arg) || REPO_HINT_VALUE_FLAGS.has(arg))) i += 1
       continue
     }
     return arg

package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts

@@ -0,0 +1,80 @@
+import type { ContentPart, ToolResult } from '@/plugin'
+
+import { classifyGhToken } from './token-class'
+
+export const GRAPHQL_AUTH_NUDGE_TAG = 'github-cli-auth:graphqlRepoHint'
+
+const NUDGE_TEXT =
+  `\n\n[${GRAPHQL_AUTH_NUDGE_TAG}] That looked like a GitHub auth failure on a ` +
+  '`gh api graphql` call. Under a multi-owner GitHub App there is no single ' +
+  '`GH_TOKEN`, and graphql carries its repo inside the query — not an inspectable ' +
+  'path — so TypeClaw cannot tell which installation token to mint. Re-run with an ' +
+  'explicit repo, e.g. `gh api graphql -R owner/repo -f query=...`. `gh api` does ' +
+  'not accept `-R/--repo`; TypeClaw consumes it as the mint hint and strips it ' +
+  'before running the command with the right token injected.'
+
+// The shell strips quotes/escapes, so we match the raw `gh ... graphql` substring
+// rather than parse — the nudge is advisory, so a loose match is acceptable and a
+// false positive only appends a hint to an unrelated failure. Captured through to
+// end of line so we can inspect the SAME invocation's flags (see REPO_FLAG).
+const GRAPHQL_INVOCATION = /\bgh\b[^\n]*\bapi\b[^\n]*\bgraphql\b[^\n]*/
+
+// `-R foo`, `-R=foo`, `--repo foo`, `--repo=foo`. Word-boundary anchored so a
+// path or token merely containing "repo" does not count as a repo hint.
+const REPO_FLAG = /(?:^|\s)(?:-R|--repo)(?:[=\s]|$)/
+
+// Concrete auth-rejection strings only — gh / the API emit these when the
+// request itself was rejected for auth. Deliberately excludes resolution
+// errors like "Could not resolve to ...", which graphql also returns for an
+// ordinary bad node ID or missing repo (not auth) and would misroute the nudge.
+const AUTH_FAILURE_SIGNATURES = [
+  'HTTP 401',
+  'Bad credentials',
+  'Resource not accessible by integration',
+  'Resource not accessible by personal access token',
+  'must be authenticated',
+  'authentication required',
+  'gh auth login',
+]
+
+export function checkGraphqlAuthNudge(options: { tool: string; result: ToolResult }): void {
+  if (options.tool !== 'bash') return
+
+  // Only meaningful when no usable token is seeded — the multi-owner App case.
+  // A seeded global token (single-owner App, classic/fine-grained PAT) means
+  // graphql already authenticates, so the advice would be wrong.
+  const tokenClass = classifyGhToken(process.env.GH_TOKEN)
+  if (tokenClass !== 'none') return
+
+  const text = collectText(options.result.content)
+  const invocation = GRAPHQL_INVOCATION.exec(text)
+  if (invocation === null) return
+  if (!AUTH_FAILURE_SIGNATURES.some((sig) => text.includes(sig))) return
+  if (text.includes(GRAPHQL_AUTH_NUDGE_TAG)) return
+
+  // The nudge's only message is "add the repo hint". If the failing invocation
+  // already carries -R/--repo, the hint is present and the failure is an
+  // authorization/permission denial (e.g. the App token lacks a scope), not a
+  // missing-repo one — so "re-run with -R" would be misleading, repeated advice.
+  if (REPO_FLAG.test(invocation[0])) return
+
+  appendAdviceToContent(options.result.content, NUDGE_TEXT)
+}
+
+function collectText(content: readonly ContentPart[]): string {
+  return content
+    .filter((p): p is ContentPart & { type: 'text' } => p.type === 'text')
+    .map((p) => p.text)
+    .join('\n')
+}
+
+function appendAdviceToContent(content: ContentPart[], advice: string): void {
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i]
+    if (part && part.type === 'text') {
+      content[i] = { ...part, text: `${part.text}${advice}` }
+      return
+    }
+  }
+  content.push({ type: 'text', text: advice.trimStart() })
+}