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

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

@@ -1,46 +1,48 @@
 /**
- * Editing the files that wire the host's hooks or un-manage this repo.
+ * 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`,
- * `.codex/config.toml`, or `adl-config.toml`. These are the files that
- * either install the hook into the host (`.claude/settings.json`,
- * `.codex/config.toml`, including the `.local.json` overrides) or arm the
- * gate in this repo (`adl-config.toml`'s `[hooks] enabled = false`
- * silently no-ops every kind — see `main.ts`'s `runHook`). Editing any
- * of them is a way to switch the gate off without anyone noticing.
+ * `.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.
  *
- * Decision 13 (STATUS.md 12p, 2026-09-29): the managed-
- * hooks lock is off, so these per-repo carrier files are now the ONLY
+ * `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.
+ *
+ * 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
  * enforcement layer for the hosts that read them — three more joined the
  * set for exactly that reason: `.codex/hooks.json`, `.cursor/hooks.json`,
  * and `.opencode/plugins/adl-repo.ts` (the generated OpenCode plugin IS
- * its own carrier; there is no separate settings file for that host).
- * Measured against the real engine before this fix: Write
- * `.codex/hooks.json` / Edit `.cursor/hooks.json` / Write
- * `.opencode/plugins/adl-repo.ts` all had `blocked: false`, while the
- * original four's own control case (`.claude/settings.json`) already had
- * `blocked: true`.
+ * its own carrier; there is no separate settings file for that host). The
+ * single source of the list is `PROTECTED_CARRIER_PATHS` in
+ * `../shell/protected-carriers.ts`, which also names Kimi's one global
+ * carrier, `~/.kimi-code/config.toml`.
  *
- * The list is hard-coded here on purpose. `adl-config.toml`'s own
- * `[hooks] enabled` already lets a repo switch the whole hook system
- * off; allowing `[rules."agent.tamper-protection"] enabled = false` in
- * the same file is the same switch wearing a different hat. A repo that
- * legitimately needs a different allowlist should patch this file in a
- * PR, not in a session.
+ * The list is hard-coded here on purpose: a per-repo allowlist in
+ * `adl-config.toml` would be one more switch in a file the repo controls.
+ * A repo that legitimately needs a different allowlist should patch this
+ * file in a PR, not in a session.
  *
  * The file names match against the FULL path and against the basename so
  * `Write .claude/settings.json` AND `Write /Users/x/repo/.claude/settings.json`
  * both fire, but `Write .claude/SETTINGS.json.bak` does NOT (the
  * case-sensitive suffix check rejects it).
  *
- * Shell-write coverage (STATUS.md 12p, decision 13 follow-up, 2026-09-29):
- * the tool-call gate above never saw a shell command at all — `echo x >
- * .cursor/hooks.json`, `tee`, `mv`/`cp`/`install`/`ln -sf`, `sed -i`/
- * `perl -pi`, `truncate`, `trash`/`rm`/`unlink`/`shred`, and `dd of=` were
- * every one of them `{blocked: false}` against all seven protected files,
- * measured directly against the real engine before this fix. Closed via
- * three additional match() branches:
+ * Shell-write coverage: the tool-call gate above never sees a shell
+ * command, so `echo x > .cursor/hooks.json`, `tee`, `mv`/`cp`/`install`/
+ * `ln -sf`, `sed -i`/`perl -pi`, `truncate`, `trash`/`rm`/`unlink`/`shred`,
+ * and `dd of=` against a protected file are covered by three additional
+ * match() branches:
  *  - `inv.kind === 'protected-carrier-write'` — the generic-command half
  *    (redirection/tee/mv/cp/install/ln/sed/perl/truncate/trash/rm/unlink/
  *    shred/dd), classified by `shell/protected-carrier-writes.ts` and wired
@@ -88,14 +90,14 @@ function logicalToolName(tool: string): string {
 /**
  * Tools whose `input.file_path` / `input.notebook_path` / `input.path` /
  * `input.filePath` decides what the edit targets — matched case-insensitively
- * (F4, independent review, 2026-09-29): OpenCode's own plugin
+ * (independent review, 2026-09-29): OpenCode's own plugin
  * (`.opencode/plugins/adl-repo.ts`'s `tool.execute.before`) sends its OWN
  * lowercase tool names (`edit`, `write`), not Claude/Codex/Kimi's
  * capitalized ones, and its `tool_input` (`output.args`) carries the target
  * as camelCase `filePath`, not `file_path`.
  */
 /**
- * P2 (independent review, 2026-09-29): widened beyond Claude/Codex/Kimi's
+ * Widened beyond Claude/Codex/Kimi's
  * own capitalized names — one normalized (lowercase) list covering every
  * edit-tool spelling a supported host actually sends:
  *  - `strreplace`/`str_replace_editor`/`edit_file`/`str_replace`/
@@ -139,7 +141,7 @@ function readStringField(input: Readonly<Record<string, unknown>>, key: string):
 }
 
 /**
- * Codex's `apply_patch` (F4): its patch body lives in `input.command`
+ * Codex's `apply_patch`: its patch body lives in `input.command`
  * (`handler.ts`'s `toDecideInput` special-cases this tool to a `tool-call`
  * precisely so it reaches here instead of being walked as shell text), and
  * the path it targets is named in a `*** Add File:`/`*** Update File:`/
@@ -161,13 +163,13 @@ function toolCallTarget(inv: Invocation & { kind: 'tool-call' }): string | null
   const name = logicalToolName(inv.tool).toLowerCase()
   // apply_patch / OpenCode's own `patch` tool: the patch body is
   // `input.command` (Codex) or `input.patchText` (OpenCode's own field
-  // name for the same shape, P2) — never a `file_path`-shaped field.
+  // name for the same shape) — never a `file_path`-shaped field.
   if (name === 'apply_patch' || name === 'patch') {
     const body = readStringField(inv.input, 'command') + readStringField(inv.input, 'patchText')
     if (body.length > 0) return applyPatchTarget(body)
   }
   if (!EDIT_TOOL_NAMES.has(name)) return null
-  // F8 (fourth independent review, 2026-09-29): Cursor's real `edit_file`
+  // Cursor's real `edit_file`
   // schema names its path argument `target_file` (confirmed via Cursor's
   // own published tool schema/system-prompt documentation).
   const filePath =
@@ -194,8 +196,8 @@ function nonOptionValues(rest: readonly Token[]): readonly string[] {
 /**
  * `git checkout` ALWAYS restores the WORKTREE for a named path — there is no
  * staged-only variant (that is `git restore --staged`'s job) — so every
- * shape is checked: `git checkout -- <path>` and, P1 (second independent
- * review, 2026-09-29), the equally real `git checkout <rev> <path>` form
+ * shape is checked: `git checkout -- <path>` and the equally real
+ * `git checkout <rev> <path>` form
  * with no `--` at all (>= 2 non-option operands; the LAST one is the path).
  */
 function checkoutTarget(rest: readonly Token[]): string | null {
@@ -215,7 +217,7 @@ function checkoutTarget(rest: readonly Token[]): string | null {
 /**
  * `git restore` touches the WORKTREE by default; `--staged`/`-S` makes it an
  * index-only unstage UNLESS `--worktree`/`-W` is ALSO given (both flags
- * together restore both). P1 (second independent review, 2026-09-29): a
+ * together restore both). A
  * plain `git restore --staged -- <path>` must be ALLOWED — it never
  * touches the file this rule exists to protect from being overwritten.
  */
@@ -242,8 +244,7 @@ function restoreTarget(rest: readonly Token[]): string | null {
  * `--hard`/`--merge`/`--keep`, none of which accepts a pathspec in real
  * git (a bare `git reset --hard` with no path at all is `git.reset`'s own
  * unconditional deny to catch, not this rule's — there is no specific
- * carrier PATH for this function to find there). P1 (second independent
- * review, 2026-09-29): `git reset -- <path>` and `git reset HEAD --
+ * carrier PATH for this function to find there). `git reset -- <path>` and `git reset HEAD --
  * <path>` must be ALLOWED — they only unstage.
  */
 function resetTouchesWorktree(rest: readonly Token[]): boolean {
@@ -267,7 +268,7 @@ function anyOperandTarget(rest: readonly Token[]): string | null {
   for (const token of rest) {
     const value = tokenValue(token)
     if (value === '--' || value.startsWith('-')) continue
-    // F5 (fourth independent review, 2026-09-29): `git mv .claude
+    // `git mv .claude
     // .claude-old` moves the WHOLE carrier directory away — file-level
     // `protectedCarrierMatch` alone never saw this.
     const hit = protectedCarrierMatch(value) ?? protectedCarrierDirMatch(value)
@@ -277,13 +278,13 @@ function anyOperandTarget(rest: readonly Token[]): string | null {
 }
 
 function gitTarget(inv: Invocation & { kind: 'git' }): string | null {
-  // P2 (independent review, 2026-09-29): `git mv` of a carrier (either
+  // `git mv` of a carrier (either
   // operand — moving it away, or overwriting it with something else).
   if (inv.subcommand === 'rm' || inv.subcommand === 'mv') return anyOperandTarget(inv.rest)
   if (inv.subcommand === 'checkout') return checkoutTarget(inv.rest)
   if (inv.subcommand === 'restore') return restoreTarget(inv.rest)
   if (inv.subcommand === 'reset') return resetTarget(inv.rest)
-  // P2: `git checkout-index` writes working-tree files from the index for
+  // `git checkout-index` writes working-tree files from the index for
   // named paths — the plumbing sibling of `git checkout -- <path>`. `-a`/
   // `--all` (every staged file, no specific path named) is a known,
   // documented gap — not handled here.
@@ -292,8 +293,7 @@ function gitTarget(inv: Invocation & { kind: 'git' }): string | null {
 }
 
 /**
- * `git apply`/the standalone `patch` utility (P2, independent review,
- * 2026-09-29): the path a patch actually modifies lives INSIDE the patch
+ * `git apply`/the standalone `patch` utility: the path a patch actually modifies lives INSIDE the patch
  * file's own headers, not (usually) as a command-line operand at all —
  * `git apply some.patch` names the PATCH FILE, never its target. Coarse,
  * whole-command (same tradeoff `interpreterTarget`/`coarsePathMention`
@@ -303,29 +303,38 @@ function gitTarget(inv: Invocation & { kind: 'git' }): string | null {
  * static, pre-execution hook (it would need to read the file from disk,
  * which this hook does not do for any other check either).
  */
-/** `git apply` flags that inspect a patch without applying anything (F7, fourth independent review, 2026-09-29). */
+/** `git apply` flags that inspect a patch without applying anything. */
 const DRY_RUN_GIT_APPLY_FLAGS: ReadonlySet<string> = new Set(['--check', '--stat', '--numstat', '--summary'])
 
+/**
+ * `name` as a whole file name: not glued to a longer name on either side. A bare
+ * substring test matched `config.toml` inside `adl-config.toml`,
+ * `enact-config.toml` and `my.config.toml`, denying any `git apply`/`patch`
+ * that named them as "rewriting .codex/config.toml".
+ */
+function mentionsWholeName(command: string, name: string): boolean {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(?<![\\w.-])${escaped}(?![\\w.-])`).test(command)
+}
+
 function coarsePathMention(command: string): string | null {
   for (const protectedPath of PROTECTED_CARRIER_PATHS) {
     if (command.includes(protectedPath)) return protectedPath
     const base = protectedPath.slice(protectedPath.lastIndexOf('/') + 1)
-    if (command.includes(base)) return protectedPath
+    if (mentionsWholeName(command, base)) return protectedPath
   }
   return null
 }
 
 /**
- * Live false positive (third independent review, 2026-09-29): the OLD check
- * paired "some write call anywhere in the command" (`WRITE_CALL_RE.test`)
- * with "a carrier path anywhere in the command text" (`coarsePathMention`)
- * — two UNCORRELATED checks. A heredoc-fed `python3 - <<'EOF'` writing an
- * unrelated file (e.g. `STATUS.md`) whose own written TEXT merely mentioned
+ * Correlated detection, not two independent checks. Pairing "some write call
+ * anywhere in the command" with "a carrier path anywhere in the command
+ * text" (`coarsePathMention`) was a live false positive (independent review,
+ * 2026-09-29): a heredoc-fed `python3 - <<'EOF'` writing an unrelated file
+ * (e.g. `notes.md`) whose own written TEXT merely mentioned
  * `.codex/config.toml` (a docstring, a log line, a commit message) was
  * wrongly denied — the mention and the write had nothing to do with each
- * other.
- *
- * Replaced with CORRELATED detection: each pattern below captures the
+ * other. So each pattern below captures the
  * WRITE-CALL'S OWN TARGET ARGUMENT specifically (group 1) — `open(TARGET,
  * 'w'|'a'|'x'…)`, `Path(TARGET).write_text/write_bytes(...)`,
  * `os.remove/unlink(TARGET)`, `os.rename(SRC, TARGET)`,
@@ -344,7 +353,7 @@ function coarsePathMention(command: string): string | null {
  * expression (neither a literal nor a bare identifier — string
  * concatenation, a function call, …) cannot be correlated at all and is
  * left alone (allowed), the same "cannot resolve, so cannot deny" stance
- * `adl.session-required-for-writes`'s own destination classification takes
+ * `adl.run-required-for-writes`'s own destination classification takes
  * for an unresolved git push remote.
  *
  * `ARG` allows one level of nested parens (`os.path.join(a, b)` as a
@@ -354,7 +363,7 @@ function coarsePathMention(command: string): string | null {
 const ARG = `((?:[^,()]|\\([^()]*\\))+)`
 /** `fs.X(...)`, `require('fs').X(...)`, or `require('fs').promises.X(...)` (no literal `fs.` substring exists in the `require(...)` forms — `'fs')` breaks it — so all three are matched explicitly rather than relying on a bare `fs\.` prefix). Required (not optional) for the async, non-Sync names below — `rename`/`unlink`/`rm` are common-enough verbs that an UNqualified bare call risks a real collision with an unrelated same-named function. */
 const FS_QUALIFIED_PREFIX = `(?:\\bfs|require\\(\\s*['"]fs['"]\\s*\\))\\s*\\.\\s*(?:promises\\s*\\.\\s*)?`
-/** The SAME prefix, but OPTIONAL — F6 (fourth independent review, 2026-09-29): `const { writeFileSync } = require('fs'); writeFileSync(...)` calls it BARE, with no qualifying prefix on the call site itself. Only for the `*Sync` names, distinctive enough on their own that an unqualified bare call is still almost certainly this Node API. */
+/** The SAME prefix, but OPTIONAL: `const { writeFileSync } = require('fs'); writeFileSync(...)` calls it BARE, with no qualifying prefix on the call site itself. Only for the `*Sync` names, distinctive enough on their own that an unqualified bare call is still almost certainly this Node API. */
 const FS_SYNC_OPTIONAL_PREFIX = `(?:${FS_QUALIFIED_PREFIX})?`
 const WRITE_TARGET_PATTERNS: readonly RegExp[] = [
   new RegExp(`\\bopen\\s*\\(\\s*${ARG}\\s*,\\s*['"][wax]`, 'g'),
@@ -364,7 +373,7 @@ const WRITE_TARGET_PATTERNS: readonly RegExp[] = [
   new RegExp(`\\bshutil\\.(?:move|copy2?|copyfile)\\s*\\(\\s*${ARG}\\s*,\\s*${ARG}\\s*\\)`, 'g'),
   new RegExp(`${FS_SYNC_OPTIONAL_PREFIX}(?:writeFileSync|appendFileSync|rmSync|unlinkSync|copyFileSync|truncateSync)\\s*\\(\\s*${ARG}`, 'g'),
   new RegExp(`${FS_SYNC_OPTIONAL_PREFIX}renameSync\\s*\\(\\s*${ARG}\\s*,\\s*${ARG}`, 'g'),
-  // F6: the async (non-Sync) forms, prefix REQUIRED.
+  // The async (non-Sync) forms, prefix REQUIRED.
   new RegExp(`${FS_QUALIFIED_PREFIX}(?:writeFile|appendFile|rm|unlink|copyFile)\\s*\\(\\s*${ARG}`, 'g'),
   new RegExp(`${FS_QUALIFIED_PREFIX}rename\\s*\\(\\s*${ARG}\\s*,\\s*${ARG}`, 'g'),
   new RegExp(`\\bBun\\.write\\s*\\(\\s*${ARG}`, 'g'),
@@ -414,7 +423,7 @@ export const agentTamperProtection: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny edits (tool, shell write, or git rewrite) to the host hook config or the repo gate marker.',
+  summary: "Deny edits (tool, shell write, or git rewrite) to the files that wire a host's hooks.",
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
     if (inv.kind === 'tool-call') {
@@ -431,10 +440,10 @@ export const agentTamperProtection: RuleSpec = {
       if (target !== null) {
         return { ruleId: 'agent.tamper-protection', severity: 'deny', detail: { path: target, via: 'git', command: `git ${inv.subcommand}` } }
       }
-      // P2: `git apply` — coarse, whole-command (see `coarsePathMention`'s
+      // `git apply` — coarse, whole-command (see `coarsePathMention`'s
       // own doc for why: the target path is inside the patch's own
       // headers, not an operand `gitTarget`'s per-operand scan would see).
-      // F7 (fourth independent review, 2026-09-29): a dry-run/inspection
+      // A dry-run/inspection
       // flag applies NOTHING — `git apply --check/--stat/--numstat/
       // --summary` never touches the working tree, so naming a carrier is
       // harmless.
@@ -444,7 +453,7 @@ export const agentTamperProtection: RuleSpec = {
       }
       return null
     }
-    // P2: the standalone `patch` utility — same coarse, whole-command
+    // The standalone `patch` utility — same coarse, whole-command
     // reasoning as `git apply` above.
     if (inv.kind === 'command' && inv.name === 'patch') {
       const hit = coarsePathMention(ctx.command ?? '')
@@ -469,21 +478,19 @@ export const agentTamperProtection: RuleSpec = {
             ? 'an interpreter one-liner writing'
             : 'editing'
     return {
-      user: `Blocked ${via === 'tool-call' ? 'editing' : verb} ${path}. This file wires the host's hooks or un-manages this repo; ask the user to change it.`,
+      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`, ' +
-        "`~/.kimi-code/config.toml`, or `adl-config.toml`. The first six install or override 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); `adl-config.toml` is the repo's " +
-        "own gate marker (`[hooks] enabled = false` silently no-ops every hook kind — see " +
-        '`main.ts`). Editing, overwriting, moving over, truncating, ' +
+        "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 (decision 13: the managed-hooks lock is ' +
-        `off). If a legitimate change is needed, file a PR or ask the user to make it themselves. ` +
+        '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. ` +
         `Blocked call: ${ctx.snippet}`,
     }
   },

package/packages/agent-hooks/src/rules/impl/deny-allowlist.ts

@@ -0,0 +1,159 @@
+/**
+ * Single source of truth for "which commands actually pass the lean-ctx
+ * shell allowlist", so the three search-tool deny rules (tool.grep,
+ * tool.find, tool.native-search) cannot lie about what's available.
+ *
+ * History (2026-10-02 research `research-2026-10-02-search-tool-usage-across-surfaces.md`
+ * finding #4):
+ *
+ *   - `tool.grep`'s deny text claimed "search is allowed". It is not — the
+ *     default lean-ctx allowlist has 223 commands and no `search` unless the
+ *     repo's `.agents/lean-ctx/config/lean-ctx/config.toml` declares it under
+ *     `shell_allowlist_extra`. Only a per-repo deploy with the seed list lands
+ *     `search`/`crg`/etc. into the actual runtime allowlist.
+ *   - `tool.find`'s deny text pointed at `search query "<text>"` for every
+ *     path-pattern request, which is the wrong recommendation — `search`
+ *     searches CONTENT, not paths; the right tool for `find -name '*.md'` is
+ *     `rg --files -g '<glob>'` or `ctx_glob`.
+ *   - `tool.native-search`'s deny text pointed at `ctx_search` /
+ *     `ctx_compose` / `ctx_callgraph` / `rg / ast-grep`, never at `search
+ *     query` — the docs-and-plans case that 11 of 25 kimi denials actually were.
+ *
+ * Every entry here is the canonical name (matches the binary on PATH); the
+ * rules import this and reference its shape from their deny messages, so a
+ * command added here appears in every deny message that recommends it, and a
+ * command removed here stops being recommended everywhere at once.
+ *
+ * The list is consumed by:
+ *
+ *   - `tool.grep.ts` (Bash shape): pipe stdin filter / literal text search
+ *   - `tool.find.ts` (Bash shape): path-pattern search
+ *   - `tool.native-search.ts` (host-native tool shape): Grep / Glob / Search
+ *
+ * Each rule still owns its own denial text, but the recommendation rows are
+ * generated from `ALLOWED` so the texts cannot drift from the truth here.
+ */
+
+export interface AllowedTool {
+  /** The binary name as it appears on PATH (no path prefix). */
+  readonly binary: string
+  /** A one-line description used by the deny rules' recommendation table. */
+  readonly purpose: string
+  /**
+   * A concrete command shape the model can copy verbatim. Used by the rules'
+   * deny messages so the message reads like documentation, not a hint.
+   * Multiple commands because some tools have multiple shapes (e.g. rg grep vs
+   * rg tree).
+   */
+  readonly examples: readonly string[]
+}
+
+/**
+ * The tools the deny messages recommend. Each row carries a single source of
+ * truth so the three rules' text cannot drift.
+ *
+ * Only the surface that's relevant to search-tool use is here. Bash itself
+ * is not "allowed" in this sense — it's the substrate the tools run in. `ls`,
+ * `cat`, `git`, etc. are not in this table because they are not search
+ * replacements.
+ */
+export const ALLOWED_SEARCH_TOOLS: readonly AllowedTool[] = [
+  // Order matters — `rules-grep-message-order.test.ts` pins it as
+  // ast-grep, search, crg, rg, ctx_search, …  (Tarun, 2026-09-30).
+  {
+    binary: 'ast-grep',
+    purpose: 'code STRUCTURE: shapes rather than strings',
+    examples: [
+      'ast-grep -p "foo($A)" -l ts',
+    ],
+  },
+  {
+    binary: 'search',
+    purpose:
+      'docs and plans by MEANING: hybrid semantic + keyword (enoted-search@0.2.2 at /usr/local/bin/search)',
+    examples: [
+      'search query "how do I author a metric"    # hybrid (default)',
+      'search query "<text>" --mode keyword       # when you only want literal matches',
+      'search query "<text>" --mode semantic      # when the doc talks about it, not the word',
+    ],
+  },
+  {
+    binary: 'crg',
+    purpose: 'the code GRAPH: callers, callees, impact (code-review-graph)',
+    examples: [
+      'crg search "<text>" --kind File            # find files matching a name/text',
+      'crg query callers_of <fn>                  # who calls this function?',
+      'crg query callees_of <fn>                  # what does this function call?',
+      'crg impact                                 # blast radius of staged changes',
+      'crg architecture                           # module/structure overview',
+    ],
+  },
+  {
+    binary: 'rg',
+    purpose: 'literal text or regex, including stdin (`npm test 2>&1 | rg "pass|fail"`)',
+    examples: [
+      'rg "TODO" src/',
+      'rg --files -g "<glob>"        # path patterns, NOT find',
+      'rg "pass|fail"                # stdin filter, NOT grep',
+    ],
+  },
+  {
+    binary: 'ctx_search',
+    purpose: 'lean-ctx MCP indexed code search (action=symbol for an exact symbol)',
+    examples: [
+      'ctx_search(action=symbol, handle="path#name@Lstart")',
+    ],
+  },
+  {
+    binary: 'ctx_glob',
+    purpose: 'lean-ctx MCP indexed file search (path patterns only, not content)',
+    examples: ['ctx_glob(pattern, path)'],
+  },
+  {
+    binary: 'ctx_read',
+    purpose: 'lean-ctx MCP indexed file read (compressed output, no token tax)',
+    examples: ['ctx_read(path, mode)'],
+  },
+  {
+    binary: 'ctx_compose',
+    purpose: 'lean-ctx MCP context compose (orient on a task without reading whole files)',
+    examples: ['ctx_compose(task)'],
+  },
+  {
+    binary: 'ctx_callgraph',
+    purpose: 'lean-ctx MCP callers/impact for callers and engines (crg also answers these, but via shell)',
+    examples: ['ctx_callgraph(symbol)'],
+  },
+] as const
+
+/**
+ * The rule's deny text needs to point at the right tool for the right
+ * surface. This helper produces a single recommendation block from
+ * `ALLOWED_SEARCH_TOOLS`, formatted as a multi-line bullet list the rules
+ * can paste into their `agent:` field. `filter` lets a rule narrow to the
+ * subset of tools that apply (e.g. only tools that work in a docs/plans
+ * tree).
+ */
+export function recommendationBlock(filter?: (tool: AllowedTool) => boolean): string {
+  const rows = ALLOWED_SEARCH_TOOLS.filter(filter ?? (() => true))
+  return rows
+    .map((row) => {
+      const examples = row.examples.map((e) => `    ${e}`).join('\n')
+      return `  ${row.binary.padEnd(11)} ${row.purpose}\n${examples}`
+    })
+    .join('\n')
+}
+
+/**
+ * The set of paths where `search` (semantic + keyword) is the right tool
+ * over `rg`/`crg`/`ctx_search`. A native `Grep` whose `tool_input.path`
+ * starts with one of these should redirect to `search`, not to `rg` — the
+ * model is searching for the document that *talks* about X, not for the
+ * literal text X.
+ */
+export const DOC_TREES: readonly string[] = [
+  'docs/',
+  'plans/',
+  '.scratchpad/',
+] as const
+

package/packages/agent-hooks/src/rules/impl/fs-trash.ts

@@ -7,8 +7,8 @@
  *
  * The original's eighth predicate -- any path with an `.agents` segment --
  * was dropped by owner decision on 2026-09-15. `.agents/` is reconciled
- * centrally every six hours (global-tools `git-maintain` refreshes repo-local
- * surfaces in every managed repo), so a trashed copy is restored rather than
+ * centrally every 12 hours (`adl reconcile`'s repository step runs `adl install --repo`,
+ * which refreshes repo-local surfaces in every managed repo), so a trashed copy is restored rather than
  * lost, and `trash(1)` is itself recoverable from ~/.Trash. Protecting it here
  * blocked routine work to guard against something the fleet already repairs.
  *

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

@@ -90,7 +90,7 @@ export function flipsCoreBare(tokens: readonly Token[]): boolean {
   return tokens.some((token) => /core\.bare/i.test(tokenValue(token)))
 }
 
-export function pathIsInProtectedTree(rawPath: string, protectedTrees: readonly string[]): boolean {
+function pathIsInProtectedTree(rawPath: string, protectedTrees: readonly string[]): boolean {
   const path = `/${rawPath.replace(/^\.\//, '').replace(/\/+$/, '')}/`
   return protectedTrees.some((tree) => path.includes(`/${tree}`))
 }
@@ -107,7 +107,7 @@ export function moveEscapesRepo(rest: readonly Token[], protectedTrees: readonly
 
 const WHOLE_TREE_PATHSPEC = new Set(['.', './', '..', '../', '*', ':', ':/', ':/*', ':(top)'])
 
-export function namedPathspecs(tokens: readonly Token[]): readonly string[] {
+function namedPathspecs(tokens: readonly Token[]): readonly string[] {
   const paths: string[] = []
   for (let index = 0; index < tokens.length; index += 1) {
     const value = tokenValue(tokens[index] as Token)
@@ -121,7 +121,7 @@ export function namedPathspecs(tokens: readonly Token[]): readonly string[] {
   return paths
 }
 
-export function isNamedPathspecOnly(tokens: readonly Token[]): boolean {
+function isNamedPathspecOnly(tokens: readonly Token[]): boolean {
   const paths = namedPathspecs(tokens)
   if (paths.length === 0) return false
   return paths.every((value) => !WHOLE_TREE_PATHSPEC.has(value))
@@ -152,23 +152,22 @@ export function updateIndexIsUnstageOnly(rest: readonly Token[]): boolean {
 }
 
 /**
- * `git push` destination classification shared by `adl.session-required-for-writes`
- * and `adl.git-push-branch-policy` — moved here (2026-09-27, docs/architecture/cli-design.md
- * decision 2 / docs/operations/agent-permissions.md) so the two rules cannot drift on what
+ * `git push` destination classification shared by `adl.run-required-for-writes`
+ * and `adl.git-push-branch-policy` — kept here (docs/architecture/cli-design.md §2 /
+ * docs/operations/agent-permissions.md) so the two rules cannot drift on what
  * counts as an Azure DevOps push. Both decide statically, off argv alone: no
  * `git remote get-url` subprocess (the deployed `bin/git` front controller can
  * do that; a pre-tool-use hook decides before the child runs).
  */
-export const ADO_HOST = 'dev.azure.com'
+const ADO_HOST = 'dev.azure.com'
 
 /**
  * The second Azure DevOps host the one-agent-identity standard names
- * (STATUS.md 12p, "What the hook covers" — REST:
- * curl/wget/httpie/xh to `dev.azure.com` / `*.visualstudio.com`). Widened
- * 2026-09-28 alongside the identity-bearing command classes below;
- * `isAdoUrl` used to check `dev.azure.com` alone.
+ * (REST: curl/wget/httpie/xh to `dev.azure.com` / `*.visualstudio.com`);
+ * `isAdoUrl` checks both, alongside the identity-bearing command classes
+ * below.
  */
-export const ADO_VISUALSTUDIO_HOST = 'visualstudio.com'
+const ADO_VISUALSTUDIO_HOST = 'visualstudio.com'
 
 export function isAdoUrl(value: string): boolean {
   const lower = value.toLowerCase()
@@ -177,13 +176,12 @@ export function isAdoUrl(value: string): boolean {
 
 /**
  * Identity-bearing `adl <...>` subcommand shapes
- * (STATUS.md 12p "What the hook covers" / W2 build
- * item 1): every one of these reaches Azure DevOps and needs the resolved
+ * (one-agent-identity standard): every one of these reaches Azure DevOps and needs the resolved
  * agent identity, exactly like a network git command. Matched positionally
  * against the words/tokens right after `adl` itself (case-insensitively,
  * dynamic values excluded by the caller) — shared by the shell scanner
  * (`../shell/git-identity.ts`, which needs the raw source span to rewrite)
- * and the ordinary invocation-based rules (`adl-session-required.ts`, which
+ * and the ordinary invocation-based rules (`adl-run-required.ts`, which
  * only needs a yes/no match) so the two classifications cannot drift apart.
  */
 export const ADL_IDENTITY_COMMAND_SHAPES: readonly (readonly string[])[] = [
@@ -202,7 +200,7 @@ export const ADL_AGENT_ID_BINARY_NAMES: ReadonlySet<string> = new Set(['adl-agen
 
 /**
  * curl/wget/httpie(`http`/`https`)/xh — the REST client family the standard
- * names. Shared with `adl-session-required.ts`'s own `HTTP_CLIENT_NAMES` so
+ * names. Shared with `adl-run-required.ts`'s own `HTTP_CLIENT_NAMES` so
  * the two classifications (this file's shape matcher vs. that rule's method
  * inspection) cannot name a different set of binaries.
  */
@@ -309,8 +307,8 @@ function httpieMethod(args: readonly Token[]): string {
 /**
  * The effective HTTP method for an `HTTP_CLIENT_BINARY_NAMES` invocation,
  * dispatched by binary name — curl/wget/httpie(`http`/`https`)/xh each spell
- * their method differently. M10 (STATUS.md 12p): shared
- * by `adl-session-required.ts` (deny with no identity, every method) and
+ * their method differently. Shared
+ * by `adl-run-required.ts` (deny with no identity, every method) and
  * `tool-azure-devops.ts` (deny a WRITE method outright, identity or not —
  * docs/operations/agent-permissions.md row 13) so the method-detection logic
  * cannot drift between the two.
@@ -334,8 +332,8 @@ export function matchesIdentityShape(values: readonly string[], shapes: readonly
 }
 
 /**
- * Drop leading dash-prefixed words — M5 (STATUS.md
- * 12p): `adl-agent-id`'s own global flags (e.g. `--verbose`/`--quiet`)
+ * Drop leading dash-prefixed words:
+ * `adl-agent-id`'s own global flags (e.g. `--verbose`/`--quiet`)
  * ahead of its `exec` subcommand, which `ADL_AGENT_ID_COMMAND_SHAPES`
  * (`[['exec']]`) would otherwise require sitting at position 0 exactly —
  * `adl-agent-id --verbose exec --agent agent-tarun -- ...` would not match
@@ -344,7 +342,7 @@ export function matchesIdentityShape(values: readonly string[], shapes: readonly
  * global flag is not a documented `adl-agent-id` shape today, so this does
  * not try to consume one — a bare `-` (stdin marker) is not treated as a
  * flag either. Shared by `../shell/git-identity.ts` (the rewrite scanner)
- * and `adl-session-required.ts` so the two classifications cannot drift on
+ * and `adl-run-required.ts` so the two classifications cannot drift on
  * this.
  */
 export function skipLeadingDashFlags(values: readonly string[]): readonly string[] {
@@ -380,9 +378,9 @@ export function classifyGitPushDestination(rest: readonly Token[]): GitPushDesti
 }
 
 /**
- * R3 (STATUS.md 12p): a coarse, TEXTUAL (not
+ * A coarse, TEXTUAL (not
  * shell-parsed) signal that some string holds an identity-bearing token —
- * used by `adl-session-required.ts`'s `identityBearingReason` for the two
+ * used by `adl-run-required.ts`'s `identityBearingReason` for the two
  * shapes the shell walker (`../shell/invocation.ts`) cannot see INTO at all:
  * an interpreter one-liner's `-c`/`-e` code string (`python3 -c
  * "...subprocess.run(['git','push'])..."` — the walker only re-parses