cc-session-tools 2.2.0__tar.gz → 2.3.0__tar.gz

{cc_session_tools-2.2.0/src/cc_session_tools.egg-info → cc_session_tools-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 2.2.0
+Version: 2.3.0
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-2.2.0 → cc_session_tools-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "2.2.0"
+version = "2.3.0"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (cccs_hooks)"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -55,12 +55,24 @@ cccs-stats = "cccs_hooks.stats:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+# skills/ and config/ are bundled data, not importable code - without this
+# exclude, setuptools' auto-discovery treats every skills/<name>/ subdirectory
+# containing a .py file (scripts, dev-only test suites) as its own importable
+# sub-package, which then bypasses exclude-package-data entirely (that option
+# only filters within the file's *own* discovered package, and a wrongly
+# auto-discovered "cc_session_tools.skills.<name>.tests" package was never
+# covered by an exclude-package-data entry keyed just "cc_session_tools").
+exclude = ["cc_session_tools.skills", "cc_session_tools.skills.*", "cc_session_tools.config", "cc_session_tools.config.*"]
 
 [tool.setuptools.package-data]
 claude_code_usage = ["data/*.json"]
+cc_session_tools = ["skills/**/*", "config/*"]
+
+[tool.setuptools.exclude-package-data]
+cc_session_tools = ["**/tests/*", "**/__pycache__/*"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests", "tests/scheduler", "skills/move-session/tests", "skills/list-empty-sessions/tests", "skills/delete-sessions/tests", "skills/generate-8digit-code/tests", "skills/reduce-persistent-context/tests", "skills/update-command-cache/tests"]
+testpaths = ["tests", "tests/scheduler", "src/cc_session_tools/skills/move-session/tests", "src/cc_session_tools/skills/list-empty-sessions/tests", "src/cc_session_tools/skills/delete-sessions/tests", "src/cc_session_tools/skills/generate-8digit-code/tests", "src/cc_session_tools/skills/reduce-persistent-context/tests", "src/cc_session_tools/skills/update-command-cache/tests"]
 addopts = "-q"
 pythonpath = ["src"]
 

{cc_session_tools-2.2.0 → cc_session_tools-2.3.0}/src/cc_session_tools/cli/ccst.py

@@ -88,17 +88,15 @@ from cc_session_tools.lib.hook_registry import HOOK_DESCRIPTIONS, HOOK_VERBS
 def _discover_source_dir() -> Path:
     """Return the bundled skills/ directory.
 
-    Walk up from this module's file to find the repo root containing skills/.
-    Falls back to ~/repos/claude-code-session-tools/skills/ for wheel installs.
+    skills/ is packaged inside cc_session_tools (declared as package-data in
+    pyproject.toml), so it sits at the same relative depth from this module
+    whether cc_session_tools is an editable source checkout or an installed
+    wheel: src/cc_session_tools/cli/ccst.py -> ../skills. No install-location
+    fallback is needed - a fallback here would just mask a broken install.
     """
-    # From src/cc_session_tools/cli/ccst.py walk up: cli/ -> cc_session_tools/ -> src/ -> repo root
-    here = Path(__file__).resolve()
-    candidate = here.parent.parent.parent.parent / "skills"
+    candidate = Path(__file__).resolve().parent.parent / "skills"
     if candidate.is_dir():
         return candidate
-    fallback = Path.home() / "repos" / "claude-code-session-tools" / "skills"
-    if fallback.is_dir():
-        return fallback
     raise FileNotFoundError(
         "Cannot locate bundled skills/ directory. "
         "Run from the source tree or use --source to specify the path explicitly."
@@ -108,18 +106,12 @@ def _discover_source_dir() -> Path:
 def _discover_bundle() -> Path:
     """Return the bundled config/hooks-bundle.json path.
 
-    Walk up from this module's file to find the repo root containing config/.
-    Falls back to ~/repos/claude-code-session-tools/config/... for wheel installs.
+    config/ is packaged inside cc_session_tools the same way skills/ is (see
+    _discover_source_dir) - src/cc_session_tools/cli/ccst.py -> ../config.
     """
-    here = Path(__file__).resolve()
-    candidate = here.parent.parent.parent.parent / "config" / "hooks-bundle.json"
+    candidate = Path(__file__).resolve().parent.parent / "config" / "hooks-bundle.json"
     if candidate.is_file():
         return candidate
-    fallback = (
-        Path.home() / "repos" / "claude-code-session-tools" / "config" / "hooks-bundle.json"
-    )
-    if fallback.is_file():
-        return fallback
     raise FileNotFoundError(
         "Cannot locate bundled config/hooks-bundle.json. "
         "Run from the source tree or use --source to specify the path explicitly."

cc_session_tools-2.3.0/src/cc_session_tools/config/hooks-bundle.json

@@ -0,0 +1,118 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run session-tag",
+            "timeout": 5,
+            "statusMessage": "Checking cc wrapper session tag..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run messaging-deliver",
+            "timeout": 10,
+            "statusMessage": "Delivering inter-session messages..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run catchup",
+            "timeout": 10,
+            "statusMessage": "Reconciling scheduled-task catch-up..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run pending-migration",
+            "timeout": 5,
+            "statusMessage": "Checking for unmigrated legacy data stores..."
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run last-screenshot",
+            "timeout": 5,
+            "statusMessage": "Resolving latest screenshot for >lss..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run messaging-deliver",
+            "timeout": 10,
+            "statusMessage": "Checking for new inter-session messages..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run catchup",
+            "timeout": 10,
+            "statusMessage": "Surfacing scheduled-task catch-up..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run bash-hard-deny",
+            "timeout": 5,
+            "statusMessage": "Checking Bash command against hard-deny rules..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run marker-allow",
+            "timeout": 5,
+            "statusMessage": "Checking for skill-marker touch..."
+          },
+          {
+            "type": "command",
+            "command": "ccst hooks run bash-security-review",
+            "timeout": 30,
+            "statusMessage": "Reviewing shell command for security risks..."
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run confirm-8digit",
+            "timeout": 10,
+            "statusMessage": "Checking 8-digit confirmation gate..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run after-response",
+            "timeout": 10,
+            "statusMessage": "Recording session activity..."
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run worklog-guard",
+            "timeout": 5,
+            "statusMessage": "Checking WORKLOG.md freshness..."
+          }
+        ]
+      }
+    ]
+  }
+}

cc_session_tools-2.3.0/src/cc_session_tools/config/session-tag-hook.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "ccst hooks run session-tag",
+            "timeout": 5,
+            "statusMessage": "Writing session tag file..."
+          }
+        ]
+      }
+    ]
+  }
+}

cc_session_tools-2.3.0/src/cc_session_tools/skills/analyse-cc-usage/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: analyse-cc-usage
+description: Analyse the user's Claude Code usage across projects, sessions, MCP servers, plugins, tools, time and models, in tokens AND dollars. Use whenever the user asks about their Claude Code usage in any way - "how much have I spent", "tokens used last week", "which project costs the most", "how much did Opus cost in April", "MCP usage by project", "compare Sonnet and Opus", "show my sessions in oneshot last month", "how often am I using the github plugin", "give me a usage report for the quarter", "what tools do I lean on", "any spike in usage recently". Backed by the cc-session-tools repo at ~/repos/claude-code-session-tools (also on GitHub at raffishquartan/claude-code-session-tools). Reconciles token totals against ccusage so we know the numbers are right.
+---
+
+# analyse-cc-usage
+
+Use this skill whenever the user asks anything about their Claude Code usage.
+The CLI behind this skill (`claude-code-usage`) is the canonical source.
+Run it behind the scenes and summarise the result in the chat - don't
+make the user look at raw markdown tables unless they ask for them.
+
+## When to use
+
+Trigger phrases (non-exhaustive):
+
+- "how much have I spent on Claude Code"
+- "tokens used [yesterday|this week|in April|...]"
+- "[which|what] project [costs the most|uses the most tokens|...]"
+- "MCP usage by project"
+- "Opus vs Sonnet usage"
+- "show my sessions in <project> last month"
+- "how often am I using the <plugin> plugin"
+- "full usage report for [quarter|year|...]"
+- "any spike in usage recently"
+- "do I have any expensive sessions"
+- "what tools am I leaning on"
+
+If the user's question maps to one of those, invoke the CLI rather than
+guessing or trying to read the JSONLs yourself.
+
+## How to translate questions into CLI invocations
+
+The CLI's grammar:
+
+```
+claude-code-usage query
+  [--since YYYY-MM-DD] [--until YYYY-MM-DD]
+  [--project NAME] [--session NAME_OR_UUID] [--model SUBSTR]
+  [--mcp SERVER] [--plugin PLUGIN] [--tool TOOL]
+  [--group-by D1,D2,...]
+  [--format markdown|csv|json] [--top N] [--sort COL]
+  [--session-format name|uuid|both]
+  [--include-children]
+  [--exclude-hooks]
+
+claude-code-usage children <PARENT_SESSION>
+  [--format markdown|csv|json] [--top N] [--sort COL]
+```
+
+`--include-children`: when grouping by session, add a cost breakdown showing
+agent subagent activity and hook session costs. Two child types are handled:
+
+- **Agent subagents** (the `Agent()` tool): their JSONL files record the
+  parent's `sessionId`, so their costs are **already included** in `cost_usd`.
+  `--include-children` adds `agent_cost_usd` (what fraction of `cost_usd` came
+  from agent dispatches) and keeps the parent row visible.
+- **Hook sessions** (bash-security-review): these have their own UUID and are
+  billed separately. They are removed from the session list and their cost is
+  folded into `child_cost_usd` on the parent row.
+
+Added columns: `agent_cost_usd`, `child_session_count`, `child_token_total`,
+`child_cost_usd`, `total_cost_usd` (= `cost_usd + child_cost_usd`).
+
+**Important:** `query --group-by session` already includes agent subagent costs
+in `cost_usd`. Do NOT add `agent_cost_usd` to `cost_usd` — that would
+double-count. `agent_cost_usd` is a breakdown of cost already in `cost_usd`.
+
+`--exclude-hooks`: strip `bash-security-review.sh` hook sessions
+(classified as `initiation_type="hook-security-review"`) from all results
+before grouping. Useful whenever you want per-session cost breakdowns without
+the tiny ~$1.60 hook sessions distorting the totals. Use `--include-hooks`
+(alias for the default) to make it explicit that hooks are included.
+
+`--group-by` dimensions: `project, session, model, mcp, plugin, tool,
+day, week, month, year`. Combine freely.
+
+When grouping by `session`, the output column defaults to the human
+display name set via `claude -n` / `ccd <tag>` (e.g.
+`20260509-oneshot-test-claude-usage-skill`). Sessions whose name we
+have never seen in `~/.claude/sessions/*.json` (the live registry, which
+is ephemeral) are rendered as `sess-<uuid8>`. Pass
+`--session-format uuid` to get the full UUID instead, or
+`--session-format both` for a `session_name` + `session_id` pair.
+
+`--session` filters accept either a name (full or case-insensitive
+substring) or a UUID (full or 4+ char prefix), so users who think in
+names don't need to look up UUIDs.
+
+Recipes:
+
+| User asks                                             | Run                                                                                       |
+|-------------------------------------------------------|-------------------------------------------------------------------------------------------|
+| "How much have I spent in the last week?"             | `claude-code-usage query --since "$(date -d '7 days ago' +%F)"`                           |
+| "Tokens by project last week"                         | `claude-code-usage query --since "$(date -d '7 days ago' +%F)" --group-by project`        |
+| "Opus vs Sonnet usage in April"                       | `claude-code-usage query --since 2026-04-01 --until 2026-05-01 --group-by model`          |
+| "MCP usage by project for Feb / Mar / Apr by month"   | `claude-code-usage query --since 2026-02-01 --until 2026-05-01 --group-by project,mcp,month` |
+| "Sessions in oneshot in April 2026"                   | `claude-code-usage query --project oneshot --since 2026-04-01 --until 2026-05-01 --group-by session` |
+| "Top sessions in coparenting by cost"                 | `claude-code-usage query --project coparenting --group-by session`                        |
+| "What's the UUID for the test-claude-usage session?"  | `claude-code-usage query --session test-claude-usage --group-by session --session-format both` |
+| "Show today's sessions with UUIDs"                    | `claude-code-usage query --since "$(date +%F)" --group-by session --session-format both`  |
+| "How much does opentabs eat in tokens?"               | `claude-code-usage query --mcp opentabs --group-by month`                                 |
+| "Which native tools cost the most?"                   | `claude-code-usage query --group-by tool` then filter to kind=native in your summary      |
+| "Full report for Q2"                                  | `claude-code-usage report --since 2026-04-01 --until 2026-07-01 --output cc-sessions/<tag>/out/usage-report.md` |
+| "Are my numbers right?" / "Reconcile against ccusage" | `claude-code-usage reconcile --since 2026-04-01 --until 2026-05-01`                       |
+| "Show session cost breakdown (interactive vs agents vs hooks)" | `claude-code-usage query --group-by session --include-children`              |
+| "What did this session's agents / hooks cost?"        | `claude-code-usage children <session-name-or-uuid>`                                       |
+| "Session cost breakdown excluding hook fires"         | `claude-code-usage query --group-by session --exclude-hooks`                              |
+
+After running, summarise the headline figure(s) in chat in plain English.
+For complex breakdowns, save the full table to the session's `out/`
+directory and reference the path in the summary.
+
+## What's in the data
+
+Each row of the fact table is one billable assistant message and carries:
+`ts, session_id, project_name (= basename(cwd)), model, input_tokens,
+cache_creation_5m, cache_creation_1h, cache_read, output_tokens,
+tool_calls, message_id, ...`. Token-to-tool attribution splits a
+message's tokens evenly across its `tool_use` blocks; tool-call counts
+are tracked separately as a more reliable metric.
+
+**Parent/child session grouping (v0.3.0):** The parser classifies each
+session as `regular`, `hook`, or `subagent` and infers a `parent_session_id`
+where possible. Hook sessions (bash security-review checks) are linked to
+their parent when the `bash-security-review.sh` hook was able to embed a
+session-name prefix in the prompt - this only happens when exactly one
+`cc-sessions/` directory exists at the time the hook fires. Use
+`--include-children` with `--group-by session` to fold hook session
+tokens/cost into the parent row; use `children <session>` to list a
+parent's children individually.
+
+**Session metadata columns (v0.5.0):** Two new session-level columns:
+- `initiation_type`: `hook-security-review` | `prompt-file` | `interactive` |
+  `unknown`. Classified from the first real user text block. Use
+  `--exclude-hooks` to filter out hook sessions in any query.
+- `is_sidechain`: `True` if any record in the session has `isSidechain=True`.
+
+TODO: `--group-by initiation_type` is not yet implemented as a grouping
+dimension but would allow breaking usage down by session initiation type.
+
+`ccusage` is the canonical source of dollar figures. Our `cost_usd` is
+a self-consistent estimate that may differ - the `reconcile` sub-command
+shows both side by side. **Token counts are guaranteed to reconcile with
+ccusage within 0.5%**.
+
+Session display names are sourced from `~/.claude/sessions/*.json`
+(live registry, set by `claude -n`/`ccd`) and merged into a persistent
+on-disk cache at `<cache_dir>/session_names.json` so any name we ever
+saw is preserved after the live record is pruned. **As of v0.5.0,
+`warm-cache` also scans JSONL files for `custom-title` records** (written
+when the user runs `/rename` in a session), so sessions whose PID file was
+pruned before `warm-cache` ran will now be resolved correctly. UUID-only
+fallback (`sess-<uuid8>`) covers sessions launched without `-n` that were
+never renamed.
+
+## Setup on a new machine
+
+This block lives in the skill body (not the frontmatter / preview note)
+so that it travels with the skill when it's deployed elsewhere.
+
+The recipes above call `claude-code-usage` directly (not `uv run
+claude-code-usage`). For that to work, the CLI must be on `PATH`. The
+canonical install is via `uv tool install ~/repos/claude-code-session-tools`,
+which builds a wheel from the local clone and drops shims into `uv tool dir
+--bin` (typically `~/.local/bin`). Non-editable install means the source is
+copied at install time - no fragile `.pth` pointer that breaks when a git
+worktree is deleted.
+
+> **WARNING:** Never run `uv tool install` from inside a git worktree. If you
+> develop on a feature branch in a worktree and need to test the CLI, use
+> `uv run` within the worktree instead. After merging a PR, run
+> `uv tool install ~/repos/claude-code-session-tools` from any directory to
+> update the global install.
+
+```bash
+# 1. Clone the repo
+git clone https://github.com/raffishquartan/claude-code-session-tools.git \
+    ~/repos/claude-code-session-tools
+
+# 2. Install the CLI globally (puts ccd, ccr, ccs, claude-code-usage on PATH)
+#    Install uv first if needed: https://docs.astral.sh/uv/getting-started/
+uv tool install ~/repos/claude-code-session-tools
+claude-code-usage --version    # should print the version
+#    If tools are not found, ensure `uv tool dir --bin` is on your PATH
+#    (run `uv tool update-shell` or add it to your shell rc file).
+
+# 3. (Optional) project-local dev venv with test deps, for hacking on
+#    the CLI. Not required for normal skill use.
+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
+bun add -g ccusage
+ccusage --version
+
+# 5. The skill lives inside the cc-session-tools repo at skills/analyse-cc-usage/.
+#    Symlink it to ~/.claude/skills/ so it is discoverable:
+ln -s ~/repos/claude-code-session-tools/src/cc_session_tools/skills/analyse-cc-usage \
+    ~/.claude/skills/analyse-cc-usage
+
+# 6. Warm the cache (first run is the slow one)
+claude-code-usage warm-cache
+
+# 7. Sanity-check by reconciling against ccusage
+claude-code-usage reconcile
+```
+
+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.
+
+## Performance notes
+
+The mtime-keyed parquet cache makes re-runs sub-second:
+
+- Cold parse of `~/.claude/projects` (1.7 GB / 7,256 files): ~11 s
+- Warm with no changes: < 1 s
+- Warm with a few new sessions since last run: ~3 s
+
+Cache location: `~/.cache/claude-code-usage/parquet/` by default
+(platformdirs user_cache_dir). Override with `--cache-dir`.
+
+## Repo
+
+- Local: `~/repos/claude-code-session-tools`
+- GitHub: <https://github.com/raffishquartan/claude-code-session-tools> (public, MIT)
+- Run `uv run pytest` after any change. The schema sanity check is the
+  early warning if Anthropic ever changes the JSONL format.

cc_session_tools-2.3.0/src/cc_session_tools/skills/delete-sessions/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: delete-sessions
+description: Use when the user wants to permanently delete one or more Claude Code sessions. Triggers on "delete session", "delete sessions", "remove empty sessions", "clean up sessions", "delete these sessions", "remove these cc-sessions", "/delete-sessions". Inputs must be explicit session basenames; the user (or the list-empty-sessions skill) must supply them. Gates every deletion behind an 8-digit confirmation code.
+---
+
+<!--
+Copyright (c) 2026 raffishquartan. All rights reserved.
+Licensed for personal use only.
+-->
+
+# Delete sessions
+
+Permanently delete one or more Claude Code sessions: the `cc-sessions/<basename>/`
+directory, the JSONL transcript, the `.tag` file, and (optionally) the
+`~/.claude/tasks/<encoded>/` task directory.
+
+**Dry-run by default.** The script prints a deletion plan and exits 0. Pass
+`--execute` to actually delete. Always review the plan before executing.
+
+**8-digit confirmation gate.** In `--execute` mode the script generates an
+8-digit code, prints it, and requires the user to type it back exactly. The
+deletion proceeds only if the code matches.
+
+## When to use
+
+- The user explicitly names one or more session basenames and asks to delete
+  them.
+- The `list-empty-sessions` skill has produced a list of basenames and the
+  user confirms they want to remove them.
+
+## When NOT to use
+
+- Listing which sessions are empty — that is the `list-empty-sessions` skill.
+  This skill deletes; it does not discover.
+- Cleaning up hook-security-check transcripts — that is the
+  `clean-hook-sessions` skill.
+- The user wants to move or rename a session — use `move-session`.
+
+## Inputs
+
+Positional arguments only: one or more session **basenames** (the
+`YYYYMMDD-<tag>` directory name under `cc-sessions/`).
+
+```
+python3 ~/.claude/skills/delete-sessions/scripts/delete_sessions.py \
+    20260516-demo-empty 20260517-beta-empty
+```
+
+The script searches for each basename locally first (under the current
+project's `cc-sessions/`), then across all configured roots. It does **not**
+accept filesystem paths — pass the basename, not the full path.
+
+## Pre-flight checks (all required — fail fast on any)
+
+1. **Format check.** Every basename must match the session-name format
+   (`YYYYMMDD-<tag>` pattern). If any does not, the script exits 1 immediately.
+
+2. **Existence check.** Every basename must resolve to a real
+   `cc-sessions/<basename>/` directory somewhere reachable. If any is missing,
+   the script exits 1 with a list of what could not be found.
+
+3. **In-session refusal.** If any of the named sessions is the *currently
+   running* CC session, the script refuses outright with exit code 2. There is
+   no override — see "In-session refusal" below.
+
+4. **Empty-only guard.** By default the script refuses to delete non-empty
+   sessions (those that contain at least one real user-typed message). Pass
+   `--allow-non-empty` to bypass this. When blocked, the script lists which
+   sessions are non-empty so the user knows what is preventing deletion.
+
+## What is deleted (per session)
+
+| Artefact | Path |
+|----------|------|
+| Session folder | `<project-cwd>/cc-sessions/<basename>/` |
+| JSONL transcript | `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl` |
+| Tag mapping row | `~/.local/share/claude/sessions.db` — `session_tags` row keyed by `<uuid>`, removed via `sessions_db.delete_tag` (not a filesystem artefact) |
+| Enumeration row | `~/.local/share/claude/sessions.db` — `sessions` row keyed by `(<project-cwd>, <basename>)`, removed via `sessions_db.delete_session_row` so the session stops appearing in `ccr`/`ccs` |
+| Tasks directory | `~/.claude/tasks/<encoded-session-dir>/` (if present, skipped with `--no-tasks`) |
+
+The dry-run plan prints the exact paths that would be deleted so you can
+verify before committing.
+
+## In-session refusal
+
+If the user asks to delete the session they are currently inside, the script
+exits 2 and explains why. There is no override flag.
+
+**Detection signals** (same as `move-session`): refusal fires if `in_cc` AND
+**either** (a) the session JSONL was modified within the last 30 seconds, OR
+(b) `realpath(getcwd()) == session_project_cwd` AND the session JSONL is the
+most-recently-modified non-hook-security JSONL in the project key directory.
+
+## Quick reference
+
+```
+python3 ~/.claude/skills/delete-sessions/scripts/delete_sessions.py \
+    [--allow-non-empty] \
+    [--no-tasks] \
+    [--execute] \
+    <basename> [<basename> ...]
+```
+
+| Flag | Meaning |
+|------|---------|
+| `<basename>` | One or more `YYYYMMDD-<tag>` basenames. Required. |
+| `--allow-non-empty` | Also delete sessions that contain real user messages. Still 8-digit gated. |
+| `--no-tasks` | Skip `~/.claude/tasks/<encoded>/` deletion. |
+| `--execute` | Actually delete. Without this flag the script only prints a plan. |
+
+## 8-digit confirmation flow (--execute only)
+
+1. The script prints the deletion plan.
+2. It generates a fresh 8-digit code and prints it.
+3. The user types the code back.
+4. If the code matches exactly, deletion proceeds. If not, the script exits 1
+   with no deletions made.
+
+The model's role: present the code to the user with the line
+`"Respond with <code> to confirm deletion."` and then pass the user's reply
+into the script's stdin.
+
+## Deletion behaviour
+
+- Artefacts are deleted one at a time; each deletion is reported on its own
+  line.
+- On any `OSError` the error is printed and the script continues (best-effort
+  for the remaining artefacts).
+- Exit `0` if every artefact was either deleted or already absent.
+- Exit `1` if any `OSError` occurred during deletion.
+
+## Common mistakes
+
+- **Forgetting `--execute`.** Default is dry-run. The plan is printed but
+  nothing is deleted. Check the output for `DRY-RUN` before reporting success.
+
+- **Trying to delete the currently-running session.** The script detects this
+  and refuses with exit 2. Exit CC first, then re-run the script from a normal
+  shell.
+
+- **Trying to delete a non-empty session without `--allow-non-empty`.** If the
+  JSONL contains even one real user message, the script refuses by default.
+  This is intentional — non-empty sessions might contain valuable work. Review
+  the session contents before using `--allow-non-empty`.
+
+- **Confusing basename with just the tag portion.** The script expects the full
+  `YYYYMMDD-<tag>` basename (e.g. `20260516-demo-session`), not just the tag
+  (`demo-session`). The `list-empty-sessions` skill outputs full basenames
+  ready for copy-paste.
+
+## Defaults and safety
+
+- **Dry-run by default.** Pass `--execute` to make filesystem changes.
+- **Empty-only by default.** Pass `--allow-non-empty` to also delete sessions
+  with real user messages.
+- **8-digit gated.** All `--execute` runs require a confirmation code.
+- **No source clobber recovery.** Deletion is permanent. Unlike `move-session`,
+  there is no cleanup script — once you confirm, the files are gone.