Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(hooks): collapse unchanged re-reads, and report what the hooks cost (#1362)
Raghav Chamadiya596e08888aad
diff --git a/docs/agent/DISTILL.md b/docs/agent/DISTILL.mdindex abca650a3..e9359eb1a 100644--- a/docs/agent/DISTILL.md+++ b/docs/agent/DISTILL.md@@ -196,6 +196,10 @@ The existing PostToolUse hook complements this passively:(opt-in: `hooks.read_skeleton`). The advisory version of this — a one-linenudge naming the skeleton's token cost — was retired after 516 firingsshowed no effect above the base rate.+- **Re-read collapse** — a `Read` of a file this session already read, at the+ same range, with no intervening edit and an identical content hash, is served+ as a short notice naming the earlier read (opt-in: `hooks.read_reread`).+ Never applied twice in a row, so one more Read always returns the content.- **Stale-read notice** — after an `Edit`/`Write`, a later `Read` of the samefile warns that earlier excerpts predate the edit.- **Search digest** — grep floods (≥50 lines) get a compact grouped-by-filediff --git a/docs/agent/HOOKS.md b/docs/agent/HOOKS.mdindex fa86866ee..097910a1e 100644--- a/docs/agent/HOOKS.md+++ b/docs/agent/HOOKS.md@@ -171,6 +171,36 @@ satisfies Claude Code's read-before-edit precondition, so an `Edit` (especiallywith `replace_all`) or a `Write` could touch bodies it never saw. Editing such afile raises a one-line warning, once per file, until the file is read in full.+**Re-reads of unchanged files.** With `hooks.read_reread: true` — same consent,+toggled afterwards with `repowise hook read-reread install | uninstall |+status` — a `Read` of a file the session already read comes back as a short+notice naming that earlier read, instead of the content. The content is already+in context a few tool calls up, so sending it twice buys nothing.++The gate is arithmetic rather than a judgement: the same range must have been+served, no `Edit` or `Write` may have come between, and the bytes must hash the+same. When they do not, the agent gets the file *and* a line saying it changed+on disk without an edit in this session — a `git checkout`, a formatter, another+agent. That is worth more than the bytes were, because nothing else in the+session can discover it.++Two rules bound how wrong this can be. It is **never applied twice in a row for+the same file**, so if a context compaction dropped the earlier copy, one more+Read always returns the content; the notice says exactly that. And a Read that+any surface replaced records no content observation at all, so the agent is+never told it already has bytes that a skeleton stood in for. Savings appear+under the `read_reread` filter, and a repo with it off still gets the+counterfactual.++**Searches that time out.** On Windows a `Glob` can exhaust ripgrep's 20-second+budget and return nothing at all — not "no matches", nothing, after twenty+seconds of waiting. A glob is a path query and the index already holds every+path, so repowise answers it offline at the moment the failure happens, naming+the matching paths and counting any it did not list. The win here is wall clock+rather than tokens. Brace expansion (`{a,b}`) is declined rather than+half-matched, and zero indexed matches stays silent: the index having nothing to+say is not the tree having no such file.+**Edit-time "governed by" decisions.** When the agent edits a file governed by anarchitectural decision (via `decision_node_links`), it gets a one-line noticewith the rationale, at most once per session per decision and only a few timesdiff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex 99ea36229..8b47ead01 100644--- a/docs/reference/CONFIG.md+++ b/docs/reference/CONFIG.md@@ -252,8 +252,26 @@ means every key below is off.```yamlhooks:read_skeleton: false # serve large indexed files as skeletons+ read_reread: false # serve unchanged re-reads as a pointer+ search_digest: false # serve multi-file grep floods as a digest```+- `read_reread` lets the PostToolUse Read hook answer a *repeat* Read with a+ short notice instead of the content, when the same range was already served+ this session, no `Edit`/`Write` came between, and the bytes hash the same.+ The notice names the earlier read and the tool call it happened on.+ Savings land in `repowise saved` under the `read_reread` filter.+ - **Nothing is guessed.** The decision is a hash comparison over what the+ agent was actually served. A file whose content differs is served in full,+ with a line saying it changed on disk and not through an edit in this+ session — which is worth more than the bytes, since nothing else in the+ session can discover that.+ - **Never twice in a row for the same file.** The premise is that the earlier+ copy is still in the agent's context, and a context compaction removes it.+ That is not detectable from a hook, so reading again always returns the+ content, and the notice says so.+ - Requires Claude Code 2.1.218+; older clients are left untouched.+ `REPOWISE_HOOK_READ_REREAD=1` overrides the file for one session.- `read_skeleton` lets the PostToolUse Read hook return the *skeleton* of afile instead of the file, for an unbounded Read of a large indexed file, onceper file per session. Signatures stay; bodies become `... N lines (a-b)`diff --git a/packages/cli/src/repowise/cli/agent_adapters/__init__.py b/packages/cli/src/repowise/cli/agent_adapters/__init__.pyindex 401f6cdea..8d76dab93 100644--- a/packages/cli/src/repowise/cli/agent_adapters/__init__.py+++ b/packages/cli/src/repowise/cli/agent_adapters/__init__.py@@ -15,4 +15,46 @@ command an agent runs. Module scope is stdlib-only; anything heavierfrom repowise.cli.agent_adapters.base import AgentAdapter, RewriteRequest, RewriteResult-__all__ = ["AgentAdapter", "RewriteRequest", "RewriteResult"]+#: Every agent repowise knows how to hook, by the ``--client`` / ``--agent``+#: marker its hook config passes. Values are ``module:attribute`` rather than+#: classes so registration costs no import: the PostToolUse hook resolves one+#: adapter per invocation and must not pay for the others.+#:+#: **This mapping is the whole cost of adding a harness.** Payload parsing,+#: response rendering, install/uninstall and — since the capability class+#: variables landed on :class:`AgentAdapter` — which tools it calls and whether+#: it can replace a tool result all live in the adapter module. Nothing+#: downstream branches on an agent's name.+_REGISTRY: dict[str, str] = {+ "claude-code": "repowise.cli.agent_adapters.claude_code:ClaudeCodeAdapter",+ "codex": "repowise.cli.agent_adapters.codex:CodexAdapter",+}++#: What an unmarked payload is. Claude Code's hook config passes no marker,+#: because it was the only harness when the hooks were written.+DEFAULT_AGENT = "claude-code"+++def adapter_for(client: str | None) -> AgentAdapter:+ """The adapter for *client*, falling back to Claude Code.++ An unknown marker resolves to the default rather than raising: a hook must+ never fail on a payload, and the default's capability answers are checked+ before anything is served, so the worst case is an enrichment declined.+ """+ import importlib++ target = _REGISTRY.get((client or "").strip().lower() or DEFAULT_AGENT)+ if target is None:+ target = _REGISTRY[DEFAULT_AGENT]+ module_name, _, attr = target.partition(":")+ return getattr(importlib.import_module(module_name), attr)()+++__all__ = [+ "DEFAULT_AGENT",+ "AgentAdapter",+ "RewriteRequest",+ "RewriteResult",+ "adapter_for",+]diff --git a/packages/cli/src/repowise/cli/agent_adapters/base.py b/packages/cli/src/repowise/cli/agent_adapters/base.pyindex b484ab57c..e9edd3cd1 100644--- a/packages/cli/src/repowise/cli/agent_adapters/base.py+++ b/packages/cli/src/repowise/cli/agent_adapters/base.py@@ -18,11 +18,17 @@ if TYPE_CHECKING:class RewriteRequest:"""Agent-agnostic view of one shell command an agent is about to run."""- __slots__ = ("command", "cwd", "shell")+ __slots__ = ("command", "cwd", "session_id", "shell")- def __init__(self, command: str, cwd: str, shell: str = "posix") -> None:+ def __init__(+ self, command: str, cwd: str, shell: str = "posix", session_id: str = ""+ ) -> None:self.command = commandself.cwd = cwd+ #: The agent's session id, carried solely so the rewrite hook can+ #: count itself in the ledger. Empty means "not offered by this+ #: harness", and an unattributable count is not written at all.+ self.session_id = session_id#: ``"posix"`` or ``"powershell"`` — which shell dialect the agent#: will run the command under. PowerShell commands get extra#: classifier bailouts (PS aliases like ``ls`` don't survive a@@ -122,17 +128,34 @@ def unmatched_tool_names(matcher: str | None, names: frozenset[str]) -> tuple[stclass AgentAdapter(ABC):- """Everything agent-specific about the command-rewrite hook.+ """Everything agent-specific about repowise's hooks, in one declaration.Implementations translate between one agent's hook protocol and the- agent-agnostic :class:`RewriteRequest`/:class:`RewriteResult` pair, and- own that agent's hook install/uninstall. The classification logic in- :mod:`repowise.cli.rewrite_hook` never sees a hook payload.+ agent-agnostic :class:`RewriteRequest`/:class:`RewriteResult` pair, own+ that agent's hook install/uninstall, and **answer the capability questions+ the hook surfaces would otherwise ask about a client by name**. The+ classification logic in :mod:`repowise.cli.rewrite_hook` and the+ PostToolUse surfaces in :mod:`repowise.cli.commands.augment_cmd` never see+ a hook payload and never branch on ``client == "codex"``.++ That last part is why the capability class variables below exist. There+ are now three surfaces that replace a tool result, and each one asking+ "which client is this, and can it honour ``updatedToolOutput``?" for+ itself is three copies of an answer that belongs to the adapter. Adding a+ fourth harness should be one registration here, not a new branch in three+ modules."""#: Stable adapter identifier (e.g. ``"claude-code"``).name: ClassVar[str]+ #: Savings-ledger ``source`` tag for commands this agent's rewrite hook+ #: wrapped, so ``repowise saved --by source`` can tell harnesses apart.+ #: None means "derive it from the shell dialect", which is what the+ #: original harness does (``hook-bash`` / ``hook-powershell``). Declared+ #: here rather than tested for by name at the call site.+ savings_source: ClassVar[str | None] = None+#: Permission postures this agent's hook protocol can actually honor for#: a rewritten command. Claude Code supports ask-with-mutation; an agent#: that can only allow-with-mutation (Codex) narrows this to@@ -140,12 +163,43 @@ class AgentAdapter(ABC):#: rather than silently escalating them to an unprompted rewrite.rewrite_permissions: ClassVar[frozenset[str]] = frozenset({"ask", "allow"})+ #: Whether this agent's PostToolUse protocol has a field that *replaces*+ #: a tool result at all. Codex's carries a context string and nothing+ #: else, so a replacement handed to it is dropped on the floor, and+ #: dropped **silently**, which is how a surface can record served rows+ #: while every agent still sees the original bytes. Default False: a+ #: harness is assumed unable to replace until its adapter says otherwise,+ #: because the cost of assuming wrong is a ledger full of savings that+ #: never happened.+ replaces_tool_output: ClassVar[bool] = False+#: Tool names this agent uses to run a shell command. The installed hook's#: matcher is derived from this set and checked back against it, so an#: upstream rename cannot leave a matcher and a gate disagreeing in#: silence. Empty means the adapter declines to say.shell_tool_names: ClassVar[frozenset[str]] = frozenset()+ #: Tool names that read a file, edit one, and search the tree. The+ #: PostToolUse dispatcher routes on these rather than on literals, so a+ #: harness that calls its editor ``apply_patch`` needs no branch of its+ #: own. Empty means this agent has no such tool, which is a real answer+ #: and not an omission: an agent that reaches the shell to search has no+ #: search tool to register a matcher against, and registering one anyway+ #: buys a surface that can never fire.+ read_tool_names: ClassVar[frozenset[str]] = frozenset()+ edit_tool_names: ClassVar[frozenset[str]] = frozenset()+ search_tool_names: ClassVar[frozenset[str]] = frozenset()++ def supports_updated_output(self) -> bool:+ """Whether the *installed build* of this agent can honour a replacement.++ Separate from :attr:`replaces_tool_output`, which is about the+ protocol: an agent whose protocol has the field may still be running a+ release that predates it. Only an adapter that answers True to both is+ handed a replacement. Default False, matching the class default above.+ """+ return False+@abstractmethoddef detect(self) -> bool:"""True when this agent appears to be installed for the current user."""diff --git a/packages/cli/src/repowise/cli/agent_adapters/claude_code.py b/packages/cli/src/repowise/cli/agent_adapters/claude_code.pyindex 1afe14047..c775fdf96 100644--- a/packages/cli/src/repowise/cli/agent_adapters/claude_code.py+++ b/packages/cli/src/repowise/cli/agent_adapters/claude_code.py@@ -11,6 +11,7 @@ approval, which is exactly the posture we want for a rewritten command.from __future__ import annotationsimport json+import osimport os.pathfrom typing import TYPE_CHECKING, ClassVar@@ -31,14 +32,44 @@ SHELL_TOOL_NAMES: frozenset[str] = frozenset({"Bash", "PowerShell"})SHELL_TOOL_MATCHER: str = "|".join(sorted(SHELL_TOOL_NAMES))+#: Claude Code release that introduced ``updatedToolOutput``. Older clients+#: ignore the field, which would silently drop the enrichment, so on those a+#: replacing surface leaves the tool result untouched.+MIN_UPDATED_OUTPUT_VERSION: tuple[int, ...] = (2, 1, 218)++class ClaudeCodeAdapter(AgentAdapter):name: ClassVar[str] = "claude-code"shell_tool_names: ClassVar[frozenset[str]] = SHELL_TOOL_NAMES+ read_tool_names: ClassVar[frozenset[str]] = frozenset({"Read"})+ edit_tool_names: ClassVar[frozenset[str]] = frozenset({"Edit", "Write"})+ search_tool_names: ClassVar[frozenset[str]] = frozenset({"Grep", "Glob"})++ #: The only harness observed so far whose PostToolUse protocol can replace+ #: a tool result (``updatedToolOutput``).+ replaces_tool_output: ClassVar[bool] = Truedef detect(self) -> bool:return os.path.isdir(os.path.expanduser("~/.claude"))+ def supports_updated_output(self) -> bool:+ """True when the installed Claude Code build can honour a replacement.++ There is no version in the hook payload and no version env var, and+ ``claude --version`` is a ~1s subprocess this path cannot afford. The+ one cheap on-disk signal is the updater's own record, so we read that+ and **fail open** — an unsupported client ignores the unknown field,+ which costs a skipped enrichment, never a broken tool call.++ ``REPOWISE_HOOK_UPDATED_OUTPUT`` overrides, for a one-session A/B.+ """+ override = os.environ.get("REPOWISE_HOOK_UPDATED_OUTPUT")+ if override is not None:+ return override.strip().lower() in ("1", "true", "yes", "on")+ version = _recorded_client_version()+ return version is None or version >= MIN_UPDATED_OUTPUT_VERSION+def parse_hook_payload(self, raw: str) -> RewriteRequest | None:try:payload = json.loads(raw)@@ -56,10 +87,12 @@ class ClaudeCodeAdapter(AgentAdapter):if not isinstance(command, str) or not command.strip():return Nonecwd = payload.get("cwd")+ session_id = payload.get("session_id")return RewriteRequest(command=command,cwd=cwd if isinstance(cwd, str) else "",shell="powershell" if tool_name == "PowerShell" else "posix",+ session_id=session_id if isinstance(session_id, str) else "",)def render_response(self, result: RewriteResult) -> str:@@ -101,3 +134,30 @@ class ClaudeCodeAdapter(AgentAdapter):)return claude_code_rewrite_hook_matcher()+++def _recorded_client_version() -> tuple[int, ...] | None:+ """Installed Claude Code version per ``~/.claude/.last-update-result.json``.++ Best effort by construction: the file only exists once the updater has run+ at least once, and its ``version_to`` is null on a failed update — in which+ case ``version_from`` is what is still installed.++ ``json`` is already imported by this module's payload parsing, so this+ costs a single small file read on the one path that asks for it.+ """+ try:+ path = os.path.join(os.path.expanduser("~"), ".claude", ".last-update-result.json")+ with open(path, encoding="utf-8") as fh:+ data = json.load(fh)+ except (OSError, ValueError, RuntimeError):+ return None+ if not isinstance(data, dict):+ return None+ for key in ("version_to", "version_from"):+ value = data.get(key)+ if isinstance(value, str) and value:+ parts = value.split(".")+ if all(p.isdigit() for p in parts) and parts:+ return tuple(int(p) for p in parts)+ return Nonediff --git a/packages/cli/src/repowise/cli/agent_adapters/codex.py b/packages/cli/src/repowise/cli/agent_adapters/codex.pyindex ab905d4b7..b14b23abf 100644--- a/packages/cli/src/repowise/cli/agent_adapters/codex.py+++ b/packages/cli/src/repowise/cli/agent_adapters/codex.py@@ -57,15 +57,42 @@ SHELL_TOOL_NAMES: frozenset[str] = frozenset({"Bash", "shell_command"})#: hook that runs and then declines every payload it is handed.SHELL_TOOL_MATCHER: str = "|".join(sorted(SHELL_TOOL_NAMES))+#: Every name Codex has given a tool that edits a file. ``apply_patch`` is the+#: current one; ``Edit``/``Write`` are carried for the same reason the shell set+#: carries more than one name — a matcher that stops matching is silent in+#: exactly the way a working hook is. A tuple, not a set, because the matcher+#: below is derived from it and the shipped ``hooks.json`` has an order.+#: Kept in step with that file by ``tests/unit/cli/test_codex_plugin.py``.+_EDIT_TOOL_ORDER: tuple[str, ...] = ("apply_patch", "Edit", "Write")++EDIT_TOOL_NAMES: frozenset[str] = frozenset(_EDIT_TOOL_ORDER)++#: The same set as a hooks.json matcher, in the order the plugin ships it.+EDIT_TOOL_MATCHER: str = "|".join(_EDIT_TOOL_ORDER)+class CodexAdapter(AgentAdapter):name: ClassVar[str] = "codex"+ #: Codex rewrites are tagged as their own surface in the savings ledger.+ savings_source: ClassVar[str | None] = "hook-codex"+shell_tool_names: ClassVar[frozenset[str]] = SHELL_TOOL_NAMES+ #: Codex has no first-class read or search tool — both go through the+ #: shell — so those sets stay empty and the PostToolUse dispatcher routes+ #: nothing to the Read and Grep surfaces for this harness. That is the+ #: honest answer, not an omission.+ edit_tool_names: ClassVar[frozenset[str]] = EDIT_TOOL_NAMES+#: No ask-with-mutation in the Codex hook protocol — see module docstring.rewrite_permissions: ClassVar[frozenset[str]] = frozenset({"allow"})+ #: Codex's PostToolUse contract carries a context string and nothing that+ #: can stand in for a tool result, so no replacing surface may hand it one+ #: (inherited default, spelled out because it is load-bearing).+ replaces_tool_output: ClassVar[bool] = False+def detect(self) -> bool:return os.path.isdir(os.path.expanduser("~/.codex"))@@ -88,9 +115,11 @@ class CodexAdapter(AgentAdapter):if not isinstance(command, str) or not command.strip():return Nonecwd = payload.get("cwd")+ session_id = payload.get("session_id")return RewriteRequest(command=command,cwd=cwd if isinstance(cwd, str) else "",+ session_id=session_id if isinstance(session_id, str) else "",# Codex names its shell tool the same on every platform, so the# dialect has to come from the platform. It is PowerShell on# Windows — the real rollouts are full of `get-content`,diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/__init__.py b/packages/cli/src/repowise/cli/commands/augment_cmd/__init__.pyindex a2c33f686..2b4367ecb 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/__init__.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/__init__.py@@ -8,7 +8,9 @@ Split out of a single ~1300-line module into cohesive submodules:* :mod:`.read_state` — per-session Read/Edit read-intelligence state machine.* :mod:`.decision_inject` — relevance-ranked standing-decision injection(SessionStart block + edit-time governing-decision notice).-* :mod:`.ledger` — the sessions.db efficacy ledger every surface writes to.+* :mod:`repowise.cli.hook_ledger` — the sessions.db ledger every surface+ writes to. It sits outside this package because the PreToolUse rewrite hook+ writes to it too and cannot afford this package's ``__init__``.* :mod:`.served_reads` — read-after-served bookkeeping (measurement only).* :mod:`.bash_staleness` — post-git-commit stale-wiki detection.* :mod:`.codex` — Codex lifecycle hooks.diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.pyindex b0f9d7131..57a19e4e4 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py@@ -14,6 +14,8 @@ from functools import lru_cachefrom pathlib import Pathfrom typing import NamedTuple+from repowise.cli import hook_ledger as _hook_ledger+class HookResult(NamedTuple):"""What one PostToolUse handler wants the hook to do.@@ -58,12 +60,14 @@ def as_result(value: HookResult | str | None) -> HookResult:#: module loads, and the response is written after. Claude Code records the#: true end-to-end figure as ``attachment.durationMs``, which the transcript#: pass in :mod:`repowise.core.sessions.efficacy` writes over the top.-_T0 = time.perf_counter()---def _elapsed_ms() -> int:- """Milliseconds of in-process hook work so far (see :data:`_T0`)."""- return int((time.perf_counter() - _T0) * 1000)+#: Re-exported, not defined: the clock and the build stamp are the rewrite+#: hook's too, so both live in :mod:`repowise.cli.hook_ledger` and there is one+#: of each. Bound at *this* module's scope on purpose — ``_shared`` is imported+#: as augment starts, so ``hook_ledger._T0`` is captured then rather than at+#: the first ledger write, which would stamp every firing with ~0 ms.+#: ``hook_ledger`` is free to import: its module scope is ``os`` and ``time``.+_elapsed_ms = _hook_ledger._elapsed_ms+emitting_build = _hook_ledger.emitting_builddef _ledger_key(surface: str, category: str, text: str) -> str:@@ -176,9 +180,17 @@ def hook_flag_enabled(repo_path: Path, flag: str) -> bool:_FORGONE_TABLE_SQL = ("CREATE TABLE IF NOT EXISTS forgone_savings (""created_at REAL NOT NULL, source TEXT NOT NULL, path TEXT NOT NULL, "- "raw_tokens INTEGER NOT NULL, distilled_tokens INTEGER NOT NULL)"+ "raw_tokens INTEGER NOT NULL, distilled_tokens INTEGER NOT NULL, "+ "filter TEXT NOT NULL DEFAULT '')")+#: ``filter`` arrived after the table did. Two replacing surfaces now share the+#: ``hook-read`` source — the skeleton and the re-read collapse — so ``source``+#: alone can no longer say which one forwent what, and summing by source would+#: report each surface's counterfactual as both of them. Rows written before+#: this column carry ``''`` and are attributed to neither.+_FORGONE_MIGRATION_SQL = "ALTER TABLE forgone_savings ADD COLUMN filter TEXT NOT NULL DEFAULT ''"+def _omission_db(repo_path: Path) -> Path | None:"""The omission store, or None when this repo has not opted into one.@@ -239,6 +251,7 @@ def record_forgone(path: str,raw_tokens: int,distilled_tokens: int,+ filter_name: str = "",) -> None:"""Record a saving this repo *would* have made, had the surface been on.@@ -255,11 +268,13 @@ def record_forgone(con = sqlite3.connect(str(db_path), timeout=2)try:con.execute(_FORGONE_TABLE_SQL)+ if "filter" not in {r[1] for r in con.execute("PRAGMA table_info(forgone_savings)")}:+ con.execute(_FORGONE_MIGRATION_SQL)con.execute("INSERT INTO forgone_savings "- "(created_at, source, path, raw_tokens, distilled_tokens) "- "VALUES (?, ?, ?, ?, ?)",- (time.time(), source, path, raw_tokens, distilled_tokens),+ "(created_at, source, path, raw_tokens, distilled_tokens, filter) "+ "VALUES (?, ?, ?, ?, ?, ?)",+ (time.time(), source, path, raw_tokens, distilled_tokens, filter_name),)con.commit()finally:diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/command.py b/packages/cli/src/repowise/cli/commands/augment_cmd/command.pyindex 2b1d6d992..867e2eb83 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/command.py@@ -91,7 +91,7 @@ from pathlib import Pathimport click-from repowise.cli.agent_adapters.codex import SHELL_TOOL_NAMES+from repowise.cli.agent_adapters import adapter_forfrom ._shared import HookResult, as_resultfrom .bash_staleness import _handle_bash_post@@ -102,14 +102,28 @@ from .served_reads import _handle_mcp_read_post, _log_read_after_servedfrom .session_start import _handle_claude_session_startfrom .wrong_path import _handle_tool_failure-_EDIT_TOOL_NAMES = {"apply_patch", "Edit", "Write"}--#: Shell tools, across both harnesses. ``PowerShell`` is Windows Claude Code;-#: the rest are what Codex has called its shell tool, owned by the adapter so-#: the dispatch here and the installed matcher cannot disagree. Free at module-#: scope: ``agent_adapters`` is stdlib-only by its own hot-path contract, and-#: `tests/unit/cli/test_augment_hook_perf.py` holds that.-_SHELL_TOOL_NAMES = SHELL_TOOL_NAMES | {"PowerShell"}+#: One adapter per hook process, resolved from the ``--client`` marker. Every+#: "which tools does this agent call?" question below reads off it, so the+#: dispatcher carries no tool-name literals and a third harness needs no branch+#: here — see ``agent_adapters._REGISTRY``, which is the whole registration.+#:+#: This replaced a union of both harnesses' tool names, which routed a Codex+#: tool name for a Claude payload and vice versa. Harmless while the names+#: happened not to collide, and exactly the shape that stops being harmless+#: when a third agent names its editor something the second one already uses.+#:+#: Free at module scope: ``agent_adapters`` is stdlib-only by its own hot-path+#: contract, and ``tests/unit/cli/test_augment_hook_perf.py`` holds that.+_ADAPTERS: dict[str, object] = {}+++def _adapter(client: str | None):+ """The adapter for this invocation, memoized for the process."""+ key = client or ""+ adapter = _ADAPTERS.get(key)+ if adapter is None:+ adapter = _ADAPTERS[key] = adapter_for(client)+ return adapter@click.command("augment")@@ -151,7 +165,7 @@ def _run_augment(*, client: str | None = None) -> None:session_id = session_id if isinstance(session_id, str) else ""result = _handle_codex_context_event(event, cwd, session_id)if result:- _emit_response(event, result)+ _emit_response(event, result, session_id)_count_run(cwd, session_id, event, "", emitted=bool(result))return@@ -162,7 +176,7 @@ def _run_augment(*, client: str | None = None) -> None:session_id = session_id if isinstance(session_id, str) else ""result = _handle_claude_session_start(cwd, session_id)if result:- _emit_response(event, result)+ _emit_response(event, result, session_id)_count_run(cwd, session_id, event, "", emitted=bool(result))return@@ -183,7 +197,7 @@ def _run_augment(*, client: str | None = None) -> None:tool_name, tool_input, payload.get("error"), cwd, session_id=session_id)if result:- _emit_response(event, result)+ _emit_response(event, result, session_id)_count_run(cwd, session_id, event, tool_name, emitted=bool(result))return@@ -202,7 +216,7 @@ def _run_augment(*, client: str | None = None) -> None:session_id=session_id,)if result:- _emit_response(event, result)+ _emit_response(event, result, session_id)if result.on_emitted is not None:# Post-response bookkeeping, for the same reason _count_run is below:# the agent must not wait on accounting.@@ -221,8 +235,9 @@ def _count_run(cwd: str, session_id: str, event: str, tool: str, *, emitted: booif not session_id:returntry:+ from repowise.cli.hook_ledger import _record_hook_run+from ._shared import _find_repo_root- from .ledger import _record_hook_runrepo_path = _find_repo_root(Path(cwd))if repo_path is not None:@@ -231,7 +246,7 @@ def _count_run(cwd: str, session_id: str, event: str, tool: str, *, emitted: booreturn-def _emit_response(event: str, result: HookResult | str) -> None:+def _emit_response(event: str, result: HookResult | str, session_id: str = "") -> None:"""Write the hook JSON response to stdout.Two fields, and they are not alternatives: ``additionalContext`` is@@ -258,7 +273,7 @@ def _emit_response(event: str, result: HookResult | str) -> None:dedup_mark = replacement or ""else:dedup_mark = json.dumps(replacement, sort_keys=True)- if not _claim_emission(event, f"{result.context or ''}\x00{dedup_mark}"):+ if not _claim_emission(event, f"{session_id}\x00{result.context or ''}\x00{dedup_mark}"):returnpayload: dict[str, object] = {"hookEventName": event}if result.context:@@ -283,6 +298,13 @@ def _claim_emission(event: str, context: str) -> bool:exactly one win: the first caller creates it atomically and emits; a secondcaller within the TTL sees a fresh marker and stays silent. Fail-open — anyerror returns True so a dedup glitch can never swallow a real emission.++ The session id is part of the key (the caller folds it into *context*).+ Without it, two genuinely separate sessions — a parent and a subagent,+ which never share an id — that read the same file at the same point in+ their own tool sequence produce byte-identical notices, and the second one+ is silently swallowed. The duplicates this exists to catch are two+ processes on *one* tool event, which by definition share a session."""import hashlibimport os@@ -332,33 +354,36 @@ def _handle_post_tool_use(:class:`HookResult` themselves; every other branch yields plain additionalcontext and keeps returning ``str | None``, which :func:`as_result` liftshere, so the two-field shape exists in one place rather than in eight.++ Every tool-name test below is the adapter's answer for *this* harness."""+ adapter = _adapter(client)# The edit-tool freshness notice is a Codex-only lifecycle hook, gated on# the Codex client so the widened Claude matcher (Read|Edit|Write) can't# emit Codex-flavored banners to Claude Code users. Both clients record# the edit for the per-session stale-read state machine; Claude clients# additionally get the once-per-decision governing-decision notice.- if tool_name in _EDIT_TOOL_NAMES:+ if tool_name in adapter.edit_tool_names:if client == "codex":_record_edit(tool_input, cwd, session_id)return as_result(_handle_post_edit_use(cwd, session_id=session_id, tool_input=tool_input))return as_result(_handle_edit_post(tool_input, cwd, session_id))- if tool_name == "Read":+ if tool_name in adapter.read_tool_names:# Read-after-served KPI: logged to the ledger, never spoken about._log_read_after_served(tool_input, tool_output, cwd, session_id)- return _handle_read_post(tool_input, tool_output, cwd, session_id)- if tool_name in _SHELL_TOOL_NAMES:+ return _handle_read_post(tool_input, tool_output, cwd, session_id, adapter=adapter)+ if tool_name in adapter.shell_tool_names:# The PowerShell tool (Windows Claude Code) and Codex's several names# for its shell all surface the same stdout/stderr response shape as# Bash — one handler covers them.return as_result(_handle_bash_post(tool_input, tool_output, cwd))- if tool_name in ("Grep", "Glob"):- # ``client`` reaches this one because the flood digest can *replace*- # the tool output, and only Claude Code's protocol can honour that.+ if tool_name in adapter.search_tool_names:+ # The adapter reaches this one because the flood digest can *replace*+ # the tool output, and not every harness's protocol can honour that.return _handle_search_post(- tool_name, tool_input, tool_output, cwd, session_id, client=client+ tool_name, tool_input, tool_output, cwd, session_id, adapter=adapter)if tool_name.startswith("mcp__") and "repowise" in tool_name.lower():# Served-content bookkeeping for the read-after-served KPI. Neverdiff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py b/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.pyindex 0f31bd11f..c206d8e25 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py@@ -436,10 +436,13 @@ def _session_decision_block(repo_path: Path, session_id: str) -> str | None:globals_shown += 1if not shown:return None- from .ledger import _record_injections+ from repowise.cli.hook_ledger import _record_injections- _record_injections(repo_path, session_id, [d["id"] for d in shown], node_id="")- return "\n".join(lines)+ block = "\n".join(lines)+ _record_injections(+ repo_path, session_id, [d["id"] for d in shown], node_id="", chars=len(block)+ )+ return block# ---------------------------------------------------------------------------@@ -523,15 +526,11 @@ def _edit_decision_notice(repo_path: Path, rel: str, session_id: str, state: dicconn.close()shown.append(decision["id"])- if session_id:- from .ledger import _claim_injection-- claimed, session_total = _claim_injection(- repo_path, session_id, decision["id"], rel- )- if not claimed or session_total > _MAX_EDIT_NOTICES:- return None+ # Built before the claim, not after: the claim records what this emission+ # costs, and the cost model sums that column. A row claimed at zero chars+ # is an injection the net reports as free. Building first is a handful of+ # string operations on a path that has already done a database query.why = _clip(decision["rationale"] or decision["decision"], _CLIP_RATIONALE)if _echoes_title(decision["title"], why):why = "" # legacy rows echo the title into decision/rationale@@ -540,7 +539,17 @@ def _edit_decision_notice(repo_path: Path, rel: str, session_id: str, state: dicline += f" because {why}"if sessions_n >= 2:line += f" (confirmed across {sessions_n} sessions)"- return line + "."+ line += "."++ if session_id:+ from repowise.cli.hook_ledger import _claim_injection++ claimed, session_total = _claim_injection(+ repo_path, session_id, decision["id"], rel, chars=len(line)+ )+ if not claimed or session_total > _MAX_EDIT_NOTICES:+ return None+ return line# ---------------------------------------------------------------------------@@ -628,8 +637,9 @@ def _edit_fix_history_notice(repo_path: Path, rel: str, session_id: str) -> strline += "."if session_id:+ from repowise.cli.hook_ledger import _claim_ledger+from ._shared import _ledger_key- from .ledger import _claim_ledgerclaimed, shown = _claim_ledger(repo_path,diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/fast_lookup.py b/packages/cli/src/repowise/cli/commands/augment_cmd/fast_lookup.pyindex f3539fa70..66512f16f 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/fast_lookup.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/fast_lookup.py@@ -136,6 +136,20 @@ def files_by_basename(return [node_id for (node_id,) in rows if node_id]+def file_nodes(conn: sqlite3.Connection, repository_id: str, limit: int = 20000) -> list[str]:+ """Every indexed file path in this repo, for answering a path query offline.++ Capped rather than exhaustive: the caller matches a glob against these and+ then shows a handful, so a repo large enough to hit the cap is one whose+ answer was going to be truncated anyway.+ """+ rows = conn.execute(+ "SELECT node_id FROM graph_nodes WHERE repository_id = ? AND node_type = 'file' LIMIT ?",+ (repository_id, limit),+ ).fetchall()+ return [node_id for (node_id,) in rows if node_id]++def symbols_matching(conn: sqlite3.Connection, repository_id: str, paths: list[str], needle: str) -> list[tuple[str, str]]:diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/glob_rescue.py b/packages/cli/src/repowise/cli/commands/augment_cmd/glob_rescue.pynew file mode 100644index 000000000..8fa038c0a--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/glob_rescue.py@@ -0,0 +1,143 @@+"""Answer a Glob that ripgrep gave up on, from the index.++``Ripgrep search timed out after 20 seconds`` is the whole event. The tool+scanned the working tree, ran out of time, and returned nothing — not "no+matches", *nothing*, after twenty seconds of the agent waiting. A glob is a+path query, and the index already holds every path, so this is answerable+offline and instantly at the moment the failure happens.++**The headline here is wall clock, not tokens.** A timeout costs twenty+seconds and then usually a retry, and the retry is the same scan. The tokens+saved are incidental.++**Platform-local, and stated as such.** These timeouts cluster on Windows,+where the filesystem walk is slow enough to hit the ceiling; the same globs on+macOS return in well under a second. This ships because the event is already+registered and the answer is free, not because it is a general win.++Precision rules, in the same posture as the wrong-path rescue:++* **Only a real timeout.** Every other Glob failure — a rejected pattern, a+ user interrupt — is somebody else's problem and gets silence.+* **No brace expansion.** ``{a,b}`` is a shell construct this does not+ implement, and half-matching a pattern is worse than not answering it.+* **Say what was dropped.** The list is capped and the tail is counted, so the+ agent can see the answer is partial.+* **Never claim emptiness.** Zero indexed matches means the index has nothing+ to say, which is not the same as the tree having no such file, so it stays+ silent rather than reporting "no matches".+"""++from __future__ import annotations++import re+from typing import TYPE_CHECKING++if TYPE_CHECKING: # pragma: no cover - hot path keeps pathlib out of the graph+ from pathlib import Path++#: The failure verbatim, as the tool emits it.+TIMEOUT_ERROR = re.compile(r"Ripgrep search timed out after \d+ seconds?")++#: Paths named in the rescue before the tail is counted instead.+_MAX_LISTED = 20++#: Brace expansion is not implemented; a pattern using it is declined whole.+_BRACES = re.compile(r"[{}]")+++def _translate(pattern: str) -> re.Pattern[str] | None:+ """A glob as a regex over POSIX paths, or None if it is not one we do.++ ``**`` crosses separators and ``*`` does not, which is the one rule a+ naive :func:`fnmatch.translate` gets wrong — there, ``*`` matches ``/`` and+ ``packages/*.py`` would answer with the whole tree. Written out rather than+ imported so the two cannot drift.+ """+ if not pattern or _BRACES.search(pattern):+ return None+ out: list[str] = []+ i, n = 0, len(pattern)+ while i < n:+ char = pattern[i]+ if char == "*":+ if pattern.startswith("**", i):+ i += 2+ # `**/` swallows the separator so it can also match zero+ # directories: `**/x.py` has to find a root-level `x.py`.+ if pattern.startswith("/", i):+ i += 1+ out.append("(?:.*/)?")+ else:+ out.append(".*")+ continue+ out.append("[^/]*")+ elif char == "?":+ out.append("[^/]")+ elif char == "[":+ end = pattern.find("]", i + 1)+ if end == -1:+ out.append(re.escape(char))+ else:+ body = pattern[i + 1 : end].replace("\\", "\\\\")+ out.append(f"[{'^' + body[1:] if body.startswith('!') else body}]")+ i = end + 1+ continue+ else:+ out.append(re.escape(char))+ i += 1+ try:+ return re.compile("".join(out) + r"\Z", re.IGNORECASE)+ except re.error:+ return None+++def matching_paths(repo_path: Path, pattern: str, limit: int = _MAX_LISTED) -> tuple[list[str], int]:+ """``(paths, total)`` indexed under *repo_path* matching *pattern*.++ ``total`` is the full match count, so the caller can say how many it is+ not showing. Any failure answers ``([], 0)`` — silence, never a guess.+ """+ matcher = _translate(pattern.replace("\\", "/").lstrip("./"))+ if matcher is None:+ return [], 0+ from . import fast_lookup++ conn = fast_lookup.connect(repo_path)+ if conn is None:+ return [], 0+ try:+ repo_id = fast_lookup.repo_id(conn, repo_path)+ if repo_id is None:+ return [], 0+ nodes = fast_lookup.file_nodes(conn, repo_id)+ except Exception:+ return [], 0+ finally:+ conn.close()++ # An indexed path can name a resolved external package rather than a file+ # in this tree; those are not answers to a glob over the working tree.+ hits = [n for n in nodes if ":" not in n.split("/")[0] and matcher.match(n)]+ hits.sort()+ return hits[:limit], len(hits)+++def rescue(repo_path: Path, tool_input: dict, error_text: str) -> str | None:+ """The line to show for a timed-out Glob, or None to stay silent."""+ if not isinstance(tool_input, dict) or not TIMEOUT_ERROR.search(error_text):+ return None+ pattern = tool_input.get("pattern")+ if not isinstance(pattern, str) or not pattern.strip():+ return None+ paths, total = matching_paths(repo_path, pattern.strip())+ if not paths:+ return None+ listed = "\n".join(f" {p}" for p in paths)+ tail = f"\n ({total - len(paths)} more)" if total > len(paths) else ""+ return (+ f"[repowise] That search timed out, so the index answered it instead. "+ f"{total} indexed path(s) match `{pattern.strip()}`:\n{listed}{tail}\n"+ "These come from the last index, so a file added since will be missing; "+ "re-run the search scoped to a directory if you need the live tree."+ )diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/ledger.py b/packages/cli/src/repowise/cli/commands/augment_cmd/ledger.pydeleted file mode 100644index 52167896c..000000000--- a/packages/cli/src/repowise/cli/commands/augment_cmd/ledger.py+++ /dev/null@@ -1,257 +0,0 @@-"""The hook path's write side of the ``sessions.db`` efficacy ledger.--Every augment surface records what it showed and what it cost here, so the-update-time miner and ``repowise hook stats`` can judge one corpus rather than-one per surface. These helpers grew inside :mod:`decision_inject`, which owns-only the *decision* surface, so the read, search and served-read surfaces were-importing the shared ledger from a peer that has nothing to do with them. This-module is that shared thing, named.--Import it lazily, inside the function that writes, the way every caller here-does. Two reasons and both are load-bearing: a hook invocation that says-nothing must not pay for a database module it never opens, and a module-scope-``from .ledger import x`` binds a copy that a test patching ``ledger.x`` will-not reach — so a spy would silently miss whichever surfaces bound early.--Two constraints shape everything here, and neither is negotiable:--* **No ``repowise.core``.** The hook budget is 155 ms and importing the ORM- costs more than that on its own, so this is raw stdlib :mod:`sqlite3` and the- ``injections`` migration is duplicated verbatim from- ``core.sessions.staging`` rather than imported.- ``tests/unit/cli/test_augment_hook_perf.py`` asserts on the import graph.-* **Silence over failure.** A hook must never surface an error into the agent's- transcript, so every function here swallows :class:`sqlite3.Error` and the- claim helpers fail *closed* — an unusable sidecar degrades to saying nothing,- never to saying it twice.-"""--from __future__ import annotations--import sqlite3-import time-from pathlib import Path--_INJECTIONS_TABLE_SQL = (- "CREATE TABLE IF NOT EXISTS injections ("- "session_id TEXT NOT NULL, decision_id TEXT NOT NULL, "- "node_id TEXT NOT NULL DEFAULT '', shown_at REAL NOT NULL, "- "evaluated INTEGER NOT NULL DEFAULT 0, "- "surface TEXT NOT NULL DEFAULT '', "- "category TEXT NOT NULL DEFAULT '', "- "chars INTEGER NOT NULL DEFAULT 0, "- "duration_ms INTEGER NOT NULL DEFAULT 0, "- "acted INTEGER NOT NULL DEFAULT 0, "- "verdict TEXT NOT NULL DEFAULT '', "- "PRIMARY KEY (session_id, decision_id))"-)--_HOOK_RUNS_TABLE_SQL = (- "CREATE TABLE IF NOT EXISTS hook_runs ("- "session_id TEXT NOT NULL, event TEXT NOT NULL, tool TEXT NOT NULL, "- "calls INTEGER NOT NULL DEFAULT 0, emitted INTEGER NOT NULL DEFAULT 0, "- "total_ms INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (session_id, event, tool))"-)--#: Mirror of core.sessions.staging.INJECTIONS_LEDGER_COLUMNS — the hook path-#: must not import repowise.core, so the migration is duplicated verbatim.-_LEDGER_COLUMNS = (- ("surface", "TEXT NOT NULL DEFAULT ''"),- ("category", "TEXT NOT NULL DEFAULT ''"),- ("chars", "INTEGER NOT NULL DEFAULT 0"),- ("duration_ms", "INTEGER NOT NULL DEFAULT 0"),- ("acted", "INTEGER NOT NULL DEFAULT 0"),- ("verdict", "TEXT NOT NULL DEFAULT ''"),-)--#: One ledger connection per hook process, opened lazily. A single invocation-#: can write several rows (two notices plus the run counter), and connect +-#: WAL pragma + the CREATE/PRAGMA/ALTER migration is the expensive part, not-#: the INSERT. The process is short-lived and single-threaded, so caching is-#: safe; every writer commits, and process exit closes the handle.-#: Keyed by repo path, not global: a hook process only ever sees one repo, but-#: the test suite drives many through one interpreter, and a cache that-#: ignored the path would hand the second repo the first one's database.-_CONN: dict[Path, sqlite3.Connection | None] = {}---def _open_injections(repo_path: Path) -> sqlite3.Connection | None:- """The shared ledger connection, migrated and ready. None if unusable.-- Callers must NOT close the returned connection — see :data:`_CONN`.- """- if repo_path in _CONN:- return _CONN[repo_path]- db_path = repo_path / ".repowise" / "sessions" / "sessions.db"- try:- db_path.parent.mkdir(parents=True, exist_ok=True)- conn = sqlite3.connect(db_path, timeout=1)- conn.execute("PRAGMA journal_mode=WAL")- conn.execute("PRAGMA busy_timeout=1000")- conn.execute(_INJECTIONS_TABLE_SQL)- conn.execute(_HOOK_RUNS_TABLE_SQL)- existing = {row[1] for row in conn.execute("PRAGMA table_info(injections)")}- for name, decl in _LEDGER_COLUMNS:- if name not in existing:- conn.execute(f"ALTER TABLE injections ADD COLUMN {name} {decl}")- _CONN[repo_path] = conn- return conn- except (sqlite3.Error, OSError):- _CONN[repo_path] = None- return None---def _record_hook_run(- repo_path: Path, session_id: str, event: str, tool: str, *, emitted: bool-) -> None:- """Count one hook invocation and what it cost. Best-effort, never raises.-- Every invocation lands here, including the large majority that return- nothing: the matcher covers Read/Edit/Write/Grep/Glob/Bash/PowerShell and- the repowise MCP tools, and a silent run still pays the import cost. The- harness only writes a transcript record for hooks that *emitted*, so- without this counter the silent invocations — the bulk of the bill — are- invisible. Aggregated per (session, event, tool) rather than one row per- call, so the table stays small and the write stays a single upsert.- """- if not session_id:- return- from ._shared import _elapsed_ms-- conn = _open_injections(repo_path)- if conn is None:- return- try:- conn.execute(- "INSERT INTO hook_runs (session_id, event, tool, calls, emitted, total_ms) "- "VALUES (?, ?, ?, 1, ?, ?) "- "ON CONFLICT(session_id, event, tool) DO UPDATE SET "- "calls = calls + 1, emitted = emitted + excluded.emitted, "- "total_ms = total_ms + excluded.total_ms",- (session_id, event, tool, 1 if emitted else 0, _elapsed_ms()),- )- conn.commit()- except sqlite3.Error:- pass---def _record_injections(- repo_path: Path, session_id: str, decision_ids: list[str], *, node_id: str-) -> None:- """Log shown decisions in the sessions.db sidecar; best-effort, never raises.-- The update-time miner reads these rows to judge whether injected guidance- was followed or contradicted (usage feedback v1). Written with raw stdlib- sqlite3 so the hook path never imports repowise.core.- """- if not session_id or not decision_ids:- return- conn = _open_injections(repo_path)- if conn is None:- return- try:- from ._shared import _elapsed_ms-- now = time.time()- elapsed = _elapsed_ms()- conn.executemany(- "INSERT OR IGNORE INTO injections "- "(session_id, decision_id, node_id, shown_at, surface, category, duration_ms) "- "VALUES (?, ?, ?, ?, 'decision', 'session_start', ?)",- [(session_id, did, node_id, now, elapsed) for did in decision_ids],- )- conn.commit()- except sqlite3.Error:- pass---def _claim_ledger(- repo_path: Path,- session_id: str,- key: str,- *,- node_id: str,- surface: str,- category: str,- chars: int,-) -> tuple[bool, int]:- """Atomically claim one non-decision ledger emission.-- Generic twin of :func:`_claim_injection` for the read/search enrichment- surfaces: *key* replaces the decision id in the primary key, so INSERT OR- IGNORE is the once-per-session-per-key gate. Returns ``(claimed,- surface_injection_count)`` where the count covers only rows that actually- carried text (``chars > 0``) on *surface* — pure measurement rows must not- eat into an injection cap. Fail-closed: any error reports unclaimed.-- ``duration_ms`` records what this firing has cost so far (see- :func:`_shared._elapsed_ms`); it is what ``repowise hook stats`` reports- until a transcript pass replaces it with the harness-measured total.- """- from ._shared import _elapsed_ms-- conn = _open_injections(repo_path)- if conn is None:- return False, 0- try:- cur = conn.execute(- "INSERT OR IGNORE INTO injections "- "(session_id, decision_id, node_id, shown_at, surface, category, chars, "- "duration_ms) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",- (- session_id,- key,- node_id,- time.time(),- surface,- category,- chars,- _elapsed_ms(),- ),- )- claimed = cur.rowcount > 0- count = conn.execute(- "SELECT COUNT(*) FROM injections WHERE session_id = ? AND surface = ? AND chars > 0",- (session_id, surface),- ).fetchone()[0]- conn.commit()- return claimed, int(count)- except sqlite3.Error:- return False, 0---def _claim_injection(- repo_path: Path, session_id: str, decision_id: str, node_id: str-) -> tuple[bool, int]:- """Atomically claim the right to show one decision this session.-- Returns ``(claimed, edit_notice_count)``. The primary key makes the- INSERT OR IGNORE the once-per-session-per-decision gate, immune to the- state-file races two concurrent hook processes produce; the count backs- the strict per-session notice cap. Fail-closed: any error reports- unclaimed, so a sidecar glitch degrades to silence, never to spam.- """- from ._shared import _elapsed_ms-- conn = _open_injections(repo_path)- if conn is None:- return False, 0- try:- cur = conn.execute(- "INSERT OR IGNORE INTO injections "- "(session_id, decision_id, node_id, shown_at, surface, category, duration_ms) "- "VALUES (?, ?, ?, ?, 'decision', 'edit_notice', ?)",- (session_id, decision_id, node_id, time.time(), _elapsed_ms()),- )- claimed = cur.rowcount > 0- # Surface-scoped: read/search enrichment rows also carry a node_id and- # must not eat into the edit-notice cap.- count = conn.execute(- "SELECT COUNT(*) FROM injections WHERE session_id = ? AND node_id != '' "- "AND surface IN ('', 'decision')",- (session_id,),- ).fetchone()[0]- conn.commit()- return claimed, int(count)- except sqlite3.Error:- return False, 0diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.py b/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.pyindex 753bd7302..d5cd537ca 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.py@@ -1,19 +1,14 @@"""PostToolUse Read → serve the indexed skeleton instead of the whole file.The skeleton *nudge* — a one-line pointer at ``get_context(include=-["skeleton"])`` — fired 516 times across 203 sessions and was acted on once.-It did not fail on content. It failed by asking the agent to do something the-hook could do itself. This module does it instead: when every gate below-clears, the hook returns ``updatedToolOutput`` and the agent's Read of a large-indexed file arrives as its skeleton.--The nudge has since been retired outright rather than kept as a fallback: a-replay under three looser judges, including the compliance form used for a-notice that asks for a *non*-action, found it at or below the unconditioned-base rate on every one, and a session's second nudge did no better than its-first. ``sessions/efficacy.py`` carries the numbers. So a client that cannot-honour a replacement now gets silence, which is the honest fallback for a-surface with nothing to say.+["skeleton"])`` — did not fail on content. It failed by asking the agent to do+something the hook could do itself. This module does it instead: when every+gate below clears, the hook returns ``updatedToolOutput`` and the agent's Read+of a large indexed file arrives as its skeleton.++The nudge has since been retired outright rather than kept as a fallback, so a+client that cannot honour a replacement now gets silence, which is the honest+fallback for a surface with nothing to say.**This is not a silent truncation.** ``build_skeleton`` marks every elidedspan with its 1-indexed line range, so the agent can see exactly what was@@ -22,44 +17,41 @@ makes for shell output and the omission store makes for truncated MCPresponses. Reads were the last unfiltered surface. Reading the file a secondtime returns it whole; the header says so.-Gates, cheapest first (:func:`skeleton_replacement`):+Gates this surface owns, cheapest first (its caller in :mod:`.read_state`+holds the first five, :func:`skeleton_replacement` the rest):1. **Unbounded read only.** A ranged Read is already a targeted question.2. **Above the size floor** (100 output lines).-3. **Opted in.** ``hooks.read_skeleton: true`` in ``.repowise/config.yaml``,- default off. Read with a lazy ``yaml`` import and fail-closed.-4. **Not a verification re-read.** A Read that follows an Edit of the same+3. **Not a verification re-read.** A Read that follows an Edit of the samefile wants fidelity, not structure.-5. **Once per file per session.** The second Read is the escape hatch.-6. **Indexed**, with symbol bounds persisted.-7. **Worth it** — skeleton well under full, and the saving clears the floor.-8. **Under the output cap**, whole. A truncated skeleton would lose its+4. **Once per file per session.** The second Read is the escape hatch.+5. **Indexed**, with symbol bounds persisted.+6. **Worth it** — skeleton well under full, and the saving clears the floor.+7. **Under the output cap**, whole. A truncated skeleton would lose itstrailing elision ranges, which is the part that makes this reversible.+The harness capability probe, the ``hooks.read_skeleton`` opt-in, the+Read-shaped wire payload, the no-payload-no-ledger-row rule and both ledger+writes are :mod:`.replacement`'s, shared with the digest and the re-read+collapse.+Operational rules are the rest of augment's: stdlib on the way in, no network,any failure degrades to returning None and the agent sees its Read untouched."""from __future__ import annotations-import json-import osimport reimport sqlite3-from pathlib import Pathfrom typing import TYPE_CHECKING-from ._shared import MAX_OUTPUT_CHARS, hook_flag_enabled-from ._shared import record_forgone as _record_forgone-from ._shared import record_saving as _record_saving+from ._shared import MAX_OUTPUT_CHARS+from .replacement import Offerif TYPE_CHECKING: # pragma: no cover - the hook path imports these lazily- from repowise.core.distill.skeleton import SkeletonResult, SkeletonSymbol+ from pathlib import Path-#: Claude Code release that introduced ``updatedToolOutput``. Older clients-#: ignore the field, which would silently drop the enrichment, so on those the-#: Read is left untouched (see :func:`supports_updated_output`).-_MIN_CLIENT_VERSION = (2, 1, 218)+ from repowise.core.distill.skeleton import SkeletonResult, SkeletonSymbol#: Hard ceiling on the replacement string; shared with every other replacing#: surface. A skeleton that does not fit is skipped rather than cut, because@@ -67,88 +59,22 @@ _MIN_CLIENT_VERSION = (2, 1, 218)_MAX_OUTPUT_CHARS = MAX_OUTPUT_CHARS#: Savings-ledger identity, so ``repowise saved`` can name this surface.-_SAVINGS_SOURCE = "hook-read"+SAVINGS_SOURCE = "hook-read"_SAVINGS_FILTER = "read_skeleton"-_CONFIG_FLAG = "read_skeleton"---class Replacement:- """A skeleton ready to be served in place of a Read, and its ledger facts.-- A tiny value object rather than a tuple: the caller records a saving, logs- a ledger row and emits the text, and three positional elements at that- call site would read as noise.- """-- __slots__ = ("full_tokens", "payload", "rel", "skeleton_tokens", "text")-- def __init__(self, *, rel: str, text: str, full_tokens: int, skeleton_tokens: int) -> None:- self.rel = rel- self.text = text- self.full_tokens = full_tokens- self.skeleton_tokens = skeleton_tokens- #: Read-shaped wire payload wrapping :attr:`text`, filled in by the- #: caller once it has the Read's own ``tool_response`` to build from.- self.payload: dict | None = None-- @property- def saved_tokens(self) -> int:- return max(0, self.full_tokens - self.skeleton_tokens)---# ----------------------------------------------------------------------------# Gates-# ---------------------------------------------------------------------------+CONFIG_FLAG = "read_skeleton"def enabled(repo_path: Path) -> bool:"""True when this repo opted into read replacement. Fails closed.- Thin alias over the shared reader so the two replacing surfaces cannot- drift on how they read their flag. See :func:`_shared.hook_flag_enabled`- for the fail-closed rationale and the env override.+ Thin alias over the shared reader so the replacing surfaces cannot drift+ on how they read their flag. See :func:`_shared.hook_flag_enabled` for the+ fail-closed rationale and the env override."""- return hook_flag_enabled(repo_path, _CONFIG_FLAG)---def supports_updated_output() -> bool:- """True when the Claude Code client can honour ``updatedToolOutput``.+ from ._shared import hook_flag_enabled- There is no version in the hook payload and no version env var, and- ``claude --version`` is a ~1s subprocess this path cannot afford. The one- cheap on-disk signal is the updater's own record, so we read that and- **fail open** — an unsupported client ignores the unknown field, which- costs a skipped enrichment, never a broken Read.- """- override = os.environ.get("REPOWISE_HOOK_UPDATED_OUTPUT")- if override is not None:- return override.strip().lower() in ("1", "true", "yes", "on")- version = _recorded_client_version()- return version is None or version >= _MIN_CLIENT_VERSION---def _recorded_client_version() -> tuple[int, ...] | None:- """Installed Claude Code version per ``~/.claude/.last-update-result.json``.-- Best effort by construction: the file only exists once the updater has run- at least once, and its ``version_to`` is null on a failed update — in which- case ``version_from`` is what is still installed.- """- try:- raw = (Path.home() / ".claude" / ".last-update-result.json").read_text(encoding="utf-8")- data = json.loads(raw)- except (OSError, ValueError, RuntimeError):- return None- if not isinstance(data, dict):- return None- for key in ("version_to", "version_from"):- value = data.get(key)- if isinstance(value, str) and value:- parts = value.split(".")- if all(p.isdigit() for p in parts) and parts:- return tuple(int(p) for p in parts)- return None+ return hook_flag_enabled(repo_path, CONFIG_FLAG)def is_unbounded_read(tool_input: dict) -> bool:@@ -169,7 +95,7 @@ def skeleton_replacement(*,min_ratio_gain: float,min_saved_tokens: int,-) -> Replacement | None:+) -> Offer | None:"""Render *rel*'s skeleton, or None when any content gate fails.Callers own the cheap gates (see the module docstring); by the time this@@ -210,42 +136,17 @@ def skeleton_replacement(text = _render(rel, result, total_lines)if len(text) > _MAX_OUTPUT_CHARS:return None- return Replacement(- rel=rel,+ return Offer(+ key=rel,text=text,- full_tokens=result.full_tokens,+ raw_tokens=result.full_tokens,# The header is part of what the agent is billed for.- skeleton_tokens=max(1, len(text) // 4),+ new_tokens=max(1, len(text) // 4),+ category="skeleton_served",+ filter_name=_SAVINGS_FILTER,)-def as_read_output(tool_output: object, text: str) -> dict | None:- """Wrap *text* in the object shape Claude Code requires for a Read.-- ``updatedToolOutput`` is validated against the schema of the tool being- replaced, not against a common one. Read's is- ``{"type": "text", "file": {"filePath", "content", "numLines",- "startLine", "totalLines"}}``, and handing it a bare string is rejected- with ``does not match Read's output shape`` — after which the *original*- output goes to the agent while the hook still records a served row. That- failure is invisible from inside the hook (exit 0, no stderr), which is- why this builds from the payload's own ``tool_response`` rather than- constructing the envelope from scratch: unknown or future keys are- carried through untouched and only ``content`` and the line counts move.-- Returns None when the payload is not the shape we think it is, which- degrades to no replacement rather than to a rejected one.- """- if not isinstance(tool_output, dict):- return None- file_block = tool_output.get("file")- if not isinstance(file_block, dict) or "content" not in file_block:- return None- lines = text.count("\n") + (0 if text.endswith("\n") else 1)- updated_file = {**file_block, "content": text, "numLines": lines, "startLine": 1}- return {**tool_output, "file": updated_file}--#: The elision marker ``_render`` in distill.skeleton emits: indent, then#: ``... N lines (start-end)``, 1-indexed and inclusive._ELISION_RE = re.compile(r"^\s*\.\.\. \d+ lines \((\d+)-(\d+)\)\s*$")@@ -343,31 +244,3 @@ def _indexed_symbols(db_path: Path, rel: str) -> list[SkeletonSymbol]:for name, kind, start, end, signature in rowsif isinstance(start, int) and isinstance(end, int) and start > 0]---# ----------------------------------------------------------------------------# Savings ledger-# ------------------------------------------------------------------------------def record_forgone(repo_path: Path, replacement: Replacement) -> None:- """Record a saving this repo *would* have made, had the feature been on."""- _record_forgone(- repo_path,- source=_SAVINGS_SOURCE,- path=replacement.rel,- raw_tokens=replacement.full_tokens,- distilled_tokens=replacement.skeleton_tokens,- )---def record_saving(repo_path: Path, replacement: Replacement) -> None:- """Bill this replacement to the savings ledger so ``repowise saved`` sees it."""- _record_saving(- repo_path,- source=_SAVINGS_SOURCE,- filter_name=_SAVINGS_FILTER,- command=replacement.rel,- raw_tokens=replacement.full_tokens,- distilled_tokens=replacement.skeleton_tokens,- )diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/read_state.py b/packages/cli/src/repowise/cli/commands/augment_cmd/read_state.pyindex e00ccf00c..274a671de 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/read_state.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/read_state.py@@ -52,8 +52,55 @@ _READ_NUDGE_MIN_SAVINGS = 1500 # estimated tokens saved must clear this_READ_NUDGE_MAX_RATIO = 0.5 # skeleton must be at most this fraction of full-def _session_state_path(repo_path: Path) -> Path:- return Path(repo_path) / ".repowise" / ".augment-session.json"+#: Per-session state lives in its own file, and that is not a detail.+#:+#: It used to be a single ``.augment-session.json`` per repo, keyed on+#: ``session_id``, which **reset the whole file whenever the id changed**. A+#: subagent sidechain runs under a different session id from its parent, and+#: PostToolUse fires in sidechains, so a parent Read and a subagent Read+#: alternating through one repo wiped each other's state on every event. No+#: Read surface could hold a once-per-file gate long enough to fire, which+#: looked like sidechains not being reachable and was really this file name.+#:+#: Partitioning is also the semantically right answer, not merely the fix: a+#: subagent never received the parent's bytes, so it must not inherit the+#: parent's "you already have this".+_STATE_DIR = "hook-sessions"++#: Session files older than this are swept, once, when a session first writes.+#: A session lasts hours at the outside and the files are a few KB, so this is+#: generous on purpose: keeping one too long costs nothing, deleting a live one+#: costs a repeated notice.+_STATE_TTL_SECONDS = 7 * 24 * 3600+++def _session_state_path(repo_path: Path, session_id: str = "") -> Path:+ """This session's state file. One per session id — see :data:`_STATE_DIR`."""+ import hashlib++ digest = hashlib.sha1(session_id.encode("utf-8", "replace")).hexdigest()[:16]+ return Path(repo_path) / ".repowise" / _STATE_DIR / f"{digest}.json"+++def _sweep_stale_sessions(directory: Path) -> None:+ """Drop session files nothing will read again. Best-effort, never raises.++ Runs only when a session writes its state for the first time, so the+ directory listing is paid once per session rather than once per Read.+ """+ import time++ cutoff = time.time() - _STATE_TTL_SECONDS+ try:+ entries = list(directory.iterdir())+ except OSError:+ return+ for entry in entries:+ try:+ if entry.is_file() and entry.stat().st_mtime < cutoff:+ entry.unlink()+ except OSError:+ continuedef _load_session_state(repo_path: Path, session_id: str) -> dict:@@ -63,13 +110,26 @@ def _load_session_state(repo_path: Path, session_id: str) -> dict:per-session sequence number (``seq``) rather than wall-clock time — twohook events can land within one clock tick on Windows, and ordering isthe only thing the stale-read comparison needs.++ The ``session_id`` check below is belt and braces now rather than the+ partition itself (see :data:`_STATE_DIR`): the file is already per-session,+ so a mismatch means a digest collision or a hand-edited file, and starting+ fresh is the right answer to both."""fresh = {"session_id": session_id,"seq": 0,"reads": {},"edits": {},+ # Per path, what the previous Read of it actually delivered: content+ # digest, the file's size and mtime then, the range requested, and the+ # tool call it happened on. The whole basis of the re-read collapse,+ # and every field is load-bearing — see :mod:`.reread`.+ "read_meta": {},"stale_notified": [],+ # Files already flagged as changed-under-the-agent, so the notice is+ # once per file per session like every other one here.+ "changed_notified": [],# Files served as a skeleton this session. Doubles as the once-per-# file gate and as the "did the agent come back for it" marker."skeletonized": [],@@ -88,7 +148,9 @@ def _load_session_state(repo_path: Path, session_id: str) -> dict:"served": {},}try:- state = json.loads(_session_state_path(repo_path).read_text(encoding="utf-8"))+ state = json.loads(+ _session_state_path(repo_path, session_id).read_text(encoding="utf-8")+ )except (OSError, json.JSONDecodeError):return freshif not isinstance(state, dict) or state.get("session_id") != session_id:@@ -103,18 +165,31 @@ def _save_session_state(repo_path: Path, state: dict) -> bool:"""Persist session state; trims unbounded growth, never raises.Returns whether the write landed. Most callers can ignore that — a lost- notice-dedup entry costs a repeated notice. The skeleton replacement- cannot: its once-per-file gate *is* this file, so it checks.+ notice-dedup entry costs a repeated notice. The two replacing Read+ surfaces cannot: their once-per-file gate *is* this file, so they check."""for key in ("reads", "edits"):entries = state.get(key, {})if len(entries) > 500:keep = sorted(entries, key=entries.get, reverse=True)[:400]state[key] = {k: entries[k] for k in keep}+ # ``read_meta`` is the biggest thing here (a digest and three ints per+ # path), so it is trimmed to whatever survived above rather than growing+ # beside it. A dropped entry costs one uncollapsed re-read, never a wrong+ # answer: the collapse needs the entry to fire at all.+ meta = state.get("read_meta")+ reads = state.get("reads", {})+ if isinstance(meta, dict) and len(meta) > len(reads):+ state["read_meta"] = {k: v for k, v in meta.items() if k in reads}+ path = _session_state_path(repo_path, state.get("session_id", ""))try:- _session_state_path(repo_path).write_text(json.dumps(state), encoding="utf-8")+ first_write = not path.exists()+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(json.dumps(state), encoding="utf-8")except (OSError, TypeError, ValueError):return False+ if first_write:+ _sweep_stale_sessions(path.parent)return True@@ -204,8 +279,24 @@ def _handle_read_post(tool_output: object,cwd: str,session_id: str,+ *,+ adapter=None,) -> HookResult:- """Stale-read notice, then the skeleton replacement where it applies."""+ """Stale-read notice, then whichever Read replacement applies.++ Two surfaces can replace this Read and **at most one of them does**. The+ collapse is tried first: when it fires, the agent already holds these+ bytes, so a skeleton of them answers a question nobody asked.++ The ordering is not the whole story, and getting the rest wrong produced a+ lie. The collapse's premise is *the agent received these exact bytes*, and+ a Read that some other surface replaced delivered something else entirely.+ So a replaced Read records **no** content observation+ (:func:`_record_read_meta`), and the next Read of that file has nothing to+ compare against: no collapse claiming bytes the agent never saw, and no+ change notice fired by a digest that only differs because a skeleton was+ served in between.+ """file_path = tool_input.get("file_path") if isinstance(tool_input, dict) else Noneif not isinstance(file_path, str) or not file_path.strip():return HookResult()@@ -215,6 +306,10 @@ def _handle_read_post(rel = _relativize(file_path, repo_path)if rel is None:return HookResult()+ if adapter is None:+ from repowise.cli.agent_adapters import adapter_for++ adapter = adapter_for(None)state = _load_session_state(repo_path, session_id)notices: list[str] = []@@ -236,84 +331,241 @@ def _handle_read_post(_log_skeleton_recovery(repo_path, rel, tool_input, state, fired)+ # Read *before* this Read is recorded: both need what the previous one+ # delivered, and the line below overwrites it.+ prior_meta = state["read_meta"].get(rel)state["seq"] += 1state["reads"][rel] = state["seq"]- replacement, forgone = _skeleton_replacement(- repo_path, rel, tool_input, tool_output, state, edited_since_read=edited_since_read+ served, on_emitted = _collapse_replacement(+ repo_path,+ rel,+ tool_input,+ tool_output,+ state,+ adapter,+ prior_meta=prior_meta,+ edited_since_read=edited_since_read,+ notices=notices,+ fired=fired,)- if replacement is not None:- fired.append(("skeleton_served", replacement.text))-- persisted = _save_session_state(repo_path, state)- if not persisted:- # The "read it again and you get it whole" escape hatch is the- # `skeletonized` list, and the list is that state file. If it did not- # persist — read-only checkout, full disk — the promise in the header- # would have no ceiling: every unbounded Read would return a skeleton- # and none would return the file. No durable state, no replacement.- if replacement is not None:- replacement = None- fired = [f for f in fired if f[0] != "skeleton_served"]- # The counterfactual's gates are the same list, so they fail the same- # way: without a durable `forgone` the once-per-file gate and the- # per-session cap both reset on the next event, and the same file is- # counted again and again. That inflates the very number the- # measurement exists to state honestly, and removes the ceiling on- # what it costs. No durable state, no measurement either.- forgone = None+ # A file that just changed underneath the agent is served whole. The+ # change notice says the content below is current, and a skeleton would+ # make that half true: current, but with every body elided, at exactly the+ # moment the agent has most reason to look at one.+ changed_under_agent = any(category == "changed_since_read" for category, _ in fired)+ if served is None and not changed_under_agent:+ served, on_emitted = _skeleton_replacement(+ repo_path,+ rel,+ tool_input,+ tool_output,+ state,+ adapter,+ edited_since_read=edited_since_read,+ )+ if served is not None:+ fired.append((served.category, served.text))+ state["skeletonized"].append(rel)++ _record_read_meta(repo_path, rel, tool_input, tool_output, state, replaced=served is not None)++ if not _save_session_state(repo_path, state):+ # Every once-per-file gate here *is* that state file. If it did not+ # persist — read-only checkout, full disk — nothing bounds a+ # replacement: every qualifying Read would be replaced and none would+ # return the file, so the "read it again and you get it whole" escape+ # hatch would not exist. The forgone measurement fails the same way,+ # and worse: without a durable gate the same file is counted again and+ # again, inflating the very number it exists to state honestly.+ # No durable state, no replacement and no measurement.+ if served is not None:+ fired = [f for f in fired if f[0] != served.category]+ served = None+ on_emitted = Nonefor category, text in fired:_log_read_firing(repo_path, session_id, category, rel, text)return HookResult(context="\n".join(notices) if notices else None,- replacement=replacement.payload if replacement is not None else None,- on_emitted=_bookkeeping(repo_path, replacement, forgone),+ replacement=served.payload if served is not None else None,+ on_emitted=on_emitted,)-def _bookkeeping(repo_path: Path, replacement, forgone):- """The ledger write this Read owes, to run after the response is emitted.+def _record_read_meta(+ repo_path: Path,+ rel: str,+ tool_input: dict,+ tool_output: object,+ state: dict,+ *,+ replaced: bool = False,+) -> None:+ """Remember what this Read delivered, so the next one can be collapsed.++ *replaced* means some surface stood in for the tool result, so the bytes in+ ``tool_output`` are **not** what the agent received. Forgetting the file+ instead of recording them is the only safe answer: recording them would let+ the next Read be collapsed with "you were served the whole file" when the+ agent got a skeleton, and recording what it *did* receive would make the+ next Read look like an external change. The file simply has no observation+ this session until the agent reads it for real.++ Otherwise recorded for every Read, including one just collapsed — the+ digest is unchanged, and re-recording it is what keeps a fourth read of the+ file collapsible after the third returned the bytes.++ Stat failures are not fatal: a missing mtime costs the "written since"+ clause, never correctness, because the digest is what decides.+ """+ if replaced:+ state["read_meta"].pop(rel, None)+ return+ content = _read_content(tool_output)+ if content is None:+ return+ from .reread import content_digest++ size = mtime = -1+ try:+ stat = (repo_path / rel).stat()+ size, mtime = stat.st_size, int(stat.st_mtime_ns)+ except OSError:+ pass+ state["read_meta"][rel] = {+ "h": content_digest(content),+ "sz": size,+ "mt": mtime,+ "off": tool_input.get("offset") if isinstance(tool_input, dict) else None,+ "lim": tool_input.get("limit") if isinstance(tool_input, dict) else None,+ "seq": state["seq"],+ }+++def _read_content(tool_output: object) -> str | None:+ """The text this Read actually delivered, or None if the shape is unfamiliar.- At most one of the two is ever set. Both are deferred for the same reason:- accounting must not sit between the agent and its tool result. The- counterfactual needs this more than the saving does, not less — it takes a- write lock on a database ``repowise distill`` also writes, and it does so- on a Read that is getting nothing back for the wait.+ Only the documented Read shape counts. Guessing at an unknown envelope is+ how a collapse would compare two things that are not the same bytes."""- if replacement is not None:- return lambda: _record_skeleton_saving(repo_path, replacement)- if forgone is not None:- return lambda: _record_forgone_saving(repo_path, forgone)- return None+ if not isinstance(tool_output, dict):+ return None+ file_block = tool_output.get("file")+ if not isinstance(file_block, dict):+ return None+ content = file_block.get("content")+ return content if isinstance(content, str) else None-def _skeleton_replacement(+def _same_range(tool_input: dict, prior: dict) -> bool:+ """Whether this Read asked for the same window as the recorded one."""+ if not isinstance(tool_input, dict):+ return False+ return tool_input.get("offset") == prior.get("off") and tool_input.get(+ "limit"+ ) == prior.get("lim")+++def _collapse_replacement(repo_path: Path,rel: str,tool_input: dict,tool_output: object,state: dict,+ adapter,*,+ prior_meta: dict | None,edited_since_read: bool,+ notices: list[str],+ fired: list[tuple[str, str]],):- """``(replacement, forgone)`` for this Read — at most one set. Never raises.+ """``(served, on_emitted)`` for a re-read of unchanged bytes. Never raises.++ Three outcomes, and the ordering of the checks is the safety argument:- Ordered cheapest-gate-first so a Read that cannot qualify — which is- almost all of them — costs a handful of dict lookups and no import. The- gates themselves are documented in :mod:`read_skeleton`.+ * no previous read, or an Edit since one, or a different range → nothing;+ * same range, same digest → collapse;+ * same range, **different** digest → serve the bytes and say what changed.- The two legs share every gate above the flag on purpose: a counterfactual- computed under looser conditions than the thing it stands in for would be- measuring a different feature.+ The digest comparison is what decides, not the mtime: identical bytes are+ identical whatever the filesystem says happened to them. mtime and size are+ the corroborating signal, and their only effect is one extra clause in the+ notice when the file was written but the content did not move.+ """+ if not isinstance(prior_meta, dict) or edited_since_read:+ return None, None+ if not _same_range(tool_input, prior_meta):+ return None, None+ content = _read_content(tool_output)+ if content is None:+ return None, None+ try:+ from .reread import CONFIG_FLAG, SAVINGS_SOURCE, changed_notice, collapse, content_digest++ digest = content_digest(content)+ if digest != prior_meta.get("h"):+ # It genuinely changed, and not through an Edit of ours. The agent+ # gets the bytes; the only thing worth adding is why they moved.+ if rel not in state["changed_notified"]:+ state["changed_notified"].append(rel)+ notices.append(changed_notice(rel, prior_meta))+ fired.append(("changed_since_read", notices[-1]))+ return None, None++ touched = False+ try:+ stat = (repo_path / rel).stat()+ touched = (+ prior_meta.get("sz") not in (-1, stat.st_size)+ or prior_meta.get("mt") not in (-1, int(stat.st_mtime_ns))+ )+ except OSError:+ pass++ from .replacement import offer++ served, on_emitted = offer(+ repo_path,+ adapter,+ flag=CONFIG_FLAG,+ source=SAVINGS_SOURCE,+ tool_name="Read",+ tool_response=tool_output,+ build=lambda: collapse(rel, content, prior_meta, touched=touched),+ forgone_gate=lambda: _claim_forgone(rel, state),+ )+ except Exception:+ return None, None+ if served is not None:+ fired.append((served.category, served.text))+ return served, on_emitted+++def _skeleton_replacement(+ repo_path: Path,+ rel: str,+ tool_input: dict,+ tool_output: object,+ state: dict,+ adapter,+ *,+ edited_since_read: bool,+):+ """``(served, on_emitted)`` for this Read. Never raises.++ Only the gates that are about *this session's reading of this file* live+ here, ordered cheapest-first so a Read that cannot qualify — which is+ almost all of them — costs a handful of dict lookups and no import.+ Everything from the harness capability probe onwards is+ :func:`replacement.offer`'s, shared with the other replacing surfaces."""try:from .read_skeleton import (- as_read_output,- enabled,+ CONFIG_FLAG,+ SAVINGS_SOURCE,is_unbounded_read,skeleton_replacement,- supports_updated_output,)if not is_unbounded_read(tool_input):@@ -328,98 +580,65 @@ def _skeleton_replacement(# file is served as a skeleton from the next session on.if edited_since_read or rel in state["skeletonized"] or rel in state["forgone"]:return None, None- if not enabled(repo_path):- return None, _measure_forgone(repo_path, rel, state)- if not supports_updated_output():- return None, None- replacement = skeleton_replacement(+ from .replacement import offer++ return offer(repo_path,- rel,- min_ratio_gain=_READ_NUDGE_MAX_RATIO,- min_saved_tokens=_READ_NUDGE_MIN_SAVINGS,+ adapter,+ flag=CONFIG_FLAG,+ source=SAVINGS_SOURCE,+ tool_name="Read",+ tool_response=tool_output,+ build=lambda: skeleton_replacement(+ repo_path,+ rel,+ min_ratio_gain=_READ_NUDGE_MAX_RATIO,+ min_saved_tokens=_READ_NUDGE_MIN_SAVINGS,+ ),+ forgone_gate=lambda: _claim_forgone(rel, state),)- if replacement is not None:- # Build the wire payload here, not at emit time: if this Read's- # tool_response is not the shape Read documents, the replacement- # would be rejected downstream and the agent would get the whole- # file *while* the ledger recorded a saving. No payload, no row.- payload = as_read_output(tool_output, replacement.text)- if payload is None:- return None, None- replacement.payload = payloadexcept Exception:# Everything is inside the try, gates included. A malformed config or# a stale index must cost this one enrichment, never the stale-read# notice and the ledger row that the rest of this handler owes.return None, None- if replacement is not None:- state["skeletonized"].append(rel)- return replacement, None#: Files per session the counterfactual will measure before it stops. The real-#: path spends ~30ms and hands back thousands of tokens; this one spends the+#: path spends its time and hands back thousands of tokens; this one spends the#: same and hands back nothing but a number, on the *common* case — every-#: qualifying Read in a repo that has the feature off. A few dozen files is+#: qualifying Read in a repo that has the surface off. A few dozen files is#: plenty to characterise a repo, and the cap is what keeps a measurement from#: costing more than the thing it is measuring._MAX_FORGONE_PER_SESSION = 40-def _measure_forgone(repo_path: Path, rel: str, state: dict) -> str | None:- """Claim a measurement slot for *rel*, or None. Computes nothing.-- Runs only when the feature is off, which is the point: a repo that- declined can still see what declining costs, and item 5's own saving can- be characterised on real work before it is switched on anywhere.-- **Nothing here is on the critical path, and that is deliberate.** The real- replacement has to build its skeleton before the response, because the- skeleton *is* the response. This one hands the agent nothing at all, so- making it wait — for an index query, a file read, a skeleton build and a- write lock on a database ``repowise distill`` also writes — would be- charging every qualifying Read in an opted-out repo for a number it will- never see. All of it is deferred to :func:`_forgone_saving`; the only- thing that must happen now is claiming the slot, because the claim has to- be in the state file the caller is about to write.-- Claiming before knowing whether the file qualifies means a file that turns- out not to qualify still spends a slot. That is the conservative- direction: the cap exists to bound what measuring *costs*, and an attempt- costs whether or not it produces a row.-- **This settles A1 and nothing else.** A1 asks whether the replacement is a- net win, and the numbers are exact — the same skeleton, the same token- counts the real path would have billed. A2 asks how often the agent has to- come back for the whole file, and nothing was replaced here, so nothing- was recovered and there is no recovery rate to read. A large forgone total- is not a pass; see the caveat ``repowise saved`` prints.- """- if len(state["forgone"]) >= _MAX_FORGONE_PER_SESSION:- return None- state["forgone"].append(rel)- return rel+def _claim_forgone(rel: str, state: dict) -> bool:+ """Claim a counterfactual measurement slot for *rel*. Computes nothing.+ Runs only when a replacing surface is off, which is the point: a repo that+ declined can still see what declining costs, before switching anything on.-def _record_forgone_saving(repo_path: Path, rel: str) -> None:- """Build the skeleton nobody will see and record what it would have saved.+ The claim has to happen now, synchronously, because it belongs in the state+ file the caller is about to write; the measurement itself is deferred (see+ :func:`replacement.offer`). Claiming before knowing whether the file+ qualifies means a file that turns out not to qualify still spends a slot.+ That is the conservative direction: the cap bounds what measuring *costs*,+ and an attempt costs whether or not it produces a row.- The whole measurement, run after the response is on its way. Never raises:- a counterfactual that broke a Read would be the worst possible trade.- """- try:- from .read_skeleton import record_forgone, skeleton_replacement+ One list across both Read surfaces on purpose. A file counted as forgone by+ one of them must not be counted again by the other, or the same read would+ be advertised as two separate savings nobody made.- would_have = skeleton_replacement(- repo_path,- rel,- min_ratio_gain=_READ_NUDGE_MAX_RATIO,- min_saved_tokens=_READ_NUDGE_MIN_SAVINGS,- )- if would_have is not None:- record_forgone(repo_path, would_have)- except Exception:- return+ **This says what the replacement would have taken off the bill and nothing+ else.** It cannot say what the agent would then have had to read back,+ because nothing was replaced, so nothing was recovered. A large forgone+ total is not a verdict; see the caveat ``repowise saved`` prints.+ """+ if rel in state["forgone"] or len(state["forgone"]) >= _MAX_FORGONE_PER_SESSION:+ return False+ state["forgone"].append(rel)+ return Truedef _log_skeleton_recovery(@@ -431,16 +650,15 @@ def _log_skeleton_recovery() -> None:"""Note that the agent came back for a file we served as a skeleton.- Gate A's two numbers live here. A *ranged* return is the elision contract- working as designed; a *full* return is the replacement having been wrong- about what the agent needed, and is what the gate caps. Both are- measurement rows — neither is ever spoken about.+ A *ranged* return is the elision contract working as designed; a *full*+ return is the replacement having been wrong about what the agent needed.+ Both are measurement rows — neither is ever spoken about — and keeping them+ apart is what lets a recovery be charged back against the saving.The requested window rides in the row text on purpose. Ledger keys hashthat text, so a full recovery (stable text) dedups to one row per file- while each distinct ranged recovery gets its own — which is what Gate A's- A1 needs, since it charges every recovery back against the saving and- cannot do that from a count of files.+ while each distinct ranged recovery gets its own, which a count of files+ could not express."""if rel not in state["skeletonized"]:return@@ -471,8 +689,9 @@ def _log_read_firing("""if not session_id:return+ from repowise.cli.hook_ledger import _claim_ledger+from ._shared import _ledger_key- from .ledger import _claim_ledger_claim_ledger(repo_path,@@ -485,21 +704,6 @@ def _log_read_firing()-def _record_skeleton_saving(repo_path: Path, replacement) -> None:- """Bill a served skeleton to the savings ledger. Never fails the hook.-- After the response is decided, for the same reason :func:`_count_run` is:- the agent must not wait on bookkeeping, and a broken ledger must not cost- an enrichment that is already computed.- """- try:- from .read_skeleton import record_saving-- record_saving(repo_path, replacement)- except Exception:- return--def _read_output_line_count(tool_output: object) -> int:"""Line count of a Read result across the hook payload shapes we see."""if isinstance(tool_output, dict):diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.py b/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.pynew file mode 100644index 000000000..2dd807ebc--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.py@@ -0,0 +1,283 @@+"""The one path from "we could replace this tool result" to a ledgered saving.++Three surfaces now replace a tool result instead of talking about it: the Read+skeleton, the Grep flood digest, and the re-read collapse. They differ only in+what they build. Everything around that build is identical, and was written+twice before this module existed:++1. **Can this harness honour a replacement at all**, protocol *and* installed+ build (:func:`can_replace`).+2. **Did this repo opt in**, fail-closed (``_shared.hook_flag_enabled``).+3. **Build the wire payload from the tool's own live response**+ (:func:`wire_payload`), never from a constructed envelope.+4. **No payload, no ledger row.** ``updatedToolOutput`` is validated against+ the replaced tool's *own* output schema, and a rejected replacement fails+ invisibly: exit 0, no stderr, the agent gets the original bytes, and the+ ledger records a saving that never happened. That failure has shipped here+ before and no test caught it, because a test can only prove the hook wrote+ the field, not that the harness accepted it. So the payload is built+ *before* the row is written, and a payload we cannot build cancels the row.+5. **A saving write, or a forgone-saving write, never both** — and the forgone+ leg answers the same questions the real one did, step 4 included, or it is+ measuring a feature we could not have shipped.++:func:`offer` is those five steps in order, with the surface supplying only+step 3's candidate. A fourth replacing surface should be a builder function+and nothing else.++**One rule changed on unification, deliberately.** The Read surface used to+record a *forgone* saving for a client that could not have honoured a+replacement in the first place. The digest never did, and the digest is right:+a saving is only forgone if the flag was the thing standing in the way. A+counterfactual measured under conditions the real path could not have met is+measuring a different feature.+"""++from __future__ import annotations++from collections.abc import Callable+from typing import TYPE_CHECKING++from ._shared import hook_flag_enabled+from ._shared import record_forgone as _record_forgone+from ._shared import record_saving as _record_saving++if TYPE_CHECKING: # pragma: no cover - hot path keeps these out of the graph+ from pathlib import Path++ from repowise.cli.agent_adapters import AgentAdapter+++class Offer:+ """A candidate replacement, and everything the two ledgers need to bill it.++ A small value object rather than a tuple: the caller records a saving, logs+ an efficacy row and emits the text, and four positional elements at that+ call site would read as noise. ``__slots__`` because this is the hot path.+ """++ __slots__ = ("category", "filter_name", "key", "new_tokens", "payload", "raw_tokens", "text")++ def __init__(+ self,+ *,+ key: str,+ text: str,+ raw_tokens: int,+ new_tokens: int,+ category: str,+ filter_name: str,+ ) -> None:+ #: What was replaced, for the ledger's ``node_id`` and the savings+ #: ledger's ``command`` column: a repo-relative path, or a pattern.+ self.key = key+ #: The replacement text, exactly as the agent will receive it.+ self.text = text+ #: What the agent would have been billed, and what it is billed now.+ #: Both are chars/4 estimates and both include any header, because the+ #: header is part of what arrives.+ self.raw_tokens = raw_tokens+ self.new_tokens = new_tokens+ #: Efficacy-ledger category (``skeleton_served``, ``digest_served``,+ #: ``reread_collapsed``) and savings-ledger filter name.+ self.category = category+ self.filter_name = filter_name+ #: Filled in by :func:`offer` once it has the live ``tool_response``.+ self.payload: dict | None = None++ @property+ def saved_tokens(self) -> int:+ return max(0, self.raw_tokens - self.new_tokens)+++def can_replace(adapter: AgentAdapter) -> bool:+ """True when this harness can honour ``updatedToolOutput`` right now.++ Two questions, both the adapter's: does the protocol have a field that+ replaces a tool result, and does the *installed build* implement it. A+ surface that asked only the first would serve replacements into a client+ that drops them silently; one that asked only the second would assume+ every harness has the field. Neither is a question a Read handler should+ be answering by client name.+ """+ return bool(adapter.replaces_tool_output) and adapter.supports_updated_output()+++def _as_read_output(tool_response: dict, text: str) -> dict | None:+ """Read's shape: ``{"type", "file": {"filePath", "content", "numLines", …}}``.++ Handing Read a bare string is rejected with ``does not match Read's output+ shape``. Built from the response's own keys so unknown or future ones carry+ through untouched and only ``content`` and the line counts move.+ ``totalLines`` is deliberately left alone: it describes the file, not this+ rendering of it, and it stays true after the swap.+ """+ file_block = tool_response.get("file")+ if not isinstance(file_block, dict) or "content" not in file_block:+ return None+ lines = text.count("\n") + (0 if text.endswith("\n") else 1)+ return {**tool_response, "file": {**file_block, "content": text, "numLines": lines,+ "startLine": 1}}+++def _as_grep_output(tool_response: dict, text: str) -> dict | None:+ """Grep's content mode. ``files_with_matches`` and Glob carry no content.++ ``totalLines`` and ``numFiles`` are left alone for the same reason Read's+ ``totalLines`` is: they describe the search, not the rendering of it, and+ they stay true after the swap. The digest's header restates both anyway.+ """+ if tool_response.get("mode") != "content":+ return None+ if not isinstance(tool_response.get("content"), str):+ return None+ lines = text.count("\n") + (0 if text.endswith("\n") else 1)+ return {**tool_response, "content": text, "numLines": lines}+++#: Wire-payload builder per tool name. A tool absent from this table cannot be+#: replaced, which is the safe default: ``updatedToolOutput`` is validated+#: against the replaced tool's own schema, so guessing an envelope for an+#: unknown tool produces exactly the invisible rejection step 4 exists to stop.+_PAYLOAD_BUILDERS: dict[str, Callable[[dict, str], dict | None]] = {+ "Read": _as_read_output,+ "Grep": _as_grep_output,+}+++def wire_payload(tool_name: str, tool_response: object, text: str) -> dict | None:+ """*text* in the object shape this tool's output schema requires, or None.++ None degrades to no replacement rather than to a rejected one — the whole+ reason this is computed before the ledger row is written.+ """+ builder = _PAYLOAD_BUILDERS.get(tool_name)+ if builder is None or not isinstance(tool_response, dict):+ return None+ return builder(tool_response, text)+++def offer(+ repo_path: Path,+ adapter: AgentAdapter,+ *,+ flag: str,+ source: str,+ tool_name: str,+ tool_response: object,+ build: Callable[[], Offer | None],+ forgone_gate: Callable[[], bool] | None = None,+) -> tuple[Offer | None, Callable[[], None] | None]:+ """``(served, on_emitted)`` for one replacement opportunity. Never raises.++ *build* is the surface's own candidate builder. It is called at most once,+ and **only on the leg that needs it now**: a client that cannot be served+ and a repo that has not opted in both pay nothing for finding out. *source*+ is the savings-ledger surface tag (``hook-read`` / ``hook-search``).++ ``served`` is the offer the agent will receive, with :attr:`Offer.payload`+ filled in, or None. ``on_emitted`` is the ledger write this owes, to run+ *after* the response is on its way: accounting must not sit between the+ agent and its tool result.++ The counterfactual needs that deferral more than the saving does, not+ less, which is why the whole of it — the build included — happens there.+ The real path has to build before responding, because what it builds *is*+ the response. This one hands the agent nothing, so making it wait for a+ build and a write lock would charge every qualifying call in an opted-out+ repo for a number it will never see.++ *forgone_gate* is the surface's own permission to spend that work: a+ once-per-key or per-session cap, claimed before the deferral because the+ claim usually has to land in state the caller is about to persist. A+ surface with no such cost to bound leaves it None.++ Everything is inside the try, gates included. A malformed config or a+ stale index must cost this one enrichment and nothing else the caller owes.+ """+ try:+ if not can_replace(adapter):+ return None, None+ if not hook_flag_enabled(repo_path, flag):+ if forgone_gate is not None and not forgone_gate():+ return None, None+ return None, _forgone_writer(+ repo_path, build, source, tool_name=tool_name, tool_response=tool_response+ )+ candidate = build()+ if candidate is None:+ return None, None+ payload = wire_payload(tool_name, tool_response, candidate.text)+ if payload is None:+ return None, None+ candidate.payload = payload+ return candidate, _saving_writer(repo_path, candidate, source)+ except Exception:+ return None, None+++def _saving_writer(repo_path: Path, served: Offer, source: str) -> Callable[[], None]:+ """The savings-ledger write for a replacement the agent received."""++ def _write() -> None:+ try:+ _record_saving(+ repo_path,+ source=source,+ filter_name=served.filter_name,+ command=served.key,+ raw_tokens=served.raw_tokens,+ distilled_tokens=served.new_tokens,+ )+ except Exception:+ return++ return _write+++def _forgone_writer(+ repo_path: Path,+ build: Callable[[], Offer | None],+ source: str,+ *,+ tool_name: str,+ tool_response: object,+) -> Callable[[], None]:+ """The write for a saving this repo *would* have made, had the flag been on.++ Builds the candidate here rather than up front — see :func:`offer` — so an+ opted-out repo learns what opting in is worth without any call waiting on+ the arithmetic. A candidate that comes back None forgoes nothing and writes+ nothing.++ **Step 4 applies here too.** The counterfactual has to answer the question+ the real path would have answered, and the real path refuses a replacement+ it cannot build a legal payload for. A forgone row written without that+ check credits the surface with a saving it would never have been allowed to+ make — the same class of error as counting one a client could not honour.++ A separate table from ``savings``, never the same one: every row there is+ an event that happened and ``repowise saved`` sums them into a published+ figure. Adding a hypothetical to that sum is the precise misreading the+ caveat under the report exists to prevent.+ """++ def _write() -> None:+ try:+ candidate = build()+ if candidate is None:+ return+ if wire_payload(tool_name, tool_response, candidate.text) is None:+ return+ _record_forgone(+ repo_path,+ source=source,+ path=candidate.key,+ raw_tokens=candidate.raw_tokens,+ distilled_tokens=candidate.new_tokens,+ filter_name=candidate.filter_name,+ )+ except Exception:+ return++ return _writediff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/reread.py b/packages/cli/src/repowise/cli/commands/augment_cmd/reread.pynew file mode 100644index 000000000..6cdeeb5e2--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/reread.py@@ -0,0 +1,183 @@+"""PostToolUse Read → when the bytes are unchanged, serve a pointer, not them.++Agents re-read files they have already read, without editing them in between,+and the second copy of a file is worth nothing: it is already in the context+window a few tool calls up. This replaces that second copy with a short notice+naming the earlier read.++**Correctness here is arithmetic, not a judgment.** The agent received these+exact bytes, in this session, and they hash the same now. That is the whole+argument for the surface, and it is what separates it from an enrichment that+guesses at what the agent wanted.++The honest limit: a file can genuinely change under the agent — a+``git checkout``, a formatter, a sibling agent. That is detectable here, and+when it happens the file is served. **On any doubt, serve the file.**++What the collapse deliberately does not touch:++* **Post-edit re-reads.** A Read that follows an Edit of the same file is+ verification and needs fidelity. Excluded by construction in+ :mod:`.read_state`, never by a heuristic here.+* **A re-read at a *different* range.** Different bytes are different bytes.+ The hash settles it without anyone having to reason about ranges, and the+ notice still names the range the agent was served last time, so a partial+ earlier read is never presented as a whole-file one.+* **A file whose bytes changed.** Then the agent gets them — and gets told+ they changed, which is worth more than the bytes were (see+ :func:`changed_notice`). "It changed underneath you" is a fact the session+ otherwise has no way to learn, because no Edit of ours recorded it.++**Never twice in a row for the same file.** The premise is that the bytes are+still in the agent's context, and after a context compaction they are not: the+earlier read is gone and a notice pointing at it names something that no longer+exists. There is no way to detect that from inside a hook, so the contract is+the escape hatch instead — reading the file once more always returns the+content, exactly as the skeleton replacement promises. It costs the second and+subsequent collapses of a hot file and buys a bound on how wrong this can be.++That falls out of one rule rather than a second list: a Read that any surface+replaced records no content observation at all (``read_state._record_read_meta``),+because what the agent received was not the file. So the next Read has nothing+to compare against and is served in full — which is also what stops a collapse+claiming "you were served the whole file" to an agent that was served a+skeleton.++Not a silent truncation: the notice names the file, the tool call of the+earlier read, the range served then, and how to get the bytes back.++This is **not** the retired ``("read", "reread")`` advisory, which told the+agent it had already read the file and left it to act. This does the thing+instead of saying it, and is ledgered under a different name so the two are+never pooled.+"""++from __future__ import annotations++from typing import TYPE_CHECKING++from .replacement import Offer++if TYPE_CHECKING: # pragma: no cover - hot path keeps pathlib out of the graph+ from pathlib import Path++#: Savings-ledger identity. Same ``hook-read`` surface as the skeleton — both+#: are Reads made cheaper — with its own filter name so ``repowise saved --by+#: filter`` never pools a collapse with a skeleton.+SAVINGS_SOURCE = "hook-read"+_SAVINGS_FILTER = "read_reread"++CONFIG_FLAG = "read_reread"+++def enabled(repo_path: Path) -> bool:+ """True when this repo opted into re-read collapsing. Fails closed."""+ from ._shared import hook_flag_enabled++ return hook_flag_enabled(repo_path, CONFIG_FLAG)+++def content_digest(content: str) -> str:+ """Short hash of exactly what the agent was served for this Read.++ Hashing the *served* text rather than the file on disk is what makes the+ comparison arithmetic: two Reads whose payloads hash the same delivered the+ same bytes, whatever their offsets were and whatever happened to the file+ in between. Twelve hex is ~48 bits — collision risk across the few hundred+ file-reads of a session is nil, and the alternative to a short digest is+ keeping whole file contents in a session state file.+ """+ import hashlib++ return hashlib.sha1(content.encode("utf-8", "replace")).hexdigest()[:12]+++def _range_label(offset: object, limit: object) -> str:+ """How to name the range an earlier Read was served."""+ if offset is None and limit is None:+ return "the whole file"+ if isinstance(offset, int) and isinstance(limit, int):+ return f"lines {offset}-{offset + limit - 1}"+ if isinstance(offset, int):+ return f"from line {offset}"+ if isinstance(limit, int):+ return f"the first {limit} lines"+ return "the same range"+++def collapse(rel: str, content: str, prior: dict, *, touched: bool) -> Offer | None:+ """The notice to serve instead of *content*, or None when it saves nothing.++ *prior* is this session's recorded metadata for the previous Read of *rel*;+ the caller has already established that its digest matches this one and+ that no Edit intervened. *touched* says the file's mtime or size moved even+ though the served range did not, which is worth one clause: something wrote+ the file, and the agent may be about to be told a stale story by something+ else.++ The clause is careful about *what* is unchanged. On a ranged read the+ digest proves the served window is identical and says nothing about the+ rest of the file, so the wording claims only the window.++ **No tuned threshold.** The only gate is that the notice is smaller than+ what it replaces, which is an exact comparison rather than a floor. A file+ short enough to fail it is one where collapsing would have saved nothing.+ """+ whole_file = prior.get("off") is None and prior.get("lim") is None+ label = _range_label(prior.get("off"), prior.get("lim"))+ turn = prior.get("seq")+ when = f" (tool call {turn} of this session)" if isinstance(turn, int) and turn else ""+ if not touched:+ also = ""+ elif whole_file:+ also = (+ " The file has been written since — a timestamp changed — but the bytes "+ "are identical."+ )+ else:+ # The digest covers the served window only. Claiming the file is+ # unchanged here would be claiming something never checked.+ also = (+ " The file has been written since — a timestamp changed — and those lines "+ "are identical, but the rest of the file may not be."+ )+ text = (+ f"[repowise] Unchanged since you read it: {rel}. You were served {label}"+ f"{when} and it hashes the same now, so those bytes are already in your "+ f"context and are not repeated here.{also}\n"+ "Read it again and you get the content — this is never collapsed twice in a row."+ )+ raw_tokens = max(1, len(content) // 4)+ new_tokens = max(1, len(text) // 4)+ if new_tokens >= raw_tokens:+ return None+ return Offer(+ key=rel,+ text=text,+ raw_tokens=raw_tokens,+ new_tokens=new_tokens,+ category="reread_collapsed",+ filter_name=_SAVINGS_FILTER,+ )+++def changed_notice(rel: str, prior: dict) -> str:+ """One line for a file that changed under the agent, with no Edit of ours.++ When the bytes genuinely differ the agent gets them, and saying *why* they+ differ is something the session cannot work out for itself. The stale-read+ notice covers the case where this session did the editing; this covers a+ ``git checkout``, a formatter, or another agent, which leave no trace in+ our state at all.++ Only ever emitted for the *same* requested range as the earlier Read.+ Different offsets legitimately return different bytes, and calling that a+ change would be the judgment this surface exists to avoid making.+ """+ turn = prior.get("seq")+ when = f" at tool call {turn}" if isinstance(turn, int) and turn else " earlier"+ return (+ f"[repowise] {rel} changed on disk since you read it{when}, and not through an "+ "Edit in this session — something outside it wrote the file. The content below "+ "is current; anything you concluded from the earlier read may not be."+ )diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py b/packages/cli/src/repowise/cli/commands/augment_cmd/search.pyindex 8f5676f8c..4aadebaad 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/search.py@@ -68,9 +68,13 @@ def _handle_search_post(tool_output: object,cwd: str,session_id: str = "",- client: str | None = None,+ adapter=None,) -> HookResult:"""Decide whether to enrich a Grep/Glob result and how."""+ if adapter is None:+ from repowise.cli.agent_adapters import adapter_for++ adapter = adapter_for(None)repo_path = _find_repo_root(Path(cwd))if repo_path is None:return HookResult()@@ -90,12 +94,13 @@ def _handle_search_post(if digest:return _digest_result(repo_path,+ tool_name,tool_input,tool_output,output_text,digest,session_id,- client=client,+ adapter=adapter,)# Unparseable output (e.g. Glob path lists, or a single-file context# grep, see search_digest): fall through to triage.@@ -161,13 +166,14 @@ def _handle_search_post(def _digest_result(repo_path: Path,+ tool_name: str,tool_input: dict,tool_output: object,output_text: str,digest: str,session_id: str,*,- client: str | None,+ adapter,) -> HookResult:"""Serve the digest in place of the flood, or append it as before.@@ -178,75 +184,33 @@ def _digest_result(scored as no-action-expected for the same structural reason``skeleton_served`` is: its text leaves as ``updatedToolOutput`` and neverappears in the transcript the classifier reads.- """- replacement, forgone = _digest_replacement(- repo_path, tool_input, tool_output, output_text, digest, client=client- )- if replacement is not None:- _log_search_firing(repo_path, session_id, "digest_served", replacement.text)- from .search_digest import record_saving-- return HookResult(- replacement=replacement.payload,- on_emitted=lambda: record_saving(repo_path, replacement),- )-- _log_search_firing(repo_path, session_id, "digest", digest)- if forgone is not None:- from .search_digest import record_forgone-- return HookResult(- context=digest,- on_emitted=lambda: record_forgone(repo_path, forgone),- )- return HookResult(context=digest)--def _digest_replacement(- repo_path: Path,- tool_input: dict,- tool_output: object,- output_text: str,- digest: str,- *,- client: str | None,-):- """``(replacement, forgone)`` for this flood; at most one set. Never raises.-- The two legs share every gate but the flag, on purpose: a counterfactual- computed under looser conditions than the thing it stands in for would be- measuring a different feature. So a repo with the surface off still learns- what it would have saved, and one whose client cannot honour a replacement- is told nothing, because for that client there was nothing to forgo.+ Every gate between "there is a digest" and "the agent got it" belongs to+ :func:`replacement.offer`, which the Read surfaces use too."""- try:- from .read_skeleton import supports_updated_output- from .search_digest import (- as_grep_output,- digest_replacement,- enabled,- replaces_tool_output,- )+ from .replacement import offer+ from .search_digest import CONFIG_FLAG, SAVINGS_SOURCE, digest_replacement- if not supports_updated_output() or not replaces_tool_output(client):- return None, None- pattern = tool_input.get("pattern") if isinstance(tool_input, dict) else None- candidate = digest_replacement(+ pattern = tool_input.get("pattern") if isinstance(tool_input, dict) else None+ served, on_emitted = offer(+ repo_path,+ adapter,+ flag=CONFIG_FLAG,+ source=SAVINGS_SOURCE,+ tool_name=tool_name,+ tool_response=tool_output,+ build=lambda: digest_replacement(pattern if isinstance(pattern, str) else "", output_text, digest- )- if candidate is None:- return None, None- if not enabled(repo_path):- return None, candidate- candidate.payload = as_grep_output(tool_output, candidate.text)- if candidate.payload is None:- # Not a shape we can legally replace (files_with_matches, Glob).- # The digest still appends, and nothing was forgone: with the flag- # on we would have reached exactly here.- return None, None- return candidate, None- except Exception:- return None, None+ ),+ )+ if served is not None:+ _log_search_firing(repo_path, session_id, served.category, served.text)+ return HookResult(replacement=served.payload, on_emitted=on_emitted)++ # Nothing was replaced, so the digest rides alongside as it always did.+ # ``on_emitted`` here is the forgone-saving write, when there was one.+ _log_search_firing(repo_path, session_id, "digest", digest)+ return HookResult(context=digest, on_emitted=on_emitted)def _log_search_firing(@@ -262,8 +226,9 @@ def _log_search_firing("""if not session_id:return+ from repowise.cli.hook_ledger import _claim_ledger+from ._shared import _ledger_key- from .ledger import _claim_ledger_claim_ledger(repo_path,diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/search_digest.py b/packages/cli/src/repowise/cli/commands/augment_cmd/search_digest.pyindex 39bd0f3d7..060dfda07 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/search_digest.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/search_digest.py@@ -1,42 +1,33 @@"""PostToolUse Grep → serve the compact digest instead of the match flood.-The flood digest has always been the most expensive thing this hook says:-across the efficacy ledger it fired 37 times for ~17.6k tokens, and it *added*-every one of them **next to** the flood the agent had already been billed for.-Ranking a flood you also keep is a lens, not a saving. This module replaces the-flood with the digest instead, the same trade ``repowise distill`` makes for-shell output and :mod:`read_skeleton` now makes for Reads.+The flood digest used to be appended **next to** the flood the agent had+already been billed for. Ranking a flood you also keep is a lens, not a+saving. This module replaces the flood with the digest instead, the same trade+``repowise distill`` makes for shell output and :mod:`read_skeleton` now makes+for Reads.**Not a silent truncation.** :func:`render_search_digest` names every file, itsmatch count, two anchored line numbers per file, and an explicit``(N more files, M matches)`` tail. The agent can see what was dropped andre-run scoped to any file it names. The header says so.-What this deliberately does **not** touch, measured over real transcripts:+What this deliberately does **not** touch:-* **Single-file context greps** (``-C``/``-A``/``-B``) are the most common- flood by a distance: 20 of 22 in the sample. Claude Code renders them with- no path prefix, so :func:`group_search_matches` declines them and no digest- is built. That is the right answer for the wrong reason: the agent asked for- that context by name, and compressing it would be taking back what it- requested. Left alone on purpose.+* **Single-file context greps** (``-C``/``-A``/``-B``). Claude Code renders+ them with no path prefix, so :func:`group_search_matches` declines them and+ no digest is built. That is the right answer for the wrong reason: the agent+ asked for that context by name, and compressing it would be taking back what+ it requested. Left alone on purpose.* **``files_with_matches`` and Glob**, whose payloads carry no ``content`` atall. There is nothing to replace, and the file list is already a digest.-So the population here is genuinely multi-file floods. On those the measured-digest is 0.30 of the flood, ~1,183 tokens saved per firing, none near the-output cap.+So the population here is genuinely multi-file floods.-Gates, cheapest first (:func:`digest_replacement`):--1. **The client can honour a replacement.** Codex's hook protocol has no- output-replacement field (see :func:`replaces_tool_output`).-2. **Opted in**: ``hooks.search_digest``, written by the same init consent as- ``hooks.read_skeleton``. Fails closed.-3. **The client build supports ``updatedToolOutput``** (shared version probe).-4. **Grep content mode**, with a ``content`` string to stand in for.-5. **Worth it**: digest well under the flood, and the saving clears a floor.-6. **Under the output cap**, whole.+Gates: this surface owns only the two that are about a *digest* — worth it,+and under the output cap (:func:`digest_replacement`). The harness capability+probe, the opt-in flag, the Grep-shaped wire payload, the no-payload-no-row+rule and both ledger writes are :mod:`.replacement`'s, shared with every other+replacing surface.Operational rules are the rest of augment's: stdlib on the way in, no network,any failure degrades to returning None and the agent sees its Grep untouched.@@ -44,17 +35,19 @@ any failure degrades to returning None and the agent sees its Grep untouched.from __future__ import annotations-from pathlib import Path+from typing import TYPE_CHECKING++from ._shared import MAX_OUTPUT_CHARS+from .replacement import Offer-from ._shared import MAX_OUTPUT_CHARS, hook_flag_enabled-from ._shared import record_forgone as _record_forgone-from ._shared import record_saving as _record_saving+if TYPE_CHECKING: # pragma: no cover - hot path keeps pathlib out of the graph+ from pathlib import Path#: Savings-ledger identity, so ``repowise saved`` can name this surface.-_SAVINGS_SOURCE = "hook-search"+SAVINGS_SOURCE = "hook-search"_SAVINGS_FILTER = "search_digest"-_CONFIG_FLAG = "search_digest"+CONFIG_FLAG = "search_digest"#: The digest must be at most this fraction of the flood it replaces. Mirrors#: ``read_state._READ_NUDGE_MAX_RATIO``: below half, replacing is a saving;@@ -68,87 +61,20 @@ _MAX_RATIO = 0.5_MIN_SAVED_TOKENS = 400-class DigestReplacement:- """A digest ready to stand in for a Grep flood, and its ledger facts."""-- __slots__ = ("digest_tokens", "flood_tokens", "pattern", "payload", "text")-- def __init__(self, *, pattern: str, text: str, flood_tokens: int, digest_tokens: int) -> None:- self.pattern = pattern- self.text = text- self.flood_tokens = flood_tokens- self.digest_tokens = digest_tokens- #: Grep-shaped wire payload wrapping :attr:`text`, filled in by the- #: caller once it has the Grep's own ``tool_response`` to build from.- self.payload: dict | None = None-- @property- def saved_tokens(self) -> int:- return max(0, self.flood_tokens - self.digest_tokens)--def enabled(repo_path: Path) -> bool:"""True when this repo opted into flood replacement. Fails closed."""- return hook_flag_enabled(repo_path, _CONFIG_FLAG)---def replaces_tool_output(client: str | None) -> bool:- """True when *client*'s hook protocol can honour ``updatedToolOutput``.-- Only Claude Code can. Codex's hook contract carries a context string and- nothing else, so a replacement handed to it is dropped on the floor, and- dropped *silently*, which is the failure that let the Read surface record- ``skeleton_served`` rows for two commits while every agent saw the original- file. A capability that is checked is worth more than one that is assumed,- even while Codex registers no Grep matcher to reach this with.-- This is the narrow version of what ``AgentAdapter`` already does for the- rewrite hook via ``rewrite_permissions`` (plan item 18 folds augment into- that ABC properly). Unknown clients are treated as Claude Code, matching- every other handler here: ``--client`` is passed only by Codex's own- lifecycle hooks.- """- return client != "codex"---def as_grep_output(tool_output: object, text: str) -> dict | None:- """Wrap *text* in the object shape Claude Code requires for a Grep.+ from ._shared import hook_flag_enabled- ``updatedToolOutput`` is validated against the schema of the tool being- replaced, not against a common one. Grep's content mode is- ``{"mode": "content", "content", "numLines", "numFiles", "filenames",- "totalLines"}``, and handing it a bare string is rejected, after which the- *original* output goes to the agent while the hook still records a served- row. That failure is invisible from inside the hook (exit 0, no stderr),- which is why this builds from the payload's own ``tool_response`` rather- than constructing the envelope from scratch: unknown or future keys are- carried through untouched and only ``content`` and its line count move.+ return hook_flag_enabled(repo_path, CONFIG_FLAG)- ``totalLines`` and ``numFiles`` are deliberately left alone. They describe- the search, not the rendering of it, and they stay true after the swap. The digest's own- header restates both anyway.- Returns None when the payload is not the shape we think it is, which- degrades to no replacement rather than to a rejected one.- """- if not isinstance(tool_output, dict):- return None- if tool_output.get("mode") != "content":- # files_with_matches / Glob carry no content to stand in for.- return None- if not isinstance(tool_output.get("content"), str):- return None- lines = text.count("\n") + (0 if text.endswith("\n") else 1)- return {**tool_output, "content": text, "numLines": lines}---def digest_replacement(- pattern: str, flood_text: str, digest_body: str-) -> DigestReplacement | None:+def digest_replacement(pattern: str, flood_text: str, digest_body: str) -> Offer | None:"""A replacement for this flood, or None when it is not worth making.- *digest_body* is what :func:`search._grep_flood_digest` already rendered. This decides whether serving it in place of *flood_text* is a saving, and- never re-renders it. Callers own the cheaper gates above.+ *digest_body* is what :func:`search._grep_flood_digest` already rendered.+ This decides whether serving it in place of *flood_text* is a saving, and+ never re-renders it. The gates around this one — capability, opt-in, wire+ shape, ledgers — are :mod:`.replacement`'s."""text = _render(digest_body)if len(text) > MAX_OUTPUT_CHARS:@@ -161,11 +87,13 @@ def digest_replacement(return Noneif flood_tokens - digest_tokens < _MIN_SAVED_TOKENS:return None- return DigestReplacement(- pattern=pattern,+ return Offer(+ key=pattern,text=text,- flood_tokens=flood_tokens,- digest_tokens=digest_tokens,+ raw_tokens=flood_tokens,+ new_tokens=digest_tokens,+ category="digest_served",+ filter_name=_SAVINGS_FILTER,)@@ -178,26 +106,3 @@ def _render(digest_body: str) -> str:"the lines directly, to see any match in full.\n"f"{digest_body}")---def record_saving(repo_path: Path, replacement: DigestReplacement) -> None:- """Bill this replacement to the savings ledger so ``repowise saved`` sees it."""- _record_saving(- repo_path,- source=_SAVINGS_SOURCE,- filter_name=_SAVINGS_FILTER,- command=replacement.pattern,- raw_tokens=replacement.flood_tokens,- distilled_tokens=replacement.digest_tokens,- )---def record_forgone(repo_path: Path, replacement: DigestReplacement) -> None:- """Record a saving this repo *would* have made, had the surface been on."""- _record_forgone(- repo_path,- source=_SAVINGS_SOURCE,- path=replacement.pattern,- raw_tokens=replacement.flood_tokens,- distilled_tokens=replacement.digest_tokens,- )diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/served_reads.py b/packages/cli/src/repowise/cli/commands/augment_cmd/served_reads.pyindex 703f33201..e70513d21 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/served_reads.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/served_reads.py@@ -64,7 +64,7 @@ def _log_read_after_served(returnstart, end = windowif _served_covers(repo_path, session_id, rel, start, end):- from .ledger import _claim_ledger+ from repowise.cli.hook_ledger import _claim_ledger_claim_ledger(repo_path,diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py b/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.pyindex e4f5c0987..34ab06bd5 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/session_start.py@@ -26,7 +26,7 @@ from __future__ import annotationsimport jsonfrom pathlib import Path-from ._shared import _find_repo_root+from ._shared import _find_repo_root, emitting_buildfrom .bash_staleness import _read_in_flight_markerfrom .decision_inject import _session_decision_block@@ -60,18 +60,30 @@ def _handle_claude_session_start(cwd: str, session_id: str = "") -> str | None:def _freshness_block(repo_path: Path, last_sync: str) -> str | None:- """The live index-freshness paragraph (the original SessionStart block)."""+ """The live index-freshness paragraph (the original SessionStart block).++ The tag carries the emitting build. It costs a few tokens once per session+ and it makes the injections that follow attributable to the install that+ produced them, which a transcript otherwise cannot recover. The ledger+ stamps every row for the same reason; this is the half a transcript can+ read back.++ A sidechain has no SessionStart, so a subagent's emissions are attributable+ through the ledger's ``build`` column only. That is a real gap, stated+ rather than papered over.+ """+ tag = f"[repowise {emitting_build()}]"head = _git_head(repo_path)if head is None:return (- "[repowise] This repository has a local codebase index. Prefer the "+ f"{tag} This repository has a local codebase index. Prefer the "f"repowise MCP tools ({_CORE_TOOLS}) over raw file reads for locating ""and understanding code before you edit.")if head == last_sync:return (- f"[repowise] Codebase index is current (HEAD {head[:8]}). The MCP tools "+ f"{tag} Codebase index is current (HEAD {head[:8]}). The MCP tools "f"({_CORE_TOOLS}) serve content verified against this exact tree; prefer ""them over raw file reads for locating and understanding code before you edit.")@@ -83,7 +95,7 @@ def _freshness_block(repo_path: Path, last_sync: str) -> str | None:f"started {int(elapsed)}s ago" if isinstance(elapsed, (int, float)) else "running now")return (- f"[repowise] Index update in progress ({elapsed_str}), catching up to "+ f"{tag} Index update in progress ({elapsed_str}), catching up to "f"{head[:8]}. The MCP tools remain reliable meanwhile; a response carries ""`stale_warning` only when a file it serves actually changed.")@@ -91,7 +103,7 @@ def _freshness_block(repo_path: Path, last_sync: str) -> str | None:changed = _changed_file_count(repo_path, last_sync, head)drift = f" ({changed} files changed since)" if changed is not None else ""return (- f"[repowise] Index is behind HEAD: indexed {last_sync[:8]}, now {head[:8]}{drift}. "+ f"{tag} Index is behind HEAD: indexed {last_sync[:8]}, now {head[:8]}{drift}. "f"The MCP tools ({_CORE_TOOLS}) stay reliable: a response carries `stale_warning` ""only when a file it serves actually changed, and silence means current. ""Run `repowise update` to resync."diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/wrong_path.py b/packages/cli/src/repowise/cli/commands/augment_cmd/wrong_path.pyindex ea58d54dd..35374ecaf 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/wrong_path.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/wrong_path.py@@ -41,6 +41,9 @@ _FILE_MISSING = re.compile(r"(?:^|\n)File does not exist\.")#: has already been said and saying it again is worse than silence._ALREADY_SUGGESTED = re.compile(r"Did you mean ", re.IGNORECASE)+#: The tools whose failure can be a timed-out search rather than a bad path.+_SEARCH_TOOLS = frozenset({"Grep", "Glob"})+def _failed_path(tool_input: dict, error_text: str) -> str:"""The path the tool tried and did not find, or "" if this is not that."""@@ -160,18 +163,29 @@ def _handle_tool_failure(*,session_id: str = "",) -> HookResult:- """Point a path-not-found failure at the file the index says it meant."""+ """Answer a failed tool call from the index, where the index can.++ Two rescues share this event and neither can be mistaken for the other: a+ path that is not in this tree, and a search the tree was too slow to+ finish. They are tried in that order only because the first is cheaper.+ """if tool_name not in _PATH_TOOLS or not isinstance(tool_input, dict):return HookResult()error_text = _error_text(error)if not error_text or _ALREADY_SUGGESTED.search(error_text):return HookResult()+ repo_root = _find_repo_root(Path(cwd)) if cwd else None+ if repo_root is not None and tool_name in _SEARCH_TOOLS:+ timeout = _timeout_rescue(repo_root, tool_input, error_text, session_id)+ if timeout is not None:+ return HookResult(context=timeout)+attempted = _failed_path(tool_input, error_text)if not attempted or _is_several_paths(attempted):return HookResult()- repo_path = _find_repo_root(Path(cwd)) if cwd else None+ repo_path = repo_rootif repo_path is None:return HookResult()@@ -194,8 +208,31 @@ def _handle_tool_failure(return HookResult(context=text)+def _timeout_rescue(+ repo_path: Path, tool_input: dict, error_text: str, session_id: str+) -> str | None:+ """A timed-out search answered from the index, or None. Never raises."""+ try:+ from .glob_rescue import rescue++ text = rescue(repo_path, tool_input, error_text)+ except Exception:+ return None+ if text is None:+ return None+ _log_firing(repo_path, session_id, "glob", "timeout_rescue", text)+ return text++def _log_wrong_path_firing(repo_path: Path, session_id: str, text: str) -> None:- """Record the firing in the shared ledger; measurement only, never fatal.+ """Record a wrong-path rescue in the shared ledger."""+ _log_firing(repo_path, session_id, "wrong_path", "rescue", text)+++def _log_firing(+ repo_path: Path, session_id: str, surface: str, category: str, text: str+) -> None:+ """Record one failure-surface firing; measurement only, never fatal.Same contract as the search surfaces: keyed on a hash of the emitted textso the transcript classifier can recompute the id from what the agent saw,@@ -204,16 +241,17 @@ def _log_wrong_path_firing(repo_path: Path, session_id: str, text: str) -> None:if not session_id:returntry:+ from repowise.cli.hook_ledger import _claim_ledger+from ._shared import _ledger_key- from .ledger import _claim_ledger_claim_ledger(repo_path,session_id,- _ledger_key("wrong_path", "rescue", text),+ _ledger_key(surface, category, text),node_id="",- surface="wrong_path",- category="rescue",+ surface=surface,+ category=category,chars=len(text),)except Exception:diff --git a/packages/cli/src/repowise/cli/commands/hook_cmd.py b/packages/cli/src/repowise/cli/commands/hook_cmd.pyindex 3e202513e..fba5f5c1b 100644--- a/packages/cli/src/repowise/cli/commands/hook_cmd.py+++ b/packages/cli/src/repowise/cli/commands/hook_cmd.py@@ -483,6 +483,68 @@ def read_skeleton_status(path: str | None, workspace: bool, no_workspace: bool))+@hook_group.group("read-reread")+def read_reread_group() -> None:+ """Manage collapsed re-reads (Claude Code).++ Reading a file the session has already read, with no edit in between and+ the bytes unchanged, returns a short notice naming the earlier read+ instead of the content — which is already a few tool calls up in context.++ Nothing is guessed: the served bytes are hashed, and a file whose content+ differs is served in full, with a line saying it changed underneath you.+ Reading again always returns the content, so a compaction that dropped the+ earlier copy costs one extra Read and nothing else.++ Like `read-skeleton`, there is no hook to install. This moves the per-repo+ verdict `hooks.read_reread`.+ """+++@read_reread_group.command("install")[email protected]("path", required=False, default=None)[email protected]("--workspace", "-w", is_flag=True, default=False, help="Force workspace mode.")[email protected]("--no-workspace", is_flag=True, default=False, help="Force single-repo mode.")+def read_reread_install(path: str | None, workspace: bool, no_workspace: bool) -> None:+ """Collapse unchanged re-reads to a notice in this repo."""+ _set_hook_surface(+ path, workspace, no_workspace,+ surface="read_reread", label="Collapsed re-reads", enabled=True,+ )+++@read_reread_group.command("uninstall")[email protected]("path", required=False, default=None)[email protected]("--workspace", "-w", is_flag=True, default=False, help="Force workspace mode.")[email protected]("--no-workspace", is_flag=True, default=False, help="Force single-repo mode.")+def read_reread_uninstall(path: str | None, workspace: bool, no_workspace: bool) -> None:+ """Stop collapsing re-reads in this repo; they come back whole."""+ _set_hook_surface(+ path, workspace, no_workspace,+ surface="read_reread", label="Collapsed re-reads", enabled=False,+ )+++@read_reread_group.command("status")[email protected]("path", required=False, default=None)[email protected]("--workspace", "-w", is_flag=True, default=False, help="Force workspace mode.")[email protected]("--no-workspace", is_flag=True, default=False, help="Force single-repo mode.")+def read_reread_status(path: str | None, workspace: bool, no_workspace: bool) -> None:+ """Report whether unchanged re-reads are being collapsed."""+ from repowise.cli.commands.augment_cmd.reread import enabled as reread_enabled++ target = _hook_target(path, workspace, no_workspace)+ for repo_path in _target_repo_paths(target):+ on = reread_enabled(repo_path)+ icon = "[green]✓[/green]" if on else "[dim]✗[/dim]"+ console.print(f" {icon} collapsed re-reads: {'on' if on else 'off'} ({repo_path})")+ if not on:+ console.print(+ " [dim]`repowise saved` shows what this would have saved "+ "if it were on.[/dim]"+ )++@hook_group.group("search-digest")def search_digest_group() -> None:"""Manage digest-served searches (Claude Code).@@ -545,6 +607,82 @@ def search_digest_status(path: str | None, workspace: bool, no_workspace: bool))+def _print_rewrite(rows: list[dict]) -> None:+ """The PreToolUse rewrite hook's own table: what it wrapped and what it let by.++ Its own block rather than a row in the efficacy table above, because the+ two measure different things and the columns do not transfer. An emission+ surface is judged on whether the agent acted; this one either rewrote a+ command or did not, and the interesting number is the reason it did not.+ """+ if not rows:+ return+ from rich.table import Table++ from repowise.cli.hook_ledger import REWRITTEN++ rewritten = sum(r["calls"] for r in rows if r["outcome"] == REWRITTEN)+ total = sum(r["calls"] for r in rows)+ table = Table(title="Command rewrite hook (PreToolUse)", header_style="bold")+ table.add_column("outcome/reason")+ table.add_column("commands", justify="right")+ table.add_column("share", justify="right")+ table.add_column("sessions", justify="right")+ table.add_column("median ms", justify="right")+ for row in rows:+ share = 100.0 * row["calls"] / total if total else 0.0+ colour = "green" if row["outcome"] == REWRITTEN else "dim"+ per_call = row["total_ms"] // row["calls"] if row["calls"] else 0+ table.add_row(+ f"[{colour}]{row['outcome']}/{row['reason']}[/{colour}]",+ f"{row['calls']:,}",+ f"{share:.1f}%",+ f"{row['sessions']:,}",+ str(per_call),+ )+ console.print(table)+ pct = 100.0 * rewritten / total if total else 0.0+ console.print(+ f" [dim]{rewritten:,} of {total:,} shell commands rewritten ({pct:.1f}%). "+ "Commands run outside an indexed repo are not counted — there is no "+ "ledger there to count them in.[/dim]"+ )+++def _print_builds(builds: list[dict]) -> None:+ """Name the builds behind these firings; loud when there is more than one.++ A ledger with two live builds in it is not a curiosity: an emitter deleted+ in one install can still be firing from the other, and from a transcript+ alone that is indistinguishable from a retirement that never happened. One+ build is a one-line footnote; two is a warning, and the rows above cannot+ be read as one population until it is resolved.+ """+ if not builds:+ return+ stamped = [b for b in builds if b["build"]]+ unstamped = next((b for b in builds if not b["build"]), None)+ if unstamped is not None:+ console.print(+ f" [dim]{unstamped['firings']:,} firings predate build stamping and "+ "cannot be attributed to an install.[/dim]"+ )+ if not stamped:+ return+ if len(stamped) == 1:+ console.print(f" [dim]emitted by build {stamped[0]['build']}.[/dim]")+ return+ console.print(+ f" [yellow]{len(stamped)} builds emitted into this ledger[/yellow] — the rows "+ "above are not one population:"+ )+ for row in stamped:+ console.print(+ f" [dim]{row['build']}: {row['firings']:,} firings across "+ f"{row['sessions']:,} sessions[/dim]"+ )++@hook_group.command("stats")@click.argument("path", required=False, default=None)@click.option(@@ -585,6 +723,8 @@ def hook_stats(path: str | None, as_json: bool) -> None:runs = store.hook_run_totals()by_tool = store.hook_run_by_tool()feedback = store.decision_feedback_totals()+ builds = store.injection_builds()+ rewrites = store.rewrite_run_totals()finally:store.close()if not rows:@@ -597,7 +737,15 @@ def hook_stats(path: str | None, as_json: bool) -> None:for row in rows:row["retired"] = (row["surface"], row["category"]) in RETIRED_CATEGORIESconsole.print_json(- json_mod.dumps({"surfaces": rows, "runs": by_tool, "decision_feedback": feedback})+ json_mod.dumps(+ {+ "surfaces": rows,+ "runs": by_tool,+ "decision_feedback": feedback,+ "builds": builds,+ "rewrite": rewrites,+ }+ ))return@@ -656,6 +804,9 @@ def hook_stats(path: str | None, as_json: bool) -> None:"adoption.[/dim]")+ _print_rewrite(rewrites)+ _print_builds(builds)+# The decision surface's own verdict, which the acted-on rate above cannot# carry: an injected decision is judged by whether the session went on to# contradict it, not by whether a tool call followed it.diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py b/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.pyindex 183774585..f4b19560c 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/_interactive.py@@ -86,11 +86,14 @@ def offer_distill_rewrite_hook(# is "hooks may compact what your agent sees", not three features.# Every surface a yes covers has to be named, or it is not consent.console_obj.print(- " [dim]Also shrinks two big tool results, both reversible: a "- "whole-file Read comes back as a skeleton, and a grep matching many "- "files comes back as a per-file summary. Each names the line numbers "- "to get the rest. Toggle later: `repowise hook read-skeleton`, "- "`repowise hook search-digest`.[/dim]"+ " [dim]Also shrinks three big tool results, all reversible: a "+ "whole-file Read comes back as a skeleton, a grep matching many "+ "files comes back as a per-file summary, and re-reading a file you "+ "already read — unchanged, unedited — comes back as a one-line "+ "pointer instead of the content. Each says how to get the rest, and "+ "reading again always returns it. Toggle later: "+ "`repowise hook read-skeleton`, `repowise hook search-digest`, "+ "`repowise hook read-reread`.[/dim]")try:flag = click.confirm(" Install the Claude Code rewrite hook?", default=True)diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.pyindex 241420c89..5e3e85e44 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py@@ -526,9 +526,11 @@ def _run_generation_phase("(tests, builds, git, searches) run through `repowise distill`; a ""whole-file Read comes back as a skeleton (`hooks.read_skeleton`); a ""grep matching many files comes back as a per-file digest "- "(`hooks.search_digest`). One consent, and this flag decides all three "- "without a prompt. Default: ask when interactive, skip otherwise. In "- "workspace mode the verdict applies to every selected repo."+ "(`hooks.search_digest`); re-reading an unchanged, unedited file comes "+ "back as a pointer to the earlier read (`hooks.read_reread`). One "+ "consent, and this flag decides all four without a prompt. Default: "+ "ask when interactive, skip otherwise. In workspace mode the verdict "+ "applies to every selected repo."),)@click.option(diff --git a/packages/cli/src/repowise/cli/commands/saved_cmd.py b/packages/cli/src/repowise/cli/commands/saved_cmd.pyindex 211efa0aa..4e1657c83 100644--- a/packages/cli/src/repowise/cli/commands/saved_cmd.py+++ b/packages/cli/src/repowise/cli/commands/saved_cmd.py@@ -135,9 +135,11 @@ def saved_command(show_footer=True,caption=("Covers the 'repowise distill' command/hook path, MCP "- "counterfactual savings (mcp:<tool>), and the Read hook serving a "- "skeleton in place of a whole file (read_skeleton / hook-read); "- "group by source to split them."+ "counterfactual savings (mcp:<tool>), and the hooks that replace a "+ "tool result: a Read served as a skeleton (read_skeleton), an "+ "unchanged re-read served as a pointer (read_reread), and a search "+ "flood served as a digest (search_digest). Group by filter or "+ "source to split them."),)table.add_column(group_by.capitalize(), style="cyan", footer="[bold]TOTAL[/bold]")@@ -168,12 +170,102 @@ def saved_command()console.print(f" [dim]Ledger: {db_path}[/dim]")_print_mcp_truncation_line(db_path, since_ts)+ _print_net(start, saved, since_ts)_print_missed_summary_line(start, missed_days)_print_reread_summary_line(start, missed_days)_print_forgone_read_skeleton_line(start, db_path, since_ts)console.print()+def _print_net(start: Path, saved_tokens: int, since_ts: float | None = None) -> None:+ """Gross saved, gross spent, net — and the net may be negative.++ This is the only line here that can answer "is this worth mounting". The+ table above counts credits and structurally cannot report a loss, which+ made every figure it printed an advertisement rather than a measurement.++ Three honesty rules are load-bearing.++ **The two sides have to cover the same window.** The debit side cannot be+ windowed: the resident prefix is a property of the file as it is now, not+ of any date range. So under ``--since`` this prints nothing at all rather+ than setting a windowed credit against an all-time cost, which produced a+ confident negative that was an artifact of the window and nothing else.++ **Sessions that predate the debit ledger have no cost rows**, so a net+ across them credits savings whose cost was never recorded.++ **The debit total is a lower bound**: some real costs are not computable+ from local data. They are named rather than dropped, so the net reads as+ "no better than this".+ """+ if since_ts is not None:+ console.print(+ "\n [dim]No net under --since: savings can be windowed by date and the "+ "resident cost of the CLAUDE.md block cannot, so the two would not "+ "describe the same period. Run without --since for the net.[/dim]"+ )+ return+ try:+ from repowise.cli.helpers import find_repowise_repo_root+ from repowise.core.sessions.efficacy import advisory_cost+ from repowise.core.sessions.footprint import measure+ from repowise.core.sessions.staging import SessionStagingStore, default_store_path++ repo_root = find_repowise_repo_root(start) or start+ advisory_chars = advisory_firings = 0+ if default_store_path(repo_root).exists():+ store = SessionStagingStore.open_default(repo_root)+ try:+ advisory_chars, advisory_firings = advisory_cost(store.efficacy_rows())+ finally:+ store.close()+ footprint = measure(+ repo_root,+ advisory_chars=advisory_chars,+ advisory_firings=advisory_firings,+ )+ except Exception:+ return+ if not footprint.debits:+ return++ amp = footprint.amplification+ multiplier = amp.ratio if amp.known else 1.0+ billed_saved = int(saved_tokens * multiplier)+ net = billed_saved - footprint.billed_total+ colour = "green" if net > 0 else "red"++ console.print()+ console.print(" [bold]Net[/bold] [dim](billed tokens, after amplification)[/dim]")+ console.print(f" gross saved [green]{billed_saved:>12,}[/green]")+ console.print(f" gross spent [yellow]{footprint.billed_total:>12,}[/yellow]")+ console.print(f" net [{colour}]{net:>12,}[/{colour}]")+ for debit in footprint.debits:+ console.print(+ f" [dim]{debit.label}: {debit.billed_tokens:,} "+ f"({debit.raw_tokens:,} raw — {debit.detail})[/dim]"+ )+ if amp.known:+ console.print(+ f" [dim]amplification {amp.ratio:.1f}x, measured over {amp.sessions} "+ f"sessions at a median {amp.calls} API calls each. It is a function of "+ "session length, not a constant.[/dim]"+ )+ else:+ console.print(+ " [dim]no cache figures on disk, so nothing was amplified and "+ "both sides are raw tokens.[/dim]"+ )+ for missing in footprint.unmeasured:+ console.print(f" [dim]not counted as a cost: {missing}.[/dim]")+ console.print(+ " [dim]Savings recorded before the cost side existed have no debit "+ "rows behind them, so this net is a ceiling on how good the trade is, "+ "never a floor.[/dim]"+ )++#: One entry per replacing hook surface: the savings-ledger source that tags#: its forgone rows, how to read its on/off verdict, and how to name it. The#: source filter is load-bearing: every surface writes into the one@@ -194,6 +286,13 @@ _FORGONE_SURFACES = ("search","repowise hook search-digest install",),+ (+ "hook-read",+ "read_reread",+ "collapsed re-reads",+ "re-read",+ "repowise hook read-reread install",+ ),)@@ -262,9 +361,17 @@ def _print_forgone_read_skeleton_line(start: Path, db_path: Path, since_ts: floatry:con = sqlite3.connect(f"file:{db_path.as_posix()}?mode=ro", uri=True, timeout=2)try:- where, params = " WHERE source = ?", (source,)+ # Filtered on the surface's *filter*, not its source: the+ # skeleton and the re-read collapse share ``hook-read``, so a+ # source-only sum would report each one's counterfactual twice.+ # Rows predating the ``filter`` column carry '' and land under+ # the surface that was the only one writing when they were made.+ legacy = " OR (filter = '' AND source = ?)" if flag == "read_skeleton" else ""+ params: tuple = (flag, source) if legacy else (flag,)+ where = f" WHERE (filter = ?{legacy})"if since_ts is not None:- where, params = " WHERE source = ? AND created_at >= ?", (source, since_ts)+ where += " AND created_at >= ?"+ params = (*params, since_ts)items, raw, distilled = con.execute("SELECT COUNT(DISTINCT path), COALESCE(SUM(raw_tokens),0), "f"COALESCE(SUM(distilled_tokens),0) FROM forgone_savings{where}",diff --git a/packages/cli/src/repowise/cli/hook_ledger.py b/packages/cli/src/repowise/cli/hook_ledger.pynew file mode 100644index 000000000..592e8cd36--- /dev/null+++ b/packages/cli/src/repowise/cli/hook_ledger.py@@ -0,0 +1,465 @@+"""The write side of the ``sessions.db`` hook ledger, shared by *both* hooks.++Every hook surface records what it showed and what it cost here, so the+update-time miner and ``repowise hook stats`` judge one corpus rather than one+per surface. These helpers grew inside :mod:`decision_inject`, which owns only+the *decision* surface, and then moved to ``augment_cmd/ledger.py``, which+could only ever serve the PostToolUse hook.++**It lives at the top of ``repowise.cli`` because the PreToolUse rewrite hook+needs it too, and cannot reach into ``augment_cmd``.** That package's+``__init__`` imports click and every submodule; paying it on every Bash call to+write one counter row would cost far more than the row is worth. Hoisting the+module was the alternative to a second copy of the connect/migrate/upsert+logic, and a second copy is how the two would drift.++The rewrite hook is here at all because its firing rate is not observable any+other way: an ``updatedInput`` rewrite never appears in a transcript, so a+transcript scan can only find hand-typed ``repowise distill`` invocations,+which say nothing about the hook. It sits on the shell tools, the busiest+surface either hook has, and until now wrote nothing at all.++Import it lazily, inside the function that writes, the way every caller here+does. Two reasons and both are load-bearing: a hook invocation that says+nothing must not pay for a database module it never opens, and a module-scope+``from .hook_ledger import x`` binds a copy that a test patching+``hook_ledger.x`` will not reach — so a spy would silently miss whichever+surfaces bound early.++Three constraints shape everything here, and none is negotiable:++* **No ``repowise.core``.** The hook budget is 155 ms and importing the ORM+ costs more than that on its own, so this is raw stdlib :mod:`sqlite3` and the+ ``injections`` migration is duplicated verbatim from+ ``core.sessions.staging`` rather than imported.+ ``tests/unit/cli/test_augment_hook_perf.py`` asserts on the import graph.+* **Nothing at module scope but the clock.** ``sqlite3`` is deferred into the+ functions that need it, because ``rewrite_hook`` imports this module at *its*+ module scope — see :data:`_T0` for why it has to — and a command that bails+ on shape must not pay for a database it never opens. Paths are handled with+ :mod:`os.path` throughout for the same reason.+ ``tests/unit/cli/test_augment_hook_perf.py`` asserts the deferral holds.+* **Silence over failure.** A hook must never surface an error into the agent's+ transcript, so every function here swallows :class:`sqlite3.Error` and the+ claim helpers fail *closed* — an unusable sidecar degrades to saying nothing,+ never to saying it twice.+"""++from __future__ import annotations++import os+import time+from typing import TYPE_CHECKING++if TYPE_CHECKING: # pragma: no cover - deferred on the hot path, see above+ import sqlite3+ from pathlib import Path++#: Process start, near enough. Both hook entry points import this module at+#: their own module scope so this is captured before any work happens; a lazy+#: import inside the writer would stamp every firing with ~0 ms.+_T0 = time.perf_counter()+++def _elapsed_ms() -> int:+ """Milliseconds of in-process hook work so far (see :data:`_T0`)."""+ return int((time.perf_counter() - _T0) * 1000)+++#: Memo for :func:`emitting_build`. One hook process emits at most a handful of+#: rows and every one of them wants the same answer.+_BUILD: str | None = None+++def emitting_build() -> str:+ """Which repowise build produced this emission: ``"<version>+<install>"``.++ Every ledger row carries this, and the SessionStart block prints it,+ because without it an emission cannot be attributed to the code that+ produced it. A retired emitter that keeps reaching agents is+ indistinguishable from a retirement that never shipped, and an unstamped+ ledger cannot tell an adoption rate apart from two builds averaged+ together.++ A version alone is not enough: the common case is two installs of the+ *same* release, an editable checkout and a pip-installed console script,+ disagreeing about what has been retired. So the second half is an install+ identity — eight hex of the directory this module was imported from. It+ says which install spoke, never who or where: the digest is one-way and+ the path never leaves the machine.+ """+ global _BUILD+ if _BUILD is None:+ import hashlib++ from repowise.cli import __version__++ # The directory rather than ``__file__``: two modules in one install+ # must not read as two installs.+ install = hashlib.sha1(os.path.dirname(__file__).encode("utf-8", "replace")).hexdigest()+ _BUILD = f"{__version__}+{install[:8]}"+ return _BUILD++_INJECTIONS_TABLE_SQL = (+ "CREATE TABLE IF NOT EXISTS injections ("+ "session_id TEXT NOT NULL, decision_id TEXT NOT NULL, "+ "node_id TEXT NOT NULL DEFAULT '', shown_at REAL NOT NULL, "+ "evaluated INTEGER NOT NULL DEFAULT 0, "+ "surface TEXT NOT NULL DEFAULT '', "+ "category TEXT NOT NULL DEFAULT '', "+ "chars INTEGER NOT NULL DEFAULT 0, "+ "duration_ms INTEGER NOT NULL DEFAULT 0, "+ "acted INTEGER NOT NULL DEFAULT 0, "+ "verdict TEXT NOT NULL DEFAULT '', "+ "build TEXT NOT NULL DEFAULT '', "+ "PRIMARY KEY (session_id, decision_id))"+)++_HOOK_RUNS_TABLE_SQL = (+ "CREATE TABLE IF NOT EXISTS hook_runs ("+ "session_id TEXT NOT NULL, event TEXT NOT NULL, tool TEXT NOT NULL, "+ "calls INTEGER NOT NULL DEFAULT 0, emitted INTEGER NOT NULL DEFAULT 0, "+ "total_ms INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (session_id, event, tool))"+)++#: The rewrite hook's own counter, aggregated rather than one row per firing.+#:+#: It cannot use ``injections``: that table is keyed on a hash of the emitted+#: text and INSERT-OR-IGNOREs, which is right for a notice that should be said+#: once and wrong for a counter — every ``bailed``/``shape`` would collapse into+#: a single row per session and the distribution this exists to measure would+#: read as "1". So this upserts a count, the same shape ``hook_runs`` already+#: uses, on the one axis that matters: **why** a command was or was not+#: rewritten. ``repowise hook stats`` renders it as the ``rewrite`` surface.+_REWRITE_RUNS_TABLE_SQL = (+ "CREATE TABLE IF NOT EXISTS rewrite_runs ("+ "session_id TEXT NOT NULL, outcome TEXT NOT NULL, reason TEXT NOT NULL, "+ "calls INTEGER NOT NULL DEFAULT 0, total_ms INTEGER NOT NULL DEFAULT 0, "+ "build TEXT NOT NULL DEFAULT '', "+ "PRIMARY KEY (session_id, outcome, reason))"+)++#: Mirror of core.sessions.staging.INJECTIONS_LEDGER_COLUMNS — the hook path+#: must not import repowise.core, so the migration is duplicated verbatim.+_LEDGER_COLUMNS = (+ ("surface", "TEXT NOT NULL DEFAULT ''"),+ ("category", "TEXT NOT NULL DEFAULT ''"),+ ("chars", "INTEGER NOT NULL DEFAULT 0"),+ ("duration_ms", "INTEGER NOT NULL DEFAULT 0"),+ ("acted", "INTEGER NOT NULL DEFAULT 0"),+ ("verdict", "TEXT NOT NULL DEFAULT ''"),+ ("build", "TEXT NOT NULL DEFAULT ''"),+)++#: One ledger connection per hook process, opened lazily. A single invocation+#: can write several rows (two notices plus the run counter), and connect ++#: WAL pragma + the CREATE/PRAGMA/ALTER migration is the expensive part, not+#: the INSERT. The process is short-lived and single-threaded, so caching is+#: safe; every writer commits, and process exit closes the handle.+#: Keyed by repo path, not global: a hook process only ever sees one repo, but+#: the test suite drives many through one interpreter, and a cache that+#: ignored the path would hand the second repo the first one's database.+#: Keyed on the *string* path: callers pass ``Path`` (augment) and ``str``+#: (the rewrite hook, which keeps pathlib off its hot path), and two spellings+#: of one repo must not open two connections.+_CONN: dict[str, sqlite3.Connection | None] = {}+++def _open_injections(repo_path: Path | str) -> sqlite3.Connection | None:+ """The shared ledger connection, migrated and ready. None if unusable.++ Callers must NOT close the returned connection — see :data:`_CONN`.+ """+ key = str(repo_path)+ if key in _CONN:+ return _CONN[key]+ import sqlite3++ db_dir = os.path.join(key, ".repowise", "sessions")+ db_path = os.path.join(db_dir, "sessions.db")+ try:+ os.makedirs(db_dir, exist_ok=True)+ conn = sqlite3.connect(db_path, timeout=1)+ conn.execute("PRAGMA journal_mode=WAL")+ conn.execute("PRAGMA busy_timeout=1000")+ conn.execute(_INJECTIONS_TABLE_SQL)+ conn.execute(_HOOK_RUNS_TABLE_SQL)+ conn.execute(_REWRITE_RUNS_TABLE_SQL)+ existing = {row[1] for row in conn.execute("PRAGMA table_info(injections)")}+ for name, decl in _LEDGER_COLUMNS:+ if name not in existing:+ conn.execute(f"ALTER TABLE injections ADD COLUMN {name} {decl}")+ _CONN[key] = conn+ return conn+ except (sqlite3.Error, OSError):+ _CONN[key] = None+ return None+++def _record_hook_run(+ repo_path: Path, session_id: str, event: str, tool: str, *, emitted: bool+) -> None:+ """Count one hook invocation and what it cost. Best-effort, never raises.++ Every invocation lands here, including the large majority that return+ nothing: the matcher covers Read/Edit/Write/Grep/Glob/Bash/PowerShell and+ the repowise MCP tools, and a silent run still pays the import cost. The+ harness only writes a transcript record for hooks that *emitted*, so+ without this counter the silent invocations — the bulk of the bill — are+ invisible. Aggregated per (session, event, tool) rather than one row per+ call, so the table stays small and the write stays a single upsert.+ """+ if not session_id:+ return+ conn = _open_injections(repo_path)+ if conn is None:+ return+ import sqlite3++ try:+ conn.execute(+ "INSERT INTO hook_runs (session_id, event, tool, calls, emitted, total_ms) "+ "VALUES (?, ?, ?, 1, ?, ?) "+ "ON CONFLICT(session_id, event, tool) DO UPDATE SET "+ "calls = calls + 1, emitted = emitted + excluded.emitted, "+ "total_ms = total_ms + excluded.total_ms",+ (session_id, event, tool, 1 if emitted else 0, _elapsed_ms()),+ )+ conn.commit()+ except sqlite3.Error:+ pass+++def _record_injections(+ repo_path: Path,+ session_id: str,+ decision_ids: list[str],+ *,+ node_id: str,+ chars: int = 0,+) -> None:+ """Log shown decisions in the sessions.db sidecar; best-effort, never raises.++ The update-time miner reads these rows to judge whether injected guidance+ was followed or contradicted (usage feedback v1). Written with raw stdlib+ sqlite3 so the hook path never imports repowise.core.++ *chars* is the whole block's size, divided across the decisions it carried:+ the cost model sums this column, and a block recorded at zero is one the+ net treats as free. It is the largest single thing this hook emits, so+ getting that wrong understates the debit side more than everything else+ combined. Rounding is upward on the first row rather than lost.+ """+ if not session_id or not decision_ids:+ return+ conn = _open_injections(repo_path)+ if conn is None:+ return+ import sqlite3++ try:+ now = time.time()+ elapsed = _elapsed_ms()+ build = emitting_build()+ share, remainder = divmod(max(0, chars), len(decision_ids))+ conn.executemany(+ "INSERT OR IGNORE INTO injections "+ "(session_id, decision_id, node_id, shown_at, surface, category, duration_ms, "+ "build, chars) VALUES (?, ?, ?, ?, 'decision', 'session_start', ?, ?, ?)",+ [+ (session_id, did, node_id, now, elapsed, build, share + (remainder if i == 0 else 0))+ for i, did in enumerate(decision_ids)+ ],+ )+ conn.commit()+ except sqlite3.Error:+ pass+++def _claim_ledger(+ repo_path: Path,+ session_id: str,+ key: str,+ *,+ node_id: str,+ surface: str,+ category: str,+ chars: int,+) -> tuple[bool, int]:+ """Atomically claim one non-decision ledger emission.++ Generic twin of :func:`_claim_injection` for the read/search enrichment+ surfaces: *key* replaces the decision id in the primary key, so INSERT OR+ IGNORE is the once-per-session-per-key gate. Returns ``(claimed,+ surface_injection_count)`` where the count covers only rows that actually+ carried text (``chars > 0``) on *surface* — pure measurement rows must not+ eat into an injection cap. Fail-closed: any error reports unclaimed.++ ``duration_ms`` records what this firing has cost so far (see+ :func:`_elapsed_ms`); it is what ``repowise hook stats`` reports until a+ transcript pass replaces it with the harness-measured total.+ """+ conn = _open_injections(repo_path)+ if conn is None:+ return False, 0+ import sqlite3++ try:+ cur = conn.execute(+ "INSERT OR IGNORE INTO injections "+ "(session_id, decision_id, node_id, shown_at, surface, category, chars, "+ "duration_ms, build) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",+ (+ session_id,+ key,+ node_id,+ time.time(),+ surface,+ category,+ chars,+ _elapsed_ms(),+ emitting_build(),+ ),+ )+ claimed = cur.rowcount > 0+ count = conn.execute(+ "SELECT COUNT(*) FROM injections WHERE session_id = ? AND surface = ? AND chars > 0",+ (session_id, surface),+ ).fetchone()[0]+ conn.commit()+ return claimed, int(count)+ except sqlite3.Error:+ return False, 0+++def _claim_injection(+ repo_path: Path, session_id: str, decision_id: str, node_id: str, *, chars: int = 0+) -> tuple[bool, int]:+ """Atomically claim the right to show one decision this session.++ Returns ``(claimed, edit_notice_count)``. The primary key makes the+ INSERT OR IGNORE the once-per-session-per-decision gate, immune to the+ state-file races two concurrent hook processes produce; the count backs+ the strict per-session notice cap. Fail-closed: any error reports+ unclaimed, so a sidecar glitch degrades to silence, never to spam.+ """+ conn = _open_injections(repo_path)+ if conn is None:+ return False, 0+ import sqlite3++ try:+ cur = conn.execute(+ "INSERT OR IGNORE INTO injections "+ "(session_id, decision_id, node_id, shown_at, surface, category, duration_ms, "+ "build, chars) VALUES (?, ?, ?, ?, 'decision', 'edit_notice', ?, ?, ?)",+ (+ session_id,+ decision_id,+ node_id,+ time.time(),+ _elapsed_ms(),+ emitting_build(),+ chars,+ ),+ )+ claimed = cur.rowcount > 0+ # Surface-scoped: read/search enrichment rows also carry a node_id and+ # must not eat into the edit-notice cap.+ count = conn.execute(+ "SELECT COUNT(*) FROM injections WHERE session_id = ? AND node_id != '' "+ "AND surface IN ('', 'decision')",+ (session_id,),+ ).fetchone()[0]+ conn.commit()+ return claimed, int(count)+ except sqlite3.Error:+ return False, 0+++#: What a rewrite-hook invocation did. ``rewritten`` carries the distill family+#: as its reason; ``bailed`` carries why, which is the distribution the plan+#: asked for and which was previously guesswork.+REWRITTEN = "rewritten"+BAILED = "bailed"+++def _open_rewrite_runs(repo_path: str):+ """A connection carrying only what the rewrite counter needs.++ The PreToolUse hook fires on every shell command, so its write has to be+ the smallest one that is still correct: one CREATE IF NOT EXISTS against a+ table nothing else migrates, and no ``injections`` work at all. Shares+ :data:`_CONN` keyed on the same path — a process is either the rewrite hook+ or the augment hook, never both, so the two openers cannot race.++ ``None`` whenever the sidecar is unusable; a counter is never worth an+ error in the agent's transcript.+ """+ key = str(repo_path)+ if key in _CONN:+ return _CONN[key]+ import sqlite3++ db_dir = os.path.join(key, ".repowise", "sessions")+ try:+ os.makedirs(db_dir, exist_ok=True)+ conn = sqlite3.connect(os.path.join(db_dir, "sessions.db"), timeout=1)+ conn.execute("PRAGMA busy_timeout=1000")+ conn.execute(_REWRITE_RUNS_TABLE_SQL)+ _CONN[key] = conn+ return conn+ except (sqlite3.Error, OSError):+ _CONN[key] = None+ return None+++def record_rewrite(+ repo_path: str, session_id: str, *, outcome: str, reason: str, elapsed_ms: int | None = None+) -> None:+ """Count one ``repowise-rewrite`` decision. Best-effort, never raises.++ Called after the response is on stdout, for the same reason every other+ write here is deferred: the agent must not wait on accounting.++ An upsert, not an INSERT-OR-IGNORE — see :data:`_REWRITE_RUNS_TABLE_SQL`.+ The point is *how many* commands bailed on shape versus on family, and a+ once-per-session row would answer "one of each".++ ``repo_path`` is a plain string because the caller resolved it with+ :mod:`os.path`; the rewrite hook keeps ``pathlib`` off its hot path.+ """+ if not session_id or not repo_path:+ return+ # Deliberately *not* :func:`_open_injections`. That opener migrates the+ # ``injections`` table — three CREATEs, a PRAGMA table_info and an ALTER+ # loop — none of which this writer touches, and it would pay for all of it+ # on every shell command an agent runs. Measured on this machine, the lean+ # path below is roughly half the cost of the shared one.+ conn = _open_rewrite_runs(repo_path)+ if conn is None:+ return+ import sqlite3++ try:+ conn.execute(+ "INSERT INTO rewrite_runs (session_id, outcome, reason, calls, total_ms, build) "+ "VALUES (?, ?, ?, 1, ?, ?) "+ "ON CONFLICT(session_id, outcome, reason) DO UPDATE SET "+ # ``build`` moves to whichever install wrote last. An upgrade+ # mid-session would otherwise leave the first build owning the row+ # and pool two builds' calls under it, which is the averaging the+ # column exists to make visible.+ "calls = calls + 1, total_ms = total_ms + excluded.total_ms, "+ "build = excluded.build",+ (+ session_id,+ outcome,+ reason,+ _elapsed_ms() if elapsed_ms is None else elapsed_ms,+ emitting_build(),+ ),+ )+ conn.commit()+ except sqlite3.Error:+ passdiff --git a/packages/cli/src/repowise/cli/rewrite_hook.py b/packages/cli/src/repowise/cli/rewrite_hook.pyindex 9fddb31e4..ac9a07509 100644--- a/packages/cli/src/repowise/cli/rewrite_hook.py+++ b/packages/cli/src/repowise/cli/rewrite_hook.py@@ -60,6 +60,12 @@ import tempfile# import at module scope. (No pathlib: it costs double-digit milliseconds# of interpreter startup, which this hook pays on every Bash call.)from repowise.cli.agent_adapters.base import RewriteResult++# Free at module scope, and it has to be here rather than lazy: this module's+# import is where the ledger's clock starts, so a firing's recorded cost covers+# the whole invocation. Its own scope is ``os`` and ``time`` — sqlite3 is+# deferred into the writer, so a command that bails never opens a database.+from repowise.cli.hook_ledger import BAILED, REWRITTENfrom repowise.cli.shell_lexer import (SAFE_FINAL_TOOLS,analyze_pipeline,@@ -563,6 +569,23 @@ _PS_ALIAS_TOKENS = frozenset()+#: Why a command was not rewritten. One of these lands in the ledger for every+#: shell command the hook sees, so the shape of what passes through stops being+#: guesswork: an ``updatedInput`` rewrite is invisible in a transcript, and so+#: is a bail, which means the hook's whole population was previously unmeasured.+#:+#: ``no_repo`` is recorded for completeness and can never actually be written —+#: a command outside a repowise repo has no ledger to write to. Naming it is+#: cheaper than leaving a reader to wonder where those went.+BAIL_SHAPE = "shape" # shell syntax the wrapper cannot preserve+BAIL_UNRECOGNIZED = "unrecognized" # not a command family we distill+BAIL_PS_ALIAS = "ps_alias" # PowerShell alias that would not survive a wrap+BAIL_NO_REPO = "no_repo" # cwd is not inside a repowise repo+BAIL_DISABLED = "disabled" # this repo turned command rewriting off+BAIL_FAMILY_OFF = "family_off" # this family specifically is off+BAIL_PERMISSION = "permission" # agent cannot honour the decided posture++def decide(command: str, cwd: str, shell: str = "posix", source: str | None = None) -> RewriteResult | None:@@ -571,42 +594,55 @@ def decide(*source* overrides the ledger tag for agents with their own surface(``hook-codex``); by default it derives from the shell dialect."""+ return _decide(command, cwd, shell, source)[0]+++def _decide(+ command: str, cwd: str, shell: str = "posix", source: str | None = None+) -> tuple[RewriteResult | None, str, str | None]:+ """:func:`decide`, plus why it said no and which repo it was asked about.++ Split out rather than folded in because the hook has to *count* itself: the+ outcome and the repo root are what a ledger row needs, and the public+ ``decide`` contract is a result or None. On a rewrite the reason is the+ distill family, so one column carries both distributions.+ """split = _split_safe_tail(command) if command else Nonechain: tuple[str, ...] = ()if split is not None:head_command, needs_inner_shell = splitfamily = _classify_head(head_command)if family is None:- return None+ return None, BAIL_UNRECOGNIZED, _find_repo_root(cwd)if shell == "powershell":first = _normalize(head_command).split(None, 1)[0]if first in _PS_ALIAS_TOKENS:- return None+ return None, BAIL_PS_ALIAS, _find_repo_root(cwd)elif command and shell != "powershell":# A chain is POSIX shell syntax by construction (`&&`, `;`, `|`), so# it is only ever offered to the POSIX dialect.chain = _chain_families(command) or ()if not chain:- return None+ return None, BAIL_SHAPE, _find_repo_root(cwd)family, needs_inner_shell = chain[0], Trueelse:- return None+ return None, BAIL_SHAPE, _find_repo_root(cwd)# Only act inside repos that opted into repowise; the hook is installed# globally, but a repo without .repowise/ gets untouched commands.repo_root = _find_repo_root(cwd)if repo_root is None:- return None+ return None, BAIL_NO_REPO, Noneenabled, permission, families = _load_commands_config(repo_root)if not enabled:- return None+ return None, BAIL_DISABLED, repo_root# Every family the command touches has to be allowed, not just the one# that names the rewrite: otherwise `git_diff: off` would be bypassable# by chaining a git diff behind anything still on.for touched in chain or (family,):if families.get(touched) in _OFF_VALUES:- return None+ return None, BAIL_FAMILY_OFF, repo_rootfamily_setting = families.get(family)if family_setting in _VALID_PERMISSIONS:permission = family_setting@@ -621,13 +657,19 @@ def decide(# inner shell reads the token back byte for byte; `$` already bailed, so# nothing in it re-expands.wrapped = _single_quote(command.strip()) if needs_inner_shell else command.strip()- return RewriteResult(- command=f"repowise distill --source {source} {wrapped}",- permission=permission,- reason=(- f"repowise distill: compact {family} rendering; full output stays "- f"recoverable via `repowise expand <ref>`"+ # The reason on a rewrite is the family: one ledger column then carries+ # both distributions, what we rewrite and what we decline.+ return (+ RewriteResult(+ command=f"repowise distill --source {source} {wrapped}",+ permission=permission,+ reason=(+ f"repowise distill: compact {family} rendering; full output stays "+ f"recoverable via `repowise expand <ref>`"+ ),),+ family,+ repo_root,)@@ -637,20 +679,21 @@ def _select_adapter(argv: list[str]):Each agent's hook config registers its own flavor (Codex hooks run``repowise-rewrite --agent codex``) — the payloads are near-identicalJSON, so argv is the only reliable discriminator.++ Resolution goes through the shared registry rather than a name test here.+ This used to be its own ``if agent == "codex"`` ladder, which meant adding+ a harness was a registration *and* an edit in this file — the thing the+ registry exists to stop."""+ from repowise.cli.agent_adapters import adapter_for+agent = ""for i, arg in enumerate(argv):if arg == "--agent" and i + 1 < len(argv):agent = argv[i + 1]elif arg.startswith("--agent="):agent = arg.split("=", 1)[1]- if agent == "codex":- from repowise.cli.agent_adapters.codex import CodexAdapter-- return CodexAdapter()- from repowise.cli.agent_adapters.claude_code import ClaudeCodeAdapter-- return ClaudeCodeAdapter()+ return adapter_for(agent)def main() -> None:@@ -658,14 +701,22 @@ def main() -> None:adapter = _select_adapter(sys.argv[1:])request = adapter.parse_hook_payload(sys.stdin.read())if request is not None:- source = "hook-codex" if adapter.name == "codex" else None- result = decide(request.command, request.cwd, request.shell, source=source)+ source = adapter.savings_source+ result, reason, repo_root = _decide(+ request.command, request.cwd, request.shell, source=source+ )+ outcome = BAILED# An agent that can't honor the decided posture gets a# passthrough, never a silently escalated rewrite (Codex has no# ask-with-mutation — only families set to `allow` rewrite).- if result is not None and result.permission in adapter.rewrite_permissions:- sys.stdout.write(adapter.render_response(result))- sys.stdout.flush()+ if result is not None:+ if result.permission in adapter.rewrite_permissions:+ sys.stdout.write(adapter.render_response(result))+ sys.stdout.flush()+ outcome = REWRITTEN+ else:+ reason = BAIL_PERMISSION+ _count_decision(repo_root, request.session_id, outcome, reason)except (SystemExit, KeyboardInterrupt):raiseexcept BaseException:@@ -674,5 +725,28 @@ def main() -> None:sys.exit(0)+def _count_decision(repo_root: str | None, session_id: str, outcome: str, reason: str) -> None:+ """Record what this invocation decided. After stdout, and never fatal.++ Deferred past the response for the reason every ledger write here is: the+ agent must not wait on accounting. Skipped entirely outside a repowise repo+ — there is no sidecar to write to — and skipped when the harness offered no+ session id, because a row nothing can be attributed to is not worth the+ write.++ This is the only instrument this hook has. A rewrite leaves no trace in a+ transcript, and neither does a passthrough, so without these counters the+ busiest surface in the system reports nothing at all.+ """+ if not repo_root or not session_id:+ return+ try:+ from repowise.cli.hook_ledger import record_rewrite++ record_rewrite(repo_root, session_id, outcome=outcome, reason=reason)+ except Exception:+ return++if __name__ == "__main__":main()diff --git a/packages/core/src/repowise/core/sessions/efficacy.py b/packages/core/src/repowise/core/sessions/efficacy.pyindex d173f1a02..74f6fde95 100644--- a/packages/core/src/repowise/core/sessions/efficacy.py+++ b/packages/core/src/repowise/core/sessions/efficacy.py@@ -121,7 +121,7 @@ AMBIGUOUS = "ranged_read"#: Surfaces this module judges. ``decision`` rows key on decision-record ids#: and are judged by the decision miner; ``read_enrich`` is a silent KPI with#: no emission to act on.-CLASSIFIED_SURFACES = ("read", "search", "fix_history", "wrong_path")+CLASSIFIED_SURFACES = ("read", "search", "fix_history", "wrong_path", "glob")#: (surface, category) pairs that carry no recommended action, so an unacted#: firing is not a failure. Reported as a count, excluded from rates. The@@ -137,6 +137,18 @@ NO_ACTION_EXPECTED = frozenset(("read", "skeleton_served"),("read", "skeleton_recovered_full"),("read", "skeleton_ranged"),+ # A collapsed re-read leaves as ``updatedToolOutput``, so the pattern+ # pass below can never see it, and nothing is asked of the agent+ # either way. Deliberately *not* the retired ``("read", "reread")``+ # name: that was the advisory version of this idea, scored against a+ # closed population, and pooling the two would average an advisory's+ # adoption rate with a replacement's firing count.+ ("read", "reread_collapsed"),+ # Its sibling: the file *did* change under the agent, so the bytes+ # were served and the notice only says why they moved. Like the+ # stale-read flag, the behaviour it asks for — stop reasoning from the+ # earlier copy — leaves no trace in a transcript.+ ("read", "changed_since_read"),# A *served* flood digest, for the same structural reason: it leaves as# updatedToolOutput, so the pattern pass below can never see it. The# appended ``search``/``digest`` rows are still scored normally, and the@@ -160,6 +172,49 @@ RETIRED_CATEGORIES = frozenset(})+#: Rows whose text the agent never saw. They exist to count something — a+#: recovery, a served read — and their ``chars`` is a label, not a bill. Any+#: cost model that sums ``chars`` across the ledger has to exclude these or it+#: charges the agent for strings that never left this process.+MEASUREMENT_ONLY = frozenset(+ {+ ("read", "skeleton_recovered_full"),+ ("read", "skeleton_ranged"),+ ("read_enrich", "read_after_served"),+ }+)++#: Rows whose text *replaced* a tool result rather than being added beside it.+#: Their chars are not a debit either: the agent was going to be billed for+#: that tool result regardless, and these are smaller than what they stood in+#: for. Their saving is already recorded in the savings ledger.+REPLACEMENT_CATEGORIES = frozenset(+ {+ ("read", "skeleton_served"),+ ("read", "reread_collapsed"),+ ("search", "digest_served"),+ }+)+++def advisory_cost(rows: list[dict[str, Any]]) -> tuple[int, int]:+ """``(chars, firings)`` the agent was actually billed for, over ledger rows.++ Everything that added text next to a tool result: notices, rescues, the+ appended digest, the session block. Measurement rows and replacements are+ excluded for the reasons given above, so this is the debit side and only+ that.+ """+ chars = firings = 0+ for row in rows:+ pair = (row.get("surface", ""), row.get("category", ""))+ if pair in MEASUREMENT_ONLY or pair in REPLACEMENT_CATEGORIES:+ continue+ chars += row.get("chars") or 0+ firings += row.get("firings") or 0+ return chars, firings++#: Firings whose recommended outcome is a *non*-action, scored as compliance#: (did the agent avoid re-offending?) rather than adoption. Same ``acted``#: column, and ``repowise hook stats`` labels these "respected" so the two are@@ -208,6 +263,11 @@ _PATTERNS: tuple[tuple[str, str, re.Pattern[str]], ...] = ("stale_read",re.compile(r"^\[repowise\] (?P<target>\S+) changed \(Edit/Write\) after your previous"),),+ (+ "read",+ "changed_since_read",+ re.compile(r"^\[repowise\] (?P<target>\S+) changed on disk since you read it"),+ ),("fix_history","edit_notice",@@ -271,6 +331,16 @@ _PATTERNS: tuple[tuple[str, str, re.Pattern[str]], ...] = (r"The only indexed \S+ is (?P<target>.+)$"),),+ # The paths ride on the continuation lines, which ``parse_emission``+ # already harvests, so this header captures the pattern and nothing else.+ (+ "glob",+ "timeout_rescue",+ re.compile(+ r"^\[repowise\] That search timed out, so the index answered it instead\. "+ r"\d+ indexed path\(s\) match `(?P<pattern>[^`]+)`"+ ),+ ),)#: The attempted path from a wrong-path rescue, for the judge below. Read offdiff --git a/packages/core/src/repowise/core/sessions/footprint.py b/packages/core/src/repowise/core/sessions/footprint.pynew file mode 100644index 000000000..f8ae80443--- /dev/null+++ b/packages/core/src/repowise/core/sessions/footprint.py@@ -0,0 +1,246 @@+"""What repowise costs an agent, so a saving can be reported as a net.++The savings ledger has only ever counted credits. It therefore cannot report a+loss, which makes it unable to answer the one question worth asking about any+of this: is the programme positive? A dashboard that structurally cannot go+negative is not measuring, it is advertising.++Three debits are computable here, and each is priced the way it is actually+paid:++* **The repowise block in ``CLAUDE.md``** is *resident*. It sits in the prompt+ prefix, so it is not paid once — it is re-read on every API call in the+ session. That makes it the most expensive place a token can sit, and it is+ where we put the most.+* **The MCP tool schema**, on the same terms, whenever the harness loads it+ rather than deferring it.+* **Every advisory injection**, priced at the characters it added times the+ amplification for the remaining calls in that session.++A fourth — tool uses a surface proposed that the user or a policy then+rejected — is **not** computed. It needs a transcript pass this module does not+do, and inventing a number for it would be worse than leaving the line blank.+It is named in the report as missing rather than silently omitted.++**Amplification is measured, never assumed.** ``cache_read / cache_creation``+per session is the multiplier on every figure above, and it is a function of+how long the session ran: a token in the prefix is re-read once per subsequent+call, so a long session punishes resident cost and a short one barely notices+it. A single constant would be wrong at both ends, so this reads the real ratio+out of the transcripts and reports the call count beside it.++Everything here is read-only and best-effort: transcripts stay on the user's+machine, an unreadable one is skipped, and any failure degrades to a smaller+report rather than an error.+"""++from __future__ import annotations++import json+from dataclasses import dataclass, field+from pathlib import Path++#: Characters per token. The same crude estimate the savings ledger uses, kept+#: identical on purpose: a debit and a credit measured differently would not be+#: subtractable, and being consistently approximate beats being inconsistently+#: precise. The ``usage`` figures below are exact and are not estimated.+_CHARS_PER_TOKEN = 4++#: Where the repowise block starts in a project's CLAUDE.md, and where it ends.+#: The generated block is fenced by this heading; everything from it to the next+#: top-level heading is ours. A file without the heading contributes nothing.+_BLOCK_HEADING = "## Codebase Intelligence for"+++@dataclass+class Amplification:+ """How many times a resident token was re-read, measured not assumed."""++ #: ``cache_read / cache_creation``, per session, median across sessions.+ ratio: float = 0.0+ #: Median API calls per session — the reason the ratio is what it is.+ calls: int = 0+ #: Sessions the ratio was measured over.+ sessions: int = 0++ @property+ def known(self) -> bool:+ return self.sessions > 0 and self.ratio > 0+++@dataclass+class Debit:+ """One thing repowise costs, and how that cost is incurred."""++ label: str+ #: Tokens added to context once.+ raw_tokens: int+ #: Tokens actually billed, after amplification.+ billed_tokens: int+ #: How the figure was arrived at, shown to the reader verbatim.+ detail: str+++@dataclass+class Footprint:+ """The full cost side, plus what could not be measured."""++ debits: list[Debit] = field(default_factory=list)+ amplification: Amplification = field(default_factory=Amplification)+ #: Cost lines that exist but were not computed, named so the total is read+ #: as a lower bound rather than as complete.+ unmeasured: list[str] = field(default_factory=list)++ @property+ def billed_total(self) -> int:+ return sum(d.billed_tokens for d in self.debits)++ @property+ def raw_total(self) -> int:+ return sum(d.raw_tokens for d in self.debits)+++def measure_amplification(+ repo_root: Path, *, projects_root: Path | None = None, limit: int = 25+) -> Amplification:+ """Median ``cache_read / cache_creation`` over this repo's recent sessions.++ Exact, not estimated: these come from each assistant message's own ``usage``+ block. A session with no cache creation is skipped rather than counted as+ zero — it means the prefix was never cached, so there is no re-read ratio+ to speak of, which is different from a ratio of nothing.+ """+ try:+ from repowise.core.sessions import transcript_dir_for++ directory = transcript_dir_for(repo_root, projects_root)+ if not directory.is_dir():+ return Amplification()+ files = sorted(+ directory.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True+ )[:limit]+ except (OSError, ValueError):+ return Amplification()++ ratios: list[float] = []+ call_counts: list[int] = []+ for path in files:+ read = created = calls = 0+ try:+ with path.open(encoding="utf-8", errors="replace") as fh:+ for line in fh:+ if '"usage"' not in line:+ continue+ try:+ entry = json.loads(line)+ except ValueError:+ continue+ usage = (entry.get("message") or {}).get("usage")+ if not isinstance(usage, dict):+ continue+ calls += 1+ read += usage.get("cache_read_input_tokens") or 0+ created += usage.get("cache_creation_input_tokens") or 0+ except OSError:+ continue+ if created > 0 and calls:+ ratios.append(read / created)+ call_counts.append(calls)+ if not ratios:+ return Amplification()+ ratios.sort()+ call_counts.sort()+ mid = len(ratios) // 2+ return Amplification(+ ratio=ratios[mid], calls=call_counts[len(call_counts) // 2], sessions=len(ratios)+ )+++def claude_md_block_chars(repo_root: Path) -> int:+ """Characters of ``CLAUDE.md`` that repowise wrote, or 0.++ Only our own block is charged. The rest of the file is the project's and+ would be there whether or not repowise was installed.+ """+ for candidate in (repo_root / ".claude" / "CLAUDE.md", repo_root / "CLAUDE.md"):+ try:+ text = candidate.read_text(encoding="utf-8")+ except (OSError, ValueError):+ continue+ start = text.find(_BLOCK_HEADING)+ if start == -1:+ continue+ rest = text[start + len(_BLOCK_HEADING) :]+ end = rest.find("\n## ")+ return len(_BLOCK_HEADING) + (len(rest) if end == -1 else end)+ return 0+++def measure(+ repo_root: Path,+ *,+ advisory_chars: int = 0,+ advisory_firings: int = 0,+ mcp_schema_chars: int = 0,+ projects_root: Path | None = None,+) -> Footprint:+ """Everything repowise cost this repo that can be counted from local data.++ *advisory_chars* and *advisory_firings* come from the hook ledger, which+ records the characters of every emission it made. *mcp_schema_chars* is+ zero unless the caller knows the harness loaded the schema rather than+ deferring it — Claude Code defers, so guessing would invent a large debit.+ """+ amp = measure_amplification(repo_root, projects_root=projects_root)+ multiplier = amp.ratio if amp.known else 1.0+ footprint = Footprint(amplification=amp)++ resident_note = (+ f"resident in the prompt prefix, re-read {amp.ratio:.1f}x per session "+ f"(median {amp.calls} API calls)"+ if amp.known+ else "resident in the prompt prefix; no cache figures on disk, so billed = raw"+ )++ block_chars = claude_md_block_chars(repo_root)+ if block_chars:+ raw = block_chars // _CHARS_PER_TOKEN+ footprint.debits.append(+ Debit(+ label="CLAUDE.md repowise block",+ raw_tokens=raw,+ billed_tokens=int(raw * multiplier),+ detail=f"{block_chars:,} chars, {resident_note}",+ )+ )+ if mcp_schema_chars:+ raw = mcp_schema_chars // _CHARS_PER_TOKEN+ footprint.debits.append(+ Debit(+ label="MCP tool schema",+ raw_tokens=raw,+ billed_tokens=int(raw * multiplier),+ detail=f"{mcp_schema_chars:,} chars, {resident_note}",+ )+ )+ else:+ footprint.unmeasured.append(+ "the MCP tool schema, which is only resident when the harness does "+ "not defer it (Claude Code defers)"+ )+ if advisory_chars:+ raw = advisory_chars // _CHARS_PER_TOKEN+ footprint.debits.append(+ Debit(+ label="advisory injections",+ raw_tokens=raw,+ billed_tokens=int(raw * multiplier),+ detail=f"{advisory_firings:,} firings, {advisory_chars:,} chars",+ )+ )++ footprint.unmeasured.append(+ "tool uses our surfaces proposed that the user or a policy then "+ "rejected, which needs a transcript pass this does not do"+ )+ return footprintdiff --git a/packages/core/src/repowise/core/sessions/staging.py b/packages/core/src/repowise/core/sessions/staging.pyindex f0139fb46..92df1885c 100644--- a/packages/core/src/repowise/core/sessions/staging.py+++ b/packages/core/src/repowise/core/sessions/staging.py@@ -100,6 +100,7 @@ CREATE TABLE IF NOT EXISTS injections (duration_ms INTEGER NOT NULL DEFAULT 0,acted INTEGER NOT NULL DEFAULT 0,verdict TEXT NOT NULL DEFAULT '',+ build TEXT NOT NULL DEFAULT '',PRIMARY KEY (session_id, decision_id));CREATE INDEX IF NOT EXISTS idx_raw_pending ON raw_candidates(structured_key)@@ -122,6 +123,11 @@ INJECTIONS_LEDGER_COLUMNS = (# for a row judged on some other surface, not yet judged, or evaluated# before this column existed. See :meth:`decision_feedback_totals`.("verdict", "TEXT NOT NULL DEFAULT ''"),+ # Which repowise build emitted the row ("<version>+<install digest>"); see+ # ``repowise.cli.hook_ledger.emitting_build``. Empty on every row written+ # before this column existed, and that emptiness is the point: those are+ # exactly the rows whose attribution cannot be recovered.+ ("build", "TEXT NOT NULL DEFAULT ''"),)@@ -514,6 +520,50 @@ class SessionStagingStore:for r in rows]+ def rewrite_run_totals(self) -> list[dict[str, Any]]:+ """What the PreToolUse rewrite hook did, per outcome and reason.++ The rewrite hook's only instrument. An ``updatedInput`` rewrite never+ appears in a transcript and neither does a passthrough, so before these+ rows the busiest hook surface reported nothing at all and its bail+ distribution was inference.+ """+ try:+ rows = self._conn.execute(+ "SELECT outcome, reason, SUM(calls), COUNT(DISTINCT session_id), SUM(total_ms) "+ "FROM rewrite_runs GROUP BY outcome, reason ORDER BY SUM(calls) DESC"+ ).fetchall()+ except sqlite3.Error:+ return [] # sidecar predates the table: no rewrite rows, not an error+ return [+ {+ "outcome": r[0],+ "reason": r[1],+ "calls": r[2] or 0,+ "sessions": r[3] or 0,+ "total_ms": r[4] or 0,+ }+ for r in rows+ ]++ def injection_builds(self) -> list[dict[str, Any]]:+ """Which repowise builds emitted the rows in this ledger, busiest first.++ More than one live build here means two installs are emitting into the+ same repo, and the rows above them are not one population: a surface+ deleted in one install can still be firing from the other. Rows written+ before the ``build`` column are grouped under ``""`` and labelled as+ unattributable rather than folded into whichever build is current.+ """+ rows = self._conn.execute(+ "SELECT build, COUNT(*), COUNT(DISTINCT session_id), MAX(shown_at) "+ "FROM injections GROUP BY build ORDER BY COUNT(*) DESC"+ ).fetchall()+ return [+ {"build": r[0] or "", "firings": r[1], "sessions": r[2], "last_seen": r[3] or 0.0}+ for r in rows+ ]+def session_duration_totals(self) -> list[int]:"""Total hook wall-time per session, in ms, for sessions that have it."""rows = self._conn.execute(diff --git a/tests/unit/cli/test_augment_hook_perf.py b/tests/unit/cli/test_augment_hook_perf.pyindex aa65e1ed1..6439812ee 100644--- a/tests/unit/cli/test_augment_hook_perf.py+++ b/tests/unit/cli/test_augment_hook_perf.py@@ -204,7 +204,9 @@ def test_a_read_in_a_repo_that_did_not_opt_in_imports_nothing_heavy(tmp_path: Pa# Guard the guard, same as the opted-in case: if the counterfactual stopped# running, the import assertion above would pass by doing nothing at all.- state = json.loads((repo / ".repowise" / ".augment-session.json").read_text("utf-8"))+ from repowise.cli.commands.augment_cmd.read_state import _session_state_path++ state = json.loads(_session_state_path(repo, "perf").read_text("utf-8"))assert state["forgone"] == [rel], "the probe did not reach the counterfactual"@@ -322,6 +324,124 @@ def test_a_wrong_path_rescue_imports_nothing_heavy(tmp_path: Path) -> None:assert out.stderr.strip() == "", f"a wrong-path rescue pulled in:\n{out.stderr}"+def _reread_repo(tmp_path: Path) -> tuple[Path, str, str]:+ """A repo where the second Read of a file is collapsed to a notice."""+ repo = tmp_path / "repo"+ (repo / ".repowise").mkdir(parents=True)+ (repo / ".repowise" / "config.yaml").write_text(+ "hooks:\n read_reread: true\n", encoding="utf-8"+ )+ rel = "big.py"+ source = "\n".join(f"line {i} with enough text to be worth not repeating" for i in range(200))+ (repo / rel).write_text(source, encoding="utf-8")+ return repo, rel, source+++def test_a_collapsed_reread_imports_nothing_heavy(tmp_path: Path) -> None:+ """The re-read collapse never needs the index, so it must never reach it.++ It is a hash comparison over the payload the hook was already handed. If+ this ever pulls the skeleton builder or the ORM in, something has started+ doing work the surface does not need.+ """+ repo, rel, _ = _reread_repo(tmp_path)+ env = _fake_home(tmp_path)+ env["REPOWISE_HOOK_UPDATED_OUTPUT"] = "1"+ probe = _read_payload_probe(repo, rel)+ code = (+ probe+ + "sys.stdout.write('|SECOND|'); "+ + probe+ + f"heavy = sorted(m for m in sys.modules if m.startswith({_HEAVY_PREFIXES!r})); "+ "print('\\n'.join(heavy), file=sys.stderr)"+ )+ out = subprocess.run(+ [sys.executable, "-c", code], capture_output=True, text=True, check=True, env=env+ )+ second = out.stdout.split("|SECOND|", 1)[1]+ assert "Unchanged since you read it" in second, "the probe did not reach the collapse"+ assert out.stderr.strip() == "", f"a collapsed re-read pulled in:\n{out.stderr}"+++def test_a_glob_timeout_rescue_imports_nothing_heavy(tmp_path: Path) -> None:+ """The rescue answers a path query from stdlib sqlite3 and nothing else."""+ repo = _indexed_search_repo(tmp_path)+ (repo / "src").mkdir(parents=True, exist_ok=True)+ (repo / "src" / "a.py").write_text("x", encoding="utf-8")+ payload = {+ "hook_event_name": "PostToolUseFailure",+ "tool_name": "Glob",+ "tool_input": {"pattern": "src/*.py"},+ "error": (+ "Ripgrep search timed out after 20 seconds. The search may have matched "+ "files but did not complete in time. Try searching a more specific path "+ "or pattern."+ ),+ "cwd": str(repo),+ "session_id": "perf",+ }+ code = (+ "import sys, json, io; "+ f"sys.stdin = io.StringIO({json.dumps(payload)!r}); "+ "from repowise.cli.commands.augment_cmd import _run_augment; "+ "_run_augment(client=None); "+ f"heavy = sorted(m for m in sys.modules if m.startswith({_HEAVY_PREFIXES!r})); "+ "print('\\n'.join(heavy), file=sys.stderr)"+ )+ out = subprocess.run(+ [sys.executable, "-c", code],+ capture_output=True,+ text=True,+ check=True,+ env=_fake_home(tmp_path),+ )+ assert "the index answered it instead" in out.stdout, "the probe did not reach the rescue"+ assert out.stderr.strip() == "", f"a glob timeout rescue pulled in:\n{out.stderr}"+++def _modules_added_by(statement: str) -> set[str]:+ """Modules an import statement adds, over what the interpreter starts with.++ A delta rather than an absolute: this interpreter already has ``pathlib``+ resident before any repowise code runs (site processing pulls it), so an+ absolute check would either fail on something nobody imported or have to+ hard-code an allowlist that rots.+ """+ code = (+ "import sys; before = set(sys.modules); "+ f"{statement} "+ "print('\\n'.join(sorted(set(sys.modules) - before)))"+ )+ out = subprocess.run(+ [sys.executable, "-c", code], capture_output=True, text=True, check=True+ )+ return set(out.stdout.split())+++def test_the_shared_ledger_is_free_to_import() -> None:+ """``hook_ledger`` sits at the *module scope* of the PreToolUse rewrite hook.++ That hook fires on every shell command an agent runs, so importing the+ ledger has to cost nothing beyond what the hook already pays. ``sqlite3``+ is deferred into the functions that open a database, so a command that+ bails on shape never touches one.+ """+ added = _modules_added_by("import repowise.cli.hook_ledger;")+ assert "sqlite3" not in added, "importing the hook ledger pulled in sqlite3"+++def test_the_rewrite_hook_still_opens_no_database_to_load() -> None:+ """The PreToolUse hook gained a ledger; it must not have gained a cost.++ It writes one counter row per shell command, and that write is deferred+ until after the response is on stdout. Loading the module must stay as+ cheap as it was before the ledger existed.+ """+ added = _modules_added_by("import repowise.cli.rewrite_hook;")+ for module in ("sqlite3", "click", "yaml"):+ assert module not in added, f"the rewrite hook pulled in {module} at import"++def test_a_silent_invocation_imports_nothing_heavy(tmp_path: Path) -> None:"""A payload the hook has nothing to say about must stay on the cheap path."""code = (diff --git a/tests/unit/cli/test_augment_read_skeleton.py b/tests/unit/cli/test_augment_read_skeleton.pyindex 1423588ef..ebd99652f 100644--- a/tests/unit/cli/test_augment_read_skeleton.py+++ b/tests/unit/cli/test_augment_read_skeleton.py@@ -19,15 +19,22 @@ from pathlib import Pathimport pytest+from repowise.cli.agent_adapters.claude_code import (+ ClaudeCodeAdapter,+ _recorded_client_version,+)from repowise.cli.commands.augment_cmd import _handle_post_tool_usefrom repowise.cli.commands.augment_cmd.read_skeleton import (_MAX_OUTPUT_CHARS,- _recorded_client_version,enabled,is_unbounded_read,- supports_updated_output,)++def supports_updated_output() -> bool:+ """The probe under test, now owned by the harness adapter that answers it."""+ return ClaudeCodeAdapter().supports_updated_output()+_SESSION = "sess-1"@@ -344,11 +351,12 @@ def test_a_verification_read_after_an_edit_is_left_alone(repo: Path) -> None:{"file_path": str(repo / "pkg/big.py")},_read_output(repo, "pkg/big.py"),)+ adapter = ClaudeCodeAdapter()- served, _ = _skeleton_replacement(*args, state, edited_since_read=False)+ served, _ = _skeleton_replacement(*args, state, adapter, edited_since_read=False)assert served is not Nonestate["skeletonized"].clear()- served, _ = _skeleton_replacement(*args, state, edited_since_read=True)+ served, _ = _skeleton_replacement(*args, state, adapter, edited_since_read=True)assert served is Nonediff --git a/tests/unit/cli/test_augment_reread.py b/tests/unit/cli/test_augment_reread.pynew file mode 100644index 000000000..03144f0b0--- /dev/null+++ b/tests/unit/cli/test_augment_reread.py@@ -0,0 +1,334 @@+"""Collapsing a re-read of unchanged bytes to a notice (``updatedToolOutput``).++The gates here are arithmetic, so the tests are about the arithmetic being+*applied* — that a changed file is served, that a different range is not+mistaken for a change, that a session cannot inherit another session's memory,+and that the escape hatch in the notice is true. A replacement surface whose+promise is false in the text is worse than one that never fires.+"""++from __future__ import annotations++import json+from pathlib import Path++import pytest++from repowise.cli.agent_adapters.claude_code import ClaudeCodeAdapter+from repowise.cli.commands.augment_cmd import _handle_post_tool_use+from repowise.cli.commands.augment_cmd.read_state import _load_session_state++SESSION = "sess-reread"++#: Long enough that the notice is a real saving; the only gate is that the+#: notice is smaller than what it replaces.+_BODY = "\n".join(f"line {i} carrying enough text to be worth not repeating" for i in range(120))+++def repo(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ (tmp_path / ".repowise").mkdir()+ (tmp_path / ".repowise" / "config.yaml").write_text(+ "hooks:\n read_reread: true\n", encoding="utf-8"+ )+ (tmp_path / "a.py").write_text(_BODY, encoding="utf-8")+ monkeypatch.setenv("REPOWISE_HOOK_UPDATED_OUTPUT", "1")+ return tmp_path+++def _read(repo: Path, *, content: str | None = None, session: str = SESSION, **window):+ """Fire the real PostToolUse Read handler and return its HookResult."""+ body = _BODY if content is None else content+ tool_input = {"file_path": str(repo / "a.py"), **window}+ return _handle_post_tool_use(+ "Read",+ tool_input,+ {+ "type": "text",+ "file": {+ "filePath": str(repo / "a.py"),+ "content": body,+ "numLines": body.count("\n") + 1,+ "startLine": window.get("offset", 1),+ "totalLines": _BODY.count("\n") + 1,+ },+ },+ str(repo),+ session_id=session,+ )+++def _served(result) -> str | None:+ """The content the agent actually receives, when it was replaced."""+ if result.replacement is None:+ return None+ return result.replacement["file"]["content"]+++class TestTheCollapse:+ def test_the_first_read_is_untouched(self, repo: Path) -> None:+ assert _read(repo).replacement is None++ def test_an_unchanged_re_read_is_collapsed(self, repo: Path) -> None:+ _read(repo)+ served = _served(_read(repo))+ assert served is not None, "identical bytes should not be sent twice"+ assert "Unchanged since you read it: a.py" in served+ assert "the whole file" in served, "the notice must name the range served before"++ def test_the_notice_names_the_earlier_tool_call(self, repo: Path) -> None:+ _read(repo)+ assert "tool call 1" in _served(_read(repo))++ def test_the_replacement_is_read_shaped_not_a_bare_string(self, repo: Path) -> None:+ """Read validates ``updatedToolOutput`` against its own schema; a bare+ string is rejected silently and the agent sees the original bytes."""+ _read(repo)+ payload = _read(repo).replacement+ assert isinstance(payload, dict)+ assert payload["file"]["filePath"] == str(repo / "a.py")+ assert payload["file"]["numLines"] == payload["file"]["content"].count("\n") + 1+ assert payload["file"]["totalLines"] == _BODY.count("\n") + 1++ def test_a_short_file_is_not_collapsed(self, repo: Path) -> None:+ """The notice would be bigger than the content. No threshold is tuned+ here — it is an exact comparison."""+ (repo / "a.py").write_text("x = 1\n", encoding="utf-8")+ _read(repo, content="x = 1\n")+ assert _read(repo, content="x = 1\n").replacement is None+++class TestWhenTheBytesDiffer:+ def test_a_changed_file_is_served_not_collapsed(self, repo: Path) -> None:+ _read(repo)+ changed = _BODY + "\nsomething else entirely"+ (repo / "a.py").write_text(changed, encoding="utf-8")+ result = _read(repo, content=changed)+ assert result.replacement is None, "different bytes must always be served"++ def test_and_the_agent_is_told_what_changed(self, repo: Path) -> None:+ """More valuable than the bytes: nothing else in the session can learn+ that a file moved under it without an Edit of ours."""+ _read(repo)+ changed = _BODY + "\nsomething else entirely"+ (repo / "a.py").write_text(changed, encoding="utf-8")+ context = _read(repo, content=changed).context or ""+ assert "a.py changed on disk since you read it" in context+ assert "not through an Edit in this session" in context++ def test_the_change_notice_fires_once(self, repo: Path) -> None:+ _read(repo)+ changed = _BODY + "\nsomething else entirely"+ (repo / "a.py").write_text(changed, encoding="utf-8")+ assert "changed on disk" in (_read(repo, content=changed).context or "")+ again = _read(repo, content=changed + "\nand again")+ assert "changed on disk" not in (again.context or "")++ def test_a_different_range_is_not_reported_as_a_change(self, repo: Path) -> None:+ """Different offsets legitimately return different bytes. Calling that+ a change would be the judgment this surface exists to avoid making."""+ _read(repo)+ result = _read(repo, content="line 5\nline 6", offset=5, limit=2)+ assert result.replacement is None+ assert "changed on disk" not in (result.context or "")+++class TestTheEscapeHatch:+ def test_never_collapsed_twice_in_a_row(self, repo: Path) -> None:+ """A compaction can take the earlier copy with it, and that is not+ detectable from a hook. Reading again always returns the content."""+ _read(repo)+ assert _read(repo).replacement is not None+ assert _read(repo).replacement is None, "the notice promises the bytes come back"+ assert _read(repo).replacement is not None++ def test_the_notice_states_that_hatch(self, repo: Path) -> None:+ _read(repo)+ assert "Read it again and you get the content" in _served(_read(repo))+++class TestAgainstTheOtherReplacingSurface:+ """A Read some *other* surface replaced delivered bytes the agent never got.++ Both surfaces on at once is the configuration one init consent produces, so+ this is the default arrangement, not an exotic one.+ """++ @pytest.fixture+ def both_on(self, repo: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ (repo / ".repowise" / "config.yaml").write_text(+ "hooks:\n read_reread: true\n read_skeleton: true\n", encoding="utf-8"+ )+ # Stand in for the indexed skeleton so the surface fires without an+ # index; what is under test is the interaction, not the skeleton.+ from repowise.cli.commands.augment_cmd import read_skeleton+ from repowise.cli.commands.augment_cmd.replacement import Offer++ monkeypatch.setattr(+ read_skeleton,+ "skeleton_replacement",+ lambda repo_path, rel, **kw: Offer(+ key=rel,+ text=f"[repowise] Skeleton of {rel}.\ndef a(): ...",+ raw_tokens=10_000,+ new_tokens=20,+ category="skeleton_served",+ filter_name="read_skeleton",+ ),+ )+ return repo++ def test_a_skeleton_is_never_followed_by_you_already_have_this(+ self, both_on: Path+ ) -> None:+ """The collapse must not claim bytes a skeleton stood in for.++ Otherwise the second Read says "you were served the whole file" to an+ agent that was served signatures, and the skeleton's own promise —+ read it again and you get it whole — is broken by a third read.+ """+ assert "Skeleton of" in _served(_read(both_on))+ second = _read(both_on)+ assert second.replacement is None, (+ "the Read after a skeleton must return the file, not a notice about it"+ )++ def test_and_that_read_is_not_reported_as_an_external_change(+ self, both_on: Path+ ) -> None:+ """The other half: the skeleton's digest differs from the file's, and+ treating that as a change would invent one."""+ _read(both_on)+ assert "changed on disk" not in (_read(both_on).context or "")++ def test_a_changed_file_is_not_served_as_a_skeleton(+ self, repo: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ """The change notice says the content below is current. A skeleton+ would make that half true at the moment the agent most needs a body.++ The first Read has to deliver real bytes for there to be anything to+ compare against, so the skeleton is turned on only after it — which is+ also the shape of a repo that enables the surface mid-session.+ """+ _read(repo)+ changed = _BODY + "\nsomething else entirely"+ (repo / "a.py").write_text(changed, encoding="utf-8")++ (repo / ".repowise" / "config.yaml").write_text(+ "hooks:\n read_reread: true\n read_skeleton: true\n", encoding="utf-8"+ )+ from repowise.cli.commands.augment_cmd import read_skeleton+ from repowise.cli.commands.augment_cmd.replacement import Offer++ monkeypatch.setattr(+ read_skeleton,+ "skeleton_replacement",+ lambda repo_path, rel, **kw: Offer(+ key=rel,+ text=f"[repowise] Skeleton of {rel}.",+ raw_tokens=10_000,+ new_tokens=20,+ category="skeleton_served",+ filter_name="read_skeleton",+ ),+ )+ result = _read(repo, content=changed)+ assert "changed on disk" in (result.context or "")+ assert result.replacement is None, "a file that just changed is served whole"+++class TestSessionIsolation:+ def test_a_second_session_does_not_inherit_the_first(self, repo: Path) -> None:+ """A subagent runs under its own session id and never received the+ parent's bytes, so it must not be told it already has them."""+ _read(repo)+ _read(repo)+ assert _read(repo, session="subagent-1").replacement is None++ def test_each_session_keeps_its_own_state_file(self, repo: Path) -> None:+ _read(repo)+ _read(repo, session="subagent-1")+ files = list((repo / ".repowise" / "hook-sessions").glob("*.json"))+ assert len(files) == 2+ for path in files:+ assert json.loads(path.read_text(encoding="utf-8"))["session_id"] in (+ SESSION,+ "subagent-1",+ )+++class TestGates:+ def test_off_by_default(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ (tmp_path / ".repowise").mkdir()+ (tmp_path / "a.py").write_text(_BODY, encoding="utf-8")+ monkeypatch.setenv("REPOWISE_HOOK_UPDATED_OUTPUT", "1")+ _read(tmp_path)+ assert _read(tmp_path).replacement is None++ def test_a_client_that_cannot_replace_is_never_handed_one(self, repo: Path) -> None:+ _read(repo)+ result = _handle_post_tool_use(+ "Read",+ {"file_path": str(repo / "a.py")},+ {"type": "text", "file": {"filePath": str(repo / "a.py"), "content": _BODY}},+ str(repo),+ client="codex",+ session_id=SESSION,+ )+ assert result.replacement is None++ def test_an_old_client_build_is_never_handed_one(+ self, repo: Path, monkeypatch: pytest.MonkeyPatch+ ) -> None:+ _read(repo)+ monkeypatch.setattr(ClaudeCodeAdapter, "supports_updated_output", lambda self: False)+ assert _read(repo).replacement is None++ def test_a_verification_read_after_an_edit_is_never_collapsed(self, repo: Path) -> None:+ """Re-reading what you just edited needs fidelity, not a pointer."""+ _read(repo)+ _handle_post_tool_use(+ "Edit", {"file_path": str(repo / "a.py")}, {}, str(repo), session_id=SESSION+ )+ result = _read(repo)+ assert result.replacement is None+ assert "stale" in (result.context or "")+++class TestLedger:+ def test_a_collapse_is_recorded_and_a_saving_billed(self, repo: Path) -> None:+ import sqlite3++ omissions = repo / ".repowise" / "omissions"+ omissions.mkdir(parents=True)+ con = sqlite3.connect(omissions / "omissions.db")+ con.execute(+ "CREATE TABLE savings (created_at REAL, filter TEXT, source TEXT, "+ "command TEXT, raw_tokens INTEGER, distilled_tokens INTEGER)"+ )+ con.commit()+ con.close()++ _read(repo)+ result = _read(repo)+ assert result.replacement is not None+ assert result.on_emitted is not None+ result.on_emitted()++ con = sqlite3.connect(omissions / "omissions.db")+ try:+ rows = con.execute(+ "SELECT filter, source, command, raw_tokens, distilled_tokens FROM savings"+ ).fetchall()+ finally:+ con.close()+ assert rows == [("read_reread", "hook-read", "a.py", len(_BODY) // 4, pytest.approx(rows[0][4]))]+ assert rows[0][4] < rows[0][3], "a collapse that saved nothing is not a saving"++ def test_the_state_records_what_was_served(self, repo: Path) -> None:+ _read(repo)+ meta = _load_session_state(repo, SESSION)["read_meta"]["a.py"]+ assert meta["off"] is None and meta["lim"] is None+ assert meta["seq"] == 1+ assert len(meta["h"]) == 12diff --git a/tests/unit/cli/test_augment_search_digest.py b/tests/unit/cli/test_augment_search_digest.pyindex 3aac5a9d6..ea3406325 100644--- a/tests/unit/cli/test_augment_search_digest.py+++ b/tests/unit/cli/test_augment_search_digest.py@@ -14,8 +14,9 @@ from unittest.mock import patchimport pytest-from repowise.cli.commands import augment_cmd-from repowise.cli.commands.augment_cmd import search_digest+from repowise.cli.agent_adapters import adapter_for+from repowise.cli.agent_adapters.claude_code import ClaudeCodeAdapter+from repowise.cli.commands.augment_cmd import replacement, search_digestfrom repowise.cli.commands.augment_cmd.search import _handle_search_post# A real multi-file flood: 60 matches over 6 files, the shape `group_search_matches`@@ -55,7 +56,7 @@ def _fire(cwd, tool_output=None, client=None, pattern="compute_value"):tool_input={"pattern": pattern},tool_output=tool_output if tool_output is not None else dict(GREP_CONTENT_FLOOD),cwd=str(cwd),- client=client,+ adapter=adapter_for(client),)@@ -113,11 +114,9 @@ class TestCapabilityGate:assert _fire(opted_in, client=None).replacement is not Nonedef test_old_client_build_falls_back_to_appending(self, opted_in) -> None:+ """Protocol yes, installed build no. Both questions are the adapter's."""with patch.object(- augment_cmd.search_digest, "replaces_tool_output", return_value=True- ), patch(- "repowise.cli.commands.augment_cmd.read_skeleton.supports_updated_output",- return_value=False,+ ClaudeCodeAdapter, "supports_updated_output", return_value=False):result = _fire(opted_in)assert result.replacement is None@@ -172,29 +171,45 @@ class TestWorthItGates:assert made.saved_tokens > 0-class TestAsGrepOutput:+class TestGrepWirePayload:+ """The shared payload builder, on Grep's own output schema."""++ def _wire(self, tool_response, text="x"):+ return replacement.wire_payload("Grep", tool_response, text)+def test_rejects_non_content_modes(self) -> None:- assert search_digest.as_grep_output({"mode": "files_with_matches"}, "x") is None- assert search_digest.as_grep_output({"filenames": []}, "x") is None+ assert self._wire({"mode": "files_with_matches"}) is None+ assert self._wire({"filenames": []}) is Nonedef test_rejects_non_dict(self) -> None:- assert search_digest.as_grep_output("a string", "x") is None- assert search_digest.as_grep_output(None, "x") is None+ assert self._wire("a string") is None+ assert self._wire(None) is Nonedef test_rejects_content_mode_without_content(self) -> None:- assert search_digest.as_grep_output({"mode": "content", "numLines": 3}, "x") is None+ assert self._wire({"mode": "content", "numLines": 3}) is None++ def test_rejects_a_tool_with_no_builder(self) -> None:+ """An unknown tool cannot be replaced: guessing its envelope is how a+ replacement gets rejected invisibly while the ledger records a saving."""+ assert replacement.wire_payload("Bash", dict(GREP_CONTENT_FLOOD), "x") is Nonedef test_leaves_search_facts_alone(self) -> None:- out = search_digest.as_grep_output(dict(GREP_CONTENT_FLOOD), "one\ntwo")+ out = self._wire(dict(GREP_CONTENT_FLOOD), "one\ntwo")assert out["totalLines"] == GREP_CONTENT_FLOOD["totalLines"]assert out["numFiles"] == GREP_CONTENT_FLOOD["numFiles"]assert out["numLines"] == 2-class TestReplacesToolOutput:+class TestCanReplace:+ """Whether a harness may be handed a replacement is the adapter's answer."""+@pytest.mark.parametrize("client", [None, "claude", "claude-code"])def test_clients_that_can_replace(self, client) -> None:- assert search_digest.replaces_tool_output(client) is True+ assert replacement.can_replace(adapter_for(client)) is Truedef test_codex_cannot(self) -> None:- assert search_digest.replaces_tool_output("codex") is False+ assert replacement.can_replace(adapter_for("codex")) is False++ def test_an_unknown_marker_resolves_to_the_default_adapter(self) -> None:+ """A hook must never fail on a payload; capability is still checked."""+ assert adapter_for("some-future-agent").name == "claude-code"diff --git a/tests/unit/cli/test_augment_served_reads.py b/tests/unit/cli/test_augment_served_reads.pyindex fd4699fc9..e7fcfa1bc 100644--- a/tests/unit/cli/test_augment_served_reads.py+++ b/tests/unit/cli/test_augment_served_reads.py@@ -14,8 +14,8 @@ import sqlite3from pathlib import Pathfrom repowise.cli.commands.augment_cmd import served_reads-from repowise.cli.commands.augment_cmd.ledger import _claim_ledgerfrom repowise.cli.commands.augment_cmd.search import _log_search_firing+from repowise.cli.hook_ledger import _claim_ledger_TARGET = "src/core/models.py"diff --git a/tests/unit/cli/test_codex_plugin.py b/tests/unit/cli/test_codex_plugin.pyindex e630f6eda..f6bc2e16e 100644--- a/tests/unit/cli/test_codex_plugin.py+++ b/tests/unit/cli/test_codex_plugin.py@@ -4,12 +4,13 @@ import jsonimport refrom pathlib import Path+from repowise.cli.agent_adapters import adapter_forfrom repowise.cli.agent_adapters.codex import (+ EDIT_TOOL_MATCHER,SHELL_TOOL_MATCHER,SHELL_TOOL_NAMES,CodexAdapter,)-from repowise.cli.commands.augment_cmd.command import _SHELL_TOOL_NAMESROOT = Path(__file__).resolve().parents[3]PLUGIN_ROOT = ROOT / "plugins" / "codex"@@ -46,7 +47,7 @@ def test_codex_plugin_hooks_match_supported_codex_events() -> None:assert hooks["SessionStart"][0]["matcher"] == "startup|resume|clear"assert [entry["matcher"] for entry in hooks["PostToolUse"]] == [SHELL_TOOL_MATCHER,- "apply_patch|Edit|Write",+ EDIT_TOOL_MATCHER,]commands = [@@ -78,8 +79,9 @@ def test_codex_shell_matcher_covers_the_names_codex_actually_sends() -> None:for name in ("Bash", "shell_command"):assert name in SHELL_TOOL_NAMESassert name in SHELL_TOOL_MATCHER.split("|")- # The augment dispatch routes it to the shell handler...- assert name in _SHELL_TOOL_NAMES+ # The augment dispatch routes it to the shell handler, off the same+ # adapter the registry hands that dispatcher for `--client codex`...+ assert name in adapter_for("codex").shell_tool_names# ...and the rewrite hook accepts rather than declines it.payload = json.dumps({diff --git a/tests/unit/distill/test_read_intelligence.py b/tests/unit/distill/test_read_intelligence.pyindex 38872fe22..a376b7223 100644--- a/tests/unit/distill/test_read_intelligence.py+++ b/tests/unit/distill/test_read_intelligence.py@@ -229,13 +229,15 @@ class TestSessionState:def test_state_file_lives_under_repowise(self, repo: Path) -> None:_write_big_file(repo, "a.py", lines=10)_read_event(repo, "a.py", num_lines=10)- assert _session_state_path(repo).exists()- state = json.loads(_session_state_path(repo).read_text(encoding="utf-8"))+ assert _session_state_path(repo, SESSION).exists()+ state = json.loads(_session_state_path(repo, SESSION).read_text(encoding="utf-8"))assert state["session_id"] == SESSIONassert "a.py" in state["reads"]def test_corrupt_state_file_is_replaced_not_fatal(self, repo: Path) -> None:- _session_state_path(repo).write_text("{not json", encoding="utf-8")+ corrupt = _session_state_path(repo, SESSION)+ corrupt.parent.mkdir(parents=True, exist_ok=True)+ corrupt.write_text("{not json", encoding="utf-8")_write_big_file(repo, "a.py", lines=10)assert _read_event(repo, "a.py", num_lines=10) is Nonestate = _load_session_state(repo, SESSION)@@ -251,7 +253,7 @@ class TestSessionState:"stale_notified": [],}_save_session_state(repo, state)- saved = json.loads(_session_state_path(repo).read_text(encoding="utf-8"))+ saved = json.loads(_session_state_path(repo, SESSION).read_text(encoding="utf-8"))assert len(saved["reads"]) == 400# Most recent timestamps survive the trim.assert "f599.py" in saved["reads"]diff --git a/tests/unit/distill/test_rewrite_ledger.py b/tests/unit/distill/test_rewrite_ledger.pynew file mode 100644index 000000000..9a0b02b21--- /dev/null+++ b/tests/unit/distill/test_rewrite_ledger.py@@ -0,0 +1,157 @@+"""The PreToolUse rewrite hook counting itself.++Its firing rate is not observable any other way: an ``updatedInput`` rewrite+never appears in a transcript and neither does a passthrough, so before these+rows the busiest hook surface reported nothing at all and the reason a command+was let through was inference. These tests pin that the counters are written,+that they aggregate rather than dedup, and that a bail reason is specific+enough to be worth having.+"""++from __future__ import annotations++import io+import json+import sqlite3+from pathlib import Path++import pytest++from repowise.cli import rewrite_hook+from repowise.cli.hook_ledger import BAILED, REWRITTEN++SESSION = "sess-rewrite"+++def repo(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ (tmp_path / ".repowise").mkdir()+ # One ledger connection is cached per repo path for the life of the+ # process; the fixture gives each test its own path, so nothing leaks.+ monkeypatch.setattr(rewrite_hook, "_POSIX_HOST", True)+ return tmp_path+++def _fire(repo: Path, command: str, monkeypatch: pytest.MonkeyPatch, tool: str = "Bash") -> None:+ payload = json.dumps(+ {+ "hook_event_name": "PreToolUse",+ "tool_name": tool,+ "tool_input": {"command": command},+ "cwd": str(repo),+ "session_id": SESSION,+ }+ )+ monkeypatch.setattr("sys.stdin", io.StringIO(payload))+ monkeypatch.setattr("sys.argv", ["repowise-rewrite"])+ with pytest.raises(SystemExit):+ rewrite_hook.main()+++def _rows(repo: Path) -> dict[tuple[str, str], int]:+ db = repo / ".repowise" / "sessions" / "sessions.db"+ con = sqlite3.connect(db)+ try:+ return {+ (outcome, reason): calls+ for outcome, reason, calls in con.execute(+ "SELECT outcome, reason, calls FROM rewrite_runs"+ )+ }+ finally:+ con.close()+++def test_a_rewrite_is_counted_under_its_family(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _fire(repo, "pytest -q", monkeypatch)+ assert _rows(repo) == {(REWRITTEN, "test_output"): 1}+++def test_an_unrecognized_command_is_counted_as_such(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ _fire(repo, "./deploy.sh --prod", monkeypatch)+ assert _rows(repo) == {(BAILED, rewrite_hook.BAIL_UNRECOGNIZED): 1}+++def test_a_shape_bail_is_told_apart_from_a_family_bail(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The distribution this surface exists to measure: shape versus family."""+ _fire(repo, "pytest -q > results.txt", monkeypatch)+ _fire(repo, "./deploy.sh", monkeypatch)+ rows = _rows(repo)+ assert rows[(BAILED, rewrite_hook.BAIL_SHAPE)] == 1+ assert rows[(BAILED, rewrite_hook.BAIL_UNRECOGNIZED)] == 1+++def test_counts_aggregate_rather_than_dedup(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """An INSERT-OR-IGNORE would answer "one of each" and measure nothing."""+ for _ in range(3):+ _fire(repo, "./deploy.sh", monkeypatch)+ assert _rows(repo)[(BAILED, rewrite_hook.BAIL_UNRECOGNIZED)] == 3+++def test_a_disabled_repo_says_so_rather_than_looking_unrecognized(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ (repo / ".repowise" / "config.yaml").write_text(+ "distill:\n commands:\n enabled: false\n", encoding="utf-8"+ )+ _fire(repo, "pytest -q", monkeypatch)+ assert _rows(repo) == {(BAILED, rewrite_hook.BAIL_DISABLED): 1}+++def test_a_family_turned_off_is_its_own_reason(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ (repo / ".repowise" / "config.yaml").write_text(+ "distill:\n commands:\n families:\n test_output: off\n", encoding="utf-8"+ )+ _fire(repo, "pytest -q", monkeypatch)+ assert _rows(repo) == {(BAILED, rewrite_hook.BAIL_FAMILY_OFF): 1}+++def test_rows_carry_the_emitting_build(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """Without it, two installs emitting into one repo are indistinguishable."""+ from repowise.cli.hook_ledger import emitting_build++ _fire(repo, "pytest -q", monkeypatch)+ con = sqlite3.connect(repo / ".repowise" / "sessions" / "sessions.db")+ try:+ assert con.execute("SELECT build FROM rewrite_runs").fetchone()[0] == emitting_build()+ finally:+ con.close()+++def test_nothing_is_written_outside_a_repowise_repo(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """The hook is installed globally. A directory that never opted in gets no+ sidecar, which is also why those commands can never be counted."""+ monkeypatch.setattr(rewrite_hook, "_POSIX_HOST", True)+ _fire(tmp_path, "pytest -q", monkeypatch)+ assert not (tmp_path / ".repowise").exists()+++def test_a_payload_with_no_session_id_writes_nothing(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """A row nothing can be attributed to is not worth the write."""+ payload = json.dumps(+ {+ "hook_event_name": "PreToolUse",+ "tool_name": "Bash",+ "tool_input": {"command": "pytest -q"},+ "cwd": str(repo),+ }+ )+ monkeypatch.setattr("sys.stdin", io.StringIO(payload))+ monkeypatch.setattr("sys.argv", ["repowise-rewrite"])+ with pytest.raises(SystemExit):+ rewrite_hook.main()+ assert not (repo / ".repowise" / "sessions").exists()diff --git a/tests/unit/distill/test_rewrite_perf.py b/tests/unit/distill/test_rewrite_perf.pyindex 3cdbb8438..f82f7de88 100644--- a/tests/unit/distill/test_rewrite_perf.py+++ b/tests/unit/distill/test_rewrite_perf.py@@ -112,6 +112,48 @@ def test_p95_under_150ms(tmp_path: Path) -> None:assert p95 < 150, f"repowise-rewrite p95 {p95:.1f} ms >= 150 ms"+#: Budget for an invocation that also writes its ledger row. Higher than the+#: 150 ms above, and the gap is the instrument: counting the hook costs a+#: ``sqlite3`` import, a connect and an upsert, measured here at roughly 15 ms+#: per shell command. That is the price of the surface being measurable at all+#: — an ``updatedInput`` rewrite leaves no transcript trace, so without the row+#: the busiest hook in the system reports nothing.+#:+#: The number is a guard against the *next* regression, not an endorsement of+#: this one. If it needs raising again, the write is the thing to fix.+_LEDGERED_BUDGET_MS = 200+++def test_a_ledgered_invocation_stays_under_budget(tmp_path: Path) -> None:+ """The path an agent in an indexed repo actually takes.++ Every other timing test here sends a payload with no ``session_id``, which+ skips the ledger write entirely — so they measure a path no real session+ uses and would not have noticed the write at all.+ """+ (tmp_path / ".repowise").mkdir()+ cmd = _hook_invocation()+ payload = json.dumps(+ {+ "hook_event_name": "PreToolUse",+ "tool_name": "Bash",+ "tool_input": {"command": "pytest -x"},+ "cwd": str(tmp_path),+ "session_id": "perf",+ }+ )+ subprocess.run(cmd, input=payload, capture_output=True, text=True)++ p95, outputs = _p95(cmd, payload)+ assert all("repowise distill --source hook-bash pytest -x" in out for out in outputs)+ # Guard the guard: a budget met by not writing the row would pass forever.+ db = tmp_path / ".repowise" / "sessions" / "sessions.db"+ assert db.exists(), "the probe never reached the ledger write it is timing"+ assert p95 < _LEDGERED_BUDGET_MS, (+ f"a ledgered rewrite p95 {p95:.1f} ms >= {_LEDGERED_BUDGET_MS} ms"+ )++@pytest.mark.parametrize("command", _PERF_COMMANDS)def test_lexer_shapes_stay_under_budget(tmp_path: Path, command: str) -> None:"""No command shape may blow the budget, whatever the lexer walks.diff --git a/tests/unit/sessions/test_injection_feedback.py b/tests/unit/sessions/test_injection_feedback.pyindex efab61e77..b9c05b781 100644--- a/tests/unit/sessions/test_injection_feedback.py+++ b/tests/unit/sessions/test_injection_feedback.py@@ -298,7 +298,7 @@ async def test_drained_orphan_is_counted_as_neither_side(session, tmp_path):def test_hook_written_injections_table_is_schema_compatible(tmp_path):"""The hook's raw CREATE TABLE and the staging schema must agree."""- from repowise.cli.commands.augment_cmd.ledger import _record_injections+ from repowise.cli.hook_ledger import _record_injections# Hook writes first (cold sidecar), store opens the same DB afterwards._record_injections(tmp_path, "sess-1", ["d1"], node_id="src/a.py")