@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/agent-hooks/src/cli/doctor.ts

@@ -0,0 +1,241 @@
+/**
+ * `adl hook doctor [--repo <path>]` — can this repo + machine actually run
+ * adl hook's hooks?
+ *
+ * One line per check, `[ok]` / `[warn]` / `[FAIL]` / `[skip]`, then a
+ * summary. Exit 1 iff any `[FAIL]`. What is a hard requirement (FAIL) vs. a
+ * soft finding (warn) follows what each hook actually does without it:
+ *
+ *   FAIL — managed repo whose `adl-config.toml` fails to decode or
+ *          whose rules fail to resolve (every hook fails loud there);
+ *          hooks enabled but no skill root exists or none has a valid
+ *          SKILL.md (skill matching suggests nothing; this is where the loud
+ *          signal for that lives now, since UserPromptSubmit only WARNS -- an
+ *          empty corpus has an innocent explanation once it is per-host and
+ *          per-extension, and a dead prompt is worse than a missing hint);
+ *          `lean-ctx` not on PATH or `--version` failing (briefing and the
+ *          lean-ctx hooks shell out to it); `code-review-graph` not on PATH
+ *          (the crg hooks shell out to it).
+ *   warn — unmanaged repo (hooks no-op by design); `[hooks] enabled = false`;
+ *          embedding model missing/corrupt (user-prompt-submit falls back to
+ *          BM25-only, never fatal); vector half disabled; lean-ctx allowlist
+ *          count not readable.
+ *
+ * The vector half is "effectively disabled by cosineFloor" when the floor
+ * exceeds 1: a vector hit must reach `cosine >= cosineFloor` to enter fusion
+ * (`../hooks/user-prompt-submit/match.ts`) and cosine similarity is at most 1.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { AdlRepoConfig } from '../gating/config.ts'
+import { buildMatchConfig } from '../hooks/user-prompt-submit/config.ts'
+import { skillRootsFor } from '../hooks/user-prompt-submit/skill-roots.ts'
+import { HOST_IDS } from '../hosts/spec.ts'
+import { scanSkills } from '../hooks/user-prompt-submit/skills.ts'
+import { loadTokenizer } from '../hooks/user-prompt-submit/tokenizer.ts'
+import { loadVectorHalf, resolveGlobalArtifactDir } from '../hooks/user-prompt-submit/vector.ts'
+import { HOOKS_DENY_LOG_REL, HOOKS_LOG_REL } from '../hooks/log.ts'
+import { DEFAULT_LEAN_CTX_DIR, leanCtxEnv } from '../lean-ctx/env.ts'
+import { spawnWithTimeout } from '../lib/spawn-with-timeout.ts'
+import { buildEngineContext } from '../rules/engine.ts'
+import { liveEnv, liveRepoIndex } from '../rules/ports.ts'
+import { BUILTIN_RULES, requireRegistered } from '../rules/registry.ts'
+import { type CliResult, type LoadedRepo, cliError, loadRepo, parseArgs, unmanagedReason } from './args.ts'
+
+type Status = 'ok' | 'warn' | 'FAIL' | 'skip' | 'info'
+type Env = Readonly<Record<string, string | undefined>>
+
+interface Check {
+  readonly status: Status
+  readonly text: string
+}
+
+const check = (status: Status, name: string, detail: string): Check => ({ status, text: `${name}: ${detail}` })
+
+export interface DoctorOptions {
+  /** Per-subprocess timeout for `lean-ctx --version` / `lean-ctx doctor --json`. */
+  readonly timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+/** Config + rule resolution, and the config the downstream checks use (null when unusable). */
+function repoChecks(loaded: LoadedRepo): { readonly checks: Check[]; readonly config: AdlRepoConfig | null } {
+  const { state } = loaded
+  if (!state.managed) {
+    return {
+      checks: [
+        check('warn', 'repo', `not managed (${unmanagedReason(state)}); hooks no-op here`),
+        check('skip', 'config', 'not a managed repo (built-in defaults apply)'),
+      ],
+      config: null,
+    }
+  }
+  const repoLine = check('ok', 'repo', `managed at ${state.root} (config ${state.configPath})`)
+  if (!loaded.ok) return { checks: [repoLine, check('FAIL', 'config', loaded.error)], config: null }
+  const root = state.root as string
+  const ctx = buildEngineContext(loaded.config.rules, loaded.config.repo, requireRegistered(BUILTIN_RULES), liveRepoIndex(root), liveEnv, undefined, loaded.config.agent)
+  if (!ctx.ok) return { checks: [repoLine, check('FAIL', 'config', `${ctx.issue.pointer}: ${ctx.issue.message}`)], config: null }
+  return { checks: [repoLine, check('ok', 'config', 'valid')], config: loaded.config }
+}
+
+function hooksAndSkills(loaded: LoadedRepo, config: AdlRepoConfig | null): Check[] {
+  if (config === null) {
+    const reason = loaded.state.managed ? 'config invalid' : 'not a managed repo'
+    return [check('skip', 'hooks', reason), check('skip', 'skills', reason)]
+  }
+  const root = loaded.state.root as string
+  const enabled = config.hooks.enabled
+  const hooks = enabled
+    ? check('ok', 'hooks', 'enabled')
+    : check('warn', 'hooks', 'disabled ([hooks] enabled = false); every hook no-ops in this repo')
+  const missingStatus: Status = enabled ? 'FAIL' : 'warn'
+  // The same roots UserPromptSubmit scans — an explicit skills_dir, else the
+  // host plugin roots named by the [extensions] roster plus the legacy pool.
+  // Doctor reports for every host, since a repo installed with `--host` for one
+  // host is a normal state and naming only one would misreport it.
+  const explicit = config.hooks.skillsDir
+  const roots = explicit !== undefined
+    ? [explicit]
+    : [...new Set(HOST_IDS.flatMap((host) => skillRootsFor(host, config.extensions)))]
+  const present = roots.filter((rel) => existsSync(join(root, rel)))
+  const absolute = (rels: readonly string[]) => rels.map((rel) => join(root, rel)).join(', ')
+  if (present.length === 0) {
+    return [hooks, check(missingStatus, 'skills', `${absolute(roots)} does not exist`)]
+  }
+  const count = scanSkills(root, present).length
+  if (count === 0) return [hooks, check(missingStatus, 'skills', `${absolute(present)} has no SKILL.md with name+description`)]
+  return [hooks, check('ok', 'skills', `${absolute(present)} (${count} ${count === 1 ? 'skill' : 'skills'})`)]
+}
+
+const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+function modelCheck(env: Env): { readonly check: Check; readonly usable: boolean } {
+  const fallback = '; skill matching is BM25-only'
+  let artifactDir: string
+  try {
+    artifactDir = resolveGlobalArtifactDir(env)
+  } catch (error) {
+    return { check: check('warn', 'embedding model', `location unresolved (${errorMessage(error)})${fallback}`), usable: false }
+  }
+  if (!existsSync(artifactDir)) {
+    return { check: check('warn', 'embedding model', `missing (${artifactDir} does not exist)${fallback}`), usable: false }
+  }
+  try {
+    const loaded = loadVectorHalf(artifactDir, loadTokenizer(artifactDir).tokenize)
+    if (!loaded.ok) return { check: check('warn', 'embedding model', `corrupt (${loaded.reason})${fallback}`), usable: false }
+    return { check: check('ok', 'embedding model', `installed at ${artifactDir} (${loaded.half.rows} rows x ${loaded.half.dim} dim)`), usable: true }
+  } catch (error) {
+    return { check: check('warn', 'embedding model', `corrupt (${errorMessage(error)})${fallback}`), usable: false }
+  }
+}
+
+function modelAndVector(env: Env): Check[] {
+  const { check: model, usable } = modelCheck(env)
+  const match = buildMatchConfig(env)
+  const floorSource = env.SKILL_MATCH_COSINE_FLOOR === undefined ? 'default' : 'SKILL_MATCH_COSINE_FLOOR'
+  let vector: Check
+  if (!match.vectorEnabled) vector = check('warn', 'vector half', 'disabled (SKILL_MATCH_VECTOR=0)')
+  else if (!usable) vector = check('warn', 'vector half', 'disabled (embedding model not usable)')
+  else if (match.cosineFloor > 1) {
+    vector = check(
+      'warn',
+      'vector half',
+      `effectively disabled (cosineFloor ${match.cosineFloor} from ${floorSource} exceeds the maximum cosine similarity 1)`,
+    )
+  } else vector = check('ok', 'vector half', `active (cosineFloor ${match.cosineFloor}, ${floorSource})`)
+  return [model, vector]
+}
+
+async function leanCtxChecks(
+  loaded: LoadedRepo,
+  config: AdlRepoConfig | null,
+  env: Env,
+  timeoutMs: number,
+): Promise<Check[]> {
+  const path = Bun.which('lean-ctx', { PATH: env.PATH ?? '' })
+  const skipAllowlist = check('skip', 'lean-ctx allowlist', 'lean-ctx not usable')
+  if (path === null) return [check('FAIL', 'lean-ctx', `not found on PATH (${env.PATH ?? ''})`), skipAllowlist]
+  const version = await spawnWithTimeout(path, ['--version'], { env, timeoutMs })
+  if (version.exitCode !== 0) {
+    const reason = version.timedOut ? `timed out after ${timeoutMs}ms` : `exited ${version.exitCode}: ${version.stderr.trim()}`
+    return [check('FAIL', 'lean-ctx', `${path} --version ${reason}`), skipAllowlist]
+  }
+  const binary = check('ok', 'lean-ctx', `${path} (${version.stdout.trim().split('\n')[0]})`)
+
+  // Same env the hooks give lean-ctx: repo-rooted LEAN_CTX_* in a managed repo, lean-ctx's own defaults otherwise (mcp.ts).
+  // `config` is the value `repoChecks` already decoded — reusing it keeps an invalid
+  // `adl-config.toml` reported by the `config` check above rather than thrown from here.
+  const root = loaded.state.managed && config !== null ? (loaded.state.root as string) : null
+  const childEnv = root === null ? { ...env } : leanCtxEnv(root, env, config?.hooks.leanCtxDir ?? DEFAULT_LEAN_CTX_DIR)
+  const scope = root === null ? 'lean-ctx defaults; LEAN_CTX_CONFIG_DIR unset' : `LEAN_CTX_CONFIG_DIR=${childEnv.LEAN_CTX_CONFIG_DIR}`
+  const unavailable = (reason: string): Check[] => [binary, check('warn', 'lean-ctx allowlist', `unavailable (${reason})`)]
+  const doctor = await spawnWithTimeout(path, ['doctor', '--json'], { env: childEnv, timeoutMs, ...(root === null ? {} : { cwd: root }) })
+  if (doctor.timedOut) return unavailable(`lean-ctx doctor --json timed out after ${timeoutMs}ms`)
+  // A non-zero exit alone is not a failure: lean-ctx 3.10.1 exits 1 whenever any of its OWN checks fail
+  // (e.g. no shell aliases) while still printing the full report. Only a report we cannot read is.
+  let parsed: { readonly checks?: readonly { readonly name?: string }[] }
+  try {
+    parsed = JSON.parse(doctor.stdout) as typeof parsed
+  } catch {
+    return unavailable(
+      doctor.exitCode === 0
+        ? 'lean-ctx doctor --json printed invalid JSON'
+        : `lean-ctx doctor --json exited ${doctor.exitCode}: ${doctor.stderr.trim()}`,
+    )
+  }
+  const count = (parsed.checks ?? []).map((entry) => /Shell allowlist\s+(\d+) command/.exec(entry.name ?? '')?.[1]).find((n) => n !== undefined)
+  if (count === undefined) return unavailable('no "Shell allowlist" check in lean-ctx doctor --json')
+  return [binary, check('ok', 'lean-ctx allowlist', `${count} command(s) enforced (${scope})`)]
+}
+
+/** Both hook logs: path, row count, and for the deny log its last 5 rows. JSON Lines (docs/architecture/cli-design.md §5a): every line is a record, there is no header row to skip. */
+function logChecks(loaded: LoadedRepo): Check[] {
+  if (!loaded.state.managed) return [check('skip', 'logs', 'not a managed repo (hooks log nothing here)')]
+  const root = loaded.state.root as string
+  const describe = (name: string, relative: string, echoLast: boolean): Check[] => {
+    const path = join(root, relative)
+    if (!existsSync(path)) return [check('info', name, `${path} (not created yet)`)]
+    let rows: string[]
+    try {
+      rows = readFileSync(path, 'utf8').split('\n').filter((row) => row.length > 0)
+    } catch (error) {
+      return [check('warn', name, `${path} unreadable (${errorMessage(error)})`)]
+    }
+    const counted = check('info', name, `${path} (${rows.length} ${rows.length === 1 ? 'row' : 'rows'})`)
+    const echoed = echoLast ? rows.slice(-5).map((row): Check => ({ status: 'info', text: `  ${row}` })) : []
+    return [counted, ...echoed]
+  }
+  return [...describe('deny log', HOOKS_DENY_LOG_REL, true), ...describe('activity log', HOOKS_LOG_REL, false)]
+}
+
+function crgCheck(env: Env): Check {
+  const path = Bun.which('code-review-graph', { PATH: env.PATH ?? '' })
+  return path === null ? check('FAIL', 'code-review-graph', `not found on PATH (${env.PATH ?? ''})`) : check('ok', 'code-review-graph', path)
+}
+
+/** `argv` is everything after `doctor`. */
+export async function runDoctor(argv: readonly string[], cwd: string, env: Env, options: DoctorOptions = {}): Promise<CliResult> {
+  const parsed = parseArgs(argv, false)
+  if ('error' in parsed) return cliError(parsed.error)
+  if (parsed.positionals.length > 0) return cliError(`unexpected argument '${parsed.positionals[0]}'`)
+  const loaded = loadRepo(cwd, parsed.repo)
+  if (loaded === null) return cliError(`--repo ${parsed.repo} is not a directory`)
+
+  const repo = repoChecks(loaded)
+  const checks = [
+    ...repo.checks,
+    ...hooksAndSkills(loaded, repo.config),
+    ...modelAndVector(env),
+    ...(await leanCtxChecks(loaded, repo.config, env, options.timeoutMs ?? DEFAULT_TIMEOUT_MS)),
+    crgCheck(env),
+    ...logChecks(loaded),
+  ]
+  const tally = (status: Status): number => checks.filter((entry) => entry.status === status).length
+  const lines = [
+    ...checks.map((entry) => `[${entry.status}] ${entry.text}`),
+    `doctor: ${tally('ok')} ok, ${tally('warn')} warn, ${tally('FAIL')} fail`,
+  ]
+  return { stdout: `${lines.join('\n')}\n`, stderr: '', exitCode: tally('FAIL') > 0 ? 1 : 0 }
+}

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

@@ -0,0 +1,133 @@
+/**
+ * `adl hook rules list [--repo <path>] [--json]`
+ * `adl hook rules show <id> [--repo <path>] [--json]`
+ *
+ * Inspect the registered rule corpus (`../rules/registry.ts`) and each rule's
+ * EFFECTIVE enabled state for one repository. "Effective" uses the engine's
+ * own resolution — `buildEngineContext` over the repo's
+ * `adl-config.toml`, exactly what `pre-tool-use` runs — AND the
+ * `[hooks] enabled` gate in front of it: with hooks disabled the engine never
+ * runs, so no rule is enforced. Outside a managed repo the built-in defaults
+ * are shown, and the output says so.
+ */
+
+import { buildEngineContext } from '../rules/engine.ts'
+import { liveEnv, liveRepoIndex } from '../rules/ports.ts'
+import { BUILTIN_RULES, requireRegistered } from '../rules/registry.ts'
+import type { AnyRuleSpec } from '../rules/spec.ts'
+import { type CliResult, type RepoState, cliError, loadRepo, parseArgs, unmanagedReason } from './args.ts'
+
+interface RuleRow {
+  readonly id: string
+  readonly category: string
+  readonly severity: string
+  readonly enabledByDefault: boolean
+  readonly enabled: boolean
+  readonly summary: string
+}
+
+interface Resolved {
+  readonly state: RepoState
+  readonly source: 'config' | 'defaults'
+  readonly hooksEnabled: boolean
+  readonly rules: readonly { readonly spec: AnyRuleSpec; readonly row: RuleRow }[]
+}
+
+const yesNo = (value: boolean): string => (value ? 'yes' : 'no')
+
+function resolveRules(cwd: string, repoArg: string | undefined): Resolved | CliResult {
+  const loaded = loadRepo(cwd, repoArg)
+  if (loaded === null) return cliError(`--repo ${repoArg} is not a directory`)
+  if (!loaded.ok) return cliError(loaded.error)
+  const { state, config } = loaded
+  const registered = requireRegistered(BUILTIN_RULES)
+  const ctx = buildEngineContext(config.rules, config.repo, registered, liveRepoIndex(state.root ?? state.start), liveEnv, undefined, config.agent)
+  if (!ctx.ok) return cliError(`${state.configPath} ${ctx.issue.pointer}: ${ctx.issue.message}`)
+  const hooksEnabled = config.hooks.enabled
+  const rules = [...registered.values()].map((spec) => ({
+    spec,
+    row: {
+      id: spec.id,
+      category: spec.category,
+      severity: spec.severity,
+      enabledByDefault: spec.enabledByDefault,
+      enabled: hooksEnabled && ctx.value.enabled.has(spec.id),
+      summary: spec.summary,
+    },
+  }))
+  return { state, source: state.managed ? 'config' : 'defaults', hooksEnabled, rules }
+}
+
+function headerLines(resolved: Resolved): string[] {
+  const { state } = resolved
+  const lines = state.managed
+    ? [`repo: ${state.root} (managed; config ${state.configPath})`]
+    : [`repo: not a managed repo (${unmanagedReason(state)}); showing built-in defaults`]
+  if (!resolved.hooksEnabled) lines.push('hooks disabled ([hooks] enabled = false): no rule is enforced in this repo')
+  return lines
+}
+
+function table(rows: readonly (readonly string[])[]): string[] {
+  const widths = rows[0]?.map((_, column) => Math.max(...rows.map((row) => (row[column] as string).length))) ?? []
+  return rows.map((row) => row.map((cell, column) => (column === row.length - 1 ? cell : cell.padEnd(widths[column] as number))).join('  '))
+}
+
+function repoJson(resolved: Resolved) {
+  return { repo: resolved.state, source: resolved.source, hooksEnabled: resolved.hooksEnabled }
+}
+
+function list(resolved: Resolved, json: boolean): CliResult {
+  if (json) {
+    const body = { ...repoJson(resolved), rules: resolved.rules.map((rule) => rule.row) }
+    return { stdout: `${JSON.stringify(body, null, 2)}\n`, stderr: '', exitCode: 0 }
+  }
+  const rows = [
+    ['ID', 'CATEGORY', 'SEVERITY', 'ENABLED', 'SUMMARY'],
+    ...resolved.rules.map(({ row }) => [row.id, row.category, row.severity, yesNo(row.enabled), row.summary]),
+  ]
+  return { stdout: `${[...headerLines(resolved), '', ...table(rows)].join('\n')}\n`, stderr: '', exitCode: 0 }
+}
+
+function show(resolved: Resolved, id: string, json: boolean): CliResult {
+  const found = resolved.rules.find((rule) => rule.spec.id === id)
+  if (found === undefined) return cliError(`unknown rule id '${id}' (run \`adl hook rules list\` for every id)`)
+  const { spec, row } = found
+  if (json) {
+    const rule = { ...row, corpus: { deny: [...spec.corpus.deny], allow: [...spec.corpus.allow] } }
+    return { stdout: `${JSON.stringify({ ...repoJson(resolved), rule }, null, 2)}\n`, stderr: '', exitCode: 0 }
+  }
+  const where = resolved.state.managed ? `repo ${resolved.state.root}` : 'built-in defaults; not a managed repo'
+  const entries = (items: readonly string[]): string[] => items.map((entry) => `  ${entry.split('\n').join('\n    ')}`)
+  const lines = [
+    `id: ${row.id}`,
+    `category: ${row.category}`,
+    `severity: ${row.severity}`,
+    `summary: ${row.summary}`,
+    `enabled by default: ${yesNo(row.enabledByDefault)}`,
+    `enabled: ${yesNo(row.enabled)} (${where})`,
+    ...(resolved.hooksEnabled ? [] : ['hooks disabled ([hooks] enabled = false): no rule is enforced in this repo']),
+    `corpus deny (${spec.corpus.deny.length}):`,
+    ...entries(spec.corpus.deny),
+    `corpus allow (${spec.corpus.allow.length}):`,
+    ...entries(spec.corpus.allow),
+  ]
+  return { stdout: `${lines.join('\n')}\n`, stderr: '', exitCode: 0 }
+}
+
+/** `argv` is everything after `rules`. */
+export function runRules(argv: readonly string[], cwd: string): CliResult {
+  const [subcommand, ...rest] = argv
+  if (subcommand !== 'list' && subcommand !== 'show') {
+    return cliError(`rules requires a subcommand (list or show), got '${subcommand ?? ''}'`)
+  }
+  const parsed = parseArgs(rest, true)
+  if ('error' in parsed) return cliError(parsed.error)
+  const [id, extra] = parsed.positionals
+  if (subcommand === 'show' && id === undefined) return cliError('rules show requires a rule id')
+  const unexpected = subcommand === 'list' ? id : extra
+  if (unexpected !== undefined) return cliError(`unexpected argument '${unexpected}'`)
+
+  const resolved = resolveRules(cwd, parsed.repo)
+  if ('exitCode' in resolved) return resolved
+  return subcommand === 'list' ? list(resolved, parsed.json) : show(resolved, id as string, parsed.json)
+}

package/packages/agent-hooks/src/deploy/deploy.ts

@@ -0,0 +1,181 @@
+/**
+ * Writes the hook wiring in assets/hooks.json into a target repository's
+ * claude/codex/cursor/opencode surfaces, per the deploy profile (profile.ts)
+ * and each surface's renderer (render.ts / opencode-template.ts). Touches
+ * only entries a PREVIOUS run of this deploy recorded as its own
+ * (json-merge.ts, lock.ts) — a user's own keys, and hook entries this
+ * deploy did not write, are left untouched (H4). The opencode-plugin
+ * surface is wholly adl-owned (H3): a pre-existing non-adl file at that
+ * path is reported as a conflict and never overwritten.
+ *
+ * Fails loud: a missing assets dir/target repo, an invalid profile, a
+ * malformed target JSON file, or a missing template all throw. There is no
+ * partial-success return value.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { renderOpencodePlugin } from './opencode-template.ts'
+import { mergeCursorHooksFile, mergeJsonHooksFile } from './json-merge.ts'
+import {
+  legacyFileHash,
+  type LegacyLockDoc,
+  legacyTakeoverForJsonHooksSurface,
+  readLegacyLock,
+  sha256Hex,
+  stripLegacyOwnership,
+  unionOwnedCommands,
+} from './legacy-lock.ts'
+import { type HookLockEntry, lockPathFor, readLock, writeLock } from './lock.ts'
+import { type HookDeployProfile, type HookSurface, loadProfile } from './profile.ts'
+import { renderCursorEntries, renderJsonHooksGroups } from './render.ts'
+import { type CanonicalHooksDoc, loadHooksSource } from './source.ts'
+
+export interface DeployHooksOptions {
+  readonly assetsDir: string
+  readonly targetRepo: string
+  /** Defaults to loadProfile() (the package's own deploy-profile.json) — pass explicitly when the caller has already resolved real on-disk paths. */
+  readonly profile?: HookDeployProfile
+  /** Defaults to loading `profile.source` relative to `dirname(assetsDir)`. */
+  readonly hooksDoc?: CanonicalHooksDoc
+}
+
+export interface HookConflict {
+  readonly file: string
+  readonly reason: string
+}
+
+export interface DeployHooksResult {
+  readonly written: readonly string[]
+  readonly unchanged: readonly string[]
+  readonly conflicts: readonly HookConflict[]
+  readonly lockPath: string
+}
+
+function readExistingJson(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined
+  let doc: unknown
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (cause) {
+    throw new Error(`target hook file is not valid JSON: ${path} (${(cause as Error).message})`)
+  }
+  if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+    throw new Error(`target hook file is not a JSON object: ${path}`)
+  }
+  return doc as Record<string, unknown>
+}
+
+function writeJsonIfChanged(path: string, content: Record<string, unknown>, changed: boolean): void {
+  if (!changed) return
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
+}
+
+export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
+  const { assetsDir, targetRepo } = options
+
+  if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
+    throw new Error(`agent-hooks assets directory not found: ${assetsDir}`)
+  }
+  if (!existsSync(targetRepo) || !statSync(targetRepo).isDirectory()) {
+    throw new Error(`deploy target is not a directory: ${targetRepo}`)
+  }
+
+  const profile = options.profile ?? loadProfile()
+  const hooksDoc = options.hooksDoc ?? loadHooksSource(join(dirname(assetsDir), profile.source))
+
+  const lock = readLock(targetRepo)
+  const legacyLockPath = profile.legacyLock !== undefined ? join(targetRepo, profile.legacyLock) : undefined
+  const legacyDoc = legacyLockPath !== undefined ? readLegacyLock(legacyLockPath) : undefined
+  const newEntries: Record<string, HookLockEntry> = {}
+  const written: string[] = []
+  const unchanged: string[] = []
+  const conflicts: HookConflict[] = []
+  const takeover = { any: false }
+
+  for (const surface of profile.surfaces) {
+    deploySurface(surface, { assetsDir, targetRepo, hooksDoc, lock, legacyDoc, takeover, newEntries, written, unchanged, conflicts })
+  }
+
+  writeLock(targetRepo, { version: 1, entries: newEntries })
+
+  // Once anything was actually taken over, this package's own bookkeeping in
+  // the legacy lock is stale — ownership has fully moved to the lock just
+  // written above. A legacy lock present but untouched by any takeover (no
+  // hash matched, or this repo never had one) is left exactly as found.
+  if (takeover.any && legacyDoc !== undefined && legacyLockPath !== undefined) {
+    const opencodeSurface = profile.surfaces.find((s) => s.format === 'opencode-plugin')
+    if (opencodeSurface !== undefined) stripLegacyOwnership(legacyDoc, legacyLockPath, opencodeSurface.file)
+  }
+
+  return {
+    written: written.sort(),
+    unchanged: unchanged.sort(),
+    conflicts: conflicts.sort((a, b) => a.file.localeCompare(b.file)),
+    lockPath: lockPathFor(targetRepo),
+  }
+}
+
+interface DeploySurfaceContext {
+  readonly assetsDir: string
+  readonly targetRepo: string
+  readonly hooksDoc: CanonicalHooksDoc
+  readonly lock: ReturnType<typeof readLock>
+  /** The pre-agent-hooks engine's own lock, if `profile.legacyLock` is set and it exists (legacy-lock.ts). */
+  readonly legacyDoc: LegacyLockDoc | undefined
+  /** Mutated to true the first time any surface actually takes over a legacy-owned entry or file this run. */
+  readonly takeover: { any: boolean }
+  readonly newEntries: Record<string, HookLockEntry>
+  readonly written: string[]
+  readonly unchanged: string[]
+  readonly conflicts: HookConflict[]
+}
+
+function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
+  const targetAbs = join(ctx.targetRepo, surface.file)
+  const prevEntry = ctx.lock.entries[surface.file]
+
+  if (surface.format === 'opencode-plugin') {
+    const exists = existsSync(targetAbs)
+    const legacyTakeover = exists && legacyFileHash(ctx.legacyDoc, surface.file) === sha256Hex(readFileSync(targetAbs))
+    if (legacyTakeover) ctx.takeover.any = true
+    const wasOwned = (prevEntry?.format === 'opencode-plugin' && prevEntry.owned === true) || legacyTakeover
+    if (exists && !wasOwned) {
+      ctx.conflicts.push({ file: surface.file, reason: 'a non-adl file already exists at this path; deploy left it untouched' })
+      return
+    }
+    const rendered = renderOpencodePlugin({ assetsDir: ctx.assetsDir, surface, hooksDoc: ctx.hooksDoc })
+    const changed = !exists || readFileSync(targetAbs, 'utf8') !== rendered
+    if (changed) {
+      mkdirSync(dirname(targetAbs), { recursive: true })
+      writeFileSync(targetAbs, rendered)
+      ctx.written.push(surface.file)
+    } else {
+      ctx.unchanged.push(surface.file)
+    }
+    ctx.newEntries[surface.file] = { format: 'opencode-plugin', owned: true }
+    return
+  }
+
+  const ownOwned = prevEntry !== undefined && prevEntry.format === surface.format ? prevEntry.ownedCommands : {}
+  const existingRaw = readExistingJson(targetAbs)
+  const legacyTakeover = legacyTakeoverForJsonHooksSurface(existingRaw, ctx.legacyDoc, surface.file)
+  if (legacyTakeover.matched) ctx.takeover.any = true
+  const previousOwned = unionOwnedCommands(ownOwned, legacyTakeover.ownedByEvent)
+
+  if (surface.format === 'cursor-hooks-v1') {
+    const desired = renderCursorEntries(ctx.hooksDoc, surface)
+    const { fileContent, ownedCommands, changed } = mergeCursorHooksFile(existingRaw, desired, previousOwned)
+    writeJsonIfChanged(targetAbs, fileContent, changed)
+    ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
+    ctx.newEntries[surface.file] = { format: 'cursor-hooks-v1', ownedCommands }
+    return
+  }
+
+  // claude-settings | codex-hooks
+  const desired = renderJsonHooksGroups(ctx.hooksDoc, surface)
+  const { fileContent, ownedCommands, changed } = mergeJsonHooksFile(existingRaw, desired, previousOwned)
+  writeJsonIfChanged(targetAbs, fileContent, changed)
+  ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
+  ctx.newEntries[surface.file] = { format: surface.format, ownedCommands }
+}