@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/agent-hooks/src/rules/impl/adl-human-azdo-bypass.ts

@@ -0,0 +1,731 @@
+/**
+ * `adl.human-azdo-bypass` — STATUS.md 12p decisions 1/1b/1c:
+ * `ADL_HUMAN_AZDO=1` marks Tarun's own interactive terminal (`bin/git-ado`'s
+ * and `resolveAgentIdentity`'s shared human-pass-through check,
+ * `packages/azdo/src/lib/agent-identity.ts`'s `isMarkedHumanAzdoCaller`:
+ * stdin is a real TTY AND `ADL_HUMAN_AZDO === '1'`, exactly — never a
+ * near-miss value, never trimmed or case-insensitive). An agent must never
+ * set it at all: doing so from an agent surface would let a LATER command
+ * on the same persistent shell (where one exists) fall through git-ado's
+ * human pass-through with no agent identity involved, exactly the incident
+ * the whole standard exists to close — just aimed at the marker itself
+ * instead of at `ADL_AGENT_ID_AGENT`.
+ *
+ * F1 (independent review, 2026-09-29, HIGH, confirmed): a live bypass —
+ * `export ADL_HUMAN_AZD''O=1; unset ADL_AGENT_ID_AGENT; script -q /dev/null
+ * git push origin feat/x` — was ALLOWED and reached `bin/git-ado`'s human
+ * pass-through via a faked pty. Fixed in three parts (a/b/c below).
+ *
+ * SECOND REVIEW (2026-09-29, same night): the first F1 fix over-matched —
+ * `git commit -m "ADL_HUMAN_AZDO=1 is denied now"`, `git log -S
+ * "ADL_HUMAN_AZDO=1"`, `declare -p ADL_HUMAN_AZDO` (a READ, not a set),
+ * `grep -c '...'` (grep's COUNT flag, mistaken for shell `-c`), and `node -e
+ * "console.log('pty')"` (a bare word 'pty' in unrelated code) were all
+ * wrongly denied. Detection is now POSITIONAL, not "any word anywhere":
+ *
+ *  (a) A setter is recognized only in a real setter POSITION — a leading
+ *      `NAME=value` assignment before a piece's own command word, or the
+ *      piece's OWN command word being `export`/`declare -x`/`typeset -x`/
+ *      `printf -v`/`read`/`env NAME=value` with the name as ITS operand
+ *      (checked against `values[0]`, the piece's actual command, never an
+ *      unrelated word buried inside some OTHER command's arguments — a git
+ *      commit message, a `-S`/`-m` operand, are never inspected for this at
+ *      all). `declare`/`typeset` require the `-x` flag to be present
+ *      (`-p`/bare prints or lists, never sets); `printf` requires `-v`;
+ *      `export -p` (list, not set) does not count either. Word values are
+ *      already quote/escape-resolved by `../shell/token.ts`'s `tokenize`
+ *      before any of this runs, closing the original quote-splitting/
+ *      backslash-escaping bypass without needing a second, looser check.
+ *      A `-c`/`--command` argument is only re-scanned as a nested shell
+ *      script when the piece's OWN command is a REAL shell
+ *      (`bash`/`sh`/`zsh`/`dash`/`ksh`/`fish`) — `grep -c PATTERN`'s count
+ *      flag is never mistaken for one.
+ *      Interpreter one-liners (python/node/ruby/perl) are matched by their
+ *      OWN coarse setter pattern (`os.environ[...]=`/`.setdefault(...)`,
+ *      `process.env.X=`/`['X']=`, `$ENV{X}=`) against ONLY the `-c`/`-e`/
+ *      `--eval` code argument's value — never a bare word anywhere in the
+ *      command.
+ *  (b) Clearing `ADL_AGENT_ID_AGENT` is denied in every named form: `unset
+ *      NAME` (as an operand of `unset`, the piece's own command), `env -u
+ *      NAME`/`--unset[=]NAME`, an empty leading assignment (`NAME=`),
+ *      `export -n NAME`, `declare +x NAME`/`typeset +x NAME` (P2: `+x`
+ *      removes the export attribute). `env -i`/`--ignore-environment`/bare
+ *      `env -` clears the WHOLE environment, but is denied ONLY when the
+ *      command it wraps is ITSELF identity-bearing (`isLikelyIdentityBearing`
+ *      below: a network git verb, a curl/wget/httpie/xh call to Azure
+ *      DevOps, `az`, or an `adl`/`adl-agent-id` entry point) — `env -i PATH=
+ *      /usr/bin ls` clears the environment for a command that never needed
+ *      an identity in the first place, and denying it would only cost a
+ *      falsely-blocked, ordinary command for no security gain.
+ *      Interpreter one-liners: `del os.environ[...]`/`.pop(...)`/
+ *      `os.unsetenv(...)` (python), `delete process.env.X`/`['X']` (node),
+ *      `delete $ENV{X}` (perl) — same "-c/-e/--eval argument only" scoping
+ *      as the setter check.
+ *  (c) `script`/`unbuffer`/`expect`, `socat` with a `pty` argument, `tmux`/
+ *      `screen` starting a detached session with a command (P2:
+ *      `new-session`/`-dm`/`-dmS`), `zsh`'s `zpty` module command, a
+ *      python/node/ruby/perl one-liner or flag that actually loads a pty
+ *      module (`import pty`/`pty.spawn(...)`, `require('pty'|'node-pty')`,
+ *      `-rpty`, `-MIO::Pty` — never a bare word), launching a real terminal
+ *      app (`open -a Terminal|iTerm...`, `open *.command`, an `osascript`
+ *      `do script ... "Terminal"|"iTerm"`) are denied UNCONDITIONALLY — none
+ *      has a legitimate purpose on an agent surface, and narrowing to
+ *      "wraps an identity-bearing command" would require parsing what each
+ *      one wraps, fragile and trivially evaded by one more layer of
+ *      indirection. `ssh -t|-tt|-o RequestTTY=force` is the one shape
+ *      narrowed to a loopback host (`localhost`, `127.0.0.0/8`, `::1`, the
+ *      shorthand `0`) — forcing a PTY on a genuine remote admin session is
+ *      ordinary usage unrelated to faking a LOCAL pty.
+ *      All of (c) resolves the piece's REAL command first — past a leading
+ *      `NAME=value`, and past a chain of `env`/`timeout`/`nice`/`nohup`/
+ *      `command`/`exec` wrappers and their own flags (`resolvedCommand`,
+ *      below) — so `env ADL_AGENT_ID_AGENT=agent-tarun nohup script -q
+ *      /dev/null git push origin feat/x` is still caught as `script`, not
+ *      missed because the literal first word was a wrapper.
+ *
+ * Word collection deliberately does NOT walk into here-documents, here-
+ * strings, or `$(...)`/backtick substitutions (out of scope for this fix);
+ * it only reaches one level into a REAL shell's `-c`/`--command` script
+ * string, depth-capped — matching this rule's own "coarse, not a precise
+ * parser" contract.
+ *
+ * Unconditional — this fires regardless of whether an agent identity is
+ * otherwise resolvable. `IDENTITY_RULE_IDS` (`../../pre-tool-use/handler.ts`)
+ * no longer names a baseline this rule "rides" — Tarun's rule (2026-09-29)
+ * removed the global identity baseline entirely (hooks run only in a repo
+ * with its own `adl-config.toml`, never unmanaged), so `IDENTITY_RULE_IDS`
+ * now serves `identity_source` LOGGING classification only, inside a
+ * managed repo's own normal rule pass — this rule fires the same way any
+ * other enabled rule does, nothing baseline-specific about it.
+ *
+ * THE PTY-FAKING-WRAPPER CLASS IS UNBOUNDED (STATUS.md 12p item 15's threat
+ * model; F4, fourth independent review, 2026-09-29, "bounded, then stop").
+ * `pieceUsesPtyFakingWrapper` recognizes a widened but still FINITE list of
+ * named tools (`script`/`unbuffer`/`expect`/`zpty`, `socat`, `tmux`/`screen`,
+ * `ssh` to a loopback host, terminal-launching `open`/`osascript`, and a
+ * `pty`-module reference from python/node/ruby/perl) — it is not, and
+ * cannot be made, a complete enumeration of every way a same-OS-user
+ * process can attach to or fake a controlling terminal (a custom compiled
+ * helper, a language runtime this list does not name, a future terminal
+ * emulator, a creative combination of otherwise-ordinary tools). Widening
+ * this list further, one reported gap at a time, has a naturally
+ * diminishing return: closing THIS session's known list here (this fix,
+ * and the two before it in this file's own history) is the last widening
+ * pass for the foreseeable future — the credential-level fix (removing the
+ * SHARED-machine TTY signal `bin/git-ado` relies on as a proxy for "is this
+ * a human") is the orchestrator's own, separate track with Tarun, not
+ * something this rule can substitute for by enumerating tools forever.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { isMarkedHumanAzdoCaller } from '../../../../azdo/src/lib/agent-identity.ts'
+import { ADL_AGENT_ID_ENV_VAR } from './adl-identity.ts'
+import { ADL_AGENT_ID_BINARY_NAMES, ADL_BINARY_NAMES, HTTP_CLIENT_BINARY_NAMES, isAdoUrl } from './git-helpers.ts'
+import { isNetworkGitInvocation } from '../shell/git-identity.ts'
+import { skipPrefixes } from '../shell/prefixes.ts'
+import { heredocBodies } from '../shell/substitution.ts'
+import { splitShell } from '../shell/split.ts'
+import { tokenize, tokenValue, type Token } from '../shell/token.ts'
+
+export const RULE_ID = 'adl.human-azdo-bypass'
+
+/**
+ * The exact env var name STATUS.md 12p decisions 1b/1c name. Not exported as
+ * a standalone string constant from `packages/azdo/src/lib/agent-identity.ts`
+ * (only the combined TTY+value check, `isMarkedHumanAzdoCaller`, is) — this
+ * is the one place in this package that spells it, rather than a second,
+ * independent literal duplicated across detection helpers below.
+ */
+export const ADL_HUMAN_AZDO_ENV_VAR = 'ADL_HUMAN_AZDO'
+
+/** `os.environ['ADL_HUMAN_AZDO'] = ...` / `os.environ.setdefault('ADL_HUMAN_AZDO', ...)` — Python. Checked against ONLY the `-c`/`-e`/`--eval` code argument (see this file's own header). */
+const PYTHON_HUMAN_AZDO_SET_RE = /os\.environ\s*(?:\[\s*['"]ADL_HUMAN_AZDO['"]\s*\]|\.setdefault\(\s*['"]ADL_HUMAN_AZDO['"])\s*[=(]/
+/** `process.env.ADL_HUMAN_AZDO = ...` / `process.env['ADL_HUMAN_AZDO'] = ...` — Node. */
+const NODE_HUMAN_AZDO_SET_RE = /process\.env\s*(?:\.\s*ADL_HUMAN_AZDO\b|\[\s*['"]ADL_HUMAN_AZDO['"]\s*\])\s*=/
+/** `$ENV{ADL_HUMAN_AZDO} = ...` — Perl. */
+const PERL_HUMAN_AZDO_SET_RE = /\$ENV\{\s*['"]?ADL_HUMAN_AZDO['"]?\s*\}\s*=/
+
+/** `del os.environ['ADL_AGENT_ID_AGENT']` / `os.environ.pop(...)` / `os.unsetenv(...)` — Python. */
+const PYTHON_AGENT_ID_DELETE_RE = /\bdel\s+os\.environ\s*\[\s*['"]ADL_AGENT_ID_AGENT['"]\s*\]|\bos\.environ\.pop\(\s*['"]ADL_AGENT_ID_AGENT['"]|\bos\.unsetenv\(\s*['"]ADL_AGENT_ID_AGENT['"]/
+/** `delete process.env.ADL_AGENT_ID_AGENT` / `delete process.env['ADL_AGENT_ID_AGENT']` — Node. */
+const NODE_AGENT_ID_DELETE_RE = /\bdelete\s+process\.env\s*(?:\.\s*ADL_AGENT_ID_AGENT\b|\[\s*['"]ADL_AGENT_ID_AGENT['"]\s*\])/
+/** `delete $ENV{ADL_AGENT_ID_AGENT}` — Perl. */
+const PERL_AGENT_ID_DELETE_RE = /\bdelete\s*\$ENV\{\s*['"]?ADL_AGENT_ID_AGENT['"]?\s*\}/
+
+/** Real shells only — a `-c`/`--command` word is re-scanned as a nested script only when the piece's OWN command is one of these (never `grep -c PATTERN`'s unrelated count flag). */
+const SHELL_NAMES: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'])
+/** python/node/ruby/perl — interpreters whose `-c`/`-e`/`--eval` inline code is inspected by the coarse patterns above. */
+const INTERPRETER_NAMES: ReadonlySet<string> = new Set(['python', 'python2', 'python3', 'node', 'nodejs', 'ruby', 'perl'])
+const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
+
+/**
+ * P2 (independent review, 2026-09-29, "dynamic names"): a strict leading
+ * assignment shape (`^[A-Za-z_][A-Za-z0-9_]*=`), but permitting
+ * `$`/backtick/`{`/`}` in the identifier portion too —
+ * `ADL_HUMAN_AZ${EMPTY}DO=1` is one word after `tokenize` (confirmed
+ * directly), and a real shell WOULD expand `${EMPTY}` before checking
+ * assignment shape, so this is a genuine bypass of a strict identifier
+ * check, not merely cosmetic. Used only to recognize the SHAPE (so a scan
+ * keeps walking past it); `isNameOperandDynamic` below decides whether the
+ * identifier portion is actually dynamic.
+ */
+const ASSIGNMENT_SHAPE_RE = /^[A-Za-z_][\w$`{}]*=/
+
+function isAssignmentTo(value: string, name: string): boolean {
+  return value === `${name}=` || value.startsWith(`${name}=`)
+}
+
+/**
+ * True when `value` — a bare operand (`unset NAME`, `read NAME`, `printf -v
+ * NAME`) or an assignment word (`NAME=value`) — has an unresolved shell
+ * expansion (`$VAR`, `${VAR}`, `$(...)`, backtick) in the NAME portion
+ * (before the first `=`, or the whole word when there is none). We cannot
+ * know what such a word actually names — `v=ADL_HUMAN_AZDO; export "$v=1"`
+ * and `X=ADL_AGENT_ID_AGENT; unset $X` both hide the real name behind a
+ * variable this static scan never resolves — so any setter/clearer-shaped
+ * position holding one is treated as a match (P2 "dynamic names",
+ * fail-closed) for whichever name the caller is checking.
+ */
+function isNameOperandDynamic(value: string): boolean {
+  const equals = value.indexOf('=')
+  const namePart = equals < 0 ? value : value.slice(0, equals)
+  return /[$`]/.test(namePart)
+}
+
+function basenameOf(value: string): string {
+  const index = value.lastIndexOf('/')
+  return index < 0 ? value : value.slice(index + 1)
+}
+
+/** Nested `-c`/`--command` shell script strings are re-tokenized at most this deep. */
+const MAX_WORD_SCAN_DEPTH = 8
+
+/** One piece of a command: its raw tokens (for `skipPrefixes`, which needs a real `Token[]`) alongside their already quote/escape-resolved string values. */
+interface WordPiece {
+  readonly tokens: readonly Token[]
+  readonly values: readonly string[]
+}
+
+/**
+ * Every piece of `command` (one `WordPiece` per top-level piece), collected
+ * into `out`. Recurses one level into a `-c`/`--command` shell script string
+ * ONLY when the piece's own command is a real shell (`SHELL_NAMES`) — never
+ * for an unrelated `-c` flag on some other command (`grep -c`, `curl -c`,
+ * `ssh -c`, …). Quote concatenation and backslash escapes are already
+ * resolved by `tokenize`.
+ */
+/**
+ * `-c`, a combined short flag ENDING in `c` (`-ic`, `-lc`, `-ec` — an
+ * interactive/login/errexit shell still reads its script from the SAME
+ * `-c` operand), or `--command[=]` — mirrors `shell/invocation.ts`'s own
+ * (private) `isShellCommandOption` one-line check, kept in sync
+ * deliberately rather than exported, to recognize a shell invoked with
+ * combined flags (`zsh -ic '...'`, `bash -lc '...'`, `sh -ec '...'`) the
+ * same way the rest of the engine already does (F2, third independent
+ * review, 2026-09-29 — this rule's own exact-`-c`-only check let `zsh -ic
+ * '...'` defeat it entirely).
+ */
+function isShellScriptOption(value: string): boolean {
+  return value === '-c' || /^-[^-]*c$/.test(value) || value === '--command' || value.startsWith('--command=')
+}
+
+/**
+ * Every piece of `command` (one `WordPiece` per top-level piece), collected
+ * into `out`. Recurses one level into a `-c`-shaped shell script string
+ * ONLY when the piece's own RESOLVED command (past a leading assignment and
+ * a chain of transparent wrappers — F2: `nohup bash -c '...'`/`FOO=1 bash
+ * -c '...'` were invisible before, since only the piece's literal FIRST
+ * word was checked) is a real shell (`SHELL_NAMES`) — never for an
+ * unrelated `-c` flag on some other command (`grep -c`, `curl -c`, `ssh
+ * -c`, …). Quote concatenation and backslash escapes are already resolved
+ * by `tokenize`.
+ */
+function collectWordPieces(command: string, depth: number, out: WordPiece[]): void {
+  if (depth > MAX_WORD_SCAN_DEPTH) return
+  const split = splitShell(command)
+  if (split.invalid) return
+  for (const piece of split.pieces) {
+    const tokenized = tokenize(piece)
+    if (tokenized.invalid) continue
+    const values = tokenized.tokens.map(tokenValue)
+    const wordPiece: WordPiece = { tokens: tokenized.tokens, values }
+    out.push(wordPiece)
+    const resolved = resolvedCommand(wordPiece)
+    if (resolved.name === undefined || !SHELL_NAMES.has(resolved.name)) continue
+    for (let index = resolved.argsStart; index < values.length; index += 1) {
+      const value = values[index] as string
+      if (isShellScriptOption(value) && !value.startsWith('--command=')) {
+        if (values[index + 1] !== undefined) collectWordPieces(values[index + 1] as string, depth + 1, out)
+      } else if (value.startsWith('--command=')) {
+        collectWordPieces(value.slice('--command='.length), depth + 1, out)
+      }
+    }
+  }
+}
+
+function wordPiecesFor(command: string): readonly WordPiece[] {
+  const out: WordPiece[] = []
+  collectWordPieces(command, 0, out)
+  return out
+}
+
+/** The `-c`/`-e`/`--eval[=]` argument value for an interpreter invocation, or null when the piece runs a script FILE (nothing inline to inspect). */
+function interpreterInlineCode(args: readonly string[]): string | null {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index] as string
+    if (value === '-c' || value === '-e' || value === '--eval') return args[index + 1] ?? null
+    if (value.startsWith('--eval=')) return value.slice('--eval='.length)
+  }
+  return null
+}
+
+/**
+ * Find the REAL command a piece resolves to, and where ITS OWN arguments
+ * begin — past a leading `NAME=value` assignment and a chain of transparent
+ * wrappers (`sudo`/`env`/`timeout`/`nice`/`caffeinate`/`arch`/`exec`/`time`/
+ * `stdbuf`/`setsid`/`command`/`doas`/`nohup`/`gtimeout`) and THEIR OWN
+ * arguments (P2: "detect... by the walker's RESOLVED command"). Reuses
+ * `../shell/prefixes.ts`'s own `skipPrefixes` — the SAME, already-tested
+ * wrapper-argument-skipping logic every other rule's classification is
+ * built on (`shell/invocation.ts`'s `walk()` calls it too) — rather than a
+ * second, narrower reimplementation: an earlier version of this function
+ * had its own generic "skip one flag at a time" loop, which mishandled a
+ * wrapper's own POSITIONAL argument (`timeout 90 script ...` — `90` is
+ * `timeout`'s duration, not a flag, and a generic dash-flag skipper does
+ * not know to skip it) — `skipPrefixes` already has a specific handler for
+ * exactly that (`skipTimeoutFlags`).
+ */
+function resolvedCommand(piece: WordPiece): { readonly name: string | undefined; readonly argsStart: number } {
+  const index = skipPrefixes(piece.tokens)
+  if (index >= piece.tokens.length) return { name: undefined, argsStart: index }
+  return { name: basenameOf(piece.values[index] as string).toLowerCase(), argsStart: index + 1 }
+}
+
+/** A network git verb, a curl/wget/httpie/xh call to Azure DevOps, `az`, or an `adl`/`adl-agent-id` entry point — the shapes `env -i`/bare `env -` is worth denying for (P1: clearing the WHOLE environment for a command that never needed an identity is harmless). Coarse, matching the same tradeoff every other check in this file makes. */
+function isLikelyIdentityBearing(name: string, args: readonly string[]): boolean {
+  if (name === 'git' || name === 'git.exe') {
+    const subIndex = args.findIndex((value) => !value.startsWith('-'))
+    if (subIndex < 0) return false
+    return isNetworkGitInvocation((args[subIndex] as string).toLowerCase(), args.slice(subIndex + 1))
+  }
+  if (HTTP_CLIENT_BINARY_NAMES.has(name)) return args.some((value) => isAdoUrl(value))
+  if (AZ_NAMES.has(name)) return true
+  if (ADL_BINARY_NAMES.has(name) || ADL_AGENT_ID_BINARY_NAMES.has(name)) return true
+  return false
+}
+
+/**
+ * F3 (third independent review, 2026-09-29): a setter/clearer keyword is
+ * still missed when it is NOT `values[0]` — `if true; then export
+ * ADL_HUMAN_AZDO=1; fi` splits (on `;`) into a piece whose first word is
+ * the keyword `then`, not `export`; `builtin export …`/`command export …`
+ * explicitly invoke the builtin/external form, bypassing any shell
+ * function or alias named `export` but still meaning the same thing. Strip
+ * a leading run of these — pure syntax markers or explicit-invocation
+ * prefixes, none of which take a flag/operand of their own to skip past —
+ * to find the actual setter/clearer keyword underneath. `command` is
+ * ALSO one of `shell/prefixes.ts`'s own `COMMAND_PREFIXES` (so
+ * `resolvedCommand`'s wrapper-chain resolution already skips it too); kept
+ * here as well since this strip runs on plain string VALUES, before (and
+ * independently of) any Token-based `resolvedCommand` call.
+ */
+const HEAD_SKIP_WORDS: ReadonlySet<string> = new Set(['then', 'do', 'else', 'elif', 'builtin', 'command'])
+
+function afterHeadSkipWords(values: readonly string[]): readonly string[] {
+  let rest = values
+  while (rest.length > 0 && HEAD_SKIP_WORDS.has(basenameOf(rest[0] as string).toLowerCase())) {
+    rest = rest.slice(1)
+  }
+  return rest
+}
+
+/** True when `values` (one piece's words) sets/exports/declares/reads-into/printf-v's `ADL_HUMAN_AZDO` in a real setter POSITION, or an interpreter's inline code writes it via `os.environ`/`process.env`/`$ENV`. */
+function pieceSetsHumanAzdo(values: readonly string[], heredocs: readonly string[]): boolean {
+  const name = ADL_HUMAN_AZDO_ENV_VAR
+  let index = 0
+  while (index < values.length && ASSIGNMENT_SHAPE_RE.test(values[index] as string)) {
+    const word = values[index] as string
+    if (isAssignmentTo(word, name) || isNameOperandDynamic(word)) return true
+    index += 1
+  }
+  const resolved = afterHeadSkipWords(values)
+  if (resolved.length === 0) return false
+  const head = basenameOf(resolved[0] as string).toLowerCase()
+  const rest = resolved.slice(1)
+  if (head === 'export') {
+    // `-f` (functions) is unrelated; `-p` (print) is deliberately NOT
+    // excluded here any more (F3) — `export -p ADL_HUMAN_AZDO=1` still
+    // carries an assignment and real bash still exports it, `-p` or not; a
+    // bare `export -p ADL_HUMAN_AZDO` (no `=`, a genuine list/print with no
+    // real effect) is a coarse, low-cost over-match this file already
+    // accepts elsewhere (documented "dynamic names" tradeoff, same file).
+    if (rest.includes('-f')) return false
+    return rest.some((value) => value === name || isAssignmentTo(value, name) || isNameOperandDynamic(value))
+  }
+  if (head === 'declare' || head === 'typeset' || head === 'local') {
+    if (!rest.some((value) => value === '-x' || /^-[a-zA-Z]*x[a-zA-Z]*$/.test(value))) return false
+    return rest.some((value) => value === name || isAssignmentTo(value, name) || isNameOperandDynamic(value))
+  }
+  if (head === 'read') {
+    const target = rest.find((value) => !value.startsWith('-'))
+    return target !== undefined && (target === name || isNameOperandDynamic(target))
+  }
+  if (head === 'printf') {
+    const vIndex = rest.indexOf('-v')
+    if (vIndex < 0) return false
+    const target = rest[vIndex + 1]
+    return target !== undefined && (target === name || isNameOperandDynamic(target))
+  }
+  if (head === 'env') {
+    for (const value of rest) {
+      if (value.startsWith('-')) continue
+      if (!ASSIGNMENT_SHAPE_RE.test(value)) break
+      if (isAssignmentTo(value, name) || isNameOperandDynamic(value)) return true
+    }
+    return false
+  }
+  if (INTERPRETER_NAMES.has(head)) {
+    // Third independent review (2026-09-29): "heredoc-fed interpreters"
+    // (`python3 - <<'EOF' ... EOF`) have no `-c`/`-e`/`--eval` argument at
+    // all — the real code is the heredoc BODY, passed in from `match()`
+    // (computed once from the whole command, not per-piece).
+    const inline = interpreterInlineCode(rest)
+    const candidates = inline !== null ? [inline] : heredocs
+    return candidates.some((code) => PYTHON_HUMAN_AZDO_SET_RE.test(code) || NODE_HUMAN_AZDO_SET_RE.test(code) || PERL_HUMAN_AZDO_SET_RE.test(code))
+  }
+  return false
+}
+
+/** True when `piece` (one piece's words) clears `ADL_AGENT_ID_AGENT` — `unset`/`env -u`/`export -n`/`declare +x`/`typeset +x` in a real clearer POSITION, an empty leading assignment, `env -i` wrapping an identity-bearing command, or an interpreter's inline code deleting it. */
+function pieceClearsAgentIdentity(piece: WordPiece, heredocs: readonly string[]): boolean {
+  const values = piece.values
+  const name = ADL_AGENT_ID_ENV_VAR
+  let index = 0
+  while (index < values.length && ASSIGNMENT_SHAPE_RE.test(values[index] as string)) {
+    const word = values[index] as string
+    if (word === `${name}=`) return true
+    if (isNameOperandDynamic(word) && word.endsWith('=')) return true
+    index += 1
+  }
+  const afterKeywords = afterHeadSkipWords(values)
+  if (afterKeywords.length === 0) return false
+  const head = basenameOf(afterKeywords[0] as string).toLowerCase()
+  const rest = afterKeywords.slice(1)
+  if (head === 'unset') return rest.some((value) => value === name || isNameOperandDynamic(value))
+  if (head === 'export') return rest.includes('-n') && rest.some((value) => value === name || isNameOperandDynamic(value))
+  if (head === 'declare' || head === 'typeset' || head === 'local') return rest.includes('+x') && rest.some((value) => value === name || isNameOperandDynamic(value))
+  if (head === 'env') {
+    for (let look = 0; look < rest.length; look += 1) {
+      const flag = rest[look] as string
+      if ((flag === '-u' || flag === '--unset') && rest[look + 1] !== undefined && (rest[look + 1] === name || isNameOperandDynamic(rest[look + 1] as string))) return true
+      if (flag.startsWith('--unset=') && (flag.slice('--unset='.length) === name || isNameOperandDynamic(flag.slice('--unset='.length)))) return true
+      if (flag === '-i' || flag === '--ignore-environment' || flag === '-') {
+        const resolved = resolvedCommand(piece)
+        return resolved.name !== undefined && isLikelyIdentityBearing(resolved.name, values.slice(resolved.argsStart))
+      }
+      if (!flag.startsWith('-') && !ASSIGNMENT_SHAPE_RE.test(flag)) break
+    }
+    return false
+  }
+  if (INTERPRETER_NAMES.has(head)) {
+    // Third independent review (2026-09-29): heredoc-fed interpreters.
+    const inline = interpreterInlineCode(rest)
+    const candidates = inline !== null ? [inline] : heredocs
+    return candidates.some((code) => PYTHON_AGENT_ID_DELETE_RE.test(code) || NODE_AGENT_ID_DELETE_RE.test(code) || PERL_AGENT_ID_DELETE_RE.test(code))
+  }
+  return false
+}
+
+const LOOPBACK_EXACT: ReadonlySet<string> = new Set(['localhost', '::1', '0'])
+
+/**
+ * F4 (fourth independent review, 2026-09-29): `user@host` (ssh's own
+ * `user@` prefix) is stripped before checking; `127.1`/`127.0.1` (partial
+ * IPv4 notation — every major OS resolves these to the `127.0.0.1` range)
+ * are accepted alongside the full four-octet form.
+ */
+function isLoopbackHost(rawValue: string): boolean {
+  const value = rawValue.includes('@') ? rawValue.slice(rawValue.lastIndexOf('@') + 1) : rawValue
+  const lower = value.toLowerCase()
+  if (LOOPBACK_EXACT.has(lower)) return true
+  return /^127(?:\.\d{1,3}){1,3}$/.test(lower)
+}
+
+/** An unresolved shell expansion in a host-shaped position (F4: `ssh -tt $(hostname) …`) — cannot be proven non-loopback, so treated as a match (fail-closed), the same "dynamic names" tradeoff this file already makes elsewhere. */
+const isDynamicHostCandidate = (value: string): boolean => /\$\(|`|\$\{/.test(value)
+
+function sshForcesTty(args: readonly string[]): boolean {
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index] as string
+    if (value === '-t' || value === '-tt' || /^-[a-zA-Z]*t{1,2}[a-zA-Z]*$/.test(value)) return true
+    const next = args[index + 1]
+    if ((value === '-o' || value === '--') && next !== undefined && /^requesttty=force$/i.test(next)) return true
+    if (/^-o?requesttty=force$/i.test(value.replace(/\s+/g, ''))) return true
+  }
+  return false
+}
+
+/** No legitimate use on an agent surface — see this file's own F1(c) header. `zpty` is zsh's own pty module command — invoked as `zsh -c 'zpty ...'`, this scanner's own `-c` recursion (real shells only) makes `zpty` the RESOLVED command of the nested piece, not merely an argument to `zsh`. */
+const UNCONDITIONAL_PTY_WRAPPERS: ReadonlySet<string> = new Set(['script', 'unbuffer', 'expect', 'zpty'])
+
+/** True when `args` is nothing but `--help`/`-h`/`--version`/`-V` — a string-value mirror of `shell/invocation.ts`'s own (Token-based) `isHelpOrVersionOnly`. F7 (fourth independent review, 2026-09-29): `expect --version` has no script to run at all — harmless. */
+function isHelpOrVersionOnlyValues(args: readonly string[]): boolean {
+  let sawHelp = false
+  for (const arg of args) {
+    if (arg === '--') return false
+    if (!arg.startsWith('-')) return false
+    if (arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V') {
+      sawHelp = true
+      continue
+    }
+    return false
+  }
+  return sawHelp
+}
+
+/** Every `-e CODE` occurrence (F4: `osascript` accepts MULTIPLE `-e` flags, each one a line of the same script — reading only the first, as `interpreterInlineCode` does, missed a script split across several). */
+function allDashEArgs(args: readonly string[]): readonly string[] {
+  const values: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '-e' && args[index + 1] !== undefined) values.push(args[index + 1] as string)
+  }
+  return values
+}
+
+const TMUX_ACTIONS: ReadonlySet<string> = new Set(['new-session', 'new', 'new-window', 'split-window', 'send-keys'])
+/** Bundle IDs for `open -b <id>` — F4: the app-name check (`open -a Terminal`) has no bundle-id equivalent to match against. */
+const TERMINAL_BUNDLE_IDS: ReadonlySet<string> = new Set([
+  'com.apple.terminal',
+  'com.googlecode.iterm2',
+  'com.mitchellh.ghostty',
+  'dev.warp.warp-stable',
+  'net.kovidgoyal.kitty',
+  'org.alacritty',
+  'com.github.wez.wezterm',
+])
+/** Terminal-app names `open -a`/AppleScript/JXA name by — F4: widened past Terminal/iTerm to every terminal emulator the finding named. */
+const TERMINAL_APP_NAME_RE = /\b(?:terminal|iterm|ghostty|warp|kitty|alacritty|wezterm)\b/i
+
+/** True when `piece` (one piece's words) invokes a pty-faking wrapper, resolved past a leading assignment and a chain of transparent wrappers. See this file's own F1(c) header for which shapes are unconditional vs. narrowed to a loopback host. */
+function pieceUsesPtyFakingWrapper(piece: WordPiece): boolean {
+  const resolved = resolvedCommand(piece)
+  const name = resolved.name
+  if (name === undefined) return false
+  const args = piece.values.slice(resolved.argsStart)
+  if (UNCONDITIONAL_PTY_WRAPPERS.has(name)) return !isHelpOrVersionOnlyValues(args)
+  if (name === 'socat') return args.some((value) => /\bpty\b/i.test(value))
+  if (name === 'tmux') return args.some((value) => TMUX_ACTIONS.has(value) || value === '-dm' || value === '-dmS')
+  if (name === 'screen') {
+    if (args.some((value) => value === '-dm' || value === '-dmS')) return true
+    return args.includes('-d') && args.includes('-m')
+  }
+  if (name === 'ruby') {
+    if (args.includes('-rpty')) return true
+    const code = interpreterInlineCode(args)
+    return code !== null && /require\s+['"]pty['"]/.test(code)
+  }
+  if (name === 'perl' && args.includes('-MIO::Pty')) return true
+  if (INTERPRETER_NAMES.has(name)) {
+    const code = interpreterInlineCode(args)
+    if (code === null) return false
+    // F4: comma-form imports (`import os, pty`) and `__import__('pty')`.
+    if (name.startsWith('python')) {
+      return (
+        /(?:^|[\s;])import\s+(?:[\w.]+\s*,\s*)*pty\b|\bfrom\s+pty\s+import\b|\bpty\.(?:spawn|fork|openpty)\s*\(|__import__\(\s*['"]pty['"]\s*\)/.test(
+          code,
+        )
+      )
+    }
+    if (name.startsWith('node')) return /\brequire\(\s*['"](?:node-)?pty['"]\s*\)/.test(code)
+    return false
+  }
+  if (name === 'ssh') {
+    if (!sshForcesTty(args)) return false
+    if (args.some(isLoopbackHost)) return true
+    return args.some((value) => !value.startsWith('-') && isDynamicHostCandidate(value))
+  }
+  if (name === 'open') {
+    for (let index = 0; index < args.length; index += 1) {
+      const value = args[index] as string
+      // F4: combined flags (`-na` = -n new-instance + -a app) — any
+      // combined short-flag string containing `a`/`b` still takes the
+      // NEXT word as the app name / bundle id, same as the bare flag.
+      if (/^-[a-zA-Z]*a[a-zA-Z]*$/.test(value) && TERMINAL_APP_NAME_RE.test(args[index + 1] ?? '')) return true
+      if (/^-[a-zA-Z]*b[a-zA-Z]*$/.test(value) && TERMINAL_BUNDLE_IDS.has((args[index + 1] ?? '').toLowerCase())) return true
+    }
+    return args.some((value) => value.toLowerCase().endsWith('.command'))
+  }
+  if (name === 'osascript') {
+    const codes = allDashEArgs(args)
+    if (codes.length === 0) return false
+    const combined = codes.join('\n')
+    if (!TERMINAL_APP_NAME_RE.test(combined)) return false
+    // F4: AppleScript's `do script` and JXA's (`-l JavaScript`) `.doScript(`
+    // are the same operation in the two languages osascript accepts.
+    return /\bdo script\b/i.test(combined) || /\.\s*doScript\s*\(/i.test(combined)
+  }
+  return false
+}
+
+type BypassReason = 'sets-human-azdo' | 'clears-agent-identity' | 'pty-faking-wrapper'
+
+export const adlHumanAzdoBypass: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary:
+    "Deny an agent command that sets/exports/assigns ADL_HUMAN_AZDO, clears ADL_AGENT_ID_AGENT, or fakes a TTY to defeat bin/git-ado's human/agent decision (STATUS.md 12p decisions 1/1b/1c; F1).",
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    // A tool-call payload (a real MCP call) carries no shell command text
+    // at all — nothing for this word-level scan to see.
+    if (inv.kind === 'tool-call') return null
+    const command = ctx.command ?? ''
+    if (command.trim().length === 0) return null
+    const pieces = wordPiecesFor(command)
+    // Third independent review (2026-09-29): heredoc-fed interpreters
+    // (`python3 - <<'EOF' ... EOF`) have no `-c`/`-e`/`--eval` argument at
+    // all — computed once from the whole command, not per-piece.
+    const heredocs = heredocBodies(command)
+    let reason: BypassReason | null = null
+    for (const piece of pieces) {
+      if (pieceSetsHumanAzdo(piece.values, heredocs)) {
+        reason = 'sets-human-azdo'
+        break
+      }
+      if (pieceClearsAgentIdentity(piece, heredocs)) {
+        reason = 'clears-agent-identity'
+        break
+      }
+      if (pieceUsesPtyFakingWrapper(piece)) {
+        reason = 'pty-faking-wrapper'
+        break
+      }
+    }
+    if (reason === null) return null
+    // Reuse the ONE shared human-pass-through check rather than asserting
+    // the same fact independently: a pre-tool-use hook invocation reads a
+    // JSON payload from its host, never an interactive TTY, so this can
+    // never legitimately be a marked-human session — `stdinIsTTY` is
+    // explicitly `false` here, by construction, not merely assumed.
+    const consideredHuman = isMarkedHumanAzdoCaller({ [ADL_HUMAN_AZDO_ENV_VAR]: ctx.env.get(ADL_HUMAN_AZDO_ENV_VAR) } as NodeJS.ProcessEnv, false)
+    return { ruleId: RULE_ID, severity: 'deny', detail: { consideredHuman: String(consideredHuman), reason } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const reason = (typeof finding.detail.reason === 'string' ? finding.detail.reason : 'sets-human-azdo') as BypassReason
+    if (reason === 'clears-agent-identity') {
+      const user = `clearing ${ADL_AGENT_ID_ENV_VAR} is not allowed — an agent must always carry its identity`
+      return {
+        user,
+        agent:
+          `DENIED ${user}. unset/env -u/env -i (wrapping an identity-bearing command)/an empty inline assignment/export -n/` +
+          `declare or typeset +x on ${ADL_AGENT_ID_ENV_VAR} removes the one thing that routes a network git command as this ` +
+          `agent instead of falling through to bin/git-ado's own default (F1, STATUS.md 12p). Never clear it; prefix the ` +
+          `command with ${ADL_AGENT_ID_ENV_VAR}=<agent> instead. Blocked: ${ctx.snippet}`,
+      }
+    }
+    if (reason === 'pty-faking-wrapper') {
+      const user =
+        'faking a TTY (script/unbuffer/expect, socat/tmux/screen/zsh zpty, a pty-module interpreter one-liner, ssh -t to a loopback host, or launching a real terminal app) is not allowed'
+      return {
+        user,
+        agent:
+          `DENIED ${user}. These tools exist to make a program's isatty() check pass when nothing real is attached to it — ` +
+          "bin/git-ado's own human-vs-agent decision is exactly such a check, and faking it (F1, STATUS.md 12p) is how a " +
+          'session with no agent identity reaches the human credential path undetected. There is no legitimate use of a ' +
+          `pty-faking wrapper on an agent surface; run the command directly instead. Blocked: ${ctx.snippet}`,
+      }
+    }
+    const user = `${ADL_HUMAN_AZDO_ENV_VAR} marks a human terminal; an agent may never set it — use ADL_AGENT_ID_AGENT=<agent>`
+    return {
+      user,
+      agent:
+        `DENIED ${user}. ${ADL_HUMAN_AZDO_ENV_VAR}=1 tells bin/git-ado this is Tarun's own interactive terminal - setting, exporting, ` +
+        `or assigning it from an agent surface (inline, export, env, declare/typeset -x, printf -v, read, a nested REAL shell — ` +
+        `quote-split or backslash-escaped included, F1 — or an interpreter's own os.environ/process.env/$ENV) would let ` +
+        `git-ado's human pass-through apply with no agent identity involved. Unset it (or use \`env -u ${ADL_HUMAN_AZDO_ENV_VAR}\`) ` +
+        `if you need it absent; prefix the command with ADL_AGENT_ID_AGENT=<agent-tarun|agent-vivek|agent-reviewer> instead. ` +
+        `Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [
+      'ADL_HUMAN_AZDO=1 git push origin main',
+      'export ADL_HUMAN_AZDO=1',
+      'export ADL_HUMAN_AZDO=1 && git push origin main',
+      'env ADL_HUMAN_AZDO=1 git push origin main',
+      'declare -x ADL_HUMAN_AZDO=1',
+      'typeset -x ADL_HUMAN_AZDO=1',
+      'export ADL_HUMAN_AZDO',
+      "bash -c 'export ADL_HUMAN_AZDO=1 && git push origin main'",
+      `python3 -c "import os; os.environ['ADL_HUMAN_AZDO'] = '1'"`,
+      `node -e "process.env.ADL_HUMAN_AZDO = '1'"`,
+      `node -e "process.env['ADL_HUMAN_AZDO'] = '1'"`,
+      // F1(a): shell quote-splitting / backslash-escaping cannot defeat the
+      // check any more — the tokenizer resolves both before matching.
+      `export ADL_HUMAN_AZD''O=1`,
+      `export ADL_HUMAN_AZ\\DO=1`,
+      // A bare `printf ...` line alone produces no Invocation at all
+      // (`printf` is in shell/invocation.ts's own `introspectionNames`, so
+      // `decideCommand`'s per-invocation loop never runs) — realistic usage
+      // always chains it with the command it is trying to unlock, which is
+      // also what makes the loop run at all.
+      `printf -v ADL_HUMAN_AZDO '1'; git push origin main`,
+      'read ADL_HUMAN_AZDO',
+      // F1(b): clearing ADL_AGENT_ID_AGENT in any form.
+      'unset ADL_AGENT_ID_AGENT',
+      'unset ADL_AGENT_ID_AGENT; git push origin feat/x',
+      'env -u ADL_AGENT_ID_AGENT git push origin feat/x',
+      'env --unset ADL_AGENT_ID_AGENT git push origin feat/x',
+      'env --unset=ADL_AGENT_ID_AGENT git push origin feat/x',
+      'env -i git push origin feat/x',
+      'env --ignore-environment git push origin feat/x',
+      'ADL_AGENT_ID_AGENT= git push origin feat/x',
+      'export -n ADL_AGENT_ID_AGENT',
+      'declare +x ADL_AGENT_ID_AGENT',
+      // F1(c): pty-faking wrappers, unconditional.
+      'script -q /dev/null git push origin feat/x',
+      'unbuffer git push origin feat/x',
+      'expect -c "spawn git push origin feat/x"',
+      "socat exec:'git push origin feat/x',pty stdio",
+      `python3 -c "import pty; pty.spawn(['git','push','origin','feat/x'])"`,
+      'ssh -t localhost git push origin feat/x',
+      'ssh -t 127.0.0.1 git push origin feat/x',
+      // The live F1 incident, combined.
+      "export ADL_HUMAN_AZD''O=1; unset ADL_AGENT_ID_AGENT; script -q /dev/null git push origin feat/x",
+    ],
+    allow: [
+      'git status',
+      'ADL_AGENT_ID_AGENT=agent-tarun git push origin feat/x',
+      // Unsetting HUMAN_AZDO is explicitly fine — only SETTING it is denied.
+      'env -u ADL_HUMAN_AZDO git status',
+      'unset ADL_HUMAN_AZDO',
+      // Unsetting an unrelated variable, or exporting one, is untouched.
+      'unset SOME_OTHER_VAR',
+      'export PATH=/usr/bin:$PATH',
+      // ssh -t to a genuine remote host: ordinary, common usage.
+      'ssh -t build-host.example.com uptime',
+      // socat without a pty argument: unrelated.
+      'socat TCP:example.com:80 -',
+      // A bare python/node one-liner naming neither variable: untouched.
+      `python3 -c "print('hello')"`,
+      // SECOND REVIEW (2026-09-29): the false positives that broke normal
+      // agent work — a mention of the name in an unrelated command's
+      // argument, a read (not a set), an unrelated `-c` flag mistaken for
+      // shell `-c`, a bare 'pty' word, and env -i clearing the WHOLE
+      // environment for a command that never needed an identity.
+      'git commit -m "ADL_HUMAN_AZDO=1 is denied now"',
+      'git log -S "ADL_HUMAN_AZDO=1"',
+      'declare -p ADL_HUMAN_AZDO',
+      // `rg`, not `grep` — `tool.grep` denies grep outright, unrelated to
+      // this rule; the point here is `-c` (rg's own count flag) not being
+      // mistaken for shell `-c`.
+      "bun -e '1' && rg -c 'unset ADL_AGENT_ID_AGENT' STATUS.md",
+      `node -e "console.log('pty')"`,
+      'env -i PATH=/usr/bin ls',
+    ],
+  },
+}