845 lines
31 KiB
Python
845 lines
31 KiB
Python
|
#!/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)
|