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

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

@@ -0,0 +1,249 @@
+/**
+ * `adl.git-identity` — carry the session identity into every network git
+ * command (docs/architecture/cli-design.md §1a "Route, don't block";
+ * docs/operations/agent-permissions.md row 15: setting `ADL_*` inline is a
+ * DENY; the rewrite itself is the route for the session's own identity).
+ *
+ * Live gap this closes (2026-09-28, codex session 01a0e611): an
+ * `adl run -- codex` session ran `git push -u origin feat/adl-m3-finish`
+ * through the lean-ctx MCP tool `mcp__lean_ctx__ctx_shell`; Codex gives
+ * `ADL_AGENT_ID_AGENT` only to its own shell tool, so the push executed with
+ * no identity and `bin/git-ado`'s HUMAN pass-through (bin/git-ado:191-194)
+ * pushed with Tarun's own credential helper. The hook 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
+ * push …`), so it runs as the session's agent no matter which process
+ * environment the executing tool hands it.
+ *
+ * Two halves:
+ *
+ *  1. The DENY rule registered here. It fires when a network git invocation
+ *     in the command conflicts with the session identity: an inline
+ *     `ADL_AGENT_ID_AGENT=<other>` (or an emptied one — `ADL_AGENT_ID_AGENT=`
+ *     would fall back to git-ado's human pass-through and launder the command
+ *     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.
+ *
+ *  2. The REWRITE stage, computed in `../engine.ts`'s `decideCommand` after
+ *     every rule passed: `../shell/git-identity.ts` rewrites the command
+ *     text, and the decision carries `rewrite` for the pre-tool-use handler
+ *     to render as the host's native "replace the tool input" envelope
+ *     (`updatedInput` on Claude/Codex/OpenCode, `updated_input` on Cursor). A
+ *     host whose hook contract has no such envelope (Kimi — its official docs
+ *     have no input replacement) gets a deny for MCP-class tools instead:
+ *     fail closed, never run the command unrewritten. The
+ *     host's own shell tool is allowed unchanged there — its child
+ *     environment already inherits the session identity, which is exactly the
+ *     mechanism cli-design.md §1a documents as "just works".
+ *
+ * Corpus: every real deny case needs a specific `ADL_AGENT_ID_AGENT` value,
+ * which the shared corpus fixture cannot supply — same pattern as
+ * `adl.git-push-branch-policy`. The allow entries prove the rule does not
+ * false-positive on ordinary read-only commands.
+ */
+
+import type { Finding, MessageContext, RuleMessage, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { ADL_AGENT_ID_ENV_VAR, NO_AGENT_IDENTITY_MESSAGE, resolveFromEnvOrFile } from './adl-identity.ts'
+import {
+  ADL_AGENT_ID_BINARY_NAMES,
+  ADL_AGENT_ID_COMMAND_SHAPES,
+  ADL_BINARY_NAMES,
+  ADL_IDENTITY_COMMAND_SHAPES,
+  HTTP_CLIENT_BINARY_NAMES,
+  isAdoUrl,
+  isHelpOnlyInvocation,
+  matchesIdentityShape,
+  skipLeadingDashFlags,
+} from './git-helpers.ts'
+import { detailString } from './messages.ts'
+import { dynamicToken, tokenValue } from '../shell/token.ts'
+import { NETWORK_GIT_VERBS, scanGitIdentityConflicts, type GitIdentityDenyReason } from '../shell/git-identity.ts'
+
+export const RULE_ID = 'adl.git-identity'
+
+export type GitIdentityRuleReason = Extract<
+  GitIdentityDenyReason,
+  'identity-mismatch' | 'unrewritable-wrapper' | 'network-alias-redefinition' | 'dynamic-agent'
+>
+
+/** 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.
+    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 {
+      user,
+      agent:
+        `DENIED ${user}: an inline ${ADL_AGENT_ID_ENV_VAR}= override must name one of the valid agents to be used ` +
+        'at all — an empty value would fall back to the human credential path, and an unrecognized name is refused ' +
+        `by name.${hint} or use a valid agent name instead. Blocked: ${ctx.snippet}`,
+    }
+  }
+  if (reason === 'unrewritable-wrapper') {
+    const user = 'git network commands cannot run through sudo or doas'
+    return {
+      user,
+      agent:
+        `DENIED ${user}: sudo/doas strip ${ADL_AGENT_ID_ENV_VAR} from the environment, so the command ` +
+        `would fall back to the human credential path in git-ado. Run the git command without sudo; if it ` +
+        `truly needs elevation, ask the user to run it in their own terminal. Blocked: ${ctx.snippet}`,
+    }
+  }
+  if (reason === 'dynamic-agent') {
+    const user = 'the agent name on this command is dynamic — it cannot be proven safe'
+    return {
+      user,
+      agent:
+        `DENIED ${user}: \`adl id token\`/\`adl-agent-id exec --agent\`'s agent argument must be a literal agent ` +
+        'name, not a shell expansion — a dynamically computed value could name any agent at runtime, evading ' +
+        `the "own identity only" check entirely. Use the literal agent name. Blocked: ${ctx.snippet}`,
+    }
+  }
+  if (reason === 'network-alias-redefinition') {
+    const user = 'a git alias redefines the command you ran into a network or credential operation'
+    return {
+      user,
+      agent:
+        `DENIED ${user}: the managed front controller (/usr/local/bin/git) routes by the literal command you ` +
+        'typed, not by resolving git aliases itself — an aliased network/credential verb never reaches its ' +
+        'identity routing and would silently fall back to the human credential path. Run the real command ' +
+        `directly instead of aliasing it inline. Blocked: ${ctx.snippet}`,
+    }
+  }
+  const user = "the session's 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`. ' +
+      `Blocked: ${ctx.snippet}`,
+  }
+}
+
+/**
+ * H3 (STATUS.md 12p): 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
+ * 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
+ * comment at this call site. Reuses `NO_AGENT_IDENTITY_MESSAGE` verbatim
+ * (the one standard message every surface shows for "no identity resolved
+ * at all") rather than inventing a second wording for the same condition.
+ */
+export function gitIdentityNeedsIdentityMessage(ctx: MessageContext): RuleMessage {
+  return {
+    user: NO_AGENT_IDENTITY_MESSAGE,
+    agent: `DENIED ${NO_AGENT_IDENTITY_MESSAGE} Blocked: ${ctx.snippet}`,
+  }
+}
+
+/**
+ * The deny rendered when the host's hook contract cannot carry a rewritten
+ * 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
+ * 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.
+ */
+export function hostCannotRewriteMessage(host: string, ctx: MessageContext, agent: string | undefined): RuleMessage {
+  const prefix = `${ADL_AGENT_ID_ENV_VAR}=${agent ?? '<agent>'}`
+  // The prefix is named in BOTH fields, not only `agent` — Kimi (and
+  // 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`
+  return {
+    user,
+    agent:
+      `DENIED ${user}: ${host}'s hook contract has no "replace the tool input" field for this call (verified ` +
+      'against its official docs, 2026-09-28), and this invocation\'s own environment does not carry ' +
+      `${ADL_AGENT_ID_ENV_VAR} — running it unchanged would reach git as the human. Prefix the command with ` +
+      `\`${prefix}\` and retry. Blocked: ${ctx.snippet}`,
+  }
+}
+
+export const adlGitIdentity: RuleSpec = {
+  id: RULE_ID,
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  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 —
+    // `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
+    // 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
+    // `firstFinding` stops at the first rule that reports anything at all.
+    let isIdentityBearing = false
+    if (inv.kind === 'git') {
+      isIdentityBearing = NETWORK_GIT_VERBS.has(inv.subcommand) && !isHelpOnlyInvocation(inv.rest)
+    } else if (inv.kind === 'command') {
+      const dynamic = inv.args.some((token) => dynamicToken(token))
+      const values = inv.args.map((token) => tokenValue(token))
+      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
+        // 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)
+      } else if (HTTP_CLIENT_BINARY_NAMES.has(inv.name)) {
+        isIdentityBearing = inv.args.some((token) => isAdoUrl(tokenValue(token)))
+      }
+    }
+    if (!isIdentityBearing) return null
+
+    const resolution = resolveFromEnvOrFile(ctx.env)
+    const fallback = resolution.ok ? resolution.agent : null
+    // `?? ''` only for hand-built test contexts that omit `command` — the
+    // engine always supplies it; an empty scan finds no conflict.
+    const conflict = scanGitIdentityConflicts(ctx.command ?? '', fallback)
+    if (conflict === null) return null
+    return { ruleId: RULE_ID, severity: 'deny', detail: { reason: conflict } }
+  },
+  message(finding: Finding, ctx: MessageContext): RuleMessage {
+    return gitIdentityDenyMessage(detailString(finding, 'reason') as GitIdentityRuleReason, ctx, undefined)
+  },
+  corpus: {
+    // Every real deny case needs a specific session identity, which the
+    // shared corpus fixture (tests/fixtures/decide.ts) cannot supply — the
+    // real coverage is tests/unit/rules-adl-git-identity.test.ts, built on
+    // custom EngineContexts per env value like rules-adl-git-push-policy.test.ts.
+    deny: [],
+    allow: [
+      'git status',
+      'git log --oneline origin/integration..HEAD',
+      'ls -la',
+    ],
+  },
+}

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

@@ -0,0 +1,258 @@
+/**
+ * `adl.git-push-branch-policy` — docs/operations/agent-permissions.md rows 2, 3 and 4
+ * ("the one source" for this table; a row changes there first).
+ *
+ * Scope: this rule only ever looks at a `git push` whose destination is
+ * Azure DevOps or UNRESOLVED (the same fail-closed classification
+ * `adl.session-required-for-writes` uses, via `classifyGitPushDestination` —
+ * see git-helpers.ts). A push with a PROVEN non-Azure-DevOps destination
+ * (e.g. an explicit `https://github.com/...` URL) is entirely outside this
+ * table's scope and this rule never fires on it.
+ *
+ * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
+ * non-blank). With no identity at all, `adl.session-required-for-writes` is
+ * the rule that denies the push (a different problem: no session, not the
+ * wrong branch or role) — this rule returns null immediately when the env
+ * var is absent or blank, exactly like `adl.role-required`-style rules.
+ *
+ * Three checks, in order (the first that matches wins — a forced push to a
+ * protected branch is still, first and foremost, a forced push):
+ *
+ *  1. Row 4 — `--force`/`-f`/`--force-if-includes`/`--force-with-lease[=...]`,
+ *     a bare leading `+` on a refspec (`+feat/x`, `+feat/x:feat/x`,
+ *     `+HEAD:refs/heads/x` — forces without ever spelling `--force`), or the
+ *     `adl`/`git-ado` policy-bypass flag `--bypass-policy` (not a real `git`
+ *     flag; named explicitly in the matrix, so matched defensively even
+ *     though nothing upstream implements it yet — see
+ *     docs/operations/agent-permissions.md row 4). `--no-verify` is already denied by
+ *     `git.no-verify` (git-verify.ts) for `commit`/`push`/`merge` alike; this
+ *     rule does not duplicate it (docs/operations/agent-permissions.md: "4 ... largely
+ *     exist; extend, don't duplicate"). `-c core.hooksPath=...`/`core.bare`
+ *     riding along with `push` (GIT_CONFIG smuggling) is likewise already
+ *     denied by `git.hooks-path`/`git.core-bare`, which scan `-c core.*=`
+ *     globals ahead of every other git rule (git-core.ts) — also not
+ *     duplicated here.
+ *  2. Row 3 — the destination branch is `integration`/`main`, OR could not be
+ *     determined from argv (a bare `git push`, or `git push origin` with no
+ *     refspec: the current branch is implicit and this rule decides
+ *     statically, off argv alone, the same constraint documented on
+ *     `classifyGitPushDestination`) — denied for EVERY identity, matching the
+ *     matrix's ❌/❌ for this row. An unrecognized branch name (neither a
+ *     protected name nor a recognized feature prefix) fails closed into this
+ *     same bucket: the matrix only grants an exception for the four listed
+ *     prefixes, not for "anything else". `develop` is retired
+ *     (docs/specs/two-branch-standard-2026-09-27.md §1b.2 — the standard is
+ *     two branches, not three) and is deliberately NOT a named protected
+ *     branch any more; a push to it still lands in this same bucket, but as
+ *     an ordinary unrecognized name, not a special case.
+ *  3. Row 2 — the destination is a recognized feature branch
+ *     (`feat/ fix/ docs/ chore/`): allowed for `agent-tarun`/`agent-vivek`
+ *     (Azure DevOps Contributors, and this is the ordinary way they ship
+ *     work); denied for `agent-reviewer` (Azure DevOps Reader — cannot push
+ *     at all, see docs/enact/handoff-enact-vps-global-tools-2026-09-25.md's
+ *     "Azure DevOps permissions are the backstop").
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Token } from '../shell/token.ts'
+import { tokenValue } from '../shell/token.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { AGENT_REVIEWER, resolveFromEnvOrFile } from './adl-identity.ts'
+import { effectiveIdentityForCommand, scanGitInvocationPieces } from '../shell/git-identity.ts'
+import { classifyGitPushDestination, hasFlagOrCluster, isHelpOnlyInvocation } from './git-helpers.ts'
+import { defaultGitMessage, detailString } from './messages.ts'
+
+const RULE_ID = 'adl.git-push-branch-policy'
+
+/**
+ * The effective identity for THIS specific push invocation (M2/M3,
+ * STATUS.md 12p) — not
+ * `effectiveIdentityForCommand`'s whole-command coarse value, which is set
+ * from whichever piece on the line happens to carry a valid inline override
+ * FIRST and would otherwise be applied to grading EVERY push on a compound
+ * command line alike. A reviewer session could smuggle a push to a feature
+ * branch (denied for agent-reviewer) past this rule just by chaining a
+ * second, unrelated push with its own override after it on the same line.
+ *
+ * Correlates `inv` (the `'git'`-kind Invocation the engine is grading, from
+ * the shared shell/invocation.ts classifier) to ITS OWN piece from
+ * `scanGitInvocationPieces` (a separate, offset-aware scanner) by
+ * subcommand + exact dequoted `rest` value match — the two parsers are
+ * independent implementations, so this is a best-effort correlation, not a
+ * shared identity. Two pushes with IDENTICAL destinations on the same
+ * command line (e.g. `git push origin main && git push origin main` with
+ * different overrides on each) are genuinely ambiguous even to a human
+ * reader; the first matching piece is used, same coarseness precedent as
+ * `commandHasValidInlineIdentity`'s own documented tradeoff. If no piece
+ * correlates at all (the two parsers disagreed on how many network git
+ * invocations this line contains — should not happen for any command shape
+ * either parser is deliberately designed to handle, and no such disagreement
+ * is currently known), this falls back to the OLD whole-command coarse value
+ * rather than a hard failure — never a worse outcome than before this fix,
+ * only a more precise one when the piece is found.
+ */
+function effectiveIdentityForPush(inv: Invocation & { kind: 'git' }, command: string, fallback: string | null): string | null {
+  const restValues = inv.rest.map((token) => tokenValue(token))
+  const pieces = scanGitInvocationPieces(command, fallback)
+  const match = pieces.find((piece) => piece.subcommand === 'push' && piece.rest.length === restValues.length && piece.rest.every((value, index) => value === restValues[index]))
+  if (match !== undefined) return match.effectiveAgent
+  return effectiveIdentityForCommand(command, fallback)
+}
+
+/**
+ * The refspec force marker: a leading `+` on a refspec token means "force
+ * this update" independently of the `--force`/`-f` FLAG — `git push origin
+ * +feat/x:feat/x` (or the same-name form `+feat/x`) forces without ever
+ * spelling `--force`. The marker always sits at the very start of the
+ * refspec (before any `:`), so checking the raw token — not just its
+ * destination half — is enough; a remote name or URL never legitimately
+ * starts with `+`, so this needs no separate "skip the remote" bookkeeping
+ * the way `pushDestinationBranches` does.
+ */
+function pushHasForceRefspecMarker(rest: readonly Token[]): boolean {
+  return rest.some((token) => tokenValue(token).startsWith('+'))
+}
+
+function pushIsForced(rest: readonly Token[]): boolean {
+  if (hasFlagOrCluster(rest, ['--force', '--force-if-includes'], ['f'])) return true
+  if (
+    rest.some((token) => {
+      const value = tokenValue(token)
+      return value === '--force-with-lease' || value.startsWith('--force-with-lease=')
+    })
+  ) {
+    return true
+  }
+  return pushHasForceRefspecMarker(rest)
+}
+
+function pushBypassesPolicy(rest: readonly Token[]): boolean {
+  return rest.some((token) => {
+    const value = tokenValue(token)
+    return value === '--bypass-policy' || value.startsWith('--bypass-policy=')
+  })
+}
+
+const PROTECTED_BRANCHES: ReadonlySet<string> = new Set(['integration', 'main'])
+const FEATURE_PREFIXES: readonly string[] = ['feat/', 'fix/', 'docs/', 'chore/']
+
+function normalizeBranchRef(ref: string): string {
+  return ref.startsWith('refs/heads/') ? ref.slice('refs/heads/'.length) : ref
+}
+
+function isFeatureBranchName(branch: string): boolean {
+  return FEATURE_PREFIXES.some((prefix) => branch.startsWith(prefix))
+}
+
+/**
+ * The destination branch name(s) a `git push`'s argv names EXPLICITLY — no
+ * subprocess, no `git symbolic-ref`/`rev-parse` (same static-off-argv
+ * constraint as `classifyGitPushDestination`). A refspec is `<src>:<dst>`
+ * (destination is the part after `:`) or a bare `<branch>` (same-name push:
+ * the token itself IS the destination). The first non-flag, non-URL token is
+ * the remote name/URL and is skipped, not treated as a branch.
+ */
+function pushDestinationBranches(rest: readonly Token[]): string[] {
+  const branches: string[] = []
+  let sawRemote = false
+  for (const token of rest) {
+    const value = tokenValue(token)
+    if (value === '--') continue
+    if (value.startsWith('-')) continue
+    if (!sawRemote) {
+      sawRemote = true
+      continue // the remote name (or an explicit destination URL) itself
+    }
+    const colon = value.indexOf(':')
+    const dest = colon >= 0 ? value.slice(colon + 1) : value
+    if (dest.length > 0) branches.push(normalizeBranchRef(dest))
+  }
+  return branches
+}
+
+/** True only when every named destination is a recognized feature-branch prefix; false (fail closed) for zero branches (unresolved) or any unrecognized name. */
+function pushTargetsOnlyFeatureBranches(rest: readonly Token[]): boolean {
+  const branches = pushDestinationBranches(rest)
+  if (branches.length === 0) return false
+  return branches.every((branch) => isFeatureBranchName(branch) && !PROTECTED_BRANCHES.has(branch))
+}
+
+type PushViolation = 'force' | 'bypass-policy' | 'protected-branch' | 'reviewer-cannot-push'
+
+export const adlGitPushBranchPolicy: RuleSpec = {
+  id: RULE_ID,
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny force/bypass-policy pushes and pushes to integration/main; route feature-branch pushes by role.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    if (inv.kind !== 'git' || inv.subcommand !== 'push') return null
+    if (isHelpOnlyInvocation(inv.rest)) return null
+
+    // WIDENED 2026-09-28 (W2 build item 2): grade the EFFECTIVE identity for
+    // THIS command — a valid inline ADL_AGENT_ID_AGENT= override on the push
+    // itself wins over the session's own env/default-file resolution (the
+    // override is a per-command identity switch: `agent-reviewer may not
+    // push` must hold even when the session's own identity is
+    // agent-tarun/agent-vivek but the command overrides to agent-reviewer).
+    const resolution = resolveFromEnvOrFile(ctx.env)
+    const fallback = resolution.ok ? resolution.agent : null
+    // M2/M3: THIS push's own piece, not the whole command's coarse value — see effectiveIdentityForPush's doc.
+    const agent = effectiveIdentityForPush(inv, ctx.command ?? '', fallback)
+    if (agent === null) return null // no identity at all: adl.session-required-for-writes's job
+
+    const destinationRisk = classifyGitPushDestination(inv.rest)
+    if (destinationRisk === 'non-ado') return null // out of this table's scope entirely
+
+    let violation: PushViolation
+    if (pushIsForced(inv.rest)) {
+      violation = 'force'
+    } else if (pushBypassesPolicy(inv.rest)) {
+      violation = 'bypass-policy'
+    } else if (pushTargetsOnlyFeatureBranches(inv.rest)) {
+      if (agent === AGENT_REVIEWER) violation = 'reviewer-cannot-push'
+      else return null
+    } else {
+      violation = 'protected-branch'
+    }
+
+    return { ruleId: RULE_ID, severity: 'deny', detail: { violation } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const violation = detailString(finding, 'violation') as PushViolation
+
+    if (violation === 'force') return defaultGitMessage('git push --force (or --force-with-lease)', ctx.snippet)
+    if (violation === 'bypass-policy') return defaultGitMessage('git push --bypass-policy', ctx.snippet)
+
+    if (violation === 'protected-branch') {
+      const user = 'protected branch: push a feature branch and open a PR'
+      return {
+        user,
+        agent: `DENIED ${user}. \`integration\`/\`main\` (and any branch this hook cannot resolve from argv alone, including a retired name like \`develop\`) never take a direct push — push a \`feat/ fix/ docs/ chore/\` branch and open a PR. Blocked: ${ctx.snippet}`,
+      }
+    }
+
+    const user = 'this operation can only be done with agent-tarun or agent-vivek'
+    return {
+      user,
+      agent: `DENIED ${user}. \`agent-reviewer\` is an Azure DevOps Reader and cannot push. Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    // Every real case here needs ADL_AGENT_ID_AGENT set to a specific agent,
+    // which the shared corpus fixture (tests/fixtures/decide.ts) cannot
+    // supply — see tests/unit/rules-adl-git-push-policy.test.ts for the real
+    // coverage, built the same way tests/unit/rules-tool-search.test.ts and
+    // rules-adl-session-required.test.ts's az-CLI split are (a custom
+    // EngineContext per env value, decide() called directly).
+    deny: [],
+    // `git fetch origin main` itself is no longer end-to-end allowed without
+    // an identity (adl.session-required-for-writes now covers reads too,
+    // 2026-09-28) — an explicit non-ADO destination stays provably safe
+    // and still proves this rule (which only ever looks at `push`) does not
+    // fire on a fetch.
+    allow: ['ls -la', 'git status', 'git fetch https://github.com/org/repo main'],
+  },
+}