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

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

@@ -0,0 +1,265 @@
+/**
+ * `git.worktree` — worktree policy (STATUS.md item 2, L2/L3;
+ * docs/operations/worktree-guard.md; docs/operations/agent-permissions.md "route, don't block").
+ *
+ * HARDCUT 2026-09-27 (Tarun, via the coordinator, on top of the earlier
+ * "deny every worktree action" hardcut this rule used to implement): the
+ * blanket deny-all is replaced by a ROUTE-when-possible, cap-aware policy:
+ *
+ *  - `git worktree list|remove|prune|repair` — ALLOW outright (`match`
+ *    returns `null`). These are needed to RECONCILE existing worktrees
+ *    (docs/operations/worktree-guard.md L6, and this cap's own remove hint), and none
+ *    of them creates a new checkout, so none of them can push a repository
+ *    over the 3-checkout cap.
+ *  - `git worktree add` — the task instruction for this change describes a
+ *    silent REWRITE to `adl worktree add …` (`updatedInput` +
+ *    `permissionDecision: allow`, "the same mechanism other adl rewrite
+ *    rules use"). That mechanism DOES NOT EXIST in this engine — verified,
+ *    not assumed: `Severity` (`../spec.ts`) is only `'deny' | 'advise'`;
+ *    `Decision`/`Finding` carry no replacement-command field anywhere in
+ *    `../engine.ts`; `HostSpec.Decision` (`../../hosts/spec.ts`) has
+ *    `verdict: 'allow' | 'deny' | 'ask'` plus `reason`/`agentMessage`
+ *    strings only, and every `renderDecision` (`../../hosts/impl/{claude,
+ *    codex,kimi,opencode}.ts`) renders exactly that shape — none of them
+ *    ever emits `updatedInput`. A repo-wide grep for `updatedInput` finds
+ *    exactly one subsystem that does this at all: `../../hooks/lean-ctx/
+ *    scope-rewrite.ts`, a DIFFERENT hook (`lean-ctx hook rewrite`) with its
+ *    own envelope, unrelated to `adl hook`'s `pre-tool-use` engine this
+ *    rule runs in. Building real rewrite support means extending
+ *    `Severity`/`Finding`/`Decision`/`HostSpec` and all four host adapters —
+ *    files this rule's write scope does not include (git-worktree.ts + its
+ *    tests/fixtures/README only). Reported as a blocker rather than faked;
+ *    see this task's final report for the flag. Until that engine work
+ *    lands, `add` gets the fallback docs/operations/agent-permissions.md's own
+ *    Principles section already names for this exact situation: "An
+ *    inexact rewrite is a deny with the `adl` command to use. The hook
+ *    never guesses." — DENY, with the precise `adl worktree add` command to
+ *    run instead.
+ *  - `git worktree move|lock|unlock` — still DENIED: each mutates a
+ *    worktree's registration or lock state without checking the cap or
+ *    reconciling anything, and none is needed to reconcile toward the cap
+ *    (unlike list/remove/prune/repair above).
+ *  - Any other/unrecognized `worktree` subcommand (bare `git worktree`,
+ *    `--help`, …) stays DENIED — fail-closed default, unchanged from the
+ *    old blanket policy.
+ *  - Claude's `EnterWorktree` tool and `Task`/`Agent` launched with
+ *    `isolation: "worktree"` cannot be rewritten either (there is no
+ *    replacement TOOL CALL to substitute, only a replacement shell command —
+ *    even a working rewrite mechanism would not help here). Neither can be
+ *    routed through `list`/`remove` the way `add` can, so instead of a flat
+ *    deny this rule now counts the session's cwd repo's worktrees itself
+ *    (`worktreeCountForCwd`, real `git worktree list --porcelain`, scoped to
+ *    `process.cwd()` — the pre-tool-use hook process's own cwd IS the
+ *    session's cwd, since the host spawns it there) and ALLOWS below the
+ *    cap, DENIES at or above it with the same limit wording `add`'s deny and
+ *    `adl worktree add`/`bin/git` use. The count is FAIL-CLOSED: a `git
+ *    worktree list` that errors (not a repo, git missing, …) denies rather
+ *    than guessing "must be fine".
+ *
+ * `MAX_WORKTREES = 3` is kept as a local literal, not imported from
+ * `packages/repo-controls/src/constants.ts` (the value this task's CLI step
+ * does import) — this rule is loaded into `BUILTIN_RULES` at process start
+ * for every hook invocation in this package, and a new cross-package import
+ * here is a materially different tradeoff (a security-critical, always-on
+ * hot path) than the CLI's own opt-in command. If `MAX_WORKTREES` ever
+ * changes, update it here, in `packages/repo-controls/src/constants.ts`, and
+ * in `apps/cli`'s copy — all three are load-bearing.
+ *
+ * The shell-side classification (`-C`, `-c`, env-prefix, chained commands,
+ * dynamic-token fail-closed, aliasing, …) is entirely UNCHANGED — it comes
+ * from `../shell/invocation.ts`'s classifier, which this rule does not
+ * touch. A chained `git status && git worktree add ../wt` is decomposed by
+ * that classifier into separate invocations before `match()` ever runs, so
+ * the `add` half is still denied on its own — this rule has no separate
+ * "chain" branch to add, unlike a true rewrite would have needed (a
+ * rewrite can only safely replace a chain's `git worktree add` segment when
+ * the rest of the chain is inert; a deny has no such constraint, since it
+ * already tells the agent to re-run the command itself).
+ */
+
+import { execFileSync } from 'node:child_process'
+import { tokenValue, type Token } from '../shell/token.ts'
+import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { gitAgentTail } from './messages.ts'
+
+const SUBAGENT_LAUNCH_TOOLS: ReadonlySet<string> = new Set(['Task', 'Agent'])
+
+/** Kept in sync by hand with repo-controls' and the CLI's copies — see this file's header. */
+const MAX_WORKTREES = 3
+
+/** Subcommands that reconcile toward the cap rather than create a checkout — safe to allow outright. */
+const ALWAYS_ALLOWED_SUBCOMMANDS: ReadonlySet<string> = new Set(['list', 'remove', 'prune', 'repair'])
+
+/** Subcommands that mutate worktree state but neither create a checkout nor help reconcile toward the cap. */
+const STILL_DENIED_SUBCOMMANDS: ReadonlySet<string> = new Set(['move', 'lock', 'unlock'])
+
+/** The first non-flag token in `git worktree <this>` — e.g. `add`, `list`, `remove` — or `null` when there isn't one (`git worktree` alone). */
+function worktreeSubcommand(rest: readonly Token[]): string | null {
+  for (const token of rest) {
+    const value = tokenValue(token)
+    if (!value.startsWith('-')) return value
+  }
+  return null
+}
+
+/**
+ * `git worktree list --porcelain` in the CURRENT process cwd (the
+ * pre-tool-use hook's own cwd, which is the session's cwd — this rule has
+ * no other way to learn "the session's cwd repo" for a tool-call, since
+ * `RuleContext`'s `RepoIndexPort` (`../ports.ts`) exposes only
+ * `stagedPaths`/`trackedModifiedPaths`, not a general git runner or a root
+ * path, and extending it is out of this file's write scope). Counts
+ * `worktree ` porcelain header lines, main worktree included. Returns
+ * `null` on any failure (not a repo, git missing, timeout, …) — the caller
+ * treats `null` as "cannot determine", which fails closed (deny), never
+ * "assume it's fine".
+ */
+function worktreeCountForCwd(): number | null {
+  try {
+    const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return out.split('\n').filter((line) => line.startsWith('worktree ')).length
+  } catch {
+    return null
+  }
+}
+
+/** The shared header/footer wording `adl worktree add` and `bin/git` also use for the cap refusal (kept in sync by eye — see this file's header). */
+function worktreeCapMessage(extra: string): string {
+  return (
+    `worktree limit: only a maximum of ${MAX_WORKTREES} worktrees per repo is allowed (including the main folder). ` +
+    `Reconcile old worktrees first: run \`adl worktree list\` to see them with branch/clean/merged status, then ` +
+    `\`git worktree remove <path>\` (or ask the human). ${extra}`
+  )
+}
+
+export const gitWorktree: RuleSpec = {
+  id: 'git.worktree',
+  category: 'git',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Allow worktree reconciliation (list/remove/prune/repair) and cap-aware add/tool-call handling; deny move/lock/unlock and anything over the 3-checkout cap.',
+  params: noParams,
+  match(inv): Finding | null {
+    if (inv.kind === 'git') {
+      if (inv.subcommand !== 'worktree') return null
+
+      const subcommand = worktreeSubcommand(inv.rest)
+      if (subcommand !== null && ALWAYS_ALLOWED_SUBCOMMANDS.has(subcommand)) return null // ALLOW: reconciliation
+
+      if (subcommand === 'add') {
+        return { ruleId: 'git.worktree', severity: 'deny', detail: { surface: 'add' } }
+      }
+      if (subcommand !== null && STILL_DENIED_SUBCOMMANDS.has(subcommand)) {
+        return { ruleId: 'git.worktree', severity: 'deny', detail: { surface: 'mutate', subcommand } }
+      }
+      // Bare `git worktree`, `--help`, or an unrecognized subcommand: unchanged fail-closed default.
+      return { ruleId: 'git.worktree', severity: 'deny', detail: { surface: 'other' } }
+    }
+
+    if (inv.kind === 'tool-call') {
+      const isEnterWorktree = inv.tool === 'EnterWorktree'
+      const isWorktreeIsolation = SUBAGENT_LAUNCH_TOOLS.has(inv.tool) && inv.input.isolation === 'worktree'
+      if (!isEnterWorktree && !isWorktreeIsolation) return null
+
+      const count = worktreeCountForCwd()
+      if (count === null) {
+        return { ruleId: 'git.worktree', severity: 'deny', detail: { surface: 'tool-cap-unknown', tool: inv.tool } }
+      }
+      if (count < MAX_WORKTREES) return null // ALLOW: below the cap
+
+      return { ruleId: 'git.worktree', severity: 'deny', detail: { surface: 'tool-cap', tool: inv.tool, count: String(count) } }
+    }
+
+    return null
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const surface = finding.detail.surface as string
+
+    if (surface === 'add') {
+      const user = worktreeCapMessage('Ask the human to run it, or use `adl worktree add` instead of raw git.')
+      return {
+        user,
+        agent:
+          `DENIED git worktree add. There is no automatic rewrite for this command yet — run the equivalent ` +
+          `\`adl worktree add\` command instead (same arguments; put \`-C <dir>\` right after \`add\` if you used ` +
+          `\`-C\` here). ${worktreeCapMessage('adl worktree add refuses at the same cap and explains why.')} ` +
+          gitAgentTail(ctx.snippet),
+      }
+    }
+
+    if (surface === 'mutate') {
+      const subcommand = finding.detail.subcommand as string
+      const user = `Blocked git worktree ${subcommand}. This mutates a worktree's registration or lock state without checking the checkout cap, and is reserved for direct human use.`
+      return {
+        user,
+        agent:
+          `DENIED git worktree ${subcommand}. Unlike list/remove/prune/repair, this does not help reconcile toward ` +
+          `the 3-checkout cap and is reserved for direct human use. ${gitAgentTail(ctx.snippet)}`,
+      }
+    }
+
+    if (surface === 'tool-cap-unknown') {
+      const tool = finding.detail.tool as string
+      return {
+        user: `Blocked ${tool}. The current worktree count could not be determined, so this is refused rather than assumed safe.`,
+        agent:
+          `DENIED ${tool}. \`git worktree list --porcelain\` could not be read from this session's cwd, so the ` +
+          `worktree count is unknown — failing closed rather than assuming it is under the cap. Run \`adl worktree ` +
+          `list\` yourself to see what is wrong, or ask the human. Blocked tool call: ${ctx.snippet}`,
+      }
+    }
+
+    if (surface === 'tool-cap') {
+      const tool = finding.detail.tool as string
+      const count = finding.detail.count as string
+      return {
+        user: `Blocked ${tool}. ${worktreeCapMessage(`This repository already has ${count}.`)}`,
+        agent:
+          `DENIED ${tool}. ${worktreeCapMessage(`This repository already has ${count}.`)} Blocked tool call: ${ctx.snippet}`,
+      }
+    }
+
+    // surface === 'other': bare `git worktree`, `--help`, or an unrecognized subcommand.
+    return {
+      user: 'Blocked git worktree. This form is reserved for direct human use because it manages or exposes secondary checkouts outside the current working tree.',
+      agent:
+        'DENIED git worktree. This form is reserved for direct human use because it manages or exposes secondary checkouts outside the current working tree. ' +
+        `Use \`git worktree list\`, \`git worktree remove <path>\`, \`git worktree prune\`, or \`git worktree repair\` to reconcile — those are allowed. ${gitAgentTail(ctx.snippet)}`,
+    }
+  },
+  corpus: {
+    deny: [
+      'git worktree',
+      'git worktree --help',
+      'git worktree add ../wt',
+      'git worktree move ../wt ../moved',
+      'git worktree lock ../wt',
+      'git worktree unlock ../wt',
+    ],
+    allow: [
+      // Decided behaviour change (Tarun, 2026-09-27, via the coordinator):
+      // these four used to be denied by the old blanket "deny every
+      // worktree action" policy — see git-worktree.test.ts's own comment on
+      // the equivalent old assertions this replaces. They are needed to
+      // RECONCILE toward the 3-checkout cap (docs/operations/worktree-guard.md L6) and
+      // create no new checkout, so they are allowed outright now.
+      'git worktree list',
+      'git worktree remove ../wt',
+      'git worktree remove --force ../wt',
+      'git worktree prune',
+      'git worktree prune --dry-run',
+      'git worktree repair',
+      'git status',
+      'git branch --list',
+      'git help worktree',
+      'orca worktree ps --json',
+      'echo git worktree list',
+    ],
+  },
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Every azdo MCP tool name any rule in this package matches by name
+ * (`packages/azdo/src/mcp-server.ts`'s full roster) — the fixed fallback set
+ * `mcpToolName` matches an UNPREFIXED tool name against (see that
+ * function's own doc for why).
+ */
+export const KNOWN_MCP_TOOL_NAMES: ReadonlySet<string> = new Set([
+  'pr_list_or_get',
+  'pr_create_or_update',
+  'pr_review',
+  'build_list_or_get',
+  'build_run',
+  'workitem_list_or_get',
+  'workitem_create_or_update',
+])
+
+/**
+ * `tool` ending in `<separator><suffix>` for one of `knownSuffixes`
+ * (`_`/`.`/`:`), with a non-empty prefix before the separator — that prefix
+ * is the "server" part, whatever it is named; this never inspects it,
+ * matching `mcpToolName`'s own "deliberately not gated on the server key"
+ * discipline. Returns the matched suffix, or null when none match. Shared by
+ * `mcpToolName` (below) and `../pre-tool-use/handler.ts`'s
+ * `classifyCommandTool`, so the separator shapes cannot drift between the
+ * two call sites that need them.
+ */
+export function toolNameEndingWithKnownSuffix(tool: string, knownSuffixes: ReadonlySet<string>): string | null {
+  for (const suffix of knownSuffixes) {
+    for (const separator of ['_', '.', ':'] as const) {
+      const marker = `${separator}${suffix}`
+      if (tool.length > marker.length && tool.endsWith(marker)) return suffix
+    }
+  }
+  return null
+}
+
+/**
+ * The tool name off the end of an MCP tool call `mcp__<prefix>__<tool>`, or
+ * null when `tool` is not MCP-shaped at all.
+ *
+ * Deliberately NOT gated on the server key naming Azure DevOps: the package
+ * is `packages/azdo`, a host may register it as `mcp__azdo__...`, and P4's
+ * plan folds the server under `adl` (`mcp__adl__...`) — a substring check on
+ * "azure-devops" would miss both. This returns whatever sits after the LAST
+ * `__`, and callers check that against their own tool-name allowlist. Also
+ * transparently covers Claude Code's plugin-scoped tool names,
+ * `mcp__plugin_<plugin>_<server>__<tool>` — its extra `plugin_<plugin>_<server>`
+ * segment has no further `__` in it, so the last-`__` split still lands
+ * exactly on `<tool>`.
+ *
+ * Shared by every rule that gates an Azure DevOps MCP tool by name
+ * (adl-session-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
+ * between them.
+ *
+ * WIDENED 2026-09-28 (STATUS.md 12p, W2 build item
+ * 4): 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 call an azdo tool with no
+ * `mcp__` prefix at all, spelled `<server>_<tool>` / `<server>.<tool>` /
+ * `<server>:<tool>`. When `tool` carries no `mcp__` prefix, this falls back
+ * to matching it against the FIXED azdo tool roster
+ * (`KNOWN_MCP_TOOL_NAMES`) under those three separators, defensively —
+ * ASSUMPTION, not a confirmed host contract; see `classifyCommandTool`'s own
+ * identical fallback for the lean-ctx shell tools.
+ */
+export function mcpToolName(tool: string): string | null {
+  const prefix = 'mcp__'
+  if (tool.startsWith(prefix)) {
+    const rest = tool.slice(prefix.length)
+    if (rest.length === 0) return null
+    const lastSeparator = rest.lastIndexOf('__')
+    return lastSeparator < 0 ? rest : rest.slice(lastSeparator + 2)
+  }
+  return toolNameEndingWithKnownSuffix(tool, KNOWN_MCP_TOOL_NAMES)
+}

package/packages/agent-hooks/src/rules/impl/messages.ts

@@ -0,0 +1,128 @@
+/**
+ * Message text shared by several rules.
+ *
+ * Ported from `.agents/hooks/pre-tool-use/src/deny.mjs`. Most git policy
+ * rules (stash, clean/rebase/filter-branch, restore, reset, update-index,
+ * --amend, branch -D, tag -d, switch -f, worktree remove --force,
+ * update-ref -d, gc --prune, checkout --) fell through `classifyReason`'s
+ * `default:` arm there and therefore shared one message, parameterized only
+ * by the `reason` prose. `defaultGitMessage` is that shared text, kept in
+ * one place rather than copied into eleven `message()` functions.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Finding, RuleMessage } from '../spec.ts'
+
+/**
+ * Read one string field out of a Finding's detail.
+ *
+ * `noUncheckedIndexedAccess` makes every `Record` lookup `T | undefined`
+ * even though a rule's own `match()` always sets the fields its `message()`
+ * reads — the two are written together, in the same file. This is the one
+ * place that fact is asserted, instead of forty optional-chaining call
+ * sites each silently tolerating a missing key they can never actually see.
+ */
+export function detailString(finding: Finding, key: string): string {
+  const value = finding.detail[key]
+  if (typeof value !== 'string') throw new Error(`finding '${finding.ruleId}' is missing string detail '${key}'`)
+  return value
+}
+
+/**
+ * Appended to EVERY git-related agent deny message (via `gitAgentTail`).
+ *
+ * Incident: a wrongly denied `git rebase --abort` was treated as an obstacle
+ * to route around — the agent rebuilt state by hand with `update-ref`,
+ * `symbolic-ref`, `read-tree` and by trashing `.git/rebase-merge`, which is
+ * far riskier than the command it was denied. A git denial must say plainly
+ * that there is no sanctioned workaround, name the recovery commands that
+ * ARE allowed, and otherwise send the agent back to the user.
+ */
+export const GIT_NO_WORKAROUND_GUIDANCE =
+  'Do NOT work around this block: no git plumbing (update-ref, symbolic-ref, read-tree, update-index, ' +
+  'reflog, replace, prune) and no editing, moving, copying over, or deleting anything under .git. If you ' +
+  'are stuck in an in-progress rebase/merge/cherry-pick/revert/am and a recovery command is what is ' +
+  'needed, run it - `git rebase --abort`, `git merge --abort`, `git cherry-pick --abort`, ' +
+  '`git revert --abort`, `git am --abort` (or `--quit`) are allowed. Otherwise STOP and ask the user how ' +
+  'to proceed.'
+
+/** The shared ending of every git-related agent deny message: the no-workaround guidance, then the blocked command. */
+export function gitAgentTail(snippet: string): string {
+  return `${GIT_NO_WORKAROUND_GUIDANCE} Blocked command: ${snippet}`
+}
+
+export function defaultGitMessage(reason: string, snippet: string): RuleMessage {
+  return {
+    user: `Blocked ${reason}. This git operation can discard or irreversibly rewrite work in a shared checkout. Run it yourself in a terminal if you really mean it.`,
+    agent:
+      `DENIED ${reason}. This git operation is blocked for agents in this shared checkout - it can discard, ` +
+      `hide, or irreversibly rewrite work. Read-only inspection (git status, git log, git diff, git stash ` +
+      `list) is always fine. If the human explicitly asked for this exact command, tell them to run it ` +
+      `themselves in their own terminal - this hook still blocks you. ${gitAgentTail(snippet)}`,
+  }
+}
+
+export function protectedTreesText(protectedTrees: readonly string[]): string {
+  return protectedTrees.join(', ')
+}
+
+/**
+ * The generic "use just recipes" pointer, shared by every rule that denies a
+ * direct tool invocation in favour of a `just` recipe (tool.cargo,
+ * tool.frontend, tool.bun-test, tool.chmod-hook-disarm).
+ *
+ * Tarun's decision (2026-09-27, feature az372), verbatim: "ban 'bun test'
+ * only and ask to run just recipes. Do not mention any particular recipe
+ * name. Same for deny rule on just frontend type check. Any debt should not
+ * mention a particular recipe name. Just deny with use just recipes.
+ * Generic!" A message that names a specific recipe (`just frontend
+ * typecheck`, `just test-affected`, `just hooks install`, ...) goes stale
+ * the moment the justfile is restructured; `just --list` never does. Every
+ * such message was ported to this one pointer instead of naming a recipe —
+ * see tests/unit/rules-no-concrete-recipe-name.test.ts, which scans every
+ * registered rule's rendered messages for a leftover concrete `just <word>`
+ * mention.
+ */
+export const JUST_RECIPES_POINTER = "the repository's just recipes (`just --list` shows them)"
+
+/**
+ * Read the live backend coverage floor, if this checkout has one.
+ *
+ * Ported from deny.mjs's `coverageAdvisory`. Real filesystem, walking up from
+ * `startDir` — no mock, since the whole point is the real ratchet file. A
+ * checkout with no such file (most of them) returns ''.
+ */
+export function coverageAdvisory(startDir: string): string {
+  const REL = 'workflows/config/coverage/coverage.json'
+  let dir = startDir
+  let found = ''
+  for (;;) {
+    const candidate = dir.endsWith('/') ? dir + REL : `${dir}/${REL}`
+    if (existsSync(candidate)) {
+      found = candidate
+      break
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  if (!found) return ''
+  try {
+    const config = JSON.parse(readFileSync(found, 'utf8')) as {
+      modules?: { backend?: { baseline?: { lines?: unknown }; crateBaseline?: { lines?: unknown } } }
+    }
+    const backend = config.modules?.backend ?? {}
+    const workspace = backend.baseline?.lines
+    const perCrate = backend.crateBaseline?.lines
+    if (typeof workspace !== 'number' || typeof perCrate !== 'number') return ''
+    return (
+      ` Advisory: backend coverage may not fall below ${workspace}% workspace-wide or ` +
+      `${perCrate}% for a crate, and sync-coverage-baseline.sh only ever ratchets those ` +
+      'floors upward - a change that adds code without tests moves you toward that floor, ' +
+      'not away from it.'
+    )
+  } catch {
+    return ''
+  }
+}

package/packages/agent-hooks/src/rules/impl/parse-uncertain.ts

@@ -0,0 +1,143 @@
+/**
+ * Fail-closed parse rule: an invocation the shell parser could not classify.
+ *
+ * Ported from every `uncertain(reason)` call in shell/{token,substitution,
+ * split,xargs,invocation}.ts, and from `classifyReason`'s
+ * `/^(?:invalid|empty|missing|unparsed|unclosed|unterminated|dynamic|shell
+ * script|hook input)/` case in deny.mjs:139-141. The original produced ~19
+ * distinct reason strings from that many distinct parse failures — a
+ * dynamic command name, an unclosed substitution or quote, an unterminated
+ * here-document, an unparsed xargs option, a shell script that is not
+ * trusted, and so on — but `classifyReason`/`userMessageFor`/
+ * `agentMessageFor` always treated every one of them identically: one
+ * message, `reason` interpolated into it. Splitting that into ~19 RuleSpecs
+ * would mean ~19 copies of the same `match`/`message` pair, distinguished
+ * only by which reason string happened to appear — no behavioural
+ * difference, and each still needs the SAME `unsafeAllowUncertain` gate
+ * (config/schema.ts's `RulesSection`). This is deliberately one rule
+ * instead; its corpus below pins a representative command for each of the
+ * ~19 distinct reason-producing code paths, so the consolidation costs no
+ * coverage.
+ */
+
+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'
+
+export const parseUncertain: RuleSpec = {
+  id: 'parse.uncertain',
+  category: 'uncertain',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Fail closed on shell input the parser could not classify.',
+  params: noParams,
+  match(inv: Invocation): Finding | null {
+    if (inv.kind !== 'uncertain') return null
+    return { ruleId: 'parse.uncertain', severity: 'deny', detail: { reason: inv.reason } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const reason = detailString(finding, 'reason')
+    return {
+      user: `Blocked uninspectable shell input (${reason}). The hook fails closed; simplify the command and retry.`,
+      agent: `DENIED ${reason}. The hook cannot prove that this shell input is safe. Remove the dynamic or unparsed shell construct and retry. Blocked command: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [
+      // dynamic shell command / dynamic git subcommand / missing subcommand
+      'git "$SUBCOMMAND"',
+      'git',
+      // dynamic shell script / shell script execution (untrusted path)
+      'bash /tmp/install.sh',
+      'bash "$SCRIPT"',
+      'bash /Users/tarunrana/Documents/Repos/adl-maintenance-checkout/workflows/scripts/gates/rust/check-rust-policy.sh',
+      'bash workflows/scripts/../../../etc/passwd',
+      'bash workflows/scripts/gates/rust/../../../../etc/passwd',
+      'bash workflows/scriptsxrust/check-rust-policy.sh',
+      'bash workflows/other/check.sh',
+      'bash .code-quality/../../../etc/passwd',
+      'bash .code-quality/typescript/../../../../etc/passwd',
+      'bash /etc/.code-quality/evil.sh',
+      'bash .code-qualityx/typescript/scan.sh',
+      'bash .agentsx/hooks/setup.sh',
+      'bash .agents/hooks/../../etc/evil.sh',
+      'bash /Users/x/.agents/hooks/setup.sh',
+      'bash .agents/hooks/',
+      'bash .code-quality/',
+      // dynamic `.`/eval/source execution
+      'eval "$COMMAND"',
+      // dynamic shell command, reached by recursing into a `-c` argument
+      // that is itself a bare, unresolved variable
+      'sh -c "$COMMAND"',
+      // unparsed unquoted here-document (no quote around the terminator)
+      'cat <<EOF\nrm -rf dist\nEOF',
+      // The remaining reasons below have no counterpart in the original
+      // self-test corpus at all — they are genuinely malformed input no
+      // legitimate command produces, so nothing in tests/self-test.mjs
+      // exercises them either. Added here (and unit-tested directly in
+      // shell-substitution.test.ts / shell-xargs.test.ts) so the
+      // consolidation into one rule still costs no coverage.
+      'echo $(unclosed', // unclosed shell substitution
+      'echo `unclosed', // unclosed backtick substitution
+      'echo "unclosed', // unclosed shell quote
+      "cat <<'EOF'\nbody", // unterminated here-document (quoted terminator, never closed)
+      'xargs -n', // incomplete xargs option
+      'xargs --not-a-real-option rm -rf x', // unparsed xargs option
+      'xargs $(cmd)', // dynamic xargs execution (bare, no options read first)
+      'xargs -0 $(safe-thing)', // dynamic xargs execution (after a real flag)
+      "xargs sh <<'EOF'\nfoo\nEOF", // dynamic xargs execution (shell over here-document input)
+      'bash <<EOF\necho hi\nEOF', // unparsed unquoted here-document fed to a shell
+      'bash <<< "$CMD"', // dynamic here-string
+      "cat <<'EOF' | tee /dev/null | bash\necho hi\nEOF", // here-document piped to shell
+      'bash < script.sh', // shell script execution (stdin from a file)
+      'tee $(pwd)/out.txt', // dynamic write target
+      'cp a `pwd`/b', // dynamic write target
+      'dd if=a of=$(pwd)/b', // dynamic write target
+      'cat install.sh | bash', // script piped to shell (producer output unknowable)
+      'git show HEAD:script.sh | sh', // script piped to shell
+      'echo "$CMD" | bash', // script piped to shell (echo with an expansion)
+      'echo x.sh | xargs bash', // dynamic xargs execution (input items become script operands)
+      'let x=1<<2', // unterminated here-document: bash reads an unquoted let `<<` as a here-document
+      // A `-c` script inherits the outer pipe's stdin: a bare shell (or
+      // `exec <shell>`) as the `-c` payload reading that stdin, fed by an
+      // unknowable local producer, fails closed exactly like the top-level
+      // `producer | shell` form.
+      "cat f | bash -c 'bash'",
+      "cat f | sh -c 'exec sh'",
+      "cat f | bash -c 'bash -s'",
+      "git show HEAD:script.sh | bash -c 'bash'",
+      'cat f | busybox sh', // a shell multi-call binary threads the outer feed the same way
+      // `source`/`.`/`eval` are unconditionally uncertain (dynamic-execution
+      // fail-closed), whether piped directly or nested in a `-c` script.
+      'cat f | source /dev/stdin',
+      'cat f | . /dev/stdin',
+      "cat f | bash -c 'source /dev/stdin'",
+      "cat f | bash -c '. /dev/stdin'",
+      "cat f | bash -c 'eval \"$(cat)\"'",
+    ],
+    allow: [
+      'timeout 90 git status',
+      "sh -c 'echo hi'",
+      'bash .agents/hooks/setup.sh',
+      './.agents/hooks/setup.sh',
+      "bash .agents/hooks/adl-code-quality scan --language typescript --filter '^raw-interactive-html$'",
+      "bash <<'EOF'\necho hi\nEOF",
+      "bash <<< 'echo hi'",
+      "cat <<'EOF' | bash\necho hi\nEOF",
+      'tee $HOME/out.txt',
+      'cp $(ls a) dest',
+      "echo 'echo hi' | bash", // static echo reconstructed and walked
+      "printf '%s\\n' 'echo hi' | sh", // static printf reconstructed and walked
+      'echo $((1<<2))', // arithmetic shift, not a here-document
+      '(( x = 1 << 2 ))', // arithmetic command shift
+      '[[ 1 -lt 2 ]]',
+      'echo "a<<b"', // quoted `<<` is literal text
+      // A `-c` script that does not read stdin as code ignores the outer
+      // pipe's content entirely, same as a bare `-c` script does.
+      "cat f | bash -c 'wc -l'",
+      "echo hi | bash -c 'read x; echo $x'",
+      "cat f | busybox echo hi",
+    ],
+  },
+}

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

@@ -0,0 +1,35 @@
+/**
+ * "Setting auto-complete" on an existing PR — docs/operations/agent-permissions.md row 9
+ * ("PR complete / set auto-complete") — shared by adl-pr-role.ts (which steps
+ * aside for this shape) and adl-pr-complete-pending.ts (which denies it).
+ *
+ * DECISION (this rule's scope, since row 9 is marked OPEN in the matrix and
+ * the tool has no dedicated "complete" action to key off): a `create` call
+ * always arms auto-complete BY DEFAULT unless the caller explicitly opts out
+ * (`packages/azdo/src/azdo-pr.ts`: "owner decision 2026-09-15: every PR is
+ * auto-complete" — `arm = args.autoComplete !== false`). Denying that default
+ * would block PR creation entirely for `agent-reviewer` too, which
+ * contradicts row 5's ALLOW and would break the one path the whole adl flow
+ * depends on. "PR complete" is read narrowly instead: an `update` call that
+ * explicitly touches completion — `autoComplete`, `mergeStrategy`, or
+ * `deleteSourceBranch` present in the input — which is exactly the "arm an
+ * EXISTING PR" shape `azdo-pr.ts`'s own `autoCompleteBody()` comment
+ * describes. A plain `create`, and a plain metadata-only `update` (title/
+ * description, no completion fields), are both untouched by row 9.
+ */
+
+export interface PrCreateOrUpdateInput {
+  readonly action?: unknown
+  readonly autoComplete?: unknown
+  readonly mergeStrategy?: unknown
+  readonly deleteSourceBranch?: unknown
+}
+
+const COMPLETION_FIELDS = ['autoComplete', 'mergeStrategy', 'deleteSourceBranch'] as const
+
+/** True for an `action: 'update'` call that also sets a completion field — see this file's header for why `create` is excluded. */
+export function isPrCompletionCall(input: Readonly<Record<string, unknown>>): boolean {
+  const args = input as PrCreateOrUpdateInput
+  if (args.action !== 'update') return false
+  return COMPLETION_FIELDS.some((field) => args[field] !== undefined)
+}