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

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

@@ -0,0 +1,128 @@
+/**
+ * `ADL_AGENT_ID_AGENT`, read the same way by every rule that keys behaviour
+ * off the session's agent identity (docs/operations/agent-permissions.md, docs/architecture/cli-design.md
+ * decision 2).
+ *
+ * The one-agent-identity standard (STATUS.md 12p)
+ * makes `packages/azdo/src/lib/agent-identity.ts` the ONE Azure DevOps
+ * identity resolver in this repo; this file no longer keeps its own copy of
+ * `VALID_AGENTS`/`NO_AGENT_IDENTITY_MESSAGE`/the default-agent-file read — it
+ * imports them, and `BUILDER_AGENTS` derives from `VALID_AGENTS` rather than
+ * naming `AGENT_TARUN`/`AGENT_VIVEK` a second time.
+ */
+import {
+  isValidAgent,
+  NO_AGENT_IDENTITY_MESSAGE,
+  resolveAgentIdentity,
+  VALID_AGENTS,
+  type ValidAgent,
+} from '../../../../azdo/src/lib/agent-identity.ts'
+import type { EnvPort } from '../ports.ts'
+
+export { isValidAgent, NO_AGENT_IDENTITY_MESSAGE, VALID_AGENTS, type ValidAgent }
+
+export const ADL_AGENT_ID_ENV_VAR = 'ADL_AGENT_ID_AGENT'
+export const AGENT_REVIEWER = 'agent-reviewer'
+export const AGENT_TARUN = 'agent-tarun'
+export const AGENT_VIVEK = 'agent-vivek'
+
+/** The two-branch standard's builders (docs/specs/two-branch-standard-2026-09-27.md §1b.1): cut a feature branch from `integration`, create their own PRs into it. Every VALID_AGENTS member except agent-reviewer. */
+export const BUILDER_AGENTS: ReadonlySet<string> = new Set(VALID_AGENTS.filter((name) => name !== AGENT_REVIEWER))
+
+/**
+ * Test-only override name the shared module accepts for its default-agent
+ * file read (`packages/azdo/src/lib/agent-identity.ts`'s `OVERRIDE_ENV_VAR`)
+ * -- re-exported here so callers in this package (and their tests) do not
+ * have to know the azdo module's internal constant name. Production never
+ * sets this; every test that wants "no default-agent file configured" MUST
+ * set it to a path that does not exist -- see `resolveFromEnvOrFile`'s doc.
+ * Never the real system path (AGENTS.md: tests are hermetic).
+ */
+export const DEFAULT_AGENT_FILE_OVERRIDE_ENV = 'ADL_DEFAULT_AGENT_FILE'
+
+// L3 (STATUS.md 12p): `currentAgent` — the
+// session-env-only read this file used to export for
+// `../../hooks/lean-ctx/scope-rewrite.ts`'s `sessionIdentityOf` — was
+// removed here (not merely superseded) once that caller switched to
+// `resolveFromEnvOrFile` (steps 2-3 of the standard: env, THEN the machine
+// default-agent file). It had no other caller left, so it stayed as dead,
+// uncovered code rather than a function this file's own contract still
+// needs — bunfig.toml's coverage policy has no ignore-list for exactly this
+// reason: a function nothing calls gets deleted, not exempted.
+
+export type IdentitySource = 'env' | 'default-file'
+
+export interface ResolvedIdentity {
+  readonly ok: true
+  readonly agent: string
+  readonly source: IdentitySource
+}
+
+/**
+ * `resolveAgentIdentity` failed: either nothing at all was configured
+ * (`reason: 'none'` — step 4 of the standard, `NO_AGENT_IDENTITY_MESSAGE`),
+ * or something WAS configured (the env var or the default-agent file) but
+ * named an agent outside `VALID_AGENTS`, or the default-agent file could not
+ * be read for a reason other than "it does not exist" (`reason: 'invalid'`).
+ * The distinction matters for the message a caller shows: "no agent
+ * identity, here is how to set one" is a different problem from "an agent
+ * identity IS configured and it is wrong."
+ */
+export interface UnresolvedIdentity {
+  readonly ok: false
+  readonly reason: 'none' | 'invalid'
+  readonly message: string
+}
+
+export type IdentityResolution = ResolvedIdentity | UnresolvedIdentity
+
+/**
+ * Steps 2-3 of the standard (STATUS.md 12p, "The
+ * standard"): `ADL_AGENT_ID_AGENT` from the session environment, else the
+ * machine default-agent file, else unresolved. Step 1 (an inline
+ * `ADL_AGENT_ID_AGENT=<agent>` prefix on the command itself) is NOT this
+ * function's job — that is a property of the command text, resolved by
+ * `../shell/git-identity.ts`'s scanner, which calls this function only for
+ * the FALLBACK once it has already looked for an inline override.
+ *
+ * Delegates to `packages/azdo/src/lib/agent-identity.ts`'s
+ * `resolveAgentIdentity` — the one resolver every Azure DevOps surface in
+ * this repo shares — passing it a minimal, hand-built `NodeJS.ProcessEnv`
+ * carrying only the two variables that function reads
+ * (`ADL_AGENT_ID_AGENT`, and the test-only `ADL_DEFAULT_AGENT_FILE`
+ * override), rather than `process.env`: this hook's own `EnvPort` is already
+ * the caller-supplied source of truth for "the environment this invocation
+ * ran in" (see `../../pre-tool-use/handler.ts`'s `invocationEnv` — a host
+ * that scrubs its hook child's environment must not inherit the wrapper
+ * process's own identity), and reusing that same discipline here keeps this
+ * function callable from a hand-built `EnvPort` in a unit test without
+ * ever touching this process's real environment.
+ *
+ * PRODUCTION NOTE — hermeticity: when neither variable is set, the shared
+ * module reads the REAL machine default-agent file
+ * (`/Library/Application Support/adl/default-agent` on darwin,
+ * `/etc/adl/default-agent` on linux) — that real read is the whole point in
+ * production (step 3 of the standard). Every test that wants "no identity
+ * resolves" MUST therefore set `ADL_DEFAULT_AGENT_FILE` (via the `EnvPort`
+ * passed in) to a path that provably does not exist; `tests/fixtures/ports.ts`'s
+ * `envWith` does this by default so ordinary rule tests stay hermetic
+ * without every call site repeating it.
+ *
+ * `platform` defaults to `process.platform` (production behaviour) but can
+ * be overridden explicitly — this is a test seam only, so a unit test can
+ * exercise the shared module's per-OS default-agent-file path (darwin vs
+ * linux) without monkey-patching the real `process.platform`.
+ */
+export function resolveFromEnvOrFile(env: Pick<EnvPort, 'get'>, platform: NodeJS.Platform = process.platform): IdentityResolution {
+  const fakeEnv = {
+    ADL_AGENT_ID_AGENT: env.get(ADL_AGENT_ID_ENV_VAR),
+    [DEFAULT_AGENT_FILE_OVERRIDE_ENV]: env.get(DEFAULT_AGENT_FILE_OVERRIDE_ENV),
+  } as NodeJS.ProcessEnv
+  try {
+    const resolved = resolveAgentIdentity(fakeEnv, platform)
+    return { ok: true, agent: resolved.agent, source: resolved.source }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    return { ok: false, reason: message === NO_AGENT_IDENTITY_MESSAGE ? 'none' : 'invalid', message }
+  }
+}

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

@@ -0,0 +1,179 @@
+/**
+ * `adl mcp cli <command> [options]` → the equivalent MCP tool call, for the
+ * role rules that must grade it EXACTLY like the real MCP tool call (M4,
+ * STATUS.md 12p): `docs/operations/agent-permissions.md`
+ * gates the tool, not the surface it was invoked through, and `adl mcp cli`
+ * (`packages/azdo/src/cli.ts`'s `runCli`) dispatches to the SAME
+ * `dispatchTool` the MCP server itself calls — a caller who runs
+ * `adl mcp cli pr-review --vote reject ...` reaches Azure DevOps exactly the
+ * way `mcp__azdo__pr_review` does, and must be denied the same way.
+ *
+ * Scoped to the four commands this package's role rules actually gate —
+ * `workitem-create-or-update`, `pr-create-or-update`, `pr-review`,
+ * `build-run` — not a general reimplementation of the whole CLI surface
+ * (`packages/azdo/src/cli.ts`'s `commands` table), which belongs to
+ * `packages/azdo`, outside this package's write scope. The flag → input-key
+ * mapping below is copied from that table (re-checked 2026-09-28) for
+ * exactly these four entries; if `cli.ts`'s flags for one of them change,
+ * this table needs a matching update — there is no cross-package import that
+ * would keep the two in sync automatically without also pulling in
+ * `tool-dispatch.ts` and everything it depends on.
+ *
+ * The synthesized `tool` name is `mcp__adl-cli__<tool>` — not the bare tool
+ * name — so `./mcp-tool.ts`'s `mcpToolName` (which requires a
+ * `mcp__<prefix>__<tool>` shape, or a known-suffix fallback that itself
+ * requires a prefix before the separator) extracts it the same way it would
+ * a real host's MCP tool-call name. `adl-cli` is not a real MCP server; it
+ * only needs to be A prefix, so `mcpToolName`'s last-`__` split lands on the
+ * real tool name.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import { dynamicToken, tokenValue } from '../shell/token.ts'
+import { ADL_BINARY_NAMES } from './git-helpers.ts'
+import { effectiveIdentityForCommand, scanAdlMcpCliPieces } from '../shell/git-identity.ts'
+
+export interface AdlMcpCliCall {
+  readonly tool: string
+  readonly input: Readonly<Record<string, unknown>>
+}
+
+type FlagType = 'string' | 'integer' | 'boolean'
+
+interface FlagSpec {
+  readonly flag: string
+  readonly key: string
+  readonly type: FlagType
+}
+
+interface GatedCommand {
+  readonly tool: string
+  readonly flags: readonly FlagSpec[]
+}
+
+/**
+ * Only the flags a role rule actually inspects: `pr-create-or-update`'s
+ * `--action`/`--auto-complete`/`--no-auto-complete`/`--merge-strategy`/
+ * `--delete-source-branch` (`isPrCompletionCall`, pr-completion.ts) and
+ * `pr-review`'s `--comment`/`--vote`/`--target-branch`
+ * (`adl-pr-review-role.ts`). `workitem-create-or-update` and `build-run` are
+ * graded on identity alone — no input field changes their outcome — so
+ * their flag lists are empty; the command still needs an entry here so it is
+ * RECOGNIZED at all.
+ */
+const GATED_COMMANDS: Readonly<Record<string, GatedCommand>> = {
+  'workitem-create-or-update': { tool: 'workitem_create_or_update', flags: [] },
+  'pr-create-or-update': {
+    tool: 'pr_create_or_update',
+    flags: [
+      { flag: '--action', key: 'action', type: 'string' },
+      { flag: '--auto-complete', key: 'autoComplete', type: 'boolean' },
+      { flag: '--no-auto-complete', key: 'autoComplete', type: 'boolean' },
+      { flag: '--merge-strategy', key: 'mergeStrategy', type: 'string' },
+      { flag: '--delete-source-branch', key: 'deleteSourceBranch', type: 'boolean' },
+    ],
+  },
+  'pr-review': {
+    tool: 'pr_review',
+    flags: [
+      { flag: '--comment', key: 'comment', type: 'string' },
+      { flag: '--vote', key: 'vote', type: 'string' },
+      { flag: '--target-branch', key: 'targetBranch', type: 'string' },
+    ],
+  },
+  'build-run': { tool: 'build_run', flags: [] },
+}
+
+/**
+ * `adl`/`adl.exe mcp cli <command> [--flag value|--boolean-flag ...]` → the
+ * MCP tool call it is equivalent to, or `null` when `inv` is not this shape,
+ * any of the first three words is dynamic, or `<command>` is not one of the
+ * four gated commands. A `--flag`'s value is read only when the flag is
+ * known for that specific command (an unrecognized flag is ignored, not an
+ * error — this is a read for GRADING, not the CLI's own arg parser, which
+ * would reject an unknown flag itself before any tool call happens) and the
+ * NEXT word is neither dynamic nor itself another `--flag` (a boolean flag
+ * taking no value, or a malformed line with a missing value, is left unset
+ * rather than guessed).
+ */
+export function adlMcpCliCall(inv: Invocation): AdlMcpCliCall | null {
+  if (inv.kind !== 'command' || !ADL_BINARY_NAMES.has(inv.name)) return null
+  const args = inv.args
+  if (args.length < 3) return null
+  if (args.slice(0, 3).some((token) => dynamicToken(token))) return null
+  if (tokenValue(args[0]!).toLowerCase() !== 'mcp' || tokenValue(args[1]!).toLowerCase() !== 'cli') return null
+
+  const commandName = tokenValue(args[2]!).toLowerCase()
+  const spec = GATED_COMMANDS[commandName]
+  if (spec === undefined) return null
+
+  const rest = args.slice(3)
+  const values = rest.map((token) => (dynamicToken(token) ? null : tokenValue(token)))
+
+  const input: Record<string, unknown> = {}
+  for (let index = 0; index < values.length; index += 1) {
+    const value = values[index]
+    if (value === null || value === undefined) continue
+    const flagSpec = spec.flags.find((candidate) => candidate.flag === value)
+    if (flagSpec === undefined) continue
+    if (flagSpec.type === 'boolean') {
+      // `--auto-complete` sets autoComplete: true; `--no-auto-complete` sets
+      // it to false (both are the SAME input key, mirroring cli.ts's own
+      // two-flags-one-key shape) — deleteSourceBranch has no "--no-" form,
+      // so this is always true for it.
+      input[flagSpec.key] = flagSpec.flag.startsWith('--no-') ? false : true
+      continue
+    }
+    const next = values[index + 1]
+    if (next === null || next === undefined || next.startsWith('--')) continue
+    input[flagSpec.key] = flagSpec.type === 'integer' ? Number(next) : next
+    index += 1
+  }
+  return { tool: `mcp__adl-cli__${spec.tool}`, input }
+}
+
+/**
+ * The `{tool, input}` pair for `inv`, whether it is a real MCP tool-call
+ * payload or an equivalent `adl mcp cli <command>` shell invocation (M4) —
+ * or `null` when `inv` is neither. Every role rule that used to check only
+ * `inv.kind === 'tool-call'` calls this instead, so a caller cannot route
+ * around role grading just by using the CLI form of the same tool.
+ */
+export function toolCallFor(inv: Invocation): AdlMcpCliCall | null {
+  if (inv.kind === 'tool-call') return { tool: inv.tool, input: inv.input }
+  return adlMcpCliCall(inv)
+}
+
+/**
+ * R5 (STATUS.md 12p, re-review 2026-09-28 night): the
+ * EFFECTIVE identity for THIS specific `adl mcp cli <command>` invocation —
+ * the same M2/M3 correlation `impl/adl-git-push-policy.ts`'s
+ * `effectiveIdentityForPush` already gives `git push`, extended to this
+ * command class. Before this fix, `adl-workitem-role.ts`/`adl-pr-role.ts`/
+ * `adl-pr-review-role.ts` graded `resolveFromEnvOrFile(ctx.env)` alone —
+ * ignoring a valid inline `ADL_AGENT_ID_AGENT=` override on the very piece
+ * being graded, so a reviewer session's own inline `agent-tarun` override on
+ * `adl mcp cli workitem-create-or-update` was denied as `agent-reviewer`
+ * regardless (a false deny), and — the more dangerous direction R5 actually
+ * names — a `agent-tarun` SESSION with an inline `ADL_AGENT_ID_AGENT=agent-
+ * reviewer` override was graded as `agent-tarun` (a false ALLOW: the piece
+ * that will actually run is `agent-reviewer`'s).
+ *
+ * A `tool-call`-kind `inv` (a real MCP tool call, not the CLI shell form)
+ * carries no command text at all — no inline override is possible for it —
+ * so `fallback` (the session's own resolved identity) is the correct,
+ * unchanged answer.
+ */
+export function effectiveIdentityForMcpCli(inv: Invocation, command: string, fallback: string | null): string | null {
+  if (inv.kind !== 'command') return fallback
+  const gatedCommandWord = inv.args[2]
+  if (gatedCommandWord === undefined) return fallback
+  const gatedCommand = tokenValue(gatedCommandWord).toLowerCase()
+  const restValues = inv.args.slice(3).map((token) => tokenValue(token))
+  const pieces = scanAdlMcpCliPieces(command, fallback)
+  const match = pieces.find(
+    (piece) => piece.command === gatedCommand && piece.rest.length === restValues.length && piece.rest.every((value, index) => value === restValues[index]),
+  )
+  if (match !== undefined) return match.effectiveAgent
+  return effectiveIdentityForCommand(command, fallback)
+}

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

@@ -0,0 +1,65 @@
+/**
+ * `adl.pr-complete-pending-decision` — docs/operations/agent-permissions.md row 9
+ * ("PR complete / set auto-complete"), marked **OPEN** in the matrix: denied
+ * for BOTH `agent-tarun`/`agent-vivek` AND `agent-reviewer` "until Tarun
+ * decides", as its own separately named rule specifically so it can be
+ * relaxed (or given a real role split) without touching
+ * `adl.pr-create-update-role` (row 5), which keeps allowing a plain PR
+ * create/update for builders and `agent-reviewer` throughout
+ * (docs/specs/two-branch-standard-2026-09-27.md §1b.5: auto-complete is armed
+ * by the azdo core at creation, not set explicitly by an agent).
+ *
+ * "Setting auto-complete" is `isPrCompletionCall()` (pr-completion.ts) —
+ * see that file for why this is scoped to an `update` call that explicitly
+ * touches `autoComplete`/`mergeStrategy`/`deleteSourceBranch`, not to every
+ * `create` (which arms auto-complete by default already, per a 2026-09-15
+ * owner decision unrelated to this row, and denying that would block PR
+ * creation entirely).
+ *
+ * Deliberately does NOT require an identity to be present: row 9 is OPEN
+ * regardless of who is asking, including a caller with no session identity at
+ * all (whichever rule reports first, the outcome is the same: denied).
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { isPrCompletionCall } from './pr-completion.ts'
+import { mcpToolName } from './mcp-tool.ts'
+import { toolCallFor } from './adl-mcp-cli.ts'
+
+const RULE_ID = 'adl.pr-complete-pending-decision'
+
+export const adlPrCompletePendingDecision: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary:
+    'Deny PR completion / auto-complete for every identity — open decision (docs/operations/agent-permissions.md row 9) — the MCP tool AND its adl mcp cli equivalent (M4).',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    // M4 (STATUS.md 12p): `adl mcp cli
+    // pr-create-or-update` is the SAME tool `adl.pr-create-update-role`
+    // steps aside for on this shape — without this, the CLI form of a
+    // completion call would sail through both rules.
+    const call = toolCallFor(inv)
+    if (call === null) return null
+    if (mcpToolName(call.tool) !== 'pr_create_or_update') return null
+    if (!isPrCompletionCall(call.input)) return null
+    return { ruleId: RULE_ID, severity: 'deny', detail: { tool: call.tool } }
+  },
+  message(_finding: Finding, ctx: MessageContext) {
+    const user = 'PR completion / auto-complete is not enabled for agents yet — pending a decision from Tarun'
+    return {
+      user,
+      agent:
+        `DENIED ${user} (docs/operations/agent-permissions.md row 9, marked OPEN). Create or update the PR's title/description ` +
+        `normally; do not pass autoComplete, mergeStrategy, or deleteSourceBranch. Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [],
+    allow: ['ls -la', 'git status'],
+  },
+}

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

@@ -0,0 +1,156 @@
+/**
+ * `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,
+ * `pr_review({ pullRequestId, comment?, vote?, targetBranch?, repository? })`
+ * — see `packages/azdo/src/azdo-pr-review.ts`.
+ *
+ * Two independent gates, because a single `pr_review` call may carry a
+ * comment, a vote, or both:
+ *
+ *  Row 6 (comment) — same allow-set as row 5's `adl.pr-create-update-role`:
+ *  a builder (`agent-tarun`/`agent-vivek`) OR `agent-reviewer`. Nobody else.
+ *  No branch restriction — comments are not a gate.
+ *
+ *  Rows 7/8 (vote) — narrower: `agent-reviewer` ONLY, and only when the
+ *  call's OWN `targetBranch` argument says `main`. This hook has no network
+ *  access and cannot ask Azure DevOps what the pull request's real target
+ *  is, so `targetBranch` is a REQUIRED, caller-declared argument on the tool
+ *  itself precisely so this rule can gate on it synchronously — the
+ *  implementation-status note for rows 7/8 in docs/operations/agent-permissions.md is
+ *  explicit that the vote tool "must fail closed for a vote whose input does
+ *  not reveal the target branch, or whose target is `integration`", which is
+ *  exactly the two `return`s below before the role check even runs. The
+ *  `azdo` core (`azdo-pr-review.ts`) does NOT trust this argument either —
+ *  it re-derives the pull request's REAL target from Azure DevOps and
+ *  refuses on a mismatch, the same "never trust the caller, ask Azure"
+ *  discipline `azdo-pr.ts`'s `assertBranchReadyForPr` already uses. This
+ *  rule and that core check are deliberately redundant: this one is the
+ *  fast, offline pre-flight; that one is the authoritative, online guard a
+ *  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`
+ * 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.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { AGENT_REVIEWER, BUILDER_AGENTS, resolveFromEnvOrFile } from './adl-identity.ts'
+import { detailString } from './messages.ts'
+import { mcpToolName } from './mcp-tool.ts'
+import { effectiveIdentityForMcpCli, toolCallFor } from './adl-mcp-cli.ts'
+
+const RULE_ID = 'adl.pr-review-role'
+
+type Reason = 'comment-role' | 'vote-no-target' | 'vote-integration' | 'vote-wrong-branch' | 'vote-role'
+
+function isAllowedToComment(agent: string): boolean {
+  return BUILDER_AGENTS.has(agent) || agent === AGENT_REVIEWER
+}
+
+interface PrReviewInput {
+  readonly comment?: unknown
+  readonly vote?: unknown
+  readonly targetBranch?: unknown
+}
+
+function finding(tool: string, agent: string, reason: Reason): Finding {
+  return { ruleId: RULE_ID, severity: 'deny', detail: { tool, agent, reason } }
+}
+
+export const adlPrReviewRole: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary:
+    '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.
+    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
+    // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation
+    // still wins, exactly like M3 already 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,
+    // else the machine default-agent file (adl-identity.ts's
+    // resolveFromEnvOrFile).
+    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
+
+    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
+    // 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
+    // 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
+    // block for why the MESSAGE half is tested against a hand-built Finding
+    // rather than through this line.
+    if (input.comment !== undefined && !isAllowedToComment(agent)) return finding(call.tool, agent, 'comment-role')
+
+    if (input.vote === undefined) return null
+
+    // Rows 7/8: vote. Fail closed before anything else — an input that does
+    // not name a real target branch is refused the same as one that names
+    // `integration`, never defaulted or inferred.
+    const targetBranch = typeof input.targetBranch === 'string' ? input.targetBranch.trim() : ''
+    if (targetBranch === '') return finding(call.tool, agent, 'vote-no-target')
+    if (targetBranch === 'integration') return finding(call.tool, agent, 'vote-integration')
+    if (targetBranch !== 'main') return finding(call.tool, agent, 'vote-wrong-branch')
+    if (agent !== AGENT_REVIEWER) return finding(call.tool, agent, 'vote-role')
+
+    return null
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const tool = detailString(finding, 'tool')
+    const agent = detailString(finding, 'agent')
+    const reason = detailString(finding, 'reason') as Reason
+    const user = ((): string => {
+      switch (reason) {
+        case 'comment-role':
+          return 'this operation can only be done with agent-tarun, agent-vivek, or agent-reviewer'
+        case 'vote-no-target':
+          return "pr_review vote requires targetBranch (the pull request's real target branch); refused rather than guessing which pull request this vote is for"
+        case 'vote-integration':
+          return 'no vote gate on integration — CI + auto-complete only, no human or agent review there'
+        case 'vote-wrong-branch':
+          return "votes are only defined for pull requests targeting 'main' or 'integration'"
+        case 'vote-role':
+          return "human approval gate — an agent vote does not substitute for Tarun's or Vivek's own review"
+      }
+    })()
+    return {
+      user,
+      agent: `DENIED ${tool} for '${agent}' (${reason}): ${user}. Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    // Tool-call rule; the shared shell corpus only proves this rule never
+    // fires on an unrelated shell command. Real coverage is
+    // tests/unit/rules-adl-pr-review-role.test.ts.
+    deny: [],
+    allow: ['ls -la', 'git status'],
+  },
+}

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

@@ -0,0 +1,121 @@
+/**
+ * `adl.pr-create-update-role` — docs/operations/agent-permissions.md row 5 (PR
+ * create/update), updated for the two-branch standard
+ * (docs/specs/two-branch-standard-2026-09-27.md §1b.1): builders
+ * (`agent-tarun`/`agent-vivek`) cut a feature branch from `integration` and
+ * **create their own PRs into it** — `packages/azdo/src/mcp-server.ts`
+ * registers exactly one PR write tool, `pr_create_or_update`
+ * (`action: 'create' | 'update'`), and it always targets `integration` (there
+ * is no target-branch choice for a caller to make). `agent-reviewer` stays
+ * ALLOWED too — its `main` vote is optional for now (§1b.1: "agent-reviewer
+ * is optional for now"), and nothing stops it opening/updating a PR either.
+ * Nobody else may.
+ *
+ * This is the mirror image of `adl-workitem-role.ts`'s row 10 (there:
+ * everyone but `agent-reviewer`; here: builders AND `agent-reviewer`), not a
+ * simple negation of either — hence the explicit allow-set below rather than
+ * a single `!== AGENT_REVIEWER` check.
+ *
+ * Azure DevOps' own repo-wide "Contribute to pull requests" Deny on
+ * `agent-tarun`/`agent-vivek` (docs/specs/two-branch-standard-2026-09-27.md
+ * §3.1 P1) is a SEPARATE, ADO-side change this rule does not make — until P1
+ * lands, a builder's create/update call can still 403 at Azure DevOps even
+ * though this hook now allows it through. The row's REWRITE half (`az repos
+ * pr create/update` → `adl pr create/update`) is explicitly a LATER stream
+ * (docs/operations/agent-permissions.md "Build order"); `tool.azure-devops` keeps
+ * denying the raw `az` form unchanged, and this rule does not touch it.
+ *
+ * Row 9 (PR complete / set auto-complete) is a SEPARATE, more specific rule
+ * (adl-pr-complete-pending.ts) so it can be relaxed independently once Tarun
+ * decides — see that file. It denies EVERY identity, builder or reviewer
+ * alike (auto-complete is armed by the azdo core at PR creation, never set
+ * explicitly by an agent — docs/specs/two-branch-standard-2026-09-27.md
+ * §1b.5's brief), so this rule steps aside for the completion shape
+ * regardless of who is asking, and the two rules never fight over the same
+ * call.
+ *
+ * Rows 6 and 7 (PR comment; PR vote) are the same allow-set shape, but
+ * `packages/azdo` has no comment/vote tool today — grepped 2026-09-27,
+ * nothing named `pr_review`/`pr_comment`/`pr_vote` exists. PENDING: add a
+ * sibling check here (or a new rule) when Stream B ships one, rather than
+ * 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`
+ * 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.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { AGENT_REVIEWER, BUILDER_AGENTS, resolveFromEnvOrFile } from './adl-identity.ts'
+import { detailString } from './messages.ts'
+import { mcpToolName } from './mcp-tool.ts'
+import { isPrCompletionCall } from './pr-completion.ts'
+import { effectiveIdentityForMcpCli, toolCallFor } from './adl-mcp-cli.ts'
+
+const RULE_ID = 'adl.pr-create-update-role'
+
+function isAllowedToCreateOrUpdatePrs(agent: string): boolean {
+  return BUILDER_AGENTS.has(agent) || agent === AGENT_REVIEWER
+}
+
+export const adlPrCreateUpdateRole: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary:
+    '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.
+    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
+    // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation
+    // still wins, exactly like M3 already 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,
+    // else the machine default-agent file (adl-identity.ts's
+    // resolveFromEnvOrFile).
+    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
+
+    // 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
+    // ALSO happens to be completion-shaped.
+    if (!isAllowedToCreateOrUpdatePrs(agent)) return { ruleId: RULE_ID, severity: 'deny', detail: { tool: call.tool } }
+
+    // A builder or agent-reviewer would otherwise be allowed by this rule —
+    // EXCEPT row 9 (PR completion / auto-complete) overrides that for
+    // everyone; let adl.pr-complete-pending-decision report instead, so it
+    // stays the one place that decision can be relaxed later.
+    if (isPrCompletionCall(call.input)) return null
+
+    return null
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const tool = detailString(finding, 'tool')
+    const user = 'this operation can only be done with agent-tarun, agent-vivek, or agent-reviewer'
+    return {
+      user,
+      agent: `DENIED ${tool}: ${user}. Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    // Tool-call rule; the shared shell corpus only proves this rule never
+    // fires on an unrelated shell command (tests/unit/rules-tool-search.test.ts's
+    // pattern). Real coverage is tests/unit/rules-adl-pr-role.test.ts.
+    deny: [],
+    allow: ['ls -la', 'git status'],
+  },
+}