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

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

@@ -0,0 +1,269 @@
+#!/usr/bin/env bun
+/**
+ * adl hook — CLI entry point.
+ *
+ * Contract (fixed; host hook commands are generated against this by another
+ * workstream, do not change without updating them too):
+ *
+ *   adl hook <kind> [subcommand] --host=<claude|codex|cursor|kimi|opencode>
+ *
+ *   kinds: pre-tool-use, user-prompt-submit, briefing, crg <subcommand>,
+ *          lean-ctx <subcommand>
+ *   crg subcommands: after-file-edit, pre-commit, session-stop
+ *   lean-ctx subcommands: mcp, pre-tool-use, post-tool-use
+ *   payload: JSON on stdin (NOT for `lean-ctx mcp` — see below)
+ *   --version prints the package version and exits 0
+ *
+ * Operator commands (src/cli/; no --host, no stdin):
+ *
+ *   adl hook rules list [--repo <path>] [--json]
+ *   adl hook rules show <id> [--repo <path>] [--json]
+ *   adl hook doctor [--repo <path>]
+ *
+ * Per-repo gating (HARDCUT replacement for enact-repo-controls's
+ * `.agents/controls.toml` MARKER scheme — see src/gating/):
+ *
+ *   - Walk up from the payload's cwd to the git root (src/gating/root.ts).
+ *   - No git root, or no `adl-config.toml` there: unmanaged repo,
+ *     silent no-op (exit 0, empty stdout/stderr).
+ *   - `adl-config.toml` present but fails to parse/decode: fail
+ *     loud (non-zero exit, reason on stderr) — never silently ignored.
+ *   - `[hooks] enabled = false`: silent no-op, same as unmanaged.
+ *
+ * `lean-ctx mcp` is the one exception to this whole flow (work item A.1): it
+ * takes no JSON payload, needs no `--host`, and never no-ops for an
+ * unmanaged repo (an MCP client that just spawned it expects a running
+ * server, not a silent exit) — see `src/lean-ctx/mcp.ts`'s header. It is
+ * dispatched before `--host` resolution, before stdin is read at all, and
+ * bypasses `HookHandler`/`HookResult` entirely (real stdio passthrough
+ * cannot be buffered into a string).
+ *
+ * Every other hook kind is dispatched through the shared `HookHandler` shape
+ * in `src/hooks/contract.ts` so a handler never touches `process`, argv, or
+ * stdin directly.
+ *
+ * Invalid JSON on stdin (work item D): every OTHER kind used to fail closed
+ * at exit code 2 uniformly. That is correct ONLY for `pre-tool-use` — it is
+ * the one kind whose contract is "block a dangerous action," so failing
+ * closed (deny) on an undecidable payload is the safe default, and exit 2 is
+ * the shared fail-closed signal `pre-tool-use`'s own decisions already use
+ * (`FAIL_CLOSED_EXIT_CODE`, `src/rules/engine.ts`) for Kimi/OpenCode denials.
+ * Every other kind is advisory or best-effort (`user-prompt-submit`,
+ * `briefing`, `crg`, `lean-ctx` pre/post/mcp) and none of them has a "block"
+ * concept at all — worse, on Claude Code and Codex, exit code 2 from
+ * `UserPromptSubmit` specifically blocks the prompt AND ERASES IT (documented
+ * Claude Code hook behaviour: a `UserPromptSubmit` hook exiting 2 shows
+ * stderr to the user and the prompt is not processed), and has other
+ * host-specific effects for `SessionStart`/`PostToolUse` (context is
+ * dropped/the tool call is treated as failed) that a merely-malformed-input
+ * error should never trigger. So invalid JSON on stdin for any non-
+ * `pre-tool-use` kind fails at exit 1 instead — a plain, non-blocking error
+ * — never 2.
+ *
+ * Missing/unknown `--host` (az385) follows the identical split, for the
+ * identical reason: `pre-tool-use` cannot decide anything without a host to
+ * render a decision for, so it fails CLOSED at `FAIL_CLOSED_EXIT_CODE`;
+ * every other kind fails at the plain `NON_BLOCKING_FAIL_EXIT_CODE` (1), same
+ * as an unrecognized hook kind or subcommand.
+ */
+
+import { readFileSync } from 'node:fs'
+// A real static import, not a runtime readFileSync path lookup: `bun build
+// --compile` bundles every statically-imported module (JSON included) into
+// the compiled executable, so this resolves correctly both under `bun run
+// src/main.ts` and inside the compiled binary. A `readFileSync(join(import.meta.dir,
+// '..', 'package.json'))` path does NOT work in the compiled binary —
+// `import.meta.dir` there is a virtual `/$bunfs/...` path, and package.json
+// is never embedded unless something actually imports it — `--version`
+// crashed with ENOENT before this fix (integration-pass bug fix, migration
+// task item 5/6).
+import packageJson from '../package.json'
+import type { HookHandler, HookInvocation, HookResult } from './hooks/contract.ts'
+import { payloadCwd } from './hooks/contract.ts'
+import { resolveHost, readHostFlag, type HostId } from './hosts/spec.ts'
+import { resolveManagedRepo, realRootIO } from './gating/root.ts'
+import { decodeConfig, type AdlRepoConfig } from './gating/config.ts'
+import { FAIL_CLOSED_EXIT_CODE } from './rules/engine.ts'
+import { handlePreToolUse } from './pre-tool-use/handler.ts'
+import { handleUserPromptSubmit } from './hooks/user-prompt-submit/handler.ts'
+import { handleBriefing } from './hooks/briefing/handler.ts'
+import { handleCrg } from './hooks/crg/handler.ts'
+import { handleLeanCtx } from './hooks/lean-ctx/handler.ts'
+import { runLeanCtxMcp } from './lean-ctx/mcp.ts'
+import { runRules } from './cli/rules.ts'
+import { runDoctor } from './cli/doctor.ts'
+import { runLogged } from './hooks/log.ts'
+
+const HOOK_KINDS = ['pre-tool-use', 'user-prompt-submit', 'briefing', 'crg', 'lean-ctx'] as const
+type HookKind = (typeof HOOK_KINDS)[number]
+
+function isHookKind(value: string | undefined): value is HookKind {
+  return value !== undefined && (HOOK_KINDS as readonly string[]).includes(value)
+}
+
+const CRG_SUBCOMMANDS = ['after-file-edit', 'pre-commit', 'session-stop'] as const
+const LEAN_CTX_SUBCOMMANDS = ['mcp', 'pre-tool-use', 'post-tool-use'] as const
+
+const HANDLERS: Readonly<Record<HookKind, HookHandler>> = {
+  'pre-tool-use': handlePreToolUse,
+  'user-prompt-submit': handleUserPromptSubmit,
+  briefing: handleBriefing,
+  crg: handleCrg,
+  'lean-ctx': handleLeanCtx,
+}
+
+/** Exit code `pre-tool-use` alone uses to fail closed on an undecidable payload — see this file's header (work item D). */
+const NON_BLOCKING_FAIL_EXIT_CODE = 1
+
+function readPackageVersion(): string {
+  const pkg = packageJson as { version?: string }
+  return pkg.version ?? 'unknown'
+}
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) return ''
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk))
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+function silentNoop(): HookResult {
+  return { stdout: '', stderr: '', exitCode: 0 }
+}
+
+function writeResult(result: HookResult): number {
+  if (result.stdout.length > 0) process.stdout.write(result.stdout)
+  if (result.stderr.length > 0) process.stderr.write(result.stderr)
+  return result.exitCode
+}
+
+export async function run(argv: readonly string[]): Promise<number> {
+  if (argv.includes('--version')) {
+    process.stdout.write(`${readPackageVersion()}\n`)
+    return 0
+  }
+
+  // Operator commands, not hooks: no --host, no stdin payload, never a silent no-op (see src/cli/).
+  if (argv[0] === 'rules') return writeResult(runRules(argv.slice(1), process.cwd()))
+  if (argv[0] === 'doctor') return writeResult(await runDoctor(argv.slice(1), process.cwd(), process.env))
+
+  const kindArg = argv[0]
+  if (!isHookKind(kindArg)) {
+    process.stderr.write(
+      `adl hook: unknown or missing hook kind '${kindArg ?? ''}' (expected one of ${HOOK_KINDS.join(', ')})\n`,
+    )
+    return 1
+  }
+  const kind: HookKind = kindArg
+
+  let subcommand: string | undefined
+  if (kind === 'crg') {
+    const candidate = argv[1]
+    if (candidate === undefined || !(CRG_SUBCOMMANDS as readonly string[]).includes(candidate)) {
+      process.stderr.write(
+        `adl hook: crg requires a subcommand (one of ${CRG_SUBCOMMANDS.join(', ')})\n`,
+      )
+      return 1
+    }
+    subcommand = candidate
+  }
+  if (kind === 'lean-ctx') {
+    const candidate = argv[1]
+    if (candidate === undefined || !(LEAN_CTX_SUBCOMMANDS as readonly string[]).includes(candidate)) {
+      process.stderr.write(
+        `adl hook: lean-ctx requires a subcommand (one of ${LEAN_CTX_SUBCOMMANDS.join(', ')})\n`,
+      )
+      return 1
+    }
+    subcommand = candidate
+  }
+
+  // `lean-ctx mcp` bypasses everything below: no --host, no stdin-as-JSON,
+  // no HookHandler dispatch, and unmanaged is NOT a no-op — see
+  // `./lean-ctx/mcp.ts`'s header and this file's own header (work item A.1).
+  if (kind === 'lean-ctx' && subcommand === 'mcp') {
+    return runLeanCtxMcp(process.cwd(), process.env)
+  }
+
+  // az385: host resolution failure fails CLOSED (FAIL_CLOSED_EXIT_CODE, 2)
+  // only for pre-tool-use — the one kind whose job is "block a dangerous
+  // action," matching the invalid-JSON-on-stdin split a few lines below and
+  // this file's header. Every other host-requiring kind stays at the plain
+  // non-blocking exit 1 it always used.
+  const rawHost = readHostFlag(argv)
+  const host: HostId | null = resolveHost(argv)
+  if (host === null) {
+    const exitCode = kind === 'pre-tool-use' ? FAIL_CLOSED_EXIT_CODE : NON_BLOCKING_FAIL_EXIT_CODE
+    process.stderr.write(`adl hook: missing or unrecognized --host (got '${rawHost ?? ''}')\n`)
+    return exitCode
+  }
+
+  const stdinText = await readStdin()
+  let payload: Record<string, unknown>
+  try {
+    payload = stdinText.length > 0 ? (JSON.parse(stdinText) as Record<string, unknown>) : {}
+  } catch (error) {
+    // Fail closed (exit 2) ONLY for `pre-tool-use` — every other kind fails
+    // at exit 1 instead (non-blocking error, never a host-side block/erase
+    // side effect). See this file's header, work item D, for the full
+    // reasoning and the host-documented behaviour this avoids.
+    const exitCode = kind === 'pre-tool-use' ? FAIL_CLOSED_EXIT_CODE : NON_BLOCKING_FAIL_EXIT_CODE
+    process.stderr.write(`adl hook: invalid JSON payload on stdin: ${String(error)}\n`)
+    return exitCode
+  }
+
+  const cwd = payloadCwd(payload) ?? process.cwd()
+  // Tarun's rule (2026-09-29): hooks run ONLY in a repo with a real
+  // `adl-config.toml` where `adl hooks deploy` has run — nowhere else. No
+  // git root, or no `adl-config.toml` above `cwd`: a strict no-op (this
+  // file's own header) — no rule evaluation, no identity check, no
+  // `hooks.log` write. This REVERSES the earlier "global identity baseline"
+  // (W2 build item 3 / STATUS.md 12p): that baseline
+  // ran the four (later seven, R2) identity rules even in an unmanaged
+  // repo; Tarun decided the repos where `adl-config.toml` does not exist
+  // have no business running hooks at all.
+  const managed = resolveManagedRepo(realRootIO, cwd)
+  if (!managed.managed || managed.root === null || managed.configPath === null) {
+    return writeResult(silentNoop())
+  }
+
+  let config: AdlRepoConfig
+  {
+    const text = readFileSync(managed.configPath, 'utf8')
+    const decoded = decodeConfig(text)
+    if (!decoded.ok) {
+      process.stderr.write(
+        `adl hook: invalid ${managed.configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}\n`,
+      )
+      return 1
+    }
+    config = decoded.value
+  }
+
+  if (!config.hooks.enabled) {
+    return writeResult(silentNoop())
+  }
+
+  const invocation: HookInvocation = {
+    kind,
+    host,
+    payload,
+    root: managed.root,
+    env: process.env,
+    ...(subcommand !== undefined ? { subcommand } : {}),
+  }
+
+  // Managed + hooks-enabled only: deny log + activity log (src/hooks/log.ts), best-effort, never changes the result.
+  const result = await runLogged(invocation, HANDLERS[kind])
+  return writeResult(result)
+}
+
+if (import.meta.main) {
+  run(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      process.stderr.write(`adl hook: unhandled error: ${String(error)}\n`)
+      process.exit(1)
+    },
+  )
+}