elliot-stack 1.0.37 → 1.0.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.37",
+  "version": "1.0.38",
   "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.1.0
 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
@@ -100,7 +101,8 @@ What are you trying to do?
 ├─ 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
@@ -136,6 +138,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,7 +155,7 @@ 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.
 - `--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`).
@@ -160,8 +163,8 @@ What are you trying to do?
 - `--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 +205,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,7 @@ 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.
+- `--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.
 
@@ -364,6 +364,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,6 +432,7 @@ 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}]` |
 | `count` | `{sessions, messages, matches}` |

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/read_transcript.py

@@ -737,6 +737,130 @@ 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)
+                    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 +1463,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",
 }
@@ -1391,7 +1515,7 @@ def build_parser() -> argparse.ArgumentParser:
     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 +1525,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"],
@@ -1544,6 +1669,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,

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"),