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

package/packages/agent-settings/src/kimi-hooks.ts

@@ -0,0 +1,455 @@
+/**
+ * Deploy/remove the ADL-managed `[[hooks]]` block in Kimi Code's global
+ * config (`<home>/.kimi-code/config.toml`).
+ *
+ * Kimi Code hooks are documented at
+ * https://moonshotai.github.io/kimi-code/en/customization/hooks.html as
+ * `[[hooks]]` TOML array-of-tables entries with exactly four fields —
+ * `event` (required), `matcher` (optional regex; omitted matches every
+ * target), `command` (required), `timeout` (optional, 1-600s, default 30).
+ * "[[hooks]] only allows these four fields; extra fields will cause the
+ * config file to fail to load," so the managed entries below carry nothing
+ * else. Only `PreToolUse`, `Stop`, and `UserPromptSubmit` can block/deny —
+ * exit code 2, or `hookSpecificOutput.permissionDecision: "deny"` — which
+ * `adl hook` (the folded-in enact-hook engine) already implements; this
+ * script only places the TOML.
+ *
+ * Unlike global-agents.ts (whole-file ownership: the target either equals
+ * the canonical file or it doesn't), this manages one user-level file that
+ * legitimately holds other content — other hook entries, provider API keys,
+ * general settings — so it uses the same BEGIN/END delimited-region
+ * strategy this project already applies to `.codex/config.toml` inside
+ * global-surface-sweep.ts, here as the file's sole write path instead of a
+ * removal target.
+ *
+ * Ownership model: only the delimited region between the markers is ours.
+ * `apply`/`uninstall` refuse to touch a region whose current content
+ * differs from the canonical block ("drifted" — hand-edited, or stale from
+ * a deployer update) unless `--force`. Everything outside the markers,
+ * including comments and key order, is left byte-for-byte untouched. The
+ * file may contain provider API keys, so this script never prints file
+ * content — only marker state, paths, and validation results.
+ *
+ * STATUS.md 12p decision 13 (Tarun, 2026-09-29, "adl is LOCAL REPO FIRST …
+ * the repos where adl-config.toml does not exist has no business of running
+ * hooks"): this carrier STAYS global, as the one exception, because Kimi has
+ * no per-repo hook configuration to deploy into — confirmed from Kimi's own
+ * docs, <https://moonshotai.github.io/kimi-code/en/customization/hooks.html>
+ * (fetched 2026-09-29): "All hook rules are written in the `[[hooks]]` array
+ * in `~/.kimi-code/config.toml`", no project-local alternative documented.
+ * Decision 13's per-repo-only requirement covers Kimi too, and is built —
+ * not here, since the TOML `command` string this file writes is a fixed
+ * shell command with no access to the hook payload's JSON `cwd`, but inside
+ * `adl hook` itself, which resolves the invoking repository root from the
+ * payload (see `packages/agent-hooks/src/hooks/contract.ts`'s `payloadCwd`)
+ * and is a strict no-op when no `adl-config.toml` is found above that root,
+ * or when `[hooks] enabled = false` (`packages/agent-hooks/src/main.ts:215-245`,
+ * proven in `packages/agent-hooks/tests/binary/hook-pre-tool-use.test.ts`).
+ * So this global carrier is safe: a Kimi session outside a managed repo
+ * still invokes `adl hook`, which no-ops before any rule runs.
+ */
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+export const BEGIN = '# BEGIN ADL KIMI HOOKS'
+export const END = '# END ADL KIMI HOOKS'
+
+/**
+ * Legacy markers used before the Enact -> adl rename. A real Kimi install
+ * that has not yet re-reconciled since the rename still carries a managed
+ * block delimited by these exact strings (byte-for-byte, see
+ * `PREVIOUS_ENACT_HOOK_BLOCK` in `tests/kimi-hooks-upgrade.test.ts`). Every
+ * marker-locating function below checks the current markers first, then
+ * falls back to these, so a legacy-marked block is found, classified, and
+ * replaced IN PLACE with the current-marker block on a plain apply/uninstall
+ * — never left orphaned alongside a freshly-inserted second block.
+ */
+const LEGACY_BEGIN = '# BEGIN ENACT KIMI HOOKS'
+const LEGACY_END = '# END ENACT KIMI HOOKS'
+
+const HOOK_BIN = 'adl hook'
+
+/**
+ * Broad file-write tool matcher shared with every other host's CRG
+ * after-file-edit hook (same set `agent-surfaces` deploys for Claude, Codex,
+ * Cursor, and OpenCode) — Kimi's own docs do not enumerate a canonical tool
+ * name list, so this reuses the fleet-wide superset rather than guessing a
+ * Kimi-specific subset; an alternative name that does not exist on this host
+ * simply never matches.
+ */
+const CRG_WRITE_MATCHER =
+  'Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file'
+
+export interface HookEntry {
+  readonly event: string
+  readonly matcher?: string
+  readonly command: string
+  readonly timeout: number
+}
+
+/**
+ * The eight ADL hook wirings for Kimi, mapped onto Kimi's own documented
+ * event names. This is kept in parity with the canonical enact-repo
+ * `hooks.json` (`enact-extensions/extensions/enact-repo/hooks/hooks.json`,
+ * read-only reference — see the "why hardcode, not derive" note below):
+ *   - PreToolUse (no matcher -> every tool) -> pre-tool-use gate
+ *   - PreToolUse (matcher "Bash") -> CRG pre-commit
+ *   - PreToolUse (no matcher -> every tool) -> lean-ctx pre-tool-use
+ *   - UserPromptSubmit (no matcher -> every prompt) -> skill-match suggestions
+ *   - SessionStart (no matcher -> both "startup" and "resume") -> briefing
+ *   - PostToolUse on file-write tools -> CRG after-file-edit
+ *   - PostToolUse (no matcher -> every tool) -> lean-ctx post-tool-use
+ *   - SessionEnd (no matcher -> both "exit" and "archive"; the session-close
+ *     event, not the per-turn "Stop" event) -> CRG session-stop, matching
+ *     every other host's own sessionEnd/SessionEnd wiring for this hook.
+ *
+ * Order within PreToolUse mirrors the canonical file exactly: catch-all guard
+ * -> Bash-matched crg pre-commit -> catch-all lean-ctx. The guard must see
+ * every tool before host-specific narrower checks run.
+ *
+ * Why this is hardcoded rather than derived from the canonical hooks list at
+ * runtime/build: this script is invoked standalone (`bin/kimi-hooks`) on any
+ * machine with `adl` on PATH, and must not depend on a sibling package's
+ * checkout existing, being up to date, or even being present at apply time —
+ * `--home` may point at a machine that never cloned this repo at all beyond
+ * the fleet's compiled binaries. A runtime read would either silently skip
+ * parity (bad: no signal that the source drifted) or hard-fail
+ * apply/uninstall on a missing file (bad: this script's job is to be
+ * applicable anywhere `adl hook` runs).
+ *
+ * `test/kimi-hooks-drift.test.ts` holds the independently specified Kimi hook
+ * contract. It does not depend on a removed Claude-plugin projection or a
+ * pinned copy, so a deployer change requires an explicit behavior review.
+ */
+export const MANAGED_HOOKS: readonly HookEntry[] = [
+  { event: 'PreToolUse', command: `${HOOK_BIN} pre-tool-use --host=kimi`, timeout: 30 },
+  { event: 'PreToolUse', matcher: 'Bash', command: `${HOOK_BIN} crg pre-commit --host=kimi`, timeout: 30 },
+  { event: 'PreToolUse', command: `${HOOK_BIN} lean-ctx pre-tool-use --host=kimi`, timeout: 30 },
+  { event: 'UserPromptSubmit', command: `${HOOK_BIN} user-prompt-submit --host=kimi`, timeout: 30 },
+  { event: 'SessionStart', command: `${HOOK_BIN} briefing --host=kimi`, timeout: 15 },
+  { event: 'PostToolUse', matcher: CRG_WRITE_MATCHER, command: `${HOOK_BIN} crg after-file-edit --host=kimi`, timeout: 30 },
+  { event: 'PostToolUse', command: `${HOOK_BIN} lean-ctx post-tool-use --host=kimi`, timeout: 30 },
+  { event: 'SessionEnd', command: `${HOOK_BIN} crg session-stop --host=kimi`, timeout: 30 },
+]
+
+function tomlEntry(entry: HookEntry): string {
+  const lines = ['[[hooks]]', `event = ${JSON.stringify(entry.event)}`]
+  if (entry.matcher !== undefined) lines.push(`matcher = ${JSON.stringify(entry.matcher)}`)
+  lines.push(`command = ${JSON.stringify(entry.command)}`, `timeout = ${entry.timeout}`)
+  return lines.join('\n')
+}
+
+export function managedBlock(): string {
+  const header = [
+    BEGIN,
+    '# Deployed by packages/agent-settings/src/kimi-hooks.ts (bin/kimi-hooks).',
+    '# Everything between the markers is regenerated on every apply —',
+    '# edit the deployer, not this block.',
+  ]
+  const body = MANAGED_HOOKS.map(tomlEntry).join('\n\n')
+  return [...header, body, END].join('\n')
+}
+
+/**
+ * sha256 of every managed block this script has ever shipped, in order,
+ * EXCLUDING the current one (which `matches` already covers). This lets
+ * `classifyBlock` tell "an older version of our own block" (safe to
+ * upgrade on a plain apply/uninstall, no --force) apart from "a human
+ * edited it, or it's foreign content that happens to sit between our
+ * markers" (drifted — requires --force). Append, never remove or reorder,
+ * a new hash here whenever MANAGED_HOOKS changes; compute it as
+ * `sha256(managedBlock())` against the pre-change source.
+ */
+const PRIOR_BLOCK_HASHES: readonly string[] = [
+  // 5-hook block (PreToolUse guard, UserPromptSubmit, SessionStart, PostToolUse crg, SessionEnd) —
+  // shipped before crg pre-commit / lean-ctx pre-tool-use / lean-ctx post-tool-use parity was added.
+  'fa83560b374bb59b7a45ffa91b5c9d3bfbc2aea36b7e28293b58168fb77db292',
+  // 8-hook block before the repository guard became a catch-all PreToolUse hook.
+  '9e6ef84ff230cf29011408dfc7d5798059a6df7790892213efc343e03381d85a',
+  // 8-hook block calling the standalone `enact-hook` binary, before it folded
+  // into the one `adl` binary (item 15/P4, docs/specs/two-branch-standard-
+  // 2026-09-27.md) and HOOK_BIN became `adl hook` — hard cut, no compat shim.
+  '0fa75023b0bb836c199bb0f1f7327fafacea73b4e494a0f45662a1fa3522b7ef',
+  // Same 8-hook `enact-hook` body as the entry above, but from one generation
+  // earlier: the header comment still reads the pre-reorg deployer path
+  // ("global-surface-sweep/src/kimi-hooks.ts") because `acf8ab1` (reorganise
+  // packages into the adl layout) moved this file to
+  // packages/agent-settings/src/kimi-hooks.ts as a pure rename (R100) without
+  // touching its content, so the header string stayed stale until the later
+  // enact-wording-removal commit (ce8979e) rewrote it. A real Kimi install
+  // provisioned by a fleet binary from that window carries exactly this text
+  // — see PREVIOUS_GLOBAL_SURFACE_SWEEP_BLOCK in
+  // tests/kimi-hooks-upgrade.test.ts. Without this hash, that install's
+  // managed block was classified `drifted` instead of `ours-outdated`,
+  // aborting a plain `apply` with "hand-edited, or unrecognized content"
+  // even though it is byte-for-byte a block this deployer itself shipped.
+  'bc3f34452cbec3dc0aeb77d917816fd4fbc73a8baedfa09f4e9313a56b330d94',
+]
+
+function hashBlock(text: string): string {
+  return createHash('sha256').update(text).digest('hex')
+}
+
+export type BlockState = 'missing' | 'matches' | 'ours-outdated' | 'drifted' | 'malformed'
+
+interface Region {
+  readonly start: number
+  /** Exclusive — the index immediately after the closing marker's text. */
+  readonly end: number
+}
+
+type RegionResult = Region | 'missing' | 'malformed'
+
+function findRegion(content: string, begin: string, end: string): RegionResult {
+  const start = content.indexOf(begin)
+  const stop = content.indexOf(end)
+  if (start < 0 && stop < 0) return 'missing'
+  if (start < 0 || stop < 0 || stop < start) return 'malformed'
+  return { start, end: stop + end.length }
+}
+
+/**
+ * Locates the managed region using the current markers first, falling back
+ * to the legacy (pre-rename) markers so an old-marker block already on disk
+ * is found, classified, and replaced exactly like a current-marker one —
+ * never mistaken for "missing" and duplicated alongside a fresh insert.
+ */
+function locateManagedRegion(content: string): RegionResult {
+  const current = findRegion(content, BEGIN, END)
+  if (current !== 'missing') return current
+  return findRegion(content, LEGACY_BEGIN, LEGACY_END)
+}
+
+/**
+ * Pure classification of the managed region's ownership state against the
+ * current canonical block. No I/O: callers read the file (or `null` when
+ * missing) and pass it in.
+ */
+export function classifyBlock(existingContent: string | null): BlockState {
+  if (existingContent === null || existingContent.length === 0) return 'missing'
+  const region = locateManagedRegion(existingContent)
+  if (region === 'missing') return 'missing'
+  if (region === 'malformed') return 'malformed'
+  const installed = existingContent.slice(region.start, region.end)
+  if (installed === managedBlock()) return 'matches'
+  return PRIOR_BLOCK_HASHES.includes(hashBlock(installed)) ? 'ours-outdated' : 'drifted'
+}
+
+function spliceIn(base: string): string {
+  const block = managedBlock()
+  const region = locateManagedRegion(base)
+  if (region !== 'missing' && region !== 'malformed') {
+    return `${base.slice(0, region.start)}${block}${base.slice(region.end)}`
+  }
+  if (base.length === 0) return `${block}\n`
+  const trimmed = base.replace(/\n+$/, '')
+  return `${trimmed}\n\n${block}\n`
+}
+
+/**
+ * Exact inverse of the append branch of spliceIn: trims the newlines spliceIn
+ * added around the block (trailing newlines on the head, leading newlines on
+ * the tail) rather than a blanket multi-blank-line collapse, so removing a
+ * freshly-applied block returns the file to byte-identical pre-apply content.
+ */
+function spliceOut(base: string): string {
+  const region = locateManagedRegion(base)
+  if (region === 'missing' || region === 'malformed') return base
+  const head = base.slice(0, region.start).replace(/\n+$/, '')
+  const tail = base.slice(region.end).replace(/^\n+/, '')
+  if (head.length === 0) return tail
+  if (tail.length === 0) return `${head}\n`
+  return `${head}\n\n${tail}`
+}
+
+function resolveConfigPath(home: string): string {
+  if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`)
+  return join(resolve(home), '.kimi-code', 'config.toml')
+}
+
+function readConfig(path: string): string | null {
+  if (!existsSync(path)) return null
+  return readFileSync(path, 'utf8')
+}
+
+/** Real TOML syntax check via Bun's built-in parser — never a stub. */
+function assertParseable(text: string, context: string): void {
+  if (text.trim().length === 0) return
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun global, no @types/bun in this package
+    ;(globalThis as any).Bun.TOML.parse(text)
+  } catch (error) {
+    throw new Error(`${context} is not valid TOML: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/** Best-effort schema check against the real `kimi` CLI when it is on PATH; a no-op note otherwise. */
+function doctorCheck(path: string): string | null {
+  const which = spawnSync('bash', ['-lc', 'command -v kimi'], { encoding: 'utf8' })
+  if (which.status !== 0) return null
+  const result = spawnSync('kimi', ['doctor', 'config', path], { encoding: 'utf8' })
+  if (result.status !== 0) {
+    throw new Error(`kimi doctor rejected the candidate config: ${(result.stderr || result.stdout || '').trim()}`)
+  }
+  return 'kimi doctor: OK'
+}
+
+function backupPath(configPath: string): string {
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
+  return `${configPath}.pre-kimi-hooks-${stamp}`
+}
+
+/**
+ * Validate the candidate, stage it in a temp file, run the best-effort
+ * `kimi doctor` check against the STAGED file (never the live one), back up
+ * the existing file, then atomically rename the staged file into place. A
+ * rejected candidate leaves the existing config completely untouched.
+ */
+function commitConfig(path: string, next: string, notes: string[]): string | undefined {
+  assertParseable(next, 'candidate config')
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = join(dirname(path), `.kimi-hooks.${process.pid}.${Date.now()}.tmp`)
+  writeFileSync(temporary, next)
+  try {
+    const doctorNote = doctorCheck(temporary)
+    if (doctorNote) notes.push(doctorNote)
+  } catch (error) {
+    rmSync(temporary, { force: true })
+    throw error
+  }
+  let backup: string | undefined
+  if (existsSync(path)) {
+    backup = backupPath(path)
+    copyFileSync(path, backup)
+    notes.push(`backed up previous config to ${backup}`)
+  }
+  renameSync(temporary, path)
+  return backup
+}
+
+export interface PlanResult {
+  readonly path: string
+  readonly state: BlockState
+  readonly wouldChangeOnApply: boolean
+  readonly wouldChangeOnUninstall: boolean
+}
+
+/** Read-only: current state and what apply/uninstall would do. Never touches the file. */
+export function planKimiHooks(home: string): PlanResult {
+  const path = resolveConfigPath(home)
+  const state = classifyBlock(readConfig(path))
+  return {
+    path,
+    state,
+    wouldChangeOnApply: state === 'missing' || state === 'drifted' || state === 'ours-outdated',
+    wouldChangeOnUninstall: state === 'matches' || state === 'drifted' || state === 'ours-outdated',
+  }
+}
+
+export interface OpResult {
+  readonly path: string
+  readonly stateBefore: BlockState
+  readonly action: 'none' | 'installed' | 'updated' | 'removed'
+  readonly notes: readonly string[]
+  readonly backupPath: string | undefined
+}
+
+export function applyKimiHooks(home: string, options: { readonly force?: boolean } = {}): OpResult {
+  const path = resolveConfigPath(home)
+  const base = readConfig(path)
+  const state = classifyBlock(base)
+  const notes: string[] = []
+
+  if (state === 'malformed') {
+    throw new Error(`malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`)
+  }
+  if (base !== null) assertParseable(base, path)
+
+  if (state === 'matches') {
+    notes.push('managed hook block already present and canonical')
+    return { path, stateBefore: state, action: 'none', notes, backupPath: undefined }
+  }
+  if (state === 'ours-outdated') {
+    notes.push('upgrading managed hook block from a previous ENACT version (no --force needed)')
+  }
+  if (state === 'drifted' && !(options.force ?? false)) {
+    throw new Error(
+      `${path} has a managed hook block that differs from the canonical block (hand-edited, or unrecognized content) — rerun apply with --force to overwrite it`,
+    )
+  }
+
+  const next = spliceIn(base ?? '')
+  const backup = commitConfig(path, next, notes)
+  return { path, stateBefore: state, action: state === 'missing' ? 'installed' : 'updated', notes, backupPath: backup }
+}
+
+export function uninstallKimiHooks(home: string, options: { readonly force?: boolean } = {}): OpResult {
+  const path = resolveConfigPath(home)
+  const base = readConfig(path)
+  const state = classifyBlock(base)
+  const notes: string[] = []
+
+  if (state === 'malformed') {
+    throw new Error(`malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`)
+  }
+  if (base !== null) assertParseable(base, path)
+
+  if (state === 'missing') {
+    notes.push('managed hook block not present; nothing to remove')
+    return { path, stateBefore: state, action: 'none', notes, backupPath: undefined }
+  }
+  if (state === 'ours-outdated') {
+    notes.push('removing managed hook block from a previous ENACT version (no --force needed)')
+  }
+  if (state === 'drifted' && !(options.force ?? false)) {
+    throw new Error(
+      `${path} has a managed hook block that differs from the canonical block (hand-edited, or unrecognized content) — rerun uninstall with --force to remove it anyway`,
+    )
+  }
+
+  const next = spliceOut(base as string)
+  const backup = commitConfig(path, next, notes)
+  return { path, stateBefore: state, action: 'removed', notes, backupPath: backup }
+}
+
+function usage(): never {
+  throw new Error('usage: kimi-hooks --home ABSOLUTE_PATH --mode plan|apply|uninstall [--force]')
+}
+
+export function main(argv: readonly string[]): void {
+  let home = ''
+  let mode = ''
+  let force = false
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (argument === '--home') home = argv[++index] ?? ''
+    else if (argument === '--mode') mode = argv[++index] ?? ''
+    else if (argument === '--force') force = true
+    else usage()
+  }
+  if (home.length === 0 || !['plan', 'apply', 'uninstall'].includes(mode)) usage()
+
+  if (mode === 'plan') {
+    const result = planKimiHooks(home)
+    console.log(`kimi-hooks: config=${result.path}`)
+    console.log(`kimi-hooks: state=${result.state}`)
+    console.log(`kimi-hooks: apply would ${result.wouldChangeOnApply ? 'change this file' : 'no-op'}`)
+    console.log(`kimi-hooks: uninstall would ${result.wouldChangeOnUninstall ? 'change this file' : 'no-op'}`)
+    return
+  }
+
+  const result = mode === 'apply' ? applyKimiHooks(home, { force }) : uninstallKimiHooks(home, { force })
+  for (const note of result.notes) console.log(`kimi-hooks: ${note}`)
+  console.log(`kimi-hooks: ${result.action} (${result.path})`)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (cause) {
+    console.error(`kimi-hooks: ${cause instanceof Error ? cause.message : String(cause)}`)
+    process.exitCode = 1
+  }
+}

package/packages/agent-settings/src/opencode-hooks.ts

@@ -0,0 +1,76 @@
+/**
+ * Retire the superseded global OpenCode hook carrier.
+ *
+ * OpenCode now discovers the canonical carrier from each managed project's
+ * `.opencode/plugins/enact-repo.ts`. Keeping the old global file would load
+ * both carriers and run every hook twice. This utility removes only the exact
+ * former Enact-owned file; the rest of OpenCode's plugin namespace is not ours.
+ */
+
+import { lstatSync, rmSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+
+const RETIRED_CARRIER_RELATIVE_PATH = ".config/opencode/plugins/enact-repo.ts";
+
+export type RetiredCarrierState = "missing" | "present";
+export type RetiredCarrierAction = "removed" | "unchanged";
+
+export function pluginPath(home: string): string {
+	if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`);
+	return join(resolve(home), RETIRED_CARRIER_RELATIVE_PATH);
+}
+
+export function classifyRetiredCarrier(home: string): RetiredCarrierState {
+	return lstatSync(pluginPath(home), { throwIfNoEntry: false }) ? "present" : "missing";
+}
+
+/** Remove exactly the former global carrier, never its directory or siblings. */
+export function removeOpenCodeHooks(home: string): { readonly action: RetiredCarrierAction; readonly path: string } {
+	const path = pluginPath(home);
+	const state = lstatSync(path, { throwIfNoEntry: false });
+	if (!state) return { action: "unchanged", path };
+	if (state.isDirectory()) throw new Error(`retired OpenCode carrier must be a file or symlink: ${path}`);
+	rmSync(path, { force: true });
+	return { action: "removed", path };
+}
+
+function parseArgs(args: readonly string[]): { home: string; mode: "plan" | "remove" } {
+	let home: string | undefined;
+	let mode: "plan" | "remove" | undefined;
+	for (let index = 0; index < args.length; index++) {
+		const arg = args[index];
+		if (arg === "--home") home = args[++index];
+		else if (arg === "--mode") {
+			const value = args[++index];
+			if (value === "plan" || value === "remove") mode = value;
+			else throw new Error(`--mode must be plan or remove: ${value ?? ""}`);
+		} else throw new Error(`unknown argument: ${arg}`);
+	}
+	if (!home) throw new Error("--home is required");
+	if (!mode) throw new Error("--mode is required");
+	return { home, mode };
+}
+
+export function main(args: readonly string[]): number {
+	const { home, mode } = parseArgs(args);
+	const path = pluginPath(home);
+	const state = classifyRetiredCarrier(home);
+	process.stdout.write(`opencode-hooks: plugin=${path}\n`);
+	process.stdout.write(`opencode-hooks: state=${state}\n`);
+	if (mode === "plan") {
+		process.stdout.write(state === "present" ? "opencode-hooks: would remove retired carrier\n" : "opencode-hooks: none\n");
+		return 0;
+	}
+	const result = removeOpenCodeHooks(home);
+	process.stdout.write(`opencode-hooks: ${result.action}\n`);
+	return 0;
+}
+
+if (import.meta.main) {
+	try {
+		process.exitCode = main(process.argv.slice(2));
+	} catch (error) {
+		process.stderr.write(`opencode-hooks: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exitCode = 1;
+	}
+}