dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/hook_binary.py

@@ -0,0 +1,194 @@
+"""Locate the native `dos-hook` fast-path binary bundled in the installed package (docs/286).
+
+The per-tool-call hook hot path (`dos hook pretool`/`posttool`) pays ~0.3-0.8 s of
+Python interpreter cold-start on EVERY tool call; a static Go binary serves the same
+decision in ~10 ms (docs/125/270, the 16-43x win). That binary ships two ways:
+
+  * **The Claude Code plugin** carries it in its git tree (`claude-plugin/bin/`,
+    docs/125 GHF4) and a shell launcher dispatches to it.
+  * **A `pip install dos-kernel` per-platform wheel** (docs/286) bundles exactly the
+    one binary for the installing machine's OS/arch into the package, at
+    `dos/_bin/dos-hook[.exe]`. THIS module is the in-package locator for that copy —
+    the wheel analogue of the plugin's POSIX `bin/dos-hook` launcher, consulted by the
+    CLI hook verbs so a pip user's `dos hook pretool` transparently routes through the
+    native binary when one is present.
+
+This is PURE stdlib and adds NO runtime dependency (the binary is package DATA, the
+same one-way arrow as the skill pack). It only RESOLVES a path + checks it is an
+executable file — it launches nothing; the CLI is the call site that execs it.
+
+**The fallback discipline (docs/100) is absolute.** On a pure-Python install (the
+sdist, or any arch with no matching wheel, or a clean dev checkout where the binary is
+gitignored), `native_hook_binary()` returns None and the caller runs the in-process
+Python decider — un-accelerated, never broken. No machine is ever BLOCKED by a missing
+accelerator; the binary is only ever a speed-up.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import sys
+from pathlib import Path
+
+# The native binary's DELEGATE sentinel (docs/125): it exits 3 for a verb/moment it
+# does not own natively, signalling "let Python decide." A clean native decision is
+# exit 0 (it already emitted any dialect to stdout). Anything else is abnormal and we
+# fall through to Python too (fail-safe).
+DELEGATE_EXIT = 3
+
+# The package-data dir the per-platform wheel drops the binary into. Resolved against
+# THIS module's location (the installed package), NOT a workspace root — the binary is
+# part of the package, wherever pip put it.
+_BIN_DIR = Path(__file__).resolve().parent / "_bin"
+
+# The verbs the native binary serves on the per-tool-call hot path. `stop` fires once
+# per TURN (negligible cold-start) and the oracle port it needs is heavier (docs/125
+# §8.2), so it stays Python on the pip path; the binary itself DELEGATEs it anyway.
+NATIVE_HOOK_VERBS = frozenset({"pretool", "posttool"})
+
+# The env opt-out, matching the plugin path's flag. Unset/anything-but-"0" => native
+# allowed; "0" => force the Python verb (the differential-oracle / debug escape hatch).
+_DISABLE_ENV = "DOS_HOOK_NATIVE"
+
+
+def _host_goos_goarch() -> tuple[str, str]:
+    """This interpreter's (GOOS, GOARCH) tokens — the same mapping `build_hook_binary.py`
+    and the POSIX launcher use, so the name we look up matches the name the build emits."""
+    goos = {"windows": "windows", "darwin": "darwin", "linux": "linux"}.get(
+        platform.system().lower(), platform.system().lower()
+    )
+    m = platform.machine().lower()
+    goarch = {
+        "x86_64": "amd64", "amd64": "amd64",
+        "arm64": "arm64", "aarch64": "arm64",
+    }.get(m, m)
+    return goos, goarch
+
+
+def bundled_binary_name() -> str:
+    """The plain in-package binary name for this platform: `dos-hook` or `dos-hook.exe`.
+
+    The per-platform wheel ships ONE binary per wheel, so it is the un-suffixed
+    `dos-hook[.exe]` (NOT the `dos-hook-<os>-<arch>` matrix names the PLUGIN bundle
+    uses — the plugin carries all arches in one dir and disambiguates by name; a wheel
+    carries only its own arch, so no disambiguation is needed)."""
+    goos, _ = _host_goos_goarch()
+    return "dos-hook.exe" if goos == "windows" else "dos-hook"
+
+
+def native_hook_enabled() -> bool:
+    """True unless `DOS_HOOK_NATIVE=0` forces the Python verb (the opt-out)."""
+    return os.environ.get(_DISABLE_ENV, "").strip() != "0"
+
+
+def native_hook_binary() -> Path | None:
+    """The bundled native dos-hook for THIS platform, or None if there isn't one.
+
+    Returns the path iff a matching, executable regular file is present at
+    `dos/_bin/dos-hook[.exe]` in the installed package; None otherwise (a pure-Python /
+    sdist install, an off-matrix arch, a clean dev checkout, or the `DOS_HOOK_NATIVE=0`
+    opt-out). The caller falls back to the in-process Python hook decider when None.
+
+    Never raises: any probe error (an exotic platform, a permissions surprise) degrades
+    to None, so a packaging oddity can only LOSE the accelerator, never break the hook.
+    """
+    if not native_hook_enabled():
+        return None
+    try:
+        candidate = _BIN_DIR / bundled_binary_name()
+        if not candidate.is_file():
+            return None
+        # On POSIX the file must be executable to exec it; on Windows the bit is
+        # meaningless (an .exe is run by extension), so we don't gate on it there.
+        if os.name != "nt" and not os.access(candidate, os.X_OK):
+            return None
+        return candidate
+    except OSError:
+        return None
+
+
+def hook_argv_from_args(args: object) -> list[str]:
+    """Rebuild the `dos hook <verb>` flag list from the parsed argparse namespace.
+
+    The native binary's CLI mirrors the Python verb's, so we re-emit the same flags it
+    understands: `--workspace`, `--dialect`, `--handler` (pretool), `--session-id`
+    (posttool), `--debug`. A flag absent / left at its argparse default is omitted (the
+    binary applies the same default). Unknown/None values are skipped, so a namespace
+    missing a flag (e.g. posttool has no --handler) simply doesn't emit it.
+    """
+    # The default-dialect name is imported, never spelled here: the vendor-blindness
+    # litmus allows the literal in hook_dialect.py ONLY (the one sanctioned default),
+    # and a kernel module must not branch on a vendor literal of its own.
+    from dos.hook_dialect import DEFAULT_DIALECT
+
+    out: list[str] = []
+    workspace = getattr(args, "workspace", None)
+    if workspace:
+        out += ["--workspace", str(workspace)]
+    dialect = getattr(args, "dialect", None)
+    # Only forward a NON-default dialect — the binary's default matches the kernel's,
+    # so omitting it keeps the argv minimal and the native default authoritative.
+    if dialect and dialect != DEFAULT_DIALECT:
+        out += ["--dialect", str(dialect)]
+    handler = getattr(args, "handler", None)
+    if handler and handler != "observe":
+        out += ["--handler", str(handler)]
+    session_id = getattr(args, "session_id", None)
+    if session_id:
+        out += ["--session-id", str(session_id)]
+    if getattr(args, "debug", False):
+        out += ["--debug"]
+    return out
+
+
+def try_native_hook(verb: str, argv: list[str]) -> int | None:
+    """Run the bundled native binary for `verb` if one is present; else return None.
+
+    The "consult and fall back" pre-amble the CLI hook verbs call BEFORE reading stdin:
+
+      * Returns an `int` exit code when the native binary OWNED the decision (it has
+        already emitted any host dialect to this process's stdout and exited 0) — the
+        CLI returns that code directly, the native fast path.
+      * Returns `None` when there is no usable native path — no bundled binary for this
+        platform, the `DOS_HOOK_NATIVE=0` opt-out, a verb the binary does not serve
+        natively (`stop`/`marker`), a DELEGATE (exit 3) sentinel, or ANY launch error.
+        The CLI then runs its in-process Python decider (the docs/100 fallback).
+
+    `verb` is the hook verb (`pretool`/`posttool`); `argv` is the flags AFTER the verb
+    (e.g. `["--workspace", "."]`) — the native binary's CLI mirrors `dos hook <verb>
+    <flags>`. stdin is inherited so the binary reads the SAME event the Python body
+    would; stdout is inherited so its dialect reaches the host unbuffered through us.
+
+    Never raises: a missing binary, a launch failure, or a crash all degrade to None
+    (run Python), so the accelerator can only be SKIPPED, never break the hook.
+    """
+    if verb not in NATIVE_HOOK_VERBS:
+        return None
+    binary = native_hook_binary()
+    if binary is None:
+        return None
+    try:
+        # Inherit stdin (the event) + stdout (the dialect) + stderr (--debug) so the
+        # native binary's I/O is byte-identical to the Python body's, and we add no
+        # buffering between it and the host runtime.
+        proc = subprocess.run(
+            [str(binary), verb, *argv],
+            stdin=sys.stdin,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+    except OSError:
+        # The binary vanished between the is_file() probe and exec, or the OS refused
+        # to launch it — fall through to Python.
+        return None
+    if proc.returncode == DELEGATE_EXIT:
+        return None  # the binary punted this one to Python
+    if proc.returncode != 0:
+        # An abnormal exit (a panic the binary's own recover() did not catch, a signal):
+        # do NOT trust a partial native decision — but stdin is now consumed, so the
+        # Python body can't re-decide. The hook fail-safe is exit 0 / emit-nothing, and
+        # the binary will have emitted nothing on a crash, so 0 is the safe report.
+        return 0
+    return 0  # the native binary owned it cleanly

dos/hook_dialect.py

@@ -0,0 +1,271 @@
+"""hook_dialect — render a DOS PRE/POST/STOP verdict into the bytes a host honors.
+
+> **The verdict is the kernel; the envelope is a driver (docs/217).** DOS computes
+> ONE dialect-neutral hook decision (deny / warn / pass) and renders it into the
+> exact JSON the *host runtime* parses — Claude Code today, Gemini CLI / Codex CLI /
+> Cursor next. This is the third instance of the kernel's pure-protocol +
+> by-name-resolver pattern, after `dos.judges` (the JUDGE rung) and
+> `dos.overlap_policy` (the disjointness scorer) — here on the OUTPUT side.
+
+Why this module exists
+======================
+
+`pretool_sensor.decide()` / `posttool_sensor.warn_payload()` already emit the exact
+**Claude Code** `hookSpecificOutput` envelope (the one real CC honors, verified
+against the CC source). But the other agent runtimes ship their OWN deny-capable
+pre-tool hook with a DIFFERENT envelope:
+
+  * **Gemini CLI** (`BeforeTool`/`AfterTool`):   `{"decision": "deny", "reason": …}`
+  * **Codex CLI** (`PreToolUse`/`PostToolUse`):   CC-identical `hookSpecificOutput`
+  * **Cursor** (`beforeShellExecution`/…):        `{"permission": "deny"|"allow", …}`
+
+Point `dos hook pretool` at any of those today and it emits the CC envelope they do
+NOT parse — a SILENT no-op (the original `dos hook stop`-vs-CC bug). This module
+closes that: a host-selected renderer turns the verdict into the right bytes.
+
+The neutral form is the Claude-Code dict
+========================================
+
+`decide()` already returns the CC dict, and that dict is **lossless** for every
+target host: a deny carries `permissionDecisionReason` (+ optional
+`additionalContext`), a warn carries `additionalContext`, a pass is `None`. So
+rather than re-plumb `decide()`'s four return sites (and churn the 67 green hook
+tests that assert its CC shape), we treat the CC dict as the canonical internal
+form and TRANSCODE it: `parse_cc(cc_dict) -> HookVerdict`, then
+`dialect.render(verdict) -> host_dict`. The `ClaudeCodeDialect` round-trips to the
+SAME bytes `decide()` already produced (so `--dialect claude-code`, the default, is
+byte-for-byte today's behavior — the docs/217 Phase-1 gate).
+
+Discipline (inherited from docs/191 §4, the byte-author floor)
+==============================================================
+
+NO dialect ever emits a tool-input REWRITE key (`updatedInput` / `updated_input`;
+Cursor's `preToolUse` *can* rewrite input — DOS must NOT). A verdict carries only a
+`reason` (operator-facing why) and a `context` (a fact to RE-SURFACE) — never a
+corrective ARGUMENT minted for the agent. Rendering is PURE: a verdict in, a dict
+out, no I/O — the same line `judges`/`overlap_policy` draw around their seams.
+
+A wrong dialect name fails LOUD, not silent
+===========================================
+
+`resolve_dialect("typo")` RAISES. Unlike `judges` (fail-to-abstain) and
+`overlap_policy` (fail-to-floor), whose fallbacks are the SAFE direction, a dialect
+fallback is NOT safe: a host that asked for `cursor` and silently got `claude-code`
+emits a no-op against Cursor — the exact failure this module exists to prevent. So
+an unknown dialect is an operator error surfaced immediately, never papered over.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from typing import Optional, Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# The dialect-neutral verdict — what the PEP decided, with no envelope grammar.
+# ---------------------------------------------------------------------------
+class HookMoment(enum.Enum):
+    """Which lifecycle seam the verdict is for (selects the host's event name)."""
+
+    PRE = "pre"    # before a tool runs — the only moment a deny is honored
+    POST = "post"  # after a tool ran — context-only (cannot block)
+    STOP = "stop"  # the agent wants to stop — refuse a false done
+
+
+class HookAction(enum.Enum):
+    """The dialect-neutral decision. Maps 1:1 onto every host's grammar."""
+
+    DENY = "deny"  # withhold the call / refuse the stop
+    WARN = "warn"  # add context, do NOT block (turn-preserving)
+    PASS = "pass"  # emit nothing
+
+
+@dataclass(frozen=True)
+class HookVerdict:
+    """A host-free description of a PRE/POST/STOP decision. PURE data.
+
+    `reason`   — the operator-facing why (carried on DENY and WARN).
+    `context`  — a fact to RE-SURFACE to the agent (a WARN's whole payload, or the
+                 corrective surfaced alongside a provenance DENY). NEVER a rewritten
+                 tool argument (the docs/191 §4 byte-author floor).
+    """
+
+    moment: HookMoment
+    action: HookAction
+    reason: str = ""
+    context: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Transcode the canonical CC dict (what decide()/warn_payload already return)
+# into the neutral verdict. PURE.
+# ---------------------------------------------------------------------------
+def parse_cc(cc_dict: Optional[dict], *, moment: HookMoment) -> HookVerdict:
+    """Read a Claude-Code hook dict (or None) into a `HookVerdict`. PURE, total.
+
+    `None` (or any unparseable shape) → a PASS verdict (emit nothing) — the
+    fail-to-passthrough direction the sensors already take. A `permissionDecision:
+    deny` → DENY (reason + any `additionalContext` as context). An
+    `additionalContext` with NO `permissionDecision` → WARN (context = that text).
+    """
+    if not isinstance(cc_dict, dict):
+        return HookVerdict(moment=moment, action=HookAction.PASS)
+    hso = cc_dict.get("hookSpecificOutput")
+    if not isinstance(hso, dict):
+        return HookVerdict(moment=moment, action=HookAction.PASS)
+    decision = hso.get("permissionDecision")
+    context = hso.get("additionalContext")
+    context = context if isinstance(context, str) else ""
+    if decision == "deny":
+        reason = hso.get("permissionDecisionReason")
+        reason = reason if isinstance(reason, str) else ""
+        return HookVerdict(moment=moment, action=HookAction.DENY, reason=reason, context=context)
+    if context:
+        # additionalContext present, no deny → a WARN (turn-preserving re-surface).
+        return HookVerdict(moment=moment, action=HookAction.WARN, context=context)
+    return HookVerdict(moment=moment, action=HookAction.PASS)
+
+
+# ---------------------------------------------------------------------------
+# The dialect Protocol + the four built-in renderers. Each is PURE: verdict in,
+# host dict (or None for PASS) out. NO I/O, NO tool-input rewrite key.
+# ---------------------------------------------------------------------------
+@runtime_checkable
+class HookDialect(Protocol):
+    name: str
+
+    def render(self, verdict: HookVerdict) -> Optional[dict]:
+        """The host's envelope for this verdict, or None to emit nothing (PASS)."""
+        ...
+
+
+_CC_EVENT = {HookMoment.PRE: "PreToolUse", HookMoment.POST: "PostToolUse", HookMoment.STOP: "Stop"}
+
+
+class ClaudeCodeDialect:
+    """The DEFAULT — byte-for-byte what `decide()`/`warn_payload` already emit.
+
+    A round-trip floor: `render(parse_cc(d))` reproduces `d` for the deny/warn/pass
+    cases the sensors produce, so `--dialect claude-code` is today's behavior exactly
+    (the docs/217 Phase-1 gate, pinned by the existing 67-test hook suite + a
+    round-trip test here).
+    """
+
+    name = "claude-code"
+
+    def render(self, verdict: HookVerdict) -> Optional[dict]:
+        if verdict.action is HookAction.PASS:
+            return None
+        event = _CC_EVENT[verdict.moment]
+        if verdict.action is HookAction.DENY:
+            hso = {
+                "hookEventName": event,
+                "permissionDecision": "deny",
+                "permissionDecisionReason": verdict.reason,
+            }
+            if verdict.context:
+                hso["additionalContext"] = verdict.context
+            return {"hookSpecificOutput": hso}
+        # WARN — additionalContext only, no permissionDecision (passthrough).
+        return {"hookSpecificOutput": {"hookEventName": event, "additionalContext": verdict.context}}
+
+
+# The non-default, vendor-NAMED renderers (`codex` / `gemini` / `cursor`) used to
+# live here, but a renderer must name its vendor as CODE (a `GeminiDialect` is
+# inherently Gemini-specific), which the vendor-blindness litmus forbids in a kernel
+# module (`tests/test_vendor_agnostic_kernel.py`). So — per docs/217's own thesis
+# ("the envelope is a driver") and the judges/overlap_policy precedent — they moved
+# to `dos.drivers.hook_dialects` and register through the `dos.hook_dialects`
+# entry-point group. `resolve_dialect("gemini")` discovers them by name at the call
+# boundary; the kernel seam imports no vendor renderer. The ONE built-in that stays
+# is `ClaudeCodeDialect`: the unshadowable default (byte-for-byte what the sensors
+# already emit), the analogue of `AbstainJudge` — a deterministic baseline the kernel
+# always has even with zero drivers installed.
+
+# Singleton (stateless).
+_CLAUDE_CODE = ClaudeCodeDialect()
+
+#: The built-in dialects, by name — just the unshadowable default. Every other host
+#: renderer is a `dos.hook_dialects` plugin (the kernel names no other vendor as code).
+BUILTIN_DIALECTS: dict[str, HookDialect] = {
+    _CLAUDE_CODE.name: _CLAUDE_CODE,
+}
+
+#: The default — the host DOS has spoken since the hooks shipped.
+DEFAULT_DIALECT = "claude-code"
+
+
+def resolve_dialect(name: Optional[str]) -> HookDialect:
+    """Resolve a dialect by name. RAISES on an unknown name (fail-LOUD).
+
+    `None`/empty → the default (`claude-code`). A built-in name → that renderer. A
+    `dos.hook_dialects` entry-point name → the discovered plugin. An UNKNOWN name →
+    `ValueError` (NEVER a silent CC fallback — a wrong dialect against a non-CC host
+    is the no-op bug this seam prevents).
+    """
+    if not name:
+        return BUILTIN_DIALECTS[DEFAULT_DIALECT]
+    if name in BUILTIN_DIALECTS:
+        return BUILTIN_DIALECTS[name]
+    plugin = _load_plugin_dialect(name)
+    if plugin is not None:
+        return plugin
+    known = ", ".join(sorted(BUILTIN_DIALECTS))
+    raise ValueError(
+        f"unknown hook dialect {name!r} — known: {known} "
+        f"(or a registered dos.hook_dialects plugin). Refusing to fall back to "
+        f"{DEFAULT_DIALECT!r}: a wrong dialect against a non-Claude-Code host is a "
+        f"silent no-op."
+    )
+
+
+def available_dialects() -> list[str]:
+    """The names a host may pass to `--dialect` — built-ins + discovered plugins."""
+    names = set(BUILTIN_DIALECTS)
+    try:
+        names.update(_plugin_dialect_names())
+    except Exception:
+        pass
+    return sorted(names)
+
+
+# ---------------------------------------------------------------------------
+# Plugin discovery (boundary I/O — at resolve time, never inside render). The
+# `dos.hook_dialects` entry-point group, the same mechanism as dos.judges /
+# dos.overlap_policies. Kept defensive: a broken plugin never breaks resolution of
+# a built-in.
+# ---------------------------------------------------------------------------
+def _iter_entry_points():
+    try:
+        from importlib.metadata import entry_points
+    except Exception:  # pragma: no cover - very old Python
+        return []
+    try:
+        eps = entry_points()
+        # Python 3.10+ selectable API, with a 3.9 dict fallback.
+        if hasattr(eps, "select"):
+            return list(eps.select(group="dos.hook_dialects"))
+        return list(eps.get("dos.hook_dialects", []))  # type: ignore[attr-defined]
+    except Exception:
+        return []
+
+
+def _plugin_dialect_names() -> list[str]:
+    return [ep.name for ep in _iter_entry_points()]
+
+
+def _load_plugin_dialect(name: str) -> Optional[HookDialect]:
+    for ep in _iter_entry_points():
+        if ep.name != name:
+            continue
+        try:
+            obj = ep.load()
+            inst = obj() if isinstance(obj, type) else obj
+        except Exception:
+            return None
+        # Duck-typed: must have a callable render + a name (the Protocol surface).
+        if hasattr(inst, "render") and callable(inst.render):
+            return inst  # type: ignore[return-value]
+        return None
+    return None

dos/hook_exit.py

@@ -0,0 +1,191 @@
+"""HEX — the hook exit-code classifier: *a plain shell script's exit code → an intervention verb.*
+
+docs/226 — idea **C3** from the Claude Code source audit (docs/189). The cheapest
+possible integration surface: a host has a shell script that checks something (a
+linter, a policy probe, a smoke test) and signals its result the only way a plain
+process can — an **exit code**. CC already gives this a meaning
+(`src/utils/hooks.ts`): a command hook's `exit 0` is success (proceed), `exit 2` is
+a *blocking error* (stop the action), and any other non-zero is a non-blocking error
+(a warning that still proceeds). It is the same convention `git` hooks and
+`pre-commit` use — universal, zero-ceremony, no JSON parser required.
+
+DOS has rich hook adapters (`pretool_sensor`, `posttool_sensor`) that read the CC
+JSON dialect, and a closed intervention vocabulary (`intervention.Intervention`:
+OBSERVE‹WARN‹BLOCK‹DEFER). What it lacked was the *bridge* between the two for the
+**unsophisticated** integration: "I just have a shell script that exits 2 — turn
+that into a DOS intervention." This module is that bridge — a pure map from an exit
+code to an `Intervention` verb.
+
+It is the `liveness`/`productivity`/`breaker` shape — a pure verdict over
+already-gathered state — for a different input:
+
+    liveness.classify       (ProgressEvidence, policy)   -> LivenessVerdict
+    productivity.classify    (WorkHistory, policy)         -> ProductivityVerdict
+    breaker.classify         (BreakerCounts, policy)       -> BreakerVerdict
+    hook_exit.classify_exit  (code, policy)                -> ExitVerdict
+                             ^ THIS module
+
+**Mechanism vs policy — the malloc split.** The mechanism is "look up the exit code
+in a map." The policy — *which code means which verb* — is data, defaulted to CC's
+convention (`0 → pass`, `2 → BLOCK`, other-nonzero → WARN) and declarable
+per-workspace in `dos.toml [hook_exit]`. A host that wants `exit 3 = DEFER`, or
+`exit 0 = OBSERVE` (record even on success), changes one line of data; the kernel's
+lookup never changes. The classifier never knows what the script *did* — only the
+code it returned. That is what makes it a universal cog: it is the `malloc` of
+shell-hook integration, mechanism with the script's domain pushed entirely out.
+
+**Why a script's exit code is sound evidence here.** The exit code is authored by
+the *script process*, not by the judged agent — it is the script's verdict on the
+agent's action, exactly the actor-witness split (docs/117): the byte-author (the
+script) is not the judged party (the agent). So `classify_exit` reads an
+agent-external signal, the same discipline `liveness` (git) and `exec_capability`
+(the command shape) follow. The script is a deterministic JUDGE on the trust ladder;
+this module routes its terse verdict into the kernel's vocabulary.
+
+**Advisory, fail-safe.** The verdict RECOMMENDS an intervention; like every verb in
+this family it never acts. And the safe-failure direction is baked into the default
+map: an *unknown* non-zero code degrades to WARN (inform, do not block) — never to a
+silent pass and never to a spurious BLOCK. A script that fails in a way the host did
+not anticipate surfaces as a warning, the docs/143 −9 pp posture (a wrong BLOCK is
+the expensive mistake; a WARN is cheap).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from dos.intervention import Intervention
+
+
+# ---------------------------------------------------------------------------
+# The default convention — CC's `src/utils/hooks.ts` exit-code semantics, lifted
+# verbatim, as data. `0` = proceed (no intervention); `2` = blocking error
+# (BLOCK); any OTHER non-zero = non-blocking error (WARN, the fallback). Declared
+# as a map so a workspace overrides it in `dos.toml [hook_exit]` — the
+# closed-config-as-data pattern (`[lanes]`/`[reasons]`/`[exec_capability]`).
+# ---------------------------------------------------------------------------
+# The codes that map to a SPECIFIC verb. `0` is the special "pass" code (no
+# intervention) — represented as None in the map so it is distinct from OBSERVE
+# (OBSERVE records a verdict; PASS records nothing and proceeds). Every other
+# non-zero code not named here falls to `fallback`.
+_CC_EXIT_MAP: dict[int, Optional[Intervention]] = {
+    0: None,                  # success — proceed, no intervention (the PASS code)
+    2: Intervention.BLOCK,    # blocking error — CC's `exit 2` (the load-bearing one)
+}
+_CC_FALLBACK = Intervention.WARN  # any other non-zero — non-blocking error → inform
+
+
+@dataclass(frozen=True)
+class HookExitPolicy:
+    """The exit-code → intervention map — policy, not mechanism.
+
+    The same "mechanism is kernel, the map is config" split as `liveness`'s windows
+    and `breaker`'s thresholds. Defaults to CC's convention; a workspace declares its
+    own in `dos.toml [hook_exit]`, e.g. `3 = "DEFER"`, `0 = "OBSERVE"`.
+
+      pass_code   — the exit code that means "proceed, no intervention" (default 0).
+                    The script approved; nothing to actuate.
+      mapping     — explicit `{code: Intervention}` for codes that map to a verb.
+                    A code present here with value None is also treated as PASS (a
+                    host can declare multiple success codes).
+      fallback    — the verb for any non-zero code NOT in `mapping` and not the
+                    `pass_code` (default WARN — inform, the fail-safe direction; never
+                    a silent pass, never a spurious BLOCK on an unanticipated code).
+    """
+
+    pass_code: int = 0
+    mapping: dict[int, Intervention] = field(
+        default_factory=lambda: {2: Intervention.BLOCK}
+    )
+    fallback: Intervention = _CC_FALLBACK
+
+    def with_mapping(self, more: dict) -> "HookExitPolicy":
+        """A new policy with `more` `{code: Intervention}` entries merged in (host on-ramp)."""
+        merged = dict(self.mapping)
+        for code, verb in (more or {}).items():
+            merged[int(code)] = verb if isinstance(verb, Intervention) else Intervention(str(verb))
+        return HookExitPolicy(pass_code=self.pass_code, mapping=merged, fallback=self.fallback)
+
+
+DEFAULT_POLICY = HookExitPolicy()
+
+
+@dataclass(frozen=True)
+class ExitVerdict:
+    """The classifier's verdict: the intervention an exit code maps to (None = PASS).
+
+    `intervention` is the `Intervention` the code maps to, or None when the code is
+    the pass code (proceed, nothing to actuate — distinct from OBSERVE, which records
+    a verdict). `code` is the exit code classified (echoed for the JSON consumer).
+    `reason` is the one-line operator-facing summary. `matched` says whether the code
+    was an EXPLICIT map entry (True) or fell to the fallback (False) — legible
+    distrust: the consumer can tell a declared mapping from the catch-all.
+    """
+
+    code: int
+    intervention: Optional[Intervention]
+    reason: str
+    matched: bool
+
+    @property
+    def passed(self) -> bool:
+        """True iff the script approved — proceed, no intervention."""
+        return self.intervention is None
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "intervention": self.intervention.value if self.intervention else None,
+            "reason": self.reason,
+            "matched": self.matched,
+        }
+
+
+def classify_exit(
+    code: int, policy: HookExitPolicy = DEFAULT_POLICY
+) -> ExitVerdict:
+    """Map a hook script's exit code → an intervention verb. PURE — no I/O.
+
+    The ladder:
+      1. PASS — `code == policy.pass_code` (default 0): the script approved. Proceed,
+         no intervention (`intervention=None`). The success case.
+      2. MAPPED — `code` is an explicit `policy.mapping` entry: the declared verb
+         (default `2 → BLOCK`, CC's blocking-error code). `matched=True`.
+      3. FALLBACK — any other non-zero code: `policy.fallback` (default WARN). The
+         fail-safe catch-all — an unanticipated failure informs, never silently
+         passes and never spuriously blocks. `matched=False`.
+
+    `code` is the integer a host captured from `subprocess`/`$?`. The classifier
+    reads only the code — never the script's stdout/stderr or what it did (that is
+    the script's domain, pushed out; the kernel maps the terse signal).
+    """
+    # A code explicitly mapped to None (a host's extra success code) is also PASS.
+    if code == policy.pass_code or (code in policy.mapping and policy.mapping[code] is None):
+        return ExitVerdict(
+            code=code,
+            intervention=None,
+            reason=f"exit {code} — the hook script approved; proceed (no intervention)",
+            matched=code in policy.mapping or code == policy.pass_code,
+        )
+    verb = policy.mapping.get(code)
+    if verb is not None:
+        return ExitVerdict(
+            code=code,
+            intervention=verb,
+            reason=(
+                f"exit {code} → {verb.value} (a declared hook-exit mapping"
+                + (" — CC's blocking-error code)" if code == 2 and verb is Intervention.BLOCK
+                   else ")")
+            ),
+            matched=True,
+        )
+    return ExitVerdict(
+        code=code,
+        intervention=policy.fallback,
+        reason=(
+            f"exit {code} → {policy.fallback.value} (a non-zero code with no declared "
+            f"mapping — the fail-safe fallback: inform, never silently pass or block)"
+        ),
+        matched=False,
+    )