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

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

@@ -1,40 +1,26 @@
 /**
- * `git.worktree` — worktree policy (STATUS.md item 2, L2/L3;
+ * `git.worktree` — worktree policy (layers L2/L3 of
  * 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:
+ * Decided 2026-09-27 (Tarun): a ROUTE-when-possible, cap-aware policy, not a
+ * blanket deny of every worktree action:
  *
  *  - `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 add` — DENIED, with the precise `adl worktree add` command
+ *    to run instead. A silent rewrite to that command is not available to a
+ *    rule: `Severity` (`../spec.ts`) is only `'deny' | 'advise'` and
+ *    `Finding` carries no replacement-command field. The one rewrite the
+ *    engine does render (`Decision.rewrite` in `../engine.ts`, carrying the
+ *    session identity into network git commands) is computed by
+ *    `../shell/git-identity.ts`, not by a rule, and `../../hooks/lean-ctx/
+ *    scope-rewrite.ts` is a different hook (`lean-ctx hook rewrite`) with its
+ *    own envelope. So `add` gets the fallback docs/operations/agent-permissions.md's
+ *    Principles section names for an inexact rewrite: "An inexact rewrite is
+ *    a deny with the `adl` command to use. The hook never guesses."
  *  - `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

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

@@ -49,12 +49,12 @@ export function toolNameEndingWithKnownSuffix(tool: string, knownSuffixes: Reado
  * 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-run-required.ts, adl-pr-role.ts, adl-pr-complete-pending.ts,
  * adl-workitem-role.ts, adl-build-run-denied.ts) so the parsing cannot drift
  * 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
+ * Prefix-less fallback (added 2026-09-28 with the one-agent-identity
+ * standard): 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>` /

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

@@ -39,7 +39,7 @@ export function detailString(finding: Finding, key: string): string {
  * 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 =
+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 ' +

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

@@ -18,7 +18,7 @@
  * description, no completion fields), are both untouched by row 9.
  */
 
-export interface PrCreateOrUpdateInput {
+interface PrCreateOrUpdateInput {
   readonly action?: unknown
   readonly autoComplete?: unknown
   readonly mergeStrategy?: unknown

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

@@ -6,14 +6,13 @@
  * classification time (shell/invocation.ts's `walkToolCommand`); this rule
  * only ever sees the denied subset.
  *
- * WIDENED 2026-09-28 (STATUS.md 12p, W3 build item
- * 5): `az account get-access-token` and `az rest` targeting Azure DevOps are
+ * `az account get-access-token` and `az rest` targeting Azure DevOps are
  * NOT in `azureDevopsSubcommands` (`../shell/invocation.ts`), so they fall
  * through to the generic `'command'` kind (name `az`) rather than the
- * `'azure-devops'` kind this rule used to match exclusively — that let an
- * agent mint a bearer token from the HUMAN's own `az login` session and call
- * the Azure DevOps REST API directly, entirely outside the agent-identity
- * standard. Both are now denied here too, steering at the same MCP server /
+ * `'azure-devops'` kind — without a dedicated check an agent could mint a
+ * bearer token from the HUMAN's own `az login` session and call the Azure
+ * DevOps REST API directly, entirely outside the agent-identity standard.
+ * Both are denied here too, steering at the same MCP server /
  * `adl id token` path. `az account show` and every other `az account`
  * subcommand, and `az rest` against a non-Azure-DevOps host, are untouched.
  */
@@ -32,8 +31,8 @@ const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
 /**
  * Interpreter-ADO risk (independent review, 2026-09-29): python
  * requests/urllib, node fetch, ruby net/http, and perl LWP one-liners hitting
- * Azure DevOps directly are the SAME structural problem R6 closed for
- * curl/wget/httpie/xh — none of them can carry the resolved agent identity,
+ * Azure DevOps directly are the SAME structural problem as curl/wget/httpie/xh
+ * (denied outright in `match` below) — none of them can carry the resolved agent identity,
  * and any one can read `~/.netrc` or an ambient token exactly like curl's
  * `-n`/`--netrc*` does. `python`/`python3`/`ruby`/`perl`/`node`/`nodejs` (and
  * the Windows `.exe` spellings) are `inv.kind === 'command'` (unclassified by
@@ -41,18 +40,17 @@ const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
  * already sees them, it just never inspected their text for an Azure DevOps
  * host.
  *
- * P1 (second independent review, 2026-09-29): the FIRST version of this
- * check scanned `ctx.command` (the whole raw command line) for the ADO
- * host substring — matching it in ARGV too, not only inline code, which
- * wrongly denied `python3 -m pip install -i https://pkgs.dev.azure.com/...`
+ * The check deliberately does NOT scan `ctx.command` (the whole raw command line) for the ADO
+ * host substring: matching it in ARGV too, not only inline code, would
+ * wrongly deny `python3 -m pip install -i https://pkgs.dev.azure.com/...`
  * (an Azure Artifacts feed) and `node scripts/x.js --remote
  * https://dev.azure.com/...` (a flag on a script FILE run, not inline
- * code at all). Narrowed to `interpreterInlineCode`'s own `-c`/`-e`/
+ * code at all). It reads `interpreterInlineCode`'s own `-c`/`-e`/
  * `--eval[=]` argument value ONLY — coarse within that scope (a literal
  * `dev.azure.com`/`visualstudio.com` substring in the INLINE code is
  * enough, no attempt to verify a real HTTP call is actually made, matching
- * R6's own "curl to the URL is enough" coarseness), but no longer coarse
- * about WHERE it looks. `pkgs.dev.azure.com` (Azure Artifacts) stays IN
+ * the HTTP-client deny's "curl to the URL is enough" coarseness), but not
+ * coarse about WHERE it looks. `pkgs.dev.azure.com` (Azure Artifacts) stays IN
  * SCOPE when it DOES appear in inline code — `isAdoUrl`'s existing
  * `dev.azure.com` substring check already matches it.
  */
@@ -60,7 +58,7 @@ const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
  * The `-c`/`-e`/`--eval[=]` argument value for an interpreter invocation, or
  * null when the piece runs a script FILE or a module (`-m pip ...`) — argv
  * a script or module sees (a pip index URL, a `--remote` flag) is NOT this
- * rule's to inspect (P1, second independent review, 2026-09-29): only the
+ * rule's to inspect: only the
  * interpreter's own INLINE code can reach a host directly through that
  * interpreter's HTTP client; a script file's own argv is opaque to this
  * hook and denying on a mere URL-shaped argument would deny an ordinary
@@ -73,7 +71,7 @@ const AZ_NAMES: ReadonlySet<string> = new Set(['az', 'az.exe'])
  */
 /**
  * `name`-specific inline-code shapes beyond the common `-c`/`-e`/`--eval[=]`
- * (P2, independent review, 2026-09-29): php's own inline-eval flag is `-r`
+ * php's own inline-eval flag is `-r`
  * (not `-e`), and Deno's is a POSITIONAL argument after its `eval`
  * subcommand, no flag at all — neither fits the shared scan below.
  */
@@ -113,7 +111,6 @@ const INTERPRETER_NAMES: ReadonlySet<string> = new Set([
   'node.exe',
   'nodejs',
   'nodejs.exe',
-  // P2 (independent review, 2026-09-29).
   'bun',
   'bun.exe',
   'deno',
@@ -129,13 +126,12 @@ export const toolAzureDevops: RuleSpec = {
   severity: 'deny',
   enabledByDefault: true,
   summary:
-    'Deny direct az devops/repos/pipelines/boards/artifacts, az account get-access-token, az rest to Azure DevOps, and curl/wget/httpie/xh to Azure DevOps under every method (R6: reads included — curl cannot carry the agent identity); steer at adl mcp serve/cli.',
+    'Deny direct az devops/repos/pipelines/boards/artifacts, az account get-access-token, az rest to Azure DevOps, and curl/wget/httpie/xh to Azure DevOps under every method (reads included — curl cannot carry the agent identity); steer at adl mcp serve/cli.',
   params: noParams,
   match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
     if (inv.kind === 'command' && INTERPRETER_NAMES.has(inv.name)) {
       const code = interpreterInlineCode(inv.name, inv.args)
-      // Third independent review (2026-09-29): "heredoc-fed interpreters"
-      // (`python3 - <<'EOF' ... EOF`) have no -c/-e/--eval argument at all
+      // Heredoc-fed interpreters (`python3 - <<'EOF' ... EOF`) have no -c/-e/--eval argument at all
       // — the real code is the heredoc BODY, only visible in `ctx.command`.
       const candidates = code !== null ? [code] : heredocBodies(ctx.command ?? '')
       if (candidates.some((candidate) => isAdoUrl(candidate))) {
@@ -146,7 +142,7 @@ export const toolAzureDevops: RuleSpec = {
       return { ruleId: 'tool.azure-devops', severity: 'deny', detail: { reason: 'az-devops-family' } }
     }
     if (inv.kind === 'command' && AZ_NAMES.has(inv.name)) {
-      // M6 (STATUS.md 12p): a global flag
+      // A global flag
       // (`az --output json account get-access-token`) must not hide the
       // real subcommand from this check either — same skip
       // shell/invocation.ts's own `azureDevopsSubcommands` classification
@@ -160,23 +156,18 @@ export const toolAzureDevops: RuleSpec = {
         return { ruleId: 'tool.azure-devops', severity: 'deny', detail: { reason: 'az-rest-ado' } }
       }
     }
-    // R6 (STATUS.md 12p, re-review 2026-09-28 night,
-    // WIDENING M10/docs/operations/agent-permissions.md row 13 — a deliberate SPEC
-    // CHANGE, not a weakening: row 13 read "writes"; Tarun's own standard
-    // ("reads included") requires every Azure DevOps access to go through
-    // the resolved agent identity, and curl/wget/httpie/xh categorically
+    // Every curl/wget/httpie/xh call to Azure DevOps is denied, every method
+    // included (docs/operations/agent-permissions.md row 13). Tarun's
+    // standard ("reads included") requires every Azure DevOps access to go
+    // through the resolved agent identity, and these clients categorically
     // cannot carry one — the request authenticates with whatever the HUMAN
     // environment already supplies (`-n`/`--netrc*` reads `~/.netrc`, `-u`
     // is a literal credential on the command line, `-H Authorization`/`-K
     // <config-file>` read a header or config a human set up, a cached
-    // credential helper, …), regardless of `ADL_AGENT_ID_AGENT`. A GET was
-    // previously exempted here ("row 13 names writes specifically") on the
-    // theory that a plain read is harmless; R6's point is narrower and
-    // structural — it is not that a read is dangerous, it is that curl
-    // cannot prove WHICH identity performed it at all, so it is denied
-    // outright, identity or not, exactly like a write): every
-    // curl/wget/httpie/xh call to Azure DevOps is denied now, every method
-    // included. `adl.session-required-for-writes` already denies every
+    // credential helper, …), regardless of `ADL_AGENT_ID_AGENT`. The point
+    // is structural, not that a read is dangerous: the client cannot prove
+    // WHICH identity performed the call, so a GET is denied outright,
+    // identity or not, exactly like a write. `adl.run-required-for-writes` already denies every
     // method with NO identity at all; this is the unconditional net once an
     // identity IS present — a raw HTTP call cannot be rewritten to an exact
     // `adl` equivalent, so it is denied rather than routed, same as az CLI
@@ -198,11 +189,11 @@ export const toolAzureDevops: RuleSpec = {
         : reason === 'az-rest-ado'
           ? 'Blocked `az rest` against Azure DevOps: it authenticates as the human `az` login, not the resolved agent identity.'
           : reason === 'http-client-ado'
-            ? // L2/M10/R6: names the actual method and binary, and steers at
+            ? // Names the actual method and binary, and steers at
               // the real, current entry points — `adl mcp serve` (the MCP
               // server folded into the `adl` binary) and its `adl mcp cli`
-              // direct-CLI form — never a path that no longer exists. R6:
-              // every method, reads included — curl/wget/httpie/xh cannot
+              // direct-CLI form — never a path that no longer exists.
+              // Every method, reads included — curl/wget/httpie/xh cannot
               // carry the agent identity at all (any auth it uses, `-n`/
               // `--netrc*`, `-u`, `-H Authorization`, `-K`, is the human's).
               `Blocked \`${detailString(finding, 'name')} ${detailString(finding, 'method')}\` to Azure DevOps: a raw HTTP call cannot be translated exactly, and it authenticates outside the agent-identity standard entirely (this client cannot carry the resolved agent identity for any method, reads included).`
@@ -235,23 +226,22 @@ export const toolAzureDevops: RuleSpec = {
       'az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798',
       'az rest --method get --url https://dev.azure.com/org/_apis/projects',
       'az rest --url https://vssps.dev.azure.com/org/_apis/profile/profiles/me',
-      // M6 (STATUS.md 12p): a real az CLI global
+      // A real az CLI global
       // flag before the subcommand group must not hide it from this rule.
       'az --output json devops project list',
       'az -o table repos pr list --status active',
       'az --verbose account get-access-token',
       'az --output json rest --method get --url https://dev.azure.com/org/_apis/projects',
-      // M10 (STATUS.md 12p, docs/operations/agent-permissions.md
-      // row 13): curl/wget/httpie/xh WRITES to Azure DevOps, denied
+      // docs/operations/agent-permissions.md
+      // row 13: curl/wget/httpie/xh WRITES to Azure DevOps, denied
       // outright regardless of identity.
       'curl -X POST https://dev.azure.com/org/project/_apis/git/repositories',
       'curl -d "{}" https://dev.azure.com/org/project/_apis/git/repositories',
       'wget --method=POST https://dev.azure.com/org/project/_apis/git/repositories',
       'http POST https://dev.azure.com/org/project/_apis/git/repositories name=x',
       'xh PUT https://vssps.dev.azure.com/org/_apis/profile/profiles/me',
-      // R6 (STATUS.md 12p, re-review 2026-09-28 night):
-      // a plain GET/HEAD is now denied too — SPEC CHANGE from row 13's
-      // "writes" wording, not a weakening; see this file's own R6 comment.
+      // A plain GET/HEAD is denied too (reads included, not only writes);
+      // see the HTTP-client comment in `match` above.
       'curl https://dev.azure.com/org/project/_apis/git/repositories',
       'curl -X GET https://dev.azure.com/org/project/_apis/git/repositories',
       'wget https://dev.azure.com/org/project/_apis/git/repositories',
@@ -274,8 +264,7 @@ export const toolAzureDevops: RuleSpec = {
       'az storage account list',
       'az rest --method get --url https://management.azure.com/subscriptions',
       `python3 -c "print('hello')"`,
-      // P1 (second independent review, 2026-09-29): the ADO host in ARGV,
-      // not inline code, is not this rule's to inspect.
+      // The ADO host in ARGV, not inline code, is not this rule's to inspect.
       'python3 -m pip install -i https://pkgs.dev.azure.com/org/_packaging/feed/pypi/simple/',
       'node scripts/x.js --remote https://dev.azure.com/org/project',
     ],

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

@@ -8,18 +8,33 @@
  * is caught: at the start, after a pipe, after `&&`/`||`/`;`, inside
  * `$()`/backticks, after xargs, after sudo, and via a leading path — all of
  * that classification lives in shell/invocation.ts, not here.
+ *
+ * DENY TEXT (2026-10-03, after research-2026-10-02-search-tool-usage-across-surfaces
+ * finding #1):
+ *
+ *   - Earlier this text pointed every `find` denial at `search query "<text>"`,
+ *     but every `find` denial that day was a path pattern (`find -name '*.md'
+ *     -newermt '2026-10-01'`, `find ~/Documents -name 'code-review-graph*'`),
+ *     never a content search. The right tool for path patterns is `rg --files
+ *     -g '<glob>'` or `ctx_glob`. `search` only answers when the doc-tree case
+ *     is the question — and `find` can't tell which case it is, so we lead
+ *     with `rg --files -g '<glob>'` (the most common case) and put `search`
+ *     behind it as the docs/plans fallback.
+ *   - Recommendation rows come from `./deny-allowlist.ts` so the three
+ *     search-tool deny texts cannot drift from each other.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
+import { recommendationBlock } from './deny-allowlist.ts'
 
 export const toolFind: RuleSpec = {
   id: 'tool.find',
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny find unconditionally; steer at `search query "<text>"`.',
+  summary: 'Deny find unconditionally; steer at rg --files -g for path patterns and `search query "<text>"` only for docs/plans.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'find') return null
@@ -27,16 +42,23 @@ export const toolFind: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked find. It matches file PATHS/names only, never file contents, so piping it to grep filters filenames, not text - use `search query "<text>"` instead (/usr/local/bin/search; subcommands: index, prepare, query, doctor).',
+      user: 'Blocked find. It emits PATHS, never contents — pipe it to grep and you filter filenames. Use instead: `rg --files -g "<glob>"` for path patterns, `ctx_glob` for indexed file search, or `search query "<text>"` only when the path is `docs/`, `plans/`, or `.scratchpad/`.',
       agent:
         'DENIED find. `find` emits PATHS, so piping it to grep (or any other text tool) filters FILENAMES, never ' +
-        'file contents - that produces confidently wrong answers, not merely incomplete ones. For example, ' +
+        'file contents — that produces confidently wrong answers, not merely incomplete ones. For example, ' +
         "`find docs -name '*.md' | grep -iE 'kernel|ontology|metric'` matched only files whose NAME contained " +
         'those words; it missed docs/semantica-cleanup/superset-setup.md, the one document that actually ' +
-        'described the subject, while counting name-matches whose contents were irrelevant. ' +
-        'Use `search query "<text>"` instead - the machine-wide docs-search CLI shim at /usr/local/bin/search ' +
-        '(subcommands: index, prepare, query, doctor; e.g. `search query "how do I author a metric"`), which is ' +
-        `real content/hybrid search. Blocked command: ${ctx.snippet}`,
+        'described the subject, while counting name-matches whose contents were irrelevant.\n' +
+        'Match the tool to the question:\n' +
+        '  rg --files -g "<glob>" -g "!node_modules/**"    path patterns (default)\n' +
+        '  ctx_glob(pattern, path)                          indexed file search\n' +
+        '  search query "<text>"                            only when the path is docs/, plans/, or .scratchpad/ and the doc TALKS about X\n' +
+        '  crg search "<text>" --kind File                  code-graph search by name or text\n' +
+        'The full replacement table from `./deny-allowlist.ts`:\n' +
+        recommendationBlock(
+          (row) => row.binary === 'rg' || row.binary === 'search' || row.binary === 'crg' || row.binary === 'ctx_glob',
+        ) +
+        `Blocked command: ${ctx.snippet}`,
     }
   },
   corpus: {
@@ -77,6 +99,11 @@ export const toolFind: RuleSpec = {
       'rg -e find file.txt',
       'python3 -c "print(s.find(\'x\'))"',
       'node -e "str.find(\'x\')"',
+      // The replacements stay allowed.
+      'rg --files -g "*.md" -g "!node_modules/**"',
+      'rg --files -g "*.test.ts"',
+      'crg search "term" --kind File',
+      'ctx_glob "*.md"',
     ],
   },
 }

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

@@ -2,13 +2,15 @@
  * `grep`, unconditionally.
  *
  * Owner decision, 2026-09-15: ban the grep family outright and steer at
- * `rg` / `ast-grep` / `search` / `ctx_search`. Every replacement was measured
- * present and already passing the allowlist before the ban was written:
+ * `rg` / `ast-grep` / `search` / `crg` / `ctx_search`. Every replacement is
+ * measured present and passing its respective allowlist:
  *
  *   rg        /opt/homebrew/bin/rg        stdin filter AND tree search
  *   fd        10.4.2                      replaces find
  *   ast-grep  0.45.3                      structural search neither ever did
- *   search    /usr/local/bin/search       hybrid semantic + keyword
+ *   search    /usr/local/bin/search       hybrid semantic + keyword (per-repo allowlist)
+ *   crg       /usr/local/bin/crg          code-graph: callers/callees/impact
+ *   ctx_search / ctx_glob / ctx_read       lean-ctx MCP (per-repo allowlist)
  *
  * BLANKET, including a pure stdin filter. An earlier proposal carved out
  * `npm test 2>&1 | grep -E '…'` as "reading output, not searching code". That
@@ -26,18 +28,35 @@
  * `ls` is deliberately NOT denied. It shares `find`'s weakness — it answers
  * about names, never contents — but it is far more load-bearing for ordinary
  * work than the search tools this replaces.
+ *
+ * DENY TEXT (2026-10-03, after research-2026-10-02-search-tool-usage-across-surfaces
+ * finding #4):
+ *
+ *   - Earlier this text claimed "rg / ast-grep / search / crg / ctx_search
+ *     — all on PATH and already allowed". `search` and `crg` are NOT in
+ *     lean-ctx's default allowlist — they only pass on repos whose
+ *     `.agents/lean-ctx/config/lean-ctx/config.toml` declares them under
+ *     `shell_allowlist_extra`. The new text is honest about that and points
+ *     at per-repo config when relevant.
+ *   - The recommendation rows come from `./deny-allowlist.ts` so a single
+ *     edit to the allowed-tools table updates this text and `tool.find.ts`
+ *     and `tool.native-search.ts` at once. Adding `--glob '!'` advice at
+ *     the top of the block (per research §2) keeps the kimi-style
+ *     `rg -rg -v Y1 | grep -v Y2` chains from re-emerging as a "let me
+ *     refine my filter" behaviour.
  */
 
 import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
+import { recommendationBlock } from './deny-allowlist.ts'
 
 export const toolGrep: RuleSpec = {
   id: 'tool.grep',
   category: 'tool',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg / ctx_search.',
+  summary: 'Deny the grep family; steer at ast-grep / search / crg / rg / ctx_search (per-repo allowlist).',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'grep') return null
@@ -45,15 +64,14 @@ export const toolGrep: RuleSpec = {
   },
   message(_finding: Finding, ctx: MessageContext) {
     return {
-      user: 'Blocked grep. Pick the tool for the question: `ast-grep` for code shapes, `search` for docs by meaning, `crg` for callers and impact, `rg` for literal text, `ctx_search` for the indexed code search.',
+      user: 'Blocked grep. Pick the tool for the question, in this order: `ast-grep` for code shapes, `search` for docs/plans by meaning, `crg` for code-graph, `rg` for literal text (incl. stdin), `ctx_search` for the indexed code search.',
       agent:
-        'DENIED grep. Match the tool to the question - in this order, all on PATH and already allowed:\n' +
-        '  ast-grep  code STRUCTURE: shapes rather than strings (`ast-grep -p "foo($A)" -l ts`)\n' +
-        '  search    docs and plans by MEANING: hybrid semantic + keyword (`search query "<text>"`)\n' +
-        '  crg       the code GRAPH: callers, callees, impact (`crg query callers_of <fn>`, `crg impact`)\n' +
-        '  rg        LITERAL text or regex, including stdin: `npm test 2>&1 | rg "pass|fail"`\n' +
-        '  ctx_search  the indexed code search (action=symbol for an exact symbol)\n' +
-        'A pure output filter is no exception: `rg` reads stdin exactly as grep does. ' +
+        'DENIED grep. A pure `something | grep -v <X>` is still a grep — refine the upstream command with ' +
+        '`--glob \'!<X>\'` or `--type-not` instead of piping. Match the tool to the question - in this order:\n' +
+        recommendationBlock(
+          (row) => row.binary !== 'ctx_glob' && row.binary !== 'ctx_read' && row.binary !== 'ctx_compose',
+        ) +
+        '\nA pure output filter is no exception: ripgrep filters stdin exactly as grep does. ' +
         `Blocked command: ${ctx.snippet}`,
     }
   },
@@ -76,11 +94,15 @@ export const toolGrep: RuleSpec = {
     ],
     allow: [
       // The replacements must keep working — a ban with no escape route is a trap.
+      // Mirrors `ALLOWED_SEARCH_TOOLS` in `./deny-allowlist.ts`; adding a row
+      // there should land here too.
       'rg TODO src/',
       "npm test 2>&1 | rg 'pass|fail'",
+      "rg -n TODO src/ -g '!node_modules/**'",
       'fd -e ts src/',
       'ast-grep --version',
       'search query "how do I author a metric"',
+      'crg search TODO --kind File',
       'ls -la',
       // The word `grep` is not the command `grep`.
       'rg grep src/',

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

@@ -19,6 +19,20 @@
  * not hand-rolled search, and it is the tool `ctx_read` redirects through.
  * Edit/Write are untouched — this rule is about search surfaces only.
  *
+ * DENY TEXT (2026-10-03, after research-2026-10-02-search-tool-usage-across-surfaces
+ * found a 3/95 pivot rate and zero pivots to `search query` / `crg`):
+ *
+ *   - Earlier this text recommended `ctx_search`/`ctx_compose`/`ctx_callgraph`
+ *     and `rg / ast-grep` only. The model took the lean-ctx MCP path (3/3
+ *     pivots went there) and never reached for `search` (the enoted-search
+ *     binary that IS the right tool for `docs/`, `plans/`, `.scratchpad/`).
+ *   - The new text leads with the docs/plans case (the most common
+ *     search-tool denial in the kimi data: 11 of 25 were docs/plans) and
+ *     then names `crg search` (the graph tool) for code-graph queries,
+ *     then falls back to the lean-ctx MCP and rg/ast-grep.
+ *   - The recommendations come from `./deny-allowlist.ts` so a single edit
+ *     updates every rule's deny text.
+ *
  * Tool names are matched exactly and case-sensitively against each host's own
  * vocabulary, the same way `../../hooks/lean-ctx/mapping.ts` matches them —
  * Claude spells them `Grep`/`Glob`, and lowercase spellings appear in the
@@ -29,6 +43,7 @@ import type { Invocation } from '../shell/invocation.ts'
 import type { Finding, MessageContext, RuleSpec } from '../spec.ts'
 import { noParams } from '../spec.ts'
 import { loadSurfacePolicy } from '../../surface-policy.ts'
+import { ALLOWED_SEARCH_TOOLS, DOC_TREES, recommendationBlock } from './deny-allowlist.ts'
 
 /**
  * Search-shaped native tools. Mirrors the search half of the `redirect` route
@@ -41,25 +56,53 @@ export const toolNativeSearch: RuleSpec = {
   category: 'tool-call',
   severity: 'deny',
   enabledByDefault: true,
-  summary: 'Deny the native Grep/Glob/Search tools; steer at ctx_search and rg.',
+  summary: 'Deny the native Grep/Glob/Search tools; steer at search query (docs/plans), crg (code graph), ctx_search, rg, ast-grep.',
   params: noParams,
   match(inv: Invocation): Finding | null {
     if (inv.kind !== 'tool-call') return null
     if (!new Set(loadSurfacePolicy().deny.nativeTools).has(inv.tool)) return null
-    return { ruleId: 'tool.native-search', severity: 'deny', detail: { tool: inv.tool } }
+    // Surface the tool input's path-ish field for the message so it can
+    // recommend `search` (the right tool for docs/plans/.scratchpad) over
+    // `crg` (the right tool for code-graph queries). Different hosts name
+    // this field differently — Claude uses `path`, Codex uses `path`,
+    // Cursor uses `target_file` / `target_directory` for Write. The
+    // engine normalises nothing here, so we read every common spelling.
+    const detail: Record<string, string> = { tool: inv.tool }
+    const input = inv.input as Record<string, unknown>
+    const candidate = input.path ?? input.directory ?? input.target_directory ?? input.target_file
+    if (typeof candidate === 'string') {
+      detail.path = candidate
+    }
+    return { ruleId: 'tool.native-search', severity: 'deny', detail }
   },
   message(finding: Finding, ctx: MessageContext) {
     const tool = typeof finding.detail.tool === 'string' ? finding.detail.tool : 'this tool'
+    // Path-aware recommendation. Native Grep on docs/plans/.scratchpad ->
+    // lead with `search`; everywhere else -> lead with `crg`/`ctx_search`.
+    const path = typeof finding.detail.path === 'string' ? finding.detail.path : ''
+    const isDoc = DOC_TREES.some((prefix) => path.startsWith(prefix))
+
+    const leadTool = isDoc ? 'search' : 'crg'
+    const leadExamples = ALLOWED_SEARCH_TOOLS.find((row) => row.binary === leadTool)?.examples ?? []
+
+    const leadLines = leadExamples.map((e) => `    ${e}`).join('\n')
+
+    const tail = recommendationBlock(
+      (row) => row.binary !== leadTool && row.binary !== 'ctx_compose' && row.binary !== 'ctx_callgraph',
+    )
+
     return {
-      user: `Blocked the native ${tool} tool. Use ctx_search (indexed), or rg / ast-grep in a shell.`,
+      user: isDoc
+        ? `Blocked the native ${tool} tool on \`${path}\` (a docs/plans/.scratchpad tree). The right answer is \`search query "<text>"\` — semantic + keyword, finds the doc that *talks* about X. \`rg\`/\`crg\`/\`ctx_search\` are the wrong tools here.`
+        : `Blocked the native ${tool} tool. Lead with \`crg search "<text>"\` for code-graph queries, fall back to \`rg\`/\`ast-grep\` for literal text, \`ctx_search\` for indexed code, \`search query "<text>"\` only when the path is docs/plans/.scratchpad.`,
       agent:
         `DENIED the native ${tool} tool. It is routed through the lean-ctx hook but NOT converted — ` +
         'the call still runs natively — so it is a way around the shell search ban rather than an ' +
-        'alternative to it. Use instead:\n' +
-        '  ctx_search               indexed search; action=symbol for an exact symbol\n' +
-        '  ctx_compose              orient on a task without reading whole files\n' +
-        '  ctx_callgraph            callers/impact, which no text search answers\n' +
-        '  rg / ast-grep in Bash    when you genuinely need raw text or structural search\n' +
+        'alternative to it.\n' +
+        `Lead with the right tool for the surface:\n` +
+        `${leadLines}\n` +
+        `Then fall back as needed:\n` +
+        `${tail}\n` +
         `Blocked call: ${ctx.snippet}`,
     }
   },
@@ -74,4 +117,4 @@ export const toolNativeSearch: RuleSpec = {
       'cat src/index.ts',
     ],
   },
-}
+}

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

@@ -53,16 +53,14 @@ export interface RepoIndexPort {
   /** Expand Git URL rewrite rules for an explicit remote URL without contacting it. */
   resolveRemoteUrl(url: string, direction: 'fetch' | 'push'): string | null
   /**
-   * R4 (STATUS.md 12p, re-review 2026-09-28 night): the
-   * repo-configured value of `alias.<verb>` (`git config --get
+   * The repo-configured value of `alias.<verb>` (`git config --get
    * alias.<verb>`), or `null` when unset or unreadable — `adl.git-
    * credential-bypass` resolves an UNKNOWN git verb (not a built-in one this
    * repo's own classifier already recognizes) this way to see whether it is
-   * actually a network/credential operation in disguise, the same way
-   * `bin/git-ado` cannot: it routes on the literal argv verb, never
-   * resolving repo config itself. Optional — a fixture that predates this
-   * finding, or one that has no reason to exercise it, is not forced to
-   * implement it; a rule reading it treats `undefined` (the method itself
+   * actually a network/credential operation in disguise, because the
+   * `bin/git` front controller routes on the literal argv verb and never
+   * resolves repo config itself. Optional — a fixture with no reason to
+   * exercise it is not forced to implement it; a rule reading it treats `undefined` (the method itself
    * absent) the same as `null` (present, resolved to nothing).
    */
   configuredAlias?(verb: string): string | null