@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/agent-hooks/src/rules/shell/git-identity.ts

@@ -0,0 +1,1415 @@
+/**
+ * Carrying the session identity (`ADL_AGENT_ID_AGENT`) into every network git
+ * invocation of a command-executing tool call.
+ *
+ * Live gap this closes (2026-09-28, codex session 01a0e611): an
+ * `adl run -- codex` session ran `git push -u origin feat/adl-m3-finish`
+ * through the lean-ctx MCP tool `mcp__lean_ctx__ctx_shell`; Codex gives
+ * `ADL_AGENT_ID_AGENT` only to its own shell tool, so the push executed with
+ * no identity and `bin/git-ado`'s HUMAN pass-through (bin/git-ado:191-194)
+ * pushed with Tarun's own credential helper. The hook process had the
+ * identity all along — it arrives in the hook's own environment, which `adl
+ * run` sets — but had no way to put it on the command. This scanner is that
+ * way: `git push …` becomes `ADL_AGENT_ID_AGENT=agent-tarun git push …`, and
+ * the pre-tool-use handler returns the rewritten command as the host's native
+ * "replace the tool input" envelope (`updatedInput` on Claude/Codex,
+ * `updated_input` on Cursor). On hosts with no such envelope the handler
+ * denies instead — see impl/adl-git-identity.ts.
+ *
+ * The verb list (`NETWORK_GIT_VERBS`) started as exactly `bin/git-ado`'s
+ * credential path (`fetch|pull|clone|ls-remote|push`, bin/git-ado:159-165):
+ * those are the commands for which a missing identity silently becomes the
+ * human. F2 (independent review, 2026-09-29) widened what this file (and
+ * `impl/adl-session-required.ts`'s deny side) actually TREATS as network —
+ * see `isNetworkGitInvocation`'s own doc below for the additional shapes
+ * (`git remote show|prune|update`/`set-head -a`, `git maintenance run
+ * --task=prefetch` specifically — not a bare `git maintenance run`, aligned
+ * with `bin/git-ado`'s own narrower routing there, another executor's
+ * surface — the transport helpers, `git submodule update|sync --recursive`,
+ * `git archive --remote`) — this claim about the bare five-verb
+ * `NETWORK_GIT_VERBS` set is no longer the WHOLE story for what this file
+ * classifies as network, only for what `bin/git-ado`'s OWN credential path
+ * covers today. Reads and local operations (`status`/`log`/`diff`/…) never
+ * touch git-ado's identity branch and are deliberately left untouched,
+ * idempotency included — a command already prefixed with the SAME identity
+ * is returned unchanged, and one prefixed with a DIFFERENT (or emptied)
+ * identity is a deny, never a
+ * rewrite, because the override would either spoof attribution or launder the
+ * command back onto the human path.
+ *
+ * The scanner is offset-aware and mirrors the shell front end's semantics
+ * (`./split.ts`, `./token.ts`, `./prefixes.ts`) for the constructs that
+ * matter: quotes, backslash escapes, `$(…)`/`${…}`/backtick/`<(…)` spans,
+ * `#` comments, IO operators, `&&`/`||`/`;`/`|`/`&`/newline/paren/brace
+ * separators, leading assignments, wrapper commands and git's own global
+ * flags. Nested `bash -c '<script>'` script strings are scanned one level at
+ * a time (depth-capped), the same shapes `./invocation.ts` walks for the deny
+ * rules; a script FILE operand (`sh deploy.sh`) is not on this command line
+ * and is not inspected. `sudo`/`doas` are denied rather than rewritten:
+ * they strip the environment, so a prefixed identity would silently not
+ * survive to git.
+ *
+ * The identity is validated against `^[A-Za-z0-9_-]+$` before it ever enters
+ * shell text — an identity outside that set means the session itself is
+ * misconfigured, and injecting it would be code execution.
+ */
+
+import { findMatchingBacktick, findMatchingParen } from './substitution.ts'
+import { GIT_GLOBAL_EQ, GIT_GLOBAL_TAKES_ARG, GIT_TERMINAL_GLOBALS } from './prefixes.ts'
+import { ADL_AGENT_ID_ENV_VAR, isValidAgent } from '../impl/adl-identity.ts'
+import {
+  ADL_AGENT_ID_BINARY_NAMES,
+  ADL_AGENT_ID_COMMAND_SHAPES,
+  ADL_BINARY_NAMES,
+  ADL_IDENTITY_COMMAND_SHAPES,
+  HTTP_CLIENT_BINARY_NAMES,
+  isAdoUrl,
+  matchesIdentityShape,
+  skipLeadingDashFlags,
+} from '../impl/git-helpers.ts'
+
+/**
+ * The five network verbs `bin/git-ado` routes through the agent identity /
+ * human pass-through decision. Only these ever need the identity on the
+ * command line.
+ */
+export const NETWORK_GIT_VERBS: ReadonlySet<string> = new Set(['fetch', 'pull', 'clone', 'ls-remote', 'push'])
+
+/**
+ * F2 (independent review, 2026-09-29): network-reaching git shapes the
+ * walker missed entirely — subcommands other than the five `NETWORK_GIT_VERBS`
+ * above, or ones where only a SPECIFIC sub-action/flag combination reaches
+ * the network (an innocuous sibling form of the same subcommand must NOT be
+ * swept in): `git remote show|prune|update <remote>` (each contacts the
+ * remote; `git remote -v`/`add`/`rename`/`remove` never do), `git remote
+ * set-head <r> -a` (auto-detects HEAD over the network; `set-head <r>
+ * <branch>` with an explicit branch does not), `git maintenance run
+ * --task=prefetch` (fetches every registered remote in the background;
+ * `--task=gc`/`commit-graph`/… do not), the internal transport helpers
+ * `git remote-https`/`git remote-http`/`git http-fetch` (network by
+ * construction when invoked directly), `git submodule update|sync
+ * --recursive` (recurses into and can fetch nested submodule remotes;
+ * without `--recursive` it only touches the top-level submodules already
+ * configured), and `git archive --remote[=<repo>]` (fetches the archive
+ * data from a remote repository over the git protocol; a bare `git archive`
+ * only reads the local tree). `git fetch` (and the other four) via a leading
+ * `git -c ...` global is already covered without any change here —
+ * `scanGitGlobals`/`scanGitGlobalsValues` (`./prefixes.ts`) already skip
+ * every global flag, `-c` included, before either call site below ever
+ * inspects the subcommand word.
+ *
+ * Used by BOTH sides `adl.session-required-for-writes`'s own header names
+ * ("deny with no identity / rewrite with one"): `identityBearingReason`
+ * (`impl/adl-session-required.ts`) for the deny side, and the REWRITE
+ * scanner's own `NETWORK_GIT_VERBS` gate below for the rewrite side — one
+ * shared predicate, not two independently-maintained shape lists.
+ */
+const REMOTE_NETWORK_ACTIONS: ReadonlySet<string> = new Set(['show', 'prune', 'update'])
+const SUBMODULE_RECURSIVE_ACTIONS: ReadonlySet<string> = new Set(['update', 'sync'])
+const REMOTE_TRANSPORT_HELPERS: ReadonlySet<string> = new Set(['remote-https', 'remote-http', 'http-fetch'])
+
+function firstNonOptionValue(values: readonly string[]): string | undefined {
+  return values.find((value) => !value.startsWith('-'))
+}
+
+export function isNetworkGitInvocation(subcommand: string, restValues: readonly string[]): boolean {
+  if (NETWORK_GIT_VERBS.has(subcommand)) return true
+  if (REMOTE_TRANSPORT_HELPERS.has(subcommand)) return true
+  if (subcommand === 'remote') {
+    const action = firstNonOptionValue(restValues)?.toLowerCase()
+    if (action === undefined) return false
+    if (REMOTE_NETWORK_ACTIONS.has(action)) return true
+    if (action === 'set-head') return restValues.some((value) => value === '-a' || value === '--auto')
+    return false
+  }
+  if (subcommand === 'maintenance') {
+    const action = firstNonOptionValue(restValues)?.toLowerCase()
+    if (action !== 'run') return false
+    return restValues.some((value, index) => value === '--task=prefetch' || (value === '--task' && restValues[index + 1] === 'prefetch'))
+  }
+  if (subcommand === 'submodule') {
+    const action = firstNonOptionValue(restValues)?.toLowerCase()
+    if (action === undefined || !SUBMODULE_RECURSIVE_ACTIONS.has(action)) return false
+    // P2 (independent review, 2026-09-29): `--init` clones every submodule
+    // not yet checked out — network, same as `--recursive` recursing into
+    // nested ones.
+    return restValues.some((value) => value === '--recursive' || value === '--init')
+  }
+  if (subcommand === 'archive') {
+    return restValues.some((value) => value === '--remote' || value.startsWith('--remote='))
+  }
+  return false
+}
+
+const SAFE_IDENTITY = /^[A-Za-z0-9_-]+$/
+
+/** Shells whose `-c`/`--command` script string is re-scanned one level deeper (mirrors invocation.ts's shellNames). */
+const SHELL_NAMES: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'])
+
+const MAX_NESTED_SCRIPT_DEPTH = 16
+
+/**
+ * `identity-mismatch` covers BOTH shapes the standard treats the same way
+ * (STATUS.md 12p, "Decision per identity-bearing
+ * shell command"): an inline `ADL_AGENT_ID_AGENT=<value>` that is empty
+ * (would launder the command back onto git-ado's human pass-through) or
+ * names an agent outside `VALID_AGENTS`. A VALID inline value — even one
+ * that differs from the resolved fallback — is no longer a conflict at all:
+ * the override wins and the command is left unchanged (`kind: 'unchanged'`).
+ * See `applyIdentityOutcome` below.
+ */
+/**
+ * `network-alias-redefinition` (H2, STATUS.md 12p):
+ * a self-referential `git -c alias.<name>=<value>`/`--config-env[=]
+ * alias.<name>=<value>` where `<name>` is the literal subcommand this
+ * invocation runs and `<value>`'s own verb is network/credential-bearing —
+ * see `networkAliasRedefinition`'s own doc.
+ */
+/**
+ * `dynamic-agent` (M5, STATUS.md 12p): `adl id
+ * token <agent>`/`adl-agent-id exec --agent <agent>` whose agent argument
+ * is itself dynamic ($-expansion, backtick, or a glob character) — denied
+ * outright rather than silently treated as "not identity-bearing", since a
+ * dynamically computed agent name could name ANY agent at runtime, evading
+ * `adl.token-minting-role`'s static "own identity only" check entirely.
+ */
+export type GitIdentityDenyReason =
+  | 'identity-mismatch'
+  | 'unrewritable-wrapper'
+  | 'unsafe-identity'
+  | 'network-alias-redefinition'
+  | 'dynamic-agent'
+
+export type GitIdentityScan =
+  | { readonly kind: 'rewrite'; readonly command: string }
+  | { readonly kind: 'unchanged' }
+  /**
+   * An identity-bearing simple command was found, it carries no (valid)
+   * inline override, and no fallback identity was resolved (the `fallback`
+   * argument was `null`). Nothing was rewritten or denied here — this is a
+   * signal for the CALLER (`adl-session-required.ts`) to deny with the
+   * standard's own message; this scanner's job is only to rewrite/detect
+   * conflicts once an identity — inline or fallback — actually exists.
+   */
+  | { readonly kind: 'needs-identity' }
+  | { readonly kind: 'deny'; readonly reason: GitIdentityDenyReason }
+
+/** One scanned word: `value` is the dequoted shell word (token.ts semantics), `start`/`end` its raw span (end exclusive) in the original command. */
+interface Word {
+  readonly value: string
+  readonly start: number
+  readonly end: number
+  readonly operator: boolean
+}
+
+interface Piece {
+  readonly words: readonly Word[]
+}
+
+/** Longest-match-first IO operators, so `>&` wins over `>` and `&>>` over `&>`. `|`/`&` alone are separators, never operators. */
+const IO_OPERATORS = ['&>>', '<<<', '<<-', '&>', '>&', '>|', '<&', '>>', '<<', '<>', '<', '>'] as const
+
+/**
+ * Longest IO operator at `text[index]`, or the bare character when none of
+ * the table matches. Every scanPieces call site guarantees `<`, `>`, `&>` or
+ * `&>>`, so the fallback is a defensive contract pin, exercised directly in
+ * tests/unit/shell-git-identity.test.ts.
+ */
+export function matchIoOperator(text: string, index: number): string {
+  for (const op of IO_OPERATORS) {
+    if (text.startsWith(op, index)) return op
+  }
+  return text[index] as string
+}
+
+/** End index (inclusive) of a `$(…)`, `${…}`, backtick or `<(`/`>(` span starting at `index`, or null — port of token.ts's expansionEnd. */
+function expansionEnd(text: string, index: number): number | null {
+  const char = text[index]
+  const next = text[index + 1]
+  if ((char === '$' || char === '<' || char === '>') && next === '(') {
+    const close = findMatchingParen(text, index + 1)
+    return close < 0 ? text.length - 1 : close
+  }
+  if (char === '$' && next === '{') {
+    const close = text.indexOf('}', index + 2)
+    return close < 0 ? text.length - 1 : close
+  }
+  if (char === '`') {
+    const close = findMatchingBacktick(text, index)
+    return close < 0 ? text.length - 1 : close
+  }
+  return null
+}
+
+function isAssignmentValue(value: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*=/.test(value)
+}
+
+/** Lower-cased final path segment of a word value — port of token.ts's basename. */
+function basenameValue(value: string): string {
+  const segments = value.split(/[/\\]/)
+  return (segments[segments.length - 1] ?? '').toLowerCase()
+}
+
+/** Port of token.ts's dynamicToken, on dequoted values. */
+function dynamicValue(value: string): boolean {
+  return value.includes('$') || value.includes('`') || /[*?]/.test(value)
+}
+
+/** Port of git-helpers.ts's isHelpOnlyInvocation, on dequoted values. */
+function valuesHelpOnly(values: readonly string[]): boolean {
+  const flags = new Set<string>()
+  for (const arg of values) {
+    if (arg === '--') break
+    if (arg === '--help' || arg === '--version') flags.add('help')
+    if (arg === '-h' && values.length === 1) flags.add('help')
+  }
+  return flags.has('help') && values.every((arg) => arg.startsWith('-') && arg !== '--')
+}
+
+/** The first `http(s)://` value among `values` — port of git-helpers.ts's `classifyGitPushDestination`'s private `firstUrl`, on dequoted string values instead of Tokens. */
+function firstHttpUrl(values: readonly string[]): string | null {
+  for (const value of values) {
+    if (/^https?:\/\//i.test(value)) return value
+  }
+  return null
+}
+
+/**
+ * Split `text` (a command, or a nested script string) into pieces at unquoted
+ * `&&`/`||`/`;`/`|`/`&`/newlines and group boundaries, tokenizing each piece
+ * into words with raw source spans offset by `base` in the original command.
+ * Mirrors split.ts's structure handling (quote-aware, comment-aware,
+ * substitution-opaque, `>&`/`&>` folding) closely enough for the git-identity
+ * analysis; it does not need split.ts's pipe feeds.
+ */
+function scanPieces(text: string, base: number, pieces: Piece[]): void {
+  const words: Word[] = []
+  let value = ''
+  let start = -1
+  let quote: '"' | "'" | null = null
+  let wordStart = true
+
+  const flush = (endLocal: number): void => {
+    if (start >= 0) {
+      words.push({ value, start: base + start, end: base + endLocal, operator: false })
+      value = ''
+      start = -1
+    }
+  }
+  const endPiece = (endLocal: number): void => {
+    flush(endLocal)
+    if (words.length > 0) pieces.push({ words: [...words] })
+    words.length = 0
+  }
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index] as string
+
+    if (quote === "'") {
+      if (char === "'") quote = null
+      else value += char
+      continue
+    }
+    if (char === '\\') {
+      // Unquoted or inside double quotes (token.ts escapes any next char in both).
+      if (start < 0) start = index
+      if (index + 1 >= text.length) return // unterminated escape: leave the partial word unflushed; the command fails closed upstream
+      value += text[index + 1]
+      index += 1
+      wordStart = false
+      continue
+    }
+    if (quote === '"') {
+      if (char === '"') {
+        quote = null
+        continue
+      }
+      const end = char === '$' || char === '`' ? expansionEnd(text, index) : null
+      if (end !== null) {
+        if (start < 0) start = index
+        value += text.slice(index, end + 1)
+        index = end
+        continue
+      }
+      value += char
+      continue
+    }
+    if (char === "'" || char === '"') {
+      if (start < 0) start = index
+      quote = char
+      wordStart = false
+      continue
+    }
+
+    const expansion = expansionEnd(text, index)
+    if (expansion !== null) {
+      if (start < 0) start = index
+      value += text.slice(index, expansion + 1)
+      index = expansion
+      wordStart = false
+      continue
+    }
+
+    if (char === '\n' || char === ';') {
+      flush(index)
+      endPiece(index)
+      wordStart = true
+      continue
+    }
+
+    if (/\s/.test(char)) {
+      flush(index)
+      wordStart = true
+      continue
+    }
+
+    if (char === '#' && wordStart) {
+      flush(index)
+      let end = index
+      while (end + 1 < text.length && text[end + 1] !== '\n') end += 1
+      index = end
+      wordStart = true
+      continue
+    }
+
+    if (char === '&') {
+      if (text[index + 1] === '&') {
+        flush(index)
+        endPiece(index)
+        index += 1
+        wordStart = true
+        continue
+      }
+      if (text[index + 1] === '>') {
+        flush(index)
+        const op = matchIoOperator(text, index)
+        words.push({ value: op, start: base + index, end: base + index + op.length, operator: true })
+        index += op.length - 1
+        wordStart = false
+        continue
+      }
+      // A bare `&` backgrounds the preceding command.
+      flush(index)
+      endPiece(index)
+      wordStart = true
+      continue
+    }
+
+    if (char === '|') {
+      if (text[index + 1] === '|') {
+        flush(index)
+        endPiece(index)
+        index += 1
+      } else {
+        flush(index)
+        endPiece(index)
+      }
+      wordStart = true
+      continue
+    }
+
+    const groupBrace =
+      (char === '{' && (index + 1 >= text.length || /\s/.test(text[index + 1] as string))) ||
+      (char === '}' && (index === 0 || /[\s;]/.test(text[index - 1] as string)))
+    if (char === '(' || char === ')' || groupBrace) {
+      flush(index)
+      endPiece(index)
+      wordStart = true
+      continue
+    }
+
+    if (char === '<' || char === '>') {
+      flush(index)
+      const op = matchIoOperator(text, index)
+      words.push({ value: op, start: base + index, end: base + index + op.length, operator: true })
+      index += op.length - 1
+      wordStart = false
+      continue
+    }
+
+    if (start < 0) start = index
+    value += char
+    wordStart = false
+  }
+
+  endPiece(text.length)
+}
+
+/** Port of prefixes.ts's skipDashOptions, on words (operators end the option run). */
+function skipDashOptions(words: readonly Word[], start: number, valueOptions: readonly string[], stopAtDoubleDash: boolean): number {
+  let index = start
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator) break
+    const value = word.value
+    if (stopAtDoubleDash && value === '--') return index + 1
+    if (!value.startsWith('-') || value === '-') break
+    index += valueOptions.includes(value) ? 2 : 1
+  }
+  return index
+}
+
+/** Port of prefixes.ts's skipWrapperFlags, on words. */
+function skipWrapperFlagArgs(words: readonly Word[], start: number, withValue: readonly string[]): number {
+  let index = start
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator) break
+    const value = word.value
+    if (value === '--') return index + 1
+    if (withValue.includes(value)) {
+      index += 2
+      continue
+    }
+    if (value.startsWith('-') && value !== '-') {
+      index += 1
+      continue
+    }
+    break
+  }
+  return index
+}
+
+/** One wrapper's flag scan: the index past its own flags, and whether it strips the environment (H1). */
+interface WrapperScan {
+  readonly index: number
+  readonly strips: boolean
+}
+
+/**
+ * Port of prefixes.ts's skipEnvFlags, on words; collects the env command's
+ * `NAME=value` arguments for identity-conflict checks, and reports whether
+ * `-u`/`--unset[=NAME]` or `-i`/`--ignore-environment` were used (H1).
+ *
+ * `-u`/`--unset` denies regardless of WHICH name it names — not only
+ * `ADL_AGENT_ID_AGENT` itself — the same blanket treatment `sudo`/`doas` get
+ * below even though `sudo -E` would actually preserve the environment: this
+ * scanner does not try to prove a specific unset is safe, it treats the
+ * FLAG as the risk, matching the existing sudo/doas precedent rather than
+ * adding a second, narrower standard only env gets.
+ */
+function skipEnvArgs(words: readonly Word[], start: number, assignments: string[]): WrapperScan {
+  let index = start
+  let strips = false
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator) break
+    const value = word.value
+    if (value === '--') return { index: index + 1, strips }
+    if (value === '-u' || value === '--unset') {
+      strips = true
+      index += 2
+      continue
+    }
+    if (value === '-i' || value === '--ignore-environment') {
+      strips = true
+      index += 1
+      continue
+    }
+    if (['-C', '--chdir', '-S', '--split-string'].includes(value)) {
+      index += 2
+      continue
+    }
+    if (value.startsWith('--unset=')) {
+      strips = true
+      index += 1
+      continue
+    }
+    if (value.startsWith('--chdir=') || value.startsWith('-') || value.includes('=')) {
+      if (isAssignmentValue(value)) assignments.push(value)
+      index += 1
+      continue
+    }
+    break
+  }
+  return { index, strips }
+}
+
+/**
+ * `exec`'s `-c`/`-l` flags run the wrapped command with an empty environment
+ * (`-c`) or as a login shell that can re-source profiles which reset it
+ * (`-l`) — H1 treats both as environment-stripping, like sudo/doas. `-a
+ * name` (argv0 only) never strips and is skipped transparently. Bash's own
+ * `exec` builtin accepts these bundled (`-cl`, `-la name`, …); any bundle
+ * containing `c` or `l` is treated as stripping, fail-closed, rather than
+ * trying to prove a particular bundling is safe.
+ */
+function skipExecArgs(words: readonly Word[], start: number): WrapperScan {
+  let index = start
+  let strips = false
+  for (;;) {
+    const word = words[index]
+    if (word === undefined || word.operator) break
+    const value = word.value
+    if (value === '--') {
+      index += 1
+      break
+    }
+    if (/^-[acl]+$/.test(value)) {
+      if (value.includes('c') || value.includes('l')) strips = true
+      index += value.includes('a') ? 2 : 1
+      continue
+    }
+    break
+  }
+  return { index, strips }
+}
+
+/** Port of prefixes.ts's skipCommandFlags + skipRepeatedTokens(['--','-p']). */
+function skipCommandArgs(words: readonly Word[], start: number): number {
+  const first = words[start]
+  if (first !== undefined && !first.operator && ['-v', '-V'].includes(first.value)) return words.length
+  let index = start
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator || !['--', '-p'].includes(word.value)) break
+    index += 1
+  }
+  return index
+}
+
+/** Port of prefixes.ts's skipTimeoutFlags (wrapper flags, then the one duration operand). */
+function skipTimeoutArgs(words: readonly Word[], start: number): number {
+  const index = skipWrapperFlagArgs(words, start, ['-s', '--signal', '-k', '--kill-after'])
+  return index < words.length ? index + 1 : index
+}
+
+/**
+ * Wrapper commands whose environment passes through to the wrapped command —
+ * port of prefixes.ts's COMMAND_PREFIXES/PREFIX_HANDLERS. Each value skips the
+ * wrapper's own flags/operands and lands on the wrapped command; none of
+ * these ever strip the environment. `env` and `exec` are NOT here — H1
+ * treats their environment-stripping flags (`env -u`/`--unset`/`-i`, `exec
+ * -c`/`-l`) like sudo/doas, so `analyzePiece` special-cases them the same
+ * way it special-cases sudo/doas, rather than folding a `strips` result into
+ * every entry in this map for the sake of two wrappers that need it.
+ */
+const WRAPPER_SKIP: Readonly<Record<string, (words: readonly Word[], start: number, assignments: string[]) => number>> = {
+  command: (words, start) => skipCommandArgs(words, start),
+  nice: (words, start) => skipDashOptions(words, start, ['-n', '--adjustment'], false),
+  time: (words, start) => skipDashOptions(words, start, ['-o', '--output'], false),
+  timeout: skipTimeoutArgs,
+  gtimeout: skipTimeoutArgs,
+  stdbuf: (words, start) => skipWrapperFlagArgs(words, start, ['-i', '-o', '-e']),
+  caffeinate: (words, start) => skipWrapperFlagArgs(words, start, ['-t', '-w']),
+  arch: (words, start) => skipWrapperFlagArgs(words, start, ['-arch']),
+  setsid: (words, start) => skipWrapperFlagArgs(words, start, []),
+  nohup: (words, start) => skipDashOptions(words, start, [], true),
+}
+
+/** Port of prefixes.ts's scanGitGlobals, on words; operators end the global scan. */
+function scanGitGlobalsValues(words: readonly Word[], start: number): { readonly index: number; readonly terminal: boolean } {
+  let index = start
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator) break
+    const value = word.value
+    if (GIT_TERMINAL_GLOBALS.has(value) || value.startsWith('--list-cmds=')) return { index, terminal: true }
+    if (GIT_GLOBAL_TAKES_ARG.has(value)) {
+      index += 2
+      continue
+    }
+    if (GIT_GLOBAL_EQ.some((prefix) => value.startsWith(prefix)) || (value.startsWith('-c') && value.includes('=') && value !== '-c')) {
+      index += 1
+      continue
+    }
+    if (value === '--') {
+      index += 1
+      break
+    }
+    if (value.startsWith('-') && value !== '-') {
+      index += 1
+      continue
+    }
+    break
+  }
+  return { index, terminal: false }
+}
+
+const CREDENTIAL_HELPER_VERBS: ReadonlySet<string> = new Set(['fill', 'approve', 'reject'])
+const SUBMODULE_NETWORK_VERBS: ReadonlySet<string> = new Set(['update', 'sync', 'foreach'])
+
+/**
+ * The alias VALUE's own verb — split on whitespace, a leading `!` (a shell
+ * alias, e.g. `!git push origin main`) stripped first and, when what
+ * follows still starts with `git`/`git.exe`, that word skipped too so
+ * `!git push …` reads as verb `push`, not `git`. A fully arbitrary shell
+ * one-liner alias (`!curl … | sh`) is not further inspected here — that is
+ * `shell.remote-script-exec`'s/`parse.uncertain`'s concern, not this one's;
+ * this only recognizes the exact network/credential VERB shapes H2 names.
+ */
+export function networkAliasVerb(aliasValue: string): boolean {
+  const stripped = aliasValue.startsWith('!') ? aliasValue.slice(1).trim() : aliasValue
+  const words = stripped.split(/\s+/).filter((word) => word.length > 0)
+  const start = words[0]?.toLowerCase() === 'git' || words[0]?.toLowerCase() === 'git.exe' ? 1 : 0
+  const first = words[start]?.toLowerCase()
+  if (first === undefined) return false
+  const second = words[start + 1]?.toLowerCase()
+  if (NETWORK_GIT_VERBS.has(first)) return true
+  if (first === 'remote' && second === 'update') return true
+  if (first === 'submodule' && second !== undefined && SUBMODULE_NETWORK_VERBS.has(second)) return true
+  if (first === 'credential' && second !== undefined && CREDENTIAL_HELPER_VERBS.has(second)) return true
+  return false
+}
+
+/**
+ * True when `globalWords` (a git invocation's `-c`/`--config-env` globals,
+ * BEFORE alias resolution) define `alias.<subcommand>` — SELF-referential:
+ * the literal word this invocation actually runs — to a value whose own
+ * verb is network/credential-bearing (`networkAliasVerb`). See H2's comment
+ * at this function's one call site for why this is narrower than a blanket
+ * `-c alias.*` deny.
+ */
+function networkAliasRedefinition(globalWords: readonly Word[], subcommand: string): boolean {
+  const targetKey = `alias.${subcommand}`
+  for (let index = 0; index < globalWords.length; index += 1) {
+    const word = globalWords[index] as Word
+    if (word.operator) continue
+    const value = word.value
+    let setting: string | null = null
+    if (value === '-c' || value === '--config-env') {
+      const next = globalWords[index + 1]
+      if (next !== undefined && !next.operator) setting = next.value
+      index += 1
+    } else if (value.startsWith('-c') && value.includes('=') && value !== '-c') {
+      setting = value.slice(2)
+    } else if (value.startsWith('--config-env=')) {
+      setting = value.slice('--config-env='.length)
+    }
+    if (setting === null) continue
+    const equals = setting.indexOf('=')
+    if (equals < 0) continue
+    if (setting.slice(0, equals).toLowerCase() !== targetKey) continue
+    if (networkAliasVerb(setting.slice(equals + 1).trim())) return true
+  }
+  return false
+}
+
+/**
+ * R4 (STATUS.md 12p, re-review 2026-09-28 night): the
+ * ENV-VAR-based sibling of `networkAliasRedefinition` — `GIT_CONFIG_COUNT`/
+ * `GIT_CONFIG_KEY_<n>`/`GIT_CONFIG_VALUE_<n>` are git's OWN alternative to
+ * `-c`/`--config-env` for supplying ad-hoc config, read the same way
+ * `../shell/invocation.ts`'s `environmentGitAlias` already reads them for
+ * CLASSIFICATION (so this repo's other rules see the alias's resolved
+ * verb) — but classification alone throws away the fact that an alias was
+ * used at all once resolved, which is exactly what this SELF-referential
+ * check needs to catch: `bin/git-ado` routes on the literal argv verb, so
+ * `GIT_CONFIG_KEY_0=alias.p GIT_CONFIG_VALUE_0=push git p` never reaches its
+ * identity routing at all, the same live gap `networkAliasRedefinition`
+ * closes for the `-c`/`--config-env` spelling.
+ */
+function environmentAliasRedefinition(assignments: readonly string[], subcommand: string): boolean {
+  const targetKey = `alias.${subcommand}`
+  let count: number | null = null
+  const keys = new Map<number, string>()
+  const values = new Map<number, string>()
+  for (const assignment of assignments) {
+    const equals = assignment.indexOf('=')
+    if (equals < 0) continue
+    const name = assignment.slice(0, equals)
+    const value = assignment.slice(equals + 1)
+    if (name === 'GIT_CONFIG_COUNT') count = /^\d+$/.test(value) ? Number(value) : null
+    const keyMatch = /^GIT_CONFIG_KEY_(\d+)$/.exec(name)
+    if (keyMatch !== null) keys.set(Number(keyMatch[1]), value)
+    const valueMatch = /^GIT_CONFIG_VALUE_(\d+)$/.exec(name)
+    if (valueMatch !== null) values.set(Number(valueMatch[1]), value)
+  }
+  if (count === null || !Number.isSafeInteger(count)) return false
+  for (const index of [...keys.keys()].filter((candidate) => candidate < count)) {
+    if (keys.get(index)?.toLowerCase() !== targetKey) continue
+    const value = values.get(index)
+    if (value !== undefined && networkAliasVerb(value)) return true
+  }
+  return false
+}
+
+/** `--global`/`--local`/`--system`/`--worktree`/`--file <path>` etc. ahead of `git config`'s own positional key/value — skipped so `git config --global alias.p push` still finds `alias.p` as the key. */
+function skipGitConfigScopeFlags(words: readonly Word[], start: number): number {
+  const VALUE_FLAGS = new Set(['--file', '-f', '--blob'])
+  let index = start
+  while (index < words.length) {
+    const word = words[index] as Word
+    if (word.operator) break
+    const value = word.value
+    if (value === '--') return index + 1
+    if (VALUE_FLAGS.has(value)) {
+      index += 2
+      continue
+    }
+    if (value.startsWith('-') && value !== '-') {
+      index += 1
+      continue
+    }
+    break
+  }
+  return index
+}
+
+/**
+ * R4 (STATUS.md 12p, re-review 2026-09-28 night):
+ * `git config [--global|--local|…] alias.<verb> <value>` WRITES a
+ * persistent alias a LATER, separate command can invoke — pre-loading the
+ * exact bypass `networkAliasRedefinition`/`environmentAliasRedefinition`
+ * catch inline, just deferred to whenever the alias is next used (by which
+ * point this scanner has no visibility into a different command line at
+ * all). Denied at the point of DEFINITION instead: `git config alias.p
+ * push` never needs `git p` to actually run on the same line to be a real
+ * bypass being set up.
+ */
+function gitConfigWritesNetworkAlias(rest: readonly Word[]): boolean {
+  const index = skipGitConfigScopeFlags(rest, 0)
+  const keyWord = rest[index]
+  if (keyWord === undefined || keyWord.operator) return false
+  const match = /^alias\.(.+)$/i.exec(keyWord.value)
+  if (match === null) return false
+  const valueWord = rest[index + 1]
+  if (valueWord === undefined || valueWord.operator || valueWord.value.startsWith('-')) return false
+  return networkAliasVerb(valueWord.value)
+}
+
+const COMMAND_OPTION = '--command='
+const SCRIPT_OPTION_TAKES_WORD = new Set(['-c', '--command'])
+
+/**
+ * The script string a shell's `-c`/`--command` option carries, as a raw
+ * content span into the original command — port of invocation.ts's
+ * walkShellArgument. `--` ends the option scan; a non-option operand is a
+ * script FILE and is not inspected; an unterminated option scan yields null.
+ */
+function scriptContentSpan(command: string, words: readonly Word[], start: number): { readonly start: number; readonly end: number } | null {
+  for (let index = start; index < words.length; index += 1) {
+    const word = words[index] as Word
+    if (word.operator) return null
+    const value = word.value
+    if (value === '--') return null
+    if (SCRIPT_OPTION_TAKES_WORD.has(value) || (/^-[^-]*c$/.test(value) && !value.startsWith('--'))) {
+      const script = words[index + 1]
+      if (script === undefined || script.operator) return null
+      // A quoted script: insertions land inside the quotes; unquoted: at the word.
+      const rawFirst = command[script.start]
+      return rawFirst === "'" || rawFirst === '"' ? { start: script.start + 1, end: script.end - 1 } : { start: script.start, end: script.end }
+    }
+    if (value.startsWith(COMMAND_OPTION)) {
+      const valueStart = word.start + COMMAND_OPTION.length
+      if (valueStart >= word.end) return null
+      // A quoted inline script inserts INSIDE the quotes; an unquoted one at
+      // the value start — either way the prefix becomes part of the script
+      // string, never a separate word that would shift the shell's $0.
+      const rawFirst = command[valueStart]
+      return rawFirst === "'" || rawFirst === '"' ? { start: valueStart + 1, end: word.end - 1 } : { start: valueStart, end: word.end }
+    }
+    if (!value.startsWith('-')) return null
+  }
+  return null
+}
+
+interface ScanState {
+  deny: Extract<GitIdentityScan, { readonly kind: 'deny' }>['reason'] | null
+  /** Original-command offsets (ascending) where the identity prefix is inserted. */
+  insertions: number[]
+  /** Rule mode: detect conflicts only, never compute insertions. */
+  conflictsOnly: boolean
+  /** Set true the moment an identity-bearing command is found with no valid inline override and `fallback === null`. */
+  needsIdentity: boolean
+  /** The fallback identity (steps 2-3 of the standard), or null when none resolved — see `applyIdentityOutcome`. */
+  fallback: string | null
+  /** Set true the moment a valid inline `ADL_AGENT_ID_AGENT=` override is found on any identity-bearing piece — see `commandHasValidInlineIdentity`. */
+  foundInlineOverride: boolean
+  /**
+   * The value of the FIRST valid inline `ADL_AGENT_ID_AGENT=` override found
+   * on any identity-bearing piece, or null — same coarseness as
+   * `foundInlineOverride` (whole-command, not per-piece); see
+   * `effectiveIdentityForCommand`.
+   */
+  inlineIdentity: string | null
+  /**
+   * Every token-minting invocation found (`adl id token <Y>` /
+   * `adl-agent-id exec --agent <Y>`), paired with the effective identity for
+   * THAT piece — see `TokenMintingPiece` and `scanTokenMintingPieces`.
+   */
+  tokenMinting: TokenMintingPiece[]
+  /**
+   * Every network git invocation found (`fetch`/`pull`/`clone`/`ls-remote`/
+   * `push`), paired with the effective identity for THAT SPECIFIC piece —
+   * see `GitInvocationPiece` and `scanGitInvocationPieces`. M2/M3
+   * (STATUS.md 12p): a role-grading rule
+   * (`adl-git-push-policy.ts`) needs the identity a PARTICULAR push on a
+   * compound command line actually carries, not the whole command's coarse
+   * `inlineIdentity` (which is set from whichever piece happens to be first
+   * — a reviewer session could otherwise smuggle a denied push past the
+   * rule by chaining an unrelated, later push with its own valid override
+   * on the same line).
+   */
+  gitInvocations: GitInvocationPiece[]
+  /**
+   * Every `adl mcp cli <command> …` invocation found, paired with the
+   * effective identity for THAT SPECIFIC piece — R5
+   * (STATUS.md 12p): the role rules that gate these
+   * commands (`adl-workitem-role.ts`, `adl-pr-role.ts`,
+   * `adl-pr-review-role.ts`) used to grade `resolveFromEnvOrFile` alone,
+   * ignoring a valid inline override on the SAME piece — the exact M3 gap,
+   * just for `adl mcp cli` instead of `git push`. See `AdlMcpCliPiece` and
+   * `scanAdlMcpCliPieces`.
+   */
+  mcpCliInvocations: AdlMcpCliPiece[]
+}
+
+/**
+ * One network git invocation (`fetch`/`pull`/`clone`/`ls-remote`/`push`)
+ * found while scanning a command, paired with the effective identity for
+ * THAT specific piece: a valid inline `ADL_AGENT_ID_AGENT=` override on the
+ * SAME piece, else the resolved fallback, else null. `rest` is the dequoted
+ * values after the subcommand — the same shape `Invocation.rest` (Token
+ * array, dequoted via `tokenValue`) carries for a `'git'`-kind Invocation
+ * from `../shell/invocation.ts`'s classifier, so a rule holding one of
+ * those can correlate it to the piece here by comparing values. See
+ * `scanGitInvocationPieces`.
+ */
+export interface GitInvocationPiece {
+  readonly subcommand: string
+  readonly rest: readonly string[]
+  readonly effectiveAgent: string | null
+}
+
+/**
+ * One `adl mcp cli <command> …` invocation found while scanning a command,
+ * paired with the effective identity for THAT specific piece — R5
+ * (STATUS.md 12p). `command` is the gated command name
+ * (e.g. `workitem-create-or-update`), lower-cased; `rest` is the dequoted
+ * values after it, the same shape `impl/adl-mcp-cli.ts`'s `adlMcpCliCall`
+ * reads off `Invocation.args.slice(3)`, so a role rule can correlate a
+ * specific `Invocation` to its own piece here by comparing values, exactly
+ * like `GitInvocationPiece`/`scanGitInvocationPieces` for `git push`. See
+ * `scanAdlMcpCliPieces`.
+ */
+export interface AdlMcpCliPiece {
+  readonly command: string
+  readonly rest: readonly string[]
+  readonly effectiveAgent: string | null
+}
+
+/**
+ * One `adl id token <agent>` or `adl-agent-id exec --agent <agent>` (or
+ * `--agent=<agent>`) invocation found while scanning a command, paired with
+ * the effective identity for that specific simple command: a valid inline
+ * `ADL_AGENT_ID_AGENT=` override on the SAME piece, else the resolved
+ * fallback (steps 2-3 of the standard), else null (no identity at all —
+ * `adl.session-required-for-writes`'s problem, not this one's).
+ * `requestedAgent` is the raw text the command names, unvalidated — the
+ * caller (`impl/adl-token-minting-role.ts`) is the one that compares it
+ * against `effectiveAgent`.
+ */
+export interface TokenMintingPiece {
+  readonly kind: 'adl-id-token' | 'adl-agent-id-exec'
+  readonly requestedAgent: string
+  readonly effectiveAgent: string | null
+}
+
+/** The value of a valid (non-empty, `VALID_AGENTS`-member) inline `ADL_AGENT_ID_AGENT=` assignment among `assignments`, or undefined. */
+function validInlineIdentity(assignments: readonly string[]): string | undefined {
+  let inlineValue: string | undefined
+  for (const assignment of assignments) {
+    const equals = assignment.indexOf('=')
+    if (assignment.slice(0, equals) !== ADL_AGENT_ID_ENV_VAR) continue
+    inlineValue = assignment.slice(equals + 1).trim()
+  }
+  if (inlineValue === undefined) return undefined
+  return inlineValue.length > 0 && isValidAgent(inlineValue) ? inlineValue : undefined
+}
+
+/** `adl-agent-id exec`'s `--agent <value>` or `--agent=<value>` argument, or undefined when absent/malformed. */
+function execAgentFlagValue(restValues: readonly string[]): string | undefined {
+  const equalsForm = restValues.find((value) => value.startsWith('--agent='))
+  if (equalsForm !== undefined) return equalsForm.slice('--agent='.length) || undefined
+  const flagIndex = restValues.indexOf('--agent')
+  if (flagIndex < 0) return undefined
+  const value = restValues[flagIndex + 1]
+  return value === undefined || value.startsWith('-') ? undefined : value
+}
+
+/**
+ * The WORD (not the dequoted string `execAgentFlagValue` reads) carrying
+ * `adl-agent-id exec`'s `--agent` value — `--agent=<value>` is itself the
+ * carrying word; `--agent <value>` is the word AFTER the flag. Used only to
+ * check DYNAMISM (M5, STATUS.md 12p): a
+ * `--agent "$AGENT"` argument could name ANY agent at runtime, evading
+ * `adl.token-minting-role`'s static "own identity only" check entirely if
+ * it were silently treated as "not identity-bearing" the way any other
+ * unrelated dynamic flag on the same command is.
+ */
+function execAgentFlagWord(rest: readonly Word[]): Word | undefined {
+  const equalsForm = rest.find((word) => !word.operator && word.value.startsWith('--agent='))
+  if (equalsForm !== undefined) return equalsForm
+  const flagIndex = rest.findIndex((word) => !word.operator && word.value === '--agent')
+  if (flagIndex < 0) return undefined
+  const value = rest[flagIndex + 1]
+  return value === undefined || value.operator || value.value.startsWith('-') ? undefined : value
+}
+
+/**
+ * Shared identity decision for ONE matched identity-bearing simple command
+ * (STATUS.md 12p, "Decision per identity-bearing
+ * shell command"):
+ *
+ *  - an inline `ADL_AGENT_ID_AGENT=<value>` among `assignments` that is
+ *    empty or not one of `VALID_AGENTS` is a deny (`identity-mismatch`) —
+ *    never rewritten over;
+ *  - a VALID inline value — regardless of whether it matches `state.fallback`
+ *    — is the override: PASS, nothing inserted (the command already carries
+ *    a safe, complete identity);
+ *  - no inline value at all: a `sudo`/`doas` wrapper is `unrewritable-wrapper`
+ *    (the environment a prefix relies on is stripped); otherwise, with
+ *    `state.fallback === null`, this piece `needsIdentity` (the caller —
+ *    `adl-session-required.ts` — is the one that denies this); otherwise the
+ *    fallback is inserted at `insertAt` (skipped in `conflictsOnly` mode).
+ */
+function applyIdentityOutcome(assignments: readonly string[], unrewritableWrapper: boolean, insertAt: number, state: ScanState): void {
+  let inlineValue: string | undefined
+  for (const assignment of assignments) {
+    const equals = assignment.indexOf('=')
+    if (assignment.slice(0, equals) !== ADL_AGENT_ID_ENV_VAR) continue
+    inlineValue = assignment.slice(equals + 1).trim()
+  }
+  // An empty or invalid inline value is a deny regardless of a sudo/doas
+  // wrapper (it is already unsafe on its own); checked first, exactly like
+  // the pre-2026-09-28 mismatch check did.
+  if (inlineValue !== undefined && (inlineValue.length === 0 || !isValidAgent(inlineValue))) {
+    state.deny = 'identity-mismatch'
+    return
+  }
+  // sudo/doas strips the environment before the wrapped command runs, so
+  // even a VALID inline assignment sitting before it never reaches git —
+  // this check must come before "a valid inline override is a pass".
+  if (unrewritableWrapper) {
+    state.deny = 'unrewritable-wrapper'
+    return
+  }
+  if (inlineValue !== undefined) {
+    // A valid inline override, no unrewritable wrapper in the way: the
+    // command already carries a complete, safe identity — nothing to
+    // insert, nothing to deny.
+    state.foundInlineOverride = true
+    if (state.inlineIdentity === null) state.inlineIdentity = inlineValue
+    return
+  }
+  if (state.fallback === null) {
+    state.needsIdentity = true
+    return
+  }
+  if (!state.conflictsOnly) state.insertions.push(insertAt)
+}
+
+/**
+ * Classify one simple command's words. Returns the insertion offset when the
+ * piece is an identity-bearing invocation (a network git verb; an
+ * identity-bearing `adl`/`adl-agent-id` subcommand; a curl/wget/httpie/xh
+ * call to `dev.azure.com`/`*.visualstudio.com`) that needs the identity,
+ * records a deny on conflict, and recurses into `bash -c '<script>'` shapes.
+ * `insertAt` is the start of the simple command (before leading
+ * assignments), so the new prefix binds to the whole command including any
+ * wrappers.
+ */
+function analyzePiece(command: string, words: readonly Word[], state: ScanState, depth: number): void {
+  let index = 0
+  // Leading redirections (operator + target word) are not the command.
+  while (index < words.length && (words[index] as Word).operator) {
+    index += 1
+    if (index < words.length && !(words[index] as Word).operator) index += 1
+  }
+  if (index >= words.length) return
+  const insertAt = (words[index] as Word).start
+
+  const assignments: string[] = []
+  while (index < words.length && isAssignmentValue((words[index] as Word).value)) {
+    assignments.push((words[index] as Word).value)
+    index += 1
+  }
+
+  let unrewritableWrapper = false
+  for (;;) {
+    if (index >= words.length) return
+    const name = basenameValue((words[index] as Word).value)
+    if (name === 'sudo' || name === 'doas') {
+      // sudo/doas strip the environment: a prefix would silently not reach git.
+      unrewritableWrapper = true
+      index = skipDashOptions(words, index + 1, ['-u', '-g', '-C', '--user', '--group'], true)
+      while (index < words.length && isAssignmentValue((words[index] as Word).value)) {
+        assignments.push((words[index] as Word).value)
+        index += 1
+      }
+      continue
+    }
+    // H1: env -u/--unset[=NAME]/-i and exec -c/-l can strip the environment
+    // a prefix would rely on, the same way sudo/doas do — see skipEnvArgs's
+    // and skipExecArgs's own docs for why this is blanket (any use of the
+    // flag), not scoped to "only when it names ADL_AGENT_ID_AGENT".
+    if (name === 'env') {
+      // No trailing-assignment loop here, unlike sudo/doas and exec below:
+      // skipEnvArgs already consumes every `NAME=value` argument itself (its
+      // own catch-all branch — anything containing `=` and not a recognized
+      // flag — pushes straight into `assignments`), so by construction it
+      // never returns sitting on an unconsumed assignment.
+      const scan = skipEnvArgs(words, index + 1, assignments)
+      if (scan.strips) unrewritableWrapper = true
+      index = scan.index
+      continue
+    }
+    if (name === 'exec') {
+      const scan = skipExecArgs(words, index + 1)
+      if (scan.strips) unrewritableWrapper = true
+      index = scan.index
+      while (index < words.length && isAssignmentValue((words[index] as Word).value)) {
+        assignments.push((words[index] as Word).value)
+        index += 1
+      }
+      continue
+    }
+    const skipWrapper = WRAPPER_SKIP[name]
+    if (skipWrapper !== undefined) {
+      index = skipWrapper(words, index + 1, assignments)
+      while (index < words.length && isAssignmentValue((words[index] as Word).value)) {
+        assignments.push((words[index] as Word).value)
+        index += 1
+      }
+      continue
+    }
+    break
+  }
+
+  const commandName = basenameValue((words[index] as Word).value)
+
+  if (commandName === 'git' || commandName === 'git.exe') {
+    const globals = scanGitGlobalsValues(words, index + 1)
+    if (globals.terminal) return
+    const subcommandWord = words[globals.index]
+    if (subcommandWord === undefined || subcommandWord.operator) return
+    if (dynamicValue(subcommandWord.value)) return
+    // H2 (STATUS.md 12p, narrowed 2026-09-28): a
+    // SELF-REFERENTIAL `-c alias.<name>=<value>` (or `--config-env[=]
+    // alias.<name>=<value>`) where `<name>` is the LITERAL subcommand word
+    // this invocation runs, and `<value>`'s own verb is a network/credential
+    // one — checked BEFORE the NETWORK_GIT_VERBS gate below, since the
+    // literal word (e.g. `status`) need not itself be a network verb at all.
+    // `/usr/local/bin/git` (bin/git-ado) routes by the literal argv verb; it
+    // does not resolve git aliases itself, so an aliased network verb never
+    // reaches its identity routing. A NON-self-referential alias (`git -c
+    // alias.wt=worktree wt …`) is untouched — see `networkAliasRedefinition`'s
+    // own doc for why this is deliberately narrower than a blanket
+    // `-c alias.*` deny.
+    const globalWords = words.slice(index + 1, globals.index)
+    const literalSubcommand = subcommandWord.value.toLowerCase()
+    if (networkAliasRedefinition(globalWords, literalSubcommand)) {
+      state.deny = 'network-alias-redefinition'
+      return
+    }
+    // R4: the ENV-VAR-based sibling of the check above (`GIT_CONFIG_COUNT`/
+    // `GIT_CONFIG_KEY_n`/`GIT_CONFIG_VALUE_n`, already collected into
+    // `assignments` by the leading-assignment loop above this function's
+    // wrapper-skip loop) — see `environmentAliasRedefinition`'s own doc.
+    if (environmentAliasRedefinition(assignments, literalSubcommand)) {
+      state.deny = 'network-alias-redefinition'
+      return
+    }
+    // R4: `git config [--global|…] alias.<verb> <value>` WRITES a
+    // persistent alias for a LATER command to exploit — see
+    // `gitConfigWritesNetworkAlias`'s own doc. Checked before the
+    // NETWORK_GIT_VERBS gate below since `config` itself is never a network
+    // verb.
+    if (literalSubcommand === 'config' && gitConfigWritesNetworkAlias(words.slice(globals.index + 1))) {
+      state.deny = 'network-alias-redefinition'
+      return
+    }
+    const rest = words.slice(globals.index + 1).map((word) => word.value)
+    // F2 (independent review, 2026-09-29): widened from a plain
+    // `NETWORK_GIT_VERBS.has(literalSubcommand)` gate — see
+    // `isNetworkGitInvocation`'s own doc for the additional shapes.
+    if (!isNetworkGitInvocation(literalSubcommand, rest)) return
+    if (valuesHelpOnly(rest)) return
+    // M2/M3: record this SPECIFIC piece's own effective identity — see
+    // `GitInvocationPiece`'s doc — before the destination exemption below,
+    // so a role-grading rule can correlate to it by subcommand+rest
+    // regardless of whether THIS scanner itself treats the piece as
+    // identity-bearing for rewriting purposes.
+    state.gitInvocations.push({
+      subcommand: subcommandWord.value.toLowerCase(),
+      rest,
+      effectiveAgent: validInlineIdentity(assignments) ?? state.fallback,
+    })
+    // H3 (STATUS.md 12p): an EXPLICIT non-Azure-DevOps
+    // destination is provably safe without an identity — same exemption
+    // `git-helpers.ts`'s `classifyGitPushDestination` gives
+    // `adl.session-required-for-writes`. No explicit URL (a bare `git push`,
+    // or one naming a remote this scanner cannot look up) stays UNRESOLVED
+    // and is treated as identity-bearing, same fail-closed rule. Needed so
+    // `../engine.ts`'s H3 defense-in-depth deny on `needs-identity` does not
+    // deny a legitimate `git fetch https://github.com/...` that has no
+    // identity at all — this scanner previously flagged every network git
+    // verb as identity-bearing regardless of destination, which was harmless
+    // when `needs-identity` was never denied on its own, but is not harmless
+    // now that it is.
+    const explicitUrl = firstHttpUrl(rest)
+    if (explicitUrl !== null && !isAdoUrl(explicitUrl)) return
+    applyIdentityOutcome(assignments, unrewritableWrapper, insertAt, state)
+    return
+  }
+
+  if (ADL_BINARY_NAMES.has(commandName)) {
+    const rest = words.slice(index + 1)
+    const restValues = rest.map((word) => word.value)
+    // The shape check itself does not care about dynamism (a dynamic
+    // position's raw text is never literally "id"/"token"/… anyway), so it
+    // can run before the dynamic checks below — that lets the M5 check just
+    // after it single out the SPECIFIC agent-argument position rather than
+    // bailing on ANY dynamic content anywhere on the line.
+    if (!matchesIdentityShape(restValues, ADL_IDENTITY_COMMAND_SHAPES)) return
+    const isIdToken = restValues[0]?.toLowerCase() === 'id' && restValues[1]?.toLowerCase() === 'token'
+    const isMcpCli = restValues[0]?.toLowerCase() === 'mcp' && restValues[1]?.toLowerCase() === 'cli'
+    // M5 (STATUS.md 12p): `adl id token <agent>` with
+    // a DYNAMIC agent argument is denied outright — a dynamically computed
+    // agent name could name ANY agent at runtime, evading
+    // adl.token-minting-role's static "own identity only" check entirely if
+    // this were silently treated as "not identity-bearing" instead.
+    if (isIdToken) {
+      const agentWord = rest[2]
+      if (agentWord !== undefined && !agentWord.operator && dynamicValue(agentWord.value)) {
+        state.deny = 'dynamic-agent'
+        return
+      }
+    }
+    // Any OTHER dynamic content (an unrelated flag elsewhere on the line)
+    // cannot be proven identity-bearing beyond doubt; leave it alone rather
+    // than guess.
+    if (rest.some((word) => !word.operator && dynamicValue(word.value))) return
+    // `adl id token <agent>`: the requested agent is the third positional
+    // word (after `id token`), when it names one at all (not a flag).
+    if (isIdToken) {
+      const requested = restValues[2]
+      if (requested !== undefined && requested.length > 0 && !requested.startsWith('-')) {
+        state.tokenMinting.push({
+          kind: 'adl-id-token',
+          requestedAgent: requested,
+          effectiveAgent: validInlineIdentity(assignments) ?? state.fallback,
+        })
+      }
+    }
+    // R5: record this SPECIFIC `adl mcp cli <command>` piece's own effective
+    // identity — see `AdlMcpCliPiece`'s doc — so the role rules that gate
+    // these commands can grade the piece actually being invoked, not the
+    // whole command's coarse `inlineIdentity`.
+    if (isMcpCli) {
+      const gatedCommand = restValues[2]
+      if (gatedCommand !== undefined && gatedCommand.length > 0 && !gatedCommand.startsWith('-')) {
+        state.mcpCliInvocations.push({
+          command: gatedCommand.toLowerCase(),
+          rest: restValues.slice(3),
+          effectiveAgent: validInlineIdentity(assignments) ?? state.fallback,
+        })
+      }
+    }
+    applyIdentityOutcome(assignments, unrewritableWrapper, insertAt, state)
+    return
+  }
+
+  if (ADL_AGENT_ID_BINARY_NAMES.has(commandName)) {
+    const rest = words.slice(index + 1)
+    const restValues = rest.map((word) => word.value)
+    // M5: leading dash-prefixed global flags (e.g. `adl-agent-id --verbose
+    // exec --agent …`) are skipped before matching the `['exec']` shape —
+    // see skipLeadingDashFlags's own doc for why this must not require
+    // `exec` sitting at position 0 exactly.
+    if (!matchesIdentityShape(skipLeadingDashFlags(restValues), ADL_AGENT_ID_COMMAND_SHAPES)) return
+    // M5: a DYNAMIC --agent value is denied outright — same reasoning as
+    // the `adl id token` case above, applied to this shape's own
+    // agent-bearing flag instead of a positional argument.
+    const agentWord = execAgentFlagWord(rest)
+    if (agentWord !== undefined && dynamicValue(agentWord.value)) {
+      state.deny = 'dynamic-agent'
+      return
+    }
+    if (rest.some((word) => !word.operator && dynamicValue(word.value))) return
+    const requested = execAgentFlagValue(restValues)
+    if (requested !== undefined) {
+      state.tokenMinting.push({
+        kind: 'adl-agent-id-exec',
+        requestedAgent: requested,
+        effectiveAgent: validInlineIdentity(assignments) ?? state.fallback,
+      })
+    }
+    applyIdentityOutcome(assignments, unrewritableWrapper, insertAt, state)
+    return
+  }
+
+  if (HTTP_CLIENT_BINARY_NAMES.has(commandName)) {
+    const rest = words.slice(index + 1)
+    const targetsAdo = rest.some((word) => !word.operator && isAdoUrl(word.value))
+    if (!targetsAdo) return
+    applyIdentityOutcome(assignments, unrewritableWrapper, insertAt, state)
+    return
+  }
+
+  if (depth < MAX_NESTED_SCRIPT_DEPTH && SHELL_NAMES.has(commandName)) {
+    const span = scriptContentSpan(command, words, index + 1)
+    if (span !== null && span.end > span.start) {
+      const nested: Piece[] = []
+      scanPieces(command.slice(span.start, span.end), span.start, nested)
+      for (const nestedPiece of nested) {
+        if (state.deny !== null) return
+        analyzePiece(command, nestedPiece.words, state, depth + 1)
+      }
+    }
+  }
+}
+
+function scan(command: string, fallback: string | null, conflictsOnly: boolean): ScanState {
+  const state: ScanState = {
+    deny: null,
+    insertions: [],
+    conflictsOnly,
+    needsIdentity: false,
+    fallback,
+    foundInlineOverride: false,
+    inlineIdentity: null,
+    tokenMinting: [],
+    gitInvocations: [],
+    mcpCliInvocations: [],
+  }
+  const pieces: Piece[] = []
+  scanPieces(command, 0, pieces)
+  for (const piece of pieces) {
+    if (state.deny !== null) break
+    analyzePiece(command, piece.words, state, 0)
+  }
+  return state
+}
+
+/**
+ * Rewrite every identity-bearing invocation in `command` to carry
+ * `fallback`, or report why it cannot be carried. `fallback` is the resolved
+ * identity from steps 2-3 of the standard (`adl-identity.ts`'s
+ * `resolveFromEnvOrFile`), or `null` when nothing resolved — a piece that
+ * needs an identity and has none at all yields `needs-identity` rather than
+ * a deny; the caller (`adl-session-required.ts`) is the one that denies that
+ * case, with the standard's own message. Idempotent; never emits a token or
+ * an identity-bearing prefix the command did not already agree to.
+ *
+ * Narrow by design (Tarun, 2026-09-29, superseding an earlier
+ * whole-command `export` attempt at this same finding — STATUS.md
+ * 12p, R1): this only rewrites the identity-bearing shapes the piece
+ * scanner (`scanPieces`/`analyzePiece`, above) actually recognizes — a
+ * TOP-LEVEL simple command (or one nested inside a recognized `bash -c`/
+ * `sh -c` script). It deliberately does NOT walk into `if`/`!`/`for..do`/
+ * `xargs`/a heredoc or here-string/an interpreter one-liner to find a
+ * buried git/adl/curl invocation — `bin/git-ado` itself now fails closed
+ * (refuses) whenever `ADL_AGENT_ID_AGENT` is unset unless the caller is an
+ * interactive human terminal, so a shape this scanner misses is refused
+ * loudly by git-ado, never silently laundered onto the human credential
+ * path — the risk a broader rewrite here would have hedged against no
+ * longer exists once that source-level fix is in place.
+ */
+export function rewriteGitNetworkCommands(command: string, fallback: string | null): GitIdentityScan {
+  if (fallback !== null && !SAFE_IDENTITY.test(fallback)) return { kind: 'deny', reason: 'unsafe-identity' }
+  const state = scan(command, fallback, false)
+  if (state.deny !== null) return { kind: 'deny', reason: state.deny }
+  if (state.needsIdentity) return { kind: 'needs-identity' }
+  if (state.insertions.length === 0) return { kind: 'unchanged' }
+  const prefix = `${ADL_AGENT_ID_ENV_VAR}=${fallback} `
+  let rewritten = command
+  for (const at of [...state.insertions].sort((left, right) => right - left)) {
+    rewritten = `${rewritten.slice(0, at)}${prefix}${rewritten.slice(at)}`
+  }
+  return { kind: 'rewrite', command: rewritten }
+}
+
+/**
+ * The deny-rule view: which conflict (if any) a command carries — an invalid
+ * or empty inline override, or an unrewritable `sudo`/`doas` wrapper. `null`
+ * when the command is clean (including a VALID inline override, which is no
+ * longer a conflict) or needs no identity at all — the rule stays silent so
+ * the rewrite stage (or plain allow) proceeds. `fallback` only affects
+ * whether a missing-inline piece is treated as "needs identity" internally;
+ * this view never reports that as a conflict (`adl-session-required.ts` owns
+ * that message), so it is safe to call with `fallback: null`.
+ */
+export function scanGitIdentityConflicts(command: string, fallback: string | null): GitIdentityDenyReason | null {
+  if (fallback !== null && !SAFE_IDENTITY.test(fallback)) return null
+  return scan(command, fallback, true).deny
+}
+
+/**
+ * Whole-command, coarse signal used by `adl-session-required.ts`: true when
+ * SOME identity-bearing simple command in `command` carries a syntactically
+ * valid inline `ADL_AGENT_ID_AGENT=` override. This is intentionally
+ * coarser than the per-piece precision `rewriteGitNetworkCommands` itself
+ * uses for the actual rewrite/deny: a compound command mixing an overridden
+ * identity-bearing call with a non-overridden one is not disambiguated here
+ * — this function only answers "is there a valid inline override ANYWHERE on
+ * this line", which is exactly what the common, single-command override
+ * shape (`ADL_AGENT_ID_AGENT=<agent> git push …`) needs, and is a
+ * strictly MORE PERMISSIVE signal than the old session-env-only check it
+ * replaces (a command this returns `false` for was ALSO going to be denied
+ * by the old check).
+ */
+export function commandHasValidInlineIdentity(command: string): boolean {
+  return scan(command, null, true).foundInlineOverride
+}
+
+/**
+ * The EFFECTIVE identity for `command` (W2 build item 2,
+ * STATUS.md 12p): a valid inline
+ * `ADL_AGENT_ID_AGENT=` override anywhere on the command line (step 1 — same
+ * whole-command coarseness as `commandHasValidInlineIdentity`, which is the
+ * shape every real override takes: `ADL_AGENT_ID_AGENT=<agent> git push …`),
+ * else `fallback` (steps 2-3, `adl-identity.ts`'s `resolveFromEnvOrFile`),
+ * else null. Used by the role rules that must grade the identity a COMMAND
+ * actually carries, not merely the session's own — `adl-git-push-policy.ts`'s
+ * `git push`. Callers should check `scanGitIdentityConflicts` first: an
+ * invalid/empty inline override or an unrewritable sudo/doas wrapper is
+ * `adl.git-identity`'s problem to report, not a value this function silently
+ * papers over (an invalid inline value is never picked up here since
+ * `inlineIdentity` is only ever set from a value that already passed
+ * `isValidAgent`).
+ */
+export function effectiveIdentityForCommand(command: string, fallback: string | null): string | null {
+  const state = scan(command, fallback, true)
+  return state.inlineIdentity ?? fallback
+}
+
+/**
+ * Every token-minting invocation (`adl id token <agent>` /
+ * `adl-agent-id exec --agent <agent>`) found in `command`, each paired with
+ * the effective identity for that specific piece — see `TokenMintingPiece`.
+ * Used by `impl/adl-token-minting-role.ts` (W2 build item 1).
+ */
+export function scanTokenMintingPieces(command: string, fallback: string | null): readonly TokenMintingPiece[] {
+  return scan(command, fallback, true).tokenMinting
+}
+
+/**
+ * Every network git invocation (`fetch`/`pull`/`clone`/`ls-remote`/`push`)
+ * found in `command`, each paired with the effective identity for THAT
+ * specific piece — see `GitInvocationPiece`. M2/M3 (STATUS.md
+ * 12p): used by `impl/adl-git-push-policy.ts` to grade a
+ * SPECIFIC push by its own piece's identity, not the whole command's coarse
+ * `effectiveIdentityForCommand` (which a compound command with more than one
+ * identity-bearing piece could use to smuggle one piece's override onto
+ * another's grading).
+ */
+export function scanGitInvocationPieces(command: string, fallback: string | null): readonly GitInvocationPiece[] {
+  return scan(command, fallback, true).gitInvocations
+}
+
+/**
+ * Every `adl mcp cli <command> …` invocation found in `command`, each
+ * paired with the effective identity for THAT specific piece — see
+ * `AdlMcpCliPiece`. R5 (STATUS.md 12p): used by
+ * `impl/adl-workitem-role.ts`/`adl-pr-role.ts`/`adl-pr-review-role.ts` to
+ * grade a SPECIFIC `adl mcp cli` invocation by its own piece's inline
+ * identity, else the fallback — the same M3 correlation
+ * `scanGitInvocationPieces` already gives `git push`, extended to this
+ * command class.
+ */
+export function scanAdlMcpCliPieces(command: string, fallback: string | null): readonly AdlMcpCliPiece[] {
+  return scan(command, fallback, true).mcpCliInvocations
+}