@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.10 → 0.1.26

package/packages/agent-hooks/src/pre-tool-use/handler.ts

@@ -35,7 +35,7 @@ import { gitIdentityNeedsIdentityMessage, hostCannotRewriteMessage, RULE_ID as G
 import { RULE_ID as GIT_CREDENTIAL_BYPASS_RULE_ID, SECURITY_RULE_ID as SECURITY_KEYCHAIN_ADO_RULE_ID } from '../rules/impl/adl-git-credential-bypass.ts'
 import { RULE_ID as HUMAN_AZDO_BYPASS_RULE_ID } from '../rules/impl/adl-human-azdo-bypass.ts'
 import { resolveFromEnvOrFile } from '../rules/impl/adl-identity.ts'
-import { identityBearingReason } from '../rules/impl/adl-session-required.ts'
+import { identityBearingReason } from '../rules/impl/adl-run-required.ts'
 import { commandHasValidInlineIdentity, effectiveIdentityForCommand } from '../rules/shell/git-identity.ts'
 import { invocations } from '../rules/shell/invocation.ts'
 import { KNOWN_MCP_TOOL_NAMES, mcpToolName, toolNameEndingWithKnownSuffix } from '../rules/impl/mcp-tool.ts'
@@ -82,7 +82,7 @@ const RULES = requireRegistered(BUILTIN_RULES)
 export function toDecideInput(payload: Record<string, unknown>): DecideInput | null {
   const toolInput = (payload.tool_input ?? {}) as Record<string, unknown>
 
-  // F4 (independent review, 2026-09-29): codex's `apply_patch` names its
+  // Codex's `apply_patch` names its
   // patch body `tool_input.command` — the same key name a real shell tool
   // call uses. Checked BEFORE the generic loop below, which would otherwise
   // read that patch TEXT as if it were a shell command and walk it through
@@ -167,13 +167,11 @@ function classifyCommandTool(payload: Record<string, unknown>): CommandToolClass
   if (typeof tool !== 'string' || tool.length === 0) return 'native-shell'
   if (tool.startsWith('mcp__') || tool.startsWith('MCP:')) return 'mcp'
   if (NATIVE_SHELL_TOOL_NAMES.has(tool)) return 'native-shell'
-  // ASSUMPTION (unverified, W2 build item 4 — STATUS.md 12p):
-  // OpenCode's and Kimi's own MCP tool-call naming has never actually been
-  // observed in production (.adl/logs/hooks.log shows only mcp__-prefixed
-  // calls, from Claude/Codex/Cursor) — they may carry no mcp__/MCP: prefix
-  // at all, spelling the lean-ctx shell tool `<server>_ctx_shell` /
-  // `<server>.ctx_shell` / `<server>:ctx_shell` (or the ctx_execute
-  // sibling). Treated as MCP-class defensively: an unrewritten push through
+  // ASSUMPTION (unverified): OpenCode's and Kimi's own MCP tool-call naming
+  // has not been confirmed against a live capture (the tests use synthetic names) — they may
+  // carry no mcp__/MCP: prefix at all, spelling the lean-ctx shell tool
+  // `<server>_ctx_shell` / `<server>.ctx_shell` / `<server>:ctx_shell` (or
+  // the ctx_execute sibling). Treated as MCP-class defensively: an unrewritten push through
   // such a call would otherwise silently fall through to 'other' and reach
   // git-ado's human pass-through unrewritten — the exact incident this
   // module exists to close (see this file's own header).
@@ -229,7 +227,7 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
 
   // The invocation's own environment, not the handler process's ambient one:
   // `main.ts` passes `process.env` here in production, and the identity rules
-  // (`adl.session-required-for-writes`, `adl.git-push-branch-policy`,
+  // (`adl.run-required-for-writes`, `adl.git-push-branch-policy`,
   // `adl.git-identity`'s rewrite) must read the environment the caller handed
   // the invocation — tests inject it explicitly, and a host that scrubs its
   // hook child's environment must not inherit the hook wrapper's own identity.
@@ -257,24 +255,21 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
 }
 
 /**
- * The identity rule ids — used below (not as a baseline any more; see
- * Tarun's rule) purely to tell `denyIdentity`/`passIdentity` which decisions
- * in a MANAGED repo's own normal rule pass are identity decisions worth
- * logging `identity_source`/`identityAgent` for, as opposed to an unrelated
- * deny (`fs.rm`, `git.no-verify`, …) that made no identity decision at all.
+ * The identity rule ids — used below purely to tell `denyIdentity`/
+ * `passIdentity` which decisions in a MANAGED repo's own normal rule pass
+ * are identity decisions worth logging `identity_source`/`identityAgent`
+ * for, as opposed to an unrelated deny (`fs.rm`, `git.no-verify`, …) that
+ * made no identity decision at all.
  *
- * HARDCUT (Tarun's rule, 2026-09-29): "the repos where `adl-
- * config.toml` does not exist have no business running hooks" — this
- * REVERSES the earlier "global identity baseline" (W2 build item 3 / R2,
- * STATUS.md 12p), which ran exactly these rules
- * (unconditionally enabled, with the schema's own defaults) even in an
- * UNMANAGED repo or one with `[hooks] enabled = false`. `main.ts` no longer
- * calls anything for either of those cases but a strict, silent no-op — see
- * its own header and `silentNoop`. The rule ids themselves stay meaningful
- * only for the logging purpose above, in the repos where hooks already run.
+ * This is NOT a baseline that runs anywhere else: hooks run only in a repo
+ * with its own `adl-config.toml` where `adl hooks deploy` has run
+ * (Tarun, 2026-09-29: "the repos where `adl-config.toml` does not exist have
+ * no business running hooks"). `main.ts` calls nothing but a strict, silent
+ * no-op for an unmanaged repo or one with `[hooks] enabled = false` — see its
+ * own header and `silentNoop`.
  */
 const IDENTITY_RULE_IDS: ReadonlySet<RuleId> = new Set([
-  'adl.session-required-for-writes',
+  'adl.run-required-for-writes',
   'adl.git-identity',
   'adl.token-minting-role',
   'tool.azure-devops',
@@ -285,18 +280,17 @@ const IDENTITY_RULE_IDS: ReadonlySet<RuleId> = new Set([
 ])
 
 /**
- * F9 (independent review, 2026-09-29): the four role-gate rules that deny a
- * SPECIFIC Azure DevOps MCP tool call by the caller's identity
- * (`adl.workitem-requires-tarun-or-vivek`, `adl.pr-create-update-role`,
- * `adl.pr-review-role`, `adl.build-run-denied`). None of these are in
- * `IDENTITY_RULE_IDS` above — that set only ever covered the FALLBACK/
- * needs-identity/no-identity rules, never a rule that denies WITH an
- * identity already resolved, on the strength of who that identity is. Left
- * out of the deny-side identity logging entirely, even though every one of
- * them can only ever fire on the exact same Azure DevOps MCP tool-call shape
- * Decision 5's PASS-side logging already covers (`isAdoMcpToolCall`, below)
- * — a role-gate deny is JUST AS MUCH an identity decision as the PASS it
- * would have been without the role mismatch.
+ * The four role-gate rules that deny a SPECIFIC Azure DevOps MCP tool call by
+ * the caller's identity (`adl.workitem-requires-tarun-or-vivek`,
+ * `adl.pr-create-update-role`, `adl.pr-review-role`,
+ * `adl.build-run-denied`). None of these are in `IDENTITY_RULE_IDS` above —
+ * that set covers the rules that fire when no identity is resolved or
+ * carried, never a rule that denies WITH an identity already resolved, on the
+ * strength of who that identity is. Each of them can only fire on the same
+ * Azure DevOps MCP tool-call shape the PASS-side logging covers
+ * (`isAdoMcpToolCall`, below), so a role-gate deny is just as much an
+ * identity decision as the PASS it would have been without the role
+ * mismatch, and its deny log line carries `identity_source` too.
  */
 const ROLE_GATE_RULE_IDS: ReadonlySet<RuleId> = new Set([
   'adl.workitem-requires-tarun-or-vivek',
@@ -314,23 +308,23 @@ interface EffectiveIdentity {
 }
 
 /**
- * Where the effective agent identity for THIS decision came from (W2 build
- * item 5 — STATUS.md 12p), AND the agent it
- * actually names (M8, STATUS.md 12p) — a valid
+ * Where the effective agent identity for THIS decision came from
+ * (`identity_source` in the log), AND the agent it actually names: a valid
  * inline `ADL_AGENT_ID_AGENT=` on the command itself (step 1 of the
- * standard), else the session env or the machine default-agent file (steps
- * 2-3, `resolveFromEnvOrFile`'s own `source`/`agent`), else `none`/no agent.
- * A tool-call input carries no command text at all, so it can never be
- * `inline` — the override for an MCP tool call is `adl run --as` (session
- * env), matching the standard's own note on that.
+ * resolution order), else the session env or the machine default-agent file
+ * (steps 2-3, `resolveFromEnvOrFile`'s own `source`/`agent`), else
+ * `none`/no agent. A tool-call input carries no command text at all, so it
+ * can never be `inline`: its identity is the session env or the machine
+ * default-agent file. MCP is the primary route to Azure DevOps operations;
+ * `ADL_AGENT_ID_AGENT=<agent> adl mcp cli <command>` (which does carry an
+ * inline prefix) is the fallback when MCP is not working.
  *
  * The AGENT half matters because it can differ from the session's own
  * `ADL_AGENT_ID_AGENT`: `ADL_AGENT_ID_AGENT=agent-vivek git push …` run in
  * an agent-tarun session is agent-vivek's push, not agent-tarun's — the
- * override, not the session env, is what actually acted, and `../hooks/log.ts`
- * reads THIS agent for the log's `agent` column instead of the session
- * env var it used to read unconditionally (M8's second symptom: "the agent
- * column shows the session agent" even on an overridden command).
+ * override, not the session env, is what actually acted, and
+ * `../hooks/log.ts` reads THIS agent for the log's `agent` column rather
+ * than the session env var.
  */
 function effectiveIdentityFor(input: DecideInput, engineCtx: EngineContext): EffectiveIdentity {
   const resolution = resolveFromEnvOrFile(engineCtx.env)
@@ -344,10 +338,10 @@ function effectiveIdentityFor(input: DecideInput, engineCtx: EngineContext): Eff
 }
 
 /**
- * R7 (STATUS.md 12p, re-review 2026-09-28 night): the
- * resolved FALLBACK identity alone (steps 2-3 of the standard: env, else the
- * machine default-agent file) — never the coarse, whole-command "any inline
- * override anywhere on the line" `effectiveIdentityFor` also reports.
+ * The resolved FALLBACK identity alone (steps 2-3 of the resolution order:
+ * env, else the machine default-agent file) — never the coarse,
+ * whole-command "any inline override anywhere on the line"
+ * `effectiveIdentityFor` also reports.
  *
  * `adl.git-identity`'s REWRITE stage (`decision.rewrite`) and its own
  * fallback-based DENY reasons (`identity-mismatch`'s hint, `unrewritable-
@@ -393,11 +387,10 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   //
   // Every branch below decided an identity (the rewrite ALWAYS comes from
   // adl.git-identity), so every inv.record?.() call here carries
-  // identitySource/identityAgent. R7 (STATUS.md 12p):
-  // the FALLBACK identity specifically, not `effectiveIdentityFor`'s coarse
-  // whole-command value — see `fallbackIdentity`'s own doc for why a
-  // rewrite is always about the fallback, never an inline override
-  // elsewhere on a chained command.
+  // identitySource/identityAgent — the FALLBACK identity specifically, not
+  // `effectiveIdentityFor`'s coarse whole-command value (see
+  // `fallbackIdentity`'s own doc for why a rewrite is always about the
+  // fallback, never an inline override elsewhere on a chained command).
   if (!decision.blocked && decision.rewrite) {
     const identity = fallbackIdentity(engineCtx)
     const identitySource = identity.source
@@ -413,7 +406,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
       inv.record?.({ reason: `REWRITE ${decision.rewrite.ruleId}`, ...identityFields(identity) })
       return { stdout: `${JSON.stringify(rendered)}\n`, stderr: '', exitCode: 0 }
     }
-    // C2: `native-shell` here is only reached when the host could not
+    // `native-shell` here is only reached when the host could not
     // render a rewrite for this payload shape (Kimi has none at all;
     // Cursor's beforeShellExecution has no tool_input to replace) — SKIP
     // (allow unchanged) is only safe when `ADL_AGENT_ID_AGENT` is actually
@@ -434,7 +427,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
     return denyHostCannotRewrite(spec, inv.host, message)
   }
 
-  // R3 (STATUS.md 12p, re-review 2026-09-28 night): the
+  // Walker-found identity-bearing shapes the rewrite scanner missed: the
   // branch above only runs when `adl.git-identity`'s own narrow, offset-
   // based scanner recognized the command as identity-bearing at all
   // (`decision.rewrite` set) — it does not walk into `if`/`!`/`for..do`/
@@ -444,11 +437,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // backstop for a shape THIS scanner misses on a REWRITING host's native
   // shell). But `../rules/shell/invocation.ts`'s walker (reused here via
   // `identityBearingReason`, already proven against every one of those
-  // shapes for `adl.session-required-for-writes`'s own deny) DOES find them
+  // shapes for `adl.run-required-for-writes`'s own deny) DOES find them
   // — and once found, there is no rewritten command to offer at all (this
   // scanner never computed one), so the only safe outcomes are: a
   // native-shell tool with an ENV-sourced identity (its child inherits it
-  // regardless of any rewrite, exactly like the C2 branch above), or an
+  // regardless of any rewrite, exactly like the native-shell SKIP in the rewrite branch above), or an
   // inline override already on the command text (travels with the text
   // itself, no env inheritance needed) — anything else must be denied
   // rather than run with no identity anyone can prove reached the child.
@@ -476,13 +469,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // unrelated deny (fs.rm, git.no-verify, …) made no identity decision at
   // all. A PASS made one too when the command is identity-bearing but
   // needed no rewrite because it ALREADY carried a valid inline override
-  // (M8, STATUS.md 12p — "the override's PASS
-  // line"): `rewriteGitNetworkCommands`'s `unchanged` outcome covers BOTH
-  // "not identity-bearing at all" and "fully covered by an inline override
-  // already", and only `commandHasValidInlineIdentity` tells those two
-  // apart from here.
-  // R7 (STATUS.md 12p, re-review 2026-09-28 night): a
-  // `adl.git-identity` deny (identity-mismatch/unrewritable-wrapper/
+  // (the override's PASS line): `rewriteGitNetworkCommands`'s `unchanged`
+  // outcome covers BOTH "not identity-bearing at all" and "fully covered by
+  // an inline override already", and only `commandHasValidInlineIdentity`
+  // tells those two apart from here.
+  // An `adl.git-identity` deny (identity-mismatch/unrewritable-wrapper/
   // network-alias-redefinition/dynamic-agent/unsafe-identity) is ALWAYS
   // about the piece LACKING a valid override — the same fallback-only
   // reasoning `fallbackIdentity`'s doc gives the rewrite branch, and
@@ -490,15 +481,13 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // hint ("your session's own resolved identity is X"). The coarse
   // `effectiveIdentityFor` could otherwise report an unrelated, valid
   // override sitting on a DIFFERENT piece of the same chained command. The
-  // other three identity rules keep the coarse helper: `adl.session-
-  // required-for-writes` only ever denies when `commandHasValidInlineIdentity`
-  // is ALSO false (so the two never actually disagree for it), and `adl.
-  // token-minting-role`/`tool.azure-devops` are not piece-correlated by this
-  // change.
-  // F9: computed here (moved ahead of the PASS-side comment below, which
-  // used to be the only reader) so the DENY-side identity computation above
-  // can also test it — a role-gate deny of an Azure DevOps MCP call is the
-  // same shape as its PASS, just with the wrong identity.
+  // other identity rules keep the coarse helper: `adl.run-required-for-writes`
+  // only ever denies when `commandHasValidInlineIdentity` is ALSO false (so
+  // the two never actually disagree for it), and
+  // `adl.token-minting-role`/`tool.azure-devops` are not piece-correlated.
+  // `isAdoMcpToolCall` is computed ahead of `denyIdentity` because the
+  // DENY-side computation tests it too: a role-gate deny of an Azure DevOps
+  // MCP call is the same shape as its PASS, just with the wrong identity.
   const isAdoMcpToolCall = input.kind === 'tool-call' && KNOWN_MCP_TOOL_NAMES.has(mcpToolName(input.tool) ?? '')
   const denyIdentity =
     decision.blocked && (IDENTITY_RULE_IDS.has(decision.ruleId) || (isAdoMcpToolCall && ROLE_GATE_RULE_IDS.has(decision.ruleId)))
@@ -506,7 +495,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
         ? fallbackIdentity(engineCtx)
         : effectiveIdentityFor(input, engineCtx)
       : undefined
-  // Decision 5 (STATUS.md 12p): an ALLOWED Azure DevOps MCP
+  // An ALLOWED Azure DevOps MCP
   // tool call — reads included (workitem_list_or_get/pr_list_or_get/
   // build_list_or_get, not only the four writes) — logs `identitySource`/
   // `identityAgent` too, the SAME field names the shell path already uses
@@ -515,11 +504,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // tool-call branch already reflects that, unchanged), so this is exactly
   // the session's resolved identity (env, else the machine default-agent
   // file). Every one of these calls ALREADY required a resolvable identity
-  // to reach this PASS line at all (`adl.session-required-for-writes` denies
+  // to reach this PASS line at all (`adl.run-required-for-writes` denies
   // otherwise) — this only makes that already-decided identity visible in
   // the log, the same way the shell path's own inline-override PASS line
-  // does (M8's "the override's PASS line"). `isAdoMcpToolCall` itself is
-  // computed above, ahead of `denyIdentity` — F9 needs it there too.
+  // does. Tarun, 2026-09-29: every Azure DevOps MCP call logs
+  // `identity_source`, reads included.
   const passIdentity = !decision.blocked && ((input.kind === 'command' && commandHasValidInlineIdentity(input.command)) || isAdoMcpToolCall) ? effectiveIdentityFor(input, engineCtx) : undefined
   inv.record?.(
     decision.blocked

package/packages/agent-hooks/src/rules/engine.ts

@@ -87,14 +87,14 @@ export type DecideInput =
   | { readonly kind: 'command'; readonly command: string }
   | { readonly kind: 'tool-call'; readonly tool: string; readonly input: Readonly<Record<string, unknown>> }
 
-export interface DenyDecision {
+interface DenyDecision {
   readonly blocked: true
   readonly ruleId: RuleId
   readonly userMessage: string
   readonly agentMessage: string
 }
 
-export interface AdviceDecision {
+interface AdviceDecision {
   readonly blocked: false
   readonly advice?: { readonly ruleId: RuleId; readonly userMessage: string; readonly agentMessage: string }
   /**
@@ -205,9 +205,8 @@ function decideCommand(command: string, ctx: EngineContext): Decision {
   }
 
   // adl.git-identity's REWRITE stage (docs/architecture/cli-design.md §1a;
-  // widened by STATUS.md 12p, "The standard", to
-  // every identity-bearing command class, not only network git): every rule
-  // passed — carry the resolved identity (steps 2-3: session env, else the
+  // it covers every identity-bearing command class, not only network git):
+  // every rule passed — carry the resolved identity (steps 2-3: session env, else the
   // machine default-agent file) into every identity-bearing invocation in
   // the command. A VALID inline override (step 1) is honoured as-is
   // (`kind: 'unchanged'`, handled inside `rewriteGitNetworkCommands` itself,
@@ -216,19 +215,16 @@ function decideCommand(command: string, ctx: EngineContext): Decision {
   // rule can be disabled per-repo; an unsafe identity is never the rule's to
   // see).
   //
-  // H3 (STATUS.md 12p): `needs-identity` (an
-  // identity-bearing command with no inline override and no resolvable
-  // fallback) USED to fall through here unhandled, relying entirely on
-  // `adl.session-required-for-writes` having already denied the SAME
-  // command earlier in the rule pass — a separate classification (the
+  // `needs-identity` (an identity-bearing command with no inline override
+  // and no resolvable fallback) is denied HERE, directly, rather than left
+  // to `adl.run-required-for-writes` having already denied the SAME command
+  // earlier in the rule pass: that rule is a separate classification (the
   // shared shell/invocation.ts walker) that can be disabled per repo
-  // (`[rules."adl.session-required-for-writes"] enabled = false`) or simply
-  // not recognize a shape this scanner does. Either way, nothing else here
-  // stands between an unidentified network git command and a plain allow.
-  // The engine now denies it directly instead of trusting another rule to
-  // have already covered the same ground.
-  // L4 (STATUS.md 12p): resolve the fallback
-  // identity — which can read the REAL machine default-agent file
+  // (`[rules."adl.run-required-for-writes"] enabled = false`) or simply not
+  // recognize a shape this scanner does, and nothing else here would stand
+  // between an unidentified network git command and a plain allow.
+  //
+  // The fallback identity — which can read the REAL machine default-agent file
   // (`resolveFromEnvOrFile`) — ONLY when the command actually has an
   // identity-bearing piece that would use it. A probe scan with
   // `fallback: null` is fallback-INDEPENDENT for every outcome except

package/packages/agent-hooks/src/rules/impl/adl-build-run-denied.ts

@@ -5,7 +5,7 @@
  * branch on `ADL_AGENT_ID_AGENT` at all: the matrix's own hook-action column
  * shows ❌ for both `agent-tarun`/`agent-vivek` and `agent-reviewer`, so there
  * is no identity this tool is allowed for. With no identity at all,
- * `adl.session-required-for-writes` (registered ahead of this rule) reports
+ * `adl.run-required-for-writes` (registered ahead of this rule) reports
  * first with its own, more specific "no session" message; this rule is what
  * fires once an identity IS present, which is the case that rule leaves
  * alone.
@@ -25,10 +25,10 @@ export const adlBuildRunDenied: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny build_run for every identity (docs/operations/agent-permissions.md row 12) — the MCP tool AND its adl mcp cli equivalent (M4).',
+  summary: 'Deny build_run for every identity (docs/operations/agent-permissions.md row 12) — the MCP tool AND its adl mcp cli equivalent.',
   params: noParams,
   match(inv: Invocation): Finding | null {
-    // M4 (STATUS.md 12p): also catch `adl mcp cli build-run` — same tool, same deny.
+    // Also catch `adl mcp cli build-run` — same tool, same deny.
     const call = toolCallFor(inv)
     if (call === null) return null
     if (mcpToolName(call.tool) !== 'build_run') return null

package/packages/agent-hooks/src/rules/impl/adl-git-credential-bypass.ts

@@ -1,8 +1,8 @@
 /**
- * `adl.git-credential-bypass` — H2 (STATUS.md 12p): deny, for agents, every
+ * `adl.git-credential-bypass` — deny, for agents, every
  * shell shape that reaches Azure DevOps credentials or bypasses
  * `bin/git-ado`'s routing entirely, without touching any of the specific
- * verbs `adl.session-required-for-writes`/`adl.git-identity` already police:
+ * verbs `adl.run-required-for-writes`/`adl.git-identity` already police:
  *
  *  - An absolute git binary other than the managed front controller
  *    `/usr/local/bin/git` (that IS the path `bin/git-ado` installs itself
@@ -13,7 +13,7 @@
  *    untouched.
  *  - `git remote update` — fetches every configured remote, the same
  *    network operation as `git fetch`, but not a verb
- *    `adl.session-required-for-writes`'s `NETWORK_GIT_VERBS` recognizes.
+ *    `adl.run-required-for-writes`'s `NETWORK_GIT_VERBS` recognizes.
  *  - `git submodule update/sync/foreach` — `update`/`sync` can fetch a
  *    submodule's own remote; `foreach` runs an arbitrary shell command once
  *    per submodule, unauditable by this hook.
@@ -21,7 +21,7 @@
  *    credential directly, sidestepping the front controller entirely.
  *
  * `security find-generic-password`/`find-internet-password` naming Azure
- * DevOps (the fifth H2 item — a macOS Keychain read, not a git operation at
+ * DevOps (a macOS Keychain read, not a git operation at
  * all) is `adl.security-keychain-ado` below, in the same file since it
  * shares `namesAzureDevops`, but registered as its own `category: 'tool'`
  * rule: `tests/unit/rules-git-deny-guidance.test.ts` requires every
@@ -33,14 +33,13 @@
  * an intentional, heavily-tested feature — `tests/unit/rules-git-worktree.
  * test.ts`'s dozens of `git -c alias.wt=worktree`-shaped corpus entries SEE
  * THROUGH a non-network inline alias on purpose). Two narrower, resolved
- * pieces of that space ARE covered, R9 correcting this header's stale
- * "BLOCKED" note (STATUS.md 12p):
+ * pieces of that space ARE covered:
  *  - a SELF-referential inline `-c alias.<verb>=<value>`/`--config-env`
  *    naming the LITERAL subcommand this invocation runs, where `<value>`'s
  *    own verb is network/credential — `adl.git-identity`'s own
  *    `network-alias-redefinition` reason (`../shell/git-identity.ts`), not
  *    this rule.
- *  - R4 (re-review 2026-09-28 night): a REPO-CONFIGURED alias (`.git/config`,
+ *  - a REPO-CONFIGURED alias (`.git/config`,
  *    invisible to the walker's own inline/env-var-only resolution) whose
  *    value's verb is network/credential — `repo-alias-network-verb` below,
  *    resolved via the injectable `ctx.index.configuredAlias` port
@@ -48,7 +47,7 @@
  *    stay hermetic. Still narrower than a blanket deny: a non-network
  *    repo-configured alias (`git st` → `alias.st=status`) is untouched.
  *
- * R4 also adds three more front-controller bypasses here, all sharing the
+ * Three more front-controller bypasses are denied here, all sharing the
  * same reasoning: `/usr/local/bin/git` (`bin/git-ado`) routes on the
  * LITERAL verb/binary an agent typed — it does not resolve `PATH`
  * overrides, `command -p`'s own default `$PATH`, or `xcrun`'s tool
@@ -130,7 +129,7 @@ const CREDENTIAL_HELPER_BINARY_PREFIX = 'credential-'
  * that holds a credential for a short-lived window and exits — `git
  * credential-cache exit` merely stops it); it never reads or writes a
  * platform secret store the way `credential-osxkeychain`/`credential-
- * manager`/… do, and this exact allow case predates R4 (H2's own corpus).
+ * manager`/… do, and this exact allow case is part of this rule's own corpus.
  * Excluded from the deny by name rather than widened into a blanket
  * "every credential-* helper", to avoid regressing that settled behaviour.
  */
@@ -143,9 +142,8 @@ function isDeniedCredentialHelper(subcommandOrName: string): boolean {
 
 /**
  * Git's own real subcommand vocabulary (porcelain and common plumbing),
- * lower-cased — R4 (STATUS.md 12p): gates the repo-
- * configured-alias lookup (`ctx.index.configuredAlias`) to an UNKNOWN verb
- * only, per this finding's own text ("resolve unknown git verbs"), so an
+ * lower-cased — gates the repo-configured-alias lookup
+ * (`ctx.index.configuredAlias`) to an UNKNOWN verb only, so an
  * ordinary `git status`/`git log`/… never pays for a `git config --get`
  * shell-out. Not exhaustive — an obscure real git verb missing here only
  * costs one harmless extra (correctness-preserving) lookup that resolves to
@@ -163,8 +161,8 @@ const KNOWN_GIT_VERBS: ReadonlySet<string> = new Set([
 /**
  * `PATH=`/`export PATH=` anywhere in `command`, co-occurring with a `git`
  * invocation this rule is already deciding — coarse (whole-command, not
- * piece-scoped) by design, matching R3's own precedent elsewhere in this
- * package: a PATH override ahead of `git` ANYWHERE on the line is suspicious
+ * piece-scoped) by design, matching the other coarse textual checks in this
+ * package (see `containsIdentityBearingToken` in `git-helpers.ts`): a PATH override ahead of `git` ANYWHERE on the line is suspicious
  * enough on its own that over-denial costs nothing legitimate.
  */
 function pathOverridePresent(command: string): boolean {

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

@@ -8,8 +8,9 @@
  * `adl run -- codex` session ran `git push -u origin feat/adl-m3-finish`
  * through the lean-ctx MCP tool `mcp__lean_ctx__ctx_shell`; Codex gives
  * `ADL_AGENT_ID_AGENT` only to its own shell tool, so the push executed with
- * no identity and `bin/git-ado`'s HUMAN pass-through (bin/git-ado:191-194)
- * pushed with Tarun's own credential helper. The hook knew the session
+ * no identity and `bin/git-ado` (which then passed an unset identity through
+ * to the human's credential helper; it now fails closed unless a real TTY and
+ * `ADL_HUMAN_AZDO=1`) pushed with Tarun's own credential. The hook knew the session
  * identity — it is in the hook's own environment — but passed the command
  * through unchanged. This module is the fix: the command is REWRITTEN to
  * carry the identity (`git push …` → `ADL_AGENT_ID_AGENT=agent-tarun git
@@ -25,9 +26,9 @@
  *     into the human credential), or a `sudo`/`doas` wrapper, which strips
  *     the environment the identity travels in. Both are denies rather than
  *     rewrites: an inexact rewrite is a deny (cli-design.md §1a's rule). With
- *     no session identity at all this rule stays silent —
- *     `adl.session-required-for-writes` denies the write with the
- *     `adl run` hint first.
+ *     no agent identity at all this rule stays silent —
+ *     `adl.run-required-for-writes` denies the write with the
+ *     inline-prefix hint first.
  *
  *  2. The REWRITE stage, computed in `../engine.ts`'s `decideCommand` after
  *     every rule passed: `../shell/git-identity.ts` rewrites the command
@@ -67,7 +68,7 @@ import { NETWORK_GIT_VERBS, scanGitIdentityConflicts, type GitIdentityDenyReason
 
 export const RULE_ID = 'adl.git-identity'
 
-export type GitIdentityRuleReason = Extract<
+type GitIdentityRuleReason = Extract<
   GitIdentityDenyReason,
   'identity-mismatch' | 'unrewritable-wrapper' | 'network-alias-redefinition' | 'dynamic-agent'
 >
@@ -75,14 +76,13 @@ export type GitIdentityRuleReason = Extract<
 /** Messages for the rule's two deny reasons and for the engine rewrite-stage nets (unsafe identity). */
 export function gitIdentityDenyMessage(reason: GitIdentityDenyReason, ctx: MessageContext, identity: string | undefined): RuleMessage {
   if (reason === 'identity-mismatch') {
-    // L1 (STATUS.md 12p): the 2026-09-28 standard
-    // widened this reason to mean ONLY "empty or not a recognized agent" —
-    // a valid inline override that merely NAMES A DIFFERENT agent than the
-    // session's own is no longer a conflict at all (see
-    // applyIdentityOutcome's doc in ../shell/git-identity.ts): it is the
-    // override, and it wins. The old wording ("a different agent identity
-    // ... conflicts with this session") described that earlier, no-longer-
-    // true behavior and was actively misleading about what to actually fix.
+    // Under the one-agent-identity standard (Tarun, 2026-09-28) this reason
+    // means ONLY "empty or not a recognized agent": a valid inline override
+    // that merely NAMES A DIFFERENT agent than the session's own is not a
+    // conflict at all (see applyIdentityOutcome's doc in
+    // ../shell/git-identity.ts) — it is the override, and it wins. The
+    // message therefore says what to fix (an empty or unrecognized value),
+    // not that another agent "conflicts with this session".
     const user = 'the inline ADL_AGENT_ID_AGENT override on this command is empty or not a recognized agent'
     const hint = identity !== undefined ? ` Your session's own resolved identity is ${identity}; remove the override to use it,` : ' Remove the override,'
     return {
@@ -124,22 +124,22 @@ export function gitIdentityDenyMessage(reason: GitIdentityDenyReason, ctx: Messa
         `directly instead of aliasing it inline. Blocked: ${ctx.snippet}`,
     }
   }
-  const user = "the session's agent identity is not a safe shell word"
+  const user = 'the agent identity is not a safe shell word'
   return {
     user,
     agent:
-      `DENIED ${user}: this session's ${ADL_AGENT_ID_ENV_VAR} contains characters outside [A-Za-z0-9_-], ` +
-      'so the hook cannot place it on a command line. The session is misconfigured — start it with `adl run`. ' +
+      `DENIED ${user}: the ${ADL_AGENT_ID_ENV_VAR} value in this environment contains characters outside [A-Za-z0-9_-], ` +
+      `so the hook cannot place it on a command line. Prefix the command with ${ADL_AGENT_ID_ENV_VAR}=<agent-tarun|agent-vivek|agent-reviewer> instead. ` +
       `Blocked: ${ctx.snippet}`,
   }
 }
 
 /**
- * H3 (STATUS.md 12p): the deny rendered by
- * `../engine.ts`'s rewrite stage itself for a `needs-identity` outcome —
+ * The deny rendered by `../engine.ts`'s rewrite stage itself for a
+ * `needs-identity` outcome —
  * an identity-bearing command with no valid inline override and no
  * resolvable fallback (steps 2-3 of the standard). This is defense in
- * depth: `adl.session-required-for-writes` is expected to have already
+ * depth: `adl.run-required-for-writes` is expected to have already
  * denied the same command with this same standard message earlier in the
  * rule pass, but it is a SEPARATE classification that can be disabled per
  * repo or simply miss a shape this scanner recognizes — see engine.ts's own
@@ -159,14 +159,14 @@ export function gitIdentityNeedsIdentityMessage(ctx: MessageContext): RuleMessag
  * tool input, and the identity is not otherwise present in THIS invocation's
  * own environment: an MCP-class tool (Kimi has no `renderRewrite` at all),
  * or a native-shell tool whose identity resolved from the machine
- * default-agent file rather than the session env (C2 — the hook process
+ * default-agent file rather than the session env (the hook process
  * read that file itself; a child process this shell tool spawns never sees
  * `ADL_AGENT_ID_AGENT`, so it would reach Azure DevOps as the human, which
  * is the exact incident this module exists to close). `agent` is the
  * resolved fallback identity (steps 2-3 of the standard) when one resolved
  * — always the case at both call sites, since a `rewrite` decision only
  * exists once a fallback resolved — so the message can name the EXACT
- * prefix to add (M1), not just point at "an agent" in the abstract.
+ * prefix to add, not just point at "an agent" in the abstract.
  */
 export function hostCannotRewriteMessage(host: string, ctx: MessageContext, agent: string | undefined): RuleMessage {
   const prefix = `${ADL_AGENT_ID_ENV_VAR}=${agent ?? '<agent>'}`
@@ -174,7 +174,7 @@ export function hostCannotRewriteMessage(host: string, ctx: MessageContext, agen
   // OpenCode's fail-closed path) writes `message.user`, not `message.agent`,
   // to stderr (see ../../pre-tool-use/handler.ts's `denyHostCannotRewrite`),
   // and that stream is what the agent itself reads on those hosts.
-  const user = `this agent surface (${host}) cannot carry the session identity into this command; prefix it with \`${prefix}\` and retry`
+  const user = `this agent surface (${host}) cannot carry the agent identity into this command; prefix it with \`${prefix}\` and retry`
   return {
     user,
     agent:
@@ -193,16 +193,16 @@ export const adlGitIdentity: RuleSpec = {
   summary: 'Deny an identity-bearing command whose inline ADL_AGENT_ID_AGENT is invalid/empty, or that runs through sudo/doas.',
   params: noParams,
   match(inv, ctx): Finding | null {
-    // WIDENED 2026-09-28 (STATUS.md 12p, W2 build
-    // item 3): every identity-bearing command class, not only network git —
+    // Every identity-bearing command class, not only network git
+    // (widened 2026-09-28 by the one-agent-identity standard) —
     // `adl mcp cli`/`adl repo doctor`/`adl repo controls azdo-push`/`adl id
     // token`, `adl-agent-id exec`, and curl/wget/httpie/xh to
     // dev.azure.com/*.visualstudio.com. This rule no longer requires a
     // resolved fallback identity to run (`identity === null` used to skip
-    // straight to session-required) — an invalid/empty INLINE override is a
+    // straight to run-required) — an invalid/empty INLINE override is a
     // real problem independent of whether a fallback exists; the two rules
     // still cannot both win for the same invocation because the registry
-    // orders session-required first (`../registry.ts`) and the engine's
+    // orders run-required first (`../registry.ts`) and the engine's
     // `firstFinding` stops at the first rule that reports anything at all.
     let isIdentityBearing = false
     if (inv.kind === 'git') {
@@ -213,7 +213,7 @@ export const adlGitIdentity: RuleSpec = {
       if (ADL_BINARY_NAMES.has(inv.name)) {
         isIdentityBearing = !dynamic && matchesIdentityShape(values, ADL_IDENTITY_COMMAND_SHAPES)
       } else if (ADL_AGENT_ID_BINARY_NAMES.has(inv.name)) {
-        // M5 (STATUS.md 12p): leading dash-prefixed
+        // Leading dash-prefixed
         // global flags (`adl-agent-id --verbose exec …`) are skipped before
         // matching the `['exec']` shape — see skipLeadingDashFlags's doc.
         isIdentityBearing = !dynamic && matchesIdentityShape(skipLeadingDashFlags(values), ADL_AGENT_ID_COMMAND_SHAPES)