typeclaw 0.21.0 → 0.23.0

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() })
+}

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

@@ -2,6 +2,7 @@ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
 import { definePlugin } from '@/plugin'
 
 import { analyzeGhCommand } from './gh-command'
+import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
 import { classifyGhToken } from './token-class'
 
 export default definePlugin({
@@ -34,8 +35,14 @@ export default definePlugin({
           // --setenv by the bash wrapper) so the token never enters the command
           // string, where it could leak through logs or later hooks.
           event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_TOKEN: result.token }
+          // graphql consumed `-R/--repo` as a mint hint; `gh api` rejects it, so
+          // run the command with the flag stripped (token still rides in env).
+          if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
           return
         },
+        'tool.after': async (event) => {
+          checkGraphqlAuthNudge({ tool: event.tool, result: event.result })
+        },
       },
     }
   },