#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Path-Scoped Spec Context Injection Hook (ticket-refresh model)

When the agent touches a file, the specs that govern that file are surfaced
right then — small, relevant, budgeted — instead of everything up front or
nothing at all. Spec .md files under .trellis/spec/ declare which code paths
they govern via YAML frontmatter (`paths:` glob list); the matching engine
lives in .trellis/scripts/common/spec_match.py and the decision engine in
.trellis/scripts/common/spec_inject.py. This file is the IO shell: stdin,
config, identity, state files, locking, GC, one print.

Triggers:

* Claude Code PostToolUse (matcher "Read|Edit|Write|MultiEdit") receives one
  structured file path after the tool runs.
* Codex PreToolUse (matcher "Edit|Write") receives an ``apply_patch`` command.
  Every patch header is matched before the patch runs. When a FULL spec is
  emitted, the patch is denied once so the model can read the injected rules
  and retry; ticket-only reminders do not block.
* OpenCode ``tool.execute.before`` adapts ``write``, ``edit``, and
  ``apply_patch`` into the same PreToolUse payload. FULL delivery uses the same
  deny-once decision before the JS plugin surfaces context as a tool error.

Behavior — per matched spec, per event (recency-decay aware):

    h    = sha256(spec bytes)
    last = newest emission recorded for (identity, spec)   # stateless → None
    if stateless:               emit TICKET  # bounded cost, always
    elif last is None:          emit FULL    # first time this session
    elif last.sha256 != h:      emit FULL    # spec changed → re-teach
    elif reset since last:      emit FULL    # the text is gone, re-teach
    elif within window:         silent       # fixed window; no state append
    else:                       emit TICKET  # refresh attention cheaply

A FULL block inlines the (budgeted) spec body with a sha256 attr; a TICKET is
a short reminder pointing back at the spec. Both append a state record; silent
hits do not (fixed window, not sliding — continuous editing is exactly when
drift is worst).

Identity (misfire asymmetry: a collision that MISSES an injection is
unacceptable; drift that OVER-injects is fine): the session/window key is
delegated to common.active_task.resolve_context_key — the shared resolver
every other hook uses — called payload-first, environment-inclusive second,
so two live sessions can never collapse onto one exported env value. A
`+a-<agent_id>` suffix (appended after each part is sanitized) keeps a
subagent's state separate from its parent's. When the resolver is unavailable
(older installed scripts tree), a minimal payload-only ladder (session keys,
then transcript hash) keeps the hook working. No key from any source, or an
unwritable state dir → stateless: no state IO at all, every hit is a TICKET
(circuit breaker — never a FULL re-emission loop).

State: user-global, out of the repo, one append-only JSONL file per identity
under ${TRELLIS_SPEC_STATE_DIR:-~/.trellis/spec-inject}/<project16>/<identity>.jsonl.
SessionStart(clear|compact) appends an opaque reset marker to the base session
shard; parent and subagent emission histories stay separate but observe that
shared marker. A best-effort fcntl lock is held across read→decide→append;
where fcntl is unavailable (Windows) the worst case is a duplicate injection.
A once-per-hour GC prunes conforming shards older than 48 h.

Budget (config.yaml `spec_injection:`): per-spec cap `max_spec_chars`
(default 9400) with code-point truncation + in-body notice; per-event cap
`max_total_chars` (default 9500 — below Claude Code's documented
additionalContext ceiling, and enforced directly for Codex). Once the total
budget is exhausted, remaining FULL bodies degrade to one <spec-index> block;
tickets are counted last and dropped (with a stderr warning) only if even they
do not fit.

Refresh window (config.yaml `spec_injection:`): `refresh_window_seconds`
(default 2700; `0` = never refresh unchanged content solely because time
passed).

Fail-open on errors: non-matching events, malformed paths, no matches, or any
internal error → exit 0 with no stdout (stderr warnings allowed). The only
deliberate block is a Codex patch that just received a FULL governing spec.
"""
from __future__ import annotations

# IMPORTANT: Suppress all warnings FIRST
import warnings
warnings.filterwarnings("ignore")

import hashlib
import json
import os
import re
import sys
import time
import uuid
from pathlib import Path

# IMPORTANT: Force UTF-8 on Windows for the streams this hook uses.
# stdin carries the payload (non-ASCII file paths), stdout carries the spec
# bodies, stderr carries warnings that quote both; without this the default
# ANSI codepage raises UnicodeDecodeError / UnicodeEncodeError.
if sys.platform.startswith("win"):
    import io as _io
    for _stream_name in ("stdin", "stdout", "stderr"):
        _stream = getattr(sys, _stream_name, None)
        if _stream is None:
            continue
        if hasattr(_stream, "reconfigure"):
            try:
                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
            except Exception:
                pass  # Optional Windows stream setup; keep hook startup non-fatal.
        elif hasattr(_stream, "detach"):
            try:
                setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
            except Exception:
                pass  # Optional Windows stream setup; keep hook startup non-fatal.


# =============================================================================
# Constants
# =============================================================================

DIR_WORKFLOW = ".trellis"
DIR_SPEC = "spec"

# Tools whose events trigger spec matching (Claude Code tool names). Touching a
# file — even a Read — counts; the miss path stays a fast exit. Overridable via
# config `spec_injection.tools` (e.g. to drop "Read").
DEFAULT_EDIT_TOOLS = ("Read", "Edit", "Write", "MultiEdit")

# Budget defaults sized against Claude Code's documented 10,000-CHARACTER
# additionalContext ceiling — stay under with margin. The <spec-context>
# wrapper (~152 chars with typical rel paths) counts against the total, so a
# spec lands whole only up to ~9348 chars; at the per-spec cap the block is
# derived-truncated further to fit the event ceiling. `0` = unlimited.
DEFAULT_MAX_SPEC_CHARS = 9400
DEFAULT_MAX_TOTAL_CHARS = 9500

# Refresh-window default. `0` = never refresh solely because time passed.
DEFAULT_REFRESH_WINDOW_SECONDS = 2700

# State-file base dir (overridable for tests / hermeticity) and GC policy.
STATE_ENV_DIR = "TRELLIS_SPEC_STATE_DIR"
STATE_DEFAULT_DIR = "~/.trellis/spec-inject"
GC_MARKER = ".last-gc"
GC_INTERVAL_SECONDS = 60 * 60          # GC runs at most once per hour
STATE_MAX_AGE_SECONDS = 48 * 60 * 60   # shards older than this are pruned

# GC scope: exactly `<base>/<project16>/<identity>[.<pid>].jsonl`, never a
# recursive walk — a hostile or mistyped TRELLIS_SPEC_STATE_DIR must not turn
# this hook into an unlink loop over someone's files. The optional `.<pid>`
# alternative covers shards written by the pre-lock layout.
GC_PROJECT_DIR_RE = re.compile(r"^[0-9a-f]{16}$")
# `+` is part of the identity charset: subagent shards use the `+a-<agent_id>`
# suffix (contract amendment 2 — without it those shards were never pruned).
GC_SHARD_NAME_RE = re.compile(r"^[A-Za-z0-9_+-]+(\.[0-9]+)?\.jsonl$")
PATCH_PATH_RE = re.compile(
    r"^\*\*\* (?:(?:Add|Update|Delete) File|Move to): (.+)$"
)

def _warn(message: str) -> None:
    print(f"[inject-spec-context] WARN: {message}", file=sys.stderr)


def _patch_paths(command: str) -> list[str]:
    """Return file paths from the shared apply_patch grammar."""
    paths: list[str] = []
    for line in command.splitlines():
        match = PATCH_PATH_RE.fullmatch(line)
        if match:
            path = match.group(1).strip()
            if path and path not in paths:
                paths.append(path)
    return paths


def _agent_id(payload: dict) -> str:
    """The subagent id carried by the event, or "" for a main-session event."""
    raw = payload.get("agent_id")
    return raw.strip() if isinstance(raw, str) else ""


def find_trellis_root(start: Path) -> Path | None:
    """Walk up from start to find the directory containing .trellis/.

    Handles CWD drift: subdirectory launches, monorepo packages, etc.
    Returns None if no .trellis/ found (silent no-op).
    """
    cur = start.resolve()
    while cur != cur.parent:
        if (cur / DIR_WORKFLOW).is_dir():
            return cur
        cur = cur.parent
    return None


def _scripts_dir_on_path(root: Path) -> None:
    scripts_dir = root / DIR_WORKFLOW / "scripts"
    if str(scripts_dir) not in sys.path:
        sys.path.insert(0, str(scripts_dir))


# =============================================================================
# Config (.trellis/config.yaml `spec_injection:` section)
# =============================================================================


def _read_trellis_config(root: Path) -> dict:
    """Load .trellis/config.yaml via the bundled trellis_config helper.

    The helper lives in .trellis/scripts/common; the hook lives outside the
    scripts tree, so we extend sys.path before importing.
    """
    _scripts_dir_on_path(root)
    try:
        from common.trellis_config import read_trellis_config  # type: ignore[import-not-found]
    except Exception:
        return {}
    try:
        return read_trellis_config(root)
    except Exception:
        return {}


def _parse_tools(raw: object) -> tuple[str, ...] | None:
    """Parse `spec_injection.tools` into a tuple of tool names.

    Two grammars, because the bundled YAML reader hands the value over in two
    shapes: a block list (``- Edit`` items) arrives as a list, a flow sequence
    (``tools: [Edit, Write]``) arrives as the raw string. ``[]`` in either
    shape is a deliberate "never trigger" and is respected. Returns None for a
    value that is neither (the caller warns and keeps the defaults).
    """
    if isinstance(raw, list):
        return tuple(t.strip() for t in raw if isinstance(t, str) and t.strip())
    if isinstance(raw, str):
        text = raw.strip()
        if text.startswith("[") and text.endswith("]"):
            items = (part.strip().strip("\"'").strip() for part in text[1:-1].split(","))
            return tuple(item for item in items if item)
    return None


def get_spec_injection_settings(
    root: Path,
) -> tuple[bool, int, int, int, tuple[str, ...]]:
    """Return (enabled, max_spec_chars, max_total_chars,
    refresh_window_seconds, tools).

    Reads the ``spec_injection:`` section of ``.trellis/config.yaml``:

        spec_injection:
          enabled: true
          max_spec_chars: 9400
          max_total_chars: 9500
          refresh_window_seconds: 2700
          tools:
            - Read
            - Edit
            - Write
            - MultiEdit

    Missing keys use their defaults; ``0`` disables the corresponding limit
    (``max_spec_chars: 0`` = inline the whole body, ``max_total_chars: 0`` =
    no per-event ceiling) or refresh (window keys). ``tools`` also accepts a
    flow sequence (``tools: [Edit, Write]``), and ``tools: []`` disables every
    trigger. Invalid values fall back to the default for that key with a
    stderr warning; tool names outside the known set warn once.
    """
    enabled = True
    tools = DEFAULT_EDIT_TOOLS
    numbers = {
        "max_spec_chars": DEFAULT_MAX_SPEC_CHARS,
        "max_total_chars": DEFAULT_MAX_TOTAL_CHARS,
        "refresh_window_seconds": DEFAULT_REFRESH_WINDOW_SECONDS,
    }

    config = _read_trellis_config(root)
    section = config.get("spec_injection") if isinstance(config, dict) else None
    if isinstance(section, dict):
        raw_enabled = section.get("enabled", True)
        if isinstance(raw_enabled, bool):
            enabled = raw_enabled
        else:
            s = str(raw_enabled).strip().lower()
            if s in ("false", "no", "0", "off"):
                enabled = False
            elif s not in ("true", "yes", "1", "on"):
                _warn(
                    f"invalid spec_injection.enabled value: {raw_enabled!r}; "
                    f"using true (default)"
                )

        # int() coercion stays local to this hook by decision (audit round,
        # 2026-07-25): widening the shared common/config.py helpers has more
        # blast radius than this small duplication costs.
        for key, default_value in list(numbers.items()):
            if key not in section:
                continue
            raw = section[key]
            try:
                value = int(raw)
            except (TypeError, ValueError):
                value = -1
            if value < 0:
                _warn(
                    f"invalid spec_injection.{key} value: {raw!r}; "
                    f"using default {default_value}"
                )
                continue
            numbers[key] = value

        if "tools" in section:
            parsed_tools = _parse_tools(section["tools"])
            if parsed_tools is None:
                _warn(
                    f"invalid spec_injection.tools value: {section['tools']!r}; "
                    f"using default {list(DEFAULT_EDIT_TOOLS)}"
                )
            else:
                tools = parsed_tools
                unknown = [t for t in tools if t not in DEFAULT_EDIT_TOOLS]
                if unknown:
                    _warn(
                        f"unknown spec_injection.tools entries {unknown} — "
                        f"they will never match; known tools: "
                        f"{list(DEFAULT_EDIT_TOOLS)}"
                    )

    return (
        enabled,
        numbers["max_spec_chars"],
        numbers["max_total_chars"],
        numbers["refresh_window_seconds"],
        tools,
    )


# =============================================================================
# Identity ladder
# =============================================================================


def _sanitize(raw: str) -> str:
    """Map a session/agent id to a filename-safe, collision-free token.

    A readable head (the first 80 characters, every character outside
    ``[A-Za-z0-9_-]`` replaced one-for-one by ``-``) plus, whenever anything
    was replaced or the id was longer than 80 characters, ``-`` and 8 hex of
    sha256(raw). The suffix is what makes the mapping injective: without it,
    "a/b" and "a:b" — or two ids sharing an 80-character prefix — would fold
    onto one state file, and a collision that MISSES an injection is the
    unacceptable failure. Output stays inside the GC name class.
    """
    raw = raw.strip()
    head = raw[:80]
    safe = re.sub(r"[^A-Za-z0-9_-]", "-", head)
    if safe != head or len(raw) > 80:
        digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:8]
        return f"{safe}-{digest}"
    return safe


def _shared_context_key(root: Path, payload: dict) -> str | None:
    """Session/window key from the shared resolver every other hook uses.

    ``common.active_task.resolve_context_key`` is the single source of truth
    for session identity: payload keys in all casings (``session_id`` /
    ``sessionId`` / ``sessionID``, conversation and transcript variants),
    nested payload shapes, the explicit ``TRELLIS_CONTEXT_ID`` override,
    per-platform env fallbacks, and Cursor shell tickets — plus the platform
    fixes accumulated behind them. Payload identity is preferred over
    environment context so two live sessions can never collapse onto one
    exported env value (collision → missed injection is the unacceptable
    direction); the environment pass still runs when the payload carries
    nothing.
    """
    try:
        _scripts_dir_on_path(root)
        from common.active_task import resolve_context_key  # type: ignore[import-not-found]

        key = resolve_context_key(payload, allow_environment_context=False)
        if key:
            return key
        return resolve_context_key(payload)
    except Exception:
        return None


def resolve_base_identity(root: Path, payload: dict) -> tuple[str, bool]:
    """Return the base session identity for reset and refresh state.

    When the shared resolver is unavailable (older installed scripts tree), a
    minimal payload-only ladder keeps the hook working. ``stateless=True``
    means no state IO is possible.
    """
    identity_payload = payload
    if payload.get("hook_event_name") == "SessionStart":
        # In this event `source` means startup/clear/compact, not platform.
        # The shared resolver also accepts a generic `source` platform hint,
        # so remove the lifecycle field to keep the same session identity as
        # later PostToolUse events.
        identity_payload = dict(payload)
        identity_payload.pop("source", None)
    key = _shared_context_key(root, identity_payload)

    if not key:
        # Minimal payload-only fallback for scripts trees that predate
        # resolve_context_key. Mirrors its payload lookup order.
        for k in ("session_id", "sessionId", "sessionID"):
            value = payload.get(k)
            if isinstance(value, str) and value.strip():
                key = "s-" + value.strip()
                break
        if not key:
            transcript = payload.get("transcript_path")
            if isinstance(transcript, str) and transcript.strip():
                digest = hashlib.sha256(
                    transcript.strip().encode("utf-8")
                ).hexdigest()
                key = "t-" + digest[:16]

    if not key:
        return "", True

    return _sanitize(key), False


# =============================================================================
# State (one append-only JSONL file per identity, locked, user-global)
# =============================================================================


def _state_base_dir() -> Path:
    override = os.environ.get(STATE_ENV_DIR)
    if override and override.strip():
        return Path(override.strip())
    return Path(os.path.expanduser(STATE_DEFAULT_DIR))


def _project_id(root: Path) -> str:
    return hashlib.sha256(os.path.realpath(str(root)).encode("utf-8")).hexdigest()[:16]


def _maybe_gc(base_dir: Path) -> None:
    """Prune conforming shards older than 48 h, at most once per hour.

    Scope is exact-depth (``<base>/<project16>/<shard>.jsonl``) and name-gated;
    foreign files and directories are never touched. Containment is enforced
    against symlinks on both levels — a symlinked project dir or shard is
    skipped outright, and every unlink candidate must still be under the
    resolved base after realpath — so a planted link cannot walk this GC out
    of its own tree. Best-effort, errors ignored.
    """
    try:
        base_real = os.path.realpath(str(base_dir))
        marker = base_dir / GC_MARKER
        now = time.time()
        try:
            age = now - marker.stat().st_mtime
        except OSError:
            age = None
        if age is not None and age < GC_INTERVAL_SECONDS:
            return
        try:
            base_dir.mkdir(parents=True, exist_ok=True)
            marker.touch()
        except OSError:
            return
        try:
            project_dirs = list(base_dir.iterdir())
        except OSError:
            return
        for project_dir in project_dirs:
            if not GC_PROJECT_DIR_RE.match(project_dir.name):
                continue
            try:
                if project_dir.is_symlink() or not project_dir.is_dir():
                    continue
                shards = list(project_dir.iterdir())
            except OSError:
                continue
            for shard in shards:
                if not GC_SHARD_NAME_RE.match(shard.name):
                    continue
                try:
                    if shard.is_symlink() or not shard.is_file():
                        continue
                    shard_real = os.path.realpath(str(shard))
                    if not shard_real.startswith(base_real + os.sep):
                        continue
                    if now - shard.stat().st_mtime > STATE_MAX_AGE_SECONDS:
                        shard.unlink()
                except OSError:
                    continue
    except Exception:
        pass


def open_shard(shard_path: Path) -> int | None:
    """Open (creating) the identity's shard for read+append.

    Doubles as the writability probe: a failure here trips the circuit breaker
    and the event runs stateless (ticket-only), which is bounded, instead of
    re-emitting full specs on every event forever.
    """
    try:
        shard_path.parent.mkdir(parents=True, exist_ok=True)
    except OSError:
        _warn(f"state dir {shard_path.parent} unusable — running stateless")
        return None
    try:
        return os.open(
            str(shard_path),
            os.O_RDWR | os.O_CREAT | os.O_APPEND,
            0o644,
        )
    except OSError:
        _warn(f"state shard {shard_path} unusable — running stateless")
        return None


def lock_shard(fd: int) -> None:
    """Best-effort exclusive lock held across read→decide→append.

    Closes the duplicate-injection race between concurrent hook processes on
    POSIX. No fcntl (Windows) or an unsupported filesystem → no lock; the
    worst case is a duplicate injection, never a lost one.
    """
    try:
        import fcntl

        fcntl.flock(fd, fcntl.LOCK_EX)
    except Exception:
        pass


def unlock_shard(fd: int) -> None:
    try:
        import fcntl

        fcntl.flock(fd, fcntl.LOCK_UN)
    except Exception:
        pass


def load_state(
    fd: int,
    state_version: int,
) -> tuple[dict[str, dict], str | None] | None:
    """Read the shard through the already-open fd; newest record per spec wins
    (``ts`` decides, and on an exact tie the later line in the file does —
    appends are ordered, and two records one float apart must not resolve to
    the older one). The latest reset marker is returned separately. Malformed
    lines and foreign schema versions are skipped silently; read failures
    return None so the caller uses stateless ticket mode."""
    result: dict[str, dict] = {}
    latest_reset: str | None = None
    try:
        os.lseek(fd, 0, os.SEEK_SET)
        chunks: list[bytes] = []
        while True:
            chunk = os.read(fd, 1 << 20)
            if not chunk:
                break
            chunks.append(chunk)
    except OSError:
        return None

    text = b"".join(chunks).decode("utf-8", errors="replace")
    for line in text.splitlines():
        line = line.strip()
        if not line:
            continue
        try:
            record = json.loads(line)
        except (json.JSONDecodeError, ValueError):
            continue
        if not isinstance(record, dict):
            continue
        if record.get("v") != state_version:
            continue
        spec = record.get("spec")
        reset = record.get("reset")
        if not isinstance(spec, str):
            if isinstance(reset, str) and reset:
                latest_reset = reset
            continue
        ts = record.get("ts")
        if not isinstance(ts, (int, float)):
            continue
        previous = result.get(spec)
        if previous is None or ts >= previous.get("ts", float("-inf")):
            result[spec] = record
    return result, latest_reset


def append_records(fd: int, records: list[dict]) -> bool:
    """Append records as JSONL (O_APPEND) and report whether all bytes landed."""
    if not records:
        return True
    try:
        blob = "".join(json.dumps(r, ensure_ascii=False) + "\n" for r in records)
        encoded = blob.encode("utf-8")
        if os.write(fd, encoded) != len(encoded):
            _warn("could not write complete state shard — state may be incomplete")
            return False
        return True
    except OSError:
        _warn("could not write state shard — state may be incomplete")
        return False


# =============================================================================
# Entry
# =============================================================================


def main() -> int:
    if os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1":
        return 0

    try:
        input_data = json.load(sys.stdin)
    except (json.JSONDecodeError, ValueError, UnicodeDecodeError):
        return 0
    if not isinstance(input_data, dict):
        return 0

    cwd = input_data.get("cwd") or os.getcwd()
    root = find_trellis_root(Path(cwd))
    if root is None:
        return 0
    # Bail out before any spec scan when the project has no spec directory.
    if not (root / DIR_WORKFLOW / DIR_SPEC).is_dir():
        return 0

    (
        enabled,
        max_spec_chars,
        max_total_chars,
        win_seconds,
        tools,
    ) = get_spec_injection_settings(root)
    if not enabled:
        return 0

    _scripts_dir_on_path(root)
    try:
        from common.spec_inject import STATE_VERSION  # type: ignore[import-not-found]
    except Exception:
        return 0

    if input_data.get("hook_event_name") == "SessionStart":
        if input_data.get("source") not in ("clear", "compact"):
            return 0
        base_identity, stateless = resolve_base_identity(root, input_data)
        if stateless:
            _warn("SessionStart reset has no stable session identity")
            return 0
        base_dir = _state_base_dir()
        _maybe_gc(base_dir)
        reset_path = base_dir / _project_id(root) / f"{base_identity}.jsonl"
        reset_fd = open_shard(reset_path)
        if reset_fd is None:
            return 0
        try:
            lock_shard(reset_fd)
            append_records(
                reset_fd,
                [{"v": STATE_VERSION, "reset": uuid.uuid4().hex, "ts": time.time()}],
            )
        finally:
            unlock_shard(reset_fd)
            try:
                os.close(reset_fd)
            except OSError:
                pass
        return 0

    event_name = input_data.get("hook_event_name")
    tool_name = input_data.get("tool_name", "") or input_data.get("toolName", "")
    if not isinstance(tool_name, str) or not tool_name:
        return 0
    is_pre_tool_use = event_name == "PreToolUse"
    is_patch_tool = event_name == "PreToolUse" and tool_name == "apply_patch"
    logical_tool = "Edit" if is_patch_tool else tool_name
    # An empty `tools` list is the documented "disable every trigger" switch.
    if not tools or logical_tool not in tools:
        return 0

    # snake_case is Claude Code's shape; camelCase keeps parity with the
    # sibling hooks that already accept both (other platforms emit toolInput).
    tool_input = input_data.get("tool_input")
    if not isinstance(tool_input, dict):
        tool_input = input_data.get("toolInput")
    if not isinstance(tool_input, dict):
        return 0
    try:
        from common.spec_match import (  # type: ignore[import-not-found]
            match_specs_for_file,
            normalize_repo_relative,
        )
        from common.spec_inject import (  # type: ignore[import-not-found]
            assemble_payload,
        )
    except Exception:
        return 0  # matching/decision engine unavailable — degrade to nothing

    if is_patch_tool:
        command = tool_input.get("command")
        if not isinstance(command, str):
            return 0
        raw_paths = _patch_paths(command)
    else:
        file_path = tool_input.get("file_path")
        if not isinstance(file_path, str) or not file_path.strip():
            return 0
        raw_paths = [file_path.strip()]

    file_paths: list[str] = []
    for raw_path in raw_paths:
        normalized = normalize_repo_relative(root, raw_path)
        if normalized is not None and normalized not in file_paths:
            file_paths.append(normalized)
    if not file_paths:
        return 0

    matches = []
    match_files: dict[str, str] = {}
    for file_path in file_paths:
        for match in match_specs_for_file(root, file_path):
            if match.rel_path in match_files:
                continue
            matches.append(match)
            match_files[match.rel_path] = file_path
    if not matches:
        return 0

    base_identity, stateless = resolve_base_identity(root, input_data)
    identity = base_identity
    agent = _agent_id(input_data)
    if agent:
        identity += "+a-" + _sanitize(agent)

    state_records: dict[str, dict] = {}
    clock = {"reset": None, "ts": time.time()}
    fd: int | None = None

    if not stateless:
        base_dir = _state_base_dir()
        _maybe_gc(base_dir)
        project_dir = base_dir / _project_id(root)
        base_fd = open_shard(project_dir / f"{base_identity}.jsonl")
        if base_fd is None:
            # Circuit breaker: unwritable state → ticket-only for this event.
            stateless = True
        else:
            lock_shard(base_fd)
            base_snapshot = load_state(base_fd, STATE_VERSION)
            if base_snapshot is None:
                stateless = True
                unlock_shard(base_fd)
                os.close(base_fd)
            else:
                base_records, reset_id = base_snapshot
                if identity == base_identity:
                    fd = base_fd
                    state_records = base_records
                else:
                    unlock_shard(base_fd)
                    os.close(base_fd)
                    fd = open_shard(project_dir / f"{identity}.jsonl")
                    if fd is None:
                        stateless = True
                    else:
                        lock_shard(fd)
                        snapshot = load_state(fd, STATE_VERSION)
                        if snapshot is None:
                            stateless = True
                            unlock_shard(fd)
                            os.close(fd)
                            fd = None
                        else:
                            state_records, _ = snapshot

                if not stateless:
                    clock = {
                        "reset": reset_id,
                        "ts": time.time(),
                    }

    edited_rel = match_files[matches[0].rel_path]
    records_persisted = True
    try:
        payload, records = assemble_payload(
            edited_rel,
            matches,
            stateless,
            state_records,
            clock,
            max_spec_chars,
            max_total_chars,
            win_seconds,
            match_files=match_files,
        )
        if fd is not None and records:
            records_persisted = append_records(fd, records)
    finally:
        if fd is not None:
            unlock_shard(fd)
            try:
                os.close(fd)
            except OSError:
                pass

    if not payload:
        return 0

    hook_specific_output = {
        "hookEventName": "PreToolUse" if is_pre_tool_use else "PostToolUse",
        "additionalContext": payload,
    }
    if (
        is_pre_tool_use
        and records_persisted
        and any(record.get("mode") == "full" for record in records)
    ):
        hook_specific_output.update(
            {
                "permissionDecision": "deny",
                "permissionDecisionReason": (
                    "Trellis injected governing specs. Review them, then retry "
                    "this tool call."
                ),
            }
        )
    output = {"hookSpecificOutput": hook_specific_output}
    print(json.dumps(output, ensure_ascii=False))
    return 0


if __name__ == "__main__":
    try:
        sys.exit(main())
    except Exception:
        # Hook failures must never break the tool result or the session.
        sys.exit(0)