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

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

@@ -0,0 +1,293 @@
+/**
+ * decide(): the single entry point that turns a shell command or tool call
+ * into a `Decision`, by running the enabled rule corpus against it.
+ *
+ * Ported from enact-repo-controls's `src/rules/engine.ts`. Fail-closed by
+ * construction: `invocations()` (shell/invocation.ts) never throws on
+ * unparseable input, it returns an `uncertain` Invocation, and `parse.uncertain`
+ * (impl/parse-uncertain.ts) denies it like any other rule — there is no
+ * separate "parse error" code path to forget to wire up.
+ *
+ * HARDCUT from the reference: `resolveHost`/`readHostFlag`/`MISSING_HOST_EXIT_CODE`
+ * moved to `../hosts/spec.ts` (per this package's target layout — host
+ * resolution is a hosts/ concern, not an engine one). `EngineContext` takes
+ * `RulesConfig` + a separate `RepoSection` from `../gating/config.ts` instead
+ * of the reference's `EffectiveConfig` (which also carries paths, host-merge
+ * config, test config, and surfaces-audit config adl hook has no use for —
+ * see `../gating/config.ts`'s header for why `RepoSection` is a sibling
+ * argument here rather than nested inside `RulesConfig`). `buildEngineContext`
+ * uses `../gating/config.ts`'s `isRuleEnabled` (`RuleEnabledResult`, not the
+ * reference's `kernel/result.ts` `Result<T, ControlsError>`).
+ */
+
+import type { AgentSection, ConfigDecodeIssue, RepoSection, RulesConfig } from '../gating/config.ts'
+import { isRuleEnabled } from '../gating/config.ts'
+import type { AgentPort, EnvPort, RepoIndexPort } from './ports.ts'
+import { noAgent } from './ports.ts'
+import type { AnyRuleSpec, Finding, MessageContext, RuleId } from './spec.ts'
+import { DEFAULT_CLASSIFY_CONFIG, invocations } from './shell/invocation.ts'
+import type { ClassifyConfig, Invocation } from './shell/invocation.ts'
+import { resolveFromEnvOrFile } from './impl/adl-identity.ts'
+import { RULE_ID, gitIdentityDenyMessage, gitIdentityNeedsIdentityMessage } from './impl/adl-git-identity.ts'
+import { rewriteGitNetworkCommands } from './shell/git-identity.ts'
+import { loadSurfacePolicy } from '../surface-policy.ts'
+
+/**
+ * The fail-closed exit code for a pre-tool-use decision that could not be
+ * rendered as a plain allow — carried over from the reference's
+ * `MISSING_HOST_EXIT_CODE` (there, also the missing-`--host` exit code; here
+ * `--host` handling is `main.ts`'s own concern, so this constant is scoped to
+ * "the engine could not build a context, or a decision could not be decided"
+ * and to Kimi's real deny contract, which independently also uses exit code
+ * 2 — see `../hosts/impl/kimi.ts` and `../pre-tool-use/handler.ts`.
+ */
+export const FAIL_CLOSED_EXIT_CODE = 2
+
+export interface EngineContext {
+  readonly config: RulesConfig
+  readonly repo: RepoSection
+  readonly agent: AgentSection
+  readonly rules: ReadonlyMap<RuleId, AnyRuleSpec>
+  /** Precomputed once per config load, not per decide() call — see buildEngineContext. */
+  readonly enabled: ReadonlySet<RuleId>
+  readonly index: RepoIndexPort
+  readonly env: EnvPort
+  /** The agent identity that produced the call being decided — see `spec.ts`'s `RuleContext.agent`. */
+  readonly agentId: AgentPort
+  /** The repository root the hook is running against — see `spec.ts`'s `RuleContext.root`. Empty when unknown. */
+  readonly root: string
+}
+
+export type BuildEngineContextResult =
+  | { readonly ok: true; readonly value: EngineContext }
+  | { readonly ok: false; readonly issue: ConfigDecodeIssue }
+
+/** Resolve which rules are enabled once, so `decide()` never has to consult `isRuleEnabled` per call. */
+export function buildEngineContext(
+  config: RulesConfig,
+  repo: RepoSection,
+  rules: ReadonlyMap<RuleId, AnyRuleSpec>,
+  index: RepoIndexPort,
+  env: EnvPort,
+  agentId: AgentPort = noAgent,
+  agent: AgentSection = { user: '', protectedBranches: ['main', 'integration'] },
+  /** The repository root — see `EngineContext.root`. Optional, appended last, so every existing call site keeps compiling. */
+  root = '',
+): BuildEngineContextResult {
+  const enabled = new Set<RuleId>()
+  for (const rule of rules.values()) {
+    const resolved = isRuleEnabled(config, rule.id, rule.category, rule.enabledByDefault)
+    if (!resolved.ok) return resolved
+    if (resolved.enabled) enabled.add(rule.id)
+  }
+  return { ok: true, value: { config, repo, agent, rules, enabled, index, env, agentId, root } }
+}
+
+export type DecideInput =
+  | { readonly kind: 'command'; readonly command: string }
+  | { readonly kind: 'tool-call'; readonly tool: string; readonly input: Readonly<Record<string, unknown>> }
+
+export interface DenyDecision {
+  readonly blocked: true
+  readonly ruleId: RuleId
+  readonly userMessage: string
+  readonly agentMessage: string
+}
+
+export interface AdviceDecision {
+  readonly blocked: false
+  readonly advice?: { readonly ruleId: RuleId; readonly userMessage: string; readonly agentMessage: string }
+  /**
+   * Set when a non-blocked command was rewritten to carry the session
+   * identity into its network git invocations (`adl.git-identity`,
+   * docs/architecture/cli-design.md §1a "Route, don't block"): the command to
+   * run instead of the one the agent sent. The pre-tool-use handler renders
+   * it per host (updatedInput / updated_input) or, on hosts whose hook
+   * contract cannot carry it, denies the call instead of running it
+   * unrewritten.
+   */
+  readonly rewrite?: { readonly ruleId: RuleId; readonly command: string }
+}
+
+export type Decision = DenyDecision | AdviceDecision
+
+/** Whitespace-collapsed and length-capped, exactly as the reference's deny.mjs built its log/message snippet. */
+export function buildSnippet(command: string): string {
+  const collapsed = command.split(/\s+/).join(' ')
+  return collapsed.length > 220 ? `${collapsed.slice(0, 217)}...` : collapsed
+}
+
+/**
+ * `~/enact-vps` is the canonical checkout the fleet reconciler builds from, and
+ * it refuses to run while that tree is dirty — so an agent writing there stops
+ * every machine updating. Agents work in a clone and push to `main`; the
+ * reconciler pulls it itself. See impl/fs-canonical-checkout.ts.
+ *
+ * The list itself is declared once in
+ * `packages/agent-settings/surface-policy.json` and inlined into the compiled
+ * binary by `bun build --compile` — the repo is absent on machines that only
+ * carry /usr/local/bin, so this must never become a runtime file read.
+ *
+ * Handoff 5 (rule 4) extends the list with two security paths that are NOT
+ * the surface-policy fleet's to manage: `~/.config/enact/` and `/etc/enact/`,
+ * where every per-vault file lives. Hard-coded here so the rule set survives
+ * a surface-policy edit, not configurable from `adl-config.toml` — a
+ * security rule the repo can switch off is one the agent can route around.
+ */
+function classifyConfigFor(repo: RepoSection, home: string): ClassifyConfig {
+  const root = home.replace(/\/+$/, '')
+  const surface = loadSurfacePolicy().deny.paths.flatMap((name) => (root ? [`${root}/${name}`, `~/${name}`] : [`~/${name}`]))
+  // No trailing slash on the tree entries — the shell classifier checks
+  // `path.startsWith('${tree}/')`, so a tree ending in `/` would require a
+  // double slash in the path to match. The handoff's `deny.paths` list
+  // (`enact-vps` etc.) follows the same no-trailing-slash convention.
+  // `/etc/enact/` is absolute on every machine, so it doesn't need a `~`
+  // expansion; `~/.config/enact/` needs both spellings because the
+  // classifier compares literal tokens and does not expand `~`.
+  // adl roots plus the legacy enact roots, which still hold vault files on
+  // machines not yet cut over.
+  const vaultRoots = root
+    ? [`${root}/.config/adl`, '~/.config/adl', '/etc/adl', `${root}/.config/enact`, '~/.config/enact', '/etc/enact']
+    : ['~/.config/adl', '/etc/adl', '~/.config/enact', '/etc/enact']
+  return {
+    ...DEFAULT_CLASSIFY_CONFIG,
+    trustedScriptPrefixes: repo.trustedScriptPrefixes,
+    deniedTrees: [...surface, ...vaultRoots],
+  }
+}
+
+function messageContextFor(command: string): MessageContext {
+  return { command, snippet: buildSnippet(command) }
+}
+
+/** `Blocked uninspectable shell input (...)` — shared with parse.uncertain.ts's own message() for the same reason. */
+function missingCommandDecision(command: string): DenyDecision {
+  const ctx = messageContextFor(command)
+  return {
+    blocked: true,
+    ruleId: 'parse.uncertain',
+    userMessage: `Blocked uninspectable shell input (missing shell command). The hook fails closed; simplify the command and retry.`,
+    agentMessage: `DENIED missing shell command. The hook cannot prove that this shell input is safe. Remove the dynamic or unparsed shell construct and retry. Blocked command: ${ctx.snippet}`,
+  }
+}
+
+/** Try every enabled rule, in registry order, against one Invocation; the first Finding wins. */
+function firstFinding(inv: Invocation, ctx: EngineContext, command: string): { readonly rule: AnyRuleSpec; readonly finding: Finding } | null {
+  for (const rule of ctx.rules.values()) {
+    if (!ctx.enabled.has(rule.id)) continue
+    const finding = rule.match(inv, { params: {}, repo: ctx.repo, index: ctx.index, env: ctx.env, agent: ctx.agentId, agentConfig: ctx.agent, command, root: ctx.root })
+    if (finding) return { rule, finding }
+  }
+  return null
+}
+
+function decideCommand(command: string, ctx: EngineContext): Decision {
+  if (!command.trim()) return missingCommandDecision(command)
+
+  const invs = invocations(command, classifyConfigFor(ctx.repo, ctx.env.home() || ''))
+  const msgCtx = messageContextFor(command)
+
+  let deny: { readonly rule: AnyRuleSpec; readonly finding: Finding } | null = null
+  let advice: { readonly rule: AnyRuleSpec; readonly finding: Finding } | null = null
+  for (const inv of invs) {
+    const found = firstFinding(inv, ctx, command)
+    if (!found) continue
+    if (found.finding.severity === 'deny') {
+      deny = found
+      break
+    }
+    if (!advice) advice = found
+  }
+
+  if (deny) {
+    const message = deny.rule.message(deny.finding, msgCtx)
+    return { blocked: true, ruleId: deny.rule.id, userMessage: message.user, agentMessage: message.agent }
+  }
+
+  // adl.git-identity's REWRITE stage (docs/architecture/cli-design.md §1a;
+  // widened by STATUS.md 12p, "The standard", to
+  // every identity-bearing command class, not only network git): every rule
+  // passed — carry the resolved identity (steps 2-3: session env, else the
+  // machine default-agent file) into every identity-bearing invocation in
+  // the command. A VALID inline override (step 1) is honoured as-is
+  // (`kind: 'unchanged'`, handled inside `rewriteGitNetworkCommands` itself,
+  // independent of whether a fallback resolved at all); an invalid/empty
+  // inline override, or a sudo/doas wrapper, is denied here as a net (the
+  // rule can be disabled per-repo; an unsafe identity is never the rule's to
+  // see).
+  //
+  // H3 (STATUS.md 12p): `needs-identity` (an
+  // identity-bearing command with no inline override and no resolvable
+  // fallback) USED to fall through here unhandled, relying entirely on
+  // `adl.session-required-for-writes` having already denied the SAME
+  // command earlier in the rule pass — a separate classification (the
+  // shared shell/invocation.ts walker) that can be disabled per repo
+  // (`[rules."adl.session-required-for-writes"] enabled = false`) or simply
+  // not recognize a shape this scanner does. Either way, nothing else here
+  // stands between an unidentified network git command and a plain allow.
+  // The engine now denies it directly instead of trusting another rule to
+  // have already covered the same ground.
+  // L4 (STATUS.md 12p): resolve the fallback
+  // identity — which can read the REAL machine default-agent file
+  // (`resolveFromEnvOrFile`) — ONLY when the command actually has an
+  // identity-bearing piece that would use it. A probe scan with
+  // `fallback: null` is fallback-INDEPENDENT for every outcome except
+  // `needs-identity`: every `deny` reason but `unsafe-identity` fires the
+  // same regardless of the fallback's value (and `unsafe-identity` itself
+  // can only ever be reached once a fallback DOES resolve, so a null-probe
+  // never reports it), and `unchanged` means no piece needed one at all —
+  // so anything other than `unchanged` is worth a real resolution (both to
+  // decide `needs-identity` for certain, and so `deny`'s own message can
+  // name the resolved identity as a hint). Most commands reaching this
+  // point (ls, cat, git status, an unrelated tool, …) are not
+  // identity-bearing at all and, with this ordering, never touch the
+  // filesystem for this.
+  const probe = rewriteGitNetworkCommands(command, null)
+  let fallback: string | null = null
+  let outcome = probe
+  if (probe.kind !== 'unchanged') {
+    const resolution = resolveFromEnvOrFile(ctx.env)
+    fallback = resolution.ok ? resolution.agent : null
+    outcome = rewriteGitNetworkCommands(command, fallback)
+  }
+  if (outcome.kind === 'needs-identity') {
+    const message = gitIdentityNeedsIdentityMessage(msgCtx)
+    return { blocked: true, ruleId: RULE_ID, userMessage: message.user, agentMessage: message.agent }
+  }
+  if (outcome.kind === 'deny') {
+    const message = gitIdentityDenyMessage(outcome.reason, msgCtx, fallback ?? undefined)
+    return { blocked: true, ruleId: RULE_ID, userMessage: message.user, agentMessage: message.agent }
+  }
+  if (outcome.kind === 'rewrite') {
+    const rewrite = { ruleId: RULE_ID, command: outcome.command }
+    if (advice) {
+      const message = advice.rule.message(advice.finding, msgCtx)
+      return { blocked: false, advice: { ruleId: advice.rule.id, userMessage: message.user, agentMessage: message.agent }, rewrite }
+    }
+    return { blocked: false, rewrite }
+  }
+
+  if (advice) {
+    const message = advice.rule.message(advice.finding, msgCtx)
+    return { blocked: false, advice: { ruleId: advice.rule.id, userMessage: message.user, agentMessage: message.agent } }
+  }
+  return { blocked: false }
+}
+
+function decideToolCall(tool: string, input: Readonly<Record<string, unknown>>, ctx: EngineContext): Decision {
+  const inv = { kind: 'tool-call' as const, tool, input }
+  const found = firstFinding(inv, ctx, `${tool} ${JSON.stringify(input)}`)
+  if (!found) return { blocked: false }
+  const msgCtx: MessageContext = { command: `${tool} ${JSON.stringify(input)}`, snippet: buildSnippet(tool) }
+  const message = found.rule.message(found.finding, msgCtx)
+  if (found.finding.severity === 'deny') {
+    return { blocked: true, ruleId: found.rule.id, userMessage: message.user, agentMessage: message.agent }
+  }
+  return { blocked: false, advice: { ruleId: found.rule.id, userMessage: message.user, agentMessage: message.agent } }
+}
+
+/** decide(command|toolcall, ctx) → Decision. Fail closed: an unparseable command denies (via parse.uncertain). */
+export function decide(input: DecideInput, ctx: EngineContext): Decision {
+  if (input.kind === 'command') return decideCommand(input.command, ctx)
+  return decideToolCall(input.tool, input.input, ctx)
+}

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

@@ -0,0 +1,51 @@
+/**
+ * `adl.build-run-denied` — docs/operations/agent-permissions.md row 12 (build run):
+ * denied for EVERY identity, unconditionally — "pipelines run on their own
+ * triggers". Unlike the other role rules in this package, this one does not
+ * branch on `ADL_AGENT_ID_AGENT` at all: the matrix's own hook-action column
+ * shows ❌ for both `agent-tarun`/`agent-vivek` and `agent-reviewer`, so there
+ * is no identity this tool is allowed for. With no identity at all,
+ * `adl.session-required-for-writes` (registered ahead of this rule) reports
+ * first with its own, more specific "no session" message; this rule is what
+ * fires once an identity IS present, which is the case that rule leaves
+ * alone.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { detailString } from './messages.ts'
+import { mcpToolName } from './mcp-tool.ts'
+import { toolCallFor } from './adl-mcp-cli.ts'
+
+const RULE_ID = 'adl.build-run-denied'
+
+export const adlBuildRunDenied: RuleSpec = {
+  id: RULE_ID,
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny build_run for every identity (docs/operations/agent-permissions.md row 12) — the MCP tool AND its adl mcp cli equivalent (M4).',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    // M4 (STATUS.md 12p): also catch `adl mcp cli build-run` — same tool, same deny.
+    const call = toolCallFor(inv)
+    if (call === null) return null
+    if (mcpToolName(call.tool) !== 'build_run') return null
+    return { ruleId: RULE_ID, severity: 'deny', detail: { tool: call.tool } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const tool = detailString(finding, 'tool')
+    const user = 'pipelines run on their own triggers'
+    return {
+      user,
+      agent:
+        `DENIED ${tool}: ${user}. No agent identity may queue a build — use build_list_or_get to inspect an ` +
+        `already-running or already-queued build instead. Blocked: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [],
+    allow: ['ls -la', 'git status'],
+  },
+}

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

@@ -0,0 +1,320 @@
+/**
+ * `adl.git-credential-bypass` — H2 (STATUS.md 12p): deny, for agents, every
+ * shell shape that reaches Azure DevOps credentials or bypasses
+ * `bin/git-ado`'s routing entirely, without touching any of the specific
+ * verbs `adl.session-required-for-writes`/`adl.git-identity` already police:
+ *
+ *  - An absolute git binary other than the managed front controller
+ *    `/usr/local/bin/git` (that IS the path `bin/git-ado` installs itself
+ *    at — see `../shell/invocation.ts`'s `binary` field on the `'git'`
+ *    Invocation). Any OTHER absolute path (`/usr/bin/git`, a homebrew git,
+ *    …) runs the real git binary directly, with no identity routing at
+ *    all — a bare `git` (resolved via `$PATH`, the normal case) is
+ *    untouched.
+ *  - `git remote update` — fetches every configured remote, the same
+ *    network operation as `git fetch`, but not a verb
+ *    `adl.session-required-for-writes`'s `NETWORK_GIT_VERBS` recognizes.
+ *  - `git submodule update/sync/foreach` — `update`/`sync` can fetch a
+ *    submodule's own remote; `foreach` runs an arbitrary shell command once
+ *    per submodule, unauditable by this hook.
+ *  - `git credential fill/approve/reject` — reads, stores or discards a
+ *    credential directly, sidestepping the front controller entirely.
+ *
+ * `security find-generic-password`/`find-internet-password` naming Azure
+ * DevOps (the fifth H2 item — a macOS Keychain read, not a git operation at
+ * all) is `adl.security-keychain-ado` below, in the same file since it
+ * shares `namesAzureDevops`, but registered as its own `category: 'tool'`
+ * rule: `tests/unit/rules-git-deny-guidance.test.ts` requires every
+ * `category: 'git'` deny to carry the git-specific "don't route around this
+ * with plumbing" guidance, which does not apply to a keychain read.
+ *
+ * `git -c alias.*` is NOT a blanket deny (regression risk: this repo's own
+ * git-alias resolution, `../shell/invocation.ts`'s `configuredGitAlias`, is
+ * an intentional, heavily-tested feature — `tests/unit/rules-git-worktree.
+ * test.ts`'s dozens of `git -c alias.wt=worktree`-shaped corpus entries SEE
+ * THROUGH a non-network inline alias on purpose). Two narrower, resolved
+ * pieces of that space ARE covered, R9 correcting this header's stale
+ * "BLOCKED" note (STATUS.md 12p):
+ *  - a SELF-referential inline `-c alias.<verb>=<value>`/`--config-env`
+ *    naming the LITERAL subcommand this invocation runs, where `<value>`'s
+ *    own verb is network/credential — `adl.git-identity`'s own
+ *    `network-alias-redefinition` reason (`../shell/git-identity.ts`), not
+ *    this rule.
+ *  - R4 (re-review 2026-09-28 night): a REPO-CONFIGURED alias (`.git/config`,
+ *    invisible to the walker's own inline/env-var-only resolution) whose
+ *    value's verb is network/credential — `repo-alias-network-verb` below,
+ *    resolved via the injectable `ctx.index.configuredAlias` port
+ *    (`git config --get alias.<verb>` in the command's own cwd) so tests
+ *    stay hermetic. Still narrower than a blanket deny: a non-network
+ *    repo-configured alias (`git st` → `alias.st=status`) is untouched.
+ *
+ * R4 also adds three more front-controller bypasses here, all sharing the
+ * same reasoning: `/usr/local/bin/git` (`bin/git-ado`) routes on the
+ * LITERAL verb/binary an agent typed — it does not resolve `PATH`
+ * overrides, `command -p`'s own default `$PATH`, or `xcrun`'s tool
+ * resolution, any of which can select a DIFFERENT `git` binary than the
+ * managed front controller while still LOOKING like an ordinary `git`
+ * invocation to this hook's own classifier:
+ *  - `PATH=`/`export PATH=` combined with a `git` invocation on the same
+ *    line (`path-override-git`).
+ *  - `command -p git …`, which explicitly uses the system default `$PATH`
+ *    (`command-dash-p-git`).
+ *  - `xcrun git …`, Xcode's own tool locator (`xcrun-git`).
+ * And a fifth: `git credential-<helper>` (or the standalone
+ * `git-credential-<helper>` binary git itself resolves that spelling to) —
+ * `credential-helper-binary` — invokes the platform credential HELPER
+ * directly, one layer below the `git credential fill/approve/reject`
+ * protocol commands this file already denies.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import type { Token } from '../shell/token.ts'
+import { tokenValue } from '../shell/token.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { isAdoUrl } from './git-helpers.ts'
+import { detailString, gitAgentTail } from './messages.ts'
+import { networkAliasVerb } from '../shell/git-identity.ts'
+
+export const RULE_ID = 'adl.git-credential-bypass'
+export const SECURITY_RULE_ID = 'adl.security-keychain-ado'
+
+/** The one absolute git path `bin/git-ado` installs itself at — see the module doc. */
+const MANAGED_GIT_BINARY = '/usr/local/bin/git'
+
+/** The first non-flag operand of `rest` — git's own `--` ends flag parsing early, same convention every other rule in this family uses. */
+function firstOperand(rest: readonly Token[]): string | null {
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = tokenValue(rest[index] as Token)
+    if (value === '--') {
+      const next = rest[index + 1]
+      return next !== undefined ? tokenValue(next).toLowerCase() : null
+    }
+    if (!value.startsWith('-')) return value.toLowerCase()
+  }
+  return null
+}
+
+const SUBMODULE_NETWORK_SUBCOMMANDS: ReadonlySet<string> = new Set(['update', 'sync', 'foreach'])
+const CREDENTIAL_HELPER_SUBCOMMANDS: ReadonlySet<string> = new Set(['fill', 'approve', 'reject'])
+
+/** `find-generic-password`, `find-internet-password`, or any other `find-*-password` subcommand `security` accepts. */
+const FIND_PASSWORD_RE = /^find-[a-z]+-password$/i
+
+/**
+ * Whether ANY argument names Azure DevOps — not just an explicit URL
+ * (`isAdoUrl`, for `https://dev.azure.com/...`), since a keychain service/
+ * account label is prose, not a URL: `"Azure DevOps"`, `azure-devops-pat`,
+ * `dev.azure.com`, `visualstudio.com`. Kept to those specific substrings
+ * (not a bare `ado`) to avoid a false positive on an unrelated service whose
+ * name happens to contain those three letters.
+ */
+function namesAzureDevops(values: readonly string[]): boolean {
+  return values.some((value) => {
+    const lower = value.toLowerCase()
+    return isAdoUrl(value) || lower.includes('azure') || lower.includes('devops') || lower.includes('visualstudio')
+  })
+}
+
+function securityFindsAdoPassword(inv: Invocation & { kind: 'command' }): boolean {
+  const values = inv.args.map((token) => tokenValue(token))
+  if (!values.some((value) => FIND_PASSWORD_RE.test(value))) return false
+  return namesAzureDevops(values)
+}
+
+/** `git credential-<helper>` as a git subcommand, or the standalone `git-credential-<helper>` binary git itself resolves that spelling to. */
+const CREDENTIAL_HELPER_BINARY_PREFIX = 'credential-'
+
+/**
+ * `credential-cache` is git's OWN transient, in-memory helper (a daemon
+ * that holds a credential for a short-lived window and exits — `git
+ * credential-cache exit` merely stops it); it never reads or writes a
+ * platform secret store the way `credential-osxkeychain`/`credential-
+ * manager`/… do, and this exact allow case predates R4 (H2's own corpus).
+ * Excluded from the deny by name rather than widened into a blanket
+ * "every credential-* helper", to avoid regressing that settled behaviour.
+ */
+const CREDENTIAL_HELPER_ALLOWED_NAMES: ReadonlySet<string> = new Set(['cache'])
+
+function isDeniedCredentialHelper(subcommandOrName: string): boolean {
+  if (!subcommandOrName.startsWith(CREDENTIAL_HELPER_BINARY_PREFIX)) return false
+  return !CREDENTIAL_HELPER_ALLOWED_NAMES.has(subcommandOrName.slice(CREDENTIAL_HELPER_BINARY_PREFIX.length))
+}
+
+/**
+ * Git's own real subcommand vocabulary (porcelain and common plumbing),
+ * lower-cased — R4 (STATUS.md 12p): gates the repo-
+ * configured-alias lookup (`ctx.index.configuredAlias`) to an UNKNOWN verb
+ * only, per this finding's own text ("resolve unknown git verbs"), so an
+ * ordinary `git status`/`git log`/… never pays for a `git config --get`
+ * shell-out. Not exhaustive — an obscure real git verb missing here only
+ * costs one harmless extra (correctness-preserving) lookup that resolves to
+ * nothing, never a false deny.
+ */
+const KNOWN_GIT_VERBS: ReadonlySet<string> = new Set([
+  'add', 'am', 'apply', 'archive', 'bisect', 'blame', 'branch', 'bundle', 'checkout', 'cherry-pick',
+  'clean', 'clone', 'commit', 'config', 'credential', 'describe', 'diff', 'difftool', 'fetch', 'format-patch',
+  'fsck', 'gc', 'grep', 'help', 'init', 'instaweb', 'log', 'ls-files', 'ls-remote', 'maintenance',
+  'merge', 'mergetool', 'mv', 'notes', 'pull', 'push', 'rebase', 'reflog', 'remote', 'request-pull',
+  'reset', 'restore', 'revert', 'rev-parse', 'rm', 'send-email', 'shortlog', 'show', 'sparse-checkout', 'stash',
+  'status', 'submodule', 'switch', 'tag', 'verify-commit', 'verify-tag', 'version', 'whatchanged', 'worktree',
+])
+
+/**
+ * `PATH=`/`export PATH=` anywhere in `command`, co-occurring with a `git`
+ * invocation this rule is already deciding — coarse (whole-command, not
+ * piece-scoped) by design, matching R3's own precedent elsewhere in this
+ * package: a PATH override ahead of `git` ANYWHERE on the line is suspicious
+ * enough on its own that over-denial costs nothing legitimate.
+ */
+function pathOverridePresent(command: string): boolean {
+  return /(?:^|[\s;&|(])(?:export\s+)?PATH=/.test(command)
+}
+
+/** `command -p git …` — `-p` makes `command` search the system default `$PATH`, bypassing any override AND the managed front controller alike. */
+function commandDashPPresent(command: string): boolean {
+  return /\bcommand\s+(?:-\S+\s+)*-p\b/.test(command)
+}
+
+/** `xcrun git …` — Xcode's own tool locator, independent of `$PATH`. */
+function xcrunGitPresent(command: string): boolean {
+  return /\bxcrun\s+git\b/i.test(command)
+}
+
+export const adlGitCredentialBypass: RuleSpec = {
+  id: RULE_ID,
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny an absolute non-managed git binary, git remote update, git submodule update/sync/foreach, git credential fill/approve/reject, a direct credential-helper binary, a PATH/command -p/xcrun bypass, and a repo-configured alias to a network verb.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    if (inv.kind === 'command') {
+      const name = inv.name.toLowerCase()
+      if (name.startsWith('git-') && isDeniedCredentialHelper(name.slice('git-'.length))) {
+        return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'credential-helper-binary', helper: inv.name } }
+      }
+      return null
+    }
+    if (inv.kind !== 'git') return null
+    if (inv.binary !== undefined && inv.binary.startsWith('/') && inv.binary !== MANAGED_GIT_BINARY) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'absolute-git-binary', binary: inv.binary } }
+    }
+    if (inv.subcommand === 'remote' && firstOperand(inv.rest) === 'update') {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'git-remote-update' } }
+    }
+    if (inv.subcommand === 'submodule' && SUBMODULE_NETWORK_SUBCOMMANDS.has(firstOperand(inv.rest) ?? '')) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'git-submodule-network' } }
+    }
+    if (inv.subcommand === 'credential' && CREDENTIAL_HELPER_SUBCOMMANDS.has(firstOperand(inv.rest) ?? '')) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'git-credential-helper' } }
+    }
+    if (isDeniedCredentialHelper(inv.subcommand)) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'credential-helper-binary', helper: inv.subcommand } }
+    }
+    const command = ctx.command ?? ''
+    if (pathOverridePresent(command)) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'path-override-git' } }
+    }
+    if (commandDashPPresent(command)) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'command-dash-p-git' } }
+    }
+    if (xcrunGitPresent(command)) {
+      return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'xcrun-git' } }
+    }
+    if (!KNOWN_GIT_VERBS.has(inv.subcommand)) {
+      const alias = ctx.index.configuredAlias?.(inv.subcommand) ?? null
+      if (alias !== null && networkAliasVerb(alias)) {
+        return { ruleId: RULE_ID, severity: 'deny', detail: { reason: 'repo-alias-network-verb', alias: inv.subcommand } }
+      }
+    }
+    return null
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const reason = detailString(finding, 'reason')
+    const specific =
+      reason === 'absolute-git-binary'
+        ? `Blocked an absolute git binary (${finding.detail.binary ?? 'a non-managed path'}) other than the managed front controller ${MANAGED_GIT_BINARY}.`
+        : reason === 'git-remote-update'
+          ? 'Blocked `git remote update`: it fetches every configured remote, the same network operation as `git fetch`.'
+          : reason === 'git-submodule-network'
+            ? 'Blocked `git submodule update/sync/foreach`: it can fetch a submodule remote, or run an arbitrary command once per submodule.'
+            : reason === 'git-credential-helper'
+              ? 'Blocked `git credential fill/approve/reject`: it reads, stores, or discards a credential directly.'
+              : reason === 'credential-helper-binary'
+                ? `Blocked the credential helper (${finding.detail.helper ?? 'git-credential-*'}) directly: it reads or stores a credential straight from the platform's own store, one layer below the \`git credential\` protocol commands.`
+                : reason === 'path-override-git'
+                  ? 'Blocked a `PATH=`/`export PATH=` override alongside a `git` invocation: it can select a different `git` binary than the managed front controller.'
+                  : reason === 'command-dash-p-git'
+                    ? "Blocked `command -p git …`: `-p` runs with the system default `$PATH`, which can bypass the managed front controller."
+                    : reason === 'xcrun-git'
+                      ? "Blocked `xcrun git …`: Xcode's own tool locator can resolve to a different `git` binary than the managed front controller."
+                      : `Blocked \`git ${finding.detail.alias ?? '<alias>'}\`: this repository's own \`.git/config\` resolves it to a network or credential operation the managed front controller would not see through.`
+    return {
+      user: specific,
+      agent:
+        `DENIED ${specific} Use \`adl id token <agent>\` or the Azure DevOps MCP server, which brokers credentials as ` +
+        'the resolved agent identity — never a raw git binary outside the managed front controller, a PATH/`command -p`/`xcrun` ' +
+        `bypass, a repo-configured alias to a network verb, or a submodule/remote/credential-helper shortcut. ${gitAgentTail(ctx.snippet)}`,
+    }
+  },
+  corpus: {
+    deny: [
+      '/usr/bin/git push origin main',
+      '/opt/homebrew/bin/git status',
+      'git remote update',
+      'git remote update origin',
+      'git submodule update --init',
+      'git submodule sync',
+      'git submodule foreach "git pull"',
+      'git credential fill',
+      'git credential approve',
+      'git credential reject',
+      'git credential-osxkeychain get',
+      'git-credential-osxkeychain get',
+      'PATH=/tmp/evil:$PATH git push origin main',
+      'export PATH=/tmp/evil:$PATH && git push origin main',
+      'command -p git push origin main',
+      'xcrun git push origin main',
+      // The repo-configured-alias case ('repo-alias-network-verb') needs a
+      // specific `ctx.index.configuredAlias` fixture the shared corpus
+      // cannot supply — see tests/unit/rules-adl-git-credential-bypass.test.ts's
+      // dedicated "repo-configured alias" describe block instead.
+    ],
+    allow: [
+      'git status',
+      '/usr/local/bin/git status',
+      'git remote -v',
+      'git remote add origin https://github.com/org/repo',
+      'git submodule status',
+      'git credential-cache exit',
+    ],
+  },
+}
+
+export const adlSecurityKeychainAdo: RuleSpec = {
+  id: SECURITY_RULE_ID,
+  category: 'tool',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny `security find-generic-password`/`find-internet-password` naming Azure DevOps — read the credential through adl instead of the macOS keychain directly.',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    if (inv.kind !== 'command' || inv.name !== 'security') return null
+    if (!securityFindsAdoPassword(inv)) return null
+    return { ruleId: SECURITY_RULE_ID, severity: 'deny', detail: { reason: 'security-find-password-ado' } }
+  },
+  message(_finding: Finding, ctx: MessageContext) {
+    const user = 'Blocked `security find-*-password` naming Azure DevOps: it reads a stored credential straight out of the macOS keychain.'
+    return {
+      user,
+      agent:
+        `DENIED ${user} Use \`adl id token <agent>\` or the Azure DevOps MCP server, which brokers credentials as the ` +
+        `resolved agent identity — never the macOS keychain directly. Blocked command: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: ['security find-generic-password -s "Azure DevOps" -w', 'security find-internet-password -s dev.azure.com -w'],
+    allow: ['security find-generic-password -s "GitHub" -w', 'security list-keychains'],
+  },
+}