@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

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

@@ -1,5 +1,6 @@
 /**
- * `adl.human-azdo-bypass` — STATUS.md 12p decisions 1/1b/1c:
+ * `adl.human-azdo-bypass` — the human pass-through in `bin/git-ado` fails
+ * closed and the human opts in (Tarun, 2026-09-29):
  * `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`:
@@ -11,17 +12,17 @@
  * 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).
+ * Three shapes are denied (a/b/c below). An independent review
+ * (2026-09-29) found the live bypass they close: `export ADL_HUMAN_AZD''O=1;
+ * unset ADL_AGENT_ID_AGENT; script -q /dev/null git push origin feat/x`
+ * reached `bin/git-ado`'s human pass-through via a faked pty.
  *
- * 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
+ * Detection is POSITIONAL, not "any word anywhere", because a looser scan
+ * 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":
+ * "console.log('pty')"` (a bare word 'pty' in unrelated code) would all be
+ * wrongly denied:
  *
  *  (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
@@ -48,7 +49,7 @@
  *  (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`
+ *      `export -n NAME`, `declare +x NAME`/`typeset +x NAME` (`+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`
@@ -62,8 +63,8 @@
  *      `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
+ *      `screen` starting a detached session with a command
+ *      (`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
@@ -84,7 +85,7 @@
  *      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);
+ * strings, or `$(...)`/backtick substitutions (out of scope for this rule);
  * 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.
@@ -98,8 +99,8 @@
  * 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").
+ * THE PTY-FAKING-WRAPPER CLASS IS UNBOUNDED (independent review,
+ * 2026-09-29: widen once, 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
@@ -109,12 +110,11 @@
  * 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
+ * diminishing return: the list as it stands 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.
+ * a human") is a separate track with Tarun, not something this rule can
+ * substitute for by enumerating tools forever.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
@@ -132,13 +132,13 @@ 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
+ * The exact env var name `bin/git-ado` checks for the human pass-through. 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'
+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*[=(]/
@@ -161,7 +161,7 @@ const INTERPRETER_NAMES: ReadonlySet<string> = new Set(['python', 'python2', 'py
 const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
 
 /**
- * P2 (independent review, 2026-09-29, "dynamic names"): a strict leading
+ * Dynamic names (independent review, 2026-09-29): 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
@@ -185,7 +185,7 @@ function isAssignmentTo(value: string, name: string): boolean {
  * 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",
+ * position holding one is treated as a match (dynamic names,
  * fail-closed) for whichever name the caller is checking.
  */
 function isNameOperandDynamic(value: string): boolean {
@@ -223,9 +223,8 @@ interface WordPiece {
  * (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).
+ * same way the rest of the engine already does (an exact-`-c`-only
+ * check would let `zsh -ic '...'` defeat this rule entirely).
  */
 function isShellScriptOption(value: string): boolean {
   return value === '-c' || /^-[^-]*c$/.test(value) || value === '--command' || value.startsWith('--command=')
@@ -235,9 +234,9 @@ function isShellScriptOption(value: string): boolean {
  * 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
+ * a chain of transparent wrappers: `nohup bash -c '...'`/`FOO=1 bash
+ * -c '...'` would be invisible if only the piece's literal FIRST
+ * word were 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`.
@@ -286,7 +285,7 @@ function interpreterInlineCode(args: readonly string[]): string | null {
  * 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
+ * arguments (detection is 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
@@ -303,7 +302,7 @@ function resolvedCommand(piece: WordPiece): { readonly name: string | undefined;
   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. */
+/** 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 (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('-'))
@@ -317,8 +316,7 @@ function isLikelyIdentityBearing(name: string, args: readonly string[]): boolean
 }
 
 /**
- * F3 (third independent review, 2026-09-29): a setter/clearer keyword is
- * still missed when it is NOT `values[0]` — `if true; then export
+ * A setter/clearer keyword can be 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
@@ -356,7 +354,7 @@ function pieceSetsHumanAzdo(values: readonly string[], heredocs: readonly string
   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
+    // excluded here — `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
@@ -387,8 +385,7 @@ function pieceSetsHumanAzdo(values: readonly string[], heredocs: readonly string
     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
+    // 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)
@@ -430,7 +427,7 @@ function pieceClearsAgentIdentity(piece: WordPiece, heredocs: readonly string[])
     return false
   }
   if (INTERPRETER_NAMES.has(head)) {
-    // Third independent review (2026-09-29): heredoc-fed interpreters.
+    // 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))
@@ -441,7 +438,7 @@ function pieceClearsAgentIdentity(piece: WordPiece, heredocs: readonly string[])
 const LOOPBACK_EXACT: ReadonlySet<string> = new Set(['localhost', '::1', '0'])
 
 /**
- * F4 (fourth independent review, 2026-09-29): `user@host` (ssh's own
+ * `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.
@@ -453,7 +450,7 @@ function isLoopbackHost(rawValue: string): boolean {
   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. */
+/** An unresolved shell expansion in a host-shaped position (`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 {
@@ -467,10 +464,10 @@ function sshForcesTty(args: readonly string[]): boolean {
   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`. */
+/** No legitimate use on an agent surface — see this file's own header, part (c). `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. */
+/** True when `args` is nothing but `--help`/`-h`/`--version`/`-V` — a string-value mirror of `shell/invocation.ts`'s own (Token-based) `isHelpOrVersionOnly`. `expect --version` has no script to run at all — harmless. */
 function isHelpOrVersionOnlyValues(args: readonly string[]): boolean {
   let sawHelp = false
   for (const arg of args) {
@@ -485,7 +482,7 @@ function isHelpOrVersionOnlyValues(args: readonly string[]): boolean {
   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). */
+/** Every `-e CODE` occurrence (`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) {
@@ -495,7 +492,7 @@ function allDashEArgs(args: readonly string[]): readonly string[] {
 }
 
 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. */
+/** Bundle IDs for `open -b <id>`: 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',
@@ -505,10 +502,10 @@ const TERMINAL_BUNDLE_IDS: ReadonlySet<string> = new Set([
   '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. */
+/** Terminal-app names `open -a`/AppleScript/JXA name by — covers every common terminal emulator, not only Terminal/iTerm. */
 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. */
+/** 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 header, part (c), for which shapes are unconditional vs. narrowed to a loopback host. */
 function pieceUsesPtyFakingWrapper(piece: WordPiece): boolean {
   const resolved = resolvedCommand(piece)
   const name = resolved.name
@@ -530,7 +527,7 @@ function pieceUsesPtyFakingWrapper(piece: WordPiece): boolean {
   if (INTERPRETER_NAMES.has(name)) {
     const code = interpreterInlineCode(args)
     if (code === null) return false
-    // F4: comma-form imports (`import os, pty`) and `__import__('pty')`.
+    // 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(
@@ -549,7 +546,7 @@ function pieceUsesPtyFakingWrapper(piece: WordPiece): boolean {
   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 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
@@ -562,7 +559,7 @@ function pieceUsesPtyFakingWrapper(piece: WordPiece): boolean {
     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(`
+    // 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)
   }
@@ -577,7 +574,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
   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).",
+    "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.",
   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
@@ -586,7 +583,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
     const command = ctx.command ?? ''
     if (command.trim().length === 0) return null
     const pieces = wordPiecesFor(command)
-    // Third independent review (2026-09-29): heredoc-fed interpreters
+    // 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)
@@ -623,7 +620,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
         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 ` +
+          `agent instead of falling through to bin/git-ado's own default. Never clear it; prefix the ` +
           `command with ${ADL_AGENT_ID_ENV_VAR}=<agent> instead. Blocked: ${ctx.snippet}`,
       }
     }
@@ -634,7 +631,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
         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 " +
+          "bin/git-ado's own human-vs-agent decision is exactly such a check, and faking it 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}`,
       }
@@ -645,7 +642,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       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 ` +
+        `quote-split or backslash-escaped included — 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}`,
@@ -664,7 +661,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       `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
+      // 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`,
@@ -675,7 +672,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       // 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.
+      // 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',
@@ -686,7 +683,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       '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.
+      // 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"',
@@ -694,7 +691,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       `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.
+      // The live bypass found by the independent review, combined.
       "export ADL_HUMAN_AZD''O=1; unset ADL_AGENT_ID_AGENT; script -q /dev/null git push origin feat/x",
     ],
     allow: [
@@ -712,7 +709,7 @@ export const adlHumanAzdoBypass: RuleSpec = {
       '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
+      // False positives a looser scan produced on 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

package/packages/agent-hooks/src/rules/impl/adl-identity.ts

@@ -1,11 +1,11 @@
 /**
  * `ADL_AGENT_ID_AGENT`, read the same way by every rule that keys behaviour
- * off the session's agent identity (docs/operations/agent-permissions.md, docs/architecture/cli-design.md
- * decision 2).
+ * off the session's agent identity (docs/operations/agent-permissions.md,
+ * docs/architecture/cli-design.md §1c).
  *
- * The one-agent-identity standard (STATUS.md 12p)
- * makes `packages/azdo/src/lib/agent-identity.ts` the ONE Azure DevOps
- * identity resolver in this repo; this file no longer keeps its own copy of
+ * The one-agent-identity standard (Tarun, 2026-09-28) makes
+ * `packages/azdo/src/lib/agent-identity.ts` the ONE Azure DevOps identity
+ * resolver in this repo; this file keeps no copy of
  * `VALID_AGENTS`/`NO_AGENT_IDENTITY_MESSAGE`/the default-agent-file read — it
  * imports them, and `BUILDER_AGENTS` derives from `VALID_AGENTS` rather than
  * naming `AGENT_TARUN`/`AGENT_VIVEK` a second time.
@@ -15,16 +15,13 @@ import {
   NO_AGENT_IDENTITY_MESSAGE,
   resolveAgentIdentity,
   VALID_AGENTS,
-  type ValidAgent,
 } from '../../../../azdo/src/lib/agent-identity.ts'
 import type { EnvPort } from '../ports.ts'
 
-export { isValidAgent, NO_AGENT_IDENTITY_MESSAGE, VALID_AGENTS, type ValidAgent }
+export { isValidAgent, NO_AGENT_IDENTITY_MESSAGE }
 
 export const ADL_AGENT_ID_ENV_VAR = 'ADL_AGENT_ID_AGENT'
 export const AGENT_REVIEWER = 'agent-reviewer'
-export const AGENT_TARUN = 'agent-tarun'
-export const AGENT_VIVEK = 'agent-vivek'
 
 /** The two-branch standard's builders (docs/specs/two-branch-standard-2026-09-27.md §1b.1): cut a feature branch from `integration`, create their own PRs into it. Every VALID_AGENTS member except agent-reviewer. */
 export const BUILDER_AGENTS: ReadonlySet<string> = new Set(VALID_AGENTS.filter((name) => name !== AGENT_REVIEWER))
@@ -38,21 +35,18 @@ export const BUILDER_AGENTS: ReadonlySet<string> = new Set(VALID_AGENTS.filter((
  * set it to a path that does not exist -- see `resolveFromEnvOrFile`'s doc.
  * Never the real system path (AGENTS.md: tests are hermetic).
  */
-export const DEFAULT_AGENT_FILE_OVERRIDE_ENV = 'ADL_DEFAULT_AGENT_FILE'
+const DEFAULT_AGENT_FILE_OVERRIDE_ENV = 'ADL_DEFAULT_AGENT_FILE'
 
-// L3 (STATUS.md 12p): `currentAgent` — the
-// session-env-only read this file used to export for
-// `../../hooks/lean-ctx/scope-rewrite.ts`'s `sessionIdentityOf` — was
-// removed here (not merely superseded) once that caller switched to
+// There is deliberately no session-env-only `currentAgent` read here:
+// `../../hooks/lean-ctx/scope-rewrite.ts`'s `sessionIdentityOf` calls
 // `resolveFromEnvOrFile` (steps 2-3 of the standard: env, THEN the machine
-// default-agent file). It had no other caller left, so it stayed as dead,
-// uncovered code rather than a function this file's own contract still
-// needs — bunfig.toml's coverage policy has no ignore-list for exactly this
+// default-agent file), so a function that read the env alone would have no
+// caller. bunfig.toml's coverage policy has no ignore-list for exactly this
 // reason: a function nothing calls gets deleted, not exempted.
 
-export type IdentitySource = 'env' | 'default-file'
+type IdentitySource = 'env' | 'default-file'
 
-export interface ResolvedIdentity {
+interface ResolvedIdentity {
   readonly ok: true
   readonly agent: string
   readonly source: IdentitySource
@@ -68,7 +62,7 @@ export interface ResolvedIdentity {
  * identity, here is how to set one" is a different problem from "an agent
  * identity IS configured and it is wrong."
  */
-export interface UnresolvedIdentity {
+interface UnresolvedIdentity {
   readonly ok: false
   readonly reason: 'none' | 'invalid'
   readonly message: string
@@ -77,9 +71,8 @@ export interface UnresolvedIdentity {
 export type IdentityResolution = ResolvedIdentity | UnresolvedIdentity
 
 /**
- * Steps 2-3 of the standard (STATUS.md 12p, "The
- * standard"): `ADL_AGENT_ID_AGENT` from the session environment, else the
- * machine default-agent file, else unresolved. Step 1 (an inline
+ * Steps 2-3 of the standard: `ADL_AGENT_ID_AGENT` from the session
+ * environment, else the machine default-agent file, else unresolved. Step 1 (an inline
  * `ADL_AGENT_ID_AGENT=<agent>` prefix on the command itself) is NOT this
  * function's job — that is a property of the command text, resolved by
  * `../shell/git-identity.ts`'s scanner, which calls this function only for

package/packages/agent-hooks/src/rules/impl/adl-mcp-cli.ts

@@ -1,7 +1,9 @@
 /**
  * `adl mcp cli <command> [options]` → the equivalent MCP tool call, for the
- * role rules that must grade it EXACTLY like the real MCP tool call (M4,
- * STATUS.md 12p): `docs/operations/agent-permissions.md`
+ * role rules that must grade it EXACTLY like the real MCP tool call.
+ * MCP is the primary route to Azure DevOps operations and `adl mcp cli` is
+ * the fallback for when MCP is not working, so both surfaces share one grade:
+ * `docs/operations/agent-permissions.md`
  * gates the tool, not the surface it was invoked through, and `adl mcp cli`
  * (`packages/azdo/src/cli.ts`'s `runCli`) dispatches to the SAME
  * `dispatchTool` the MCP server itself calls — a caller who runs
@@ -134,7 +136,7 @@ export function adlMcpCliCall(inv: Invocation): AdlMcpCliCall | null {
 
 /**
  * The `{tool, input}` pair for `inv`, whether it is a real MCP tool-call
- * payload or an equivalent `adl mcp cli <command>` shell invocation (M4) —
+ * payload or an equivalent `adl mcp cli <command>` shell invocation —
  * or `null` when `inv` is neither. Every role rule that used to check only
  * `inv.kind === 'tool-call'` calls this instead, so a caller cannot route
  * around role grading just by using the CLI form of the same tool.
@@ -145,19 +147,20 @@ export function toolCallFor(inv: Invocation): AdlMcpCliCall | null {
 }
 
 /**
- * R5 (STATUS.md 12p, re-review 2026-09-28 night): the
- * EFFECTIVE identity for THIS specific `adl mcp cli <command>` invocation —
- * the same M2/M3 correlation `impl/adl-git-push-policy.ts`'s
- * `effectiveIdentityForPush` already gives `git push`, extended to this
- * command class. Before this fix, `adl-workitem-role.ts`/`adl-pr-role.ts`/
- * `adl-pr-review-role.ts` graded `resolveFromEnvOrFile(ctx.env)` alone —
- * ignoring a valid inline `ADL_AGENT_ID_AGENT=` override on the very piece
- * being graded, so a reviewer session's own inline `agent-tarun` override on
- * `adl mcp cli workitem-create-or-update` was denied as `agent-reviewer`
- * regardless (a false deny), and — the more dangerous direction R5 actually
- * names — a `agent-tarun` SESSION with an inline `ADL_AGENT_ID_AGENT=agent-
- * reviewer` override was graded as `agent-tarun` (a false ALLOW: the piece
- * that will actually run is `agent-reviewer`'s).
+ * The EFFECTIVE identity for THIS specific `adl mcp cli <command>`
+ * invocation — the same per-piece correlation
+ * `impl/adl-git-push-policy.ts`'s `effectiveIdentityForPush` gives
+ * `git push`, extended to this command class. The role rules
+ * (`adl-workitem-role.ts`/`adl-pr-role.ts`/`adl-pr-review-role.ts`) grade this
+ * value, not `resolveFromEnvOrFile(ctx.env)` alone, because a valid inline
+ * `ADL_AGENT_ID_AGENT=` override on the very piece being graded wins. Grading
+ * the session identity alone would be wrong in both directions: a reviewer
+ * session's own inline `agent-tarun` override on
+ * `adl mcp cli workitem-create-or-update` would be denied as `agent-reviewer`
+ * (a false deny), and — the more dangerous direction — an `agent-tarun`
+ * SESSION with an inline `ADL_AGENT_ID_AGENT=agent-reviewer` override would be
+ * graded as `agent-tarun` (a false ALLOW: the piece that will actually run is
+ * `agent-reviewer`'s).
  *
  * A `tool-call`-kind `inv` (a real MCP tool call, not the CLI shell form)
  * carries no command text at all — no inline override is possible for it —

package/packages/agent-hooks/src/rules/impl/adl-pr-complete-pending.ts

@@ -36,10 +36,10 @@ export const adlPrCompletePendingDecision: RuleSpec = {
   severity: 'deny',
   enabledByDefault: true,
   summary:
-    'Deny PR completion / auto-complete for every identity — open decision (docs/operations/agent-permissions.md row 9) — the MCP tool AND its adl mcp cli equivalent (M4).',
+    'Deny PR completion / auto-complete for every identity — open decision (docs/operations/agent-permissions.md row 9) — the MCP tool AND its adl mcp cli equivalent.',
   params: noParams,
   match(inv: Invocation): Finding | null {
-    // M4 (STATUS.md 12p): `adl mcp cli
+    // `adl mcp cli
     // pr-create-or-update` is the SAME tool `adl.pr-create-update-role`
     // steps aside for on this shape — without this, the CLI form of a
     // completion call would sail through both rules.

package/packages/agent-hooks/src/rules/impl/adl-pr-review-role.ts

@@ -2,7 +2,7 @@
  * `adl.pr-review-role` — docs/operations/agent-permissions.md rows 6-8 (PR comment; PR
  * vote on `main`; PR vote on `integration`), the sibling `adl-pr-role.ts`'s
  * own header named as PENDING until `packages/azdo` shipped a comment/vote
- * tool (C3, `pr_review`). Gates the ONE MCP tool that ships that shape,
+ * tool (`pr_review`). Gates the ONE MCP tool that ships that shape,
  * `pr_review({ pullRequestId, comment?, vote?, targetBranch?, repository? })`
  * — see `packages/azdo/src/azdo-pr-review.ts`.
  *
@@ -31,7 +31,7 @@
  *  caller cannot route around by skipping the hook.
  *
  * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
- * non-blank) — with no identity at all, `adl.session-required-for-writes`
+ * non-blank) — with no identity at all, `adl.run-required-for-writes`
  * denies the call first (a different problem: no session, not the wrong
  * role or branch), so this rule returns null when the env var is absent or
  * blank, matching `adl-pr-role.ts`'s own convention exactly.
@@ -72,16 +72,14 @@ export const adlPrReviewRole: RuleSpec = {
     'Gate pr_review: comment for a builder or agent-reviewer (row 6); vote for agent-reviewer only, main only, fail-closed without a declared target (rows 7-8).',
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
-    // M4 (STATUS.md 12p): `adl mcp cli
-    // pr-review` dispatches to the same tool the MCP server calls.
+    // `adl mcp cli pr-review` dispatches to the same tool the MCP server calls.
     const call = toolCallFor(inv)
     if (call === null) return null
     if (mcpToolName(call.tool) !== 'pr_review') return null
 
-    // R5 (STATUS.md 12p, re-review 2026-09-28 night):
-    // grade the EFFECTIVE identity for THIS specific piece — a valid inline
+    // Grade the EFFECTIVE identity for THIS specific piece — a valid inline
     // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation
-    // still wins, exactly like M3 already does for `git push` (see
+    // still wins, exactly like it does for `git push` (see
     // `effectiveIdentityForMcpCli`'s own doc). A real MCP tool-call payload
     // carries no command text at all (no inline override possible), so this
     // still resolves to the plain session identity for that shape — env,
@@ -90,19 +88,18 @@ export const adlPrReviewRole: RuleSpec = {
     const resolution = resolveFromEnvOrFile(ctx.env)
     const fallback = resolution.ok ? resolution.agent : null
     const agent = effectiveIdentityForMcpCli(inv, ctx.command ?? '', fallback)
-    if (agent === null) return null // no identity at all: adl.session-required-for-writes's job
+    if (agent === null) return null // no identity at all: adl.run-required-for-writes's job
 
     const input = call.input as PrReviewInput
 
     // Row 6: comment — the more fundamental restriction when present, same
     // allow-set as row 5, checked first regardless of whether a vote is ALSO
-    // on this call. W2 build item 2 (2026-09-28): `agent` is now guaranteed
+    // on this call. `agent` is guaranteed
     // a VALID_AGENTS member whenever it is non-null (resolveFromEnvOrFile
     // validates it), and BUILDER_AGENTS ∪ {agent-reviewer} already IS all of
     // VALID_AGENTS for this row — so `!isAllowedToComment(agent)` can never
-    // be true through any real resolved identity any more (same fact
-    // adl-pr-role.ts's sibling check already lived with, one line, before
-    // this widening). Kept as defense in depth for a future VALID_AGENTS
+    // be true through any real resolved identity (same fact
+    // adl-pr-role.ts's sibling check already lives with). Kept as defense in depth for a future VALID_AGENTS
     // member this allow-set does not name, in the same single-physical-line
     // shape adl-pr-role.ts already uses for its own now-unreachable check —
     // see rules-adl-pr-role.test.ts's "denial message is exact" describe