cc-session-tools 3.6.1__tar.gz → 3.7.0__tar.gz

{cc_session_tools-3.6.1/src/cc_session_tools.egg-info → cc_session_tools-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.6.1
+Version: 3.7.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License
@@ -105,7 +105,7 @@ bundled scheduled jobs:
 | **`session-tag`** (SessionStart) | Writes a `<uuid>.tag` file so `claude-code-usage` can map session UUIDs to human-readable names. |
 | **`last-screenshot`** (UserPromptSubmit) | Resolves your newest screenshot for the `>lss` token and injects its path. Requires `CCST_SCREENSHOT_DIR`. |
 | **`bash-hard-deny`** (PreToolUse) | Categorical hard-deny gate for Bash: destructive file ops (`rm`/`rmdir`/`unlink`/`shred`, incl. inline python/node and script-file/heredoc forms), delete-by-move to a tmp-like location, `git branch`/`git push` branch deletion, `gh api`/`gh release` delete, destructive curl/wget methods, `sudo`, and direct telemetry-log reads. Runs before every other Bash hook; a match here can never be overridden in-session (the message tells you to run the command yourself in a separate terminal). |
-| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review with an allowlist cache and LLM fallback. |
+| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review: trivial/read-only pre-filters, heuristic escalation, a reviewed-script allowlist (script path + content hash, managed with `ccst hooks allowlist list\|add\|remove\|verify`), a command cache, and a slimmed `claude -p` LLM fallback (~770 tokens per review instead of ~50k+). |
 | **`marker-allow`** (PreToolUse) | Auto-approves a bare `touch` of a skill marker under `~/.cache/claude/markers/` (and nothing else), so marker-gated skills can refresh their TTL marker without a permission prompt. |
 | **`confirm-8digit`** (PreToolUse) | Blocks a configurable set of high-stakes tool calls unless the user repeats back an 8-digit confirmation code. |
 | **`after-response`** (Stop) | Touches a `.last-active` sentinel so `ccs --order-by active` can sort sessions by recency of Claude activity. |
@@ -151,7 +151,7 @@ If you've ever tried to remember which `1f4a8b3c-...` UUID is the session where
 
 - **Python 3.11+** (3.12+ recommended)
 - **The `claude` CLI on your `$PATH`.** Install it first via [the official Claude Code instructions](https://docs.anthropic.com/en/docs/claude-code/setup) and verify with `claude --version`.
-- **`ccusage` (optional)** - if on `$PATH`, `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing.
+- **`ccusage` (optional)** - if on `$PATH` (or in bun's global bin dir, `~/.bun/bin`), `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing. Needs `bun` to install; `ccst doctor` reports both under `deps:bun` / `deps:ccusage` and prints the install command. See the `analyse-cc-usage` skill's setup section.
 - **`ripgrep` (optional)** - `ccs --contents` prefers `rg`; falls back to threaded Python `grep` if missing.
 
 ### Install and set up

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/README.md

@@ -48,7 +48,7 @@ bundled scheduled jobs:
 | **`session-tag`** (SessionStart) | Writes a `<uuid>.tag` file so `claude-code-usage` can map session UUIDs to human-readable names. |
 | **`last-screenshot`** (UserPromptSubmit) | Resolves your newest screenshot for the `>lss` token and injects its path. Requires `CCST_SCREENSHOT_DIR`. |
 | **`bash-hard-deny`** (PreToolUse) | Categorical hard-deny gate for Bash: destructive file ops (`rm`/`rmdir`/`unlink`/`shred`, incl. inline python/node and script-file/heredoc forms), delete-by-move to a tmp-like location, `git branch`/`git push` branch deletion, `gh api`/`gh release` delete, destructive curl/wget methods, `sudo`, and direct telemetry-log reads. Runs before every other Bash hook; a match here can never be overridden in-session (the message tells you to run the command yourself in a separate terminal). |
-| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review with an allowlist cache and LLM fallback. |
+| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review: trivial/read-only pre-filters, heuristic escalation, a reviewed-script allowlist (script path + content hash, managed with `ccst hooks allowlist list\|add\|remove\|verify`), a command cache, and a slimmed `claude -p` LLM fallback (~770 tokens per review instead of ~50k+). |
 | **`marker-allow`** (PreToolUse) | Auto-approves a bare `touch` of a skill marker under `~/.cache/claude/markers/` (and nothing else), so marker-gated skills can refresh their TTL marker without a permission prompt. |
 | **`confirm-8digit`** (PreToolUse) | Blocks a configurable set of high-stakes tool calls unless the user repeats back an 8-digit confirmation code. |
 | **`after-response`** (Stop) | Touches a `.last-active` sentinel so `ccs --order-by active` can sort sessions by recency of Claude activity. |
@@ -94,7 +94,7 @@ If you've ever tried to remember which `1f4a8b3c-...` UUID is the session where
 
 - **Python 3.11+** (3.12+ recommended)
 - **The `claude` CLI on your `$PATH`.** Install it first via [the official Claude Code instructions](https://docs.anthropic.com/en/docs/claude-code/setup) and verify with `claude --version`.
-- **`ccusage` (optional)** - if on `$PATH`, `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing.
+- **`ccusage` (optional)** - if on `$PATH` (or in bun's global bin dir, `~/.bun/bin`), `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing. Needs `bun` to install; `ccst doctor` reports both under `deps:bun` / `deps:ccusage` and prints the install command. See the `analyse-cc-usage` skill's setup section.
 - **`ripgrep` (optional)** - `ccs --contents` prefers `rg`; falls back to threaded Python `grep` if missing.
 
 ### Install and set up

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.6.1"
+version = "3.7.0"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/src/cc_session_tools/cli/ccst.py

@@ -6,6 +6,8 @@ Current subcommands:
   hooks install [--hook <name>]  Merge hook entries from the bundled set (or a
                                  custom --source) into a target settings.json.
   hooks uninstall [--hook <name>] Remove hook entries from a target settings.json.
+  hooks allowlist list|add|remove|verify
+                                 Manage the bash-security-review reviewed-script allowlist.
   hooks run <name>               Run a Claude Code hook by name.
                                  Available hooks: bash-hard-deny,
                                  bash-security-review, marker-allow,
@@ -1949,6 +1951,65 @@ def _cmd_machine_identity_confirm(args: argparse.Namespace) -> int:
 # ---------- hooks run ----------
 
 
+def _cmd_hooks_allowlist(args: argparse.Namespace) -> int:
+    """`ccst hooks allowlist list|add|remove|verify` - the reviewed-script allowlist store."""
+    import hashlib
+
+    from hooks import cache as cache_mod
+    from hooks import script_allowlist
+
+    verb = args.allowlist_verb
+    if verb == "list":
+        entries = cache_mod.allowlist_list()
+        if not entries:
+            print("No allowlisted scripts.")
+            return 0
+        for e in entries:
+            print(
+                f"{e.script_path}  source={e.source}  sha256={e.sha256[:8]}  added={e.added_at}  "
+                f"last_used={e.last_used or '-'}  uses={e.use_count}"
+            )
+        return 0
+    if verb == "add":
+        path = Path(args.script).expanduser().resolve()
+        if not path.is_file():
+            print(f"error: {args.script}: not a file", file=sys.stderr)
+            return 2
+        root = script_allowlist.find_project_root(path.parent)
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        cache_mod.allowlist_upsert(
+            str(path), digest, str(root), source="manual", overwrite_source=True
+        )
+        print(f"Allowlisted {path} (sha256 {digest[:8]}, project {root})")
+        return 0
+    if verb == "remove":
+        path = Path(args.script).expanduser().resolve()
+        if not cache_mod.allowlist_remove(str(path)):
+            print(f"error: {path} is not in the allowlist", file=sys.stderr)
+            return 1
+        print(f"Removed {path}")
+        return 0
+    # verify
+    drift = 0
+    entries = cache_mod.allowlist_list()
+    if not entries:
+        print("No allowlisted scripts.")
+        return 0
+    for e in entries:
+        p = Path(e.script_path)
+        if not p.is_file():
+            print(f"MISSING  {e.script_path}")
+            drift += 1
+            continue
+        current = hashlib.sha256(p.read_bytes()).hexdigest()
+        if current != e.sha256:
+            print(f"CHANGED  {e.script_path}  {e.sha256[:8]} -> {current[:8]}")
+            drift += 1
+        else:
+            print(f"OK       {e.script_path}")
+    return 1 if drift else 0
+
+
 def _cmd_hooks_run(args: argparse.Namespace) -> int:
     """Dispatch to the named hook, or exit 1 (never 2) if it is unknown.
 
@@ -2598,6 +2659,24 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Write changes (default: dry run)",
     )
 
+    # hooks allowlist
+    allowlist_parser = hooks_sub.add_parser(
+        "allowlist",
+        help="Manage the bash-security-review reviewed-script allowlist",
+    )
+    allowlist_sub = allowlist_parser.add_subparsers(dest="allowlist_verb", metavar="<action>")
+    allowlist_sub.required = True
+    allowlist_sub.add_parser("list", help="List allowlisted scripts")
+    allowlist_add = allowlist_sub.add_parser(
+        "add", help="Allowlist a script at its current content hash (you vouch for it)"
+    )
+    allowlist_add.add_argument("script", metavar="<script>", help="Path to the script")
+    allowlist_remove = allowlist_sub.add_parser("remove", help="Remove a script from the allowlist")
+    allowlist_remove.add_argument("script", metavar="<script>", help="Path to the script")
+    allowlist_sub.add_parser(
+        "verify", help="Report allowlisted scripts that changed or no longer exist (exit 1 on drift)"
+    )
+
     # hooks run
     run_parser = hooks_sub.add_parser(
         "run",
@@ -3500,6 +3579,8 @@ def main() -> None:
             sys.exit(_cmd_hooks_install(args))
         if args.verb == "uninstall":
             sys.exit(_cmd_hooks_uninstall(args))
+        if args.verb == "allowlist":
+            sys.exit(_cmd_hooks_allowlist(args))
         if args.verb == "run":
             sys.exit(_cmd_hooks_run(args))
 

cc_session_tools-3.7.0/src/cc_session_tools/lib/bun_tools.py

@@ -0,0 +1,39 @@
+"""Locate tools installed through bun (bun itself, ccusage).
+
+`bun add -g` installs into ``$BUN_INSTALL/bin`` (default ``~/.bun/bin``). That directory is
+only on ``PATH`` if the user edited a shell rc file that the current shell type reads, which
+non-interactive shells (hooks, scheduled jobs, subagent Bash calls) often do not. Resolving the
+directory directly keeps a correct install findable from every shell type.
+"""
+from __future__ import annotations
+
+import dataclasses
+import os
+import shutil
+from pathlib import Path
+
+# Upstream's installer works on macOS and on Linux/WSL (which also needs `unzip` installed).
+BUN_INSTALL_COMMAND = "curl -fsSL https://bun.sh/install | bash"
+CCUSAGE_INSTALL_COMMAND = "bun add -g ccusage"
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Resolved:
+    path: str
+    on_path: bool
+
+
+def bun_bin_dir() -> Path:
+    install = os.environ.get("BUN_INSTALL")
+    return (Path(install) if install else Path.home() / ".bun") / "bin"
+
+
+def resolve(name: str, *, bin_dir: Path | None = None) -> Resolved | None:
+    """Find *name* on ``PATH`` first, then in bun's global bin directory."""
+    found = shutil.which(name)
+    if found is not None:
+        return Resolved(path=found, on_path=True)
+    candidate = (bin_dir if bin_dir is not None else bun_bin_dir()) / name
+    if candidate.is_file() and os.access(candidate, os.X_OK):
+        return Resolved(path=str(candidate), on_path=False)
+    return None

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/src/cc_session_tools/lib/doctor.py

@@ -21,6 +21,7 @@ from enum import Enum
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from cc_session_tools.lib import bun_tools
 from cc_session_tools.lib.db import connect as _db_connect
 from cc_session_tools.lib.db import migration_applied as _migration_applied
 from cc_session_tools.lib.hook_registry import HOOK_VERBS, hook_name_from_command
@@ -121,6 +122,69 @@ def check_env_dir(
     return CheckResult(name=name, status=Status.OK, reason=str(p))
 
 
+def _check_bun_tool(
+    name: str, *, install_hint: str, bin_dir: Path | None, timeout: float
+) -> CheckResult:
+    """WARN-only check for an optional bun-installed tool (see `bun_tools.resolve`)."""
+    check_name = f"deps:{name}"
+    resolved = bun_tools.resolve(name, bin_dir=bin_dir)
+    if resolved is None:
+        return CheckResult(name=check_name, status=Status.WARN, reason=f"{name!r} not found; {install_hint}")
+    if not resolved.on_path:
+        found_dir = Path(resolved.path).parent
+        return CheckResult(
+            name=check_name,
+            status=Status.WARN,
+            reason=(
+                f"installed at {resolved.path} but {found_dir} is not on PATH; add it to PATH "
+                f"(for non-interactive shells too: ~/.zshenv for zsh, ~/.profile for bash)"
+            ),
+        )
+    try:
+        result = subprocess.run(
+            [resolved.path, "--version"], capture_output=True, text=True, timeout=timeout
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return CheckResult(
+            name=check_name, status=Status.WARN, reason=f"could not run {name} --version: {e}"
+        )
+    if result.returncode != 0:
+        return CheckResult(
+            name=check_name, status=Status.WARN, reason=f"{name} --version exited {result.returncode}"
+        )
+    return CheckResult(
+        name=check_name,
+        status=Status.OK,
+        reason=(result.stdout + result.stderr).strip().split("\n")[0],
+    )
+
+
+def check_bun(bin_dir: Path | None = None, timeout: float = 5.0) -> CheckResult:
+    """WARN (never FAIL) if bun, needed to install ccusage, is missing or not on PATH."""
+    return _check_bun_tool(
+        "bun",
+        install_hint=(
+            f"install with `{bun_tools.BUN_INSTALL_COMMAND}` (macOS and Linux/WSL; "
+            "Linux/WSL also needs `unzip`)"
+        ),
+        bin_dir=bin_dir,
+        timeout=timeout,
+    )
+
+
+def check_ccusage(bin_dir: Path | None = None, timeout: float = 5.0) -> CheckResult:
+    """WARN (never FAIL) if ccusage, used by `claude-code-usage reconcile`, is missing.
+
+    ccusage is optional: claude-code-usage works without it apart from `reconcile`.
+    """
+    return _check_bun_tool(
+        "ccusage",
+        install_hint=f"install bun first (see deps:bun), then `{bun_tools.CCUSAGE_INSTALL_COMMAND}`",
+        bin_dir=bin_dir,
+        timeout=timeout,
+    )
+
+
 def check_settings_json(settings_path: Path) -> CheckResult:
     """Verify settings.json exists and is valid JSON."""
     name = "settings.json"
@@ -1111,6 +1175,10 @@ def run_all_checks(
         results.extend(check_sessions_uuid_migration(sessions_db_path))
         results.extend(check_sessions_project_dir_absolute(sessions_db_path))
 
+    # Optional dependencies for claude-code-usage's reconcile / ccusage blocks
+    results.append(check_bun())
+    results.append(check_ccusage())
+
     # PyPI version check
     if not skip_pypi:
         results.append(check_pypi_version(installed_version))

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/src/cc_session_tools/skills/analyse-cc-usage/SKILL.md

@@ -206,8 +206,23 @@ claude-code-usage --version    # should print the version
 uv sync --extra dev
 uv run pytest    # all 350+ tests should pass
 
-# 4. Install ccusage globally so reconciliation works
-#    Install bun first if needed: https://bun.com/docs/installation
+# 4a. Install bun (needed to install ccusage). Same command on macOS and Linux/WSL.
+#     Linux/WSL: install `unzip` first (e.g. `sudo apt install unzip`), and install bun
+#     inside the Linux environment - a Windows-side bun is not visible to WSL tools.
+#     macOS alternative: `brew install oven-sh/bun/bun`.
+curl -fsSL https://bun.sh/install | bash
+bun --version
+
+# 4b. Make bun's global bin dir (default ~/.bun/bin) resolvable on PATH, including in
+#     non-interactive shells (hooks, scheduled jobs). The installer edits the rc file of the
+#     shell you ran it from, which non-interactive shells often skip; also add it to
+#     ~/.zshenv (zsh) or ~/.profile (bash):
+#         export PATH="$HOME/.bun/bin:$PATH"
+#     claude-code-usage also falls back to ~/.bun/bin ($BUN_INSTALL/bin) on its own, so
+#     reconcile works without this; the PATH edit is what makes the `ccusage` command itself
+#     (e.g. `ccusage blocks`) available.
+
+# 4c. Install ccusage globally so reconciliation works
 bun add -g ccusage
 ccusage --version
 
@@ -223,6 +238,11 @@ claude-code-usage warm-cache
 claude-code-usage reconcile
 ```
 
+**Existing machine that already has CCST:** `ccst doctor` reports `deps:bun` and `deps:ccusage`
+(WARN when missing or not on `PATH`, with the exact fix). `ccst install-everything` runs doctor at
+its end, so upgrading surfaces a missing install; CCST never installs bun or ccusage itself. Mute
+with `ccst doctor --mute deps:ccusage` if you deliberately skip it.
+
 The repo can also be sourced from GitHub directly (via the upstream
 remote) if you don't want to clone it - see the README's "Install"
 section for that path.

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0/src/cc_session_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.6.1
+Version: 3.7.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License
@@ -105,7 +105,7 @@ bundled scheduled jobs:
 | **`session-tag`** (SessionStart) | Writes a `<uuid>.tag` file so `claude-code-usage` can map session UUIDs to human-readable names. |
 | **`last-screenshot`** (UserPromptSubmit) | Resolves your newest screenshot for the `>lss` token and injects its path. Requires `CCST_SCREENSHOT_DIR`. |
 | **`bash-hard-deny`** (PreToolUse) | Categorical hard-deny gate for Bash: destructive file ops (`rm`/`rmdir`/`unlink`/`shred`, incl. inline python/node and script-file/heredoc forms), delete-by-move to a tmp-like location, `git branch`/`git push` branch deletion, `gh api`/`gh release` delete, destructive curl/wget methods, `sudo`, and direct telemetry-log reads. Runs before every other Bash hook; a match here can never be overridden in-session (the message tells you to run the command yourself in a separate terminal). |
-| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review with an allowlist cache and LLM fallback. |
+| **`bash-security-review`** (PreToolUse) | Tiered Bash command security review: trivial/read-only pre-filters, heuristic escalation, a reviewed-script allowlist (script path + content hash, managed with `ccst hooks allowlist list\|add\|remove\|verify`), a command cache, and a slimmed `claude -p` LLM fallback (~770 tokens per review instead of ~50k+). |
 | **`marker-allow`** (PreToolUse) | Auto-approves a bare `touch` of a skill marker under `~/.cache/claude/markers/` (and nothing else), so marker-gated skills can refresh their TTL marker without a permission prompt. |
 | **`confirm-8digit`** (PreToolUse) | Blocks a configurable set of high-stakes tool calls unless the user repeats back an 8-digit confirmation code. |
 | **`after-response`** (Stop) | Touches a `.last-active` sentinel so `ccs --order-by active` can sort sessions by recency of Claude activity. |
@@ -151,7 +151,7 @@ If you've ever tried to remember which `1f4a8b3c-...` UUID is the session where
 
 - **Python 3.11+** (3.12+ recommended)
 - **The `claude` CLI on your `$PATH`.** Install it first via [the official Claude Code instructions](https://docs.anthropic.com/en/docs/claude-code/setup) and verify with `claude --version`.
-- **`ccusage` (optional)** - if on `$PATH`, `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing.
+- **`ccusage` (optional)** - if on `$PATH` (or in bun's global bin dir, `~/.bun/bin`), `claude-code-usage reconcile` cross-checks dollar totals against it. Skipped gracefully if missing. Needs `bun` to install; `ccst doctor` reports both under `deps:bun` / `deps:ccusage` and prints the install command. See the `analyse-cc-usage` skill's setup section.
 - **`ripgrep` (optional)** - `ccs --contents` prefers `rg`; falls back to threaded Python `grep` if missing.
 
 ### Install and set up

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/src/cc_session_tools.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/cc_session_tools/cli/migrate_telemetry.py
 src/cc_session_tools/config/hooks-bundle.json
 src/cc_session_tools/config/session-tag-hook.json
 src/cc_session_tools/lib/__init__.py
+src/cc_session_tools/lib/bun_tools.py
 src/cc_session_tools/lib/claude_flags.py
 src/cc_session_tools/lib/claude_md_install.py
 src/cc_session_tools/lib/context_overrides.py
@@ -176,6 +177,7 @@ src/hooks/normalise.py
 src/hooks/pdata_sync.py
 src/hooks/pending_migration.py
 src/hooks/pending_rename.py
+src/hooks/script_allowlist.py
 src/hooks/session_tag.py
 src/hooks/stats.py
 src/hooks/telemetry.py
@@ -187,6 +189,8 @@ tests/test_after_response.py
 tests/test_attribution.py
 tests/test_bash_hard_deny.py
 tests/test_bash_security_review.py
+tests/test_bash_security_review_allowlist.py
+tests/test_bun_tools.py
 tests/test_cache.py
 tests/test_cache_sqlite.py
 tests/test_ccr_orphans.py
@@ -204,6 +208,7 @@ tests/test_ccst_doctor.py
 tests/test_ccst_gc_prune.py
 tests/test_ccst_gc_report.py
 tests/test_ccst_hook_dispatcher.py
+tests/test_ccst_hooks_allowlist.py
 tests/test_ccst_hooks_install_prune.py
 tests/test_ccst_hooks_install_zero_arg.py
 tests/test_ccst_hooks_uninstall.py
@@ -268,6 +273,7 @@ tests/test_roots.py
 tests/test_rules.py
 tests/test_scheduler_bundled_jobs.py
 tests/test_schema.py
+tests/test_script_allowlist.py
 tests/test_session_names.py
 tests/test_session_tag.py
 tests/test_sessions.py

{cc_session_tools-3.6.1 → cc_session_tools-3.7.0}/src/claude_code_usage/ccusage_wrapper.py

@@ -10,11 +10,12 @@ that's our domain.
 from __future__ import annotations
 
 import json
-import shutil
 import subprocess
 from dataclasses import dataclass, field
 from typing import Any
 
+from cc_session_tools.lib import bun_tools
+
 
 @dataclass
 class DailyEntry:
@@ -52,11 +53,11 @@ class ReconcileDiff:
 
 
 class CcusageNotInstalled(RuntimeError):
-    """Raised when ccusage is not on PATH."""
+    """Raised when ccusage is neither on PATH nor in bun's global bin directory."""
 
 
 def is_available() -> bool:
-    return shutil.which("ccusage") is not None
+    return bun_tools.resolve("ccusage") is not None
 
 
 def run_daily(since: str | None = None, until: str | None = None,
@@ -65,9 +66,14 @@ def run_daily(since: str | None = None, until: str | None = None,
 
     Dates are formatted as YYYYMMDD per ccusage's CLI.
     """
-    if not is_available():
-        raise CcusageNotInstalled("ccusage CLI is not on PATH; bun add -g ccusage")
-    cmd = ["ccusage", "daily", "--json"]
+    resolved = bun_tools.resolve("ccusage")
+    if resolved is None:
+        raise CcusageNotInstalled(
+            "ccusage not found on PATH or in bun's global bin directory. Follow the "
+            "analyse-cc-usage skill's setup step 4 (install bun, then "
+            f"`{bun_tools.CCUSAGE_INSTALL_COMMAND}`); `ccst doctor` shows the current state."
+        )
+    cmd = [resolved.path, "daily", "--json"]
     if offline:
         cmd.append("--offline")
     if since: