elliot-stack 1.0.37 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.37",
+  "version": "1.0.39",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-read-claude-session-history/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-read-claude-session-history
-version: 1.0.4
+version: 1.2.1
 description: >-
   (read-claude-session-history) Invoke for ANY task involving Claude Code
   session history, transcripts, or .jsonl files - this is the only way to read,
@@ -9,7 +9,8 @@ description: >-
   compact"), advisor response retrieval ("what did the advisor say"), subagent
   output collection ("get all subagent finals"), cross-project session search by
   keyword, session listing and triage, UUID and title lookup, resume-command
-  generation, file-edit and tool-call forensics, session diff between two
+  generation, file-edit and tool-call forensics, tool- and skill-usage tallies
+  ("which skills do I actually use"), session diff between two
   sessions or subagents, weekly work journal, day timeline of activity blocks
   and idle gaps, engagement/attention-time accounting (active vs elapsed time,
   break detection, parallel-chat-safe totals), recovering from .claude-backups
@@ -95,12 +96,14 @@ What are you trying to do?
 │  ├─ One session ─────────────────────────────── --mode search --file …
 │  ├─ One project ─────────────────────────────── --mode search --cwd …
 │  ├─ All projects ────────────────────────────── --mode search --all-projects
+│  ├─ Expand a wide search to full windows ───── --full
 │  └─ Filter to user msgs / tool-use inputs ──── --role user --in tool_use
 │
 ├─ Forensics on a session
 │  ├─ Chronological tool-call log ────────────── --mode changelog
 │  ├─ Every file touched ─────────────────────── --mode file-edits
-│  └─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│  ├─ Every tool call (optionally filtered) ──── --mode tool-calls --tool Bash,Edit
+│  └─ Which tools/skills do I actually use? ───── --mode tool-usage (+ scope; --tool Skill)
 │
 ├─ Subagent (fan-out) work
 │  ├─ List spawned subagents ─────────────────── --mode subagent-list
@@ -126,7 +129,7 @@ What are you trying to do?
 | `advisor` | `--file` | All `advisor_tool_result` payloads |
 | `pre-compact` | `--file` | 40 exchanges before the most recent `/compact` |
 | `dump` | `--file` | Human-readable dump (auto-degrades on transcripts >5MB) |
-| `search` | `--query` + scope | Matches windowed for context (supports `--role`, `--in text|tool_use|thinking|all`) |
+| `search` | `--query` + scope | Single file: full match windows. Wide scope (`--cwd`/`--project`/`--all-projects`): per-session summary by default; `--full` expands to windows. Either way the full view is bounded by a char budget and degrades back to a summary (with a note) if it would overflow. Supports `--role`, `--in text\|tool_use\|tool_result\|thinking\|all` |
 | `debug` | `--file` | Entry/block type distributions + probes |
 | `brief` | `--file` | 6-line summary: uuid·project·mtime·status / intent / last / edits / tools / subagents |
 | `list` | `--cwd` or `--all-projects` | Rich table: mtime, size, uuid, msg count, flags, status, title |
@@ -136,6 +139,7 @@ What are you trying to do?
 | `changelog` | `--file` | `HH:MM:SS  TOOL  one-line-summary`, day-grouped |
 | `file-edits` | `--file` | Unique paths sorted with op tags |
 | `tool-calls` | `--file` (+ `--tool` filter) | Timestamped per-call blocks |
+| `tool-usage` | `--file` or scope (+ `--tool` filter, `--include-subagents`) | Tool-call tallies by name; `Skill` calls sub-tallied by skill name (counts real invocations, not text) |
 | `subagent-list` | `--file` | List sibling subagents with agentType + description |
 | `subagent-finals` | `--file` | Every subagent's final assistant message |
 | `subagent-tools` | `--subagent` | Forensics on one subagent |
@@ -152,16 +156,17 @@ What are you trying to do?
 - `--root {live|mirror|snapshot-24h|snapshot-1w|snapshot-1mo|<abs-path>}` — read from a `.claude-backups` mirror or snapshot instead of live. Default `live`.
 - `--cwd <path>` — single-project scope. Use the original working directory (e.g. `"C:\Users\2supe\Other Claude Code"`).
 - `--all-projects` — walk every project under `--root`.
-- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
+- `--project <name>` — filter projects by name substring, case-insensitive, matches encoded or decoded form (`--project keel`, `--project "Other Claude Code"`). Works on `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`, `tool-usage`. Use this instead of `--cwd` when you know the project's name but not its exact path. (Note: for `engagement`, scope filters which sessions are *reported* — the attention stream is always computed across all projects so parallel chats never double-count.)
 - `--file <path>` — single-session scope.
+- `--full` — for wide-scope `search` (`--cwd`/`--project`/`--all-projects`), expand the default per-session summary into full match windows. Single-file searches (`--file`) are always full and ignore this flag. In every case the full view is bounded by a character budget (~10k tokens); if the windows would overflow it, the output degrades back to the summary with a note.
 - `--since <spec>` / `--until <spec>` — accepts ISO date, ISO datetime, relative (`30m`, `24h`, `7d`, `1w`, `1mo`), named (`today`, `yesterday`, `now`).
 - `--date <spec>` — single-day window for `timeline` (`--date yesterday`, `--date 2026-06-01`).
 - `--gap <spec>` — idle-gap threshold for `timeline` blocks (`15m` default, `1h`).
 - `--break <spec>` — break threshold for `engagement` (`10m` default; `5m` strict, `20m` forgiving). Gaps between your prompts longer than this count as breaks unless you replied right after Claude finished working.
 - `--tz <spec>` — display timezone override (IANA name, `UTC`, or offset like `-4`). Default: system local time.
 - `--format json` (or `--json`) — structured JSON output on every mode (except the legacy `--list`/`--list-subagents` aliases). Pipe-friendly: paths are strings, timestamps ISO.
-- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, and `engagement`.
-- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`.
+- `--exclude-current` — drop the current session (detected via `CLAUDE_SESSION_ID`) from `list`, `journal`, `search`, `count`, `timeline`, `engagement`, and `tool-usage`. Useful for `tool-usage` so the very commands you're running now don't skew the tally.
+- `--include-subagents` — fold subagent finals into `brief`, `last`, `dump` output, each tagged `[subagent <id-short> · <agentType>]`. For `tool-usage`, folds each session's subagent `tool_use` calls into the tally (the subagent is not counted as a separate session).
 - `--force-dump` — bypass the 5 MB `dump` guard.
 - `-n N` — count modifier (default 5 for `last`, 80 for `dump`, 10 for `resume-prev`).
 
@@ -202,6 +207,7 @@ See `references/recipes.md` → "Deletion-incident recovery" for the full playbo
 | "How much did I actually work today?" | `--mode engagement --date today` |
 | "How much time on Keel today?" | `--mode engagement --project keel --date today` |
 | "How long did that session take me?" | `--mode engagement --file <session.jsonl>` |
+| "Which skills do I actually use?" | `--mode tool-usage --all-projects --tool Skill` |
 | Feed session data into a script | any mode + `--format json` |
 
 See `references/recipes.md` for fuller multi-step workflows.

package/skills/estack-read-claude-session-history/references/modes.md

@@ -15,7 +15,8 @@ python read_transcript.py [--root <root>] [--cwd <path> | --all-projects | --pro
 ```
 
 Global flag notes:
-- `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`. Exit 1 when nothing matches.
+- `--since <spec>` / `--until <spec>` — the time window is half-open `[since, until)`: `since` is inclusive, `until` is exclusive, so an event stamped exactly at `--until` is not included. This holds for every message-level mode (`search`, `timeline`, `engagement`, `tool-usage`). Session-level modes (`list`, `journal`, `count`) instead filter whole sessions by file mtime, so a session last written at or before `--until` is shown.
+- `--project <name>` — case-insensitive substring filter on project directory names (encoded or decoded form). Applies to `list`, `journal`, `search`, `count`, `find`, `timeline`, `engagement`, `tool-usage`. Exit 1 when nothing matches.
 - `--tz <spec>` — display timezone: IANA name (`America/New_York`), `UTC`, or fixed offset (`+5`, `-4`, `+05:30`, `UTC-4`). Default is system local time. All displayed timestamps AND `--since/--until/--date` interpretation use this zone.
 - `--format json` (alias `--json`) — structured output on every mode except the legacy `--list`/`--list-subagents` aliases. Shapes per mode are listed below.
 
@@ -188,17 +189,27 @@ python read_transcript.py --cwd <path> --mode search --query "<q>"
 
 # All projects
 python read_transcript.py --all-projects --mode search --query "<q>"
+
+# Expand a wide search to full match windows
+python read_transcript.py --all-projects --mode search --query "<q>" --full
 ```
 
 Flags:
 - `--role {user,assistant,both}` (default `both`)
-- `--in {text,tool_use,thinking,all}` (default `text`)
+- `--in {text,tool_use,tool_result,thinking,all}` (default `text`)
+- `--full` — wide scope only (see Output below)
 - `--since` / `--until`
 
 `--in tool_use` searches the `name + JSON-stringified input` of every `tool_use` block — useful for finding "the session where I ran `git push --force`".
 
 `--in thinking` searches `thinking` blocks (model reasoning).
 
+`--in tool_result` searches the text content of `tool_result` blocks (what tools returned). `--in all` covers text + tool_use + tool_result + thinking.
+
+**Output.** A single-file search (`--file`) prints full match windows. A wide search (`--cwd` / `--project` / `--all-projects`) prints a **per-session summary** by default — one line per session (`mtime · uuid8 · project · hit-count · first snippet`), sorted newest first, with a header counting total hits and sessions. This keeps cross-project searches well under the harness's ~25k-token Read cap instead of dumping tens of thousands of tokens that the reader then refuses. Add `--full` to expand a wide search into full windows. In every case the full view (single-file, or wide + `--full`) is bounded by a character budget (~10k tokens) and degrades back to the summary with a note if it would overflow — so even a single huge session can't blow the Read cap. Sessions past the 200-line summary cap are counted in a footer, never silently dropped. JSON mirrors this: wide scope returns compact per-session metadata (`uuid`, `project`, `hits`, `first_snippet`) by default, full per-match objects (with `window`) under `--full`.
+
+Progress (`Searching i/N…`) prints to stderr only when stderr is an interactive terminal — captured/piped runs stay clean.
+
 ### `count`
 
 Count sessions matching a query.
@@ -364,6 +375,37 @@ path, first, last, elapsed_minutes, active_minutes, active_seconds, ratio,
 user_messages}], totals: {sessions, active_minutes, active_seconds,
 span_minutes}, stream_breaks: [{start, end, minutes}]}`.
 
+### `tool-usage`
+
+Tally tool calls by tool name; `Skill` calls are sub-tallied by skill name. Answers "which tools / skills do I actually use".
+
+```bash
+# Every tool across one session
+python read_transcript.py --file <path> --mode tool-usage
+
+# Skill usage across every project (the "what skills do I actually use" question)
+python read_transcript.py --all-projects --mode tool-usage --tool Skill
+
+# One project, last 30 days
+python read_transcript.py --project keel --mode tool-usage --since 30d
+```
+
+Scope is `--file` (one session) or `--cwd` / `--project` / `--all-projects`. `--tool` narrows to a comma-separated subset (e.g. `--tool Skill` for a skills-only view, `--tool Bash,Edit`). `--since/--until` bound the calls by their own timestamp (not file mtime — a session modified after `--until` is still read so in-window calls are counted). `--exclude-current` drops the current session so the commands you're running now don't skew the count. `--include-subagents` folds each session's `agent-*.jsonl` tool calls into its tally — needed to capture skills invoked inside fan-out subagents (the subagent is not counted as a separate session).
+
+Why this exists: it counts real **invocations** — a `tool_use` block whose `name` is the tool (and, for skills, `input.skill`). Text-based modes like `search --in tool_use` and `count` match the *string* "ast-grep" wherever it appears (a `CLAUDE.md` instruction, a bash command, even your own search commands this session), so they over-count. `tool-usage` keys on structure and is immune to that.
+
+Text output: one `<count>  <ToolName>` row per tool, sorted by count descending; under the `Skill` row, a tree of `<count> <skill-name>` sub-rows. A leading line gives the grand total and number of sessions with calls.
+
+```
+Tool calls (66 total across 43 session(s)):
+     66  Skill
+         ├ 38 manage-e-stack
+         ├ 9 commit
+         └ ...
+```
+
+JSON shape: `{total, sessions, tools: [{tool, count}], skills: [{skill, count}]}` (both lists sorted by count descending; `skills` is empty unless `Skill` calls were counted).
+
 ---
 
 ## Comparison modes
@@ -401,8 +443,9 @@ Output is prefixed `A>` / `B>` (or with subagent id shorts).
 | `resume-cmd` | `{uuid, path, project, encoded, command}` |
 | `changelog` | `[{timestamp, tool, summary}]` |
 | `tool-calls` / `subagent-tools` | `[{timestamp, tool, summary, input}]` |
+| `tool-usage` | `{total, sessions, tools: [{tool, count}], skills: [{skill, count}]}` |
 | `file-edits` / `subagent-files` | `[{path, ops}]` |
-| `search` | `[{session, mtime_iso, role, where, timestamp, window}]` |
+| `search` | single-file or `--full`: `[{session, mtime_iso, role, where, timestamp, window}]`; wide scope default: `[{session, uuid, project, mtime_iso, hits, first_snippet}]` |
 | `count` | `{sessions, messages, matches}` |
 | `subagent-list` | `[{id, agentType, description, path, size_kb, mtime_iso}]` |
 | `subagent-finals` | `[{id, agentType, text}]` |

package/skills/estack-read-claude-session-history/references/recipes.md

@@ -245,6 +245,35 @@ python "$PY" --file <matching-session>.jsonl --mode tool-calls --tool Bash
 
 ---
 
+## 8b. "Which skills (or tools) do I actually use?" — true invocation counts
+
+To decide which skills to keep or prune, you need real usage counts. Do **not**
+use `search`/`count` for this: they match the *string* (a skill name in a
+`CLAUDE.md` instruction, a bash command, even the search commands you're running
+right now), so they over-count. `tool-usage` counts real `tool_use` invocations —
+for skills, the `Skill` block's `input.skill` — and is immune to that.
+
+```bash
+# Skills you actually invoked, ranked, across every project
+python "$PY" --all-projects --mode tool-usage --tool Skill
+
+# All tools (skills broken out under the Skill row)
+python "$PY" --all-projects --mode tool-usage
+
+# One project, last 30 days, excluding this very session
+python "$PY" --project keel --mode tool-usage --tool Skill --since 30d --exclude-current
+
+# Machine-readable: skills sorted by count
+python "$PY" --all-projects --mode tool-usage --tool Skill --format json \
+  | python -c "import json,sys; [print(s['count'], s['skill']) for s in json.load(sys.stdin)['skills']]"
+```
+
+A skill missing from the output was never invoked in that scope — a positive
+inventory ("here is everything I used, and X isn't in it") is stronger evidence
+of non-use than a search that simply returns nothing.
+
+---
+
 ## 9. Resume previous session in the current project
 
 If you just `cd`'d into a project and want to pick up where you left off:

package/skills/estack-read-claude-session-history/scripts/lib/parser.py

@@ -282,9 +282,10 @@ def filter_by_time(
         # Strip tzinfo for naive comparison
         if ts.tzinfo is not None:
             ts = ts.replace(tzinfo=None)
+        # Half-open window [since, until): since inclusive, until exclusive.
         if since is not None and ts < since:
             continue
-        if until is not None and ts > until:
+        if until is not None and ts >= until:
             continue
         out.append(m)
     return out

package/skills/estack-read-claude-session-history/scripts/lib/search.py

@@ -70,6 +70,16 @@ def _entry_search_text(obj: dict, in_channel: str) -> list[tuple[str, str]]:
     return out
 
 
+def _show_progress(progress: bool) -> bool:
+    """Progress is for a live terminal only.
+
+    When stderr is captured to a file or pipe (e.g. by a tool harness), the
+    per-file ``Searching i/N…\\r`` stream lands as hundreds of literal lines and
+    inflates the captured output. Suppress it unless stderr is an interactive TTY.
+    """
+    return progress and sys.stderr.isatty()
+
+
 def _window(text: str, q: str, n: int = 200) -> str:
     """Return up to n chars of context around the first match of q."""
     if not text or not q:
@@ -90,7 +100,7 @@ def search_session(
     path: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
 ) -> list[Match]:
@@ -117,9 +127,10 @@ def search_session(
                 continue
             if ts_dt.tzinfo is not None:
                 ts_dt = ts_dt.replace(tzinfo=None)
+            # Half-open window [since, until): since inclusive, until exclusive.
             if since is not None and ts_dt < since:
                 continue
-            if until is not None and ts_dt > until:
+            if until is not None and ts_dt >= until:
                 continue
         for where, text in _entry_search_text(obj, in_channel):
             if q in text.lower():
@@ -138,15 +149,19 @@ def search_project(
     project_dir: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
     progress: bool = True,
 ) -> Iterator[Match]:
     """Search every transcript in a project directory, newest first."""
-    files = _paths.list_transcripts(project_dir, since=since, until=until)
+    # Filter files by mtime >= since only. A session last written after `until`
+    # may still contain messages inside the window, so we don't bound file mtime
+    # above — search_session() applies the `until` cut per-message instead.
+    files = _paths.list_transcripts(project_dir, since=since)
+    show = _show_progress(progress)
     for i, f in enumerate(files, 1):
-        if progress:
+        if show:
             print(
                 f"Searching {i}/{len(files)}: {f.name}...",
                 file=sys.stderr,
@@ -156,8 +171,11 @@ def search_project(
             for m in search_session(f, query, role, in_channel, since, until):
                 yield m
         except Exception as e:
-            print(f"\nError reading {f.name}: {e}", file=sys.stderr)
-    if progress:
+            # Lead with \n only to clear an active \r progress line; when progress
+            # is suppressed there's no line to clear, so don't add a blank one.
+            prefix = "\n" if show else ""
+            print(f"{prefix}Error reading {f.name}: {e}", file=sys.stderr)
+    if show:
         print(file=sys.stderr)
 
 
@@ -165,14 +183,14 @@ def search_all_projects(
     root: Path,
     query: str,
     role: Literal["user", "assistant", "both"] = "both",
-    in_channel: Literal["text", "tool_use", "thinking", "all"] = "text",
+    in_channel: Literal["text", "tool_use", "tool_result", "thinking", "all"] = "text",
     since: datetime | None = None,
     until: datetime | None = None,
     progress: bool = True,
 ) -> Iterator[Match]:
     """Walk every project directory under root."""
     for project_dir in _paths.list_projects(root):
-        if progress:
+        if _show_progress(progress):
             print(f"--- {project_dir.name} ---", file=sys.stderr)
         yield from search_project(
             project_dir, query, role, in_channel, since, until, progress

package/skills/estack-read-claude-session-history/scripts/read_transcript.py

@@ -33,6 +33,16 @@ from lib import search as S  # noqa: E402
 from lib import subagents as SA  # noqa: E402
 
 
+# Wide-scope search output budget. Full match windows across many sessions can
+# balloon past the harness's ~25k-token Read cap, forcing a write-then-can't-read
+# round trip. We summarize by default and degrade --full back to a summary once
+# the rendered text would exceed this many characters (~10k tokens at ~4 ch/tok).
+SEARCH_CHAR_BUDGET = 40_000
+# Cap session lines in the summary view so the summary itself stays bounded.
+# Overflow is counted and noted, never silently dropped.
+SEARCH_SUMMARY_SESSION_CAP = 200
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Legacy mode implementations (kept byte-identical to v1 for backwards-compat)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -107,24 +117,6 @@ def mode_dump(lines, limit=80):
     return "\n\n".join(output)
 
 
-def mode_search_legacy(lines, query: str):
-    """Legacy single-file search: assistant text only, case-insensitive."""
-    messages = PR.get_messages(lines)
-    results = []
-    q = query.lower()
-    for m in messages:
-        if m["role"] == "assistant":
-            combined = " ".join(m["texts"])
-            if q in combined.lower():
-                results.append(combined)
-    if not results:
-        return None
-    output = [f"=== {len(results)} match(es) for '{query}' ===\n"]
-    for i, r in enumerate(results, 1):
-        output.append(f"--- Match #{i} ---\n{r[:1500]}")
-    return "\n\n".join(output)
-
-
 def mode_debug(lines):
     output = []
     type_counts: dict[str, int] = {}
@@ -579,6 +571,81 @@ def mode_tool_calls(path: Path, tool_filter: set[str] | None, fmt: str = "text")
     return "\n".join(out).lstrip("\n")
 
 
+def _one_line(text: str, n: int) -> str:
+    """Collapse whitespace to a single line and truncate to n chars."""
+    s = " ".join((text or "").split())
+    return s[:n] + ("…" if len(s) > n else "")
+
+
+def _sessions_by_mtime(matches) -> list:
+    """Group matches by session, return (session_path, matches) sorted newest first."""
+    by_session: dict[Path, list] = {}
+    for m in matches:
+        by_session.setdefault(m.session_path, []).append(m)
+    return sorted(by_session.items(), key=lambda kv: kv[1][0].mtime, reverse=True)
+
+
+def _render_search_full(matches) -> str:
+    """Full per-match windows grouped by session, newest first (the detailed view)."""
+    out = []
+    for sp, ms in _sessions_by_mtime(matches):
+        out.append(f"{'=' * 60}\nSession: {sp.name}  ({_fmt_mtime(ms[0].mtime)})\n{'=' * 60}")
+        for i, m in enumerate(ms, 1):
+            label = f"--- Match #{i} [{m.role}/{m.where}] ---"
+            out.append(f"{label}\n{m.window_text[:1500]}")
+    return "\n\n".join(out)
+
+
+def _render_search_summary(query: str, matches, already_full: bool = False) -> str:
+    """One line per session: mtime · uuid8 · project · hits · first snippet.
+
+    Every hit is counted in the header; sessions past the cap are counted in a
+    footer note, never silently dropped. When ``already_full`` is set (the
+    summary is a degraded ``--full`` result), the footer drops the "use --full"
+    suggestion the caller already tried.
+    """
+    sessions = _sessions_by_mtime(matches)
+    total_hits = len(matches)
+    total_sessions = len(sessions)
+    shown = sessions[:SEARCH_SUMMARY_SESSION_CAP]
+    hit_w = "match" if total_hits == 1 else "matches"
+    sess_w = "session" if total_sessions == 1 else "sessions"
+    lines = [f'=== "{query}": {total_hits} {hit_w} across {total_sessions} {sess_w} ===']
+    for sp, ms in shown:
+        uuid8 = sp.stem[:8]
+        project = P.decode_project_name(sp.parent.name)
+        snippet = _one_line(ms[0].window_text, 120)
+        n = len(ms)
+        # Pad the unit so singular ("hit ") and plural ("hits") align the snippet column.
+        hits = f'{n:>4} hit' + ('s' if n != 1 else ' ')
+        lines.append(f'{_fmt_mtime(ms[0].mtime)}  {uuid8}  {project[:28]:<28}  {hits}  · "{snippet}"')
+    if total_sessions > len(shown):
+        lines.append(
+            f"… and {total_sessions - len(shown)} more session(s) not shown — "
+            f"narrow with --project or a tighter --query."
+        )
+    # On a degrade (already_full) the [note] prefix already carries the actionable
+    # hint, so don't append a second — possibly conflicting — guidance line.
+    if not already_full:
+        lines.append("Use --full for match windows, or narrow with --project / a tighter --query.")
+    return "\n".join(lines)
+
+
+def _search_summary_json(matches) -> list:
+    """Compact per-session metadata (no windows) for structured consumers."""
+    return [
+        {
+            "session": str(sp),
+            "uuid": sp.stem,
+            "project": P.decode_project_name(sp.parent.name),
+            "mtime_iso": _fmt_mtime(ms[0].mtime),
+            "hits": len(ms),
+            "first_snippet": _one_line(ms[0].window_text, 120),
+        }
+        for sp, ms in _sessions_by_mtime(matches)
+    ]
+
+
 def mode_search_v2(
     root: Path,
     cwd: str | None,
@@ -593,6 +660,7 @@ def mode_search_v2(
     fmt: str = "text",
     exclude_current: bool = False,
     current_uuid: str | None = None,
+    full: bool = False,
 ):
     """Cross-scope search with role/in-channel filters."""
     matches: list = []
@@ -607,12 +675,21 @@ def mode_search_v2(
         pd = P.find_project_dir(cwd, root)
         matches = list(S.search_project(pd, query, role, in_channel, since, until))
     else:
-        return "Provide --file, --cwd, --project, or --all-projects"
+        # Unreachable from the CLI (the dispatch guarantees a scope flag), but keep
+        # the direct-call contract honest: JSON callers get a JSON object.
+        msg = "Provide --file, --cwd, --project, or --all-projects"
+        return {"error": msg} if fmt == "json" else msg
 
     if exclude_current and current_uuid:
         matches = [m for m in matches if m.session_path.stem != current_uuid]
 
+    # Single-file scope is narrow and won't overflow — render full by default.
+    # Wide scope (cwd / project / all-projects) summarizes unless --full is set.
+    wide = file_path is None
+
     if fmt == "json":
+        if wide and not full:
+            return _search_summary_json(matches)
         return [
             {
                 "session": str(m.session_path),
@@ -628,17 +705,25 @@ def mode_search_v2(
     if not matches:
         return f"No matches for '{query}'."
 
-    # Group by session for readable output
-    by_session: dict[Path, list] = {}
-    for m in matches:
-        by_session.setdefault(m.session_path, []).append(m)
-    out = []
-    for sp, ms in by_session.items():
-        out.append(f"\n{'=' * 60}\nSession: {sp.name}  ({_fmt_mtime(ms[0].mtime)})\n{'=' * 60}")
-        for i, m in enumerate(ms, 1):
-            label = f"--- Match #{i} [{m.role}/{m.where}] ---"
-            out.append(f"{label}\n{m.window_text[:1500]}")
-    return "\n\n".join(out)
+    if wide and not full:
+        return _render_search_summary(query, matches)
+
+    # Full render (single-file, or wide + --full), bounded by the char budget so
+    # the output never exceeds what the reader accepts. Degrade to summary if it would.
+    full_text = _render_search_full(matches)
+    if len(full_text) > SEARCH_CHAR_BUDGET:
+        # Ceiling-round the size so it always reads as strictly over the budget.
+        size_k = (len(full_text) + 999) // 1000
+        if wide:
+            hint = "Use a tighter --query / --role / --in, or --file <session> to read one session in full."
+        else:
+            hint = "This one session has many matches; use a tighter --query / --role / --in to narrow."
+        note = (
+            f"[note: full output is ~{size_k}K chars (> "
+            f"{SEARCH_CHAR_BUDGET // 1000}K budget) — showing a summary instead. {hint}]"
+        )
+        return note + "\n" + _render_search_summary(query, matches, already_full=True)
+    return full_text
 
 
 def mode_subagent_list(path: Path, fmt: str = "text"):
@@ -737,6 +822,131 @@ def mode_count(
     return {"sessions": sessions, "messages": total_msgs, "matches": matches}
 
 
+def _tally_tool_usage(
+    groups: list[list[Path]],
+    tool_filter: set[str] | None,
+    since: datetime | None,
+    until: datetime | None,
+) -> tuple[dict[str, int], dict[str, int], int, int]:
+    """Tally tool_use blocks by name (Skill sub-tallied by skill) over session groups.
+
+    Each group is the files of ONE logical session — the parent transcript plus,
+    when subagents are folded in, its `agent-*.jsonl` siblings. A group counts as
+    one session-with-calls if any of its files contributed a call.
+
+    Returns (tool_counts, skill_counts, total_calls, sessions_with_calls).
+    Keys on invocation STRUCTURE (a tool_use block's name / input.skill), so it
+    is immune to the substring false-positives that plague text search — the
+    word "ast-grep" in a CLAUDE.md or a bash command never counts as a call.
+    """
+    tool_counts: dict[str, int] = {}
+    skill_counts: dict[str, int] = {}
+    total = 0
+    sessions_with = 0
+    window = since is not None or until is not None
+    for group in groups:
+        hit = False
+        for f in group:
+            try:
+                lines = PR.parse_lines(f)
+            except Exception as e:  # noqa: BLE001 — one bad file shouldn't abort the tally
+                print(f"Error reading {f.name}: {e}", file=sys.stderr)
+                continue
+            for c in T.extract_tool_calls(lines, tool_filter):
+                if window:
+                    ts = PR._parse_timestamp(c.get("timestamp"))
+                    if ts is None:
+                        continue
+                    if ts.tzinfo is not None:
+                        ts = ts.replace(tzinfo=None)
+                    # Half-open window [since, until): since inclusive, until exclusive.
+                    if since is not None and ts < since:
+                        continue
+                    if until is not None and ts >= until:
+                        continue
+                name = c["name"] or "(unknown)"
+                tool_counts[name] = tool_counts.get(name, 0) + 1
+                total += 1
+                hit = True
+                if name == "Skill":
+                    sk = (c.get("input") or {}).get("skill") or "(unnamed)"
+                    skill_counts[sk] = skill_counts.get(sk, 0) + 1
+        if hit:
+            sessions_with += 1
+    return tool_counts, skill_counts, total, sessions_with
+
+
+def mode_tool_usage(
+    root: Path,
+    cwd: str | None,
+    all_projects: bool,
+    file_path: Path | None,
+    since: datetime | None,
+    until: datetime | None,
+    tool_filter: set[str] | None = None,
+    project: str | None = None,
+    exclude_current: bool = False,
+    include_subagents: bool = False,
+    current_uuid: str | None = None,
+    fmt: str = "text",
+):
+    """Tally tool_use blocks by tool name; Skill calls sub-tallied by skill name.
+
+    Answers "which tools/skills do I actually use" by counting real invocations,
+    not text occurrences. Scope is --file (one session) or the usual
+    --cwd/--project/--all-projects. --tool narrows to a subset (e.g. --tool Skill).
+    --include-subagents folds each session's agent-*.jsonl tool calls into its tally.
+    """
+    if file_path:
+        parents = [file_path]
+    else:
+        project_dirs = _scoped_project_dirs(root, cwd, all_projects, project)
+        if project_dirs is None:
+            return "--file, --cwd, --project, or --all-projects required"
+        parents = []
+        for pd in project_dirs:
+            # `since` is a safe lower-bound mtime pre-filter (a session whose last
+            # event predates `since` holds no in-window calls). `until` is NOT a
+            # safe mtime filter — a session modified after `until` can still hold
+            # calls inside the window — so the upper bound is applied per-call in
+            # _tally_tool_usage, mirroring timeline/engagement.
+            parents.extend(P.list_transcripts(pd, since=since))
+        if exclude_current and current_uuid:
+            parents = [f for f in parents if f.stem != current_uuid]
+
+    groups = []
+    for p in parents:
+        group = [p]
+        if include_subagents:
+            group.extend(P.list_subagents(p))
+        groups.append(group)
+
+    tool_counts, skill_counts, total, sessions_with = _tally_tool_usage(
+        groups, tool_filter, since, until
+    )
+    tools_sorted = sorted(tool_counts.items(), key=lambda x: (-x[1], x[0]))
+    skills_sorted = sorted(skill_counts.items(), key=lambda x: (-x[1], x[0]))
+
+    if fmt == "json":
+        return {
+            "total": total,
+            "sessions": sessions_with,
+            "tools": [{"tool": k, "count": v} for k, v in tools_sorted],
+            "skills": [{"skill": k, "count": v} for k, v in skills_sorted],
+        }
+
+    if total == 0:
+        return "No tool calls found."
+    out = [f"Tool calls ({total} total across {sessions_with} session(s)):"]
+    for name, count in tools_sorted:
+        out.append(f"  {count:5d}  {name}")
+        if name == "Skill" and skills_sorted:
+            for i, (sk, n) in enumerate(skills_sorted):
+                glyph = "└" if i == len(skills_sorted) - 1 else "├"
+                out.append(f"         {glyph} {n} {sk}")
+    return "\n".join(out)
+
+
 def mode_journal(
     root: Path,
     cwd: str | None,
@@ -1339,7 +1549,7 @@ LEGACY_MODES = {"last", "advisor", "pre-compact", "dump", "search", "debug"}
 
 NEW_MODES = {
     "list", "lookup", "find", "resume-cmd", "brief",
-    "changelog", "file-edits", "tool-calls",
+    "changelog", "file-edits", "tool-calls", "tool-usage",
     "subagent-list", "subagent-finals", "subagent-tools", "subagent-files",
     "resume-prev", "count", "journal", "diff", "timeline", "engagement",
 }
@@ -1385,13 +1595,16 @@ def build_parser() -> argparse.ArgumentParser:
 
     # Mode-specific flags
     p.add_argument("--query", help="Search query (for search/count modes)")
+    p.add_argument("--full", action="store_true",
+                   help="Wide-scope search: expand to full match windows instead of "
+                        "the per-session summary (bounded; degrades back to summary if oversized)")
     p.add_argument("--uuid", help="UUID prefix (for lookup/resume-cmd modes)")
     p.add_argument("--title", help="Title substring (for find mode)")
     p.add_argument("--first-prompt", dest="first_prompt", help="First-prompt substring (for find mode)")
     p.add_argument("--role", default="both", choices=["user", "assistant", "both"])
     p.add_argument("--in", dest="in_channel", default="text",
                    choices=["text", "tool_use", "tool_result", "thinking", "all"])
-    p.add_argument("--tool", help="Comma-separated tool names (for tool-calls)")
+    p.add_argument("--tool", help="Comma-separated tool names (for tool-calls / tool-usage)")
     p.add_argument("--subagent", help="Subagent file path (for subagent-tools/files)")
     p.add_argument("--file-a", dest="file_a", help="First file for diff mode")
     p.add_argument("--file-b", dest="file_b", help="Second file for diff mode")
@@ -1401,7 +1614,8 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--exclude-current", action="store_true",
                    help="Drop the current session (via CLAUDE_SESSION_ID) from output")
     p.add_argument("--include-subagents", action="store_true",
-                   help="Fold subagent finals into brief/last/dump output")
+                   help="Fold subagent finals into brief/last/dump output; "
+                        "fold subagent tool calls into tool-usage tallies")
     p.add_argument("--force-dump", action="store_true",
                    help="Bypass the 5MB dump-size guard")
     p.add_argument("--format", default="text", choices=["text", "json"],
@@ -1465,40 +1679,6 @@ def main() -> int:
     since = _resolve_time(args.since)
     until = _resolve_time(args.until)
 
-    # Legacy --mode search with --cwd (no --file) preserved byte-for-byte.
-    if args.mode == "search" and args.cwd and not args.file and not args.all_projects \
-            and not args.project and fmt == "text" \
-            and args.role == "both" and args.in_channel == "text":
-        if not args.query:
-            print("--query required with --mode search", file=sys.stderr)
-            return 1
-        files = P.list_transcripts(P.find_project_dir(args.cwd, root))
-        if not files:
-            print("No transcript files found.")
-            return 0
-        total_matches = 0
-        for i, f in enumerate(files, 1):
-            print(f"Searching {i}/{len(files)}: {f.name}...", file=sys.stderr, end="\r")
-            try:
-                lines = PR.parse_lines(f)
-                result = mode_search_legacy(lines, args.query)
-            except Exception as e:
-                print(f"\nError reading {f.name}: {e}", file=sys.stderr)
-                continue
-            if result is not None:
-                mtime = _fmt_mtime(f.stat().st_mtime)
-                print(f"\n{'=' * 60}")
-                print(f"Session: {f.name}  ({mtime})")
-                print("=" * 60)
-                print(result)
-                total_matches += 1
-        print(file=sys.stderr)
-        if total_matches == 0:
-            print(f"No matches for '{args.query}' found across {len(files)} session(s).")
-        else:
-            print(f"\n--- Found matches in {total_matches}/{len(files)} session(s) ---")
-        return 0
-
     mode = args.mode
 
     # Discovery modes — don't need --file
@@ -1544,6 +1724,19 @@ def main() -> int:
             )
             print(counts["sessions"])
         return 0
+    if mode == "tool-usage":
+        fp = Path(args.file) if args.file else None
+        if fp and not fp.exists():
+            print(f"File not found: {fp}", file=sys.stderr)
+            return 1
+        _emit(mode_tool_usage(
+            root, args.cwd, args.all_projects, fp, since, until,
+            tool_filter=_split_tools(args.tool), project=args.project,
+            exclude_current=args.exclude_current,
+            include_subagents=args.include_subagents,
+            current_uuid=current_uuid, fmt=fmt,
+        ))
+        return 0
     if mode == "journal":
         _emit(mode_journal(root, args.cwd, args.all_projects, since, until,
                            current_uuid, project=args.project, fmt=fmt,
@@ -1631,8 +1824,8 @@ def main() -> int:
             return 1
         _emit(mode_diff(Path(args.file_a), Path(args.file_b), fmt=fmt))
         return 0
-    # (cwd-scoped searches with non-default role/in/json land here — the
-    # byte-compat legacy path above already handled the default-flag case.)
+    # All scoped searches (--file / --cwd / --project / --all-projects) route here.
+    # Wide scope summarizes by default; --full expands to bounded match windows.
     if mode == "search" and (args.file or args.all_projects or args.project or args.cwd):
         if not args.query:
             print("--query required", file=sys.stderr)
@@ -1642,8 +1835,12 @@ def main() -> int:
                              args.role, args.in_channel, since, until,
                              project=args.project, fmt=fmt,
                              exclude_current=args.exclude_current,
-                             current_uuid=current_uuid))
+                             current_uuid=current_uuid, full=args.full))
         return 0
+    if mode == "search":
+        # Reached only when no scope flag was given — search needs one of these.
+        print("search requires --file, --cwd, --project, or --all-projects", file=sys.stderr)
+        return 1
 
     # File-required modes
     if mode == "subagent-tools":
@@ -1736,13 +1933,6 @@ def main() -> int:
             if args.include_subagents:
                 body += _append_subagents(path)
             print(body)
-    elif mode == "search":
-        if not args.query:
-            print("--query required with --mode search", file=sys.stderr)
-            return 1
-        result = mode_search_legacy(lines, args.query)
-        print(result if result is not None
-              else f"No assistant messages containing '{args.query}' found.")
     elif mode == "debug":
         print(mode_debug(lines))
 

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/tool-usage-parent/subagents/agent-sub1.jsonl

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:00:03Z","message":{"role":"user","content":"sub task"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:04Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"s1","name":"Skill","input":{"skill":"estack-repo-search"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:05Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"s2","name":"Bash","input":{"command":"ls"}}]}}

package/skills/estack-read-claude-session-history/scripts/tests/fixtures/tool-usage-parent.jsonl

@@ -0,0 +1,3 @@
+{"type":"user","timestamp":"2026-05-01T10:00:00Z","message":{"role":"user","content":"do it"}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:01Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"p1","name":"Skill","input":{"skill":"commit"}}]}}
+{"type":"assistant","timestamp":"2026-05-01T10:00:02Z","message":{"role":"assistant","content":[{"type":"tool_use","id":"p2","name":"Agent","input":{"description":"sub","subagent_type":"Explore"}}]}}

package/skills/estack-read-claude-session-history/scripts/tests/test_modes.py

@@ -110,6 +110,130 @@ def test_tool_calls_filter(cli_path, fixtures_dir):
     assert "Glob" not in r.stdout
 
 
+def test_tool_usage_file(cli_path, fixtures_dir):
+    r = _run_cli(cli_path, "--file", str(fixtures_dir / "tool-zoo.jsonl"), "--mode", "tool-usage")
+    assert r.returncode == 0
+    assert "Tool calls" in r.stdout
+    assert "Bash" in r.stdout
+    assert "Skill" in r.stdout
+    # Skill calls are sub-tallied by the actual skill name (input.skill).
+    assert "using-superpowers" in r.stdout
+
+
+def test_tool_usage_skill_filter(cli_path, fixtures_dir):
+    r = _run_cli(
+        cli_path, "--file", str(fixtures_dir / "tool-zoo.jsonl"),
+        "--mode", "tool-usage", "--tool", "Skill",
+    )
+    assert r.returncode == 0
+    assert "Skill" in r.stdout
+    assert "using-superpowers" in r.stdout
+    # Filtering to Skill must drop every other tool.
+    assert "Bash" not in r.stdout
+    assert "Glob" not in r.stdout
+
+
+def test_tool_usage_json(cli_path, fixtures_dir):
+    r = _run_cli(
+        cli_path, "--file", str(fixtures_dir / "tool-zoo.jsonl"),
+        "--mode", "tool-usage", "--format", "json",
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    assert data["total"] == 9
+    assert data["sessions"] == 1
+    tools = {t["tool"]: t["count"] for t in data["tools"]}
+    assert tools["Skill"] == 1
+    assert tools["Bash"] == 1
+    skills = {s["skill"]: s["count"] for s in data["skills"]}
+    assert skills == {"using-superpowers": 1}
+
+
+def test_tool_usage_scope_aggregates(cli_path, fixtures_dir, tmp_path):
+    # Two sessions in one project → counts add up across files.
+    fake_root = tmp_path / "projects"
+    fake_proj = fake_root / "C--fake-proj"
+    fake_proj.mkdir(parents=True)
+    shutil.copy(fixtures_dir / "tool-zoo.jsonl", fake_proj / "a.jsonl")
+    shutil.copy(fixtures_dir / "tool-zoo.jsonl", fake_proj / "b.jsonl")
+    r = _run_cli(
+        cli_path, "--root", str(fake_root), "--cwd", "C:\\fake\\proj",
+        "--mode", "tool-usage", "--format", "json",
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    assert data["sessions"] == 2
+    assert data["total"] == 18
+    skills = {s["skill"]: s["count"] for s in data["skills"]}
+    assert skills == {"using-superpowers": 2}
+
+
+def test_tool_usage_missing_file(cli_path, tmp_path):
+    r = _run_cli(cli_path, "--file", str(tmp_path / "nope.jsonl"), "--mode", "tool-usage")
+    assert r.returncode == 1
+
+
+def test_tool_usage_until_keeps_in_window_calls(cli_path, fixtures_dir, tmp_path):
+    # The tool-zoo calls are stamped 2026-05-01T10:00:0x. Copy the fixture, then
+    # bump its mtime far past --until. A naive mtime filter would drop the file
+    # and report zero; per-call timestamp filtering must still count the calls.
+    import os
+    fake_root = tmp_path / "projects"
+    fake_proj = fake_root / "C--fake-proj"
+    fake_proj.mkdir(parents=True)
+    target = fake_proj / "a.jsonl"
+    shutil.copy(fixtures_dir / "tool-zoo.jsonl", target)
+    future = 1_900_000_000  # ~2030, well after the --until bound below
+    os.utime(target, (future, future))
+    r = _run_cli(
+        cli_path, "--root", str(fake_root), "--cwd", "C:\\fake\\proj",
+        "--mode", "tool-usage", "--until", "2026-05-02", "--format", "json",
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    assert data["total"] == 9, data  # all 9 calls are inside the window
+    assert data["sessions"] == 1
+
+
+def test_tool_usage_exclude_current_drops_session(cli_path, fixtures_dir, tmp_path):
+    fake_root = tmp_path / "projects"
+    fake_proj = fake_root / "C--fake-proj"
+    fake_proj.mkdir(parents=True)
+    shutil.copy(fixtures_dir / "tool-zoo.jsonl", fake_proj / "cur.jsonl")
+    shutil.copy(fixtures_dir / "tool-zoo.jsonl", fake_proj / "other.jsonl")
+    # Without exclusion: 2 sessions, 18 calls. Excluding "cur" leaves 1 session, 9.
+    r = _run_cli(
+        cli_path, "--root", str(fake_root), "--cwd", "C:\\fake\\proj",
+        "--mode", "tool-usage", "--exclude-current", "--format", "json",
+        env_overrides={"CLAUDE_SESSION_ID": "cur"},
+    )
+    assert r.returncode == 0
+    data = json.loads(r.stdout)
+    assert data["sessions"] == 1
+    assert data["total"] == 9
+
+
+def test_tool_usage_include_subagents(cli_path, fixtures_dir):
+    # Parent calls: Skill(commit) + Agent. Subagent calls: Skill(estack-repo-search) + Bash.
+    # --include-subagents must fold the subagent's calls in, without counting the
+    # subagent as its own session.
+    parent = fixtures_dir / "tool-usage-parent.jsonl"
+    without = json.loads(_run_cli(
+        cli_path, "--file", str(parent), "--mode", "tool-usage", "--format", "json",
+    ).stdout)
+    assert without["total"] == 2
+    assert without["sessions"] == 1
+    assert {s["skill"] for s in without["skills"]} == {"commit"}
+
+    with_sub = json.loads(_run_cli(
+        cli_path, "--file", str(parent), "--mode", "tool-usage",
+        "--include-subagents", "--format", "json",
+    ).stdout)
+    assert with_sub["total"] == 4  # +Skill(estack-repo-search) +Bash
+    assert with_sub["sessions"] == 1  # subagent is not a separate session
+    assert {s["skill"] for s in with_sub["skills"]} == {"commit", "estack-repo-search"}
+
+
 def test_subagent_list(cli_path, fixtures_dir):
     r = _run_cli(
         cli_path, "--file", str(fixtures_dir / "subagent-parent.jsonl"),

package/skills/estack-read-claude-session-history/scripts/tests/test_parser.py

@@ -1,7 +1,7 @@
 """Tests for lib.parser."""
 
 import json
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 
 import pytest
@@ -132,6 +132,15 @@ def test_filter_by_time(fixtures_dir):
     )
 
 
+def test_filter_by_time_until_is_exclusive():
+    # Half-open [since, until): a message stamped exactly at `until` is excluded.
+    # Derive the bound from the parser so the test is timezone-independent.
+    msgs = [{"timestamp": "2026-05-01T10:00:00Z"}]
+    at = PR._parse_timestamp(msgs[0]["timestamp"])
+    assert PR.filter_by_time(msgs, since=None, until=at) == []
+    assert PR.filter_by_time(msgs, since=None, until=at + timedelta(seconds=1)) == msgs
+
+
 def test_truncated_line_dropped(fixtures_dir, capsys):
     # Should not raise, and warning should be on stderr
     lines = _load(fixtures_dir, "truncated.jsonl")

package/skills/estack-read-claude-session-history/scripts/tests/test_search.py

@@ -1,8 +1,9 @@
 """Tests for lib.search."""
 
-from datetime import datetime
+from datetime import datetime, timedelta
 from pathlib import Path
 
+from lib import parser as PR
 from lib import search as S
 
 
@@ -67,6 +68,21 @@ def test_search_with_time_filter(fixtures_dir):
     assert matches == []
 
 
+def test_search_until_is_exclusive(fixtures_dir):
+    # The "Hello" user message is stamped 2026-05-01T10:00:00Z. Derive the bound
+    # from the parser (it converts to local naive time) so this is tz-independent.
+    # Half-open [since, until): until at that instant excludes it; one second later includes it.
+    at = PR._parse_timestamp("2026-05-01T10:00:00Z")
+    assert S.search_session(
+        fixtures_dir / "basic-session.jsonl", "Hello", role="both", until=at
+    ) == []
+    # "Hello" matches only the user message at the boundary instant, so +1s yields exactly 1.
+    assert len(S.search_session(
+        fixtures_dir / "basic-session.jsonl", "Hello", role="both",
+        until=at + timedelta(seconds=1)
+    )) == 1
+
+
 def test_search_project(fixtures_dir, tmp_path):
     # Copy 2 fixtures into a fake project dir and search
     import shutil

package/skills/estack-read-claude-session-history/scripts/tests/test_search_output.py

@@ -0,0 +1,161 @@
+"""Tests for cross-scope search output budgeting: summary-by-default, --full,
+the char-budget degrade, and TTY-gated progress."""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import read_transcript as RT
+from lib.search import Match
+
+
+def _run_cli(cli_path, *args):
+    env = dict(os.environ)
+    env["PYTHONIOENCODING"] = "utf-8"
+    return subprocess.run(
+        [sys.executable, str(cli_path), *args],
+        capture_output=True, text=True, encoding="utf-8", env=env,
+    )
+
+
+# A realistic epoch base so _fmt_mtime renders sane dates if output is printed.
+_BASE_MTIME = 1_700_000_000
+
+
+def _mk(stem, project, mtime, window, role="assistant", where="text"):
+    sp = Path("/root") / project / f"{stem}.jsonl"
+    return Match(session_path=sp, mtime=mtime, role=role, where=where,
+                 timestamp=None, window_text=window)
+
+
+@pytest.fixture
+def wide_root(fixtures_dir, tmp_path):
+    """A fake projects root with two projects, each holding a session."""
+    root = tmp_path / "projects"
+    keel = root / "C--Users-x-Keel-Project"
+    other = root / "C--Users-x-Other-Claude-Code"
+    keel.mkdir(parents=True)
+    other.mkdir(parents=True)
+    shutil.copy(fixtures_dir / "basic-session.jsonl", keel / "keelsession.jsonl")
+    shutil.copy(fixtures_dir / "basic-session.jsonl", other / "othersession.jsonl")
+    return root
+
+
+# ── unit: renderers ──────────────────────────────────────────────────────────
+
+def test_one_line_collapses_and_truncates():
+    assert RT._one_line("a\n  b   c", 100) == "a b c"
+    assert RT._one_line("x" * 200, 10) == "x" * 10 + "…"
+    assert RT._one_line("", 10) == ""
+
+
+def test_summary_counts_all_hits_and_orders_newest_first():
+    matches = [
+        _mk("aaaaaaaa11", "C--Users-x-Proj", _BASE_MTIME, "hello world"),
+        _mk("aaaaaaaa11", "C--Users-x-Proj", _BASE_MTIME, "hello again"),
+        _mk("bbbbbbbb22", "C--Users-x-Proj", _BASE_MTIME + 100, "hello there"),
+    ]
+    out = RT._render_search_summary("hello", matches)
+    assert '"hello": 3 matches across 2 sessions' in out
+    assert "2 hits" in out  # the aaaa session has 2
+    # bbbb (BASE+100, newer) sorts before aaaa (BASE, older) — newest first
+    assert out.index("bbbbbbbb") < out.index("aaaaaaaa")
+    assert "--- Match #" not in out  # no full windows in summary
+
+
+def test_summary_caps_sessions_but_counts_all(monkeypatch):
+    monkeypatch.setattr(RT, "SEARCH_SUMMARY_SESSION_CAP", 2)
+    matches = [_mk(f"sess{i:04d}xx", "C--Users-x-Proj", _BASE_MTIME + i, "hit") for i in range(5)]
+    out = RT._render_search_summary("hit", matches)
+    assert "5 matches across 5 sessions" in out  # header counts everything
+    assert "3 more session" in out  # 5 total - 2 shown
+
+
+def test_search_summary_json_has_no_windows():
+    matches = [_mk("aaaaaaaa11", "C--Users-x-My-Proj", _BASE_MTIME, "hello world snippet")]
+    js = RT._search_summary_json(matches)
+    assert js[0]["uuid"] == "aaaaaaaa11"
+    assert js[0]["hits"] == 1
+    assert "window" not in js[0]
+    assert js[0]["first_snippet"] == "hello world snippet"
+
+
+def test_single_file_full_degrades_to_summary_when_oversized(monkeypatch, fixtures_dir):
+    # Even a single-file search degrades if its full windows exceed the budget.
+    monkeypatch.setattr(RT, "SEARCH_CHAR_BUDGET", 10)
+    out = RT.mode_search_v2(
+        root=Path("."), cwd=None, all_projects=False,
+        file_path=fixtures_dir / "basic-session.jsonl",
+        query="Hello", role="both", in_channel="text",
+        since=None, until=None, fmt="text",
+    )
+    assert out.startswith("[note: full output")
+    assert '"Hello":' in out  # summary header is appended after the note
+
+
+def test_wide_full_degrades_to_summary_when_oversized(monkeypatch, wide_root):
+    # The advertised path: wide scope + --full, oversized, degrades to summary.
+    monkeypatch.setattr(RT, "SEARCH_CHAR_BUDGET", 10)
+    out = RT.mode_search_v2(
+        root=wide_root, cwd=None, all_projects=True, file_path=None,
+        query="Hello", role="both", in_channel="text",
+        since=None, until=None, fmt="text", full=True,
+    )
+    assert out.startswith("[note: full output")
+    assert "matches across" in out  # summary header appended
+    assert "--- Match #" not in out  # degraded — no windows survive
+
+
+# ── CLI: end-to-end ──────────────────────────────────────────────────────────
+
+def test_wide_search_summarizes_by_default(cli_path, wide_root):
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects")
+    assert r.returncode == 0
+    assert '"Hello":' in r.stdout and "matches across" in r.stdout  # real summary header
+    assert "--- Match #" not in r.stdout  # summary, not windows
+
+
+def test_wide_search_full_shows_windows(cli_path, wide_root):
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects", "--full")
+    assert r.returncode == 0
+    assert "--- Match #" in r.stdout  # full windows present
+
+
+def test_progress_suppressed_when_stderr_not_a_tty(cli_path, wide_root):
+    # stderr is captured (not a TTY) — the Searching i/N progress must not appear.
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--all-projects")
+    assert "Searching" not in r.stderr
+
+
+def test_cwd_search_matches_user_messages(cli_path, wide_root):
+    # "Hello" lives only in the user message of basic-session.jsonl. A --cwd
+    # search now routes through mode_search_v2 (role=both), so it must be found —
+    # the old assistant-only --cwd path would have missed it.
+    found = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                     "--query", "Hello", "--cwd", "Keel")
+    assert found.returncode == 0
+    assert '"Hello":' in found.stdout and "across" in found.stdout
+    assert "keelsess" in found.stdout
+
+    # Restricting to assistant role excludes the user-only hit.
+    asst = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                    "--query", "Hello", "--cwd", "Keel", "--role", "assistant")
+    assert asst.returncode == 0
+    assert "No matches" in asst.stdout
+
+
+def test_json_role_filter_excludes_user_only_match(cli_path, wide_root):
+    # JSON path honors --role too: assistant-only over a user-only term → empty list.
+    r = _run_cli(cli_path, "--root", str(wide_root), "--mode", "search",
+                 "--query", "Hello", "--cwd", "Keel",
+                 "--role", "assistant", "--format", "json")
+    assert r.returncode == 0
+    assert json.loads(r.stdout) == []

package/skills/estack-read-claude-session-history/scripts/tests/test_timezone_and_project.py

@@ -186,11 +186,24 @@ def test_cli_list_project_filter(cli_path, multi_root):
 
 
 def test_cli_search_project_filter(cli_path, multi_root):
+    # Wide scope summarizes by default: the session shows as its uuid8 prefix,
+    # and the off-project session must not appear.
     r = _run_cli(
         cli_path, "--root", str(multi_root), "--mode", "search",
         "--query", "help", "--project", "keel",
     )
     assert r.returncode == 0
+    assert "keelsess" in r.stdout
+    assert "othersess" not in r.stdout
+
+
+def test_cli_search_project_filter_full(cli_path, multi_root):
+    # --full expands to match windows, which include the full session filename.
+    r = _run_cli(
+        cli_path, "--root", str(multi_root), "--mode", "search",
+        "--query", "help", "--project", "keel", "--full",
+    )
+    assert r.returncode == 0
     assert "keelsession" in r.stdout