copilot-session-usage 0.8.4__tar.gz → 0.9.1__tar.gz

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/.github/changes/requests/skill-breakdown/01-request.md

@@ -130,16 +130,16 @@ Cache session metadata (title, created_at, has_debug_logs, debug_log_dir) in a s
 
 ## Acceptance criteria
 
-- [ ] `copilot-session-usage id <uuid> --skill-breakdown` prints a per-skill cost table.
-- [ ] `copilot-session-usage list --title <substring>` returns only matching sessions.
-- [ ] `copilot-session-usage analyze --title <substring> --latest` analyzes the most recent matching session.
-- [ ] `copilot-session-usage id <uuid> --skill "<name>"` filters the report to that skill.
-- [ ] Subagents spawned by `runSubagent` show their real name, not `unknown`.
-- [ ] `copilot-session-usage id <uuid> --tool-breakdown` prints per-skill/per-subagent tool-call counts.
-- [ ] `copilot-session-usage id <uuid> --format json --minimal` returns a small, stable JSON object.
-- [ ] `copilot-session-usage skills --last 7d` lists skills with aggregated cost.
-- [ ] All new features are covered by unit tests.
-- [ ] `just preflight` passes.
+- [x] `copilot-session-usage id <uuid> --skill-breakdown` prints a per-skill cost table.
+- [x] `copilot-session-usage list --title <substring>` returns only matching sessions.
+- [x] `copilot-session-usage analyze --title <substring> --latest` analyzes the most recent matching session.
+- [x] `copilot-session-usage id <uuid> --skill "<name>"` filters the report to that skill.
+- [x] Subagents spawned by `runSubagent` show their real name, not `unknown`.
+- [x] `copilot-session-usage id <uuid> --tool-breakdown` prints per-skill/per-subagent tool-call counts.
+- [x] `copilot-session-usage id <uuid> --format json --minimal` returns a small, stable JSON object.
+- [x] `copilot-session-usage skills --last 7d` lists skills with aggregated cost.
+- [x] All new features are covered by unit tests.
+- [x] `just preflight` passes.
 
 ## Non-goals
 

copilot_session_usage-0.9.1/.github/skills/record-finding/README.md

@@ -0,0 +1,48 @@
+# Record Finding
+
+`record-finding` is a handoff tool for investigations that outgrow the current
+model. When a small model struggles to reach a reliable conclusion, it can leave
+the maximum useful evidence for a bigger model to continue from.
+
+## Why use this skill?
+
+Debugging sessions and log investigations often reach a useful boundary before
+they reach a reliable conclusion. A small model may have already found the
+relevant files, tested several explanations, and identified what remains unclear,
+but lack the context window or reasoning capacity to finish. If that partial work
+stays in the conversation, a bigger model has to rediscover it.
+
+Usage:
+
+```md
+/record-findings
+```
+
+## Use it when
+
+- a small or fast model is stuck after a meaningful investigation;
+- you need to hand off debugging context to a bigger model without starting over;
+- you have finished diagnosing a bug or unexpected behavior;
+- you verified how VS Code, Copilot, pricing, or session logs behave; or
+- you discovered a non-trivial fact that another investigation may need.
+
+The skill writes exactly one immutable file under `knowledge/findings/` and runs
+the knowledge-base validation checks.
+
+## Do not use it for
+
+- team standards or rules, which belong in a Principle;
+- descriptions of how a system or object is composed, which belong in a Structure;
+- stable, consolidated ideas, which belong in a Concept; or
+- a collection of unrelated observations.
+
+Record one claim at a time. If a conclusion changes later, add a new Finding that
+links to the earlier one instead of rewriting the historical record.
+
+## Example prompts
+
+- "I am stuck on why this Copilot session has no model name. Record everything a
+  bigger model needs to continue."
+- "Create a Finding from the investigation of the pricing mismatch."
+- "Save the parser behavior, attempted fixes, and open questions as an OKF
+  Finding for a bigger model."

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copilot-session-usage
-Version: 0.8.4
+Version: 0.9.1
 Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
 Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
 Project-URL: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/
@@ -70,7 +70,7 @@ Copilot CLI/App event logs and turns them into repeatable reports. It provides:
 | Estimated cost (`$`) **per model** | ❌ No accurate cost per breakdown | ✅ |
 | Tokens **per subagent** | ⚠️ LLM digging each time; consumes tokens | ✅ |
 | Estimated cost (`$`) **per subagent** | ❌ No accurate cost per breakdown | ✅ |
-| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ |
+| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ Limited timeline attribution (VS Code) |
 | Tool-call counts by skill and subagent | ⚠️ LLM digging each time | ✅ |
 | Batch analysis, filtering, and aggregation | Limited/conversational | ✅ |
 | Stable JSON, table, and detailed output | No stable contract | ✅ |
@@ -82,6 +82,13 @@ In the table, `⚠️` means that Chronicle may answer the question in a particu
 environment or with additional analysis, but does not guarantee a stable, reproducible
 breakdown for it.
 
+Skill token and cost attribution is limited: VS Code requests are grouped under
+the latest explicit slash-command skill, including the whole request context and
+later work until another invocation. This is not an isolated measurement of tokens
+or cost caused by the skill; automatically loaded and overlapping skills cannot be
+separated. CLI/App per-skill tokens and costs are unavailable. See
+[Skill attribution](docs/source/explanation/how-cost-estimation-works.md#skill-attribution).
+
 Use Chronicle for **“What did I do?”** and use this project for **“How much did it cost,
 which model or subagent consumed it, and can I export the evidence?”**
 
@@ -165,9 +172,11 @@ copilot-session-usage list --dir /path/to/debug-logs --format table
 - **Session filtering** — regex match by name, date-range filtering
 - **Aggregation** — roll up costs across many sessions in one command
 - **Skill-aware cost attribution** — detect skills, attribute LLM and tool calls to the active skill
+- **Skill-source detection** — inspect slash commands, discovery events, system prompts, and skill tools
 - **Skill cost breakdown** — per-skill token counts and estimated cost (VS Code provider)
 - **Tool-call attribution** — per-skill/per-subagent tool-call counts
 - **Title filtering** — find sessions by title substring
+- **Metadata cache** — reuse session indexes until the workspace database changes
 - **Efficiency summaries** — cache ratio, model split, cost per 1M tokens
 - **Field extraction** — pull specific values with `--query`
 
@@ -181,9 +190,17 @@ copilot-session-usage list --dir /path/to/debug-logs --format table
 `~/.config/Code/User/workspaceStorage/` (Linux).
 
 Each session directory contains a `GitHub.copilot-chat/debug-logs/` folder with
-JSONL files. The tool parses these files, extracts token counts per model,
-applies per-model pricing (including cache-hit discounts and long-context tier
-switching), and estimates the session cost in USD.
+JSONL files plus optional `system_prompt_*.json` and `tools_*.json` artifacts.
+The tool parses the JSONL files, extracts token counts per model, applies
+per-model pricing (including cache-hit discounts and long-context tier
+switching), and estimates the session cost in USD. Skill detection also reads
+the optional system-prompt skill list and skill tool definitions. Those artifacts
+identify available skills; only timestamped slash-command user messages drive
+the active-skill attribution timeline.
+
+Session metadata from `state.vscdb` is cached in a small local index keyed by
+workspace hash. The index stores metadata only, never raw logs or message
+content, and is invalidated when the source database mtime changes.
 
 Subagent calls (`runSubagent`) are tracked separately so you can see how much
 token usage was delegated to helper agents.
@@ -262,6 +279,7 @@ just knowledge-validate
 | `--workspace PATH` | Only sessions from this workspace folder |
 | `--aggregate` | Aggregate all matching sessions into one summary |
 | `--summary` | Output a cost-efficiency summary |
+| `--minimal` | Alias for `--detail minimal` on analysis commands |
 | `--skill-breakdown` | Emit a per-skill cost breakdown |
 | `--tool-breakdown` | Emit a per-skill/per-subagent tool-call count breakdown |
 | `--skill NAME` | Filter the report to a single skill |

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/README.md

@@ -52,7 +52,7 @@ Copilot CLI/App event logs and turns them into repeatable reports. It provides:
 | Estimated cost (`$`) **per model** | ❌ No accurate cost per breakdown | ✅ |
 | Tokens **per subagent** | ⚠️ LLM digging each time; consumes tokens | ✅ |
 | Estimated cost (`$`) **per subagent** | ❌ No accurate cost per breakdown | ✅ |
-| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ |
+| Cost attribution to skills | ❌ Cannot provide cost per breakdown | ✅ Limited timeline attribution (VS Code) |
 | Tool-call counts by skill and subagent | ⚠️ LLM digging each time | ✅ |
 | Batch analysis, filtering, and aggregation | Limited/conversational | ✅ |
 | Stable JSON, table, and detailed output | No stable contract | ✅ |
@@ -64,6 +64,13 @@ In the table, `⚠️` means that Chronicle may answer the question in a particu
 environment or with additional analysis, but does not guarantee a stable, reproducible
 breakdown for it.
 
+Skill token and cost attribution is limited: VS Code requests are grouped under
+the latest explicit slash-command skill, including the whole request context and
+later work until another invocation. This is not an isolated measurement of tokens
+or cost caused by the skill; automatically loaded and overlapping skills cannot be
+separated. CLI/App per-skill tokens and costs are unavailable. See
+[Skill attribution](docs/source/explanation/how-cost-estimation-works.md#skill-attribution).
+
 Use Chronicle for **“What did I do?”** and use this project for **“How much did it cost,
 which model or subagent consumed it, and can I export the evidence?”**
 
@@ -147,9 +154,11 @@ copilot-session-usage list --dir /path/to/debug-logs --format table
 - **Session filtering** — regex match by name, date-range filtering
 - **Aggregation** — roll up costs across many sessions in one command
 - **Skill-aware cost attribution** — detect skills, attribute LLM and tool calls to the active skill
+- **Skill-source detection** — inspect slash commands, discovery events, system prompts, and skill tools
 - **Skill cost breakdown** — per-skill token counts and estimated cost (VS Code provider)
 - **Tool-call attribution** — per-skill/per-subagent tool-call counts
 - **Title filtering** — find sessions by title substring
+- **Metadata cache** — reuse session indexes until the workspace database changes
 - **Efficiency summaries** — cache ratio, model split, cost per 1M tokens
 - **Field extraction** — pull specific values with `--query`
 
@@ -163,9 +172,17 @@ copilot-session-usage list --dir /path/to/debug-logs --format table
 `~/.config/Code/User/workspaceStorage/` (Linux).
 
 Each session directory contains a `GitHub.copilot-chat/debug-logs/` folder with
-JSONL files. The tool parses these files, extracts token counts per model,
-applies per-model pricing (including cache-hit discounts and long-context tier
-switching), and estimates the session cost in USD.
+JSONL files plus optional `system_prompt_*.json` and `tools_*.json` artifacts.
+The tool parses the JSONL files, extracts token counts per model, applies
+per-model pricing (including cache-hit discounts and long-context tier
+switching), and estimates the session cost in USD. Skill detection also reads
+the optional system-prompt skill list and skill tool definitions. Those artifacts
+identify available skills; only timestamped slash-command user messages drive
+the active-skill attribution timeline.
+
+Session metadata from `state.vscdb` is cached in a small local index keyed by
+workspace hash. The index stores metadata only, never raw logs or message
+content, and is invalidated when the source database mtime changes.
 
 Subagent calls (`runSubagent`) are tracked separately so you can see how much
 token usage was delegated to helper agents.
@@ -244,6 +261,7 @@ just knowledge-validate
 | `--workspace PATH` | Only sessions from this workspace folder |
 | `--aggregate` | Aggregate all matching sessions into one summary |
 | `--summary` | Output a cost-efficiency summary |
+| `--minimal` | Alias for `--detail minimal` on analysis commands |
 | `--skill-breakdown` | Emit a per-skill cost breakdown |
 | `--tool-breakdown` | Emit a per-skill/per-subagent tool-call count breakdown |
 | `--skill NAME` | Filter the report to a single skill |

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/docs/source/explanation/how-cost-estimation-works.md

@@ -56,8 +56,8 @@ token-count events emitted by the Copilot extension for each LLM call:
 - `model` — the model name as reported by the provider
 
 A single session may call multiple models (e.g., Claude Sonnet for the main
-request and Claude Haiku for a subagent). Each model's tokens are summed
-separately, then costs are computed per model and aggregated.
+request and Claude Haiku for a subagent). Each request is priced separately,
+then its tokens and cost are aggregated by model, subagent, and active skill.
 
 ### Utility models
 
@@ -78,21 +78,20 @@ The VS Code debug log reports `inputTokens` as the **total** prompt sent
 (cached + non-cached combined). `cachedTokens` is the subset served from
 the provider's cache. The non-cached portion is `inputTokens − cachedTokens`.
 
-Each `llm_request` event also carries `copilotUsageNanoAiu` — VS Code's own
-cost for that call in nano-AI Credits (nanoAIU). It is present for all
-Copilot-plan models (Claude, GPT, and others). It is absent for Azure-hosted
-models not billed via Copilot AIC — `Kimi-K2.6-azure` is one such model:
-it is billed through Azure separately and correctly reports $0 AIC.
+An `llm_request` event can also carry `copilotUsageNanoAiu` — VS Code's own
+cost for that call in nano-AI Credits (nanoAIU). Recent logs expose it for
+Copilot-plan models (Claude, GPT, and others), but it can be missing.
+Absence alone does not establish a zero bill or identify an external provider.
 
-When `copilotUsageNanoAiu` is present and non-zero, the tool uses it directly:
+When `copilotUsageNanoAiu` is present, including zero, the tool uses it directly:
 
 ```
 cost_usd = copilotUsageNanoAiu / 100_000_000_000   (1 nanoAIU = 1e-11 USD)
 ```
 
-For models that do not report `copilotUsageNanoAiu` — Azure-hosted models billed
-outside the Copilot plan — the tool falls back to token-based computation
-(or $0 when the model has no Copilot pricing entry):
+For individual requests without `copilotUsageNanoAiu`, the tool falls back to
+token-based computation. An unknown model uses the generic fallback rate and is
+listed in `fallback_pricing_models`; it is not automatically treated as free:
 
 ```
 cost_usd = (
@@ -102,10 +101,18 @@ cost_usd = (
 ) / 1_000_000
 ```
 
-plus the Anthropic cache-write approximation when applicable.
+plus the cache-write premium approximation when the rate card defines one,
+including Anthropic and GPT-5.6 and later models. Fallback tiers are selected
+from each request's input tokens, not a model's accumulated session tokens.
+Billed and estimated requests can coexist without either being dropped.
 
-Verified on a real session: `copilotUsageNanoAiu`-based cost matches the
-VS Code AIC panel at **0.000% error** for Claude models.
+On 2026-10-07, an audit of 34 fully billed local sessions matched the sum of
+VS Code's billed nano-credit telemetry at the output's four-decimal USD precision.
+The inspected VS Code 1.140.0 debug-summary implementation sums this same field.
+The audit included GPT and Claude requests; it did not verify every model against
+an invoice. Exact parity requires complete billing telemetry. Token-only cache
+estimates cannot guarantee it. Breakdowns round to six decimals, so their sums
+can differ slightly from the four-decimal session total.
 
 ---
 
@@ -121,18 +128,39 @@ Subagent names are extracted from the JSONL filename
 
 ## Skill attribution
 
-Skills are detected from three sources in the debug logs:
+Skills are detected from four sources in the debug logs:
 
 - `user_message` events containing slash commands such as `/skill-name` or
   `/namespace skill-name`.
 - `discovery` events of type `Skill Discovery` that list loaded skills.
 - `generic` events named `Custom Instructions` that enumerate on-demand skills.
+- `system_prompt_*.json` skill blocks and `tools_*.json` skill definitions.
 
 Each `llm_request` and `tool_call` is attributed to the most recently invoked
 skill at that timestamp. The result is included in the session report under the
 `skills` key and can be surfaced with `--skill-breakdown`, `--tool-breakdown`,
 or `--skill <name>`.
 
+System-prompt and tool artifacts establish detected or available skills only;
+timestamped slash-command user messages establish the active-skill timeline.
+Session metadata discovery uses a local workspace-hash index keyed by the
+`state.vscdb` mtime. The cache contains metadata such as titles and log paths,
+not raw debug logs or user message content.
+
+Skill costs preserve the same billed request amounts as the other breakdowns,
+but **skill token and cost attribution is limited**. Each request's full token
+counts and cost are assigned to the latest slash-command skill until another
+invocation occurs. These tokens include conversation history, instructions, and
+tool results, not just the skill's own text or incremental token consumption.
+
+Detection does not establish attribution: discovery events identify skills but
+do not independently assign request usage to them. Automatically loaded or read
+skills and overlapping skill use cannot be separated. Unrelated work after a
+skill invocation can remain attributed to that skill, while requests before any
+invocation belong to `unknown`. Exact billed request costs do not make the skill
+assignment causal or exact. CLI/App cumulative usage does not provide a validated
+per-skill token or cost split; those breakdowns remain unavailable.
+
 ---
 
 ## Copilot CLI / Copilot App provider (`--agent cli`)
@@ -202,28 +230,40 @@ added to `diagnostics` explaining what was skipped.
 
 ### Cost calculation
 
-The shared, token-based pricing calculation (the same as the VS Code
-provider's, described above) is applied to the per-model `usage` reported in
-`session.shutdown`. Copilot CLI's own per-model billing figure,
-`totalNanoAiu`, is *not* used for this calculation: it is reported separately
-under `provider_usage.total_nano_aiu` and never substituted for or blended
-into `total.estimated_usd` or `model_breakdown[].estimated_usd`, since it is
-not validated to carry the same USD-billing meaning as VS Code's own
-`copilotUsageNanoAiu` field.
+Copilot CLI's billed figures are used first, mirroring the VS Code
+provider's use of `copilotUsageNanoAiu` (1 nanoAIU = 1e-11 USD):
+
+- `total.estimated_usd` is the session-level `totalNanoAiu`, which is
+  cumulative across resumes (the largest value from the last
+  `session.shutdown` or `session.usage_checkpoint`).
+- Each `model_breakdown` row uses that model's `totalNanoAiu`. Without it, the
+  model's tokens are priced exactly: `inputTokens` includes cache reads and
+  cache writes, so fresh input is `inputTokens - cacheReadTokens -
+  cacheWriteTokens`, and only `cacheWriteTokens` are charged at the
+  cache-write rate. The pricing tier is chosen from the average request size,
+  not the session sum.
+- `subagents` lists the main agent and each subagent from
+  `session.shutdown.agentMetrics`, with their own billed `totalNanoAiu`.
+- Per-model and per-agent metrics omit segments that ended without a
+  `session.shutdown` (a crash or kill before a resume). That remainder is
+  reported as `total.unattributed_usd`, with a diagnostic, so
+  breakdowns plus `unattributed_usd` always equal the total.
+
+Across 101 local CLI/App sessions, totals matched the billed `totalNanoAiu`
+exactly and breakdowns reconciled with it. Pricing tokens with the exact
+cache-write count reproduced per-model billed amounts for 89 of 96 models;
+the rest included long-context requests or discounts invisible in aggregates.
 
 ### When usage is unavailable
 
 A session that is still active, or that was interrupted before shutting down,
 has no `session.shutdown` event. In that case:
 
-- Per-model token totals, the model breakdown, skill cost breakdown, and the
-  shared `total` block (tokens, cost, cache ratio) are all unavailable — they
-  are represented as `null`/missing, **never** as a fabricated zero.
-- If a `session.usage_checkpoint` exists, its cumulative `totalNanoAiu` and
-  `totalPremiumRequests` are still reported under `provider_usage` (separate
-  from the shared token/cost calculation), but the shared `total` block stays
-  unavailable — there is no per-model token breakdown at checkpoint
-  granularity to price.
+- Per-model token totals, the model breakdown, and skill cost breakdown are
+  unavailable — they are represented as `null`/missing, **never** as a
+  fabricated zero.
+- If a `session.usage_checkpoint` exists, its cumulative `totalNanoAiu`
+  provides `total.estimated_usd`, entirely reported as `unattributed_usd`.
 - `diagnostics` explains exactly what is unavailable and why.
 - Batch/aggregate operations exclude sessions with unavailable evidence from
   their sums (rather than counting them as zero) and report how many were
@@ -261,18 +301,16 @@ to:
   and duration — all evidence taken directly from `subagent.started`/
   `subagent.completed`.
 
-The shared, per-subagent `subagents` block (the same contract VS Code
-populates with a validated input/output/cached split per subagent) stays
-empty for `cli` sessions: `subagent.completed` reports only a single combined
-`totalTokens` figure, with no validated split to populate that contract
-without fabricating it.
+The shared, per-subagent `subagents` block is built from
+`session.shutdown.agentMetrics`: one row for `main` and one per subagent,
+with per-model tokens (including `cache_write_tokens`) and the agent's billed
+`totalNanoAiu`. CLI versions that do not emit `agentMetrics` leave it empty.
 
 ### Provider-native counters
 
-`provider_usage` always carries Copilot CLI's own counters — `total_nano_aiu`,
-`total_premium_requests`, `shutdown_type`, `resume_count`, and `code_changes`
-— separately from the shared `total` block. These are never substituted for
-the shared token/estimated-USD calculation.
+`provider_usage` carries Copilot CLI's own counters — `total_nano_aiu`,
+`total_premium_requests`, `shutdown_type`, `resume_count`, and `code_changes`.
+`total_nano_aiu` is the same cumulative figure used for `total.estimated_usd`.
 
 ---
 

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/docs/source/how-to/add-commit-trailer.md

@@ -32,9 +32,9 @@ and model names keep the casing from `data/models-and-pricing.yml`.
 Token counts are expressed in millions of tokens with two decimals. The
 `aic` value and the `Copilot-Session-Usage-AIC` line show the cost in AI
 credits (1 AIC = $0.01) with two decimals. If the commit already contains
-`Copilot-Session-Usage-Acc` or `Copilot-Session-Usage-AIC` trailers, they are
-replaced so the values stay fresh. Other trailers, such as `Signed-off-by`,
-are preserved and kept at the end of the message.
+usage trailers, they are replaced so the values stay fresh. Optional session ID,
+name, and type trailers are removed when their options are omitted on a later amendment.
+Other trailers, such as `Signed-off-by`, are preserved and kept at the end of the message.
 
 ## From VS Code Copilot context
 
@@ -110,6 +110,40 @@ Copilot-Session-Usage-AIC: 232
 This will allow another process, not done by Copilot-Session-Cost, to later rewrite
 the commit chain with commit-accurate costs.
 
+## Add client metadata
+
+Pass either or both of these optional parameters:
+
+- `--session-type TEXT`: the name of the tool, process, or framework that uses
+  `copilot-session-usage` to set commit trailers.
+- `--session-name TEXT`: the name of the current change, PRD folder, or identifier
+  of the whole coding session. It usually corresponds to one session ID, but the
+  same name can span several session IDs.
+
+These fields are for clients to consume. `copilot-session-usage` writes them as
+trailers but does not use them for session discovery, grouping, or cost analysis.
+They do not require `--with-session-id`.
+
+```bash
+copilot-session-usage amend-commit \
+  --session-id "abc-123" \
+  --session-id "def-456" \
+  --with-session-id \
+  --session-type "MyFrameWork" \
+  --session-name "auth-refactor"
+```
+
+The command adds one trailer for each supplied metadata value, regardless of the
+number of session IDs:
+
+```text
+Copilot-Session-Usage-Session-Name: auth-refactor
+Copilot-Session-Usage-Session-Type: MyFrameWork
+```
+
+Use the same name across commits for the same change, even when the session ID changes.
+Supply the metadata options on each amendment to retain them.
+
 ## Preview before amending
 
 Use `--dry-run` to see the trailers that would be injected without modifying

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/docs/source/how-to/analyze-specific-session.md

@@ -101,7 +101,16 @@ Path-based analysis requires choosing one provider.
 ## Skill-aware analysis
 
 When a session invokes a skill (for example `/compendium-generic get-session-costs`),
-you can attribute costs and tool calls to that skill.
+you can group VS Code request tokens, costs, and tool calls under that skill.
+
+:::{note}
+Skill token and cost attribution is limited to the latest explicit slash-command
+invocation. It assigns the whole request context, not just the skill text or usage
+caused by that skill. Automatically loaded skills, overlapping skills, and later
+unrelated work cannot be reliably separated; requests before any invocation are
+grouped under `unknown`. CLI/App per-skill tokens and costs remain unavailable.
+See [How cost estimation works](../explanation/how-cost-estimation-works.md).
+:::
 
 ```bash
 # Per-skill cost breakdown for a session
@@ -113,9 +122,12 @@ copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56 --tool-breakdown
 # Concise cost for a single skill
 copilot-session-usage id 3a91c012-1b4e-4c8a-9f72-ab12cd34ef56 \
   --skill "/compendium-generic get-session-costs" \
-  --format json --detail minimal
+  --format json --minimal
 ```
 
+`--minimal` is an alias for `--detail minimal`; both forms return the stable
+single-skill fields without the full session breakdown.
+
 ## List skills across sessions
 
 ```bash

{copilot_session_usage-0.8.4 → copilot_session_usage-0.9.1}/docs/source/how-to/copilot-cli-provider.md

@@ -99,10 +99,9 @@ Diagnostics:
 ```
 
 When a `session.usage_checkpoint` is available (a periodic cumulative
-counter), its provider-native counters (`total_nano_aiu`,
-`total_premium_requests`) are still reported under `provider_usage`, but the
-shared `total` block (tokens, cost, cache ratio) stays unavailable — there is
-no per-model token breakdown at checkpoint granularity to price. See
+counter), its billed `totalNanoAiu` provides `total.estimated_usd`, reported
+entirely as `total.unattributed_usd` because there is no per-model breakdown
+at checkpoint granularity. See
 [How cost estimation works](../explanation/how-cost-estimation-works.md)
 (Copilot CLI / Copilot App provider section) for the full breakdown of what
 is and isn't available at each stage.
@@ -121,10 +120,9 @@ everything into `main`. `--tool-breakdown` shows the resolved subagent name
 (or the raw `agentId` when a `subagent.started` event wasn't captured) in its
 `subagent` column. `provider_usage.subagents` separately preserves the raw
 per-subagent evidence available from the event log (name, model, tool-call
-count, a combined `total_tokens_reported`, and duration) — this is kept
-apart from the shared, per-subagent `subagents` cost contract, which stays
-empty for `cli` sessions because `subagent.completed` reports only a single
-combined token count, not a validated input/output/cached split.
+count, a combined `total_tokens_reported`, and duration). The shared
+`subagents` cost block is built from `session.shutdown.agentMetrics` (main
+agent plus each subagent, with billed `totalNanoAiu`).
 
 ## What's different from the VS Code provider
 
@@ -132,14 +130,10 @@ combined token count, not a validated input/output/cached split.
   `cli` sessions: `events.jsonl` only exposes cumulative session-level token
   totals, not per-request ones. `skills.detected` and `--tool-breakdown` are
   still fully populated, including subagent attribution (see above).
-- The shared, per-subagent `subagents` block (cost split by subagent) is
-  always empty for `cli` sessions — see "Subagent and skill attribution"
-  above for the separate, evidence-preserving `provider_usage.subagents`.
-- Provider-native counters (`total_nano_aiu`, `total_premium_requests`, and
-  similar) are reported separately under `provider_usage` and never replace
-  the shared token/estimated-USD calculation — including nanoAiu, which is
-  informational only for this provider and is never used to compute
-  `total.estimated_usd`.
+- Costs use Copilot's billed `totalNanoAiu` (session, per model, per agent).
+  Without it, tokens are priced with the exact `cacheWriteTokens` count.
+  Usage from segments that ended without `session.shutdown` appears as
+  `total.unattributed_usd`.
 - Pricing lookups for `cli`/`all` are local-only by default (no runtime
   pricing refresh attempt), unlike the `vscode` provider's default daily
   refresh attempt. Run `copilot-session-usage pricing refresh` to update