@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.26

package/packages/agent-hooks/src/log/adl-dir.ts

@@ -0,0 +1,44 @@
+/**
+ * The one place that makes a repository's `.adl/` folder self-ignoring.
+ *
+ * Every adl component that creates `<repo>/.adl/` (the `.adl/logs/` writer,
+ * `adl run`'s transcript, the crg background update, the git-hook log seam)
+ * calls `ensureAdlGitignore` right after it creates the directory. The file it
+ * writes, `.adl/.gitignore` containing exactly `*\n`, ignores the folder's whole
+ * content INCLUDING itself, so `.adl/` never shows in `git status` -- in any git
+ * repository, adl-controlled or not, without ever editing the repo's own
+ * `.gitignore` (the `/.adl/` block `adl repo controls install` writes covers
+ * controlled repos only). Logs carry commands and output, so they must not be
+ * committable by accident.
+ *
+ * `apps/cli` and `packages/repo-controls` import this module by relative path
+ * (as they already do `./writer.ts`), so there is exactly one copy.
+ */
+import { writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const ADL_DIR_NAME = ".adl";
+
+/** Exactly this content, nothing else: ignore every entry, this file included. */
+const ADL_GITIGNORE_CONTENT = "*\n";
+
+/**
+ * Finds the nearest `.adl` directory at or above `path` and, if it has no
+ * `.gitignore` yet, writes one containing `*\n`. An existing `.gitignore` is
+ * never overwritten or read. A `path` with no `.adl` segment (the
+ * `~/.local/state/adl/logs` fallback, a test tmp dir) is a no-op. The `.adl`
+ * directory must already exist; a missing one throws, like any other write.
+ */
+export function ensureAdlGitignore(path: string): void {
+  if (basename(path) !== ADL_DIR_NAME) {
+    const parent = dirname(path);
+    if (parent !== path) ensureAdlGitignore(parent);
+    return;
+  }
+  try {
+    // "wx": create only if absent -- an existing file is left untouched.
+    writeFileSync(join(path, ".gitignore"), ADL_GITIGNORE_CONTENT, { flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+}

package/packages/agent-hooks/src/log/writer.ts

@@ -2,7 +2,7 @@
  * The `.adl/logs/` logger (docs/architecture/cli-design.md §5a, item 9). `agent-hooks`
  * "holds logs" (§12): this module lives here and writes `hooks.log` /
  * `hooks-deny.log` (`../hooks/log.ts`); `apps/cli/src/log.ts` re-exports it
- * unchanged so `adl run`'s `tool-calls.log` writer keeps working. The module
+ * unchanged so `adl run`'s `agents/tool-calls.log` writer keeps working. The module
  * is generic across all five documented files so a caller never has to
  * reinvent the format.
  *
@@ -28,7 +28,8 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { ensureAdlGitignore } from "./adl-dir.ts";
 
 export type LogFileName = "hooks" | "hooks-deny" | "tool-rewrites" | "tool-calls" | "repo-controls";
 
@@ -128,9 +129,22 @@ function tightenMode(path: string, target: number): void {
 function ensureDirSecure(dir: string): void {
   const parent = dirname(dir);
   mkdirSync(parent, { recursive: true });
+  // A nested log stream such as `.adl/logs/agents/` must not leave the
+  // repository's `.adl/` ancestor at the default mkdir mode (0755).
+  // Root-level streams already tightened it as `parent`; locate it rather
+  // than changing unrelated ancestors of the state-directory fallback.
+  let ancestor = parent;
+  while (ancestor !== dirname(ancestor)) {
+    if (basename(ancestor) === ".adl") {
+      tightenMode(ancestor, 0o700);
+      break;
+    }
+    ancestor = dirname(ancestor);
+  }
   tightenMode(parent, 0o700);
   mkdirSync(dir, { recursive: true });
   tightenMode(dir, 0o700);
+  ensureAdlGitignore(dir);
 }
 
 function ensureFileSecure(filePath: string): void {

package/packages/agent-hooks/src/main.ts

@@ -7,11 +7,9 @@
  *
  *   adl hook <kind> [subcommand] --host=<claude|codex|cursor|kimi|opencode>
  *
- *   kinds: pre-tool-use, user-prompt-submit, briefing, crg <subcommand>,
- *          lean-ctx <subcommand>
+ *   kinds: pre-tool-use, user-prompt-submit, briefing, crg <subcommand>
  *   crg subcommands: after-file-edit, pre-commit, session-stop
- *   lean-ctx subcommands: mcp, pre-tool-use, post-tool-use
- *   payload: JSON on stdin (NOT for `lean-ctx mcp` — see below)
+ *   payload: JSON on stdin
  *   --version prints the package version and exits 0
  *
  * Operator commands (src/cli/; no --host, no stdin):
@@ -30,14 +28,6 @@
  *     loud (non-zero exit, reason on stderr) — never silently ignored.
  *   - `[hooks] enabled = false`: silent no-op, same as unmanaged.
  *
- * `lean-ctx mcp` is the one exception to this whole flow (work item A.1): it
- * takes no JSON payload, needs no `--host`, and never no-ops for an
- * unmanaged repo (an MCP client that just spawned it expects a running
- * server, not a silent exit) — see `src/lean-ctx/mcp.ts`'s header. It is
- * dispatched before `--host` resolution, before stdin is read at all, and
- * bypasses `HookHandler`/`HookResult` entirely (real stdio passthrough
- * cannot be buffered into a string).
- *
  * Every other hook kind is dispatched through the shared `HookHandler` shape
  * in `src/hooks/contract.ts` so a handler never touches `process`, argv, or
  * stdin directly.
@@ -49,7 +39,7 @@
  * the shared fail-closed signal `pre-tool-use`'s own decisions already use
  * (`FAIL_CLOSED_EXIT_CODE`, `src/rules/engine.ts`) for Kimi/OpenCode denials.
  * Every other kind is advisory or best-effort (`user-prompt-submit`,
- * `briefing`, `crg`, `lean-ctx` pre/post/mcp) and none of them has a "block"
+ * `briefing`, `crg`) and none of them has a "block"
  * concept at all — worse, on Claude Code and Codex, exit code 2 from
  * `UserPromptSubmit` specifically blocks the prompt AND ERASES IT (documented
  * Claude Code hook behaviour: a `UserPromptSubmit` hook exiting 2 shows
@@ -88,13 +78,11 @@ import { handlePreToolUse } from './pre-tool-use/handler.ts'
 import { handleUserPromptSubmit } from './hooks/user-prompt-submit/handler.ts'
 import { handleBriefing } from './hooks/briefing/handler.ts'
 import { handleCrg } from './hooks/crg/handler.ts'
-import { handleLeanCtx } from './hooks/lean-ctx/handler.ts'
-import { runLeanCtxMcp } from './lean-ctx/mcp.ts'
 import { runRules } from './cli/rules.ts'
 import { runDoctor } from './cli/doctor.ts'
 import { runLogged } from './hooks/log.ts'
 
-const HOOK_KINDS = ['pre-tool-use', 'user-prompt-submit', 'briefing', 'crg', 'lean-ctx'] as const
+const HOOK_KINDS = ['pre-tool-use', 'user-prompt-submit', 'briefing', 'crg'] as const
 type HookKind = (typeof HOOK_KINDS)[number]
 
 function isHookKind(value: string | undefined): value is HookKind {
@@ -102,14 +90,12 @@ function isHookKind(value: string | undefined): value is HookKind {
 }
 
 const CRG_SUBCOMMANDS = ['after-file-edit', 'pre-commit', 'session-stop'] as const
-const LEAN_CTX_SUBCOMMANDS = ['mcp', 'pre-tool-use', 'post-tool-use'] as const
 
 const HANDLERS: Readonly<Record<HookKind, HookHandler>> = {
   'pre-tool-use': handlePreToolUse,
   'user-prompt-submit': handleUserPromptSubmit,
   briefing: handleBriefing,
   crg: handleCrg,
-  'lean-ctx': handleLeanCtx,
 }
 
 /** Exit code `pre-tool-use` alone uses to fail closed on an undecidable payload — see this file's header (work item D). */
@@ -167,24 +153,6 @@ export async function run(argv: readonly string[]): Promise<number> {
     }
     subcommand = candidate
   }
-  if (kind === 'lean-ctx') {
-    const candidate = argv[1]
-    if (candidate === undefined || !(LEAN_CTX_SUBCOMMANDS as readonly string[]).includes(candidate)) {
-      process.stderr.write(
-        `adl hook: lean-ctx requires a subcommand (one of ${LEAN_CTX_SUBCOMMANDS.join(', ')})\n`,
-      )
-      return 1
-    }
-    subcommand = candidate
-  }
-
-  // `lean-ctx mcp` bypasses everything below: no --host, no stdin-as-JSON,
-  // no HookHandler dispatch, and unmanaged is NOT a no-op — see
-  // `./lean-ctx/mcp.ts`'s header and this file's own header (work item A.1).
-  if (kind === 'lean-ctx' && subcommand === 'mcp') {
-    return runLeanCtxMcp(process.cwd(), process.env)
-  }
-
   // az385: host resolution failure fails CLOSED (FAIL_CLOSED_EXIT_CODE, 2)
   // only for pre-tool-use — the one kind whose job is "block a dangerous
   // action," matching the invalid-JSON-on-stdin split a few lines below and
@@ -217,11 +185,9 @@ export async function run(argv: readonly string[]): Promise<number> {
   // `adl-config.toml` where `adl hooks deploy` has run — nowhere else. No
   // git root, or no `adl-config.toml` above `cwd`: a strict no-op (this
   // file's own header) — no rule evaluation, no identity check, no
-  // `hooks.log` write. This REVERSES the earlier "global identity baseline"
-  // (W2 build item 3 / STATUS.md 12p): that baseline
-  // ran the four (later seven, R2) identity rules even in an unmanaged
-  // repo; Tarun decided the repos where `adl-config.toml` does not exist
-  // have no business running hooks at all.
+  // `hooks.log` write. There is no global identity baseline: a repo where
+  // `adl-config.toml` does not exist has no business running hooks at all.
+  // The same no-op applies when `[hooks] enabled = false` (below).
   const managed = resolveManagedRepo(realRootIO, cwd)
   if (!managed.managed || managed.root === null || managed.configPath === null) {
     return writeResult(silentNoop())

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

@@ -35,7 +35,7 @@ import { gitIdentityNeedsIdentityMessage, hostCannotRewriteMessage, RULE_ID as G
 import { RULE_ID as GIT_CREDENTIAL_BYPASS_RULE_ID, SECURITY_RULE_ID as SECURITY_KEYCHAIN_ADO_RULE_ID } from '../rules/impl/adl-git-credential-bypass.ts'
 import { RULE_ID as HUMAN_AZDO_BYPASS_RULE_ID } from '../rules/impl/adl-human-azdo-bypass.ts'
 import { resolveFromEnvOrFile } from '../rules/impl/adl-identity.ts'
-import { identityBearingReason } from '../rules/impl/adl-session-required.ts'
+import { identityBearingReason } from '../rules/impl/adl-run-required.ts'
 import { commandHasValidInlineIdentity, effectiveIdentityForCommand } from '../rules/shell/git-identity.ts'
 import { invocations } from '../rules/shell/invocation.ts'
 import { KNOWN_MCP_TOOL_NAMES, mcpToolName, toolNameEndingWithKnownSuffix } from '../rules/impl/mcp-tool.ts'
@@ -82,7 +82,7 @@ const RULES = requireRegistered(BUILTIN_RULES)
 export function toDecideInput(payload: Record<string, unknown>): DecideInput | null {
   const toolInput = (payload.tool_input ?? {}) as Record<string, unknown>
 
-  // F4 (independent review, 2026-09-29): codex's `apply_patch` names its
+  // Codex's `apply_patch` names its
   // patch body `tool_input.command` — the same key name a real shell tool
   // call uses. Checked BEFORE the generic loop below, which would otherwise
   // read that patch TEXT as if it were a shell command and walk it through
@@ -167,13 +167,11 @@ function classifyCommandTool(payload: Record<string, unknown>): CommandToolClass
   if (typeof tool !== 'string' || tool.length === 0) return 'native-shell'
   if (tool.startsWith('mcp__') || tool.startsWith('MCP:')) return 'mcp'
   if (NATIVE_SHELL_TOOL_NAMES.has(tool)) return 'native-shell'
-  // ASSUMPTION (unverified, W2 build item 4 — STATUS.md 12p):
-  // OpenCode's and Kimi's own MCP tool-call naming has never actually been
-  // observed in production (.adl/logs/hooks.log shows only mcp__-prefixed
-  // calls, from Claude/Codex/Cursor) — they may carry no mcp__/MCP: prefix
-  // at all, spelling the lean-ctx shell tool `<server>_ctx_shell` /
-  // `<server>.ctx_shell` / `<server>:ctx_shell` (or the ctx_execute
-  // sibling). Treated as MCP-class defensively: an unrewritten push through
+  // ASSUMPTION (unverified): OpenCode's and Kimi's own MCP tool-call naming
+  // has not been confirmed against a live capture (the tests use synthetic names) — they may
+  // carry no mcp__/MCP: prefix at all, spelling the lean-ctx shell tool
+  // `<server>_ctx_shell` / `<server>.ctx_shell` / `<server>:ctx_shell` (or
+  // the ctx_execute sibling). Treated as MCP-class defensively: an unrewritten push through
   // such a call would otherwise silently fall through to 'other' and reach
   // git-ado's human pass-through unrewritten — the exact incident this
   // module exists to close (see this file's own header).
@@ -229,7 +227,7 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
 
   // The invocation's own environment, not the handler process's ambient one:
   // `main.ts` passes `process.env` here in production, and the identity rules
-  // (`adl.session-required-for-writes`, `adl.git-push-branch-policy`,
+  // (`adl.run-required-for-writes`, `adl.git-push-branch-policy`,
   // `adl.git-identity`'s rewrite) must read the environment the caller handed
   // the invocation — tests inject it explicitly, and a host that scrubs its
   // hook child's environment must not inherit the hook wrapper's own identity.
@@ -257,24 +255,21 @@ export async function handlePreToolUse(inv: HookInvocation): Promise<HookResult>
 }
 
 /**
- * The identity rule ids — used below (not as a baseline any more; see
- * Tarun's rule) purely to tell `denyIdentity`/`passIdentity` which decisions
- * in a MANAGED repo's own normal rule pass are identity decisions worth
- * logging `identity_source`/`identityAgent` for, as opposed to an unrelated
- * deny (`fs.rm`, `git.no-verify`, …) that made no identity decision at all.
+ * The identity rule ids — used below purely to tell `denyIdentity`/
+ * `passIdentity` which decisions in a MANAGED repo's own normal rule pass
+ * are identity decisions worth logging `identity_source`/`identityAgent`
+ * for, as opposed to an unrelated deny (`fs.rm`, `git.no-verify`, …) that
+ * made no identity decision at all.
  *
- * HARDCUT (Tarun's rule, 2026-09-29): "the repos where `adl-
- * config.toml` does not exist have no business running hooks" — this
- * REVERSES the earlier "global identity baseline" (W2 build item 3 / R2,
- * STATUS.md 12p), which ran exactly these rules
- * (unconditionally enabled, with the schema's own defaults) even in an
- * UNMANAGED repo or one with `[hooks] enabled = false`. `main.ts` no longer
- * calls anything for either of those cases but a strict, silent no-op — see
- * its own header and `silentNoop`. The rule ids themselves stay meaningful
- * only for the logging purpose above, in the repos where hooks already run.
+ * This is NOT a baseline that runs anywhere else: hooks run only in a repo
+ * with its own `adl-config.toml` where `adl hooks deploy` has run
+ * (Tarun, 2026-09-29: "the repos where `adl-config.toml` does not exist have
+ * no business running hooks"). `main.ts` calls nothing but a strict, silent
+ * no-op for an unmanaged repo or one with `[hooks] enabled = false` — see its
+ * own header and `silentNoop`.
  */
 const IDENTITY_RULE_IDS: ReadonlySet<RuleId> = new Set([
-  'adl.session-required-for-writes',
+  'adl.run-required-for-writes',
   'adl.git-identity',
   'adl.token-minting-role',
   'tool.azure-devops',
@@ -285,18 +280,17 @@ const IDENTITY_RULE_IDS: ReadonlySet<RuleId> = new Set([
 ])
 
 /**
- * F9 (independent review, 2026-09-29): the four role-gate rules that deny a
- * SPECIFIC Azure DevOps MCP tool call by the caller's identity
- * (`adl.workitem-requires-tarun-or-vivek`, `adl.pr-create-update-role`,
- * `adl.pr-review-role`, `adl.build-run-denied`). None of these are in
- * `IDENTITY_RULE_IDS` above — that set only ever covered the FALLBACK/
- * needs-identity/no-identity rules, never a rule that denies WITH an
- * identity already resolved, on the strength of who that identity is. Left
- * out of the deny-side identity logging entirely, even though every one of
- * them can only ever fire on the exact same Azure DevOps MCP tool-call shape
- * Decision 5's PASS-side logging already covers (`isAdoMcpToolCall`, below)
- * — a role-gate deny is JUST AS MUCH an identity decision as the PASS it
- * would have been without the role mismatch.
+ * The four role-gate rules that deny a SPECIFIC Azure DevOps MCP tool call by
+ * the caller's identity (`adl.workitem-requires-tarun-or-vivek`,
+ * `adl.pr-create-update-role`, `adl.pr-review-role`,
+ * `adl.build-run-denied`). None of these are in `IDENTITY_RULE_IDS` above —
+ * that set covers the rules that fire when no identity is resolved or
+ * carried, never a rule that denies WITH an identity already resolved, on the
+ * strength of who that identity is. Each of them can only fire on the same
+ * Azure DevOps MCP tool-call shape the PASS-side logging covers
+ * (`isAdoMcpToolCall`, below), so a role-gate deny is just as much an
+ * identity decision as the PASS it would have been without the role
+ * mismatch, and its deny log line carries `identity_source` too.
  */
 const ROLE_GATE_RULE_IDS: ReadonlySet<RuleId> = new Set([
   'adl.workitem-requires-tarun-or-vivek',
@@ -314,23 +308,23 @@ interface EffectiveIdentity {
 }
 
 /**
- * Where the effective agent identity for THIS decision came from (W2 build
- * item 5 — STATUS.md 12p), AND the agent it
- * actually names (M8, STATUS.md 12p) — a valid
+ * Where the effective agent identity for THIS decision came from
+ * (`identity_source` in the log), AND the agent it actually names: a valid
  * inline `ADL_AGENT_ID_AGENT=` on the command itself (step 1 of the
- * standard), else the session env or the machine default-agent file (steps
- * 2-3, `resolveFromEnvOrFile`'s own `source`/`agent`), else `none`/no agent.
- * A tool-call input carries no command text at all, so it can never be
- * `inline` — the override for an MCP tool call is `adl run --as` (session
- * env), matching the standard's own note on that.
+ * resolution order), else the session env or the machine default-agent file
+ * (steps 2-3, `resolveFromEnvOrFile`'s own `source`/`agent`), else
+ * `none`/no agent. A tool-call input carries no command text at all, so it
+ * can never be `inline`: its identity is the session env or the machine
+ * default-agent file. MCP is the primary route to Azure DevOps operations;
+ * `ADL_AGENT_ID_AGENT=<agent> adl mcp cli <command>` (which does carry an
+ * inline prefix) is the fallback when MCP is not working.
  *
  * The AGENT half matters because it can differ from the session's own
  * `ADL_AGENT_ID_AGENT`: `ADL_AGENT_ID_AGENT=agent-vivek git push …` run in
  * an agent-tarun session is agent-vivek's push, not agent-tarun's — the
- * override, not the session env, is what actually acted, and `../hooks/log.ts`
- * reads THIS agent for the log's `agent` column instead of the session
- * env var it used to read unconditionally (M8's second symptom: "the agent
- * column shows the session agent" even on an overridden command).
+ * override, not the session env, is what actually acted, and
+ * `../hooks/log.ts` reads THIS agent for the log's `agent` column rather
+ * than the session env var.
  */
 function effectiveIdentityFor(input: DecideInput, engineCtx: EngineContext): EffectiveIdentity {
   const resolution = resolveFromEnvOrFile(engineCtx.env)
@@ -344,10 +338,10 @@ function effectiveIdentityFor(input: DecideInput, engineCtx: EngineContext): Eff
 }
 
 /**
- * R7 (STATUS.md 12p, re-review 2026-09-28 night): the
- * resolved FALLBACK identity alone (steps 2-3 of the standard: env, else the
- * machine default-agent file) — never the coarse, whole-command "any inline
- * override anywhere on the line" `effectiveIdentityFor` also reports.
+ * The resolved FALLBACK identity alone (steps 2-3 of the resolution order:
+ * env, else the machine default-agent file) — never the coarse,
+ * whole-command "any inline override anywhere on the line"
+ * `effectiveIdentityFor` also reports.
  *
  * `adl.git-identity`'s REWRITE stage (`decision.rewrite`) and its own
  * fallback-based DENY reasons (`identity-mismatch`'s hint, `unrewritable-
@@ -393,11 +387,10 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   //
   // Every branch below decided an identity (the rewrite ALWAYS comes from
   // adl.git-identity), so every inv.record?.() call here carries
-  // identitySource/identityAgent. R7 (STATUS.md 12p):
-  // the FALLBACK identity specifically, not `effectiveIdentityFor`'s coarse
-  // whole-command value — see `fallbackIdentity`'s own doc for why a
-  // rewrite is always about the fallback, never an inline override
-  // elsewhere on a chained command.
+  // identitySource/identityAgent — the FALLBACK identity specifically, not
+  // `effectiveIdentityFor`'s coarse whole-command value (see
+  // `fallbackIdentity`'s own doc for why a rewrite is always about the
+  // fallback, never an inline override elsewhere on a chained command).
   if (!decision.blocked && decision.rewrite) {
     const identity = fallbackIdentity(engineCtx)
     const identitySource = identity.source
@@ -413,7 +406,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
       inv.record?.({ reason: `REWRITE ${decision.rewrite.ruleId}`, ...identityFields(identity) })
       return { stdout: `${JSON.stringify(rendered)}\n`, stderr: '', exitCode: 0 }
     }
-    // C2: `native-shell` here is only reached when the host could not
+    // `native-shell` here is only reached when the host could not
     // render a rewrite for this payload shape (Kimi has none at all;
     // Cursor's beforeShellExecution has no tool_input to replace) — SKIP
     // (allow unchanged) is only safe when `ADL_AGENT_ID_AGENT` is actually
@@ -434,7 +427,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
     return denyHostCannotRewrite(spec, inv.host, message)
   }
 
-  // R3 (STATUS.md 12p, re-review 2026-09-28 night): the
+  // Walker-found identity-bearing shapes the rewrite scanner missed: the
   // branch above only runs when `adl.git-identity`'s own narrow, offset-
   // based scanner recognized the command as identity-bearing at all
   // (`decision.rewrite` set) — it does not walk into `if`/`!`/`for..do`/
@@ -444,11 +437,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // backstop for a shape THIS scanner misses on a REWRITING host's native
   // shell). But `../rules/shell/invocation.ts`'s walker (reused here via
   // `identityBearingReason`, already proven against every one of those
-  // shapes for `adl.session-required-for-writes`'s own deny) DOES find them
+  // shapes for `adl.run-required-for-writes`'s own deny) DOES find them
   // — and once found, there is no rewritten command to offer at all (this
   // scanner never computed one), so the only safe outcomes are: a
   // native-shell tool with an ENV-sourced identity (its child inherits it
-  // regardless of any rewrite, exactly like the C2 branch above), or an
+  // regardless of any rewrite, exactly like the native-shell SKIP in the rewrite branch above), or an
   // inline override already on the command text (travels with the text
   // itself, no env inheritance needed) — anything else must be denied
   // rather than run with no identity anyone can prove reached the child.
@@ -476,13 +469,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // unrelated deny (fs.rm, git.no-verify, …) made no identity decision at
   // all. A PASS made one too when the command is identity-bearing but
   // needed no rewrite because it ALREADY carried a valid inline override
-  // (M8, STATUS.md 12p — "the override's PASS
-  // line"): `rewriteGitNetworkCommands`'s `unchanged` outcome covers BOTH
-  // "not identity-bearing at all" and "fully covered by an inline override
-  // already", and only `commandHasValidInlineIdentity` tells those two
-  // apart from here.
-  // R7 (STATUS.md 12p, re-review 2026-09-28 night): a
-  // `adl.git-identity` deny (identity-mismatch/unrewritable-wrapper/
+  // (the override's PASS line): `rewriteGitNetworkCommands`'s `unchanged`
+  // outcome covers BOTH "not identity-bearing at all" and "fully covered by
+  // an inline override already", and only `commandHasValidInlineIdentity`
+  // tells those two apart from here.
+  // An `adl.git-identity` deny (identity-mismatch/unrewritable-wrapper/
   // network-alias-redefinition/dynamic-agent/unsafe-identity) is ALWAYS
   // about the piece LACKING a valid override — the same fallback-only
   // reasoning `fallbackIdentity`'s doc gives the rewrite branch, and
@@ -490,15 +481,13 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // hint ("your session's own resolved identity is X"). The coarse
   // `effectiveIdentityFor` could otherwise report an unrelated, valid
   // override sitting on a DIFFERENT piece of the same chained command. The
-  // other three identity rules keep the coarse helper: `adl.session-
-  // required-for-writes` only ever denies when `commandHasValidInlineIdentity`
-  // is ALSO false (so the two never actually disagree for it), and `adl.
-  // token-minting-role`/`tool.azure-devops` are not piece-correlated by this
-  // change.
-  // F9: computed here (moved ahead of the PASS-side comment below, which
-  // used to be the only reader) so the DENY-side identity computation above
-  // can also test it — a role-gate deny of an Azure DevOps MCP call is the
-  // same shape as its PASS, just with the wrong identity.
+  // other identity rules keep the coarse helper: `adl.run-required-for-writes`
+  // only ever denies when `commandHasValidInlineIdentity` is ALSO false (so
+  // the two never actually disagree for it), and
+  // `adl.token-minting-role`/`tool.azure-devops` are not piece-correlated.
+  // `isAdoMcpToolCall` is computed ahead of `denyIdentity` because the
+  // DENY-side computation tests it too: a role-gate deny of an Azure DevOps
+  // MCP call is the same shape as its PASS, just with the wrong identity.
   const isAdoMcpToolCall = input.kind === 'tool-call' && KNOWN_MCP_TOOL_NAMES.has(mcpToolName(input.tool) ?? '')
   const denyIdentity =
     decision.blocked && (IDENTITY_RULE_IDS.has(decision.ruleId) || (isAdoMcpToolCall && ROLE_GATE_RULE_IDS.has(decision.ruleId)))
@@ -506,7 +495,7 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
         ? fallbackIdentity(engineCtx)
         : effectiveIdentityFor(input, engineCtx)
       : undefined
-  // Decision 5 (STATUS.md 12p): an ALLOWED Azure DevOps MCP
+  // An ALLOWED Azure DevOps MCP
   // tool call — reads included (workitem_list_or_get/pr_list_or_get/
   // build_list_or_get, not only the four writes) — logs `identitySource`/
   // `identityAgent` too, the SAME field names the shell path already uses
@@ -515,11 +504,11 @@ function decideAndRespond(inv: HookInvocation, engineCtx: EngineContext): HookRe
   // tool-call branch already reflects that, unchanged), so this is exactly
   // the session's resolved identity (env, else the machine default-agent
   // file). Every one of these calls ALREADY required a resolvable identity
-  // to reach this PASS line at all (`adl.session-required-for-writes` denies
+  // to reach this PASS line at all (`adl.run-required-for-writes` denies
   // otherwise) — this only makes that already-decided identity visible in
   // the log, the same way the shell path's own inline-override PASS line
-  // does (M8's "the override's PASS line"). `isAdoMcpToolCall` itself is
-  // computed above, ahead of `denyIdentity` — F9 needs it there too.
+  // does. Tarun, 2026-09-29: every Azure DevOps MCP call logs
+  // `identity_source`, reads included.
   const passIdentity = !decision.blocked && ((input.kind === 'command' && commandHasValidInlineIdentity(input.command)) || isAdoMcpToolCall) ? effectiveIdentityFor(input, engineCtx) : undefined
   inv.record?.(
     decision.blocked

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

@@ -87,14 +87,14 @@ 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 {
+interface DenyDecision {
   readonly blocked: true
   readonly ruleId: RuleId
   readonly userMessage: string
   readonly agentMessage: string
 }
 
-export interface AdviceDecision {
+interface AdviceDecision {
   readonly blocked: false
   readonly advice?: { readonly ruleId: RuleId; readonly userMessage: string; readonly agentMessage: string }
   /**
@@ -205,9 +205,8 @@ function decideCommand(command: string, ctx: EngineContext): Decision {
   }
 
   // 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
+  // it covers 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,
@@ -216,19 +215,16 @@ function decideCommand(command: string, ctx: EngineContext): Decision {
   // 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
+  // `needs-identity` (an identity-bearing command with no inline override
+  // and no resolvable fallback) is denied HERE, directly, rather than left
+  // to `adl.run-required-for-writes` having already denied the SAME command
+  // earlier in the rule pass: that rule is 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
+  // (`[rules."adl.run-required-for-writes"] enabled = false`) or simply not
+  // recognize a shape this scanner does, and nothing else here would stand
+  // between an unidentified network git command and a plain allow.
+  //
+  // 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

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

@@ -5,7 +5,7 @@
  * 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
+ * `adl.run-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.
@@ -25,10 +25,10 @@ export const adlBuildRunDenied: RuleSpec = {
   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).',
+  summary: 'Deny build_run for every identity (docs/operations/agent-permissions.md row 12) — the MCP tool AND its adl mcp cli equivalent.',
   params: noParams,
   match(inv: Invocation): Finding | null {
-    // M4 (STATUS.md 12p): also catch `adl mcp cli build-run` — same tool, same deny.
+    // 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