zikaron 0.1.0__py3-none-any.whl

zikaron/hook/main.py

@@ -0,0 +1,118 @@
+"""The process entry point a harness's own hook configuration invokes.
+
+A hook receives its event as JSON on **stdin** — `{hook_event_name, cwd, session_id}` always, plus
+`prompt` for the prompt trigger and `agent_type` for the subagent trigger — and the same `command`
+string is registered under every trigger it serves, dispatching here on `hook_event_name` from the
+payload itself rather than on an argv flag.
+
+Both harnesses would accept a per-trigger flag, so this is a choice rather than a constraint. One
+identical command under every trigger keeps the installed entries uniform, and — the reason that
+actually matters — the payload's own `hook_event_name` cannot disagree with the event that fired
+it, while a flag copied into several config entries can be copied wrong exactly once and then
+mis-dispatch every invocation of that trigger, silently.
+
+**Trigger names are normalized before anything branches on them.** `zikaron.harness.spec` owns the
+vocabulary; this module knows only the three events it resolves to. That is what keeps one
+implementation serving both harnesses instead of two ladders of string comparisons drifting apart.
+
+**Output channel is a property of the event, not a constant.** An earlier version of this module
+wrote plain stdout unconditionally, which is correct for the spawn and prompt triggers and reaches
+nobody at all for the subagent trigger — measured, not assumed. The seam answers which channel each
+event uses and this module honours the answer.
+
+**This process always exits 0, unconditionally.** `push.py`'s own module docstring states why: only
+exit-0 stdout reaches the model, so a genuine failure is relayed through that channel rather than
+through a non-zero exit or stderr, either of which would go unseen. `main()`'s own outermost
+`contextlib.suppress(Exception)` is a *different*, narrower boundary again: it exists for whatever
+none of the dispatched modules anticipated — a payload that is not even valid JSON, or a field a
+harness's documented shape does not actually guarantee — and stays silent on stdout too, since at
+that point this process may not even know which hook event it was invoked for, let alone have a
+store-scoped failure to relay.
+"""
+
+import contextlib
+import json
+import os
+import sys
+from pathlib import Path
+
+from zikaron.harness import detect
+from zikaron.harness.spec import HookEvent, OutputChannel, channel_for, event_for
+from zikaron.hook import push, spawn_warm, subagent_policy
+
+
+def main() -> None:
+    """Read one JSON payload from stdin, dispatch on `hook_event_name`, emit whatever the dispatched
+    module returns (if anything) on that event's own channel, and exit 0 unconditionally.
+    """
+    with contextlib.suppress(Exception):
+        _run()
+    sys.exit(0)
+
+
+def _run() -> None:
+    payload = json.loads(sys.stdin.read())
+    if not isinstance(payload, dict):
+        return
+    trigger = payload.get("hook_event_name")
+    event = event_for(trigger)
+    if event is None:
+        # A trigger this hook is not registered for, or one a harness adds later. Not a failure of
+        # anything this module owns: the process was invoked for a name it does not implement.
+        return
+    output = _dispatch(event, payload)
+    if output is not None:
+        _emit(event, output, trigger=str(trigger))
+
+
+def _dispatch(event: HookEvent, payload: dict[str, object]) -> str | None:
+    """Whatever this event's own module wants emitted, or `None` for nothing at all."""
+    # **Not the payload's `cwd` directly** — that is the value this harness reports *live*, and
+    # under Claude Code it follows the agent's own `cd`, so keying a store on it put stores under
+    # log directories and Scala source trees while `zikaron-mcp` stayed on the real one. The seam
+    # decides; both clients ask it the same question. See `HarnessSpec.store_scope_dir`.
+    scope_dir = detect.current_spec().store_scope_dir(Path(str(payload.get("cwd", "."))))
+    if event is HookEvent.SPAWN:
+        return spawn_warm.run(scope_dir=scope_dir, payload_session_id=payload.get("session_id"))
+    if event is HookEvent.PROMPT:
+        prompt = payload.get("prompt")
+        if not isinstance(prompt, str):
+            return None
+        return push.run(
+            scope_dir=scope_dir,
+            payload_session_id=payload.get("session_id"),
+            prompt=prompt,
+            pid=os.getpid(),
+        )
+    return subagent_policy.run(scope_dir=scope_dir, agent_type=payload.get("agent_type"))
+
+
+def _emit(event: HookEvent, output: str, *, trigger: str) -> None:
+    """Write `output` on the channel this event actually reaches a model through.
+
+    `sys.stdout.write`, not `print`, on the plain channel: `print` appends a trailing newline the
+    dispatched modules never included in their returned text, and the empty-store case is specified
+    as "prints nothing at all" — `print("")` would still emit a bare newline, which is not the same
+    observable as nothing. Writing exactly the returned string is what makes a successful surface
+    response reach the model byte-for-byte identical to what the service sent, and what makes the
+    write-policy text land verbatim too.
+
+    The structured channel echoes back the harness's own trigger name rather than reconstructing
+    one. The name has already been validated — it resolved to a known event — and echoing what
+    arrived is what keeps this correct if a harness ever serves one event under more than one
+    spelling.
+    """
+    if channel_for(event) is OutputChannel.STDOUT:
+        sys.stdout.write(output)
+        return
+    envelope = {"hookSpecificOutput": {"hookEventName": trigger, "additionalContext": output}}
+    # `json.dumps` defaults, including `ensure_ascii`: escaping non-ASCII inflates the emitted text
+    # against a budget the harness measures on what it receives, so it is worth knowing by how much
+    # rather than assuming. Measured on the shipped policy: 13 non-ASCII characters, 65 characters
+    # of escaping, 1.2% — immaterial against this channel's budget, so the default stands and the
+    # decoded text is identical either way.
+    sys.stdout.write(json.dumps(envelope))
+
+
+if __name__ == "__main__":
+    main()

zikaron/hook/push.py

@@ -0,0 +1,183 @@
+"""`userPromptSubmit`: suppress, connect once, ask for the push block, print or relay a failure.
+
+`architecture.md` §"Degraded modes" is normative for the whole sequence, and §"Subagent sessions"
+for step 0. Every branch below reaches exactly one of three observable outcomes, and every one
+exits 0: print `surface`'s text; print nothing (a suppressed subagent turn — not a failure); or
+print a short, model-facing instruction asking the agent to relay the failure to the operator.
+Every path, including an exception this module did not anticipate, reaches one of those three
+rather than propagating: `run()` is the one function in this package that must never let an
+exception escape uncaught, because a caller (`main.py`) treats a raised exception here identically
+to any other unanticipated failure, with no carve-out for "unless something unexpected happened."
+
+**On a failure, this always exits 0 and uses stdout, never stderr, to notify anyone at all —
+because that is the one channel confirmed to reach the model on the harness this ships against**
+(`architecture.md` §"Degraded modes" has the full measurement). `hook.log` still gets the exact,
+verbatim, machine-readable record on every failure — the source of truth an operator can grep
+directly — while the returned stdout text is a deliberately paraphrasable nudge pointing at that
+log, never itself the record of what happened.
+"""
+
+import socket
+import time
+from pathlib import Path
+
+from zikaron.core.errors import ZikaronError
+from zikaron.harness import detect
+from zikaron.hook import connect, envelope, failure, rpc, tripwire
+from zikaron.service import paths
+
+#: `architecture.md`: "enforce an internal deadline of ~2 s, far under the `timeout_ms` the harness
+#: enforces on the whole hook command" — 10 s on this harness, and stated explicitly in the shipped
+#: hook entry rather than inherited (`architecture.md` §"The install contract").
+#: Budgets the *whole* sequence below — connect, spawn-if-absent, health poll, the `surface`
+#: request itself — not only the connect phase `connect.HEALTH_POLL_DEADLINE_SECONDS` bounds on
+#: its own. Checked once, right before the one blocking sequence that can exceed it, rather than
+#: interleaved through every step: the alternative (a fresh deadline check between each socket
+#: call) would not materially tighten the bound, since `connect.connect_once` and
+#: `rpc.surface_once` are each already individually bounded by socket timeouts, and a mid-sequence
+#: abort would still need to close whatever socket was open — no cheaper than letting the one
+#: attempt run to its own conclusion and discarding the result if it overran.
+_DEADLINE_SECONDS = 2.0
+
+#: `architecture.md` §"MCP tool surface": `surface`'s own documented default limit.
+_SURFACE_LIMIT = 5
+
+
+def run(*, scope_dir: Path, payload_session_id: object, prompt: str, pid: int) -> str | None:
+    """Run the whole `userPromptSubmit` sequence and return what to print to stdout, or `None` if
+    nothing should be printed — the caller (`main.py`) owns the actual `print`, so this function
+    stays trivially testable without capturing real stdout.
+
+    Every failure this function detects is handled by exactly one `_degrade` call before
+    returning — there is no path that returns silently for a reason `hook.log` does not also
+    record, and no path that returns silently for a reason the return value itself does not also
+    carry as a model-facing relay instruction. That includes an exception this module did not
+    anticipate: the degraded boundary below catches a genuine `Exception`, not a finite list of
+    types, specifically so a defect in a dependency this function calls — or in this function's
+    own future edits — degrades through the documented channel rather than escaping uncaught into
+    `main.py`'s own outermost catch-all, which reports nothing on either channel.
+    """
+    started_at = time.monotonic()
+    spec = detect.current_spec()
+    env_session_id = detect.session_label(spec)
+    if envelope.is_subagent_session(
+        env_session_id=env_session_id, payload_session_id=payload_session_id
+    ):
+        # Print nothing, make no RPC. Under a harness that fires this hook for subagent sessions
+        # that is the whole story and not a failure at all. Under one where payload and
+        # environment session ids are invariantly equal it instead means the harness was
+        # misdetected — the single case `tripwire` records, and the only one that writes a line
+        # here.
+        tripwire.record_if_misdetected(spec=spec, scope_dir=scope_dir)
+        return None
+
+    # `hook_log_path` is resolved *before* the degraded boundary, deliberately: it is the one
+    # value `_degrade` itself needs to report *any* failure, including one raised by resolving
+    # everything else below it — so it cannot itself be inside the boundary it feeds.
+    store_dir = paths.store_dir(scope_dir)
+    hook_log_path = paths.hook_log_path(store_dir)
+
+    sock: socket.socket | None = None
+    try:
+        sock_path = connect.resolve_sock_path(store_dir)
+        store_db_path = paths.store_db_path(store_dir)
+        sock = connect.connect_once(
+            sock_path,
+            store_db_path=store_db_path,
+            store_id=None,
+            server_command=connect.default_server_command(sock_path, store_dir),
+        )
+        remaining = _DEADLINE_SECONDS - (time.monotonic() - started_at)
+        if remaining <= 0:
+            return _degrade(hook_log_path, "deadline_exceeded")
+        sock.settimeout(remaining)
+        client_envelope = envelope.build_envelope(session_id=env_session_id, pid=pid)
+        return rpc.surface_once(sock, prompt=prompt, limit=_SURFACE_LIMIT, envelope=client_envelope)
+    except (connect.HookTransportError, rpc.SurfaceRejectionError, ZikaronError) as error:
+        kind, code = _classify_failure(error)
+        return _degrade(hook_log_path, kind, code=code)
+    except Exception:
+        # Anything else — a send/recv failure, a malformed response, a timeout mid-request, or a
+        # genuinely unanticipated defect in this function's own future edits. Never logs the
+        # underlying exception's own message text: `_degrade`'s `kind` argument here is the fixed
+        # word "transport", which is what keeps `hook.log` holding only the closed vocabulary
+        # `architecture.md`'s error table names rather than arbitrary exception text that could
+        # in principle echo something this process read (a path, a partial response body).
+        return _degrade(hook_log_path, "transport")
+    finally:
+        if sock is not None:
+            sock.close()
+
+
+#: `architecture.md`'s error table names five wire codes a `surface` call can plausibly receive:
+#: contention, the three store-level open failures, and an identity mismatch this module never
+#: reaches through `SurfaceRejectionError` (it is caught earlier, inside `connect.connect_once`,
+#: as a `HookTransportError`). Mapped to the log kind so `hook.log` names the same vocabulary
+#: `architecture.md` §"Errors" already uses, rather than inventing a second one.
+_REJECTION_KINDS: dict[int, str] = {
+    -32020: "store_busy",
+    -32022: "reindexing",
+    -32023: "bad_config",
+    -32024: "schema_incompatible",
+}
+
+
+def _classify_failure(error: Exception) -> tuple[str, int | None]:
+    """Every exception `run()` catches, as the `(kind, code)` pair `_degrade` needs — one small
+    dispatch rather than a `return _degrade(...)` per `except` clause, since the growing set of
+    exception types this function must treat identically (a `SurfaceRejectionError`'s wire code,
+    a `ZikaronError`'s own error code, a `StoreIdentityError`'s fixed `-32030`, or nothing more
+    specific than "transport" for everything else) was pushing `run()` itself past a plain
+    function's reasonable return-statement count — a lint signal worth heeding rather than
+    suppressing, since the *reason* it fired is that `run()` was starting to do this module's
+    classification work inline as well as its own control flow.
+
+    A wire code the design's error table does not name (a programming error in the service, or a
+    future addition neither side has been told about yet) still gets something identifiable
+    rather than an uninformative default — `_REJECTION_KINDS.get(code, f"rejected_{code}")`.
+    """
+    if isinstance(error, connect.StoreIdentityError):
+        # Checked before the plain `HookTransportError` base class it subclasses: an identity
+        # mismatch is `architecture.md`'s own named code `-32030 store_identity`, not the generic
+        # "transport" the base class's other cause (no server ever became reachable) collapses
+        # to. Reachable through the unconditional store-*path* comparison
+        # `connect._verify_identity` always runs — the hook has no persistent connection across
+        # invocations to have learned a real `store_id` from the way a long-running client could,
+        # so its own identity check stays path-only rather than reading the store file for one,
+        # which would violate `architecture.md`'s own "never a reader of the store, under any
+        # failure."
+        return "store_identity", -32030
+    if isinstance(error, rpc.SurfaceRejectionError):
+        return _REJECTION_KINDS.get(error.code, f"rejected_{error.code}"), error.code
+    if isinstance(error, ZikaronError):
+        # `connect.connect_once`'s own docstring: `security.ensure_runtime_dir`'s `ZikaronError`
+        # on a hostile runtime directory "propagates as itself, since this single attempt has no
+        # fallback path to degrade *through* a runtime directory it does not trust" — true about
+        # *retrying*, but every failure kind must still reach `hook.log` and the model-facing
+        # relay identically, **with its own numeric code**, not merely its name —
+        # `architecture.md` names both wherever one exists, and omitting the code here would
+        # leave `hook.log` naming, for example, `bad_config` with no accompanying `-32023`.
+        return str(error.code.wire_name), int(error.code)
+    # `connect.HookTransportError`'s own "no server became reachable" case, and anything else the
+    # socket calls or JSON parsing can raise — a send/recv failure, a malformed response, a
+    # timeout mid-request. `architecture.md` draws no distinction between these and a plain
+    # transport failure.
+    return "transport", None
+
+
+def _degrade(hook_log_path: Path, kind: str, *, code: int | None = None) -> str:
+    """Log the exact failure to `hook.log`, and return the model-facing relay instruction for it.
+
+    The two channels carry different content on purpose: `hook.log`'s line names the machine
+    vocabulary (`kind`, `code`) a future grep or an operator reading it directly can act on, while
+    the returned instruction is prose aimed at a model that will paraphrase it — it names `kind`
+    too, for a curious model to quote back, but its real job is pointing at `hook.log` as the
+    place the exact detail lives, since the instruction itself is not the source of truth.
+    """
+    failure.record_failure(hook_log_path, kind, code=code)
+    detail = f"{kind} ({code})" if code is not None else kind
+    return (
+        "The Zikaron memory hook failed to surface project memories for this turn "
+        f"(reason: {detail}). Please let the operator know the memory hook failed, and that "
+        "the exact error is recorded in .zikaron/hook.log if they want to look at it directly."
+    )

zikaron/hook/rpc.py

@@ -0,0 +1,85 @@
+"""Framing and sending exactly one `surface` request, and reading its one response line.
+
+`architecture.md` §RPC: newline-delimited JSON-RPC 2.0. This module is deliberately not a copy of
+`zikaron.service.rpc`'s own framing helpers — that module is stdlib-only too and reuse would be
+free, but its whole surface (`parse_request`, `encode_result`, `encode_error`) is written from the
+*server's* side of one exchange, parsing an incoming request and encoding an outgoing response;
+this client only ever constructs one outgoing request and parses one incoming response, the
+opposite pair, so there is nothing in that module this side would actually call. Mirrors the
+identical hand-rolled shape `zikaron.service.lifecycle`'s own internal `_send_request` uses for
+`health()`, restated here for `surface` rather than imported for the reason `connect.py`'s module
+docstring gives.
+"""
+
+import json
+import socket
+
+from zikaron.hook.envelope import HookEnvelope
+
+
+class SurfaceRejectionError(Exception):
+    """The service answered with a JSON-RPC `error` object rather than a result.
+
+    Carries the wire fields verbatim so `push.py`'s failure-logging path can name the code
+    `architecture.md`'s error table gives — `store_busy`, `bad_config`, `reindexing`,
+    `schema_incompatible`, or anything else the service returns — without this module needing to
+    know what any of them mean.
+    """
+
+    def __init__(self, code: int, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"{code}: {message}")
+
+
+def surface_once(sock: socket.socket, *, prompt: str, limit: int, envelope: HookEnvelope) -> str:
+    """Send one `memory_surface(prompt, limit)` request and return the text it answered with.
+
+    A single `sendall`/`recv`-until-newline round trip — this client makes exactly one request per
+    process, so there is no held connection for a partial-send ambiguity to matter against: unlike
+    `zikaron.mcp.connection`'s own client, which must distinguish "nothing was sent" from "some of
+    it was" because it might otherwise wrongly retry a request the service already ran, this
+    process is about to exit either way and never retries anything, so `sendall`'s own
+    documented inability to report partial progress carries no risk here that a second attempt
+    could get wrong.
+
+    Raises:
+        OSError: the socket failed during send or receive.
+        ConnectionError: the connection closed before a full line arrived, or the response was
+            not a well-formed JSON-RPC envelope.
+        SurfaceRejection: the service answered with an `error` object.
+    """
+    request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "memory_surface",
+        "params": {
+            "prompt": prompt,
+            "limit": limit,
+            "client": envelope.as_client_object(),
+        },
+    }
+    sock.sendall((json.dumps(request) + "\n").encode("utf-8"))
+    buffer = b""
+    while not buffer.endswith(b"\n"):
+        chunk = sock.recv(4096)
+        if not chunk:
+            raise ConnectionError("connection closed before a full response was read")
+        buffer += chunk
+    parsed = json.loads(buffer.decode("utf-8"))
+    if not isinstance(parsed, dict):
+        raise ConnectionError(f"response was not a JSON object: {parsed!r}")
+    if "result" in parsed:
+        result = parsed["result"]
+        text = result.get("text") if isinstance(result, dict) else None
+        if not isinstance(text, str):
+            raise ConnectionError(f"surface() did not return {{text}}: {result!r}")
+        return text
+    error = parsed.get("error")
+    if not isinstance(error, dict):
+        raise ConnectionError(f"response has neither a result nor an error object: {parsed!r}")
+    code = error.get("code")
+    message = error.get("message")
+    if not isinstance(code, int) or not isinstance(message, str):
+        raise ConnectionError(f"error object is missing code/message: {error!r}")
+    raise SurfaceRejectionError(code, message)

zikaron/hook/spawn_warm.py

@@ -0,0 +1,81 @@
+"""`agentSpawn`: print the write policy, spawn the detached warm helper, never fail.
+
+`architecture.md` §"Warming" is normative: "the hook process prints the write policy — static
+text, no RPC, so it can never fail — and spawns a detached warm helper, then exits." The split
+matters, and the section says why: "the `agentSpawn` hook talks to the service" and "the
+`agentSpawn` path makes no RPC" cannot both describe one process, so this module's own body makes
+no socket call at all — it prints a constant string and asks the OS to start a *different*
+process, `zikaron.hook.warm_helper`, which does the work that can fail.
+
+§"Subagent sessions" applies here identically to `push.py`: "When they **differ**, this is a
+subagent session and the hook **prints nothing and exits 0** — for `userPromptSubmit` *and*
+`agentSpawn`."
+"""
+
+import contextlib
+import subprocess
+import sys
+from pathlib import Path
+
+from zikaron.harness import detect
+from zikaron.hook import connect, envelope, tripwire, write_policy
+from zikaron.service import paths
+
+
+def run(*, scope_dir: Path, payload_session_id: object) -> str | None:
+    """Return the write-policy text to print, or `None` in a subagent session — and, as a side
+    effect on the non-subagent path, best-effort spawn the detached warm helper.
+
+    Never raises: the only real action on the critical path is holding a string constant, and the
+    spawn is deliberately best-effort — a `subprocess.Popen` failure here (a missing interpreter,
+    an unreadable working directory) is caught and produces no output change at all, since
+    `architecture.md` gives the warm helper no observable effect on this hook's own behaviour one
+    way or the other. It exists purely to make the *next* `userPromptSubmit` warmer than it would
+    otherwise be; failing to start it changes nothing about what `agentSpawn` itself prints.
+
+    The one part that is not a bare constant is the operator's optional
+    `.zikaron/write-policy.md` override (`write_policy.read_policy`), and it is read inside the same
+    kind of whole-body guard as the spawn — so the never-fail property survives even a reader that
+    raises for a reason its own six documented conditions did not anticipate: this function still
+    returns the shipped text.
+    """
+    spec = detect.current_spec()
+    env_session_id = detect.session_label(spec)
+    if envelope.is_subagent_session(
+        env_session_id=env_session_id, payload_session_id=payload_session_id
+    ):
+        tripwire.record_if_misdetected(spec=spec, scope_dir=scope_dir)
+        return None
+    _spawn_warm_helper_best_effort(scope_dir)
+    return write_policy.resolved_policy_text(scope_dir, spec=spec)
+
+
+def _spawn_warm_helper_best_effort(scope_dir: Path) -> None:
+    """Best-effort, whole-operation: path derivation and the spawn itself are both allowed to
+    fail with no effect on what `run()` returns. Wrapping only the `Popen` call itself in
+    `contextlib.suppress(OSError)` would leave path derivation (`resolve_sock_path`'s own
+    `Path.resolve()`, which can raise on a symlink loop) unguarded — a failure there would
+    propagate straight past this function, past `run()` (which has no `try` of its own), and into
+    `main.py`'s own outermost catch-all, which for `agentSpawn` would then suppress the
+    **write-policy print itself**, not merely the warm-up this function exists to attempt.
+    Catching a genuine `Exception` around the whole body, not a narrower list, is what keeps that
+    guarantee true regardless of which step inside it fails.
+    """
+    with contextlib.suppress(Exception):
+        store_dir = paths.store_dir(scope_dir)
+        sock_path = connect.resolve_sock_path(store_dir)
+        command = [
+            sys.executable,
+            "-m",
+            "zikaron.hook.warm_helper",
+            str(sock_path),
+            str(store_dir),
+        ]
+        subprocess.Popen(  # noqa: S603 — a fixed argv this process itself constructed, not
+            # built from request or payload data.
+            command,
+            start_new_session=True,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )

zikaron/hook/subagent_policy.py

@@ -0,0 +1,57 @@
+"""`SubagentStart`: deliver the write policy to a subagent, and nothing else.
+
+`design/harness.md` §Subagents is normative. The spawn trigger fires once per session, so a subagent
+would otherwise inherit Zikaron's tools having never seen the write policy at all. This path exists
+to close that gap and does nothing more.
+
+**Policy-only, stated because each omission is deliberate.** It does not spawn the warm helper — the
+session's own spawn trigger already did, and a second spawn per subagent is pure cost against
+nothing. It makes no RPC and opens no socket. It does not consult the session comparison the spawn
+and prompt paths make: a subagent is identified here by the agent identity its own payload carries,
+which is the exact mechanism the older, session-comparing rule existed to approximate, and the
+relationship between a subagent payload's session id and the environment's is not something this
+path needs to assume.
+
+**The exclusion is exact, which is the whole reason this trigger is worth having.** The other
+harness suppresses *every* subagent because its payload carries no agent identity to discriminate
+on. Here the payload names the agent type, so the policy goes to every subagent except the
+consolidator — whose policy is its own system prompt, and which must not be handed the primary
+agent's write instructions on top of it.
+"""
+
+from pathlib import Path
+
+from zikaron.harness import detect
+from zikaron.hook import write_policy
+
+#: The agent type whose own system prompt already carries its instructions, and the one subagent
+#: this path stays silent for.
+#:
+#: A guarded copy rather than an import: the canonical declaration lives with the installer that
+#: writes the agent config, and importing that module would pull the whole installer onto a
+#: critical path that is measured in milliseconds. A test asserts the two agree, which is the same
+#: arrangement the request envelope's own copy uses — the test pays the import cost, the hook does
+#: not.
+CONSOLIDATOR_AGENT_TYPE = "zikaron-consolidator"
+
+
+def run(*, scope_dir: Path, agent_type: object) -> str | None:
+    """Return the write-policy text to deliver to this subagent, or `None` for the consolidator.
+
+    `agent_type` is typed `object` because it arrives as untrusted JSON from the harness's own
+    stdin delivery. Anything that is not exactly the consolidator's type — a missing field, a
+    non-string, an agent type this build has never heard of — receives the policy, which is the
+    safe direction to be wrong in: an agent that holds the memory write verbs and has not been
+    told the write policy is the failure this path exists to prevent, while an agent that receives
+    a policy it did not need has merely read a few thousand characters.
+
+    Never raises, for the same reason every other hook path does not: the caller's contract is to
+    exit 0 having printed something or nothing, and `resolved_policy_text` absorbs any failure
+    beneath it and falls back to the shipped constant.
+    """
+    if agent_type == CONSOLIDATOR_AGENT_TYPE:
+        return None
+    # Resolved through the seam rather than assumed to be the one harness that sends this trigger:
+    # a path that hard-coded a harness here would be the forked code path the single-implementation
+    # rule exists to prevent, however unreachable the other branch looks today.
+    return write_policy.resolved_policy_text(scope_dir, spec=detect.current_spec())

zikaron/hook/tripwire.py

@@ -0,0 +1,54 @@
+"""The one signal that this process misdetected its harness.
+
+A process tree running under an enclosing session of a marked harness inherits that harness's
+marker and its session variable. The root failure is **misdetection** — the wrong channel table and
+the wrong injection budget follow from it, not only a stale session label — and link coverage
+cannot see it: both clients read the environment by construction, so both read the same stale
+value, they agree, and coverage reads as healthy while the inner session's work is attributed to
+the outer, live one.
+
+**Why the scoping is load-bearing rather than tidy.** The naive rule — log whenever the payload's
+session id differs from the environment's — is the *identical* predicate as
+`envelope.is_subagent_session`. Under a harness that fires its ordinary hooks for subagent sessions,
+that divergence is the routine, expected case, so an unscoped tripwire would fire on every subagent
+turn: it would drown the signal and pollute a log whose whole value is a closed vocabulary of
+failure kinds. So the tripwire fires only under a harness where payload and environment are
+invariantly equal, and that property travels as a field on the harness spec rather than as an
+identity test against a particular harness here.
+
+**On that divergence the hook prints nothing and makes no RPC**, which the callers own and this
+module does not. Making no call is what delivers the reasoning, not merely printing nothing: a push
+resolved under a stale label would be injected into — and counted against — a different, live
+session's instrument stream, and the surfacing event is emitted by the service, so a call made but
+not printed would corrupt the instrument anyway. A lost push is recoverable through pull, the arm
+that depends on no hook at all.
+"""
+
+import contextlib
+from pathlib import Path
+
+from zikaron.harness.spec import HarnessSpec
+from zikaron.hook import failure
+from zikaron.service import paths
+
+#: The one log kind this module writes. Named as its own fixed label so `hook.log`'s vocabulary
+#: stays closed — every line in that file is a fixed kind and an optional wire error code, never
+#: prompt or memory content.
+SESSION_ENV_MISMATCH = "session_env_mismatch"
+
+
+def record_if_misdetected(*, spec: HarnessSpec, scope_dir: Path) -> None:
+    """Write one `session_env_mismatch` line, if this harness is one where the divergence the
+    caller just observed means a misdetection rather than a subagent.
+
+    Called on the suppression path of a hook that has already decided to print nothing, so it must
+    never raise: the caller's guarantee is that it exits quietly, and a tripwire that turned a
+    silent suppression into a crash would cost more than the signal it buys. Best-effort as a
+    whole rather than per-step, so a failure while deriving the log path is swallowed exactly like
+    a failure while writing to it.
+    """
+    if spec.fires_hooks_for_subagent_sessions:
+        return
+    with contextlib.suppress(Exception):
+        store_dir = paths.store_dir(scope_dir)
+        failure.record_failure(paths.hook_log_path(store_dir), SESSION_ENV_MISMATCH)