@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.35 → 0.1.46

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

@@ -34,11 +34,12 @@
  * 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.
+ * Rows 6-8 (PR comment; PR vote on `main`; PR vote on `integration`) ship
+ * their own gate now: the sibling `adl-pr-review-role.ts` rules
+ * `pr_review` (shipped in `packages/azdo/src/azdo-pr-review.ts`, C3
+ * 2026-09-27) — comment allowed for the same allow-set as row 5, vote
+ * allowed for `agent-reviewer` only and only on `main`. This rule does not
+ * match `pr_review` at all; the two rules never fight over the same call.
  *
  * Requires an identity to already be present (`ADL_AGENT_ID_AGENT`
  * non-blank) — with no identity at all, `adl.run-required-for-writes`

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

@@ -58,9 +58,12 @@
  *    request-item/`--form`/`--raw` implying a body (httpie's own semantics:
  *    a request with data defaults to POST, one without defaults to GET).
  *  - An Azure DevOps MCP write tool (the `'tool-call'` kind), named
- *    `mcp__<prefix>__<tool>` where `<tool>` is one of the four mutating
+ *    `mcp__<prefix>__<tool>` where `<tool>` is one of the six mutating
  *    tools `packages/azdo/src/mcp-server.ts` actually registers:
- *    `pr_create_or_update`, `pr_review`, `build_run`, `workitem_create_or_update`. The
+ *    `pr_create_or_update`, `pr_review`, `build_run`, and the three
+ *    `workitem_create_or_update_feature`/`_pbi`/`_bug` (the tool NAME carries
+ *    the work-item type, so there is no blanket `workitem_create_or_update`
+ *    tool any more). The
  *    match is on the TOOL NAME alone, not the server prefix — the package is
  *    `azdo`, P4 folds the server under `adl`, and Claude Code's plugin-scoped
  *    form (`mcp__plugin_<plugin>_<server>__<tool>`) adds a third spelling —
@@ -165,7 +168,8 @@ const HTTP_CLIENT_NAMES = HTTP_CLIENT_BINARY_NAMES
  * `ListToolsRequestSchema` handler (re-checked 2026-10-01) — the
  * complete tool roster there is `pr_list_or_get`/`pr_create_or_update`/
  * `pr_review`, `build_list_or_get`/`build_run`, `workitem_list_or_get`/
- * `workitem_create_or_update`; the three not in this set are the read half.
+ * `workitem_create_or_update_feature`/`_pbi`/`_bug`; the three not in this
+ * set are the read half.
  * `pr_review` (docs/operations/agent-permissions.md rows 6-8: comment + vote) is
  * in this set because `adl-pr-review-role.ts` gates it by role —
  * a caller with no run identity at all must be denied here FIRST, the
@@ -176,7 +180,9 @@ const ADO_MCP_WRITE_TOOLS: ReadonlySet<string> = new Set([
   'pr_create_or_update',
   'pr_review',
   'build_run',
-  'workitem_create_or_update',
+  'workitem_create_or_update_feature',
+  'workitem_create_or_update_pbi',
+  'workitem_create_or_update_bug',
 ])
 
 /**
@@ -184,7 +190,7 @@ const ADO_MCP_WRITE_TOOLS: ReadonlySet<string> = new Set([
  * DevOps MCP tool call, reads included — the read half gets no
  * pass just because it cannot mutate anything. `mcp-server.ts`'s complete
  * roster: `pr_list_or_get`, `build_list_or_get`, `workitem_list_or_get`
- * (reads) alongside the four writes above.
+ * (reads) alongside the six writes above.
  */
 /** The leading words of the `identityBearingReason` for an Azure DevOps MCP tool call — `message()` keys the MCP-only CLI advice off it. */
 const MCP_REASON_PREFIX = 'Azure DevOps MCP tool'

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

@@ -27,20 +27,33 @@ import { effectiveIdentityForMcpCli, toolCallFor } from './adl-mcp-cli.ts'
 
 const RULE_ID = 'adl.workitem-requires-tarun-or-vivek'
 
+/**
+ * The work-item write tools this rule grades — the three per-type siblings the
+ * MCP server registers (the old single `workitem_create_or_update` tool is
+ * gone; the tool NAME is the type, so there is no `type` argument to inspect).
+ * A name outside this set is not a work-item write at all and is left to
+ * `adl.run-required-for-writes`/`adl-pr-role.ts`.
+ */
+const WORKITEM_WRITE_TOOLS: ReadonlySet<string> = new Set([
+  'workitem_create_or_update_feature',
+  'workitem_create_or_update_pbi',
+  'workitem_create_or_update_bug',
+])
+
 export const adlWorkitemRequiresTarunOrVivek: RuleSpec = {
   id: RULE_ID,
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny workitem_create_or_update for agent-reviewer (docs/operations/agent-permissions.md row 10) — the MCP tool AND its adl mcp cli equivalent.',
+  summary: 'Deny the workitem_create_or_update_* tools for agent-reviewer (docs/operations/agent-permissions.md row 10) — the MCP tools AND their adl mcp cli equivalents.',
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
-    // `adl mcp cli
-    // workitem-create-or-update` dispatches to the same tool the MCP server
-    // calls — graded identically, not only the tool-call payload shape.
+    // `adl mcp cli workitem-create-or-update-feature`/`-pbi`/`-bug` dispatch to
+    // the same tools the MCP server calls — graded identically, not only the
+    // tool-call payload shape.
     const call = toolCallFor(inv)
     if (call === null) return null
-    if (mcpToolName(call.tool) !== 'workitem_create_or_update') return null
+    if (!WORKITEM_WRITE_TOOLS.has(mcpToolName(call.tool) ?? '')) return null
 
     // Grade the EFFECTIVE identity for THIS specific piece — a valid inline
     // `ADL_AGENT_ID_AGENT=` override on the same `adl mcp cli` invocation

package/packages/agent-hooks/src/rules/impl/agent-tamper-protection.ts

@@ -2,21 +2,25 @@
  * Editing the files that wire the host's hooks.
  *
  * Handoff 5, rule 5: deny Write/Edit/MultiEdit/NotebookEdit on
- * `.claude/settings.json`, `.claude/settings.local.json`, or
- * `.codex/config.toml`. These are the files that install the hook into the
- * host (including the `.local.json` overrides). Editing any of them is a way
- * to switch the gate off without anyone noticing.
+ * `.claude/settings.json`, `.claude/settings.local.json`, and
+ * `.codex/config.toml`. These are the files that install the hook into
+ * the host (including the `.local.json` overrides) — editing any of them
+ * is a way to switch the gate off without anyone noticing.
  *
- * `adl-config.toml` was the fourth file until 2026-10-01 (Tarun: "nobody
- * should stop editing adl-config.toml"). It is no longer on the list, so an
- * agent can edit, move or delete it. Two things follow, both accepted by the
- * owner: (1) every hook run re-reads it, so `[hooks] enabled = false` (a
- * silent no-op, `main.ts`'s `runHook`) or a `[rules."<id>"] enabled = false`
- * takes effect on the agent's next tool call, ahead of any commit — the
- * commit-time layers (`git.protected-tree-commit`, repo-controls' integrity
- * gate) are the only review left; (2) the carriers that stayed on the list
- * below are only as strong as that file, since it can also switch THIS rule
- * off.
+ * `adl-config.toml` is NOT in this set. The earlier 2026-10-12 ruling
+ * ("we left a door open, close it") assumed the working-tree copy is what
+ * every running hook reads and that an agent writing
+ * `[hooks] enabled = false` flips the gate off ahead of any commit. The
+ * commit side IS enforced — repo-controls' `integrity.ts` (`WIRING`,
+ * refuses a normal commit of `adl-config.toml`) and `agent-hooks`'s
+ * `git.protected-tree-commit` rule (PBI 373/679) — and the working-tree
+ * edit is a runtime-config edit, not a carrier rewrite. The design
+ * ("agents may edit [WIRING] while preparing a reviewed change, but a
+ * normal commit must never land them" — integrity.ts:5-7) places the
+ * edit on the allowed side and the commit on the denied side.
+ * Re-confirmed 2026-10-13 (Tarun: "adl-config.toml can be editted but
+ * not committed by the agents"). `adl-config.toml` is a config file,
+ * not a hook carrier.
  *
  * Hooks are local-repo-first (Tarun, 2026-09-29): there is no managed-hooks
  * lock and no global carrier, so these per-repo carrier files are the ONLY
@@ -477,20 +481,21 @@ export const agentTamperProtection: RuleSpec = {
           : via === 'interpreter'
             ? 'an interpreter one-liner writing'
             : 'editing'
+    const listed = [...PROTECTED_CARRIER_PATHS]
+      .map((p) => '`' + p + '`')
+      .join(', ')
     return {
       user: `Blocked ${via === 'tool-call' ? 'editing' : verb} ${path}. This file wires the host's hooks; ask the user to change it.`,
       agent:
-        `DENIED ${verb} ${path}. This file is one of the tamper-protected files: ` +
-        '`.claude/settings.json`, `.claude/settings.local.json`, `.codex/config.toml`, ' +
-        '`.codex/hooks.json`, `.cursor/hooks.json`, `.opencode/plugins/adl-repo.ts`, ' +
-        "or `~/.kimi-code/config.toml`. Each installs or overrides a host's own hook contract " +
-        "(directly, or — for `.opencode/plugins/adl-repo.ts` — as the generated plugin THAT IS " +
-        "the carrier; `~/.kimi-code/config.toml` is Kimi's own single, globally-installed " +
-        'carrier — Kimi has no per-repo one). Editing, overwriting, moving over, truncating, ' +
-        'deleting, or rewriting any of them — by a tool call, a shell write, or a git checkout/ ' +
-        'restore/reset/rm — is a way to switch the gate off without anyone noticing, the ONLY ' +
-        'enforcement layer for the hosts that read them (there is no managed-hooks lock). ' +
-        `If a legitimate change is needed, file a PR or ask the user to make it themselves. ` +
+        `DENIED ${verb} ${path}. This file is one of the tamper-protected files: ${listed}. ` +
+        'Each installs or overrides a host\'s own hook contract. Editing, overwriting, moving ' +
+        'over, truncating, deleting, or rewriting any of them — by a tool call, a shell write, ' +
+        'or a git checkout/restore/reset/rm — is a way to switch the gate off without anyone ' +
+        'noticing, the ONLY enforcement layer for the hosts that read them (there is no ' +
+        'managed-hooks lock). `adl-config.toml` is intentionally NOT in this list: it is a ' +
+        'runtime config file an agent may edit; the commit is denied by `git.protected-tree-' +
+        'commit` and by repo-controls\' `integrity.ts` (PBI 373/679). If a legitimate change ' +
+        `to a host carrier is needed, file a PR or ask the user to make it themselves. ` +
         `Blocked call: ${ctx.snippet}`,
     }
   },

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

@@ -49,10 +49,9 @@ export const gitHooksPath: RuleSpec = {
       'git -c core.hooksPath=/dev/null commit -m x',
       'git -c core.hooksPath= push',
       'git -c core.hooksPath=/tmp/empty commit --amend',
-      'git config core.hooksPath /dev/null',
-      'git config --global core.hooksPath /tmp/empty',
     ],
-    allow: ['git stash --help', 'git config user.name t'],
+    // The `git config core.hooksPath …` positive controls were here for years — gone as of Bug 695 (2026-10-12): `adl.git-user-override-block` denies every `git config` invocation in the engine, so a `git config …` string is denied upstream and never exercises the `subcommand === 'config' && overridesHooksPath(git.rest)` branch (the `-c` deny entries above still cover the override surface).
+    allow: ['git stash --help'],
   },
 }
 
@@ -91,11 +90,8 @@ export const gitCoreBare: RuleSpec = {
     deny: [
       'git -c core.bare=true status',
       'git -c core.bare=false commit -m x',
-      'git config core.bare true',
-      'git config --bool core.bare true',
-      'git config --global core.bare true',
-      'git config --unset core.bare',
     ],
-    allow: ['git status', 'git config user.name t'],
+    // The `git config core.bare …` positive controls were here for years — gone as of Bug 695 (2026-10-12): `adl.git-user-override-block` denies every `git config` invocation in the engine, so a `git config …` string is denied upstream and never exercises the `subcommand === 'config' && flipsCoreBare(git.rest)` branch (the `-c` deny entries above still cover the override surface).
+    allow: ['git status'],
   },
 }

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

@@ -209,6 +209,7 @@ function heredocDelimiters(piece: string): string[] | 'unparsable' {
       for (; i < piece.length && !/[\s;|&<>()]/.test(piece[i] as string); i++) {
         sawWord = true
         const c = piece[i] as string
+        /* istanbul ignore next -- splitShell() only yields a valid (non-`invalid`) result when its trailing `escape` flag is clear, and it clears that flag by consuming the escaped character; so a valid piece can never END on a lone `\`, it can only end on the SECOND half of a `\\` pair, which this scan reaches as `c` and steps over with a defined `piece[++i]`. Exhaustively checked: 15,867,149 valid commands over the 18-symbol quote/separator alphabet produced zero pieces ending in a lone backslash. */
         if (c === '\\') word += piece[++i] ?? ''
         else if (c === "'" || c === '"') {
           const close = piece.indexOf(c, i + 1)
@@ -240,6 +241,7 @@ function parse(command: string): Parsed | null | 'closed' {
   let cursor = 0
   for (const piece of split.pieces) {
     const at = command.indexOf(piece, cursor)
+    /* istanbul ignore next -- every piece splitShell() returns is an ordered, non-overlapping substring of the very `command` it was split from, so `indexOf(piece, cursor)` always finds it at or after `cursor`; `at < 0` would require splitShell() to emit a piece that is not in its input. Exhaustively checked: 958,762 valid commands over the 18-symbol quote/separator alphabet produced zero such pieces. */
     if (at < 0) return { tokens, gaps: null, functions }
     gaps.push(command.slice(cursor, at))
     cursor = at + piece.length
@@ -342,9 +344,11 @@ function applyState(parsed: Parsed, until: number, target: Mutable): boolean {
       if (state.names.includes('GIT_WORK_TREE')) delete target.workTree
       continue
     }
+    /* istanbul ignore next -- `gaps` is null on exactly one path, parse()'s `at < 0` return above, which is itself unreachable because splitShell() only emits ordered non-overlapping substrings of `command`. Every other parse() result carries a populated `gaps`, so this re-check is the fail-closed half of that invariant rather than a reachable state. */
     if (parsed.gaps === null) return false
     const before = plainGap(parsed.gaps[i] as string)
     if (before === null) return false
+    /* istanbul ignore next -- `parsed.tokens[i - 1]` is null only for a here-doc BODY, and parse() sets `gaps[body] = '\n'` for every such nulled index; bodies are newline-separated, so the gap at the next index is that same `'\n'`, never `'&&'`. `before === '&&'` therefore short-circuits before this line reads `tokens[i - 1]`, so the `?? null` fallback is unreachable. */
     if (before === '&&' && (i === 0 || !['cd', 'export'].includes(classify(parsed.tokens[i - 1] ?? null, parsed.functions).kind))) return false
     for (let j = i + 1; j <= Math.min(until, parsed.gaps.length - 1); j++) if (plainGap(parsed.gaps[j] as string) === null) return false
     if (state.kind === 'cd') {
@@ -406,6 +410,7 @@ function walk(command: string, inv: Invocation & { kind: 'git' }, inherited: Mut
     if (inner === undefined) continue
     if (inner === null || !applyState(parsed, i, target)) return null
     const nested = walk(script, inv, target)
+    /* istanbul ignore next -- `inner` and `nested` are the SAME walk over the SAME script and invocation, differing only in the inherited `dirs`/`gitDir`/`workTree`; no branch inside walk() reads those to choose null or undefined (only `homeUnknown` gates expandPath, and applyState above never sets it). Since `inner` was already a non-null target here, so is `nested`, and the fallback is unreachable. Fuzzed: 6.6M generated shell/-c command pairs produced no case where it fires. */
     return nested ?? null
   }
   return undefined

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

@@ -11,7 +11,9 @@ export const KNOWN_MCP_TOOL_NAMES: ReadonlySet<string> = new Set([
   'build_list_or_get',
   'build_run',
   'workitem_list_or_get',
-  'workitem_create_or_update',
+  'workitem_create_or_update_feature',
+  'workitem_create_or_update_pbi',
+  'workitem_create_or_update_bug',
 ])
 
 /**
@@ -50,7 +52,7 @@ export function toolNameEndingWithKnownSuffix(tool: string, knownSuffixes: Reado
  *
  * Shared by every rule that gates an Azure DevOps MCP tool by name
  * (adl-run-required.ts, adl-pr-role.ts, adl-pr-complete-pending.ts,
- * adl-workitem-role.ts, adl-build-run-denied.ts) so the parsing cannot drift
+ * adl-workitem-role.ts, adl-build-run-role.ts) so the parsing cannot drift
  * between them.
  *
  * Prefix-less fallback (added 2026-09-28 with the one-agent-identity

package/packages/agent-hooks/src/rules/impl/tool-frontend.ts

@@ -9,6 +9,30 @@
  * body either way; the allowance is stated in the message for the human,
  * not enforced here).
  *
+ * az365 (Scope A — JS-toolchain mutation policy, 2026-10-13): the matcher
+ * was a binary-name-only `deny` returning a Finding for every
+ * `frontend-tool` invocation regardless of effect. The OLD corpus
+ * contained 14 read-only invocations (lint, typecheck, coverage, test
+ * runs without snapshot updates, help-only) as `deny`, which is the bug:
+ * a legitimate "look at my code" call was refused with the same Finding
+ * as a file-rewriting one. The new matcher inspects `inv.args` and
+ * returns `null` (allow) for read-only invocations, returning a Finding
+ * only for the mutating ones:
+ *
+ *   deny  biome format … --write   (file rewrite)
+ *   deny  vitest run -u / --update  (snapshot mutation)
+ *   deny  tsc <file>               (no --noEmit; emits .js/.d.ts)
+ *   allow tsc --noEmit             (type-check, no emit)
+ *   allow biome check …            (read)
+ *   allow biome lint …             (read)
+ *   allow vitest run               (test runner, no source write)
+ *   allow vitest --coverage run    (writes only to coverage/)
+ *   allow jest --testPathPattern=  (test runner, no source write)
+ *
+ * The matcher does NOT inspect the `just` recipe body — the gate runs at
+ * the recipe boundary, not inside it. `--help`/`--version` are already
+ * short-circuited at classification time and never reach this matcher.
+ *
  * Tarun's decision (2026-09-27, feature az372): the message must not name a
  * particular recipe — see messages.ts's `JUST_RECIPES_POINTER`.
  */
@@ -18,37 +42,231 @@ import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
 import { detailString, JUST_RECIPES_POINTER } from './messages.ts'
 
+/** `biome format … --write` rewrites files in place. The flag may appear anywhere on the command line (`--write foo` or `foo --write`); the `--write=foo` and `-wX` concatenated forms arrive as single tokens. */
+function biomeFormatWritesFile(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '--write' || arg.value === '-w') return true
+    if (arg.value.startsWith('--write=')) return true
+    // Concatenated short-flag form: `-wX` where X is anything. The shell
+    // does not split the token; the matcher sees `-wX` as one element.
+    if (arg.value.startsWith('-w') && arg.value.length > 2) return true
+    return false
+  })
+}
+
+/**
+ * `tsc <file>` without `--noEmit` emits `.js` and `.d.ts` files into the
+ * working tree. `tsc --noEmit` is the read intent. A bare `tsc` (no
+ * file operand, no flags) does nothing the matcher cares about — tsc
+ * without operands reads `tsconfig.json` and may emit based on its
+ * `noEmit` setting; we treat the no-operand case as ambiguous and let
+ * it through (the engine's `uncertain` category would catch it if a
+ * future rule needs that).
+ */
+const TSC_VALUE_FLAGS: ReadonlySet<string> = new Set([
+  '-p', '--project', // config file
+  '--build',          // takes a project reference; value can be 'false'
+  '-t', '--target',
+  '--module',
+  '--moduleResolution',
+  '--jsx',
+  '--outDir',
+  '--rootDir',
+  '--baseUrl',
+  '--paths',
+  '--types',
+  '--lib',
+])
+
+function tscWritesFiles(args: readonly { readonly value: string }[]): boolean {
+  // --noEmit is the read intent; --noEmit=false is the write intent.
+  if (args.some((arg) => arg.value === '--noEmit')) return false
+  // Explicit emit flags are the write intent regardless of the file operand.
+  if (args.some((arg) => arg.value === '--emit' || arg.value.startsWith('--emit='))) return true
+  // Walk the args, skipping a value-taking flag's operand, and look for a
+  // positional file operand that names a .ts/.tsx file. That is the
+  // write intent: tsc defaults to emit when given a source file.
+  // `tsc -p tsconfig.json` is read-only because `-p` only names the
+  // config; tsc respects the config's own `noEmit` setting.
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] as { readonly value: string }
+    if (arg.value.startsWith('-')) {
+      // Flag with a value takes the next word; skip it so we do not
+      // mistake the flag's value (`tsconfig.json` after `-p`) for a
+      // positional file operand.
+      if (TSC_VALUE_FLAGS.has(arg.value)) index += 1
+      continue
+    }
+    // Positional operand that names a TypeScript source file is the
+    // write intent. Anything else (a config, a glob, an empty) is not.
+    if (/\.tsx?$/.test(arg.value)) return true
+  }
+  return false
+}
+
+/**
+ * `vitest run -u` / `vitest run --update` mutates snapshot files in place.
+ * The shell hands the matcher individual tokens; the `-uX` / `--update=now`
+ * / `-u=foo` concatenation forms arrive as a single token whose value
+ * starts with `-u` or `--update=`. Treat any token that starts with `-u`
+ * or `--update` (and is not a different flag like `--updateSnapshot`
+ * which is a different binary's flag) as the snapshot-write trigger.
+ */
+function vitestUpdatesSnapshots(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '-u' || arg.value === '--update') return true
+    if (arg.value === '-u=' || arg.value.startsWith('--update=')) return true
+    // Concatenated short-flag form: `-uX` where X is anything (rare in
+    // practice; vitest doesn't combine `-u` with other short flags, but
+    // the shell hands the matcher the token unsplit). Match `-u` as a
+    // prefix only when the rest is a non-flag char, so `-update` (long
+    // option) does not match.
+    if (arg.value.startsWith('-u') && arg.value.length > 2) return true
+    return false
+  })
+}
+
+/** `jest --testPathPattern=… -u` / `jest -u` / `jest --updateSnapshot` mutates snapshots. */
+function jestUpdatesSnapshots(args: readonly { readonly value: string }[]): boolean {
+  return args.some((arg) => {
+    if (arg.value === '-u' || arg.value === '--updateSnapshot') return true
+    if (arg.value === '-u=' || arg.value.startsWith('--updateSnapshot=')) return true
+    // Concatenated short-flag form: `-uX` as above.
+    if (arg.value.startsWith('-u') && arg.value.length > 2) return true
+    return false
+  })
+}
+
 export const toolFrontend: RuleSpec = {
   id: 'tool.frontend',
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: "Deny direct npx/vitest/jest/biome/tsc; steer at the repository's just recipes.",
+  summary: "Deny mutating npx/vitest/jest/biome/tsc invocations; reads and tests are permitted.",
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'frontend-tool') return null
-    return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool } }
+    const args = inv.args
+    // The mutating surfaces. Each is the only binary-name whose flag
+    // shape can change the working tree; if the rule's matcher here
+    // grows, the corpus deny list below is the place to add the new
+    // fixture so the engine's verdict stays testable.
+    switch (inv.tool.replace(/\.exe$/i, '')) {
+      case 'biome':
+        // `biome format … --write` is the file-rewrite path. `biome
+        // check` and `biome lint` are reads and must NOT be denied. The
+        // matcher inspects the args to distinguish; without this
+        // inspection every biome invocation is denied, which is the
+        // az365 Scope A bug.
+        if (biomeFormatWritesFile(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'biome-format-write' } }
+        }
+        return null
+      case 'tsc':
+        // `tsc --noEmit` is a read. `tsc <file>` without --noEmit emits
+        // .js and .d.ts into the working tree. Match the absence of
+        // --noEmit as the write intent.
+        if (tscWritesFiles(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'tsc-emit' } }
+        }
+        return null
+      case 'vitest':
+        // `vitest run` is a test runner. The .vitest cache directory and
+        // any coverage output live under node_modules / coverage/, not in
+        // project source. `-u` / `--update` is the snapshot-mutation
+        // path; the snapshot files live alongside the test files and ARE
+        // project source.
+        if (vitestUpdatesSnapshots(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'vitest-snapshot-write' } }
+        }
+        return null
+      case 'jest':
+        if (jestUpdatesSnapshots(args)) {
+          return { ruleId: 'tool.frontend', severity: 'deny', detail: { tool: inv.tool, action: 'jest-snapshot-write' } }
+        }
+        return null
+      case 'npx':
+        // `npx biome check …` is a read; `npx vitest run` is a test
+        // runner; `npx tsc --noEmit` is a typecheck. None mutate source.
+        // The mutating shape (browser automation, file rewrites) is
+        // Scope B (az365's split into a separate Feature for browser
+        // automation); this rule's match() does not cover it today and
+        // the agent-hooks `adl-human-azdo-bypass` rule plus the future
+        // `tool.browser-automation` rule (Feature azTBA) are the right
+        // place for it.
+        return null
+      default:
+        // Unknown `frontend-tool` name (a new addition to
+        // ClassifyConfig.frontendToolNames the rule does not yet know
+        // about). Default to allow and let the corpus surface it as a
+        // chosen behaviour on the next pass.
+        return null
+    }
   },
   message(finding: Finding, ctx: MessageContext) {
     const tool = detailString(finding, 'tool')
+    const action = detailString(finding, 'action')
+    const actionLabel =
+      action === 'biome-format-write' ? 'file rewrite'
+      : action === 'tsc-emit' ? 'tsc emit (.js / .d.ts write)'
+      : action === 'vitest-snapshot-write' ? 'snapshot update'
+      : action === 'jest-snapshot-write' ? 'snapshot update'
+      : 'mutating invocation'
     return {
-      user: `Blocked direct ${tool}. Run it through ${JUST_RECIPES_POINTER} instead; it carries the same arguments and runs through the gate profile.`,
+      user: `Blocked ${tool} (${actionLabel}). Run it through ${JUST_RECIPES_POINTER} instead; it carries the same arguments and runs through the gate profile.`,
       agent:
-        `DENIED direct ${tool}. Do not invoke ${tool} from Bash/Shell, including through sh -c, xargs, find -exec, or command substitution. ` +
+        `DENIED ${tool} (${actionLabel}). Do not invoke ${tool} from Bash/Shell, including through sh -c, xargs, find -exec, or command substitution. ` +
         `Run it through ${JUST_RECIPES_POINTER} instead - the recipe carries the same arguments and runs the gate profile rather than skipping it. ` +
-        '--help and --version remain allowed (they print text and run nothing), ' +
-        'and invoking the tool from inside a `just` recipe body is allowed because the gate runs at the recipe boundary. ' +
+        'Read-only invocations of the same tool (lint, typecheck, test runs without snapshot updates) are permitted. ' +
         `Blocked command: ${ctx.snippet}`,
     }
   },
   corpus: {
+    // The mutating invocations — the only ones `match()` returns a Finding
+    // for. 6 entries; the az388 corpus floor in tests/unit/rules-corpus-floors.test.ts
+    // was lowered from 15 to 6 on 2026-10-13 (az365 Scope A) and the file
+    // header explains why.
     deny: [
+      'biome format packages/desktop/src --write',
+      'biome format --write packages/desktop/src',
+      'biome format --write src/foo.ts',
+      // Concatenated short-flag form: the shell hands the matcher a
+      // single `-wX` token; the predicate's prefix check catches it.
+      'biome format src/foo.ts -w',
+      'vitest run -u',
+      'vitest run --update',
+      // Concatenated form: the shell hands the matcher a single `-uX`
+      // token; the predicate's prefix check catches it. The corpus entry
+      // is the value the shell actually produces (`-uX`); vitest does
+      // not combine `-u` with other short flags, but the matcher has
+      // to handle the form anyway.
+      'vitest run -uX',
+      // `=`-form: `--update=now` arrives as a single token, predicate
+      // catches via `startsWith('--update=')`.
+      'vitest run --update=now',
+      'tsc src/foo.ts',
+      // jest's snapshot-mutation flag form; covers the jest branch of
+      // match() and the jest action label in message(). The flag is
+      // either `-u` or `--updateSnapshot`; both must be denied.
+      'jest -u',
+      'jest --updateSnapshot',
+      'jest -uX',
+    ],
+    // The read-only invocations — every one `match()` returns null for.
+    // The 14 the OLD corpus mis-classified as denied move here as the
+    // audit-trail entry that pins "this is a read, the deny is over-broad
+    // and a future narrowing should permit it" — the future narrowing is
+    // THIS rule's match(), already implemented; these entries are the
+    // proof the test suite pins against.
+    allow: [
       'npx biome check packages/desktop/src',
+      'npx vitest run',
+      'npx tsc --noEmit',
       'vitest run',
       'vitest --coverage run',
       'jest --testPathPattern=adl-conversation',
+      'biome check packages/desktop/src',
       'biome lint packages/desktop/src',
-      'biome format packages/desktop/src --write',
       'tsc --noEmit',
       'tsc -p tsconfig.json',
       'xargs npx tsc --noEmit',
@@ -56,12 +274,13 @@ export const toolFrontend: RuleSpec = {
       "sh -c 'npx tsc --noEmit'",
       "bash -lc 'npx tsc --noEmit'",
       'echo $(biome lint src/)',
-      // Not help-only: isHelpOrVersionOnly requires EVERY token to be a
-      // help/version flag, and 'lint'/'--noEmit' are real arguments.
+      // The two help-only entries are already short-circuited by
+      // isHelpOrVersionOnly at classification time; they never reach
+      // `match()`. Listed under `allow` for the same audit-trail reason
+      // as the reads above: chosen behaviour, not merely a passing test.
       'biome lint --help',
       'tsc --noEmit --help',
-    ],
-    allow: [
+      // Pre-existing allow entries preserved.
       'npx --version',
       'vitest --version',
       'jest --version',

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

@@ -25,6 +25,7 @@ import type { AnyRuleSpec, RuleId } from './spec.ts'
 import { asAnyRuleSpec, corpusIsEmpty } from './spec.ts'
 
 import { gitHooksPath, gitCoreBare } from './impl/git-core.ts'
+import { adlGitUserOverrideBlock } from './impl/adl-git-user-override-block.ts'
 import { gitStash, gitClean, gitRebase, gitFilterBranch, gitRestore, gitReset, gitUpdateIndex } from './impl/git-transitions.ts'
 import { gitNoVerify, gitAmend } from './impl/git-verify.ts'
 import { gitProtectedTreeCommit } from './impl/git-protected-tree.ts'
@@ -63,7 +64,7 @@ import { adlPrCreateUpdateRole } from './impl/adl-pr-role.ts'
 import { adlPrReviewRole } from './impl/adl-pr-review-role.ts'
 import { adlPrCompletePendingDecision } from './impl/adl-pr-complete-pending.ts'
 import { adlWorkitemRequiresTarunOrVivek } from './impl/adl-workitem-role.ts'
-import { adlBuildRunDenied } from './impl/adl-build-run-denied.ts'
+import { adlBuildRunRole } from './impl/adl-build-run-role.ts'
 import { toolFind } from './impl/tool-find.ts'
 import { toolGrep } from './impl/tool-grep.ts'
 import { toolNativeSearch } from './impl/tool-native-search.ts'
@@ -85,6 +86,14 @@ import { agentTamperProtection } from './impl/agent-tamper-protection.ts'
 export const GIT_RULES: readonly AnyRuleSpec[] = [
   gitHooksPath,
   gitCoreBare,
+  // Right after the `core.*` override rules: a `user.*` override rides
+  // along with any subcommand via `-c user.*=`, exactly the way
+  // `core.hooksPath` / `core.bare` do — a `git -c user.name=human commit`
+  // / `push` should be reported as the user override, not whatever
+  // commit/push policy would otherwise report. The user's call (2026-10-12)
+  // is "no use of git -c user* at all … blanket ban for agents"; see
+  // CONTRIBUTING.md line 18 and INVARIANTS.md line 55.
+  adlGitUserOverrideBlock,
   gitStash,
   gitClean,
   gitRebase,
@@ -150,7 +159,7 @@ export const TOOL_RULES: readonly AnyRuleSpec[] = [
   adlPrReviewRole,
   adlPrCompletePendingDecision,
   adlWorkitemRequiresTarunOrVivek,
-  adlBuildRunDenied,
+  adlBuildRunRole,
 ].map(
   asAnyRuleSpec,
 )

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

@@ -869,7 +869,7 @@ export interface GitInvocationPiece {
 /**
  * One `adl mcp cli <command> …` invocation found while scanning a command,
  * paired with the effective identity for THAT specific piece. `command` is the gated command name
- * (e.g. `workitem-create-or-update`), lower-cased; `rest` is the dequoted
+ * (e.g. `workitem-create-or-update-pbi`), lower-cased; `rest` is the dequoted
  * values after it, the same shape `impl/adl-mcp-cli.ts`'s `adlMcpCliCall`
  * reads off `Invocation.args.slice(3)`, so a role rule can correlate a
  * specific `Invocation` to its own piece here by comparing values, exactly

package/packages/agent-hooks/src/rules/shell/invocation.ts

@@ -86,7 +86,19 @@ export type Invocation =
   | { readonly kind: 'azure-devops'; readonly args: readonly Token[] }
   | { readonly kind: 'find' }
   | { readonly kind: 'grep' }
-  | { readonly kind: 'frontend-tool'; readonly tool: string }
+  /**
+   * `npx`/`vitest`/`jest`/`biome`/`tsc` and their Windows spellings (the
+   * `.exe` variants, see `ClassifyConfig.frontendToolNames`). The
+   * `args` field carries the tokenized post-name argument list so
+   * `tool.frontend.match()` (and any future `tool.browser-automation`
+   * rule) can inspect flags — `--write` on `biome format`, `--noEmit`
+   * on `tsc`, `-u`/`--update` on `vitest run`, etc. — instead of
+   * denying every binary-name invocation regardless of effect. Threaded
+   * through by `walkToolCommand` below; the args are not consumed by
+   * `isHelpOrVersionOnly` (which has already run before this producer),
+   * they are what remains of the post-name token stream.
+   */
+  | { readonly kind: 'frontend-tool'; readonly tool: string; readonly args: readonly Token[] }
   /**
    * `bun test` (any arguments, including a file/pattern operand) — the
    * `test` subcommand specifically, after skipping bun's own `-C <dir>` /
@@ -638,7 +650,7 @@ function walkToolCommand(name: string, args: readonly Token[], cfg: ClassifyConf
     return [{ kind: 'azure-devops', args }]
   }
   if (cfg.cargoNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'cargo' }]
-  if (cfg.frontendToolNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'frontend-tool', tool: name }]
+  if (cfg.frontendToolNames.has(name)) return isHelpOrVersionOnly(args) ? [] : [{ kind: 'frontend-tool', tool: name, args }]
   if (cfg.bunNames.has(name)) return isBunTestSubcommand(args) ? [{ kind: 'bun-test' }] : null
   if (cfg.justNames.has(name)) return walkJustCommand(args)
   if (name === 'xargs' || name === 'xargs.exe') return xargsInvocation(args, walk)