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

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

@@ -0,0 +1,77 @@
+/**
+ * The host's own `Grep` / `Glob` / `Search` tools, denied.
+ *
+ * WHY THIS EXISTS AT ALL, and why a shell-only grep ban is half a door:
+ * the lean-ctx hook ROUTES these tools but does not CONVERT them. Measured in
+ * this session's activity log:
+ *
+ *   PreToolUse  Read -> "lean-ctx hook redirect"    PASS
+ *   PostToolUse Read -> "lean-ctx hook read-dedup"  PASS
+ *
+ * the hook fires, exits 0, and the native call still executes and returns
+ * ordinary content. (Compare a Bash command, which comes back visibly
+ * compressed — that path really is rewritten.) So `../shell/invocation.ts`'s
+ * grep deny closes the shell while leaving `Grep` reachable as a native tool,
+ * and an agent blocked at one simply switches to the other. Denying only the
+ * shell buys friction, not behaviour change.
+ *
+ * `Read` is deliberately NOT denied: opening a file you can already name is
+ * not hand-rolled search, and it is the tool `ctx_read` redirects through.
+ * Edit/Write are untouched — this rule is about search surfaces only.
+ *
+ * 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
+ * other hosts' payloads.
+ */
+
+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'
+
+/**
+ * Search-shaped native tools. Mirrors the search half of the `redirect` route
+ * in `../../hooks/lean-ctx/mapping.ts`, deliberately WITHOUT the Read family
+ * (`Read`/`ReadFile`/`View`) or the directory-listing family
+ * (`ListFiles`/`ListDirectory`), which stay allowed.
+ */
+export const toolNativeSearch: RuleSpec = {
+  id: 'tool.native-search',
+  category: 'tool-call',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary: 'Deny the native Grep/Glob/Search tools; steer at ctx_search and rg.',
+  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 } }
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const tool = typeof finding.detail.tool === 'string' ? finding.detail.tool : 'this tool'
+    return {
+      user: `Blocked the native ${tool} tool. Use ctx_search (indexed), or rg / ast-grep in a shell.`,
+      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' +
+        `Blocked call: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    // Tool-call rules are exercised by test/unit/rules-tool-search.test.ts through
+    // decide({kind:'tool-call'}); the shell corpus below only has to prove that
+    // this rule never fires on a shell command, which is the mistake worth catching.
+    deny: [],
+    allow: [
+      'rg TODO src/',
+      'ls -la',
+      'cat src/index.ts',
+    ],
+  },
+}

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

@@ -0,0 +1,178 @@
+/**
+ * Ports the rule engine needs beyond the `Invocation` it is matching against.
+ *
+ * HARDCUT-narrowed from enact-repo-controls's `kernel/ports/index.ts` +
+ * `kernel/ports/live.ts`: adl hook is a pre-tool-use guard only, so it
+ * carries just the two ports `src/rules/impl/*.ts` actually consult —
+ * `fs.trash`'s `$HOME` check and `git.protected-tree-commit`'s real index
+ * read. The reference's `ProcessPort`/`HttpPort`/`ClockPort`/`Platform` exist
+ * there for a setup/deploy CLI (`controls setup`, `controls doctor`, release
+ * downloads) this package does not have.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { homedir } from 'node:os'
+
+export interface EnvPort {
+  get(name: string): string | undefined
+  home(): string
+}
+
+/**
+ * The agent identity that produced one tool call.
+ *
+ * Host payloads (verified for Claude Code's PreToolUse, this session) carry
+ * `agent_type` and `agent_id` only when a subagent is making the call — the
+ * main session has neither. `adl hook rules list` and the H2 rules consult
+ * these to enforce role-based denies (handoff 5, H2: rules 2 and 3).
+ *
+ * `liveAgent` reads the two fields off the hook payload; `noAgent` is the
+ * default a non-host caller (operator CLI, unit test) gets, which makes a
+ * missing agent identity indistinguishable from a main-session call rather
+ * than silently passing as a subagent — a rule that wants "no subagent at
+ * all" treats `type() === undefined` as that case.
+ */
+export interface AgentPort {
+  type(): string | undefined
+  id(): string | undefined
+}
+
+/**
+ * Read-only access to the repository's git index.
+ *
+ * `stagedPaths`/`trackedModifiedPaths` return `null` — never an empty array —
+ * when the read itself fails (not a git repository, git missing, etc.), so
+ * `git.protected-tree-commit` can fail closed on "could not read the index"
+ * instead of silently treating an unreadable index as a clean one.
+ */
+export interface RepoIndexPort {
+  stagedPaths(): readonly string[] | null
+  trackedModifiedPaths(): readonly string[] | null
+  /** All URLs Git will use for a named remote operation, or null when it cannot be resolved. */
+  remoteUrls(name: string, direction: 'fetch' | 'push'): readonly string[] | null
+  /** 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
+   * 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
+   * absent) the same as `null` (present, resolved to nothing).
+   */
+  configuredAlias?(verb: string): string | null
+}
+
+export const liveEnv: EnvPort = {
+  get: (name) => process.env[name],
+  home: () => homedir(),
+}
+
+export const noAgent: AgentPort = {
+  type: () => undefined,
+  id: () => undefined,
+}
+
+/** Build an AgentPort from a Claude Code / Codex / Cursor PreToolUse payload. */
+export function liveAgent(payload: Readonly<Record<string, unknown>>): AgentPort {
+  return {
+    type: () => {
+      const value = payload.agent_type
+      return typeof value === 'string' && value.length > 0 ? value : undefined
+    },
+    id: () => {
+      const value = payload.agent_id
+      return typeof value === 'string' && value.length > 0 ? value : undefined
+    },
+  }
+}
+
+/** Real git, read-only, scoped to `root`. */
+export function liveRepoIndex(root: string): RepoIndexPort {
+  type UrlRewrite = { readonly base: string; readonly kind: 'insteadOf' | 'pushInsteadOf'; readonly prefix: string }
+
+  const urlRewrites = (): readonly UrlRewrite[] | null => {
+    let out: string
+    try {
+      out = execFileSync('git', ['-C', root, 'config', '--get-regexp', '^url\\..*\\.(insteadof|pushinsteadof)$'], {
+        encoding: 'utf8',
+        timeout: 10_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+    } catch (error) {
+      if (typeof error === 'object' && error !== null && 'status' in error && error.status === 1) return []
+      return null
+    }
+    return out.split('\n').flatMap((line) => {
+      const separator = line.search(/\s/)
+      if (separator < 0) return []
+      const key = line.slice(0, separator)
+      const prefix = line.slice(separator).trim()
+      const match = /^url\.(.+)\.(insteadof|pushinsteadof)$/i.exec(key)
+      const base = match?.[1]
+      const rawKind = match?.[2]?.toLowerCase()
+      const kind = rawKind === 'insteadof' ? 'insteadOf' : rawKind === 'pushinsteadof' ? 'pushInsteadOf' : undefined
+      return base === undefined || kind === undefined || prefix.length === 0 ? [] : [{ base, kind, prefix }]
+    })
+  }
+
+  const rewriteUrl = (url: string, direction: 'fetch' | 'push'): string | null => {
+    const rewrites = urlRewrites()
+    if (rewrites === null) return null
+    const bestMatch = (kind: UrlRewrite['kind']): UrlRewrite | undefined =>
+      rewrites.filter((rewrite) => rewrite.kind === kind && url.startsWith(rewrite.prefix)).sort((left, right) => right.prefix.length - left.prefix.length)[0]
+    const rewrite = direction === 'push' ? bestMatch('pushInsteadOf') ?? bestMatch('insteadOf') : bestMatch('insteadOf')
+    return rewrite === undefined ? url : `${rewrite.base}${url.slice(rewrite.prefix.length)}`
+  }
+
+  const gitPaths = (args: readonly string[]): readonly string[] | null => {
+    try {
+      const out = execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        timeout: 10_000,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      return out.split('\n').filter((line) => line.length > 0)
+    } catch {
+      return null
+    }
+  }
+
+  return {
+    stagedPaths: () => gitPaths(['diff', '--cached', '--name-only']),
+    trackedModifiedPaths: () => gitPaths(['diff', '--name-only']),
+    remoteUrls: (name, direction) => {
+      try {
+        const args = ['-C', root, 'remote', 'get-url', ...(direction === 'push' ? ['--push'] : []), '--all', '--', name]
+        const out = execFileSync('git', args, {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        const urls = out.split('\n').filter((url) => url.length > 0)
+        return urls.length > 0 ? urls : null
+      } catch {
+        return null
+      }
+    },
+    resolveRemoteUrl: rewriteUrl,
+    configuredAlias: (verb) => {
+      try {
+        const out = execFileSync('git', ['-C', root, 'config', '--get', `alias.${verb}`], {
+          encoding: 'utf8',
+          timeout: 10_000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        })
+        const value = out.replace(/\n+$/, '')
+        return value.length > 0 ? value : null
+      } catch {
+        return null
+      }
+    },
+  }
+}

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

@@ -0,0 +1,233 @@
+/**
+ * The built-in rule registry.
+ *
+ * Ported from enact-repo-controls's `src/rules/registry.ts`. Order here is
+ * the evaluation order for a `'git'` Invocation (engine.ts iterates the
+ * registry once, in this order, and returns the first `Finding`). That order
+ * matters beyond readability: `git.hooks-path` and `git.core-bare` check
+ * `-c core.*=` GLOBALS, which can ride along with any subcommand, so they are
+ * tried before every subcommand-specific rule. Every other category's rules
+ * are mutually exclusive by `Invocation.kind`, so their relative order here
+ * is cosmetic.
+ *
+ * HARDCUT from the reference: `custom.ts` (repo-declared custom rules from
+ * `RulesSection.custom`) is not ported — `../gating/config.ts`'s
+ * `RulesConfig` has no `custom` field, so `BUILTIN_RULES` is the complete
+ * corpus for adl hook, not "built-in plus whatever `custom.ts` decoded".
+ * `registerAll`'s failure is a plain string, not the reference's
+ * `Result<_, ControlsError>` — there is no `kernel/result.ts` here and this
+ * check only ever runs over a static, developer-controlled array, so a
+ * failure here is a bug in this file, not a runtime condition a caller needs
+ * a structured error to branch on.
+ */
+
+import type { AnyRuleSpec, RuleId } from './spec.ts'
+import { asAnyRuleSpec, corpusIsEmpty } from './spec.ts'
+
+import { gitHooksPath, gitCoreBare } from './impl/git-core.ts'
+import { gitStash, gitClean, gitRebase, gitFilterBranch, gitRestore, gitReset, gitUpdateIndex } from './impl/git-transitions.ts'
+import { gitNoVerify, gitAmend } from './impl/git-verify.ts'
+import { gitProtectedTreeCommit } from './impl/git-protected-tree.ts'
+import {
+  gitBranchForceDelete,
+  gitTagDelete,
+  gitSwitchForce,
+  gitGcPrune,
+} from './impl/git-history.ts'
+import {
+  gitUpdateRef,
+  gitSymbolicRefWrite,
+  gitReadTree,
+  gitReplace,
+  gitFilterRepo,
+  gitReflogRewrite,
+  gitPrune,
+} from './impl/git-plumbing.ts'
+import { gitWorktree } from './impl/git-worktree.ts'
+import { gitRm, gitMvEscape, gitCheckoutDashDash } from './impl/git-paths.ts'
+import { fsGitInternals } from './impl/fs-git-internals.ts'
+import { fsRm } from './impl/fs-rm.ts'
+import { fsMv } from './impl/fs-mv.ts'
+import { fsCanonicalCheckout } from './impl/fs-canonical-checkout.ts'
+import { fsTrash } from './impl/fs-trash.ts'
+import { toolCargo } from './impl/tool-cargo.ts'
+import { toolBunTest } from './impl/tool-bun-test.ts'
+import { toolAzureDevops } from './impl/tool-azure-devops.ts'
+import { adlSessionRequiredForWrites } from './impl/adl-session-required.ts'
+import { adlHumanAzdoBypass } from './impl/adl-human-azdo-bypass.ts'
+import { adlGitCredentialBypass, adlSecurityKeychainAdo } from './impl/adl-git-credential-bypass.ts'
+import { adlGitPushBranchPolicy } from './impl/adl-git-push-policy.ts'
+import { adlGitIdentity } from './impl/adl-git-identity.ts'
+import { adlTokenMintingRole } from './impl/adl-token-minting-role.ts'
+import { adlPrCreateUpdateRole } from './impl/adl-pr-role.ts'
+import { adlPrReviewRole } from './impl/adl-pr-review-role.ts'
+import { adlPrCompletePendingDecision } from './impl/adl-pr-complete-pending.ts'
+import { adlWorkitemRequiresTarunOrVivek } from './impl/adl-workitem-role.ts'
+import { adlBuildRunDenied } from './impl/adl-build-run-denied.ts'
+import { toolFind } from './impl/tool-find.ts'
+import { toolGrep } from './impl/tool-grep.ts'
+import { toolNativeSearch } from './impl/tool-native-search.ts'
+import { toolFrontend } from './impl/tool-frontend.ts'
+import { toolChmodHookDisarm } from './impl/tool-chmod-hook.ts'
+import { toolLeanCtxGlobalState } from './impl/tool-lean-ctx-global.ts'
+import { shellRemoteScriptExec } from './impl/shell-remote-script-exec.ts'
+import { parseUncertain } from './impl/parse-uncertain.ts'
+import { advisoryFinder } from './impl/advisory-finder.ts'
+import { advisoryCoverage } from './impl/advisory-coverage.ts'
+import { agentSecretsStayUnread } from './impl/agent-secrets-stay-unread.ts'
+import { agentTamperProtection } from './impl/agent-tamper-protection.ts'
+
+/**
+ * The 27 git rules, in `blockedGitReason`'s precedence order (plus the
+ * plumbing rules from git-plumbing.ts, slotted in beside the history rules) — see the
+ * module doc. Read this array top to bottom to answer "if a command trips
+ * two of these, which one reports?"
+ */
+export const GIT_RULES: readonly AnyRuleSpec[] = [
+  gitHooksPath,
+  gitCoreBare,
+  gitStash,
+  gitClean,
+  gitRebase,
+  gitFilterBranch,
+  gitRestore,
+  gitReset,
+  gitUpdateIndex,
+  gitNoVerify,
+  gitAmend,
+  gitProtectedTreeCommit,
+  gitBranchForceDelete,
+  gitTagDelete,
+  gitSwitchForce,
+  gitWorktree,
+  gitUpdateRef,
+  gitSymbolicRefWrite,
+  gitReadTree,
+  gitReplace,
+  gitFilterRepo,
+  gitReflogRewrite,
+  gitPrune,
+  gitGcPrune,
+  gitRm,
+  gitMvEscape,
+  gitCheckoutDashDash,
+].map(asAnyRuleSpec)
+
+export const FILESYSTEM_RULES: readonly AnyRuleSpec[] = [fsGitInternals, fsRm, fsMv, fsTrash, fsCanonicalCheckout].map(asAnyRuleSpec)
+
+export const TOOL_RULES: readonly AnyRuleSpec[] = [
+  toolCargo,
+  toolBunTest,
+  toolAzureDevops,
+  toolFind,
+  toolGrep,
+  toolNativeSearch,
+  toolFrontend,
+  toolChmodHookDisarm,
+  toolLeanCtxGlobalState,
+  shellRemoteScriptExec,
+  // Before everything else identity-related: an agent setting the human
+  // pass-through marker itself is the most fundamental problem (decisions
+  // 1/1b/1c) — it gets its own specific message rather than being shadowed
+  // by a "no identity"/"protected branch"/credential-bypass one.
+  adlHumanAzdoBypass,
+  // Before adl.session-required-for-writes: an absolute-binary/remote-
+  // update/submodule/credential-helper bypass is the more fundamental
+  // problem (it sidesteps bin/git-ado's routing regardless of whether an
+  // identity would otherwise resolve), so it gets its own specific message
+  // rather than being shadowed by the generic "no identity" one.
+  adlGitCredentialBypass,
+  adlSecurityKeychainAdo,
+  adlSessionRequiredForWrites,
+  adlGitPushBranchPolicy,
+  // After the push policies: it rewrites what they allow, and denies the
+  // identity conflicts (inline override / sudo wrapper) those rules ignore.
+  adlGitIdentity,
+  // After adl.git-identity: token minting only sees a command that already
+  // has SOME conflict-free identity (adl.git-identity's own conflicts are
+  // reported first) — see adl-token-minting-role.ts's header.
+  adlTokenMintingRole,
+  adlPrCreateUpdateRole,
+  adlPrReviewRole,
+  adlPrCompletePendingDecision,
+  adlWorkitemRequiresTarunOrVivek,
+  adlBuildRunDenied,
+].map(
+  asAnyRuleSpec,
+)
+
+export const UNCERTAIN_RULES: readonly AnyRuleSpec[] = [parseUncertain].map(asAnyRuleSpec)
+
+export const ADVISORY_RULES: readonly AnyRuleSpec[] = [advisoryFinder, advisoryCoverage].map(asAnyRuleSpec)
+
+/**
+ * Handoff 5 agent-identity rules — placed BEFORE `FILESYSTEM_RULES` so the
+ * shared `denied-path` mechanism (engine.ts's classifyConfigFor adds the
+ * security paths) is claimed by `agent.secrets-stay-unread` rather than by
+ * `fs.canonical-checkout`, which denies the same kind for `~/enact-vps` only.
+ *
+ * HARDCUT (2026-09-27): the Handoff 5 Agent-Vault identity mechanism
+ * (`agent.no-plain-git-to-azure-devops`, `agent.vault-must-match-subagent`,
+ * `agent.role-actions` — host-payload `agent_type`/`agent_id` +
+ * `AGENT_VAULT_*` env triad) was removed. It gated Azure DevOps access
+ * unconditionally on `AGENT_VAULT_VAULT`, ran BEFORE every `adl.*` rule in
+ * `BUILTIN_RULES`, and did not know about adl's own identity mechanism
+ * (`ADL_AGENT_ID_AGENT`, `adl.session-required-for-writes`,
+ * `adl.git-push-branch-policy`) — the two mechanisms conflicted and the
+ * Agent-Vault one intercepted first, regressing adl's tested behaviour. Only
+ * `agent.secrets-stay-unread` and `agent.tamper-protection` survive; neither
+ * consults `AgentPort`/`ctx.agent`.
+ */
+export const AGENT_RULES: readonly AnyRuleSpec[] = [agentSecretsStayUnread, agentTamperProtection].map(asAnyRuleSpec)
+
+/** Every built-in rule, in evaluation order. There is no `custom.ts` corpus to append — see the module doc. */
+export const BUILTIN_RULES: readonly AnyRuleSpec[] = [
+  ...UNCERTAIN_RULES,
+  ...AGENT_RULES,
+  ...GIT_RULES,
+  ...FILESYSTEM_RULES,
+  ...TOOL_RULES,
+  ...ADVISORY_RULES,
+]
+
+export type RegisterResult =
+  | { readonly ok: true; readonly value: ReadonlyMap<RuleId, AnyRuleSpec> }
+  | { readonly ok: false; readonly error: string }
+
+/**
+ * Validate a set of rules and index them by id.
+ *
+ * Fails on an empty corpus (a rule with nothing to prove it does anything —
+ * see spec.ts's `corpusIsEmpty`) or a duplicate id. Called once, at module
+ * load, over `BUILTIN_RULES` — see `../pre-tool-use/handler.ts`.
+ */
+export function registerAll(rules: readonly AnyRuleSpec[]): RegisterResult {
+  const byId = new Map<RuleId, AnyRuleSpec>()
+  for (const rule of rules) {
+    if (corpusIsEmpty(rule)) {
+      return { ok: false, error: `rule '${rule.id}' registered with an empty corpus` }
+    }
+    if (byId.has(rule.id)) {
+      return { ok: false, error: `duplicate rule id registered: '${rule.id}'` }
+    }
+    byId.set(rule.id, rule)
+  }
+  return { ok: true, value: byId }
+}
+
+/** Look up one built-in rule by id — used by tests that want a single RuleSpec in isolation. */
+export function builtinRule(id: RuleId): AnyRuleSpec | undefined {
+  return BUILTIN_RULES.find((rule) => rule.id === id)
+}
+
+/**
+ * `registerAll`, throwing on failure. A registration failure can only come
+ * from a bug in `BUILTIN_RULES` itself, never from a repository's config, so
+ * callers (`../pre-tool-use/handler.ts` at module load, `../cli/rules.ts`)
+ * treat it as a crash rather than a per-invocation result.
+ */
+export function requireRegistered(rules: readonly AnyRuleSpec[]): ReadonlyMap<RuleId, AnyRuleSpec> {
+  const registered = registerAll(rules)
+  if (!registered.ok) throw new Error(`adl hook: rule registration failed: ${registered.error}`)
+  return registered.value
+}