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

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

@@ -0,0 +1,233 @@
+/**
+ * The agent-hook decision logs: `.adl/logs/hooks.log` (every decision —
+ * allow, deny, route) and `.adl/logs/hooks-deny.log` (every deny, with the
+ * rule and the `adl` hint shown to the agent) — docs/architecture/cli-design.md §5a.
+ *
+ * BEHAVIOUR CHANGE (Tarun, 2026-09-27, §5a): this used to write two CSV
+ * files under `.enact/logs/` (`adl-hook-deny.log` / `adl-hook-activity.log`,
+ * ported from enact-m5's `.agents/hooks/pre-tool-use/src/deny.mjs`
+ * `logDenial`). §5a's later decision replaces that with ONE JSON-Lines
+ * format shared by all five `.adl/logs/*.log` files
+ * (`../log/writer.ts`'s `writeLogEntry`), written to `.adl/logs/hooks.log`
+ * and `.adl/logs/hooks-deny.log`. `.enact/logs/` is a **hard cut**: it is no
+ * longer written (the old files, if present, are left in place — see
+ * `../log/writer.ts`'s header and `writeLogEntry`'s rotation/redaction/0700
+ * '0600 behaviour, which this file now delegates to instead of owning its
+ * own CSV formatting).
+ *
+ * Field mapping onto `LogEntryInput` (`../log/writer.ts`) — the shared
+ * schema has no dedicated "message" or "downstream" field (the old CSV
+ * activity log's last columns), so those choices are recorded here rather
+ * than left implicit:
+ *   - `host` is the SECOND column, the host alone (`claude`, `codex`,
+ *     `cursor`, `kimi`, `opencode`) — Tarun, 2026-09-28: "keep host and
+ *     remove the surface; host at the same position as surface".
+ *   - `tool_call` is the THIRD column, the hook kind
+ *     (`pre-tool-use`, `user-prompt-submit`, `crg:session-stop`,
+ *     `lean-ctx:pre-tool-use`, …) — `surfaceFor`'s old remainder, now its
+ *     own field.
+ *   - `run_id` links the row to the `adl run` dispatch (`ADL_RUN_ID` from
+ *     the invoking environment, when set — one run_id per dispatch);
+ *     `session_id` keeps the host's own session id unchanged.
+ *   - `decision` is `ActivityNote.reason` (`PASS`, `DENY <rule>`, `ERROR
+ *     <what>`, `TIMEOUT <what>`, `SKIP <why>`), with `ActivityNote.downstream`
+ *     appended (` → <downstream>`) when the handler set one — folding the old
+ *     CSV's "reason_id" and "downstream" columns into one descriptive field
+ *     rather than dropping the downstream detail on the floor.
+ *   - `result` carries the human-facing hint (`ActivityNote.message`, e.g.
+ *     the agent-facing deny reason) when the handler set one, falling back
+ *     to the hook's own exit code (as a string) when it did not — so
+ *     `result` is never left empty just because a row has nothing to say.
+ *   - `rule` is set only for a blocked pre-tool-use decision
+ *     (`ActivityNote.denyRuleId`), same trigger as the old deny log.
+ *   - `agent` is `ActivityNote.identityAgent` (M8,
+ *     STATUS.md 12p) — the EFFECTIVE identity the
+ *     decision actually used, set by `../pre-tool-use/handler.ts`'s
+ *     `effectiveIdentityFor` — when an identity decision was made; a valid
+ *     inline `ADL_AGENT_ID_AGENT=` override on the command differs from the
+ *     session's own env var, and the override is what actually acted, not
+ *     the session. Falls back to the old best-effort read straight off
+ *     `ADL_AGENT_ID_AGENT` (`../rules/impl/adl-identity.ts`'s env var) for
+ *     any row with no identity decision at all. `human` has no source at
+ *     this layer and is left absent.
+ *   - `identity_source` (W2 build item 5, 2026-09-28) comes straight off
+ *     `ActivityNote.identitySource` (`./contract.ts`), set by
+ *     `../pre-tool-use/handler.ts`'s `decideAndRespond` only when an
+ *     identity decision was actually made for this invocation — absent
+ *     otherwise, never defaulted to `'none'` for an unrelated row. M8 widens
+ *     when this is set to also cover the "override's PASS" row: an
+ *     identity-bearing command whose only identity-bearing pieces already
+ *     carry a valid inline override needs no rewrite (`rewriteGitNetworkCommands`'s
+ *     `unchanged` outcome), but it still made a real identity decision.
+ *
+ * `command` is truncated at 2000 characters (`truncateCommand`, unchanged
+ * from the CSV format — §5a does not say to drop the cap, and an unbounded
+ * command on one JSON-Lines row is still worth capping) before
+ * `writeLogEntry` redacts it.
+ *
+ * Only invocation data is logged — payload fields and handler notes, never
+ * the environment. Strictly best-effort: `writeLogEntry` throwing (a
+ * genuinely unwritable `.adl/logs/`, not the ordinary "directory does not
+ * exist yet" case, which it creates) is swallowed here, by design, and can
+ * never change a hook's stdout/stderr/exit code.
+ */
+
+import { join } from 'node:path'
+import type { LogEntryInput } from '../log/writer.ts'
+import { writeLogEntry } from '../log/writer.ts'
+import type { ActivityNote, HookHandler, HookInvocation, HookResult } from './contract.ts'
+
+export const HOOKS_LOG_REL = '.adl/logs/hooks.log'
+export const HOOKS_DENY_LOG_REL = '.adl/logs/hooks-deny.log'
+export const MAX_LOGGED_COMMAND_LENGTH = 2000
+
+export function truncateCommand(value: string): string {
+  return value.length > MAX_LOGGED_COMMAND_LENGTH ? `${value.slice(0, MAX_LOGGED_COMMAND_LENGTH)}...<truncated>` : value
+}
+
+function kindFor(inv: Pick<HookInvocation, 'kind' | 'subcommand'>): string {
+  return inv.subcommand === undefined ? inv.kind : `${inv.kind}:${inv.subcommand}`
+}
+
+const stringAt = (record: Readonly<Record<string, unknown>>, key: string): string | undefined =>
+  typeof record[key] === 'string' ? (record[key] as string) : undefined
+
+/**
+ * A compact, human-readable summary of what the hook was asked about: the
+ * shell command; a Grep/Glob pattern (and its path); a Read/Edit/Write file
+ * path; a URL or search query; otherwise the tool input as JSON; for a
+ * prompt hook, the prompt.
+ *
+ * Cursor's own payload fields, verified against
+ * https://cursor.com/docs/agent/hooks (this session, 2026-09-14): the
+ * `command`/`cmd`/`script` and `pattern`/`path`/`file_path` keys checked
+ * below (nested under `tool_input`, falling back to the payload's top level)
+ * already match Cursor's documented shapes for both events this file logs —
+ * a `preToolUse` Shell call's `{"tool_name": "Shell", "tool_input":
+ * {"command": "..."}}`, and a `beforeShellExecution` call's top-level
+ * `{"command": "...", "cwd": "...", "sandbox": false}` (no `tool_input` at
+ * all). No Cursor-specific field renaming was needed here.
+ */
+export function toolSummary(payload: Readonly<Record<string, unknown>>): string {
+  const rawInput = payload.tool_input
+  const input = typeof rawInput === 'object' && rawInput !== null && !Array.isArray(rawInput) ? (rawInput as Record<string, unknown>) : {}
+  for (const key of ['command', 'cmd', 'script']) {
+    const value = stringAt(input, key) ?? stringAt(payload, key)
+    if (value !== undefined) return value
+  }
+  const pattern = stringAt(input, 'pattern')
+  if (pattern !== undefined) {
+    const path = stringAt(input, 'path')
+    return path === undefined ? pattern : `${pattern} in ${path}`
+  }
+  for (const key of ['file_path', 'notebook_path', 'path', 'url', 'query']) {
+    const value = stringAt(input, key)
+    if (value !== undefined) return value
+  }
+  if (Object.keys(input).length > 0) return JSON.stringify(input)
+  return stringAt(payload, 'prompt') ?? ''
+}
+
+// Cursor's payload names its session field `conversation_id` and its event
+// field `hook_event_name` (both are common fields on every Cursor hook
+// payload per https://cursor.com/docs/agent/hooks, e.g. `{"conversation_id":
+// "string", ..., "hook_event_name": "string", ...}`) — already covered by
+// the fallback chains below.
+function sessionOf(payload: Readonly<Record<string, unknown>>): string | undefined {
+  return stringAt(payload, 'session_id') ?? stringAt(payload, 'conversation_id') ?? stringAt(payload, 'sessionId')
+}
+
+function eventOf(inv: HookInvocation): string {
+  return stringAt(inv.payload, 'hook_event_name') ?? stringAt(inv.payload, 'hookEventName') ?? inv.event ?? kindFor(inv)
+}
+
+/** Best-effort agent identity (`ADL_AGENT_ID_AGENT`, `../rules/impl/adl-identity.ts`), trimmed; absent/blank is undefined, not `''`. */
+function agentIdentityOf(env: HookInvocation['env']): string | undefined {
+  const value = env.ADL_AGENT_ID_AGENT
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+/** Best-effort `adl run` dispatch link (`ADL_RUN_ID`), trimmed like the agent identity; absent/blank is undefined, not `''`. */
+function runIdOf(env: HookInvocation['env']): string | undefined {
+  const value = env.ADL_RUN_ID
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+function noteFromResult(result: HookResult): ActivityNote {
+  return result.exitCode === 0 ? { reason: 'PASS' } : { reason: `ERROR exit=${result.exitCode}`, message: result.stderr.trim() }
+}
+
+/**
+ * Run `handler` for a managed, hooks-enabled repo invocation and log it. The
+ * handler's result (or thrown error) is returned (re-thrown) unchanged.
+ */
+export async function runLogged(inv: HookInvocation, handler: HookHandler, now: () => Date = () => new Date()): Promise<HookResult> {
+  let note: ActivityNote | undefined
+  const started = performance.now()
+  const write = (outcome: ActivityNote, result: HookResult): void => {
+    const duration = Math.round(performance.now() - started)
+    const sessionId = sessionOf(inv.payload)
+    const runId = runIdOf(inv.env)
+    // M8 (STATUS.md 12p): the EFFECTIVE identity
+    // this decision used — set on `outcome` whenever an identity decision
+    // was actually made (`../pre-tool-use/handler.ts`'s `effectiveIdentityFor`)
+    // — wins over the session's raw `ADL_AGENT_ID_AGENT` env var: they
+    // differ exactly when the command carries a valid inline override
+    // naming a DIFFERENT agent than the session's own, and the override is
+    // the identity that actually acted. Rows with no identity decision at
+    // all (an unrelated command, an unrelated deny) fall back to the old
+    // env-based best-effort read, unchanged.
+    const agent = outcome.identityAgent ?? agentIdentityOf(inv.env)
+    const tool = stringAt(inv.payload, 'tool_name')
+    const decision = outcome.downstream !== undefined && outcome.downstream.length > 0 ? `${outcome.reason} → ${outcome.downstream}` : outcome.reason
+    // `exactOptionalPropertyTypes`: an absent field must be OMITTED from the
+    // object literal, never set to `undefined` explicitly.
+    const entry: LogEntryInput = {
+      host: inv.host,
+      tool_call: kindFor(inv),
+      ...(sessionId !== undefined ? { session_id: sessionId } : {}),
+      ...(runId !== undefined ? { run_id: runId } : {}),
+      ...(agent !== undefined ? { agent } : {}),
+      ...(outcome.identitySource !== undefined ? { identity_source: outcome.identitySource } : {}),
+      event: eventOf(inv),
+      ...(tool !== undefined ? { tool } : {}),
+      decision,
+      ...(outcome.denyRuleId !== undefined ? { rule: outcome.denyRuleId } : {}),
+      command: truncateCommand(toolSummary(inv.payload)),
+      result: outcome.message !== undefined && outcome.message.length > 0 ? outcome.message : String(result.exitCode),
+      duration_ms: duration,
+    }
+    // `inv.root` is already the resolved git root (`../gating/root.ts`'s own
+    // walk) — pass it as `dir` rather than `cwd` so `writeLogEntry` writes
+    // straight there instead of re-deriving the root with its own
+    // `git rev-parse` subprocess (which a non-git test fixture root, or a
+    // detached-HEAD/worktree edge case, could resolve differently).
+    const dir = join(inv.root, '.adl', 'logs')
+    // One `ts` for both files: `writeLogEntry` calls `now()` itself on every
+    // invocation, so passing `now` straight through to two separate calls
+    // could stamp the hooks.log and hooks-deny.log rows for the SAME
+    // decision a millisecond apart. Capture it once here instead.
+    const stamped = now()
+    const sameNow = () => stamped
+    try {
+      writeLogEntry('hooks', entry, { dir, now: sameNow })
+      if (outcome.denyRuleId !== undefined) writeLogEntry('hooks-deny', entry, { dir, now: sameNow })
+    } catch {
+      // Best-effort: a log write must never change a hook's stdout/stderr/exit code.
+    }
+  }
+  let result: HookResult
+  try {
+    result = await handler({ ...inv, record: (recorded) => (note = recorded) })
+  } catch (error) {
+    write({ reason: `ERROR ${error instanceof Error ? error.message : String(error)}` }, { stdout: '', stderr: '', exitCode: 1 })
+    throw error
+  }
+  const outcome = note ?? noteFromResult(result)
+  write(outcome, result)
+  return result
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Per-invocation tuning config, built from `HookInvocation.env`.
+ *
+ * Ported unchanged from enact-repo-controls-m5's
+ * `src/hooks/user-prompt-submit/config.ts`. The reference
+ * (`utils/constants.mjs` in enact-m5) reads these same seven knobs from
+ * `process.env` once, at module load. This hook is handed its environment
+ * explicitly per call instead of reading the ambient process environment, so
+ * they are threaded as one plain object rather than module-level constants —
+ * see the header comment in `constants.ts` for why.
+ */
+import {
+  DEFAULT_COSINE_FLOOR,
+  DEFAULT_MIN_SCORE,
+  DEFAULT_RELATIVE_FLOOR,
+  DEFAULT_RRF_K,
+  DEFAULT_RRF_TEXT_WEIGHT,
+  DEFAULT_RRF_VECTOR_WEIGHT,
+  DEFAULT_TOP_K,
+  VECTOR_MIN_TOKENS,
+} from './constants.ts'
+
+export interface MatchConfig {
+  readonly topK: number
+  readonly minScore: number
+  readonly relativeFloor: number
+  readonly cosineFloor: number
+  readonly rrfK: number
+  readonly rrfTextWeight: number
+  readonly rrfVectorWeight: number
+  readonly vectorEnabled: boolean
+  readonly vectorMinTokens: number
+  /** Retrieval width per list before fusion — matches docs-search's limit*2. */
+  readonly vectorCandidates: number
+}
+
+function numEnv(value: string | undefined, fallback: number): number {
+  if (value === undefined) return fallback
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : fallback
+}
+
+export function buildMatchConfig(env: Readonly<Record<string, string | undefined>>): MatchConfig {
+  const topK = numEnv(env.SKILL_MATCH_TOP_K, DEFAULT_TOP_K)
+  return {
+    topK,
+    minScore: numEnv(env.SKILL_MATCH_MIN_SCORE, DEFAULT_MIN_SCORE),
+    relativeFloor: numEnv(env.SKILL_MATCH_RELATIVE_FLOOR, DEFAULT_RELATIVE_FLOOR),
+    cosineFloor: numEnv(env.SKILL_MATCH_COSINE_FLOOR, DEFAULT_COSINE_FLOOR),
+    rrfK: numEnv(env.SKILL_MATCH_RRF_K, DEFAULT_RRF_K),
+    rrfTextWeight: numEnv(env.SKILL_MATCH_RRF_TEXT_WEIGHT, DEFAULT_RRF_TEXT_WEIGHT),
+    rrfVectorWeight: numEnv(env.SKILL_MATCH_RRF_VECTOR_WEIGHT, DEFAULT_RRF_VECTOR_WEIGHT),
+    // SKILL_MATCH_VECTOR=0 forces the BM25-only path (bisecting).
+    vectorEnabled: env.SKILL_MATCH_VECTOR !== '0',
+    vectorMinTokens: VECTOR_MIN_TOKENS,
+    vectorCandidates: 2 * topK,
+  }
+}

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

@@ -0,0 +1,149 @@
+/**
+ * Fixed tuning constants for the UserPromptSubmit skill matcher.
+ *
+ * Ported from `enact-repo-controls-m5`'s
+ * `src/hooks/user-prompt-submit/constants.ts` (itself ported from
+ * `.agents/hooks/user-prompt-submit/utils/constants.mjs` in enact-m5). The
+ * numeric knobs that the reference reads from `process.env` at module-load
+ * time (TOP_K, MIN_SCORE, RELATIVE_FLOOR, COSINE_FLOOR, RRF_K,
+ * RRF_TEXT_WEIGHT, RRF_VECTOR_WEIGHT, VECTOR_ENABLED) are NOT module-level
+ * constants here — this hook receives its environment explicitly through
+ * `HookInvocation.env` rather than reading `process.env` directly, so those
+ * become a `MatchConfig` built per-invocation in `config.ts`. The DEFAULT_*
+ * threshold values (MIN_SCORE, RELATIVE_FLOOR, COSINE_FLOOR) below are no
+ * longer the reference's hardcoded fallbacks — see each constant's own
+ * comment for why they were re-measured against this repo's own skill-match
+ * eval fixture instead. Every other constant here is still ported unchanged.
+ */
+
+// Empirically tuned (not ported) against `test/fixtures/skill-match-eval.json`
+// — 41 positive prompts across 32 of the real adl-repo skills, 22 negative
+// prompts, and 6 Do-Not-Use-When near-misses — run through a full
+// minScore x relativeFloor x cosineFloor sweep (see the regression test
+// below and `enact-vps-m5/.scratch/sweep2.ts`, not part of this repo) against
+// the pinned skill corpus in `test/fixtures/skill-corpus-pinned.json`.
+// Superseded the reference's hardcoded 50/0.7/0.45: at 50, several correctly
+// top-ranked skills scored below the gate (measured: research 16.5, grill-me
+// 30.7, interaction-design 14.0, tdd 40.0) and were dropped even though
+// nothing else outranked them. 35 is the lowest minScore that still keeps
+// the negative false-positive rate at/below 5% (measured 3.8%) and precision
+// at/above 85% (measured 86.8%, vs. 88.6% at 50 — the small trade for
+// recall 76.7% vs. 72.1%); higher precision configs exist but cap recall
+// noticeably lower (see the regression test's asserted floors).
+export const DEFAULT_MIN_SCORE = 35
+// A result must reach 70% of the top score to survive alongside it. Ties for
+// best recall/precision across 0.5-0.7 in the sweep; kept at the reference's
+// original value since nothing favors moving it.
+export const DEFAULT_RELATIVE_FLOOR = 0.7
+export const DEFAULT_TOP_K = 3
+
+// Hybrid vector half — RRF fusion mirrors enact-docs-search's hybridSearch.
+export const DEFAULT_RRF_K = 60
+export const DEFAULT_RRF_TEXT_WEIGHT = 0.5
+export const DEFAULT_RRF_VECTOR_WEIGHT = 0.5
+// Small positional bonus per list: being ranked #1 somewhere is a signal the
+// flat 1/(k+rank) curve under-rewards.
+export const RANK1_BONUS = 0.05
+export const RANK3_BONUS = 0.02
+
+// A vector hit must clear this cosine to enter the fusion. Empirically
+// tuned (see DEFAULT_MIN_SCORE above), not ported: the same sweep found no
+// cosine floor between 0.25 and 0.65 that let the vector half contribute
+// recall without also pushing the negative false-positive rate past 5% —
+// this installed Model2Vec artifact's mean-pooled cosines for this 38-skill
+// corpus don't separate short off-topic prompts from on-topic ones cleanly
+// enough at those floors. 0.7 is the lowest floor at which the vector half
+// never fires on this eval's negatives, i.e. hybrid mode degrades to the
+// BM25-only ranking rather than adding noise — a deliberate "do no harm"
+// choice over a lower floor that would trade quietness for unproven recall.
+export const DEFAULT_COSINE_FLOOR = 0.7
+// Mean pooling over very few tokens produces an unstable centroid, so short
+// prompts fall back to the BM25 half.
+export const VECTOR_MIN_TOKENS = 3
+
+// Search options, matching enact-docs-search's DocumentStore: prefix and
+// fuzzy gated by term length so filler words don't match every skill.
+export const FUZZY = (term: string): number | false => (term.length > 4 ? 0.2 : false)
+export const PREFIX = (term: string): boolean => term.length > 3
+export const FIELD_BOOST: Readonly<Record<string, number>> = { name: 3, keywords: 2, description: 1 }
+
+// Dropped from both the index and the query. Prompts are full sentences.
+export const STOPWORDS: ReadonlySet<string> = new Set([
+  'a', 'about', 'after', 'all', 'also', 'am', 'an', 'and', 'any', 'are', 'as', 'at',
+  'be', 'been', 'before', 'being', 'but', 'by',
+  'can', 'could',
+  'did', 'do', 'does', 'doing', 'done',
+  'each',
+  'for', 'from',
+  'get',
+  'had', 'has', 'have', 'he', 'her', 'here', 'him', 'his', 'how',
+  'i', 'if', 'in', 'into', 'is', 'it', 'its',
+  'just',
+  'let', 'like',
+  'make', 'may', 'me', 'might', 'more', 'most', 'much', 'must', 'my',
+  'need', 'no', 'not', 'now',
+  'of', 'off', 'on', 'one', 'only', 'or', 'other', 'our', 'out', 'over', 'own',
+  'please',
+  'said', 'same', 'she', 'should', 'so', 'some', 'such',
+  'than', 'that', 'the', 'their', 'them', 'then', 'there', 'these', 'they', 'this', 'those', 'through', 'to', 'today', 'too',
+  'under', 'up', 'us', 'use', 'used', 'user', 'using',
+  'very',
+  'want', 'was', 'we', 'were', 'what', 'when', 'where', 'which', 'while', 'who', 'why', 'will', 'with', 'would',
+  'you', 'your',
+])
+
+/** Prompts shorter than this carry too little signal to rank descriptions usefully. */
+export const MIN_PROMPT_CHARS = 12
+
+/**
+ * Generic multi-root fixture, kept only because `scanSkills` is a generic
+ * multi-root scanner and existing unit coverage
+ * (`test/unit/hooks-user-prompt-submit.test.ts`) exercises it with two
+ * arbitrary roots. Not a production default — `adl hook`'s own default
+ * resolution (a single `hooks.skills_dir`, see `adl-config.toml`) is
+ * `DEFAULT_SKILLS_DIR` below, not this constant — see `handler.ts`.
+ */
+export const SKILL_ROOTS: readonly string[] = ['.agents/skill-catalog', '.claude/skills']
+
+/**
+ * `handler.ts`'s fallback for `adl-config.toml`'s `[hooks]
+ * skills_dir` when that key is unset.
+ *
+ * HARDCUT (integration pass, migration task item 2): enact-repo-controls-m5
+ * (the migration source) declared `paths.skillRoots: ['.agents/skill-catalog']`
+ * as its authoritative default — a per-repo, hand-authored skill catalog.
+ * That is not adl hook's world: the `adl-extensions` installer places a
+ * *shared* copy of the skill corpus at `.agents/skills` in every repo it
+ * installs into (see `packages/agent-skills/extensions/adl-repo/skills`), for
+ * every host — Claude's plugin-bundled skills at
+ * `.claude-plugin/adl-repo/skills` are a distribution detail of how the
+ * plugin ships, not a second independent source, so Claude also resolves
+ * against `.agents/skills` like every other host rather than getting its own
+ * default. One default, `.agents/skills`, for all five hosts. There is no
+ * back-compat path to `.agents/skill-catalog`: a repo relying on the old
+ * default must set `hooks.skills_dir` explicitly (or wait for its
+ * `adl-extensions` install to lay down `.agents/skills`).
+ */
+export const DEFAULT_SKILLS_DIR = '.agents/skills'
+
+export const DISABLE_ENV = 'SKILL_MATCH_DISABLED'
+
+/**
+ * Specific, distinguishing stderr notes for a failed embedding-model load —
+ * gap fix over the reference, whose equivalent hook always emitted one fixed
+ * generic string ("embedding model not installed") regardless of why the
+ * load failed. Never fatal: whichever note fires, the hook still falls back
+ * to BM25-only search (see `index.ts`'s `loadVector`), but the reason is
+ * always specific enough to act on.
+ */
+export function modelDirMissingNote(dir: string): string {
+  return `adl: embedding model directory missing (${dir} does not exist); skill matching falls back to BM25-only`
+}
+
+export function modelArtifactCorruptNote(reason: string): string {
+  return `adl: embedding model directory present but its artifact is invalid (${reason}); skill matching falls back to BM25-only`
+}
+
+export function modelLoadErrorNote(reason: string): string {
+  return `adl: embedding model failed to load (${reason}); skill matching falls back to BM25-only`
+}

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

@@ -0,0 +1,72 @@
+/**
+ * `handleUserPromptSubmit`: the `HookHandler`-shaped entry point `main.ts`
+ * dispatches `user-prompt-submit` invocations to.
+ *
+ * This file's only job is config-driven root resolution: read
+ * `<inv.root>/adl-config.toml` (already known to exist and to have
+ * decoded successfully — `main.ts` gates on both before ever calling a
+ * handler) via `../../gating/config.ts`'s `decodeConfig` to get
+ * `hooks.skillsDir`, fall back to `DEFAULT_SKILLS_DIR`
+ * (`.agents/skills` — see `constants.ts` for why that is the one default
+ * for every host) when it is unset, and hand the
+ * single resulting repo-relative root to `index.ts`'s `runUserPromptSubmit`,
+ * which does the actual BM25 + vector matching.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { HookHandler, HookInvocation } from '../contract.ts'
+import { decodeConfig } from '../../gating/config.ts'
+import { MARKER } from '../../gating/root.ts'
+import { DEFAULT_SKILLS_DIR } from './constants.ts'
+import { skillRootsFor } from './skill-roots.ts'
+import { runUserPromptSubmit } from './index.ts'
+
+/**
+ * Resolve the repo-relative skills directory for this invocation.
+ *
+ * `adl-config.toml` not existing under `inv.root` is expected when
+ * this handler is called directly (e.g. unit tests) rather than through
+ * `main.ts`'s gating, which requires that file to exist before it will ever
+ * dispatch here — so a missing file falls back to the default rather than
+ * erroring. A file that exists but fails to decode is a real config error and
+ * is thrown, surfacing through `handleUserPromptSubmit`'s own try/catch below
+ * as a loud, non-zero-exit failure rather than a silent fallback.
+ */
+/**
+ * Skill roots for this invocation.
+ *
+ * An explicit `[hooks] skills_dir` still wins outright — it is the escape
+ * hatch for a repo that keeps its corpus somewhere of its own choosing, and
+ * overriding it from the roster would make that setting a lie.
+ *
+ * Otherwise the roots come from the host plus the `[extensions]` roster (see
+ * `./skill-roots.ts`), because adl-extensions retired the single shared
+ * `.agents/skills/` pool in favour of one plugin root per host, namespaced by
+ * extension. That legacy pool is still scanned last, so a repo installed
+ * before the change keeps working until it is reinstalled.
+ */
+function resolveSkillRoots(inv: HookInvocation): readonly string[] {
+  const configPath = join(inv.root, MARKER)
+  if (!existsSync(configPath)) return [DEFAULT_SKILLS_DIR]
+
+  const text = readFileSync(configPath, 'utf8')
+  const decoded = decodeConfig(text)
+  if (!decoded.ok) {
+    throw new Error(`invalid ${configPath} at ${decoded.issue.pointer}: ${decoded.issue.message}`)
+  }
+
+  const explicit = decoded.value.hooks.skillsDir
+  if (explicit !== undefined) return [explicit]
+
+  return skillRootsFor(inv.host, decoded.value.extensions)
+}
+
+export const handleUserPromptSubmit: HookHandler = async (inv) => {
+  try {
+    const skillRoots = resolveSkillRoots(inv)
+    return await runUserPromptSubmit(inv, skillRoots)
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack ?? error.message) : String(error)
+    return { stdout: '', stderr: `adl: user-prompt-submit: ${message}\n`, exitCode: 1 }
+  }
+}