@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/pre-read.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+# codeArbiter — PreToolUse:Read hook: file-scoped just-in-time context injection.
+#
+# Thin entry point for the file-scoped-context-injection spec (AC-03, AC-10).
+# All testable logic lives in _readinjectlib.py; this file wires the Claude Code
+# hook protocol to the lib's compute_injection / allow_output helpers.
+#
+# Control flow:
+#   1. utf8_stdio(); root = project_root().
+#   2. If not arbiter_active(root): sys.exit(0) — dormant in non-opted-in repos.
+#   3. Parse input: data = read_input(); extract file_path from tool_input(data);
+#      session_id = data.get("session_id", "").
+#   4. rel = repo_rel(file_path, root). If rel is falsy (outside repo): sys.exit(0).
+#   5. ctx = compute_injection(root, session_id, rel) — handles the .codearbiter/
+#      self-read guard (AC-10), per-(session, file) dedup (AC-09), four-tier index
+#      lookup, budget assembly, and marker write internally.
+#   6. If ctx non-empty: print allow_output(ctx) as JSON (AC-03) and exit 0.
+#      If ctx empty (miss, self-read, or dedup): exit 0 with no output — silent allow.
+#
+# Design invariants:
+#   - Always allows the Read — never emits a deny or block decision.
+#   - Emits allow_output(ctx) ONLY when ctx is non-empty (AC-10: miss and self-read
+#     must be silent; "Done looks like" requires no output on a non-governed Read).
+#   - Fail-open (AC-12): any exception degrades to sys.exit(0) with no stdout
+#     output. A hook crash must NEVER block or stall a Read. The outer
+#     except Exception clause is the last-resort safety net; sys.exit(0) calls
+#     inside the try block raise SystemExit (a BaseException, not an Exception)
+#     so they propagate normally and are never swallowed by this clause.
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    arbiter_active, project_root, read_input, repo_rel, set_host, tool_input,
+    utf8_stdio,
+)
+from _readinjectlib import allow_output, compute_injection  # noqa: E402
+
+
+def main():
+    try:
+        utf8_stdio()
+        root = project_root()
+        if not arbiter_active(root):
+            sys.exit(0)
+        data = read_input()
+        file_path = tool_input(data).get("file_path", "")
+        session_id = data.get("session_id", "")
+        rel = repo_rel(file_path, root)
+        if not rel:
+            sys.exit(0)
+        ctx = compute_injection(root, session_id, rel)
+        if ctx:
+            print(json.dumps(allow_output(ctx)))
+        sys.exit(0)
+    except Exception:  # noqa: BLE001 — AC-12: fail-open, never block a Read
+        sys.exit(0)
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/pre-write.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+# codeArbiter v2 — PreToolUse(Write) guard. Activation + audit-log + marker + ADR
+# integrity. Python port of pre-write.sh (#25): no jq, fails loud, blocks via
+# exit 2.
+#
+# Guards (all on the arbiter-enabled repo only):
+#   H-18  .codearbiter/CONTEXT.md is the activation switch every hook gates on
+#         (#159) — a Write may not flip `arbiter: enabled` off or corrupt the
+#         frontmatter, which would make every gate dormant.
+#   H-19  .codearbiter/.markers/* are the gate-pass tokens that turn a hard-gate
+#         BLOCK into an allow (#160) — never writable via the Write tool.
+#   H-05  audit logs (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) are append-only.
+#   H-11  ADRs under decisions/ are authored only via /adr.
+#   H-22  the protected-state registry (B1/#564): a marker-gated entry admits
+#         only under a fresh authoring marker; a helper-only or append-only
+#         entry is hard-blocked with NO marker path at all — one generic
+#         branch resolves the entry's policy via _protectedstatelib and
+#         applies it, so a fourth registered file needs a registry entry,
+#         never a new hook branch.
+#
+# Every protected-path decision resolves symlinks (#162): classify_protected()
+# checks the raw path AND its realpath-resolved repo-relative form, so a symlink
+# alias whose visible path lacks `.codearbiter/` can't launder a write past a
+# guard.
+
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    MARKER_FRESHNESS_MINUTES, arbiter_active, block, classify_protected,
+    frontmatter_enabled_text, get_host, marker_fresh, project_root,
+    read_input, set_host, utf8_stdio,
+)
+from _protectedstatelib import (  # noqa: E402
+    ProtectedPolicy, marker_gated_write_admitted, resolve_registered_path,
+)
+
+
+def _guard_op(root, op):
+    """Run the four protected-path guards against ONE canonical file op
+    (hostapi.Host.iter_file_ops). Under Claude Code this receives exactly the
+    one "write" op its Write payload maps to, so every check, message, and
+    check ORDER below is byte-identical to the pre-seam single-payload body.
+    The "edit"/"delete" kinds arrive only from a host whose write tool batches
+    per-file operations (Codex's apply_patch, ADR-0011 M2) — a patch hunk's
+    resulting content cannot be replayed the way pre-edit.py replays an Edit,
+    so those kinds resolve CLOSED on the content-sensitive guards."""
+    fpath = op.get("file_path", "") or ""
+    kind = op.get("kind", "write")
+
+    # H-21: an "opaque" op is a host's signal that a write-batching payload
+    # carried a recognizable envelope the adapter could NOT decompose into
+    # per-file ops (e.g. an apply_patch variant outside the mirrored grammar).
+    # Whatever it touches is unknowable here, so it can never pass unguarded —
+    # ambiguity resolves CLOSED (ORCHESTRATOR §2). Claude Code never emits
+    # this kind; its Write payload always maps to exactly one "write" op.
+    if kind == "opaque":
+        block("H-21", "This patch envelope could not be decomposed into per-file operations, "
+                      "so its targets cannot be guarded. Failing closed. Re-issue the change "
+                      "as a plain patch in the documented apply_patch grammar (or split it "
+                      "into smaller single-file patches).")
+
+    classes = classify_protected(fpath, root)
+
+    # H-19: the gate-pass markers are the mechanism that turns a hard-gate BLOCK
+    # into an allow (#160). They are recorded only by the sanctioned producers
+    # (security-pass.py / migration-pass.py) and the /adr `touch` — a Write here
+    # is a hand-forged marker. Block outright (any kind: write, edit, delete).
+    if "marker" in classes:
+        block("H-19", "The .codearbiter/.markers/ gate tokens are not writable via the Write "
+                      "tool (#160) — a hand-written marker forges a security/migration/ADR gate "
+                      "pass. Markers are recorded only by the sanctioned gate producers.")
+
+    # H-18: CONTEXT.md is the master switch arbiter_active() reads (#159). A Write
+    # is a full overwrite, so vet the RESULTING content: allow only if it still
+    # carries a well-formed `arbiter: enabled` frontmatter. Disabling arbiter
+    # from inside the repo it governs is exactly the kill-switch this closes (a
+    # human can still opt out by editing the file outside the agent's tools).
+    if "context" in classes:
+        if kind == "write":
+            enabled, malformed = frontmatter_enabled_text(op.get("content", "") or "")
+            if malformed or not enabled:
+                block("H-18", "This Write would remove or alter the `arbiter: enabled` frontmatter in "
+                              ".codearbiter/CONTEXT.md (#159) — the activation switch every enforcement "
+                              "hook reads. Disabling it from inside the repo would make every gate "
+                              "dormant. Keep `arbiter: enabled` in a well-formed frontmatter block.")
+        else:
+            # A patch edit's resulting frontmatter cannot be verified from its
+            # hunks, and a delete removes the activation switch outright —
+            # ambiguity resolves CLOSED (ORCHESTRATOR §2). /ca:override is the
+            # sanctioned escape hatch.
+            block("H-18", "This patch operation edits or deletes .codearbiter/CONTEXT.md (#159) — "
+                          "the activation switch every enforcement hook reads — and its resulting "
+                          "frontmatter cannot be verified from patch hunks. Failing closed; use the "
+                          "sanctioned init path (or "
+                          + get_host().cmd_ref("override") + ").")
+
+    # H-05: the audit logs (and the /sprint decision record) are append-only —
+    # a Write is a full overwrite. (path set: _hooklib.is_audit_log)
+    if "audit" in classes:
+        if kind == "write":
+            block("H-05", "The .codearbiter audit logs (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) "
+                          "are append-only (ORCHESTRATOR §7). Append with Edit or '>>', never Write.")
+        # A patch edit is positional (it can rewrite interior lines) and a
+        # patch delete destroys the trail — neither can be a verifiable pure
+        # append the way pre-edit.py's tail-anchored Edit can.
+        block("H-05", "The .codearbiter audit logs (overrides.log, triage.log, sprint-log.md, decisions/decision-log.md) "
+                      "are append-only (ORCHESTRATOR §7). A patch cannot express a verifiable "
+                      "pure append; append with '>>' instead.")
+
+    # H-11: ADRs may only be authored via /adr (the skill drops the marker first).
+    # Any .md anywhere under decisions/ is covered — a non-numbered draft or a
+    # nested path is still an immutable decision artifact. (set: is_decisions_path)
+    if "decisions" in classes:
+        if kind == "delete":
+            block("H-11", "ADR files under .codearbiter/decisions/ are immutable history "
+                          "(ORCHESTRATOR §6) — deleting one is prohibited, marker or not.")
+        marker = os.path.join(root, ".codearbiter", ".markers", "adr-authoring-active")
+        if not os.path.isfile(marker):
+            block("H-11", "ADR files are authored only via /adr (ORCHESTRATOR §3) — user "
+                          "attribution required. Subagent-authored ADRs are prohibited.")
+        if not marker_fresh(marker, MARKER_FRESHNESS_MINUTES):
+            block("H-11", f"ADR authoring marker is stale (>{MARKER_FRESHNESS_MINUTES} min). Re-run /adr.")
+
+    # H-22: the protected-state registry (B1/#564) — ONE generic branch,
+    # regardless of `kind`. classify_protected already decided "state" is a
+    # hit; resolve_registered_path only resolves WHICH registered path
+    # matched and WHICH policy it carries — never a second, independent
+    # membership check (T-06 design ruling). marker-gated admits only under a
+    # fresh authoring marker; helper-only and append-only are
+    # flank-IDENTICAL here — both hard-block unconditionally, with NO marker
+    # path at all. The policies differ only in what the SANCTIONED HELPER's
+    # own file I/O is allowed to do, which this tool-call flank never sees by
+    # construction (its argv/content never reaches this guard).
+    if "state" in classes:
+        rel, policy = resolve_registered_path(fpath, root)
+        if kind == "delete":
+            # A DELETE is never authoring, so no authoring marker admits it —
+            # for any policy, marker-gated included. The marker means "the
+            # sanctioned lane is writing a row right now"; reading it as
+            # "...and may therefore remove the file entirely" turns a
+            # self-mintable, friction-grade token (ADR-0024) into a delete
+            # capability over protected state, which is strictly more than
+            # the lane it gates can legitimately need.
+            block("H-22", f"'{rel}' is protected project state (#564) — deleting it is "
+                          f"never admitted, including under a fresh authoring marker. "
+                          f"An authoring lane writes rows; it does not remove the file. "
+                          + get_host().cmd_ref("override") + " if this is deliberate.")
+        if policy == ProtectedPolicy.MARKER_GATED:
+            if not marker_gated_write_admitted(rel, root):
+                block("H-22", f"'{rel}' is marker-gated protected project state (#564) — a "
+                              f"Write is admitted only under a fresh authoring marker. Run "
+                              f"the sanctioned authoring lane, or "
+                              + get_host().cmd_ref("override") + ".")
+        else:
+            block("H-22", f"'{rel}' is protected project state (#564) — the Write tool may "
+                          f"never target it; there is no marker path for this policy. Use "
+                          f"the sanctioned helper.")
+
+
+def _run(root):
+    # The host seam (ADR-0011, M2): iter_file_ops maps this host's native
+    # payload to canonical per-file ops. Claude's Write payload maps to exactly
+    # one "write" op (same fields the pre-seam body read straight off
+    # tool_input), so the Claude verdict path is unchanged; Codex's apply_patch
+    # envelope fans out to one op per touched file, each hitting the same
+    # guards.
+    for op in get_host().iter_file_ops(read_input()):
+        _guard_op(root, op)
+    sys.exit(0)
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not arbiter_active(root):
+        sys.exit(0)
+    # reliability-002 (#189): scoped to arbiter-enabled repos only (above), so a
+    # dormant/non-codeArbiter repo can never be bricked by a crash here. An
+    # uncaught exception in the scan below must fail CLOSED (exit 2 = BLOCK),
+    # not exit 1 — a non-2 exit is a NON-blocking error under the Claude Code
+    # hook contract (_hooklib.py:11-15) and would silently ALLOW the Write.
+    # read_input()'s documented fail-OPEN parse behavior is unaffected: it
+    # catches its own errors and returns {} before this wrapper is reached.
+    try:
+        _run(root)
+    except SystemExit:
+        raise
+    except Exception:  # noqa: BLE001 — the fail-closed backstop of last resort
+        traceback.print_exc(file=sys.stderr)
+        block("H-00", "pre-write guard crashed while scanning this Write — failing "
+                      "closed (ORCHESTRATOR §2) rather than silently allowing an "
+                      "unscanned write. See the traceback above; retry, or report it.")
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so main()'s `get_host()` call resolves
+    to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/preview.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+# codeArbiter — thin entry point for /ca:preview (architecture-006/#179).
+#
+# Wraps _previewlib.collect_diff / scan_secrets and prints the JSON-serialized
+# form command prose needs, so the field-access/serialization step (reaching
+# into ChangedFile.kinds and SecretFinding._asdict()) is import-covered
+# (py_compile + unit tests) instead of living as inline `python -c`
+# multi-statement blocks coupled to the lib's namedtuple internals. Mirrors
+# doctor.py / taskwrite.py: entry point stays thin, all logic lives in
+# _previewlib.
+#
+# Invoked by commands/preview.md as (interpreter resolved once by presence,
+# never a `python3 X || python X` fold -- #577):
+#   "$PY" "<plugin>/hooks/preview.py" diff
+#   "$PY" "<plugin>/hooks/preview.py" secrets
+#
+# Read-only, mirrors _previewlib's own read-only contract (git rev-parse/diff/
+# ls-files and read-only file opens only): this wrapper writes nothing.
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _hooklib  # noqa: E402 — set_host DI seam (#257)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+import _previewlib  # noqa: E402
+
+
+def diff_json():
+    """JSON-serializable form of collect_diff(): path -> sorted kind list."""
+    return {p: sorted(cf.kinds) for p, cf in _previewlib.collect_diff().items()}
+
+
+def secrets_json():
+    """JSON-serializable form of scan_secrets(): list of finding dicts, each
+    already carrying the redacted (never plaintext) snippet."""
+    return [f._asdict() for f in _previewlib.scan_secrets()]
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="preview", add_help=True)
+    parser.add_argument("mode", choices=("diff", "secrets"))
+    args = parser.parse_args(argv)
+
+    result = diff_json() if args.mode == "diff" else secrets_json()
+    json.dump(result, sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Delegates to main(argv) and returns its exit code,
+    exactly as the old `sys.exit(main())` guard propagated it.
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, _hooklib.set_host,
+                               pass_argv=True, propagate_result=True)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)

package/plugins/ca-pi/hooks/prune-transcript.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+# codeArbiter — session-transcript pruner entry point.
+#
+# CLI today (Phase 1); a hook mode (UserPromptSubmit/PreCompact) is wired in a
+# later phase. The pruning engine lives in _prunelib.py.
+#
+#   prune-transcript.py <path|session-id> [--execute] [--tier T]
+#                       [--strategies a,b] [--keep-recent N] [--max-bytes N]
+#   prune-transcript.py audit  <path>     # read-only integrity report
+#   prune-transcript.py report <path>     # size / est-token breakdown only
+#
+# Dry-run is the default. --execute is required to write, and refuses a live
+# transcript (mtime within LIVE_SECS) — the live session is only ever touched
+# by the hook path. Stdlib only.
+
+import argparse
+import glob
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+from _prunelib import (  # noqa: E402
+    Config, audit, est_tokens, hook_run, load_lines,
+)
+# Aliased (ADR-0011): `run(host)` is now this script's host-seam entry point,
+# so the pruning engine's `run` cedes the module-level name here.
+from _prunelib import run as _engine_run  # noqa: E402
+
+
+def utf8_stdio():
+    for s in (sys.stdout, sys.stderr):
+        try:
+            s.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def staleness_check(payload):
+    """(CONFIRM-09) WARN, never block, when an active /dev or /sprint flow's
+    marker has sat past the staleness window with no matching audit-log
+    activity — see _hooklib.staleness_warning for the detection rule and
+    security-controls.md § Audit trail for the accepted-strategy rationale.
+
+    Only runs when the repo has opted in (arbiter_active). Best-effort: ANY
+    failure (missing _hooklib import, a broken root, an unreadable marker)
+    degrades to doing nothing — this must never affect prune-transcript.py's
+    hook-mode exit code (always 0) or block the user's prompt."""
+    try:
+        import _hooklib
+        # Resolve through the host seam (ADR-0011), not the raw payload cwd —
+        # a session whose cwd is a repo subdirectory must still resolve the
+        # repo root (CLAUDE_PROJECT_DIR -> payload cwd -> git toplevel ->
+        # process cwd), or this WARN silently never fires (#264).
+        root = _hooklib.get_host().project_root(payload)
+        if not _hooklib.arbiter_active(root):
+            return
+        for msg in _hooklib.staleness_warning(root):
+            _hooklib.warn(msg)
+    except Exception:  # noqa: BLE001 — a missed warn is acceptable; a crash is not
+        pass
+
+
+def resolve(path_or_id):
+    """Accept a direct path or a bare session id (resolved under ~/.claude)."""
+    if os.path.isfile(path_or_id):
+        return path_or_id
+    hits = glob.glob(os.path.expanduser(
+        f"~/.claude/projects/*/{path_or_id}.jsonl"))
+    if len(hits) == 1:
+        return hits[0]
+    if len(hits) > 1:
+        sys.exit(f"ambiguous session id (matches {len(hits)} files); pass a path")
+    sys.exit(f"no such transcript: {path_or_id}")
+
+
+def is_live(path, live_secs):
+    try:
+        return (time.time() - os.path.getmtime(path)) < live_secs
+    except OSError:
+        return False
+
+
+def _fmt_bytes(n):
+    n = float(n)
+    for unit in ("B", "K", "M", "G"):
+        if abs(n) < 1024 or unit == "G":
+            return f"{int(n)}B" if unit == "B" else f"{n:.1f}{unit}"
+        n /= 1024
+
+
+def print_report(res):
+    rows = res["strategies"]
+    if rows:
+        print(f"{'strategy':<24}{'scope':>11}{'lines':>7}{'before':>12}"
+              f"{'after':>12}{'est≈ saved':>12}")
+        for name, r in rows.items():
+            saved = est_tokens(r["bytes_before"] - r["bytes_after"])
+            print(f"{name:<24}{r['metric_scope']:>11}{r['lines']:>7}"
+                  f"{r['bytes_before']:>12}"
+                  f"{r['bytes_after']:>12}{saved:>12}")
+    print(f"\nfile: {_fmt_bytes(res['bytes_before'])} -> "
+          f"{_fmt_bytes(res['bytes_after'])}  "
+          f"({res['file_pct']:.1f}% smaller, "
+          f"{res['file_bytes_freed']} bytes freed)")
+    print(f"context: {res['context_est_tokens_freed']} estimated tokens freed")
+    if res["validation_errors"]:
+        print("VALIDATION FAILED:", file=sys.stderr)
+        for e in res["validation_errors"]:
+            print("  -", e, file=sys.stderr)
+    print(f"verdict: {res['verdict']}")
+
+
+def cmd_audit(path):
+    with open(path, "rb") as f:
+        data = f.read()
+    results = audit(data)
+    width = max(len(lvl) for lvl, _ in results)
+    for lvl, line in results:
+        print(f"{lvl:<{width}}  {line}")
+    return 1 if any(lvl == "FAIL" for lvl, _ in results) else 0
+
+
+def cmd_report(path):
+    with open(path, "rb") as f:
+        data = f.read()
+    lines = load_lines(data)
+    n = sum(1 for ln in lines if ln.obj is not None)
+    print(f"{os.path.basename(path)}: {len(data)} bytes, {len(lines)} lines "
+          f"({n} JSON), est≈{est_tokens(len(data))} tokens")
+    return 0
+
+
+def main(argv=None):
+    utf8_stdio()
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    # Serialized-transcript hook mode: invoked with no argv and one hook JSON
+    # payload on stdin. Semantic hosts use their native compaction event adapter
+    # instead; direct manual execution remains limited to inactive copies.
+    if not argv:
+        raw = ""
+        try:
+            if not sys.stdin.isatty():
+                raw = sys.stdin.read()
+        except Exception:  # noqa: BLE001
+            raw = ""
+        if raw.strip():
+            try:
+                payload = json.loads(raw)
+            except Exception:  # noqa: BLE001
+                payload = {}
+            if isinstance(payload, dict) and payload.get("hook_event_name"):
+                # CONFIRM-09 staleness-warn: runs unconditionally on
+                # UserPromptSubmit (independent of CODEARBITER_PRUNE, which
+                # gates hook_run's own pruning logic below) — a WARN-only
+                # check must not depend on an unrelated opt-in env var.
+                if payload.get("hook_event_name") == "UserPromptSubmit":
+                    staleness_check(payload)
+                # This codec below rewrites Claude-Code-format transcript
+                # JSONL; semantic hosts plan through _prunepolicy without
+                # rewriting an active session. The staleness-warn
+                # above already ran — it reads the .codearbiter audit logs,
+                # not the transcript, so it is host-neutral (ADR-0011).
+                import _hooklib
+                if not _hooklib.get_host().has_prunable_transcript:
+                    return 0
+                return hook_run(payload)
+        print("usage: prune-transcript.py <path|session-id> [--execute] ...",
+              file=sys.stderr)
+        return 2
+
+    if argv and argv[0] in ("audit", "report"):
+        if len(argv) < 2:
+            sys.exit(f"usage: prune-transcript.py {argv[0]} <path>")
+        path = resolve(argv[1])
+        return cmd_audit(path) if argv[0] == "audit" else cmd_report(path)
+
+    ap = argparse.ArgumentParser(prog="prune-transcript.py")
+    ap.add_argument("target", help="transcript path or session id")
+    ap.add_argument("--execute", action="store_true",
+                    help="write changes (default: dry-run)")
+    ap.add_argument("--tier", default=None, choices=["gentle", "standard", "aggressive"])
+    ap.add_argument("--strategies", default=None,
+                    help="explicit comma-separated strategy list (overrides --tier)")
+    ap.add_argument("--keep-recent", type=int, default=None)
+    ap.add_argument("--max-bytes", type=int, default=None)
+    args = ap.parse_args(argv)
+
+    path = resolve(args.target)
+    cfg = Config.from_env()
+    if args.tier:
+        cfg.tier = args.tier
+    if args.strategies:
+        cfg.strategies = [s.strip() for s in args.strategies.split(",") if s.strip()]
+    if args.keep_recent is not None:
+        cfg.keep_recent = args.keep_recent
+    if args.max_bytes is not None:
+        cfg.max_bytes = args.max_bytes
+    cfg.execute = args.execute
+
+    if cfg.execute and is_live(path, cfg.live_secs):
+        sys.exit(f"refusing --execute on a live transcript (modified < {cfg.live_secs}s ago).\n"
+                 "Run against a copy, or let the hook handle the live session.")
+
+    session = os.path.splitext(os.path.basename(path))[0]
+    res = _engine_run(path, cfg, session=session)
+    print_report(res)
+    return 0 if not res["validation_errors"] else 1
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Delegates to main(argv) and returns its exit code,
+    exactly as the old `sys.exit(main())` guard propagated it.
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so main()'s `_hooklib.get_host()` call
+    (hook-mode path) resolves to the SAME instance the caller passed here —
+    no second `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`. Local import mirrors this module's existing lazy `_hooklib`
+    import convention (staleness_check) — the CLI (argv) paths never touch
+    _hooklib, so it stays off that path's import surface."""
+    import _hooklib
+    _hooklib.set_host(host)
+    return main(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)