Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.md
index 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-line
nudge naming the skeleton's token cost — was retired after 516 firings
showed 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 same
file warns that earlier excerpts predate the edit.
- **Search digest** — grep floods (≥50 lines) get a compact grouped-by-file
diff --git a/docs/agent/HOOKS.md b/docs/agent/HOOKS.md
index 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` (especially
with `replace_all`) or a `Write` could touch bodies it never saw. Editing such a
file 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 an
architectural decision (via `decision_node_links`), it gets a one-line notice
with the rationale, at most once per session per decision and only a few times
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index 99ea36229..8b47ead01 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -252,8 +252,26 @@ means every key below is off.
```yaml
hooks:
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 a
file instead of the file, for an unbounded Read of a large indexed file, once
per 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__.py
index 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 heavier
from 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.py
index 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 = command
self.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[st
class 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
+
@abstractmethod
def 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.py
index 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 annotations
import json
+import os
import os.path
from 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] = True
def 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 None
cwd = 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 None
diff --git a/packages/cli/src/repowise/cli/agent_adapters/codex.py b/packages/cli/src/repowise/cli/agent_adapters/codex.py
index 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 None
cwd = 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__.py
index 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.py
index 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_cache
from pathlib import Path
from 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_build
def _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.py
index 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 Path
import click
-from repowise.cli.agent_adapters.codex import SHELL_TOOL_NAMES
+from repowise.cli.agent_adapters import adapter_for
from ._shared import HookResult, as_result
from .bash_staleness import _handle_bash_post
@@ -102,14 +102,28 @@ from .served_reads import _handle_mcp_read_post, _log_read_after_served
from .session_start import _handle_claude_session_start
from .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: boo
if not session_id:
return
try:
+ from repowise.cli.hook_ledger import _record_hook_run
+
from ._shared import _find_repo_root
- from .ledger import _record_hook_run
repo_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: boo
return
-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}"):
return
payload: 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 second
caller within the TTL sees a fresh marker and stays silent. Fail-open — any
error 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 hashlib
import os
@@ -332,33 +354,36 @@ def _handle_post_tool_use(
:class:`HookResult` themselves; every other branch yields plain additional
context and keeps returning ``str | None``, which :func:`as_result` lifts
here, 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. Never
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py b/packages/cli/src/repowise/cli/commands/augment_cmd/decision_inject.py
index 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 += 1
if 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: dic
conn.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: dic
line += 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) -> str
line += "."
if session_id:
+ from repowise.cli.hook_ledger import _claim_ledger
+
from ._shared import _ledger_key
- from .ledger import _claim_ledger
claimed, 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.py
index 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.py
new file mode 100644
index 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.py
deleted file mode 100644
index 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, 0
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.py b/packages/cli/src/repowise/cli/commands/augment_cmd/read_skeleton.py
index 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 elided
span 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 MCP
responses. Reads were the last unfiltered surface. Reading the file a second
time 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 same
file 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 its
trailing 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 os
import re
import sqlite3
-from pathlib import Path
from 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 Offer
if 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 rows
if 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.py
index 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:
+ continue
def _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 — two
hook events can land within one clock tick on Windows, and ordering is
the 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 fresh
if 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 None
if 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"] += 1
state["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 = None
for 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 = payload
except 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 True
def _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 hash
that 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.py
new file mode 100644
index 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 _write
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/reread.py b/packages/cli/src/repowise/cli/commands/augment_cmd/reread.py
new file mode 100644
index 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.py
index 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 never
appears 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.py
index 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, its
match count, two anchored line numbers per file, and an explicit
``(N more files, M matches)`` tail. The agent can see what was dropped and
re-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`` at
all. 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 None
if 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.py
index 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(
return
start, end = window
if _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.py
index 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 annotations
import json
from pathlib import Path
-from ._shared import _find_repo_root
+from ._shared import _find_repo_root, emitting_build
from .bash_staleness import _read_in_flight_marker
from .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.py
index 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_root
if 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 text
so 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:
return
try:
+ 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.py
index 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_CATEGORIES
console.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.py
index 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.py
index 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.py
index 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: floa
try:
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.py
new file mode 100644
index 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:
+ pass
diff --git a/packages/cli/src/repowise/cli/rewrite_hook.py b/packages/cli/src/repowise/cli/rewrite_hook.py
index 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, REWRITTEN
from 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 None
chain: tuple[str, ...] = ()
if split is not None:
head_command, needs_inner_shell = split
family = _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], True
else:
- 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, None
enabled, 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_root
family_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-identical
JSON, 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):
raise
except 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.py
index 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 off
diff --git a/packages/core/src/repowise/core/sessions/footprint.py b/packages/core/src/repowise/core/sessions/footprint.py
new file mode 100644
index 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 footprint
diff --git a/packages/core/src/repowise/core/sessions/staging.py b/packages/core/src/repowise/core/sessions/staging.py
index 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.py
index 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.py
index 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 Path
import pytest
+from repowise.cli.agent_adapters.claude_code import (
+ ClaudeCodeAdapter,
+ _recorded_client_version,
+)
from repowise.cli.commands.augment_cmd import _handle_post_tool_use
from 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 None
state["skeletonized"].clear()
- served, _ = _skeleton_replacement(*args, state, edited_since_read=True)
+ served, _ = _skeleton_replacement(*args, state, adapter, edited_since_read=True)
assert served is None
diff --git a/tests/unit/cli/test_augment_reread.py b/tests/unit/cli/test_augment_reread.py
new file mode 100644
index 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"]) == 12
diff --git a/tests/unit/cli/test_augment_search_digest.py b/tests/unit/cli/test_augment_search_digest.py
index 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 patch
import 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_digest
from 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 None
def 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 None
def 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 None
def 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 None
def 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 True
def 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.py
index 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 sqlite3
from pathlib import Path
from repowise.cli.commands.augment_cmd import served_reads
-from repowise.cli.commands.augment_cmd.ledger import _claim_ledger
from 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.py
index e630f6eda..f6bc2e16e 100644
--- a/tests/unit/cli/test_codex_plugin.py
+++ b/tests/unit/cli/test_codex_plugin.py
@@ -4,12 +4,13 @@ import json
import re
from pathlib import Path
+from repowise.cli.agent_adapters import adapter_for
from 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_NAMES
ROOT = 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_NAMES
assert 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.py
index 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"] == SESSION
assert "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 None
state = _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.py
new file mode 100644
index 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.py
index 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.py
index 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")