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

package/packages/agent-hooks/src/hooks/user-prompt-submit/tokenizer.ts

@@ -0,0 +1,115 @@
+/**
+ * Minimal Unigram tokenizer over the pruned tokenizer.json of the
+ * adl-embedding artifact. Pure TS — no dependency on a native tokenizer
+ * package.
+ *
+ * Ported unchanged from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/tokenizer.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/src/tokenizer.mjs` in enact-m5).
+ *
+ * Deliberate approximation of the upstream SentencePiece pipeline: the
+ * precompiled-charsmap normalizer is a serialized normalization trie with no
+ * practical JS port, so this applies NFKC (what that charsmap mostly is for
+ * Latin scripts) and Metaspace exactly. Queries and documents go through the
+ * SAME tokenizer in this process, so ranking is self-consistent even where a
+ * tokenization differs from the backend's.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Score given to a consumed unknown character. Rare real tokens sit above -8;
+ * anything below forces the Viterbi to prefer known tokens and burn single
+ * characters only where nothing matches.
+ */
+const UNK_PENALTY = -10
+
+export interface Tokenizer {
+  tokenize(text: string): number[]
+  readonly unkId: number
+}
+
+/** Load the tokenizer half of an installed artifact. */
+export function loadTokenizer(artifactDir: string): Tokenizer {
+  const parsed = JSON.parse(readFileSync(join(artifactDir, 'tokenizer.json'), 'utf8')) as {
+    model: { vocab: [string, number][]; unk_id?: number }
+  }
+  const vocabList = parsed.model.vocab
+  const unkId = parsed.model.unk_id ?? 1
+
+  const vocab = new Map<string, { id: number; score: number }>()
+  let maxTokenLength = 1
+  for (let id = 0; id < vocabList.length; id++) {
+    const entry = vocabList[id] as [string, number]
+    const [token, score] = entry
+    vocab.set(token, { id, score })
+    if (token.length > maxTokenLength) maxTokenLength = token.length
+  }
+
+  /**
+   * Metaspace: NFKC, then whitespace -> ▁ with a leading ▁ (prepend_scheme
+   * "always", split false — the replacement joins, it does not split pieces).
+   */
+  function normalize(text: string): string {
+    return '▁' + text.normalize('NFKC').replace(/\s/g, '▁')
+  }
+
+  function relaxKnownTokens(s: string, index: number, best: Float64Array, back: Int32Array): boolean {
+    let matched = false
+    const maxLen = Math.min(maxTokenLength, s.length - index)
+    for (let len = 1; len <= maxLen; len++) {
+      const entry = vocab.get(s.slice(index, index + len))
+      if (entry === undefined) continue
+      matched = true
+      const candidate = (best[index] as number) + entry.score
+      if (candidate <= (best[index + len] as number)) continue
+      best[index + len] = candidate
+      back[index + len] = index
+    }
+    return matched
+  }
+
+  function relaxUnknown(index: number, best: Float64Array, back: Int32Array): void {
+    const candidate = (best[index] as number) + UNK_PENALTY
+    if (candidate <= (best[index + 1] as number)) return
+    best[index + 1] = candidate
+    back[index + 1] = index
+  }
+
+  function collectTokenIds(s: string, back: Int32Array): number[] {
+    const ids: number[] = []
+    let end = s.length
+    while (end > 0) {
+      const start = back[end] as number
+      if (start === -1) break
+      const entry = vocab.get(s.slice(start, end))
+      if (entry) ids.push(entry.id)
+      end = start
+    }
+    return ids.reverse()
+  }
+
+  /**
+   * Unigram Viterbi: best-sum log-probability segmentation. A position with
+   * no matching token advances one character as an unk; the caller (embed)
+   * drops unk ids, matching the backend embedder's semantics.
+   */
+  function tokenize(text: string): number[] {
+    const s = normalize(text)
+    const n = s.length
+    const best = new Float64Array(n + 1).fill(Number.NEGATIVE_INFINITY)
+    const back = new Int32Array(n + 1).fill(-1)
+    best[0] = 0
+
+    for (let i = 0; i < n; i++) {
+      if (best[i] === Number.NEGATIVE_INFINITY) continue
+      if (!relaxKnownTokens(s, i, best, back)) relaxUnknown(i, best, back)
+    }
+
+    // Unknown spans are consumed by the Viterbi but never emitted, matching
+    // the backend embedder's `id === unkId` drop.
+    return collectTokenIds(s, back)
+  }
+
+  return { tokenize, unkId }
+}

package/packages/agent-hooks/src/hooks/user-prompt-submit/vector.ts

@@ -0,0 +1,174 @@
+/**
+ * Static (Model2Vec) embedding half: token -> row lookup + mean pooling, no
+ * forward pass.
+ *
+ * Ported unchanged from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/vector.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/src/vector.mjs` in enact-m5).
+ *
+ * One deliberate change from the enact-m5 reference: that reference resolves
+ * the artifact from a repo-local `.cache/enact-embedding/model/` directory
+ * built by that repo's own installer. This hook instead treats the model as a
+ * GLOBAL, machine-wide asset shared by every repository —
+ * `resolveGlobalArtifactDir` resolves `${XDG_CACHE_HOME:-$HOME/.cache}/adl-embedding/model/`
+ * (renamed from `enact-embedding`, matching `packages/fleet/src/install-embedding-model.ts`,
+ * the installer that actually writes this directory) from the invocation's
+ * own `env`, never `process.env` and never repo-relative.
+ *
+ * `loadVectorHalf`'s `LoadVectorResult.reason` (on `ok: false`) already
+ * carries a specific, human-readable cause (directory missing, which files
+ * are missing, bad magic, a header/manifest mismatch, a byte-length
+ * mismatch, or a thrown parse error) — `handler.ts`'s `index.ts` caller
+ * classifies that reason into a specific stderr note rather than the
+ * generic fixed string the enact-m5 hook currently emits.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const MAGIC = 'CLPEMB\0'
+const HEADER_BYTES = 16
+
+/** Longest input embedded, same cap as the backend embedder. */
+const MAX_CHARS = 8_000
+
+const ARTIFACT_FILES = ['model.bin', 'tokenizer.json', 'tokenizer_config.json', 'manifest.json']
+
+/** The global, machine-wide artifact directory — shared by every repository this hook runs in. */
+export function resolveGlobalArtifactDir(env: Readonly<Record<string, string | undefined>>): string {
+  const xdgCacheHome = env.XDG_CACHE_HOME
+  const base = xdgCacheHome && xdgCacheHome.trim() !== '' ? xdgCacheHome : join(requireHome(env), '.cache')
+  return join(base, 'adl-embedding', 'model')
+}
+
+function requireHome(env: Readonly<Record<string, string | undefined>>): string {
+  const home = env.HOME
+  if (!home || home.trim() === '') throw new Error('HOME is not set and XDG_CACHE_HOME is not set')
+  return home
+}
+
+function artifactMissingReason(dir: string): string | null {
+  if (!existsSync(dir)) return `artifact directory ${dir} does not exist`
+  const missing = ARTIFACT_FILES.filter((file) => !existsSync(join(dir, file)))
+  if (missing.length > 0) return `artifact is incomplete (missing ${missing.join(', ')})`
+  return null
+}
+
+export interface VectorHalf {
+  readonly dim: number
+  readonly rows: number
+  embed(text: string, options?: { minTokens?: number }): Float32Array | null
+}
+
+export type LoadVectorResult = { readonly ok: true; readonly half: VectorHalf; readonly reason: null } | { readonly ok: false; readonly half: null; readonly reason: string }
+
+/**
+ * Load the embedding table from `artifactDir`. `tokenize` is injected
+ * (tokenizer.ts) so this module stays free of tokenizer dependencies.
+ * `ok: false` with a human-readable reason when the artifact is absent or
+ * unreadable — callers treat that as "no vector half this time" and must say
+ * so, never swallow it silently.
+ */
+export function loadVectorHalf(artifactDir: string, tokenize: (text: string) => number[]): LoadVectorResult {
+  const missing = artifactMissingReason(artifactDir)
+  if (missing) return { ok: false, half: null, reason: missing }
+
+  try {
+    const manifest = JSON.parse(readFileSync(join(artifactDir, 'manifest.json'), 'utf8')) as { rows: number; dim: number }
+    const buf = readFileSync(join(artifactDir, 'model.bin'))
+    const magic = buf.subarray(0, MAGIC.length).toString('latin1')
+    if (magic !== MAGIC) {
+      return { ok: false, half: null, reason: `bad magic in model.bin: ${JSON.stringify(magic)}` }
+    }
+
+    const rows = buf.readUInt32LE(8)
+    const dim = buf.readUInt32LE(12)
+    if (rows !== manifest.rows || dim !== manifest.dim) {
+      return {
+        ok: false,
+        half: null,
+        reason: `model.bin (${rows}×${dim}) disagrees with manifest (${manifest.rows}×${manifest.dim})`,
+      }
+    }
+
+    const scalesEnd = HEADER_BYTES + rows * 4
+    const expected = scalesEnd + rows * dim
+    if (buf.byteLength !== expected) {
+      return { ok: false, half: null, reason: `model.bin is ${buf.byteLength} bytes, expected ${expected}` }
+    }
+
+    const scales = new Float32Array(buf.buffer.slice(buf.byteOffset + HEADER_BYTES, buf.byteOffset + scalesEnd))
+    const quant = new Int8Array(buf.buffer, buf.byteOffset + scalesEnd, rows * dim)
+
+    return { ok: true, reason: null, half: { dim, rows, embed: embedFn({ tokenize, quant, scales, rows, dim }) } }
+  } catch (error) {
+    return { ok: false, half: null, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+function embedFn({
+  tokenize,
+  quant,
+  scales,
+  rows,
+  dim,
+}: {
+  tokenize: (text: string) => number[]
+  quant: Int8Array
+  scales: Float32Array
+  rows: number
+  dim: number
+}): VectorHalf['embed'] {
+  function poolTokens(ids: readonly number[]): { out: Float32Array; used: number } {
+    const out = new Float32Array(dim)
+    let used = 0
+    for (const id of ids) {
+      if (id < 0 || id >= rows) continue
+      const offset = id * dim
+      const scale = scales[id] as number
+      for (let d = 0; d < dim; d++) out[d] = (out[d] as number) + (quant[offset + d] as number) * scale
+      used++
+    }
+    return { out, used }
+  }
+
+  function normalizePooled(out: Float32Array, used: number): Float32Array | null {
+    let norm = 0
+    for (let d = 0; d < dim; d++) {
+      out[d] = (out[d] as number) / used
+      norm += (out[d] as number) * (out[d] as number)
+    }
+    norm = Math.sqrt(norm)
+    if (norm === 0) return null
+    for (let d = 0; d < dim; d++) out[d] = (out[d] as number) / norm
+    return out
+  }
+
+  /**
+   * Embed one string; null when there are fewer than `minTokens` usable
+   * tokens. minTokens exists because mean pooling over very few tokens
+   * produces an unstable centroid that scores high against unrelated text, so
+   * short prompts fall back to the BM25 half rather than trusting a noisy
+   * vector.
+   */
+  return function embed(text, { minTokens = 1 } = {}) {
+    const trimmed = text.trim()
+    if (!trimmed) return null
+
+    const ids = tokenize(trimmed.length > MAX_CHARS ? trimmed.slice(0, MAX_CHARS) : trimmed)
+
+    // Unknown tokens carry no signal, and an out-of-range id would read past
+    // the table — both are dropped rather than pooled as zeros.
+    const { out, used } = poolTokens(ids)
+
+    if (used < minTokens) return null
+    return normalizePooled(out, used)
+  }
+}
+
+/** Cosine similarity between two L2-normalized vectors: the dot product IS the cosine. */
+export function cosine(a: Float32Array, b: Float32Array): number {
+  const n = Math.min(a.length, b.length)
+  let dot = 0
+  for (let i = 0; i < n; i++) dot += (a[i] as number) * (b[i] as number)
+  return dot
+}

package/packages/agent-hooks/src/hosts/impl/claude.ts

@@ -0,0 +1,47 @@
+/**
+ * Claude Code.
+ *
+ * Ported verbatim (decision-rendering behaviour) from enact-repo-controls's
+ * `src/hosts/impl/claude.ts`.
+ *
+ * `renderDecision`'s exact JSON shape (`hookSpecificOutput.permissionDecision`)
+ * follows Claude Code's publicly documented PreToolUse hook output contract.
+ *
+ * Integration-pass HARDCUT (migration task item 3): this file used to also
+ * export deployment concerns (`targets`, `renderContext`, `commandFor`,
+ * `briefing`, `liveProbe`, `claudeHookGroup`) — see `../spec.ts`'s header for
+ * why those were removed. Only `renderDecision`, called from
+ * `../../pre-tool-use/handler.ts`, ever runs outside a test.
+ */
+
+import type { Decision, HostSpec } from '../spec.ts'
+
+export const claudeSpec: HostSpec = {
+  id: 'claude',
+
+  renderDecision(d: Decision): unknown {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: d.verdict === 'allow' ? 'allow' : d.verdict === 'ask' ? 'ask' : 'deny',
+        permissionDecisionReason: d.agentMessage ?? d.reason,
+      },
+    }
+  },
+
+  renderRewrite(toolInput: Readonly<Record<string, unknown>>): unknown {
+    // PreToolUse `updatedInput` "modifies the tool's input parameters before
+    // execution" and "replaces the entire input object", paired with
+    // `permissionDecision: "allow"` — verified 2026-09-28 against
+    // https://code.claude.com/docs/en/hooks. Fires for Bash and MCP tools
+    // alike, which is exactly the surface the adl.git-identity rewrite
+    // (../../rules/impl/adl-git-identity.ts) exists to reach.
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: toolInput,
+      },
+    }
+  },
+}

package/packages/agent-hooks/src/hosts/impl/codex.ts

@@ -0,0 +1,47 @@
+/**
+ * Codex.
+ *
+ * Ported verbatim (decision-rendering behaviour) from enact-repo-controls's
+ * `src/hosts/impl/codex.ts`.
+ *
+ * Integration-pass HARDCUT (migration task item 3): this file used to also
+ * export deployment concerns (`targets`, `renderContext`, `commandFor`,
+ * `briefing`, `liveProbe`, `codexHookGroup`, `codexMcpTable`,
+ * `CODEX_MCP_MARKERS`) — see `../spec.ts`'s header for why those were
+ * removed. Only `renderDecision`, called from
+ * `../../pre-tool-use/handler.ts`, ever runs outside a test.
+ */
+
+import type { Decision, HostSpec } from '../spec.ts'
+
+export const codexSpec: HostSpec = {
+  id: 'codex',
+
+  renderDecision(d: Decision): unknown {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: d.verdict === 'allow' ? 'allow' : d.verdict === 'ask' ? 'ask' : 'deny',
+        permissionDecisionReason: d.agentMessage ?? d.reason,
+      },
+    }
+  },
+
+  renderRewrite(toolInput: Readonly<Record<string, unknown>>): unknown {
+    // Identical shape to claude's: Codex's own hooks documentation shows
+    // `permissionDecision: "allow"` + `updatedInput` to "rewrite a supported
+    // tool call without blocking" — "for MCP and other local function tools,
+    // updatedInput is the replacement arguments object", and "Return
+    // updatedInput only with permissionDecision: 'allow'". Verified
+    // 2026-09-28 against https://developers.openai.com/codex/hooks. This is
+    // the incident host's missing piece: mcp__lean_ctx__ctx_shell git pushes
+    // now arrive carrying the session identity.
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: toolInput,
+      },
+    }
+  },
+}

package/packages/agent-hooks/src/hosts/impl/cursor.ts

@@ -0,0 +1,40 @@
+/**
+ * Cursor.
+ *
+ * Ported verbatim (decision-rendering behaviour) from enact-repo-controls's
+ * `src/hosts/impl/cursor.ts`.
+ *
+ * Integration-pass HARDCUT (migration task item 3): this file used to also
+ * export deployment concerns (`targets`, `renderContext`, `commandFor`,
+ * `briefing`, `liveProbe`, `cursorHookEntry`) — see `../spec.ts`'s header for
+ * why those were removed. Only `renderDecision`, called from
+ * `../../pre-tool-use/handler.ts`, ever runs outside a test.
+ */
+
+import type { Decision, HostSpec } from '../spec.ts'
+
+export const cursorSpec: HostSpec = {
+  id: 'cursor',
+
+  renderDecision(d: Decision): unknown {
+    return {
+      decision: d.verdict === 'allow' ? 'approve' : d.verdict === 'ask' ? 'ask' : 'block',
+      reason: d.agentMessage ?? d.reason,
+    }
+  },
+
+  renderRewrite(toolInput: Readonly<Record<string, unknown>>): unknown {
+    // Cursor's `preToolUse` documents `updated_input` as "Modified tool input
+    // to use instead" — the doc's own example replaces a Shell call's
+    // `command`. Verified 2026-09-28 against
+    // https://cursor.com/docs/agent/hooks. This shape is only meaningful for
+    // `preToolUse` payloads (the ones carrying `tool_input`); the
+    // `beforeShellExecution` hook has no rewrite field — the handler treats
+    // that event as the host's own shell execution and allows an unchanged
+    // network git command (the session env already carries the identity).
+    return {
+      permission: 'allow',
+      updated_input: toolInput,
+    }
+  },
+}

package/packages/agent-hooks/src/hosts/impl/kimi.ts

@@ -0,0 +1,47 @@
+/**
+ * Kimi Code.
+ *
+ * Ported verbatim (decision-rendering behaviour) from enact-repo-controls's
+ * `src/hosts/impl/kimi.ts`. Task 0 there confirmed the premise: Kimi has no
+ * repo-local configuration discovery at all — `kimi doctor config` (no path
+ * argument), run from inside a scratch git repository that itself contained
+ * a `.kimi-code/config.toml`, reported checking the *global*
+ * `~/.kimi-code/config.toml` path and never mentioned the repo-local file.
+ *
+ * `renderDecision`'s wire shape fixes a real security bug found there: Kimi's
+ * own PreToolUse contract blocks ONLY on exit code 2 or
+ * `hookSpecificOutput.permissionDecision === 'deny'` — it does not read a bare
+ * `{decision, reason}` object at all. So this renders the same
+ * `hookSpecificOutput` envelope Claude and Codex use; the caller
+ * (`../../pre-tool-use/handler.ts`) pairs this with exiting 2 (and writing the
+ * reason to stderr) whenever the host is kimi and the decision is blocked, so
+ * the denial is recognized through either signal Kimi checks. Kimi has no
+ * `ask` concept at all (only allow/deny), so `ask` collapses to `deny` here
+ * rather than passing an unrecognized value through.
+ *
+ * Integration-pass HARDCUT (migration task item 3): this file used to also
+ * export deployment concerns (`targets`, `renderContext`, `commandFor`,
+ * `briefing`, `kimiHookTable`, `KIMI_HOOKS_MARKERS`) — see `../spec.ts`'s
+ * header for why those were removed. Only `renderDecision`, called from
+ * `../../pre-tool-use/handler.ts`, ever runs outside a test.
+ */
+
+import type { Decision, HostSpec } from '../spec.ts'
+
+export const kimiSpec: HostSpec = {
+  id: 'kimi',
+
+  renderDecision(d: Decision): unknown {
+    // Kimi recognizes only `hookSpecificOutput.permissionDecision` (or exit
+    // code 2) as a deny — see the header comment above. `ask` is not a
+    // concept Kimi has, so it collapses to `deny` rather than passing through
+    // a value nothing on the Kimi side interprets.
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: d.verdict === 'allow' ? 'allow' : 'deny',
+        permissionDecisionReason: d.agentMessage ?? d.reason,
+      },
+    }
+  },
+}

package/packages/agent-hooks/src/hosts/impl/opencode.ts

@@ -0,0 +1,54 @@
+/**
+ * OpenCode.
+ *
+ * Ported verbatim (decision-rendering behaviour) from enact-repo-controls's
+ * `src/hosts/impl/opencode.ts`.
+ *
+ * `renderDecision`'s wire shape fixes the same security bug fixed for Kimi
+ * (see `./kimi.ts`): the OpenCode plugin adl-extensions generates
+ * (`src/create/opencode.ts`'s `denyReason()`) blocks a tool call ONLY on exit
+ * code 2 or `hookSpecificOutput.permissionDecision === 'deny'` — it never
+ * reads a bare `{decision, reason}` object, so rendering that shape with exit
+ * 0 let every denial through as an allow. This renders the `hookSpecificOutput`
+ * envelope Claude, Codex and Kimi use; `../../pre-tool-use/handler.ts` pairs
+ * it with exiting 2 (reason on stderr) for a blocked opencode decision. The
+ * plugin has no `ask` concept, so `ask` collapses to `deny` (fail closed).
+ *
+ * Integration-pass HARDCUT (migration task item 3): this file used to also
+ * export deployment concerns (`targets`, `renderContext`, `commandFor`,
+ * `briefing`, `liveProbe`, `opencodeMcpServer`, `OPENCODE_PLUGIN_SHIM`) — see
+ * `../spec.ts`'s header for why those were removed. Only `renderDecision`,
+ * called from `../../pre-tool-use/handler.ts`, ever runs outside a test.
+ */
+
+import type { Decision, HostSpec } from '../spec.ts'
+
+export const opencodeSpec: HostSpec = {
+  id: 'opencode',
+
+  renderDecision(d: Decision): unknown {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: d.verdict === 'allow' ? 'allow' : 'deny',
+        permissionDecisionReason: d.agentMessage ?? d.reason,
+      },
+    }
+  },
+
+  renderRewrite(toolInput: Readonly<Record<string, unknown>>): unknown {
+    // Same envelope as Claude and Codex. OpenCode's plugin runtime does not
+    // read `updatedInput` itself; the generated plugin
+    // (packages/agent-skills `emitToolMethod`) copies this object onto
+    // `output.args`. OpenCode documents that mutation
+    // (https://opencode.ai/docs/plugins/, verified 2026-09-28: a
+    // `tool.execute.before` example assigns `output.args.command`).
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: toolInput,
+      },
+    }
+  },
+}

package/packages/agent-hooks/src/hosts/registry.ts

@@ -0,0 +1,29 @@
+/**
+ * The assembled host registry.
+ *
+ * Ported (narrowed to adl hook's five hosts — no `vscode`, see
+ * `./spec.ts`'s header) from enact-repo-controls's `src/hosts/registry.ts`.
+ * `HOST_SPECS` is the one place every spec is gathered; `../pre-tool-use/handler.ts`
+ * reads it by `HostId` via `specFor` rather than importing `impl/*.ts` files
+ * directly.
+ */
+
+import type { HostId, HostSpec } from './spec.ts'
+import { claudeSpec } from './impl/claude.ts'
+import { codexSpec } from './impl/codex.ts'
+import { cursorSpec } from './impl/cursor.ts'
+import { opencodeSpec } from './impl/opencode.ts'
+import { kimiSpec } from './impl/kimi.ts'
+
+export const HOST_SPECS: Readonly<Record<HostId, HostSpec>> = {
+  claude: claudeSpec,
+  codex: codexSpec,
+  cursor: cursorSpec,
+  opencode: opencodeSpec,
+  kimi: kimiSpec,
+}
+
+/** Exhaustive by construction: a `HostId` missing from `HOST_SPECS` is a compile error, not a runtime gap. */
+export function specFor(id: HostId): HostSpec {
+  return HOST_SPECS[id]
+}

package/packages/agent-hooks/src/hosts/spec.ts

@@ -0,0 +1,113 @@
+/**
+ * The host contract.
+ *
+ * Ported from enact-repo-controls's `src/hosts/spec.ts` + the
+ * `resolveHost`/`readHostFlag`/host-id pieces of its `src/rules/engine.ts`.
+ * A `HostSpec` describes one coding-agent CLI as data: how it renders a
+ * pre-tool-use decision into that host's native shape.
+ *
+ * HARDCUT from the reference: adl hook has five hosts, not six — `vscode`
+ * is dropped from `HOST_IDS` entirely (it is `audit-only` there: no hook
+ * mechanism at all, and its `renderDecision` returns `null` for every
+ * verdict). It stays recognized by `resolveHost` below only so a `--host=vscode`
+ * invocation gets a clear, specific refusal instead of the generic
+ * "unrecognized host" one — see `resolveHost`'s doc.
+ *
+ * Integration-pass HARDCUT (migration task item 3): the reference's
+ * `HostSpec` also carried deployment concerns — `mode`, `targets`,
+ * `renderContext`, `commandFor`, `briefing`, `liveProbe` — plus the
+ * `CommandStyle`/`RepoRelative`/`repoPath`/`TargetSpec`/`Markers`/
+ * `BriefingWiring`/`LiveProbe`/`PromptEvent` types those needed, and each
+ * `impl/*.ts` file exported deploy-time shape helpers
+ * (`claudeHookGroup`, `codexHookGroup`/`codexMcpTable`, `cursorHookEntry`,
+ * `kimiHookTable`, `opencodeMcpServer`) and marker constants
+ * (`CODEX_MCP_MARKERS`, `KIMI_HOOKS_MARKERS`, `OPENCODE_PLUGIN_SHIM`). None
+ * of that is reachable from `adl hook`'s own runtime — only
+ * `renderDecision`, called from `../pre-tool-use/handler.ts`, ever executes
+ * outside a test — because installing/deploying hook wiring into a host's
+ * config now belongs to `adl-extensions`, not this package. All of it was
+ * removed; `HostSpec` here carries only what the pre-tool-use guard actually
+ * calls.
+ */
+
+/** The five hosts adl hook's pre-tool-use guard renders decisions for. */
+export const HOST_IDS = ['claude', 'codex', 'cursor', 'kimi', 'opencode'] as const
+export type HostId = (typeof HOST_IDS)[number]
+
+export function isHostId(value: string): value is HostId {
+  return (HOST_IDS as readonly string[]).includes(value)
+}
+
+/**
+ * A rule's verdict on one shell command, as it will be rendered into a host's
+ * native hook-decision shape (an exit code, a JSON stdout payload, or both).
+ */
+export interface Decision {
+  readonly verdict: 'allow' | 'deny' | 'ask'
+  /** Shown to the human. */
+  readonly reason: string
+  /** Shown to the agent, when the host has a channel for it distinct from `reason`. */
+  readonly agentMessage?: string | undefined
+}
+
+export interface HostSpec {
+  readonly id: HostId
+  renderDecision(d: Decision): unknown
+  /**
+   * Render a REWRITTEN tool input for hosts whose PreToolUse contract can
+   * replace the tool's input before execution (Claude/Codex/OpenCode
+   * `hookSpecificOutput.updatedInput`, Cursor `preToolUse`'s `updated_input`
+   * — each verified against the host's official docs, 2026-09-28). OpenCode's
+   * runtime does not read `updatedInput`; the generated plugin copies that
+   * object onto `output.args`. Absent on Kimi (its official hook docs have no
+   * input replacement): the pre-tool-use handler then DENIES an MCP-class
+   * call it cannot carry the identity into, rather than letting it run
+   * unrewritten. `toolInput` is the complete replacement input object — the
+   * host replaces the whole tool input with it, unchanged fields included.
+   */
+  readonly renderRewrite?: (toolInput: Readonly<Record<string, unknown>>) => unknown
+}
+
+/**
+ * Read a `--host <value>` or `--host=<value>` flag's raw, unvalidated string.
+ *
+ * Both forms exist on real command lines: `--host=<id>` is what every
+ * deployed hook entry spells, but the separated form is also accepted.
+ * Exported (not just `resolveHost`) so a caller can distinguish "no --host
+ * given" from "a --host was given but it named something `resolveHost`
+ * refuses" — `main.ts`'s vscode-specific error message needs the raw value
+ * to be worth printing.
+ */
+export function readHostFlag(argv: readonly string[]): string | null {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === undefined) continue
+    if (arg === '--host') {
+      const value = argv[i + 1]
+      return value !== undefined && !value.startsWith('-') ? value : null
+    }
+    if (arg.startsWith('--host=')) {
+      const value = arg.slice('--host='.length)
+      return value.length > 0 ? value : null
+    }
+  }
+  return null
+}
+
+/**
+ * Resolve which host is invoking a hook, or `null` to fail closed.
+ *
+ * `vscode` is a real host id in the wider enact ecosystem (kept there for
+ * surface auditing) but it is `audit-only`: it has no hook mechanism at all,
+ * so its `renderDecision` would return `null` for every verdict, deny
+ * included. Accepting `--host=vscode` here would let a blocked decision
+ * silently render as nothing rather than failing closed, so it is refused
+ * here as though it were unrecognized — even though, unlike a genuinely
+ * unknown string, the caller can tell the two apart via `readHostFlag` and
+ * report specifically that vscode is unsupported.
+ */
+export function resolveHost(argv: readonly string[]): HostId | null {
+  const raw = readHostFlag(argv)
+  if (raw === null || raw === 'vscode') return null
+  return isHostId(raw) ? raw : null
+}