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

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

@@ -0,0 +1,549 @@
+/**
+ * The pre-tool-use guard: `adl hook pre-tool-use --host=X`.
+ *
+ * Ported from enact-repo-controls's `runPreToolUse` (`src/main.ts`) and its
+ * `toDecideInput`/`renderFor` helpers. `main.ts` has already confirmed
+ * `<inv.root>/adl-config.toml` exists and decoded it once (to check
+ * `[hooks] enabled`) before ever calling this handler — see `main.ts`'s
+ * `runHook`. This handler re-reads and re-decodes that same file rather than
+ * having `main.ts` thread the already-decoded `AdlRepoConfig` through
+ * `HookInvocation` (whose shape is fixed by `../hooks/contract.ts` and is
+ * deliberately the same for every hook kind, none of which need a config
+ * object in their invocation). A decode failure here, on a file `main.ts`
+ * just decoded successfully, would mean the file changed on disk between the
+ * two reads or `decodeConfig` is non-deterministic — either way a real bug,
+ * not a condition to fail closed over quietly, so it is thrown rather than
+ * swallowed into a `HookResult`.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ActivityNote, HookInvocation, HookResult } from '../hooks/contract.ts'
+import { decodeConfig } from '../gating/config.ts'
+import { MARKER } from '../gating/root.ts'
+import {
+  buildEngineContext,
+  buildSnippet,
+  decide,
+  FAIL_CLOSED_EXIT_CODE,
+  type Decision as EngineDecision,
+  type EngineContext,
+} from '../rules/engine.ts'
+import type { DecideInput } from '../rules/engine.ts'
+import type { RuleId, RuleMessage } from '../rules/spec.ts'
+import { gitIdentityNeedsIdentityMessage, hostCannotRewriteMessage, RULE_ID as GIT_IDENTITY_RULE_ID } from '../rules/impl/adl-git-identity.ts'
+import { RULE_ID as GIT_CREDENTIAL_BYPASS_RULE_ID, SECURITY_RULE_ID as SECURITY_KEYCHAIN_ADO_RULE_ID } from '../rules/impl/adl-git-credential-bypass.ts'
+import { RULE_ID as HUMAN_AZDO_BYPASS_RULE_ID } from '../rules/impl/adl-human-azdo-bypass.ts'
+import { resolveFromEnvOrFile } from '../rules/impl/adl-identity.ts'
+import { identityBearingReason } from '../rules/impl/adl-session-required.ts'
+import { commandHasValidInlineIdentity, effectiveIdentityForCommand } from '../rules/shell/git-identity.ts'
+import { invocations } from '../rules/shell/invocation.ts'
+import { KNOWN_MCP_TOOL_NAMES, mcpToolName, toolNameEndingWithKnownSuffix } from '../rules/impl/mcp-tool.ts'
+import { BUILTIN_RULES, requireRegistered } from '../rules/registry.ts'
+import { liveAgent, liveEnv, liveRepoIndex } from '../rules/ports.ts'
+import { specFor } from '../hosts/registry.ts'
+import type { Decision as HostDecision, HostId, HostSpec } from '../hosts/spec.ts'
+
+/**
+ * The static rule corpus, registered once at module load. A registration
+ * failure (an empty corpus or a duplicate id) can only come from a bug in
+ * `../rules/registry.ts`'s own `BUILTIN_RULES` array, never from anything a
+ * repository's config supplies — so it throws at import time rather than
+ * being checked on every invocation.
+ */
+const RULES = requireRegistered(BUILTIN_RULES)
+
+/**
+ * Read the command (or tool-call) out of a host's PreToolUse payload.
+ *
+ * The hosts spell a shell command differently — `command`, `cmd`, `script`,
+ * either nested under `tool_input` or at the payload's top level — which is
+ * why this tolerates all three keys in both places rather than assuming one.
+ * Anything else with a string `tool_name` is treated as a non-shell tool
+ * call (Read, Write, Edit, an MCP tool, ...); everything else is not a
+ * decidable payload at all.
+ *
+ * Cursor alone needs BOTH shapes this function tries, verified against
+ * https://cursor.com/docs/agent/hooks (this session, 2026-09-14):
+ *  - `preToolUse` (`tool_name: "Shell"`) nests the command under
+ *    `tool_input`: `{"tool_name": "Shell", "tool_input": {"command": "npm
+ *    install", "working_directory": "/project"}, "tool_use_id": "abc123",
+ *    "cwd": "/project", ...}` — read via the `toolInput[key]` branch below.
+ *  - `beforeShellExecution` carries the command at the payload's top level
+ *    instead, with no `tool_name`/`tool_input` at all: `{"command": "<full
+ *    terminal command>", "cwd": "<current working directory>", "sandbox":
+ *    false}` — read via the `payload[key]` fallback below.
+ * `adl hook pre-tool-use --host=cursor` and `adl hook crg pre-commit
+ * --host=cursor` (`../hooks/crg/index.ts`'s `isGitCommitInvocation`, which
+ * calls this same function) are wired to `beforeShellExecution` in
+ * production, but both shapes are exercised end to end — see
+ * `test/binary/hook-e2e-matrix.test.ts`'s cursor `preToolUse` payload tests.
+ */
+export function toDecideInput(payload: Record<string, unknown>): DecideInput | null {
+  const toolInput = (payload.tool_input ?? {}) as Record<string, unknown>
+
+  // F4 (independent review, 2026-09-29): codex's `apply_patch` names its
+  // patch body `tool_input.command` — the same key name a real shell tool
+  // call uses. Checked BEFORE the generic loop below, which would otherwise
+  // read that patch TEXT as if it were a shell command and walk it through
+  // the shell classifier (garbage in, and — worse — a write to a protected
+  // carrier inside the patch body never reaches agent.tamper-protection's
+  // tool-call branch at all, since nothing ever builds a `tool-call` for it).
+  if (payload.tool_name === 'apply_patch') return { kind: 'tool-call', tool: 'apply_patch', input: toolInput }
+
+  for (const key of ['command', 'cmd', 'script'] as const) {
+    const value = toolInput[key] ?? payload[key]
+    if (typeof value === 'string') return { kind: 'command', command: value }
+  }
+
+  const tool = payload.tool_name
+  if (typeof tool === 'string') return { kind: 'tool-call', tool, input: toolInput }
+  return null
+}
+
+/**
+ * Envelope a decision for one host, by delegating to that host's own
+ * `HostSpec.renderDecision`.
+ *
+ * The two `Decision` shapes differ — the engine's `Decision` is
+ * `{blocked, ruleId, userMessage, agentMessage}` / `{blocked: false, advice?}`,
+ * while `hosts/spec.ts`'s `Decision` (what `renderDecision` takes) is
+ * `{verdict, reason, agentMessage?}` — so a blocked engine decision is adapted
+ * to `{verdict: 'deny', reason: userMessage, agentMessage}` before being
+ * handed to the host spec. A non-blocked decision (advice included: advice is
+ * never rendered into hook output) short-circuits to `{}` before the adapter
+ * or any host spec is ever consulted — every host reads that as "no opinion".
+ */
+export function renderFor(host: HostId, decision: EngineDecision): unknown {
+  if (!decision.blocked) return {}
+  const adapted: HostDecision = {
+    verdict: 'deny',
+    reason: decision.userMessage,
+    agentMessage: decision.agentMessage,
+  }
+  return specFor(host).renderDecision(adapted)
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+type CommandToolClass = 'native-shell' | 'mcp' | 'other'
+
+/** The host's own shell tool names across the five surfaces (Claude/Codex/Kimi `Bash`, Cursor `Shell`, OpenCode `bash`). */
+const NATIVE_SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(['Bash', 'bash', 'Shell', 'shell', 'sh'])
+
+/**
+ * The lean-ctx MCP tools that execute a shell command (docs/architecture/cli-design.md
+ * §1a; ../rules/shell/git-identity.ts's own header names the live incident:
+ * `mcp__lean_ctx__ctx_shell`). Shared with `../rules/impl/mcp-tool.ts`'s
+ * `toolNameEndingWithKnownSuffix` for the unprefixed-name fallback below.
+ */
+const KNOWN_MCP_SHELL_TOOL_NAMES: ReadonlySet<string> = new Set(['ctx_shell', 'ctx_execute'])
+
+/**
+ * Which kind of tool carries the command — this decides what the
+ * adl.git-identity rewrite stage may do with it:
+ *
+ *  - `native-shell`: the host's own shell tool, or a top-level command
+ *    payload (Cursor's `beforeShellExecution` shape, which has no
+ *    `tool_name` at all). Its child process inherits the session
+ *    environment, which already carries `ADL_AGENT_ID_AGENT` — the
+ *    mechanism docs/architecture/cli-design.md §1a documents as "just works".
+ *    Rewriting is still applied where the host supports it (defense in
+ *    depth, idempotent); where it does not, the unchanged command is safe.
+ *  - `mcp`: an MCP server tool. Its process environment does NOT reliably
+ *    carry the identity — that is the live incident (Codex gives
+ *    `ADL_AGENT_ID_AGENT` only to its own shell tool, so a push inside
+ *    `mcp__lean_ctx__ctx_shell` reached git-ado's human pass-through). The
+ *    command MUST be rewritten; a host whose hook contract cannot rewrite is
+ *    asked to deny instead — see the rewrite branch in handlePreToolUse.
+ *  - `other`: a tool with a command-shaped input field that executes nothing
+ *    (codex `apply_patch`'s patch body). Rewriting would corrupt the
+ *    payload; left exactly as sent.
+ */
+function classifyCommandTool(payload: Record<string, unknown>): CommandToolClass {
+  const tool = payload.tool_name
+  if (typeof tool !== 'string' || tool.length === 0) return 'native-shell'
+  if (tool.startsWith('mcp__') || tool.startsWith('MCP:')) return 'mcp'
+  if (NATIVE_SHELL_TOOL_NAMES.has(tool)) return 'native-shell'
+  // ASSUMPTION (unverified, W2 build item 4 — STATUS.md 12p):
+  // OpenCode's and Kimi's own MCP tool-call naming has never actually been
+  // observed in production (.adl/logs/hooks.log shows only mcp__-prefixed
+  // calls, from Claude/Codex/Cursor) — they may carry no mcp__/MCP: prefix
+  // at all, spelling the lean-ctx shell tool `<server>_ctx_shell` /
+  // `<server>.ctx_shell` / `<server>:ctx_shell` (or the ctx_execute
+  // sibling). Treated as MCP-class defensively: an unrewritten push through
+  // such a call would otherwise silently fall through to 'other' and reach
+  // git-ado's human pass-through unrewritten — the exact incident this
+  // module exists to close (see this file's own header).
+  if (toolNameEndingWithKnownSuffix(tool, KNOWN_MCP_SHELL_TOOL_NAMES) !== null) return 'mcp'
+  return 'other'
+}
+
+/**
+ * The replacement tool input for a rewritten command: the original
+ * `tool_input` object with only the command field replaced, so unchanged
+ * fields ride along (Claude's `updatedInput` "replaces the entire input
+ * object"). Mirrors `toDecideInput`'s key precedence (`command`, then `cmd`,
+ * then `script`, tool_input first). `null` when the command was read from
+ * the payload's top level — no `tool_input` object exists to replace, which
+ * only happens for the host's own shell execution (classified native-shell).
+ */
+export function replacementToolInput(payload: Record<string, unknown>, rewritten: string): Record<string, unknown> | null {
+  const toolInput = isRecord(payload.tool_input) ? payload.tool_input : null
+  for (const key of ['command', 'cmd', 'script'] as const) {
+    const value = toolInput?.[key] ?? payload[key]
+    if (typeof value !== 'string') continue
+    if (toolInput !== null && typeof toolInput[key] === 'string') return { ...toolInput, [key]: rewritten }
+    return null
+  }
+  return null
+}
+
+/**
+ * The fail-closed deny for a host whose hook contract cannot carry the
+ * rewritten tool input (no `renderRewrite`): render the host's native deny
+ * envelope, and pair it with exit code 2 on the hosts (Kimi, and OpenCode if
+ * this helper is called directly) that recognize a denial only through that
+ * signal. Exported for direct testing. Only Kimi lacks `renderRewrite`, so
+ * only Kimi reaches this from `handlePreToolUse`'s rewrite stage. OpenCode
+ * renders the same `updatedInput` envelope as Claude and Codex.
+ */
+export function denyHostCannotRewrite(spec: HostSpec, host: string, message: RuleMessage): HookResult {
+  const stdout = `${JSON.stringify(spec.renderDecision({ verdict: 'deny', reason: message.user, agentMessage: message.agent }))}\n`
+  if (host === 'kimi' || host === 'opencode') {
+    return { stdout, stderr: `adl hook: ${message.user}\n`, exitCode: FAIL_CLOSED_EXIT_CODE }
+  }
+  return { stdout, stderr: '', exitCode: 0 }
+}
+
+export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult> {
+  const configPath = join(inv.root, MARKER)
+  const text = readFileSync(configPath, 'utf8')
+  const decoded = decodeConfig(text)
+  if (!decoded.ok) {
+    throw new Error(`adl hook: invalid ${configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}`)
+  }
+  const config = decoded.value
+
+  // The invocation's own environment, not the handler process's ambient one:
+  // `main.ts` passes `process.env` here in production, and the identity rules
+  // (`adl.session-required-for-writes`, `adl.git-push-branch-policy`,
+  // `adl.git-identity`'s rewrite) must read the environment the caller handed
+  // the invocation — tests inject it explicitly, and a host that scrubs its
+  // hook child's environment must not inherit the hook wrapper's own identity.
+  const invocationEnv = { get: (name: string) => inv.env[name], home: () => liveEnv.home() }
+  const ctx = buildEngineContext(
+  config.rules,
+  config.repo,
+  RULES,
+  liveRepoIndex(inv.root),
+  invocationEnv,
+  liveAgent(inv.payload),
+  config.agent,
+  inv.root,
+)
+  if (!ctx.ok) {
+    inv.record?.({ reason: 'ERROR rules config', message: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}` })
+    return {
+      stdout: '',
+      stderr: `adl hook: ${configPath} ${ctx.issue.pointer}: ${ctx.issue.message}\n`,
+      exitCode: FAIL_CLOSED_EXIT_CODE,
+    }
+  }
+
+  return decideAndRespond(inv, ctx.value)
+}
+
+/**
+ * The identity rule ids — used below (not as a baseline any more; see
+ * Tarun's rule) purely to tell `denyIdentity`/`passIdentity` which decisions
+ * in a MANAGED repo's own normal rule pass are identity decisions worth
+ * logging `identity_source`/`identityAgent` for, as opposed to an unrelated
+ * deny (`fs.rm`, `git.no-verify`, …) that made no identity decision at all.
+ *
+ * HARDCUT (Tarun's rule, 2026-09-29): "the repos where `adl-
+ * config.toml` does not exist have no business running hooks" — this
+ * REVERSES the earlier "global identity baseline" (W2 build item 3 / R2,
+ * STATUS.md 12p), which ran exactly these rules
+ * (unconditionally enabled, with the schema's own defaults) even in an
+ * UNMANAGED repo or one with `[hooks] enabled = false`. `main.ts` no longer
+ * calls anything for either of those cases but a strict, silent no-op — see
+ * its own header and `silentNoop`. The rule ids themselves stay meaningful
+ * only for the logging purpose above, in the repos where hooks already run.
+ */
+const IDENTITY_RULE_IDS: ReadonlySet<RuleId> = new Set([
+  'adl.session-required-for-writes',
+  'adl.git-identity',
+  'adl.token-minting-role',
+  'tool.azure-devops',
+  'parse.uncertain',
+  GIT_CREDENTIAL_BYPASS_RULE_ID,
+  SECURITY_KEYCHAIN_ADO_RULE_ID,
+  HUMAN_AZDO_BYPASS_RULE_ID,
+])
+
+/**
+ * F9 (independent review, 2026-09-29): the four role-gate rules that deny a
+ * SPECIFIC Azure DevOps MCP tool call by the caller's identity
+ * (`adl.workitem-requires-tarun-or-vivek`, `adl.pr-create-update-role`,
+ * `adl.pr-review-role`, `adl.build-run-denied`). None of these are in
+ * `IDENTITY_RULE_IDS` above — that set only ever covered the FALLBACK/
+ * needs-identity/no-identity rules, never a rule that denies WITH an
+ * identity already resolved, on the strength of who that identity is. Left
+ * out of the deny-side identity logging entirely, even though every one of
+ * them can only ever fire on the exact same Azure DevOps MCP tool-call shape
+ * Decision 5's PASS-side logging already covers (`isAdoMcpToolCall`, below)
+ * — a role-gate deny is JUST AS MUCH an identity decision as the PASS it
+ * would have been without the role mismatch.
+ */
+const ROLE_GATE_RULE_IDS: ReadonlySet<RuleId> = new Set([
+  'adl.workitem-requires-tarun-or-vivek',
+  'adl.pr-create-update-role',
+  'adl.pr-review-role',
+  'adl.build-run-denied',
+])
+
+type IdentitySourceLabel = 'inline' | 'env' | 'default-file' | 'none'
+
+interface EffectiveIdentity {
+  readonly source: IdentitySourceLabel
+  /** Absent exactly when `source === 'none'` — nothing resolved, so there is no agent to report. */
+  readonly agent: string | undefined
+}
+
+/**
+ * Where the effective agent identity for THIS decision came from (W2 build
+ * item 5 — STATUS.md 12p), AND the agent it
+ * actually names (M8, STATUS.md 12p) — a valid
+ * inline `ADL_AGENT_ID_AGENT=` on the command itself (step 1 of the
+ * standard), else the session env or the machine default-agent file (steps
+ * 2-3, `resolveFromEnvOrFile`'s own `source`/`agent`), else `none`/no agent.
+ * A tool-call input carries no command text at all, so it can never be
+ * `inline` — the override for an MCP tool call is `adl run --as` (session
+ * env), matching the standard's own note on that.
+ *
+ * The AGENT half matters because it can differ from the session's own
+ * `ADL_AGENT_ID_AGENT`: `ADL_AGENT_ID_AGENT=agent-vivek git push …` run in
+ * an agent-tarun session is agent-vivek's push, not agent-tarun's — the
+ * override, not the session env, is what actually acted, and `../hooks/log.ts`
+ * reads THIS agent for the log's `agent` column instead of the session
+ * env var it used to read unconditionally (M8's second symptom: "the agent
+ * column shows the session agent" even on an overridden command).
+ */
+function effectiveIdentityFor(input: DecideInput, engineCtx: EngineContext): EffectiveIdentity {
+  const resolution = resolveFromEnvOrFile(engineCtx.env)
+  const fallback = resolution.ok ? resolution.agent : null
+  if (input.kind === 'command') {
+    const agent = effectiveIdentityForCommand(input.command, fallback)
+    if (agent !== null && commandHasValidInlineIdentity(input.command)) return { source: 'inline', agent }
+    return { source: resolution.ok ? resolution.source : 'none', agent: agent ?? undefined }
+  }
+  return { source: resolution.ok ? resolution.source : 'none', agent: resolution.ok ? resolution.agent : undefined }
+}
+
+/**
+ * R7 (STATUS.md 12p, re-review 2026-09-28 night): the
+ * resolved FALLBACK identity alone (steps 2-3 of the standard: env, else the
+ * machine default-agent file) — never the coarse, whole-command "any inline
+ * override anywhere on the line" `effectiveIdentityFor` also reports.
+ *
+ * `adl.git-identity`'s REWRITE stage (`decision.rewrite`) and its own
+ * fallback-based DENY reasons (`identity-mismatch`'s hint, `unrewritable-
+ * wrapper`, `network-alias-redefinition`, `dynamic-agent`) are ALWAYS about
+ * the FALLBACK, by construction: a piece with its OWN valid inline override
+ * is left untouched (`kind: 'unchanged'` for it) and never reaches either
+ * path — only a piece lacking one does. On a chained command
+ * (`git fetch origin && ADL_AGENT_ID_AGENT=agent-vivek git push origin
+ * main`), `effectiveIdentityFor`'s coarse `commandHasValidInlineIdentity`
+ * check would report the SECOND piece's override (`agent-vivek`) even
+ * though the piece actually rewritten (the first) received the FALLBACK —
+ * a materially wrong log label on exactly the kind of chained command this
+ * finding names. Used wherever the decision being logged came from the
+ * REWRITE stage or one of `adl.git-identity`'s own fallback-attributed deny
+ * reasons — see this function's call sites.
+ */
+function fallbackIdentity(engineCtx: EngineContext): EffectiveIdentity {
+  const resolution = resolveFromEnvOrFile(engineCtx.env)
+  return { source: resolution.ok ? resolution.source : 'none', agent: resolution.ok ? resolution.agent : undefined }
+}
+
+/** `{identitySource, identityAgent}` fields for an `ActivityNote`, or `{}` when `identity` is `undefined` — `identityAgent` itself is omitted whenever the source is `'none'` (nothing resolved). */
+function identityFields(identity: EffectiveIdentity | undefined): Pick<ActivityNote, 'identitySource' | 'identityAgent'> {
+  if (identity === undefined) return {}
+  return { identitySource: identity.source, ...(identity.agent !== undefined ? { identityAgent: identity.agent } : {}) }
+}
+
+function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookResult {
+  const input = toDecideInput(inv.payload)
+  if (input === null) {
+    inv.record?.({ reason: 'ERROR invalid hook payload', message: 'adl hook: invalid hook payload' })
+    return { stdout: '', stderr: 'adl hook: invalid hook payload\n', exitCode: FAIL_CLOSED_EXIT_CODE }
+  }
+
+  const decision = decide(input, engineCtx)
+
+  // adl.git-identity's rewrite (route, don't block — docs/architecture/cli-design.md §1a):
+  // render the host's native "replace the tool input" envelope where one
+  // exists; allow the host's own shell tool unchanged where one does not (its
+  // child environment already carries the session identity); and DENY an
+  // MCP-class call on a host with no rewrite envelope — running it unchanged
+  // would reach git as the human, which is the incident this branch closes.
+  //
+  // Every branch below decided an identity (the rewrite ALWAYS comes from
+  // adl.git-identity), so every inv.record?.() call here carries
+  // identitySource/identityAgent. R7 (STATUS.md 12p):
+  // the FALLBACK identity specifically, not `effectiveIdentityFor`'s coarse
+  // whole-command value — see `fallbackIdentity`'s own doc for why a
+  // rewrite is always about the fallback, never an inline override
+  // elsewhere on a chained command.
+  if (!decision.blocked && decision.rewrite) {
+    const identity = fallbackIdentity(engineCtx)
+    const identitySource = identity.source
+    const toolClass = classifyCommandTool(inv.payload)
+    const spec = specFor(inv.host)
+    if (toolClass === 'other') {
+      inv.record?.({ reason: `SKIP ${decision.rewrite.ruleId} non-shell tool`, ...identityFields(identity) })
+      return { stdout: '{}\n', stderr: '', exitCode: 0 }
+    }
+    const replacement = replacementToolInput(inv.payload, decision.rewrite.command)
+    const rendered = replacement === null ? undefined : spec.renderRewrite?.(replacement)
+    if (rendered !== undefined && rendered !== null) {
+      inv.record?.({ reason: `REWRITE ${decision.rewrite.ruleId}`, ...identityFields(identity) })
+      return { stdout: `${JSON.stringify(rendered)}\n`, stderr: '', exitCode: 0 }
+    }
+    // C2: `native-shell` here is only reached when the host could not
+    // render a rewrite for this payload shape (Kimi has none at all;
+    // Cursor's beforeShellExecution has no tool_input to replace) — SKIP
+    // (allow unchanged) is only safe when `ADL_AGENT_ID_AGENT` is actually
+    // present in THIS invocation's own environment (identitySource 'env'),
+    // which the spawned child process inherits. A 'default-file' identity
+    // was read by the HOOK process itself from the machine default-agent
+    // file — the child never sees it — so unchanged execution would
+    // silently reach git-ado's human pass-through; that case falls through
+    // to the same deny an MCP-class call gets below, rather than being
+    // trusted.
+    if (toolClass === 'native-shell' && identitySource === 'env') {
+      inv.record?.({ reason: `SKIP ${decision.rewrite.ruleId} native shell tool`, ...identityFields(identity) })
+      return { stdout: '{}\n', stderr: '', exitCode: 0 }
+    }
+    const originalCommand = input.kind === 'command' ? input.command : ''
+    const message = hostCannotRewriteMessage(inv.host, { command: originalCommand, snippet: buildSnippet(originalCommand) }, identity.agent)
+    inv.record?.({ reason: `DENY ${decision.rewrite.ruleId}`, message: message.agent, denyRuleId: decision.rewrite.ruleId, ...identityFields(identity) })
+    return denyHostCannotRewrite(spec, inv.host, message)
+  }
+
+  // R3 (STATUS.md 12p, re-review 2026-09-28 night): the
+  // branch above only runs when `adl.git-identity`'s own narrow, offset-
+  // based scanner recognized the command as identity-bearing at all
+  // (`decision.rewrite` set) — it does not walk into `if`/`!`/`for..do`/
+  // `xargs`/a heredoc or here-string/a piped-into shell to find a buried
+  // git/adl/curl invocation (see shell/git-identity.ts's own header on why
+  // that stays narrow — bin/git-ado's own fail-closed behaviour is the
+  // backstop for a shape THIS scanner misses on a REWRITING host's native
+  // shell). But `../rules/shell/invocation.ts`'s walker (reused here via
+  // `identityBearingReason`, already proven against every one of those
+  // shapes for `adl.session-required-for-writes`'s own deny) DOES find them
+  // — and once found, there is no rewritten command to offer at all (this
+  // scanner never computed one), so the only safe outcomes are: a
+  // native-shell tool with an ENV-sourced identity (its child inherits it
+  // regardless of any rewrite, exactly like the C2 branch above), or an
+  // inline override already on the command text (travels with the text
+  // itself, no env inheritance needed) — anything else must be denied
+  // rather than run with no identity anyone can prove reached the child.
+  if (!decision.blocked && !decision.rewrite && input.kind === 'command') {
+    const broadlyIdentityBearing = invocations(input.command).some((walked) => identityBearingReason(walked) !== null)
+    if (broadlyIdentityBearing) {
+      const identity = effectiveIdentityFor(input, engineCtx)
+      const toolClass = classifyCommandTool(inv.payload)
+      const canCarry = identity.source === 'inline' || toolClass === 'other' || (toolClass === 'native-shell' && identity.source === 'env')
+      if (!canCarry) {
+        const snippet = buildSnippet(input.command)
+        const message =
+          identity.agent === undefined
+            ? gitIdentityNeedsIdentityMessage({ command: input.command, snippet })
+            : hostCannotRewriteMessage(inv.host, { command: input.command, snippet }, identity.agent)
+        inv.record?.({ reason: 'DENY R3-broad', message: message.agent, denyRuleId: GIT_IDENTITY_RULE_ID, ...identityFields(identity) })
+        const spec = specFor(inv.host)
+        return denyHostCannotRewrite(spec, inv.host, message)
+      }
+    }
+  }
+
+  // Outside the rewrite branch: a DENY made an identity decision only when
+  // the rule that actually decided is one of the four identity rules — an
+  // unrelated deny (fs.rm, git.no-verify, …) made no identity decision at
+  // all. A PASS made one too when the command is identity-bearing but
+  // needed no rewrite because it ALREADY carried a valid inline override
+  // (M8, STATUS.md 12p — "the override's PASS
+  // line"): `rewriteGitNetworkCommands`'s `unchanged` outcome covers BOTH
+  // "not identity-bearing at all" and "fully covered by an inline override
+  // already", and only `commandHasValidInlineIdentity` tells those two
+  // apart from here.
+  // R7 (STATUS.md 12p, re-review 2026-09-28 night): a
+  // `adl.git-identity` deny (identity-mismatch/unrewritable-wrapper/
+  // network-alias-redefinition/dynamic-agent/unsafe-identity) is ALWAYS
+  // about the piece LACKING a valid override — the same fallback-only
+  // reasoning `fallbackIdentity`'s doc gives the rewrite branch, and
+  // exactly what `gitIdentityDenyMessage` itself already names as the
+  // hint ("your session's own resolved identity is X"). The coarse
+  // `effectiveIdentityFor` could otherwise report an unrelated, valid
+  // override sitting on a DIFFERENT piece of the same chained command. The
+  // other three identity rules keep the coarse helper: `adl.session-
+  // required-for-writes` only ever denies when `commandHasValidInlineIdentity`
+  // is ALSO false (so the two never actually disagree for it), and `adl.
+  // token-minting-role`/`tool.azure-devops` are not piece-correlated by this
+  // change.
+  // F9: computed here (moved ahead of the PASS-side comment below, which
+  // used to be the only reader) so the DENY-side identity computation above
+  // can also test it — a role-gate deny of an Azure DevOps MCP call is the
+  // same shape as its PASS, just with the wrong identity.
+  const isAdoMcpToolCall = input.kind === 'tool-call' && KNOWN_MCP_TOOL_NAMES.has(mcpToolName(input.tool) ?? '')
+  const denyIdentity =
+    decision.blocked && (IDENTITY_RULE_IDS.has(decision.ruleId) || (isAdoMcpToolCall && ROLE_GATE_RULE_IDS.has(decision.ruleId)))
+      ? decision.ruleId === GIT_IDENTITY_RULE_ID
+        ? fallbackIdentity(engineCtx)
+        : effectiveIdentityFor(input, engineCtx)
+      : undefined
+  // Decision 5 (STATUS.md 12p): an ALLOWED Azure DevOps MCP
+  // tool call — reads included (workitem_list_or_get/pr_list_or_get/
+  // build_list_or_get, not only the four writes) — logs `identitySource`/
+  // `identityAgent` too, the SAME field names the shell path already uses
+  // (`identityFields`, below). A tool-call carries no command text at all
+  // (no inline override is possible for it — `effectiveIdentityFor`'s own
+  // tool-call branch already reflects that, unchanged), so this is exactly
+  // the session's resolved identity (env, else the machine default-agent
+  // file). Every one of these calls ALREADY required a resolvable identity
+  // to reach this PASS line at all (`adl.session-required-for-writes` denies
+  // otherwise) — this only makes that already-decided identity visible in
+  // the log, the same way the shell path's own inline-override PASS line
+  // does (M8's "the override's PASS line"). `isAdoMcpToolCall` itself is
+  // computed above, ahead of `denyIdentity` — F9 needs it there too.
+  const passIdentity = !decision.blocked && ((input.kind === 'command' && commandHasValidInlineIdentity(input.command)) || isAdoMcpToolCall) ? effectiveIdentityFor(input, engineCtx) : undefined
+  inv.record?.(
+    decision.blocked
+      ? {
+          reason: `DENY ${decision.ruleId}`,
+          message: decision.agentMessage,
+          denyRuleId: decision.ruleId,
+          ...identityFields(denyIdentity),
+        }
+      : {
+          reason: 'PASS',
+          ...(decision.advice ? { downstream: `advice ${decision.advice.ruleId}` } : {}),
+          ...identityFields(passIdentity),
+        },
+  )
+  const stdout = `${JSON.stringify(renderFor(inv.host, decision))}\n`
+
+  // Kimi and the adl-extensions OpenCode plugin recognize a denial only
+  // through exit code 2 or hookSpecificOutput.permissionDecision === 'deny'
+  // (see ../hosts/impl/kimi.ts and ../hosts/impl/opencode.ts) — exiting 0
+  // here, as every other host does, risks a real invocation reading an allow.
+  if ((inv.host === 'kimi' || inv.host === 'opencode') && decision.blocked) {
+    return { stdout, stderr: `adl hook: ${decision.userMessage}\n`, exitCode: FAIL_CLOSED_EXIT_CODE }
+  }
+
+  return { stdout, stderr: '', exitCode: 0 }
+}