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

package/packages/agent-hooks/src/rules/impl/tool-lean-ctx-global.ts

@@ -0,0 +1,594 @@
+/**
+ * `tool.lean-ctx-global-state` — deny a `lean-ctx` subcommand that writes
+ * GLOBAL/user state instead of the repo-scoped state this estate actually
+ * enforces.
+ *
+ * Tarun's standing rule (`.scratchpad/FINISH_BRIEF.md`, this session):
+ * lean-ctx is REPO-LOCAL. Its config is per repository
+ * (`.agents/lean-ctx/config/lean-ctx/config.toml` by default, or wherever
+ * `[hooks] lean_ctx_dir` in `adl-config.toml` names — reached via
+ * `LEAN_CTX_CONFIG_DIR`, which `adl hook lean-ctx …` sets — see
+ * `../../lean-ctx/env.ts`), and no lean-ctx hook, shell hook, skill or MCP
+ * entry may live at user/global level. Global state kept coming back because
+ * lean-ctx's OWN subcommands re-inject it:
+ *  - `lean-ctx setup` (2026-09-14) injected an `exec lean-ctx -c
+ *    "$BASH_EXECUTION_STRING"` shell hook into `~/.bashenv` and wrote raw
+ *    `lean-ctx hook observe|rewrite|redirect|read-dedup` entries into
+ *    `~/.claude/settings.json`. `observe` must never run — Tarun does not
+ *    want data leaving the machine.
+ *  - The same setup put global `SKILL.md` copies into `~/.claude/skills`,
+ *    `~/.codex/skills`, `~/.cursor/skills` and `~/.config/opencode/skills`.
+ *  - `lean-ctx allow <cmd>` run with no `LEAN_CTX_CONFIG_DIR` writes the
+ *    GLOBAL `~/.config/lean-ctx/config.toml`, not the repo config that is
+ *    actually enforced — lean-ctx's own "blocked" message tells agents to
+ *    run exactly that.
+ *
+ * Independent review (this session) found and this file now closes six
+ * further gaps beyond the original pass — see each numbered comment below
+ * for the specific fix:
+ *  1. `-c`/`-t`/`exec`/`raw`/`bypass` ran an ARBITRARY command this rule
+ *     (and every OTHER rule) never inspected — fixed at the source, in
+ *     `../shell/invocation.ts`'s `walkLeanCtxExec`, not here: see that
+ *     file's own doc. `shell-invocation-lean-ctx-exec.test.ts` covers it.
+ *  2. A wrapper AFTER a valid `LEAN_CTX_CONFIG_DIR=` assignment (`env -u`,
+ *     `env -i`, `sudo`, …) defeated the `allow` exemption — see
+ *     `prefixHonorsExemption` below.
+ *  3. A redirection before the subcommand (`lean-ctx >/dev/null setup`)
+ *     bypassed the subcommand scan entirely — see the `withoutRedirections`
+ *     call in `match()` below.
+ *  4. (Closed for free by #1: once `-c`/`-t`/`exec`/`raw`/`bypass`'s
+ *     argument is parsed as the real inner script, this rule never sees a
+ *     `{kind:'command', name:'lean-ctx', args:['-c','npm','install']}`
+ *     shape to misread `install` out of at all.)
+ *  5. Several more global/account-state subcommands were unchecked
+ *     entirely — see `DENY_UNCONDITIONALLY`'s new entries and the
+ *     `security`/`daemon`/`filter`/`gain`/`cloud` two-level checks below.
+ *     `config set`/`tools <level>`/`profile set|create`/`compression
+ *     <level>`/`theme set|import` now join `allow` under the same
+ *     per-invocation repo-config-dir exemption.
+ *  6. The `LEAN_CTX_CONFIG_DIR` path exemption was suffix-only (`ends with
+ *     .agents/lean-ctx/config/lean-ctx` accepted ANY prefix, including
+ *     `..`-escaping ones and another repository's absolute path) — see
+ *     `isRepoScopedConfigDir` below, and `suffixFor`, which derives the
+ *     suffix from `[hooks] lean_ctx_dir` via `resolveLeanCtxDir`
+ *     (`../../lean-ctx/env.ts`) instead of a hard-coded constant.
+ *
+ * Not fixed here (documented, not silently dropped — see
+ * `docs/operations/agent-permissions.md` row 19's "Not covered yet"):
+ * `echo setup | xargs lean-ctx` (finding 7, LOW — pinned as a known gap,
+ * `rules-tool-lean-ctx-global.test.ts`); a handful of `lean-ctx`
+ * subcommands that touch a network account or a local proxy but were never
+ * named in the review (`proxy start`, `knowledge import`, `cloud pull`) —
+ * not guessed at, per "check each name against the real `help all`, don't
+ * guess"; a `LEAN_CTX_CONFIG_DIR=` value that is syntactically an
+ * assignment only because THIS scanner's `isAssignment` does not
+ * distinguish a fully-quoted word (`"NAME=value"`, which real bash does
+ * NOT treat as an assignment prefix at all) from a partially-quoted one
+ * (`NAME="value"`, which it does) — a narrower, separate tokenizer nuance,
+ * not one of the eight findings, outside this pass's scope; and `cd
+ * ../other && LEAN_CTX_CONFIG_DIR=$PWD/…`, where `$PWD` is textually
+ * accepted but this static scanner cannot know an earlier `cd` in the same
+ * chained command already moved it.
+ *
+ * Subcommand list is `lean-ctx help all`, v3.10.5 (every name below
+ * verified against the real binary this session, not guessed):
+ *  - `wrap`/`unwrap`/`onboard`/`setup`/`install` (incl. `install --repair`)/
+ *    `bootstrap` — the "setup family": every one of these can (re-)inject a
+ *    global shell hook, host settings entry, or skill copy.
+ *  - `init`, in any form (`init`, `init --global`, `init --agent X`,
+ *    `init --prompt`) — always denied regardless of its own flags.
+ *  - `doctor --fix`/`--fix=VALUE` only — plain `doctor`/`doctor --json` are
+ *    read-only and stay allowed (`../../cli/doctor.ts` itself runs
+ *    `lean-ctx doctor --json`).
+ *  - `update`/`uninstall`/`dev-install`/`enable-gpu`/`codesign-setup`.
+ *  - `plugin enable|disable|init` (`plugin list`/other subcommands allowed).
+ *  - `rules sync|init` (`rules list`/other subcommands allowed).
+ *  - `yolo` ("Disable containment: any path + any command"), `secure`
+ *    ("Restore secure defaults" — still a global security-posture toggle,
+ *    either direction, denied unconditionally), `security secrets <on|off>`
+ *    (a WRITE; bare `security`/`security status`, a READ, stays allowed),
+ *    `daemon enable|disable` (auto-start on login; `daemon
+ *    start|stop|restart|status` — process control, not global CONFIG state
+ *    — stays allowed), `filter init` (`filter list|validate` stay allowed),
+ *    `gain --reset`/`gain --publish` (every other `gain` flag is a local
+ *    read), `login <email>`, `register <email>`, `sync` (bare — "Sync
+ *    stats, plus your context when your plan includes synchronization"),
+ *    `cloud autosync <on|off>` (`cloud autosync status`/`cloud
+ *    status`/`cloud pull` stay allowed — see "Not fixed here" above for why
+ *    `pull` specifically is out of scope), `contribute` ("Share anonymized
+ *    compression data").
+ *  - `allow <cmd>`, `config set …`, `tools <level>` (`tools show`/`tools
+ *    list` stay allowed), `profile set|create …` (`profile
+ *    list|show|diff|suggest` stay allowed), `compression <level>`, `theme
+ *    set|import …` (`theme list|export` stay allowed) — ALL of these join
+ *    ONE shared exemption: allowed UNLESS THIS SPECIFIC invocation carries
+ *    its own inline `LEAN_CTX_CONFIG_DIR=` assignment resolving to the
+ *    repo-scoped config directory — see `exemptionKind` below. The
+ *    exemption is per-invocation, not per-command-line:
+ *    `LEAN_CTX_CONFIG_DIR=… lean-ctx allow a && lean-ctx allow b` denies
+ *    the SECOND call (it has no assignment of its own); a wrapper after
+ *    the assignment (finding 2) or a path outside the repo (finding 6)
+ *    voids it too.
+ *
+ * Read-only shapes are deliberately NOT matched at all (no branch below
+ * reaches them, so they fall through to allow, same as tool.azure-devops'
+ * `az account show`): `read`, `grep`, `find`, `ls`, `doctor`/`doctor
+ * --json`, `status`, `config` (bare, show), `--version`, `help`, `gain`
+ * (bare or with a read-only flag), `hook …` (the hook runner itself).
+ * `-c`/`-t`/`exec`/`raw`/`bypass` are NOT this rule's to judge AT ALL any
+ * more (finding 1) — their argument is parsed as the real inner command
+ * one level deeper, in `../shell/invocation.ts`, before this rule ever
+ * sees an Invocation for them.
+ *
+ * Invocation forms: `lean-ctx`, `/usr/local/bin/lean-ctx`, any path ending
+ * in `/lean-ctx` (e.g. `.agents/bin/lean-ctx`) all classify to the same
+ * `{kind:'command', name:'lean-ctx', ...}` for free — `shell/invocation.ts`'s
+ * `classify()` names a command by `basename()` (`../shell/token.ts`), which
+ * already strips any directory prefix and lowercases. `&&`/`;`/pipes,
+ * `env`/`sudo`/`command`/`exec` wrappers, and nested `bash -c`/`sh -c` are
+ * likewise already handled by the shared scanner (`shell/prefixes.ts`'s
+ * `skipPrefixes`, and `shell/invocation.ts`'s own recursive `parseScript`)
+ * before this rule ever sees an Invocation — nothing here re-parses any of
+ * that.
+ *
+ * `Invocation`'s `'command'` kind carries `prefix`: the exact tokens
+ * `skipPrefixes` consumed ahead of `lean-ctx` for THIS occurrence — a
+ * leading `NAME=value` assignment, a wrapper command and its own flags, or
+ * both. `&&`/`;` split into separate top-level pieces (each walked, and so
+ * each classified, on its own — `shell/invocation.ts`'s `parse()`), and a
+ * nested `bash -c '…'` script is walked the same way one level deeper
+ * (`parseScript`), so `prefix` is always scoped to the ONE `lean-ctx`
+ * occurrence this `Invocation` represents, never leaked from a sibling
+ * occurrence earlier or later on the same command line.
+ */
+
+import type { Invocation } from '../shell/invocation.ts'
+import { withoutRedirections } from '../shell/git-internals.ts'
+import type { Token } from '../shell/token.ts'
+import { isAssignment, tokenValue } from '../shell/token.ts'
+import type { Finding, MessageContext, RuleContext, RuleSpec } from '../spec.ts'
+import { noParams } from '../spec.ts'
+import { detailString } from './messages.ts'
+import { DEFAULT_LEAN_CTX_DIR, resolveLeanCtxDir } from '../../lean-ctx/env.ts'
+
+const LEAN_CTX_NAMES: ReadonlySet<string> = new Set(['lean-ctx', 'lean-ctx.exe'])
+
+/** Subcommands denied outright, regardless of any flag they carry — `install --repair` is still just `install`. */
+const DENY_UNCONDITIONALLY: ReadonlySet<string> = new Set([
+  'wrap',
+  'unwrap',
+  'onboard',
+  'setup',
+  'install',
+  'bootstrap',
+  'init',
+  'update',
+  'uninstall',
+  'dev-install',
+  'enable-gpu',
+  'codesign-setup',
+  // Finding 5 — every name below verified against the real `lean-ctx help
+  // all` (v3.10.5) this session.
+  'yolo',
+  'secure',
+  'login',
+  'register',
+  'sync',
+  'contribute',
+])
+
+/** The subset of `DENY_UNCONDITIONALLY` that specifically (re-)injects a global hook/shell-hook/skill — gets its own message. */
+const SETUP_FAMILY: ReadonlySet<string> = new Set(['wrap', 'unwrap', 'onboard', 'setup', 'install', 'bootstrap'])
+
+const PLUGIN_DENY_SUBCOMMANDS: ReadonlySet<string> = new Set(['enable', 'disable', 'init'])
+const RULES_DENY_SUBCOMMANDS: ReadonlySet<string> = new Set(['sync', 'init'])
+/** `daemon enable|disable` (auto-start on login) — `start|stop|restart|status` is process control, not this rule's concern. */
+const DAEMON_DENY_SUBCOMMANDS: ReadonlySet<string> = new Set(['enable', 'disable'])
+/** `tools [minimal|standard|power|show|list]` — `show`/`list` are reads; any other value sets the level. */
+const TOOLS_READ_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'list'])
+/** `profile [list|show|diff|create|set|suggest]` — only `create`/`set` write. */
+const PROFILE_WRITE_SUBCOMMANDS: ReadonlySet<string> = new Set(['create', 'set'])
+/** `theme [list|set|export|import]` — only `set`/`import` write. */
+const THEME_WRITE_SUBCOMMANDS: ReadonlySet<string> = new Set(['set', 'import'])
+
+interface Positional {
+  readonly value: string
+  readonly index: number
+}
+
+/**
+ * The first non-flag word in `args` from `from` onward, lower-cased. Every
+ * flag-shaped word is skipped on its own (coarse — lean-ctx has no
+ * value-taking global left for this scan to special-case: `-c`/`-t` are no
+ * longer reachable here at all, see the module doc's finding 1/4).
+ */
+function firstPositional(args: readonly Token[], from = 0): Positional | null {
+  let index = from
+  while (index < args.length) {
+    const value = tokenValue(args[index] as Token)
+    if (value.startsWith('-')) {
+      index += 1
+      continue
+    }
+    return { value: value.toLowerCase(), index }
+  }
+  return null
+}
+
+/**
+ * The value of the LAST `LEAN_CTX_CONFIG_DIR=` assignment among `prefix`
+ * (this invocation's own leading-assignment/wrapper tokens — see the module
+ * doc), or null when none is present. "Last wins" mirrors real shell
+ * semantics for repeated `NAME=value NAME=value cmd` assignments and for
+ * `env`'s own left-to-right operand processing.
+ */
+function leanCtxConfigDirValue(prefix: readonly Token[] | undefined): string | null {
+  if (prefix === undefined) return null
+  let value: string | null = null
+  for (const token of prefix) {
+    const text = tokenValue(token)
+    if (text.startsWith('LEAN_CTX_CONFIG_DIR=')) value = text.slice('LEAN_CTX_CONFIG_DIR='.length)
+  }
+  return value
+}
+
+/**
+ * Finding 2 (HIGH): "Honour the assignment only when every prefix token is
+ * an assignment, or a literal `env` followed only by assignments. Any
+ * other wrapper, or any env flag, voids the exemption." (coordinator, this
+ * session.)
+ *
+ * Implemented as: strip every assignment-shaped token from `prefix`
+ * (reusing `../shell/token.ts`'s own `isAssignment` — no second regex);
+ * what remains must be EMPTY (every token was an assignment) or exactly
+ * `['env']` (one literal wrapper name, nothing else — no flag, no other
+ * wrapper). Position-independent by design: `A=1 LEAN_CTX_CONFIG_DIR=…
+ * env B=2 lean-ctx …` honours the exemption exactly like `env
+ * LEAN_CTX_CONFIG_DIR=… lean-ctx …` does — `env`'s POSITION among a run of
+ * assignments does not matter, only that nothing ELSE is present.
+ */
+function prefixHonorsExemption(prefix: readonly Token[] | undefined): boolean {
+  if (prefix === undefined || prefix.length === 0) return false
+  const nonAssignments = prefix.filter((token) => !isAssignment(token)).map(tokenValue)
+  if (nonAssignments.length === 0) return true
+  return nonAssignments.length === 1 && nonAssignments[0] === 'env'
+}
+
+/**
+ * Finding 6 (MEDIUM): the suffix every accepted `LEAN_CTX_CONFIG_DIR` value
+ * must resolve to — DERIVED from `[hooks] lean_ctx_dir`
+ * (`resolveLeanCtxDir`, `../../lean-ctx/env.ts`) when a real repository
+ * root is known, never a hard-coded constant; falls back to
+ * `DEFAULT_LEAN_CTX_DIR` (no filesystem touched) only when `root` is empty
+ * or absent — a non-host caller (operator CLI, a test with no root) still
+ * gets a sensible, deterministic suffix rather than reading whatever
+ * `adl-config.toml` happens to sit under the current process's cwd.
+ */
+function suffixFor(root: string | undefined): string {
+  const dir = root !== undefined && root.length > 0 ? resolveLeanCtxDir(root) : DEFAULT_LEAN_CTX_DIR
+  return `${dir}/config/lean-ctx`
+}
+
+/**
+ * Finding 6 (MEDIUM): "Accept only: the bare suffix, `./<suffix>`,
+ * `$PWD/<suffix>`, `${PWD}/<suffix>`, or an absolute path equal to `<repo
+ * root>/<suffix>`. Take the repo root from the hook ctx." Plus: "Reject any
+ * `..` segment" — checked FIRST, unconditionally, so a value that only
+ * LOOKS like it ends in the suffix after a `..`-escape (`$HOME/.config/
+ * lean-ctx/../../.agents/lean-ctx/config/lean-ctx`) never reaches the
+ * per-form comparisons below at all.
+ */
+function isRepoScopedConfigDir(value: string, suffix: string, root: string | undefined): boolean {
+  if (value.split(/[\\/]/).some((segment) => segment === '..')) return false
+  const normalized = value.replace(/\/+$/, '')
+  if (normalized === suffix) return true
+  if (normalized === `./${suffix}`) return true
+  if (normalized === `$PWD/${suffix}`) return true
+  if (normalized === `\${PWD}/${suffix}`) return true
+  if (root !== undefined && root.length > 0) {
+    const repoPath = `${root.replace(/\/+$/, '')}/${suffix}`
+    if (normalized === repoPath) return true
+  }
+  return false
+}
+
+type ExemptionOutcome = 'exempt' | 'no-config-dir' | 'wrapper-voids' | 'wrong-config-dir'
+
+/**
+ * Precedence: whether ANY `LEAN_CTX_CONFIG_DIR=` is present at all
+ * (finding-2-agnostic — a bare wrapper with no assignment anywhere is
+ * simply "no-config-dir", not "a wrapper voided it"), THEN whether the
+ * prefix shape honours it (finding 2), THEN whether the value itself names
+ * the repo-scoped directory (finding 6).
+ */
+function exemptionKind(prefix: readonly Token[] | undefined, root: string | undefined): ExemptionOutcome {
+  const value = leanCtxConfigDirValue(prefix)
+  if (value === null) return 'no-config-dir'
+  if (!prefixHonorsExemption(prefix)) return 'wrapper-voids'
+  return isRepoScopedConfigDir(value, suffixFor(root), root) ? 'exempt' : 'wrong-config-dir'
+}
+
+type DenyKind = 'setup-family' | 'global-state' | 'allow-no-config-dir' | 'allow-wrapper-voids' | 'allow-wrong-config-dir'
+
+function findingFor(subcommand: string, kind: DenyKind, extra: Readonly<Record<string, string>> = {}): Finding {
+  return { ruleId: 'tool.lean-ctx-global-state', severity: 'deny', detail: { subcommand, kind, ...extra } }
+}
+
+/**
+ * The shared per-invocation repo-config-dir exemption — `allow`, `config
+ * set`, `tools <level>`, `profile set|create`, `compression <level>`,
+ * `theme set|import` all funnel through this one function (finding 5's
+ * "same exemption as allow"). `label` is the exact matched subcommand text
+ * shown in the message (`allow`, `config set`, `tools power`, …).
+ */
+function exemptableFinding(label: string, prefix: readonly Token[] | undefined, root: string | undefined): Finding | null {
+  const outcome = exemptionKind(prefix, root)
+  if (outcome === 'exempt') return null
+  const kind: DenyKind = outcome === 'no-config-dir' ? 'allow-no-config-dir' : outcome === 'wrapper-voids' ? 'allow-wrapper-voids' : 'allow-wrong-config-dir'
+  return findingFor(label, kind, { suffix: suffixFor(root) })
+}
+
+export const toolLeanCtxGlobalState: RuleSpec = {
+  id: 'tool.lean-ctx-global-state',
+  category: 'tool',
+  severity: 'deny',
+  enabledByDefault: true,
+  summary:
+    'Deny a lean-ctx subcommand that writes global/user state — the setup family, init, doctor --fix, update/uninstall/dev-install/enable-gpu/codesign-setup, plugin enable|disable|init, rules sync|init, yolo/secure/security secrets/daemon enable|disable/filter init/gain --reset|--publish/login/register/sync/cloud autosync/contribute, and allow/config set/tools/profile set|create/compression/theme set|import without a valid per-invocation LEAN_CTX_CONFIG_DIR= — lean-ctx is repo-local only.',
+  params: noParams,
+  match(inv: Invocation, ctx: RuleContext<Record<string, never>>): Finding | null {
+    if (inv.kind !== 'command' || !LEAN_CTX_NAMES.has(inv.name)) return null
+    // Finding 3 (MEDIUM): a redirection between `lean-ctx` and its first
+    // real argument must not hide the subcommand from either scan below.
+    const args = withoutRedirections(inv.args)
+    const sub = firstPositional(args)
+    if (sub === null) return null
+
+    if (DENY_UNCONDITIONALLY.has(sub.value)) {
+      return findingFor(sub.value, SETUP_FAMILY.has(sub.value) ? 'setup-family' : 'global-state')
+    }
+
+    if (sub.value === 'doctor') {
+      // Finding 8 (LOW): `--fix=true` must match too, not only the exact `--fix` token.
+      const hasFix = args.some((token) => tokenValue(token).startsWith('--fix'))
+      return hasFix ? findingFor('doctor --fix', 'global-state') : null
+    }
+
+    if (sub.value === 'plugin' || sub.value === 'rules') {
+      const second = firstPositional(args, sub.index + 1)
+      if (second === null) return null
+      const denySet = sub.value === 'plugin' ? PLUGIN_DENY_SUBCOMMANDS : RULES_DENY_SUBCOMMANDS
+      return denySet.has(second.value) ? findingFor(`${sub.value} ${second.value}`, 'global-state') : null
+    }
+
+    // Finding 5: `security secrets <on|off>` is a WRITE; bare `security`/`security status` is a READ.
+    if (sub.value === 'security') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && second.value === 'secrets' ? findingFor('security secrets', 'global-state') : null
+    }
+
+    // Finding 5: `daemon enable|disable` only — start/stop/restart/status is process control, not config state.
+    if (sub.value === 'daemon') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && DAEMON_DENY_SUBCOMMANDS.has(second.value) ? findingFor(`daemon ${second.value}`, 'global-state') : null
+    }
+
+    // Finding 5: `filter init` only — `filter list|validate` are reads.
+    if (sub.value === 'filter') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && second.value === 'init' ? findingFor('filter init', 'global-state') : null
+    }
+
+    // Finding 5: `gain --reset`/`gain --publish` only — every other gain flag is a local read.
+    if (sub.value === 'gain') {
+      const hit = args.some((token) => {
+        const value = tokenValue(token)
+        return value === '--reset' || value === '--publish' || value.startsWith('--publish=')
+      })
+      return hit ? findingFor('gain --reset/--publish', 'global-state') : null
+    }
+
+    // Finding 5: `cloud autosync <on|off>` only — `cloud autosync status`/`cloud status`/`cloud pull` are out of scope (see module doc).
+    if (sub.value === 'cloud') {
+      const second = firstPositional(args, sub.index + 1)
+      if (second === null || second.value !== 'autosync') return null
+      const third = firstPositional(args, second.index + 1)
+      return third !== null && third.value !== 'status' ? findingFor('cloud autosync', 'global-state') : null
+    }
+
+    // Finding 5: the shared per-invocation repo-config-dir exemption group.
+    if (sub.value === 'allow') return exemptableFinding('allow', inv.prefix, ctx.root)
+
+    if (sub.value === 'config') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && second.value === 'set' ? exemptableFinding('config set', inv.prefix, ctx.root) : null
+    }
+
+    if (sub.value === 'tools') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && !TOOLS_READ_SUBCOMMANDS.has(second.value) ? exemptableFinding(`tools ${second.value}`, inv.prefix, ctx.root) : null
+    }
+
+    if (sub.value === 'profile') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && PROFILE_WRITE_SUBCOMMANDS.has(second.value) ? exemptableFinding(`profile ${second.value}`, inv.prefix, ctx.root) : null
+    }
+
+    if (sub.value === 'compression') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null ? exemptableFinding(`compression ${second.value}`, inv.prefix, ctx.root) : null
+    }
+
+    if (sub.value === 'theme') {
+      const second = firstPositional(args, sub.index + 1)
+      return second !== null && THEME_WRITE_SUBCOMMANDS.has(second.value) ? exemptableFinding(`theme ${second.value}`, inv.prefix, ctx.root) : null
+    }
+
+    return null
+  },
+  message(finding: Finding, ctx: MessageContext) {
+    const subcommand = detailString(finding, 'subcommand')
+    const kind = detailString(finding, 'kind') as DenyKind
+
+    if (kind === 'setup-family' || kind === 'global-state') {
+      const specific =
+        kind === 'setup-family'
+          ? `\`lean-ctx ${subcommand}\` re-injects global hooks, shell hooks, or skills (~/.bashenv, ~/.claude/settings.json, ~/.claude/skills and the other hosts' skill directories) — that is Tarun's call only.`
+          : `\`lean-ctx ${subcommand}\` writes global/user lean-ctx state.`
+      return {
+        user: `Blocked \`lean-ctx ${subcommand}\`: global lean-ctx state is forbidden - lean-ctx is repo-local. ${specific}`,
+        agent:
+          `DENIED \`lean-ctx ${subcommand}\`. lean-ctx config is per-repository only ` +
+          '(reached via `LEAN_CTX_CONFIG_DIR` - see `packages/agent-hooks/src/lean-ctx/env.ts`); no lean-ctx ' +
+          `hook, shell hook, skill, or MCP entry may live at user/global level. ${specific} If a legitimate ` +
+          `global change is needed, ask the user to run it themselves. Blocked call: ${ctx.snippet}`,
+      }
+    }
+
+    // The three exemption-group kinds — all share the same repo-scoped remedy.
+    const suffix = detailString(finding, 'suffix')
+    const remedyTail = subcommand === 'allow' ? ' <cmd>' : ''
+    const remedyForm = `LEAN_CTX_CONFIG_DIR="$PWD/${suffix}" lean-ctx ${subcommand}${remedyTail}`
+    const specific =
+      kind === 'allow-no-config-dir'
+        ? `\`lean-ctx ${subcommand}\` with no inline \`LEAN_CTX_CONFIG_DIR=\` on THIS call writes GLOBAL/user lean-ctx state, not the repo config that is actually enforced.`
+        : kind === 'allow-wrapper-voids'
+          ? `\`LEAN_CTX_CONFIG_DIR\` is set earlier on the command line, but a wrapper after it (an \`env\` flag, \`sudo\`, or anything other than a literal \`env\` followed only by assignments) voids the exemption for THIS call.`
+          : `\`LEAN_CTX_CONFIG_DIR\` is set on THIS call, but does not resolve to the repo-scoped config directory (\`${suffix}\`) — that still writes state outside the repo config this estate enforces.`
+    const remedy =
+      ` Run it as \`${remedyForm}\` instead — that writes only the repo config. Every \`lean-ctx ${subcommand}\` ` +
+      `call needs its OWN inline assignment; one earlier in a chained command does not cover a later call.`
+    return {
+      user: `Blocked \`lean-ctx ${subcommand}\`: global lean-ctx state is forbidden - lean-ctx is repo-local. ${specific}${remedy}`,
+      agent:
+        `DENIED \`lean-ctx ${subcommand}\`. lean-ctx config is per-repository only ` +
+        '(reached via `LEAN_CTX_CONFIG_DIR` - see `packages/agent-hooks/src/lean-ctx/env.ts`); no lean-ctx ' +
+        `hook, shell hook, skill, or MCP entry may live at user/global level. ${specific}${remedy} If a ` +
+        `legitimate global change is needed, ask the user to run it themselves. Blocked call: ${ctx.snippet}`,
+    }
+  },
+  corpus: {
+    deny: [
+      'lean-ctx wrap',
+      'lean-ctx unwrap',
+      'lean-ctx onboard',
+      'lean-ctx setup',
+      'lean-ctx install',
+      'lean-ctx install --repair',
+      'lean-ctx bootstrap',
+      'lean-ctx init',
+      'lean-ctx init --global',
+      'lean-ctx init --agent codex',
+      'lean-ctx init --prompt',
+      'lean-ctx doctor --fix',
+      'lean-ctx doctor --fix=true',
+      'lean-ctx update',
+      'lean-ctx uninstall',
+      'lean-ctx dev-install',
+      'lean-ctx enable-gpu',
+      'lean-ctx codesign-setup',
+      'lean-ctx plugin enable foo',
+      'lean-ctx plugin disable foo',
+      'lean-ctx plugin init',
+      'lean-ctx rules sync',
+      'lean-ctx rules init',
+      'lean-ctx allow "git status"',
+      '/usr/local/bin/lean-ctx setup',
+      '.agents/bin/lean-ctx setup',
+      'sudo lean-ctx setup',
+      "bash -c 'lean-ctx setup'",
+      'echo hi && lean-ctx allow "git status"',
+      'timeout 30 lean-ctx allow "git status"',
+      // Per-invocation exemption gap: the assignment on the FIRST `allow`
+      // call does not cover a SECOND one later in the same command line.
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow a && lean-ctx allow b',
+      'env LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow a; lean-ctx allow b',
+      'lean-ctx allow a; LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow b',
+      "bash -c 'LEAN_CTX_CONFIG_DIR=\"$PWD/.agents/lean-ctx/config/lean-ctx\" lean-ctx allow a; lean-ctx allow b'",
+      // A `LEAN_CTX_CONFIG_DIR` that IS set on this exact call but does not
+      // end in the repo-scoped suffix still writes global/user state.
+      'LEAN_CTX_CONFIG_DIR=~/.config/lean-ctx lean-ctx allow "git status"',
+      'LEAN_CTX_CONFIG_DIR=/tmp/lean-ctx lean-ctx allow "git status"',
+      // Finding 2: a wrapper AFTER the assignment defeats it.
+      'LEAN_CTX_CONFIG_DIR=$PWD/.agents/lean-ctx/config/lean-ctx env -u LEAN_CTX_CONFIG_DIR lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=$PWD/.agents/lean-ctx/config/lean-ctx env -i lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=$PWD/.agents/lean-ctx/config/lean-ctx sudo lean-ctx allow x',
+      // Finding 3: a redirection before the subcommand.
+      'lean-ctx >/dev/null setup',
+      'lean-ctx 2>/dev/null allow x',
+      'lean-ctx 2>&1 setup',
+      // Finding 5: the new denylist.
+      'lean-ctx yolo',
+      'lean-ctx secure',
+      'lean-ctx security secrets off',
+      'lean-ctx daemon enable',
+      'lean-ctx filter init',
+      'lean-ctx gain --reset',
+      'lean-ctx gain --publish',
+      'lean-ctx login a@b.c',
+      'lean-ctx register a@b.c',
+      'lean-ctx sync',
+      'lean-ctx cloud autosync on',
+      'lean-ctx contribute',
+      'lean-ctx config set shell_hook true',
+      'lean-ctx tools power',
+      'lean-ctx profile set x',
+      'lean-ctx compression off',
+      'lean-ctx theme set x',
+      // Finding 6: path restrictions.
+      'LEAN_CTX_CONFIG_DIR=$HOME/.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=~/.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=/Users/x/Repos/other/.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=$HOME/.config/lean-ctx/../../.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+    ],
+    allow: [
+      'lean-ctx -c "$BASH_EXECUTION_STRING"',
+      'lean-ctx raw README.md',
+      'lean-ctx read README.md',
+      'lean-ctx grep pattern',
+      'lean-ctx doctor',
+      'lean-ctx doctor --json',
+      'lean-ctx status',
+      'lean-ctx config',
+      'lean-ctx --version',
+      'lean-ctx help',
+      'lean-ctx help all',
+      'lean-ctx gain',
+      'lean-ctx hook observe',
+      'lean-ctx plugin list',
+      'lean-ctx rules list',
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow "git status"',
+      // `env NAME=value` wrapper form is exempted the same as a bare leading assignment.
+      'env LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow "git status"',
+      // Chained/nested forms are allowed when EVERY occurrence carries its own valid assignment.
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow a && LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx allow b',
+      "bash -c 'LEAN_CTX_CONFIG_DIR=\"$PWD/.agents/lean-ctx/config/lean-ctx\" lean-ctx allow x'",
+      // Finding 5: reads stay allowed.
+      'lean-ctx security',
+      'lean-ctx security status',
+      'lean-ctx filter list',
+      'lean-ctx filter validate',
+      'lean-ctx daemon status',
+      'lean-ctx daemon start',
+      'lean-ctx cloud status',
+      'lean-ctx cloud autosync status',
+      'lean-ctx tools show',
+      'lean-ctx tools list',
+      'lean-ctx profile list',
+      'lean-ctx profile show',
+      'lean-ctx theme list',
+      'lean-ctx theme export',
+      // Finding 5: the exemption group WITH a valid assignment.
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx config set shell_hook true',
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx tools power',
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx profile set x',
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx compression off',
+      'LEAN_CTX_CONFIG_DIR="$PWD/.agents/lean-ctx/config/lean-ctx" lean-ctx theme set x',
+      // Finding 6: the accepted path forms.
+      'LEAN_CTX_CONFIG_DIR=${PWD}/.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+      'LEAN_CTX_CONFIG_DIR=./.agents/lean-ctx/config/lean-ctx lean-ctx allow x',
+      // Finding 7: the known, documented xargs gap (see module doc) — pinned as ALLOW.
+      'echo setup | xargs lean-ctx',
+    ],
+  },
+}