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

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

@@ -19,17 +19,15 @@
  * 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
+ * human. What this file (and `impl/adl-run-required.ts`'s deny side)
+ * actually TREATS as network is wider — 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 the `bin/git` front controller's
+ * own narrower routing there — the transport helpers,
+ * `git submodule update|sync --recursive`, `git archive --remote`); the bare
+ * five-verb `NETWORK_GIT_VERBS` set is only what the git-ado credential path
+ * itself was first built around. 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)
@@ -76,8 +74,8 @@ import {
 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`
+ * Network-reaching git shapes beyond the bare verb set —
+ * 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
@@ -98,9 +96,9 @@ export const NETWORK_GIT_VERBS: ReadonlySet<string> = new Set(['fetch', 'pull',
  * 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
+ * Used by BOTH sides `adl.run-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
+ * (`impl/adl-run-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.
  */
@@ -130,7 +128,7 @@ export function isNetworkGitInvocation(subcommand: string, restValues: readonly
   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
+    // `--init` clones every submodule
     // not yet checked out — network, same as `--recursive` recursing into
     // nested ones.
     return restValues.some((value) => value === '--recursive' || value === '--init')
@@ -149,9 +147,8 @@ const SHELL_NAMES: ReadonlySet<string> = new Set(['sh', 'bash', 'zsh', 'dash', '
 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
+ * `identity-mismatch` covers BOTH shapes the identity standard treats the
+ * same way (one 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:
@@ -159,14 +156,14 @@ const MAX_NESTED_SCRIPT_DEPTH = 16
  * See `applyIdentityOutcome` below.
  */
 /**
- * `network-alias-redefinition` (H2, STATUS.md 12p):
+ * `network-alias-redefinition`:
  * 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
+ * `dynamic-agent`: `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
@@ -187,8 +184,9 @@ export type GitIdentityScan =
    * 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
+   * signal for the CALLER to deny with the standard's own message (the
+   * engine's rewrite stage does, and `adl-run-required.ts` already has,
+   * earlier in the rule pass); this scanner's job is only to rewrite/detect
    * conflicts once an identity — inline or fallback — actually exists.
    */
   | { readonly kind: 'needs-identity' }
@@ -471,7 +469,7 @@ function skipWrapperFlagArgs(words: readonly Word[], start: number, withValue: r
   return index
 }
 
-/** One wrapper's flag scan: the index past its own flags, and whether it strips the environment (H1). */
+/** One wrapper's flag scan: the index past its own flags, and whether it strips the environment. */
 interface WrapperScan {
   readonly index: number
   readonly strips: boolean
@@ -480,7 +478,7 @@ interface WrapperScan {
 /**
  * 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[=NAME]` or `-i`/`--ignore-environment` were used.
  *
  * `-u`/`--unset` denies regardless of WHICH name it names — not only
  * `ADL_AGENT_ID_AGENT` itself — the same blanket treatment `sudo`/`doas` get
@@ -529,7 +527,7 @@ function skipEnvArgs(words: readonly Word[], start: number, assignments: string[
 /**
  * `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
+ * (`-l`) — both are treated 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
@@ -579,8 +577,7 @@ function skipTimeoutArgs(words: readonly Word[], start: number): number {
  * 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
+ * these ever strip the environment. `env` and `exec` are NOT here — 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.
@@ -637,7 +634,7 @@ const SUBMODULE_NETWORK_VERBS: ReadonlySet<string> = new Set(['update', 'sync',
  * `!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.
+ * this only recognizes the exact network/credential VERB shapes `network-alias-redefinition` names.
  */
 export function networkAliasVerb(aliasValue: string): boolean {
   const stripped = aliasValue.startsWith('!') ? aliasValue.slice(1).trim() : aliasValue
@@ -657,7 +654,7 @@ export function networkAliasVerb(aliasValue: string): boolean {
  * 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
+ * verb is network/credential-bearing (`networkAliasVerb`). See the comment
  * at this function's one call site for why this is narrower than a blanket
  * `-c alias.*` deny.
  */
@@ -687,8 +684,7 @@ function networkAliasRedefinition(globalWords: readonly Word[], subcommand: stri
 }
 
 /**
- * R4 (STATUS.md 12p, re-review 2026-09-28 night): the
- * ENV-VAR-based sibling of `networkAliasRedefinition` — `GIT_CONFIG_COUNT`/
+ * 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
@@ -748,7 +744,6 @@ function skipGitConfigScopeFlags(words: readonly Word[], start: number): number
 }
 
 /**
- * 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`
@@ -833,9 +828,8 @@ interface ScanState {
   /**
    * 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
+   * see `GitInvocationPiece` and `scanGitInvocationPieces`. 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
@@ -845,13 +839,12 @@ interface ScanState {
   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`.
+   * effective identity for THAT SPECIFIC piece: the role rules that gate
+   * these commands (`adl-workitem-role.ts`, `adl-pr-role.ts`,
+   * `adl-pr-review-role.ts`) must grade a valid inline override on the SAME
+   * piece, not `resolveFromEnvOrFile` alone — the same per-piece rule as
+   * `gitInvocations`, for `adl mcp cli` instead of `git push`. See
+   * `AdlMcpCliPiece` and `scanAdlMcpCliPieces`.
    */
   mcpCliInvocations: AdlMcpCliPiece[]
 }
@@ -875,8 +868,7 @@ export interface GitInvocationPiece {
 
 /**
  * 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
+ * paired with the effective identity for THAT specific piece. `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
@@ -896,7 +888,7 @@ export interface AdlMcpCliPiece {
  * 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).
+ * `adl.run-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`.
@@ -933,7 +925,7 @@ function execAgentFlagValue(restValues: readonly string[]): string | undefined {
  * 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
+ * check DYNAMISM: 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
@@ -950,8 +942,7 @@ function execAgentFlagWord(rest: readonly Word[]): Word | undefined {
 
 /**
  * Shared identity decision for ONE matched identity-bearing simple command
- * (STATUS.md 12p, "Decision per identity-bearing
- * shell command"):
+ * (the identity standard's one 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`) —
@@ -962,7 +953,7 @@ function execAgentFlagWord(rest: readonly Word[]): Word | undefined {
  *  - 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
+ *    `engine.ts`, and `adl-run-required.ts` earlier — is what 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 {
@@ -1041,7 +1032,7 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
       }
       continue
     }
-    // H1: env -u/--unset[=NAME]/-i and exec -c/-l can strip the environment
+    // 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".
@@ -1086,15 +1077,14 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
     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[=]
+    // 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
+    // `/usr/local/bin/git` (the `bin/git` front controller) routes by the
+    // literal argv verb; it does not resolve git aliases itself, so an
+    // aliased network verb never reaches git-ado's 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.
@@ -1104,7 +1094,7 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
       state.deny = 'network-alias-redefinition'
       return
     }
-    // R4: the ENV-VAR-based sibling of the check above (`GIT_CONFIG_COUNT`/
+    // 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.
@@ -1112,7 +1102,7 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
       state.deny = 'network-alias-redefinition'
       return
     }
-    // R4: `git config [--global|…] alias.<verb> <value>` WRITES a
+    // `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
@@ -1122,12 +1112,11 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
       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
+    // Wider than 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
+    // 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
@@ -1137,18 +1126,16 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
       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.
+    // An EXPLICIT non-Azure-DevOps destination is provably safe without an
+    // identity — same exemption `git-helpers.ts`'s
+    // `classifyGitPushDestination` gives `adl.run-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 own deny on
+    // `needs-identity` does not deny a legitimate
+    // `git fetch https://github.com/...` that has no identity at all: a
+    // scanner that flagged every network git verb regardless of destination
+    // would make that engine deny wrongly block it.
     const explicitUrl = firstHttpUrl(rest)
     if (explicitUrl !== null && !isAdoUrl(explicitUrl)) return
     applyIdentityOutcome(assignments, unrewritableWrapper, insertAt, state)
@@ -1160,14 +1147,13 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
     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
+    // can run before the dynamic checks below — that lets the dynamic-agent 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
+    // `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.
@@ -1194,7 +1180,7 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
         })
       }
     }
-    // R5: record this SPECIFIC `adl mcp cli <command>` piece's own effective
+    // 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`.
@@ -1215,12 +1201,12 @@ function analyzePiece(command: string, words: readonly Word[], state: ScanState,
   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
+    // 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
+    // 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)
@@ -1290,23 +1276,24 @@ function scan(command: string, fallback: string | null, conflictsOnly: boolean):
  * 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
+ * a deny; the caller (`engine.ts`'s rewrite stage, and
+ * `adl-run-required.ts` earlier in the rule pass) 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
+ * Narrow by design (Tarun, 2026-09-29: the rewrite covers only Azure DevOps
+ * commands, not a whole-command `export ADL_AGENT_ID_AGENT=<id>; ` prefix on
+ * every shell command): 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.
+ * buried git/adl/curl invocation — `bin/git-ado` itself fails closed
+ * (refuses) whenever `ADL_AGENT_ID_AGENT` is unset unless the caller is a
+ * marked human terminal (a real TTY AND `ADL_HUMAN_AZDO=1`), 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 does not exist.
  */
 export function rewriteGitNetworkCommands(command: string, fallback: string | null): GitIdentityScan {
   if (fallback !== null && !SAFE_IDENTITY.test(fallback)) return { kind: 'deny', reason: 'unsafe-identity' }
@@ -1329,7 +1316,7 @@ export function rewriteGitNetworkCommands(command: string, fallback: string | nu
  * 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
+ * this view never reports that as a conflict (`adl-run-required.ts` owns
  * that message), so it is safe to call with `fallback: null`.
  */
 export function scanGitIdentityConflicts(command: string, fallback: string | null): GitIdentityDenyReason | null {
@@ -1338,7 +1325,7 @@ export function scanGitIdentityConflicts(command: string, fallback: string | nul
 }
 
 /**
- * Whole-command, coarse signal used by `adl-session-required.ts`: true when
+ * Whole-command, coarse signal used by `adl-run-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
@@ -1356,8 +1343,7 @@ export function commandHasValidInlineIdentity(command: string): boolean {
 }
 
 /**
- * The EFFECTIVE identity for `command` (W2 build item 2,
- * STATUS.md 12p): a valid inline
+ * The EFFECTIVE identity for `command`: 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 …`),
@@ -1380,7 +1366,7 @@ export function effectiveIdentityForCommand(command: string, fallback: string |
  * 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).
+ * Used by `impl/adl-token-minting-role.ts`.
  */
 export function scanTokenMintingPieces(command: string, fallback: string | null): readonly TokenMintingPiece[] {
   return scan(command, fallback, true).tokenMinting
@@ -1389,8 +1375,7 @@ export function scanTokenMintingPieces(command: string, fallback: string | null)
 /**
  * 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 piece — see `GitInvocationPiece`. 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
@@ -1403,12 +1388,12 @@ export function scanGitInvocationPieces(command: string, fallback: string | null
 /**
  * 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
+ * `AdlMcpCliPiece`. 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.
+ * identity, else the fallback — the same per-piece correlation
+ * `scanGitInvocationPieces` gives `git push`, extended to this command
+ * class.
  */
 export function scanAdlMcpCliPieces(command: string, fallback: string | null): readonly AdlMcpCliPiece[] {
   return scan(command, fallback, true).mcpCliInvocations

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

@@ -23,7 +23,7 @@ import { isRedirection, redirectionWrites, type Token, tokenValue } from './toke
  * `.gitignore`, `.github`, `repo.git-backup` are not matched: the check is on
  * a whole `.git` path segment.
  */
-export function isGitInternalsPath(raw: string): boolean {
+function isGitInternalsPath(raw: string): boolean {
   const value = raw.replace(/^--?[A-Za-z][\w-]*=/, '')
   if (/\bGIT_DIR\b/.test(value)) return true
   if (/--(?:absolute-)?git-dir\b|--git-common-dir\b|--git-path\b/.test(value)) return true