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

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

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

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

@@ -41,7 +41,7 @@
  * matching a guessed tool name now.
  *
  * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
- * non-blank) — with no identity at all, `adl.session-required-for-writes`
+ * non-blank) — with no identity at all, `adl.run-required-for-writes`
  * denies the call first (a different problem: no session, not the wrong
  * role), so this rule returns null when the env var is absent or blank.
  */
@@ -70,16 +70,14 @@ export const adlPrCreateUpdateRole: RuleSpec = {
     'Deny pr_create_or_update for any identity other than a builder (agent-tarun/agent-vivek) or agent-reviewer (docs/operations/agent-permissions.md row 5).',
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
-    // M4 (STATUS.md 12p): `adl mcp cli
-    // pr-create-or-update` dispatches to the same tool the MCP server calls.
+    // `adl mcp cli pr-create-or-update` dispatches to the same tool the MCP server calls.
     const call = toolCallFor(inv)
     if (call === null) return null
     if (mcpToolName(call.tool) !== 'pr_create_or_update') return null
 
-    // R5 (STATUS.md 12p, re-review 2026-09-28 night):
-    // grade the EFFECTIVE identity for THIS specific piece — a valid inline
+    // Grade the EFFECTIVE identity for THIS specific piece — a valid inline
     // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation
-    // still wins, exactly like M3 already does for `git push` (see
+    // still wins, exactly like it does for `git push` (see
     // `effectiveIdentityForMcpCli`'s own doc). A real MCP tool-call payload
     // carries no command text at all (no inline override possible), so this
     // still resolves to the plain session identity for that shape — env,
@@ -88,7 +86,7 @@ export const adlPrCreateUpdateRole: RuleSpec = {
     const resolution = resolveFromEnvOrFile(ctx.env)
     const fallback = resolution.ok ? resolution.agent : null
     const agent = effectiveIdentityForMcpCli(inv, ctx.command ?? '', fallback)
-    if (agent === null) return null // no identity at all: adl.session-required-for-writes's job
+    if (agent === null) return null // no identity at all: adl.run-required-for-writes's job
 
     // Not a builder and not agent-reviewer: denied regardless of shape — this
     // is the more fundamental restriction, so it reports even for a call that

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

@@ -0,0 +1,411 @@
+/**
+ * `adl.run-required-for-writes` — the managed baseline hook (docs/architecture/cli-design.md
+ * §2/§3).
+ *
+ * Widened 2026-09-28 by the one-agent-identity standard (Tarun): the rule id
+ * is kept stable, but this rule's job is no longer "writes only". Every Azure DevOps access
+ * — reads included — needs a resolvable agent identity now: the session env
+ * (set by the surface's managed default), the machine default-agent file
+ * (`adl-identity.ts`'s `resolveFromEnvOrFile`, steps 2-3 of the standard),
+ * or a valid inline `ADL_AGENT_ID_AGENT=<agent>` override on the command
+ * itself (step 1, detected via `../shell/git-identity.ts`'s
+ * `commandHasValidInlineIdentity` — see `checkResolvableIdentity` below). With
+ * NONE of those present, this rule denies every identity-bearing command
+ * class (git network reads/writes, the azdo MCP tools including their reads,
+ * `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 under any HTTP method) with the
+ * standard's own message; every other command is left alone. Once an
+ * identity resolves, this rule gets out of the way entirely — `git-ado`/
+ * `adl`'s own rules, and the role rules, police what an authenticated
+ * run may do.
+ *
+ * Four write surfaces, each inspected in the shape the shell/tool-call
+ * classifier already hands every other rule:
+ *
+ *  - `git push` (`../shell/invocation.ts`'s `'git'` kind). The hook cannot run
+ *    `git remote get-url` (it decides before the child runs, statically, off
+ *    argv alone) the way the deployed `bin/git` front controller can — so an
+ *    explicit `https://.../dev.azure.com/...` URL anywhere in the push's
+ *    arguments is authoritative, and otherwise the destination is UNRESOLVED
+ *    (a bare `git push`, or `git push origin main` naming a remote this rule
+ *    cannot look up) and fails closed: unresolved is treated exactly like
+ *    "proven Azure DevOps", because the rule cannot prove otherwise. Only an
+ *    explicit NON-Azure-DevOps URL is provably safe and lets a write through
+ *    without an identity. `git-verify.ts`'s `git.no-verify` corpus already
+ *    anticipates this: its own `allow` list deliberately never contains a bare
+ *    `git push` or `git push -n`, see the comment there and
+ *    `rules-corpus-executed.test.ts`'s "corrected corpus entries" check.
+ *  - `az devops|repos|pipelines|boards|artifacts ...` (the `'azure-devops'`
+ *    kind). `tool.azure-devops` (`./tool-azure-devops.ts`) already denies
+ *    EVERY direct invocation of this family outright, read or write,
+ *    identity or not, steering everything at the MCP server — and it is
+ *    registered ahead of this rule, so in the real engine it always reports
+ *    first. This rule's own az-CLI classification (read verbs `list`/`show`/
+ *    `get`/`query` vs. everything else, fail-closed to "write" when neither
+ *    matches) is therefore defense in depth for a repository that disables
+ *    `tool.azure-devops` (`[rules."tool.azure-devops"] enabled = false`), not
+ *    something reachable through `decide()` today — see
+ *    `tests/unit/rules-adl-run-required.test.ts`, which exercises it via
+ *    a direct `match()` call rather than the shared corpus (which runs
+ *    through the real engine and would otherwise always see `tool.azure-devops`
+ *    win first).
+ *  - `curl`/`wget`/httpie (`http`/`https`)/`xh` (the generic `'command'` kind)
+ *    with a non-GET method against a `dev.azure.com` URL. curl's method is
+ *    explicit (`-X`/`--request`) or implied by a data flag (`-d`/`--data*`,
+ *    `-F`/`--form`, `--json`); wget's by `--method=`/`--post-data`/
+ *    `--post-file`; httpie/xh's by an explicit leading method argument or a
+ *    request-item/`--form`/`--raw` implying a body (httpie's own semantics:
+ *    a request with data defaults to POST, one without defaults to GET).
+ *  - An Azure DevOps MCP write tool (the `'tool-call'` kind), named
+ *    `mcp__<prefix>__<tool>` where `<tool>` is one of the four mutating
+ *    tools `packages/azdo/src/mcp-server.ts` actually registers:
+ *    `pr_create_or_update`, `pr_review`, `build_run`, `workitem_create_or_update`. The
+ *    match is on the TOOL NAME alone, not the server prefix — the package is
+ *    `azdo`, P4 folds the server under `adl`, and Claude Code's plugin-scoped
+ *    form (`mcp__plugin_<plugin>_<server>__<tool>`) adds a third spelling —
+ *    so `mcp__azdo__...`, `mcp__adl__...`, `mcp__azure-devops-mcp__...` and
+ *    `mcp__plugin_adl_azdo__...` are all matched the same way. Its three read
+ *    tools (`pr_list_or_get`, `build_list_or_get`, `workitem_list_or_get`)
+ *    are left alone under every one of those prefixes too.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Token } from '../shell/token.ts'
+import { dynamicToken, tokenValue } from '../shell/token.ts'
+import { commandHasValidInlineIdentity, isNetworkGitInvocation } from '../shell/git-identity.ts'
+import type { EnvPort } from '../ports.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import {
+  ADL_AGENT_ID_BINARY_NAMES,
+  ADL_AGENT_ID_COMMAND_SHAPES,
+  ADL_BINARY_NAMES,
+  ADL_IDENTITY_COMMAND_SHAPES,
+  classifyGitPushDestination,
+  containsIdentityBearingToken,
+  HTTP_CLIENT_BINARY_NAMES,
+  httpClientMethod,
+  isAdoUrl,
+  isHelpOnlyInvocation,
+  matchesIdentityShape,
+  skipLeadingDashFlags,
+} from './git-helpers.ts'
+import { NO_AGENT_IDENTITY_MESSAGE, resolveFromEnvOrFile } from './adl-identity.ts'
+import { detailString } from './messages.ts'
+import { mcpToolName } from './mcp-tool.ts'
+
+const RULE_ID = 'adl.run-required-for-writes'
+const ENV_VAR = 'ADL_AGENT_ID_AGENT'
+
+/**
+ * Whether an identity is
+ * resolvable for `command`, and if not, the EXACT message to show — the
+ * one standard `NO_AGENT_IDENTITY_MESSAGE` when nothing is configured at
+ * all, or the SPECIFIC named error when something IS configured but is
+ * invalid (an unrecognized `ADL_AGENT_ID_AGENT` value, or a default-agent
+ * file naming an agent outside `VALID_AGENTS`) — `resolveFromEnvOrFile`'s
+ * own `UnresolvedIdentity.message` already carries exactly the right text
+ * for either case (see `adl-identity.ts`'s `resolveFromEnvOrFile`: it is
+ * `NO_AGENT_IDENTITY_MESSAGE` verbatim for `reason: 'none'`, and the named
+ * `invalidAgentError` text for `reason: 'invalid'`), so this reads that
+ * message through rather than reporting the SAME generic "run the fleet
+ * reconcile" text regardless of which of the two actually happened — an
+ * invalid identity is a materially different, more actionable diagnosis
+ * than none configured at all, and reporting the generic text for both
+ * hid that distinction from the agent.
+ *
+ * A valid inline `ADL_AGENT_ID_AGENT=<agent>` override anywhere on the
+ * command line (step 1 of the standard — coarse, whole-command; see
+ * `commandHasValidInlineIdentity`'s own doc for what that trades off)
+ * resolves too, without needing the session env / machine default-agent
+ * file (steps 2-3) at all.
+ */
+type IdentityCheck = { readonly resolvable: true } | { readonly resolvable: false; readonly message: string }
+
+function checkResolvableIdentity(command: string, env: EnvPort): IdentityCheck {
+  if (commandHasValidInlineIdentity(command)) return { resolvable: true }
+  const resolution = resolveFromEnvOrFile(env)
+  return resolution.ok ? { resolvable: true } : { resolvable: false, message: resolution.message }
+}
+
+const classifyPush = classifyGitPushDestination
+
+/**
+ * az CLI verbs that only read. Fail-closed by design: anything NOT
+ * recognized here (including a verb this list simply does not know about
+ * yet) is treated as a write, never the reverse. Recognized against the
+ * FULL args after `az` (the subcommand group included, e.g. `repos pr
+ * list`) — a flag's VALUE (`--status active`) could in principle collide
+ * with a verb spelling, an accepted heuristic risk given `tool.azure-devops`
+ * denies the whole family outright regardless (see header).
+ */
+const AZ_READ_VERBS: ReadonlySet<string> = new Set(['list', 'show', 'get', 'query'])
+
+function azCommandIsWrite(args: readonly Token[]): boolean {
+  for (const token of args) {
+    const value = tokenValue(token).toLowerCase()
+    if (value.startsWith('-')) continue
+    if (AZ_READ_VERBS.has(value)) return false
+  }
+  return true
+}
+
+/**
+ * The name set and the per-binary method detection live in
+ * `git-helpers.ts`'s `HTTP_CLIENT_BINARY_NAMES`/`httpClientMethod` — shared
+ * with `tool-azure-devops.ts`'s WRITE-outright deny
+ * (docs/operations/agent-permissions.md row 13), so the two cannot classify
+ * the same command two different ways.
+ */
+const HTTP_CLIENT_NAMES = HTTP_CLIENT_BINARY_NAMES
+
+/**
+ * Azure DevOps MCP write tools, derived from `packages/azdo/src/mcp-server.ts`'s
+ * `ListToolsRequestSchema` handler (re-checked 2026-10-01) — the
+ * complete tool roster there is `pr_list_or_get`/`pr_create_or_update`/
+ * `pr_review`, `build_list_or_get`/`build_run`, `workitem_list_or_get`/
+ * `workitem_create_or_update`; the three not in this set are the read half.
+ * `pr_review` (docs/operations/agent-permissions.md rows 6-8: comment + vote) is
+ * in this set because `adl-pr-review-role.ts` gates it by role —
+ * a caller with no run identity at all must be denied here FIRST, the
+ * same "no session, not merely the wrong role" ordering `adl-pr-role.ts`
+ * documents for `pr_create_or_update`.
+ */
+const ADO_MCP_WRITE_TOOLS: ReadonlySet<string> = new Set([
+  'pr_create_or_update',
+  'pr_review',
+  'build_run',
+  'workitem_create_or_update',
+])
+
+/**
+ * The standard requires an identity for every Azure
+ * DevOps MCP tool call, reads included — the read half gets no
+ * pass just because it cannot mutate anything. `mcp-server.ts`'s complete
+ * roster: `pr_list_or_get`, `build_list_or_get`, `workitem_list_or_get`
+ * (reads) alongside the four writes above.
+ */
+/** The leading words of the `identityBearingReason` for an Azure DevOps MCP tool call — `message()` keys the MCP-only CLI advice off it. */
+const MCP_REASON_PREFIX = 'Azure DevOps MCP tool'
+
+const ADO_MCP_ALL_TOOLS: ReadonlySet<string> = new Set([...ADO_MCP_WRITE_TOOLS, 'pr_list_or_get', 'build_list_or_get', 'workitem_list_or_get'])
+
+/** `adl <...>` shapes that need an identity even with no HTTP client or git verb involved — see `git-helpers.ts`'s `ADL_IDENTITY_COMMAND_SHAPES`. */
+const ADL_BINARY_ALL_NAMES: ReadonlySet<string> = ADL_BINARY_NAMES
+const ADL_AGENT_ID_BINARY_ALL_NAMES: ReadonlySet<string> = ADL_AGENT_ID_BINARY_NAMES
+
+/**
+ * Interpreter one-liners whose `-c`/`-e`/`--eval` code string names an
+ * identity-bearing operation — `../shell/invocation.ts`'s walker classifies
+ * these as a plain, unclassified `'command'` Invocation (it only re-parses
+ * `-c` as shell for `sh`/`bash`/`zsh`/`dash`/`ksh`/`fish`, never an
+ * interpreter's own code), so
+ * `python3 -c "import subprocess; subprocess.run(['git','push'])"` would be
+ * invisible to this rule without this check. Deliberately coarse
+ * (`containsIdentityBearingToken`, textual) — precise parsing of arbitrary
+ * Python/JS/Perl/Ruby/AppleScript source is not this rule's job.
+ */
+const INTERPRETER_ONE_LINER_NAMES: ReadonlySet<string> = new Set([
+  'python', 'python.exe', 'python2', 'python2.exe', 'python3', 'python3.exe',
+  'node', 'node.exe', 'perl', 'perl.exe', 'ruby', 'ruby.exe', 'bun', 'bun.exe',
+  'osascript', 'osascript.exe',
+])
+const INTERPRETER_CODE_FLAGS: ReadonlySet<string> = new Set(['-c', '-e', '--eval'])
+
+/** Every code string passed via `-c`/`-e`/`--eval` among `args` — the token immediately following the flag. */
+function interpreterCodeStrings(args: readonly Token[]): readonly string[] {
+  const codes: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (!INTERPRETER_CODE_FLAGS.has(tokenValue(args[index] as Token))) continue
+    const next = args[index + 1]
+    if (next !== undefined) codes.push(tokenValue(next))
+  }
+  return codes
+}
+
+/**
+ * Whether `inv` is a candidate this rule cares about at all, and if so, the
+ * "reason" text for its Finding — computed WITHOUT ever resolving an
+ * identity (see `match`'s own comment on resolution order for why the ordering matters). The
+ * four surfaces are exactly the ones documented in this file's header.
+ */
+/**
+ * Exported for `../../pre-tool-use/handler.ts`'s own broader net: a
+ * walker-visible identity-bearing shape the narrow `adl.git-identity` rewrite scanner does not recognize (buried
+ * inside `if`/`!`/`for..do`/`xargs`/a heredoc or here-string/a piped-into
+ * shell) still needs denying when the resolved identity cannot actually
+ * reach THIS specific host/tool-class's child process — this rule alone
+ * cannot make that call (it has no host/tool-class in its `RuleContext`),
+ * but it IS the one place that already classifies every one of those shapes
+ * correctly (see this file's header), so the handler reuses this function
+ * rather than re-deriving the same walker-based classification a second
+ * time.
+ */
+export function identityBearingReason(inv: Invocation): string | null {
+  if (inv.kind === 'git') {
+    // Wider than a plain
+    // `NETWORK_GIT_VERBS.has(inv.subcommand)` gate — see
+    // `isNetworkGitInvocation`'s own doc for the additional network-reaching
+    // shapes now covered (git remote show/prune/update/set-head -a, git
+    // maintenance run --task=prefetch, the remote-https/remote-http/
+    // http-fetch transport helpers, git submodule update/sync --recursive,
+    // git archive --remote).
+    if (!isNetworkGitInvocation(inv.subcommand, inv.rest.map(tokenValue))) return null
+    if (isHelpOnlyInvocation(inv.rest)) return null
+    const risk = classifyPush(inv.rest)
+    if (risk === 'non-ado') return null
+    const verbLabel = inv.subcommand === 'push' ? 'git push' : `git ${inv.subcommand}`
+    return risk === 'ado' ? `${verbLabel} against a dev.azure.com remote` : `${verbLabel} with an unresolved (implicit) remote destination`
+  }
+
+  if (inv.kind === 'azure-devops') {
+    // Defense in depth only — tool.azure-devops (registered ahead of this
+    // rule in ../registry.ts) already denies the whole `az devops|repos|
+    // pipelines|boards|artifacts` family outright, read or write, identity
+    // or not. See this file's header.
+    return azCommandIsWrite(inv.args) ? 'az CLI Azure DevOps write' : null
+  }
+
+  if (inv.kind === 'command') {
+    if (HTTP_CLIENT_NAMES.has(inv.name)) {
+      const targetsAdo = inv.args.some((token) => isAdoUrl(tokenValue(token)))
+      if (!targetsAdo) return null
+      // Every method needs an identity, GET included — the standard covers
+      // reads too, not only the mutating methods.
+      const method = httpClientMethod(inv.name, inv.args)
+      return `${inv.name} ${method} to dev.azure.com/visualstudio.com`
+    }
+    if (ADL_BINARY_ALL_NAMES.has(inv.name)) {
+      const values = inv.args.map((token) => tokenValue(token))
+      if (inv.args.some((token) => dynamicToken(token))) return null
+      if (!matchesIdentityShape(values, ADL_IDENTITY_COMMAND_SHAPES)) return null
+      return `${inv.name} ${values.slice(0, 3).join(' ')}`
+    }
+    if (ADL_AGENT_ID_BINARY_ALL_NAMES.has(inv.name)) {
+      const values = inv.args.map((token) => tokenValue(token))
+      if (inv.args.some((token) => dynamicToken(token))) return null
+      // Leading dash-prefixed
+      // global flags are skipped before matching the `['exec']` shape —
+      // see git-helpers.ts's skipLeadingDashFlags doc.
+      if (!matchesIdentityShape(skipLeadingDashFlags(values), ADL_AGENT_ID_COMMAND_SHAPES)) return null
+      return `${inv.name} ${values.slice(0, 3).join(' ')}`
+    }
+    if (INTERPRETER_ONE_LINER_NAMES.has(inv.name)) {
+      const identityBearing = interpreterCodeStrings(inv.args).some((code) => containsIdentityBearingToken(code))
+      return identityBearing ? `${inv.name} interpreter one-liner` : null
+    }
+    return null
+  }
+
+  if (inv.kind === 'tool-call') {
+    const toolName = mcpToolName(inv.tool)
+    if (toolName === null || !ADO_MCP_ALL_TOOLS.has(toolName)) return null
+    return `${MCP_REASON_PREFIX} ${inv.tool}`
+  }
+
+  return null
+}
+
+export const adlRunRequiredForWrites: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny Azure DevOps access (git, az CLI, curl/wget/httpie, adl entry points, MCP tools) with no resolvable ADL agent identity.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    // The shape check runs
+    // FIRST, entirely without touching `ctx.env` — `checkResolvableIdentity`
+    // can hit the real filesystem (the machine default-agent file) once
+    // neither the command's own inline override nor the session env
+    // resolves, so it must not run for every invocation this rule is asked
+    // about. The vast majority (ls, cat, git status, an unrelated tool
+    // call, …) are not identity-bearing at all and, with this ordering,
+    // never reach `checkResolvableIdentity` — only a genuine candidate does.
+    const reason = identityBearingReason(inv)
+    if (reason === null) return null
+
+    const identity = checkResolvableIdentity(ctx.command ?? '', ctx.env)
+    if (identity.resolvable) return null
+    // The exact message this specific failure earns — NOT a fixed
+    // generic string — carried in the Finding so message() reports it
+    // faithfully instead of a constant that cannot distinguish "nothing
+    // configured" from "something IS configured but it's wrong".
+    return { ruleId: RULE_ID, severity: 'deny', detail: { reason, identityMessage: identity.message } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const reason = detailString(finding, 'reason')
+    const identityMessage = detailString(finding, 'identityMessage')
+    // NO_AGENT_IDENTITY_MESSAGE (the "nothing configured at all" case) IS
+    // ALREADY "prefix the command with ADL_AGENT_ID_AGENT=<agent-...>" —
+    // appending the same advice a second time, in slightly different
+    // wording, would say it twice. The INVALID case (something IS configured, but names an agent
+    // outside VALID_AGENTS) has no such text at all, so the "how to fix it"
+    // sentence is the only place that advice appears for it and stays.
+    const advice = identityMessage === NO_AGENT_IDENTITY_MESSAGE ? '' : ` Prefix the command with ${ENV_VAR}=<agent>.`
+    // An MCP tool call carries no command text, so "prefix the command"
+    // cannot apply to it (Tarun, 2026-10-01): its identity comes from the
+    // environment or the machine default-agent file. MCP stays the primary
+    // route; `adl mcp cli <command>` is the FALLBACK when no identity
+    // resolves for the MCP server, and it takes the inline prefix like any
+    // command. Never `adl run` / "start the session" — see
+    // docs/operations/agent-permissions.md.
+    const cliAdvice = reason.startsWith(MCP_REASON_PREFIX)
+      ? ` An MCP tool call cannot carry an inline prefix; its identity comes from the environment or the machine default-agent file. Until one resolves, use the fallback: ${ENV_VAR}=<agent> adl mcp cli <command>.`
+      : ''
+    return {
+      user: `${identityMessage}${cliAdvice}`,
+      agent: `DENIED ${reason} without an ADL agent identity. ${identityMessage}${advice}${cliAdvice} Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [
+      'git push https://dev.azure.com/org/project/_git/repo main',
+      'git push origin main',
+      'git push',
+      // Git network READS need an identity too — every Azure DevOps access
+      // does, not only writes.
+      'git fetch origin main',
+      'git clone https://dev.azure.com/org/project/_git/repo',
+      'git ls-remote https://dev.azure.com/org/project/_git/repo',
+      'curl -X POST https://dev.azure.com/org/project/_apis/git/repositories',
+      'wget --method=POST https://dev.azure.com/org/project/_apis/git/repositories',
+      // A plain GET to dev.azure.com needs an identity too.
+      'curl https://dev.azure.com/org/project/_apis/git/repositories',
+      'wget https://dev.azure.com/org/project/_apis/git/repositories',
+      // The adl entry points that reach Azure DevOps.
+      'adl mcp cli pr-list-or-get',
+      'adl repo doctor',
+      'adl repo controls azdo-push',
+      'adl id token agent-tarun',
+      'adl-agent-id exec --agent agent-tarun -- adl id token agent-tarun --json',
+      // Already denied outright by tool.azure-devops (steers at the MCP server) —
+      // kept here too so this rule's own corpus is non-empty and honest about
+      // az CLI being a write surface it cares about; see the header for why
+      // its OWN read/write split is exercised in a dedicated unit test instead.
+      'az repos pr create --title x',
+    ],
+    allow: [
+      // Explicit non-ADO destination: provably safe without an identity.
+      'git push https://github.com/org/repo main',
+      'git fetch https://github.com/org/repo main',
+      'curl https://github.com/org/repo',
+      'wget https://github.com/org/repo',
+      // Non-identity-bearing local commands and adl subcommands are untouched.
+      'git status',
+      'ls -la',
+      'adl run -- claude',
+      'adl repo controls compliance --repo .',
+      // A valid inline override supplies its own identity. A feature-branch
+      // destination (not `main`/`integration`) is used here so this stays a
+      // clean example of THIS rule's own concern — adl.git-push-branch-policy
+      // grades the command's EFFECTIVE identity too, so an inline-only
+      // override does not bypass branch protection:
+      // `ADL_AGENT_ID_AGENT=agent-tarun git push origin main` is denied by
+      // that rule, not allowed by this one.
+      'ADL_AGENT_ID_AGENT=agent-tarun git push origin feat/x',
+      'ADL_AGENT_ID_AGENT=agent-tarun adl id token agent-tarun',
+    ],
+  },
+}

package/packages/agent-hooks/src/rules/impl/adl-token-minting-role.ts

@@ -1,6 +1,5 @@
 /**
- * `adl.token-minting-role` — W2 build item 1
- * (STATUS.md 12p): an agent may mint a bearer
+ * `adl.token-minting-role` — one-agent-identity standard: an agent may mint a bearer
  * token, or exec as an agent identity, only for its OWN effective identity —
  * never for a different agent whose passport happens to be installed on the
  * same machine. Covers the two token-minting entry points the standard
@@ -12,7 +11,7 @@
  * `ADL_AGENT_ID_AGENT=<value>` on the command wins (step 1); otherwise the
  * session's resolved identity, env then the machine default-agent file
  * (`adl-identity.ts`'s `resolveFromEnvOrFile`, steps 2-3). With no identity
- * at all, this rule stays silent — `adl.session-required-for-writes` denies
+ * at all, this rule stays silent — `adl.run-required-for-writes` denies
  * the call first (no session, not the wrong agent); with an invalid/empty
  * inline override or an unrewritable sudo/doas wrapper, `adl.git-identity`
  * denies first (registered ahead of this rule — see `../registry.ts`). This
@@ -56,7 +55,7 @@ export const adlTokenMintingRole: RuleSpec = {
     if (scanGitIdentityConflicts(command, fallback) !== null) return null
 
     for (const piece of scanTokenMintingPieces(command, fallback)) {
-      if (piece.effectiveAgent === null) continue // adl.session-required-for-writes's job
+      if (piece.effectiveAgent === null) continue // adl.run-required-for-writes's job
       if (piece.effectiveAgent === piece.requestedAgent) continue
       return {
         ruleId: RULE_ID,
@@ -84,7 +83,7 @@ export const adlTokenMintingRole: RuleSpec = {
     // adl.git-identity / adl.git-push-branch-policy — the shared corpus
     // fixture (tests/fixtures/decide.ts) is hermetically identity-less, so
     // even a bare `adl id token`/`adl-agent-id exec` there is denied by
-    // adl.session-required-for-writes first, not usable as an allow entry
+    // adl.run-required-for-writes first, not usable as an allow entry
     // here. Real coverage is tests/unit/rules-adl-token-minting-role.test.ts.
     deny: [],
     allow: ['ls -la', 'git status'],

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

@@ -12,7 +12,7 @@
  * order"); `tool.azure-devops` keeps denying the raw `az` form unchanged.
  *
  * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
- * non-blank) — with no identity at all, `adl.session-required-for-writes`
+ * non-blank) — with no identity at all, `adl.run-required-for-writes`
  * denies the call first, so this rule returns null when the env var is
  * absent or blank.
  */
@@ -32,20 +32,19 @@ export const adlWorkitemRequiresTarunOrVivek: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny workitem_create_or_update for agent-reviewer (docs/operations/agent-permissions.md row 10) — the MCP tool AND its adl mcp cli equivalent (M4).',
+  summary: 'Deny workitem_create_or_update for agent-reviewer (docs/operations/agent-permissions.md row 10) — the MCP tool AND its adl mcp cli equivalent.',
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
-    // M4 (STATUS.md 12p): `adl mcp cli
+    // `adl mcp cli
     // workitem-create-or-update` dispatches to the same tool the MCP server
     // calls — graded identically, not only the tool-call payload shape.
     const call = toolCallFor(inv)
     if (call === null) return null
     if (mcpToolName(call.tool) !== 'workitem_create_or_update') return null
 
-    // R5 (STATUS.md 12p, re-review 2026-09-28 night):
-    // grade the EFFECTIVE identity for THIS specific piece — a valid inline
+    // Grade the EFFECTIVE identity for THIS specific piece — a valid inline
     // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation
-    // still wins, exactly like M3 already does for `git push`
+    // still wins, exactly like it does for `git push`
     // (effectiveIdentityForMcpCli's own doc has the full "why"). A real MCP
     // tool-call payload carries no command text at all (no inline override
     // possible), so this still resolves to the plain session identity for
@@ -54,7 +53,7 @@ export const adlWorkitemRequiresTarunOrVivek: RuleSpec = {
     const resolution = resolveFromEnvOrFile(ctx.env)
     const fallback = resolution.ok ? resolution.agent : null
     const agent = effectiveIdentityForMcpCli(inv, ctx.command ?? '', fallback)
-    if (agent === null) return null // no identity at all: adl.session-required-for-writes's job
+    if (agent === null) return null // no identity at all: adl.run-required-for-writes's job
     if (agent !== AGENT_REVIEWER) return null
 
     return { ruleId: RULE_ID, severity: 'deny', detail: { tool: call.tool } }