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

package/packages/agent-hooks/src/gating/config.ts

@@ -0,0 +1,514 @@
+/**
+ * `adl-config.toml` — the per-repo gate for the adl hook runtime.
+ *
+ * HARDCUT replacement for enact-repo-controls's `.agents/controls.toml`
+ * (`src/kernel/config/schema.ts` + `decode.ts` + `effective.ts`): this file
+ * carries only what the hook runtime itself needs to decide whether to run
+ * and which rules to enforce. It does not carry surfaces, features, paths,
+ * hosts, or test sections — those belong to adl-extensions, not here.
+ *
+ * `adl-config.toml` is shared with other tools at the same root: adl hook
+ * owns `[hooks]`, `[rules]`, and `[repo]`; `adl-repo-controls` owns
+ * `[controls]`; `adl-extensions` owns `[extensions]` (and, before its
+ * HARDCUT, `[skills]`). `[controls]` and `[skills]` are recognized root tables
+ * this module accepts and never reads into.
+ *
+ * `[extensions]` is the one exception, and a deliberate one: its sub-table
+ * KEYS are decoded into `AdlRepoConfig.extensions`. Since adl-extensions
+ * retired the shared `.agents/skills/` pool for one plugin root per host
+ * namespaced by extension, that roster is the only way to know where this
+ * repo's skill corpus lives — see `../hooks/user-prompt-submit/skill-roots.ts`
+ * for why it is read rather than globbed. Their VALUES are still never read.
+ *
+ * Format:
+ *
+ *   [hooks]
+ *   enabled = true            # default true; false disables every hook kind
+ *                              # (pre-tool-use, user-prompt-submit, briefing,
+ *                              # crg) for this repo: exit 0, empty stdout/stderr.
+ *   skills_dir = ".agents/skills"  # optional; see src/hooks/user-prompt-submit
+ *   lean_ctx_dir = ".agents/lean-ctx"  # optional; repo-relative root for
+ *                              # lean-ctx's own config/data/state/cache dirs
+ *                              # (see src/lean-ctx/env.ts). A throwaway repo
+ *                              # — a binary test fixture, say — sets this so
+ *                              # lean-ctx's state, and any daemon it starts
+ *                              # off that state, lands somewhere disposable
+ *                              # instead of the default.
+ *
+ *   [rules]
+ *   default = "on"             # "on" | "off"; baseline for rules with no
+ *                              # explicit [rules."<id>"] entry
+ *   unsafeAllowUncertain = false
+ *
+ *   [rules."rm-smoke"]
+ *   enabled = false
+ *
+ *   [repo]
+ *   protectedTrees = [".agents/"]
+ *   trustedScriptPrefixes = [".agents/hooks/"]
+ *
+ * `[repo]` is an additive extension beyond the module's original scope: the
+ * rule corpus ported from enact-repo-controls's `src/rules/impl/*.ts` (see
+ * `../rules/spec.ts`'s `RuleContext.repo`) needs `protectedTrees` (which
+ * trees `git commit`/`git mv`/`mv` must not touch or move out of the repo)
+ * and `trustedScriptPrefixes` (which repo-relative script paths an agent may
+ * execute without inspection) to reproduce the reference's
+ * `git.protected-tree-commit`, `git.mv-escape`, and `fs.mv` behaviour. Both
+ * default to enact-repo-controls's own `DEFAULT_CONFIG.repo` values
+ * (`kernel/config/defaults.ts`) so a repo that omits `[repo]` entirely still
+ * gets the same protection the reference ships out of the box.
+ *
+ * Rule resolution mirrors enact-repo-controls's `isRuleEnabled`
+ * (`src/kernel/config/effective.ts`) exactly: an explicit
+ * `[rules."<id>"] enabled` always wins; failing that, `rules.default = "off"`
+ * disables every rule not explicitly re-enabled, while `"on"` (the default)
+ * leaves each rule at whatever default its own spec declares
+ * (`enabledByDefault`). A rule in the `uncertain` category additionally
+ * cannot resolve to disabled unless `unsafeAllowUncertain` is set.
+ */
+
+import { MARKER } from './root.ts'
+
+export interface RuleSection {
+  readonly enabled: boolean
+}
+
+export interface RulesConfig {
+  readonly default: 'on' | 'off'
+  readonly unsafeAllowUncertain: boolean
+  readonly byId: Readonly<Record<string, RuleSection>>
+}
+
+export interface HooksConfig {
+  readonly enabled: boolean
+  readonly skillsDir: string | undefined
+  /** Repo-relative root for lean-ctx's config/data/state/cache; see `../lean-ctx/env.ts`. */
+  readonly leanCtxDir: string | undefined
+}
+
+/**
+ * The pieces of enact-repo-controls's `RepoSection` the rule corpus actually
+ * consults — see this file's header for why `[repo]` exists here at all.
+ */
+export interface RepoSection {
+  /**
+   * Trees a file may not be moved OUT of (`fs.mv`, `git.mv-escape`). Deleting
+   * is already denied outright by `fs.rm`/`fs.trash`, so a move is the only
+   * remaining way to make a file in one of these trees stop taking effect.
+   */
+  readonly protectedTrees: readonly string[]
+  /**
+   * Paths that may not be COMMITTED (`git.protected-tree-commit`). Separate
+   * from `protectedTrees` since 2026-09-15: `.agents/` holds files agents
+   * legitimately change and must be able to commit (`adl-repo.lock.json`,
+   * the lean-ctx config), while still being a tree nothing may be moved out
+   * of. One list could not express both.
+   */
+  readonly commitProtectedTrees: readonly string[]
+  readonly trustedScriptPrefixes: readonly string[]
+}
+
+/**
+ * Handoff 5 agent-identity config — needed by `agent.vault-must-match-subagent`
+ * (rule 2) and `agent.role-actions` (rule 3). Lives under `[agent]` at the
+ * root of `adl-config.toml` so the file's owner does not have to edit the
+ * hook's own `[hooks]` / `[rules]` / `[repo]` sections to enable H2.
+ */
+export interface AgentSection {
+  /**
+   * The OS user this checkout belongs to, used to compute the executor's
+   * expected vault name (`agent-<user>`). The handoff's table for rule 2:
+   * `tarun → agent-tarun`, `vivek → agent-vivek`. Absent (or empty) means
+   * the repo did not declare a user; rule 2 denies any vault the
+   * subagent names in that case — the safe default — and rule 3 falls
+   * back to the built-in protected-branch list below.
+   */
+  readonly user: string
+  /**
+   * Branches an `executor` subagent may NOT push to. Default
+   * `["main", "integration"]` matches the `[controls]` branch policy the
+   * repo already ships with; the handoff's wider fleet also lists
+   * `develop`, which is not used by adl hook itself.
+   */
+  readonly protectedBranches: readonly string[]
+}
+
+export interface AdlRepoConfig {
+  readonly hooks: HooksConfig
+  readonly rules: RulesConfig
+  readonly repo: RepoSection
+  readonly agent: AgentSection
+  /**
+   * Extension names declared in `[extensions]`, in file order — the roster
+   * adl-extensions writes on install and removes on uninstall.
+   *
+   * This module reads only the sub-table KEYS, never their contents. It is the
+   * one place adl hook looks at another owner's table, and it is deliberate:
+   * since `.agents/skills/` was retired, "which extensions are installed" is
+   * the only way to know where this repo's skill corpus lives (see
+   * `../hooks/user-prompt-submit/skill-roots.ts`). A glob over plugin roots
+   * would also pick up a root a failed uninstall left behind.
+   */
+  readonly extensions: readonly string[]
+}
+
+export type ConfigDecodeIssue = { readonly pointer: string; readonly message: string }
+
+export type ConfigDecodeResult =
+  | { readonly ok: true; readonly value: AdlRepoConfig }
+  | { readonly ok: false; readonly issue: ConfigDecodeIssue }
+
+/** Matches enact-repo-controls's own `kernel/config/defaults.ts` `DEFAULT_CONFIG.repo`. */
+const DEFAULT_REPO: RepoSection = {
+  // Owner decisions, 2026-09-15:
+  //  - `.code-quality/` removed everywhere; this fleet does not use that tree.
+  //  - `.agents/` stays move-protected but is no longer commit-protected:
+  //    it holds `adl-repo.lock.json` and the lean-ctx config that the
+  //    extension installer rewrites, so blocking commits fired on the ordinary
+  //    path. Moving a hook out of it is still denied.
+  protectedTrees: ['.agents/', MARKER],
+  // MARKER alone: `adl-config.toml` is the kill switch -- a repo without it
+  // is unmanaged (gating/root.ts `resolveManagedRepo`) and the hook stands
+  // down, so a committable marker would let an agent switch off its own gate.
+  commitProtectedTrees: [MARKER],
+  trustedScriptPrefixes: ['workflows/scripts/', '.agents/hooks/'],
+}
+
+/**
+ * Handoff 5 agent defaults — empty user (rule 2 denies any vault in that
+ * case), and the two branches the repo's own `[controls] branches.protected`
+ * already lists.
+ */
+const DEFAULT_AGENT: AgentSection = {
+  user: '',
+  protectedBranches: ['main', 'integration'],
+}
+
+const DEFAULT_CONFIG: AdlRepoConfig = {
+  hooks: { enabled: true, skillsDir: undefined, leanCtxDir: undefined },
+  rules: { default: 'on', unsafeAllowUncertain: false, byId: {} },
+  repo: DEFAULT_REPO,
+  agent: DEFAULT_AGENT,
+  extensions: [],
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Reject a table carrying any key outside `known` — the shared "unknown keys
+ * fail loud" check every section below runs before decoding its own known
+ * fields. A typo'd or forward-looking key (e.g. `[hooks] enable = true`, the
+ * missing `d`) must never be silently ignored: this package has no separate
+ * `surfacesAudit`/schema-migration layer to catch it later, so a config that
+ * does not do what its author intended has to fail at decode time instead.
+ */
+function rejectUnknownKeys(
+  value: Readonly<Record<string, unknown>>,
+  known: ReadonlySet<string>,
+  pointer: string,
+): ConfigDecodeIssue | null {
+  const unknown = Object.keys(value).filter((key) => !known.has(key))
+  if (unknown.length === 0) return null
+  const expected = [...known].sort().join(', ')
+  return {
+    pointer: unknown.length === 1 ? `${pointer}/${unknown[0]}` : pointer,
+    message: `unknown key(s) ${unknown.map((k) => `'${k}'`).join(', ')} (expected one of: ${expected})`,
+  }
+}
+
+/**
+ * Top-level keys `decodeConfig` recognizes. `version` is accepted (and
+ * ignored) only so the marker file's own minimal `version = 1\n` convention
+ * stays valid — this package has no schema migrations to gate on it.
+ * controls/skills: see module header for ownership.
+ */
+/**
+ * Root tables this module accepts. It owns `version`/`hooks`/`rules`/`repo`
+ * and never reads the rest — they belong to the other tools sharing this file:
+ * `controls` to adl-repo-controls, and `extensions` (formerly `skills`) to
+ * adl-extensions.
+ *
+ * `skills` is retained alongside `extensions` on purpose. adl-extensions
+ * HARDCUT to `[extensions]` because an extension owns its skills rather than
+ * the reverse, and nothing writes `[skills]` any more — but a repo installed
+ * before that change still carries one until it is reinstalled. Dropping it
+ * here would fail exactly those repos, the ones nobody has touched yet.
+ */
+const KNOWN_ROOT_KEYS: ReadonlySet<string> = new Set([
+  'version', 'hooks', 'rules', 'repo', 'agent', 'controls', 'skills', 'extensions',
+])
+
+/**
+ * Parse `adl-config.toml`'s already-read text into an
+ * `AdlRepoConfig`. Parse-don't-validate: a key with the wrong shape is a
+ * decode error (the caller fails loud), a key simply absent falls back to
+ * `DEFAULT_CONFIG`. A key nowhere in the schema — at the document root or
+ * inside `[hooks]`/`[repo]` — is likewise a decode error, never silently
+ * dropped; see `rejectUnknownKeys`.
+ */
+export function decodeConfig(text: string): ConfigDecodeResult {
+  // A TOML document is always a table at its root (TOML v1.0.0 spec: "a TOML
+  // document ... is a hash table"), so Bun.TOML.parse either throws or returns
+  // a plain object — there is no non-table root to reject.
+  let raw: Record<string, unknown>
+  try {
+    raw = Bun.TOML.parse(text) as Record<string, unknown>
+  } catch (error) {
+    return { ok: false, issue: { pointer: '/', message: `invalid TOML: ${String(error)}` } }
+  }
+
+  const unknownRoot = rejectUnknownKeys(raw, KNOWN_ROOT_KEYS, '')
+  if (unknownRoot !== null) return { ok: false, issue: unknownRoot }
+
+  if (raw.version !== undefined && typeof raw.version !== 'number') {
+    return { ok: false, issue: { pointer: '/version', message: 'expected a number' } }
+  }
+
+  const hooksResult = decodeHooks(raw.hooks)
+  if (!hooksResult.ok) return hooksResult
+
+  const rulesResult = decodeRules(raw.rules)
+  if (!rulesResult.ok) return rulesResult
+
+  const repoResult = decodeRepo(raw.repo)
+  if (!repoResult.ok) return repoResult
+
+  const agentResult = decodeAgent(raw.agent)
+  if (!agentResult.ok) return agentResult
+
+  const extensions = decodeExtensionRoster(raw.extensions)
+  if (!extensions.ok) return { ok: false, issue: extensions.issue }
+
+  return {
+    ok: true,
+    value: {
+      hooks: hooksResult.value,
+      rules: rulesResult.value,
+      repo: repoResult.value,
+      agent: agentResult.value,
+      extensions: extensions.value,
+    },
+  }
+}
+
+const KNOWN_HOOKS_KEYS: ReadonlySet<string> = new Set(['enabled', 'skills_dir', 'lean_ctx_dir'])
+
+function decodeHooks(value: unknown): { ok: true; value: HooksConfig } | { ok: false; issue: ConfigDecodeIssue } {
+  if (value === undefined) return { ok: true, value: DEFAULT_CONFIG.hooks }
+  if (!isPlainObject(value)) {
+    return { ok: false, issue: { pointer: '/hooks', message: 'expected a table' } }
+  }
+
+  const unknown = rejectUnknownKeys(value, KNOWN_HOOKS_KEYS, '/hooks')
+  if (unknown !== null) return { ok: false, issue: unknown }
+
+  const enabledRaw = value.enabled
+  if (enabledRaw !== undefined && typeof enabledRaw !== 'boolean') {
+    return { ok: false, issue: { pointer: '/hooks/enabled', message: 'expected a boolean' } }
+  }
+
+  const skillsDirRaw = value.skills_dir
+  if (skillsDirRaw !== undefined && typeof skillsDirRaw !== 'string') {
+    return { ok: false, issue: { pointer: '/hooks/skills_dir', message: 'expected a string' } }
+  }
+
+  const leanCtxDirRaw = value.lean_ctx_dir
+  if (leanCtxDirRaw !== undefined && typeof leanCtxDirRaw !== 'string') {
+    return { ok: false, issue: { pointer: '/hooks/lean_ctx_dir', message: 'expected a string' } }
+  }
+
+  return {
+    ok: true,
+    value: {
+      enabled: enabledRaw ?? true,
+      skillsDir: skillsDirRaw,
+      leanCtxDir: leanCtxDirRaw,
+    },
+  }
+}
+
+function decodeRules(value: unknown): { ok: true; value: RulesConfig } | { ok: false; issue: ConfigDecodeIssue } {
+  if (value === undefined) return { ok: true, value: DEFAULT_CONFIG.rules }
+  if (!isPlainObject(value)) {
+    return { ok: false, issue: { pointer: '/rules', message: 'expected a table' } }
+  }
+
+  const defaultRaw = value.default
+  if (defaultRaw !== undefined && defaultRaw !== 'on' && defaultRaw !== 'off') {
+    return { ok: false, issue: { pointer: '/rules/default', message: 'expected "on" or "off"' } }
+  }
+
+  const unsafeRaw = value.unsafeAllowUncertain
+  if (unsafeRaw !== undefined && typeof unsafeRaw !== 'boolean') {
+    return { ok: false, issue: { pointer: '/rules/unsafeAllowUncertain', message: 'expected a boolean' } }
+  }
+
+  const byId: Record<string, RuleSection> = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === 'default' || key === 'unsafeAllowUncertain') continue
+    if (!isPlainObject(entry)) {
+      return { ok: false, issue: { pointer: `/rules/${key}`, message: 'expected a table' } }
+    }
+    const ruleEnabled = entry.enabled
+    if (typeof ruleEnabled !== 'boolean') {
+      return { ok: false, issue: { pointer: `/rules/${key}/enabled`, message: 'expected a boolean' } }
+    }
+    byId[key] = { enabled: ruleEnabled }
+  }
+
+  return {
+    ok: true,
+    value: {
+      default: defaultRaw ?? 'on',
+      unsafeAllowUncertain: unsafeRaw ?? false,
+      byId,
+    },
+  }
+}
+
+function decodeStringArray(
+  value: unknown,
+  pointer: string,
+): { ok: true; value: readonly string[] } | { ok: false; issue: ConfigDecodeIssue } {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+    return { ok: false, issue: { pointer, message: 'expected an array of strings' } }
+  }
+  return { ok: true, value: value as readonly string[] }
+}
+
+const KNOWN_REPO_KEYS: ReadonlySet<string> = new Set(['protectedTrees', 'commitProtectedTrees', 'trustedScriptPrefixes'])
+
+function decodeRepo(value: unknown): { ok: true; value: RepoSection } | { ok: false; issue: ConfigDecodeIssue } {
+  if (value === undefined) return { ok: true, value: DEFAULT_REPO }
+  if (!isPlainObject(value)) {
+    return { ok: false, issue: { pointer: '/repo', message: 'expected a table' } }
+  }
+
+  const unknown = rejectUnknownKeys(value, KNOWN_REPO_KEYS, '/repo')
+  if (unknown !== null) return { ok: false, issue: unknown }
+
+  const protectedTreesRaw = value.protectedTrees
+  const protectedTrees =
+    protectedTreesRaw === undefined
+      ? { ok: true as const, value: DEFAULT_REPO.protectedTrees }
+      : decodeStringArray(protectedTreesRaw, '/repo/protectedTrees')
+  if (!protectedTrees.ok) return protectedTrees
+
+  const commitProtectedTreesRaw = value.commitProtectedTrees
+  const commitProtectedTrees =
+    commitProtectedTreesRaw === undefined
+      ? { ok: true as const, value: DEFAULT_REPO.commitProtectedTrees }
+      : decodeStringArray(commitProtectedTreesRaw, '/repo/commitProtectedTrees')
+  if (!commitProtectedTrees.ok) return commitProtectedTrees
+
+  const trustedScriptPrefixesRaw = value.trustedScriptPrefixes
+  const trustedScriptPrefixes =
+    trustedScriptPrefixesRaw === undefined
+      ? { ok: true as const, value: DEFAULT_REPO.trustedScriptPrefixes }
+      : decodeStringArray(trustedScriptPrefixesRaw, '/repo/trustedScriptPrefixes')
+  if (!trustedScriptPrefixes.ok) return trustedScriptPrefixes
+
+  return {
+    ok: true,
+    value: {
+      protectedTrees: protectedTrees.value,
+      commitProtectedTrees: commitProtectedTrees.value,
+      trustedScriptPrefixes: trustedScriptPrefixes.value,
+    },
+  }
+}
+
+export type RuleEnabledResult =
+  | { readonly ok: true; readonly enabled: boolean }
+  | { readonly ok: false; readonly issue: ConfigDecodeIssue }
+
+/**
+ * Resolve whether a rule is enabled — ported verbatim (semantics, not code)
+ * from enact-repo-controls's `isRuleEnabled` in `src/kernel/config/effective.ts`.
+ *
+ * A rule categorised `uncertain` that would resolve to disabled without
+ * `rules.unsafeAllowUncertain` set is a config error, not a silent
+ * override: those rules fail closed by design, and turning that off needs
+ * an explicit, documented opt-in rather than this function quietly forcing
+ * a value either way.
+ */
+export function isRuleEnabled(
+  config: RulesConfig,
+  ruleId: string,
+  category: string,
+  specDefault: boolean,
+): RuleEnabledResult {
+  const explicit = config.byId[ruleId]
+  const resolved = explicit !== undefined ? explicit.enabled : config.default === 'off' ? false : specDefault
+
+  if (category === 'uncertain' && !resolved && !config.unsafeAllowUncertain) {
+    return {
+      ok: false,
+      issue: {
+        pointer: '/rules/unsafeAllowUncertain',
+        message: `rule '${ruleId}' is 'uncertain' and would be switched off; set rules.unsafeAllowUncertain = true to allow this`,
+      },
+    }
+  }
+
+  return { ok: true, enabled: resolved }
+}
+
+const KNOWN_AGENT_KEYS: ReadonlySet<string> = new Set(['user', 'protected_branches'])
+
+function decodeAgent(value: unknown): { ok: true; value: AgentSection } | { ok: false; issue: ConfigDecodeIssue } {
+  if (value === undefined) return { ok: true, value: DEFAULT_AGENT }
+  if (!isPlainObject(value)) {
+    return { ok: false, issue: { pointer: '/agent', message: 'expected a table' } }
+  }
+  const unknown = rejectUnknownKeys(value, KNOWN_AGENT_KEYS, '/agent')
+  if (unknown !== null) return { ok: false, issue: unknown }
+
+  const userRaw = value.user
+  if (userRaw !== undefined && typeof userRaw !== 'string') {
+    return { ok: false, issue: { pointer: '/agent/user', message: 'expected a string' } }
+  }
+
+  const protectedBranchesRaw = value.protected_branches
+  const protectedBranches =
+    protectedBranchesRaw === undefined
+      ? { ok: true as const, value: DEFAULT_AGENT.protectedBranches }
+      : decodeStringArray(protectedBranchesRaw, '/agent/protected_branches')
+  if (!protectedBranches.ok) return protectedBranches
+
+  return {
+    ok: true,
+    value: {
+      user: userRaw ?? DEFAULT_AGENT.user,
+      protectedBranches: protectedBranches.value,
+    },
+  }
+}
+
+/**
+ * Extension names from `[extensions]`: every sub-table key except `version`,
+ * which is the marker's own schema version rather than an extension.
+ *
+ * Absent table means an unmanaged-by-extensions repo, not an error — a repo
+ * predating the roster still decodes, and simply contributes no roots.
+ */
+function decodeExtensionRoster(
+  value: unknown,
+): { ok: true; value: readonly string[] } | { ok: false; issue: ConfigDecodeIssue } {
+  if (value === undefined) return { ok: true, value: [] }
+  if (!isPlainObject(value)) {
+    return { ok: false, issue: { pointer: '/extensions', message: 'expected a table' } }
+  }
+
+  const names: string[] = []
+  for (const [name, entry] of Object.entries(value)) {
+    if (name === 'version') continue
+    if (!isPlainObject(entry)) {
+      return { ok: false, issue: { pointer: `/extensions/${name}`, message: 'expected a table' } }
+    }
+    names.push(name)
+  }
+  return { ok: true, value: names }
+}

package/packages/agent-hooks/src/gating/root.ts

@@ -0,0 +1,117 @@
+/**
+ * Managed-repo resolution for the global `adl hook` binary.
+ *
+ * enact-repo-controls's `src/kernel/root.ts` resolved a repository root two
+ * ways: an explicit `--repo` flag, or (as its strongest signal) the
+ * *compiled binary's own location* — `<root>/.agents/bin/controls` — because
+ * that tool was installed per-repo. `adl hook` is installed once, globally,
+ * at `/usr/local/bin/adl` (see global-tools/manifest.json), so that
+ * signal does not exist here: there is exactly one binary location for every
+ * repository on the machine. Root resolution is correspondingly simpler —
+ * HARDCUT, not a port:
+ *
+ *   1. No `--repo` flag, no host environment variables (same reasoning as
+ *      the original: those break the moment a repo is relocated or copied).
+ *   2. Walk up from the payload's cwd (`payloadCwd()` in `../hooks/contract.ts`)
+ *      looking for `.git` (a directory for a normal checkout, a file for a
+ *      worktree or submodule) — that directory is the git root.
+ *   3. A repository is *managed* iff `<git root>/adl-config.toml`
+ *      exists. No marker, no git root found at all, or `[hooks] enabled =
+ *      false` in that file: the caller treats the invocation as a no-op
+ *      (exit 0, empty stdout/stderr) — never an error. An unmanaged
+ *      directory is the overwhelmingly common case for a globally-installed
+ *      hook (every host but Kimi's hook is repo-scoped anyway, but Kimi's
+ *      is global, so this path runs on every repo on the machine).
+ */
+
+import { dirname, join } from 'node:path'
+import { statSync } from 'node:fs'
+
+/** Guard against a symlink loop or a pathological mount turning the walk into a hang. */
+export const MAX_WALK_DEPTH = 128
+
+/** The repo marker + settings file (docs/architecture/adl-config.md). Hard cut (Tarun, 2026-09-27): no fallback read of the old `adl-config.toml` name. */
+export const MARKER = 'adl-config.toml'
+
+export interface RootIO {
+  readonly isFile: (path: string) => boolean
+  readonly isDirectory: (path: string) => boolean
+  readonly exists: (path: string) => boolean
+  readonly cwd: () => string
+}
+
+export interface GitRootResult {
+  readonly root: string | null
+  readonly searched: readonly string[]
+}
+
+/**
+ * Walk up from `startDir` looking for a `.git` entry (directory or file).
+ * Stops at the first one found, at the filesystem root, or after
+ * `MAX_WALK_DEPTH` levels — whichever comes first.
+ */
+export function findGitRoot(io: RootIO, startDir: string): GitRootResult {
+  const searched: string[] = []
+  let current = startDir
+
+  for (let depth = 0; depth < MAX_WALK_DEPTH; depth += 1) {
+    searched.push(current)
+    if (io.exists(join(current, '.git'))) return { root: current, searched }
+
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+
+  return { root: null, searched }
+}
+
+export interface ManagedRepoResult {
+  readonly managed: boolean
+  readonly root: string | null
+  readonly configPath: string | null
+}
+
+/**
+ * Resolve whether the repository containing `startDir` is managed by
+ * adl hook. `managed` is true iff a git root was found *and* that root
+ * carries `adl-config.toml` — the caller (`main.ts`) still has to
+ * read and decode that file itself to check `[hooks] enabled` and rule
+ * config, since this function only answers "is there a marker at all".
+ */
+export function resolveManagedRepo(io: RootIO, startDir: string): ManagedRepoResult {
+  const { root } = findGitRoot(io, startDir)
+  if (root === null) return { managed: false, root: null, configPath: null }
+
+  const configPath = join(root, MARKER)
+  if (!io.isFile(configPath)) return { managed: false, root, configPath: null }
+
+  return { managed: true, root, configPath }
+}
+
+/** Production `RootIO`: the real filesystem. */
+export const realRootIO: RootIO = {
+  isFile: (path) => {
+    try {
+      return statSync(path).isFile()
+    } catch {
+      return false
+    }
+  },
+  isDirectory: (path) => {
+    try {
+      return statSync(path).isDirectory()
+    } catch {
+      return false
+    }
+  },
+  exists: (path) => {
+    try {
+      statSync(path)
+      return true
+    } catch {
+      return false
+    }
+  },
+  cwd: () => process.cwd(),
+}

package/packages/agent-hooks/src/hooks/briefing/handler.ts

@@ -0,0 +1,22 @@
+/**
+ * `main.ts`-facing entry point for the `briefing` hook kind.
+ *
+ * Thin wiring only: `main.ts` dispatches every `HookInvocation` through one
+ * `HookHandler` shape (see `../contract.ts`) and imports this exact
+ * `handleBriefing` export from this exact path — the actual briefing logic
+ * (base lean-ctx briefing + PROJECT WARMUP appendix, per-host rendering,
+ * once-per-session delivery gate) lives in `./index.ts`, built against an
+ * injectable `Runner` so it can be unit-tested without a real `lean-ctx`
+ * binary. This file wires that logic to the production, timeout-enforcing
+ * `bunRunner` — the same shape the reference tree's `main.ts` used to wire
+ * `handleBriefing` straight from `./index.ts`.
+ */
+
+import type { HookInvocation, HookResult } from '../contract.ts'
+import { bunRunner, createBriefingHandler } from './index.ts'
+
+const briefingHandler = createBriefingHandler({ run: bunRunner })
+
+export async function handleBriefing(inv: HookInvocation): Promise<HookResult> {
+  return briefingHandler(inv)
+}