agent-cost-tracker 0.2.1__tar.gz

agent_cost_tracker-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yingxiangge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_cost_tracker-0.2.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: agent-cost-tracker
+Version: 0.2.1
+Summary: Token, cache and context observability for AI coding agents.
+Author: yingxiangge
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/yingxiangge/agent-cost
+Project-URL: Repository, https://github.com/yingxiangge/agent-cost
+Project-URL: Issues, https://github.com/yingxiangge/agent-cost/issues
+Project-URL: Changelog, https://github.com/yingxiangge/agent-cost/blob/main/CHANGELOG.md
+Keywords: llm,tokens,cost,observability,codex,hermes,agent,claude-code,opencode
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agent-cost
+
+[![CI](https://github.com/yingxiangge/agent-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/yingxiangge/agent-cost/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**Token, cache and context observability for AI coding agents.**
+
+AI coding agents are expensive not because they have no cache — they usually
+have too much of it. `agent-cost` is a read-only CLI that shows you, per
+session or across multiple agents, how many tokens were really burned, where
+the context went, and which agent delivers the best prompt-caching efficiency.
+
+It was built from real-world usage across Codex, Hermes, and Claude Code. Across
+72 real Claude Code sessions (63.7M characters of transcript), the context
+attribution comes out as:
+
+```text
+tool_output   94.8%
+assistant      4.3%
+user           0.5%
+tool_calls     0.1%
+```
+
+Those same sessions total 9.1B billed prompt tokens at a 98.7% cache hit rate —
+a high hit rate does not protect you from unbounded context growth, it only
+changes the unit price.
+
+## Install
+
+```bash
+git clone https://github.com/yingxiangge/agent-cost.git
+cd agent-cost
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+Not on PyPI yet. The distribution will be published as **`agent-cost-tracker`**
+— `agent-cost` is taken on PyPI — while the command it installs stays
+`agent-cost`:
+
+```bash
+pip install agent-cost-tracker
+pipx run --spec agent-cost-tracker agent-cost compare ~/.claude/projects/
+```
+
+## Usage
+
+```bash
+# Compare usage, cache efficiency, and cost across multiple agents or sessions
+agent-cost compare ~/.claude/projects/ ~/.codex/sessions/ ./hermes/
+
+# Output structured JSON for analysis pipelines
+agent-cost compare --json ~/.claude/projects/ ~/.codex/sessions/
+
+# Inspect one session (Claude Code, Hermes, OpenCode, Codex, or a folder)
+agent-cost inspect ~/.codex/sessions/2026/08/11/rollout-*.jsonl
+
+# Context growth and actionable recommendations
+agent-cost analyze ~/.codex/sessions/2026/08/11/
+
+# Aggregate totals across sessions
+agent-cost stats ~/.codex/sessions/2026/08/
+
+# On a Claude Pro/Max subscription: report API-equivalent value, not spend
+agent-cost --subscription compare ~/.claude/projects/
+```
+
+### Real example (`agent-cost compare`)
+
+```text
+Agent Comparison Report
+══════════════════════════════════════════════════════════════════════════════
+AGENT          SESSIONS   TOTAL TOKENS  CACHED %   TOOLS   EST. USD  AVG $/SESS
+-------------------------------------------------------------------------------
+hermes                2      2,071,557     89.9%       0      0.82*        0.41
+claude-code           1         12,590     76.2%       1       0.02        0.02
+opencode              1          8,130     83.1%       2       0.00        0.00
+codex                 1            111      0.0%       1       0.00        0.00
+-------------------------------------------------------------------------------
+TOTAL                 5      2,092,388                        0.84*
+
+n/a / * = model has no rate card, excluded from dollar totals (1 of 5 sessions).
+
+Key Insights:
+  • Highest cache efficiency: hermes (89.9% hit rate).
+  • Most tool intensive: opencode (2 total tool calls).
+  • Prompt caching saved approx. $0.03 across analyzed sessions.
+  • 1 of 5 sessions have no rate card and are excluded from every dollar
+    figure above. Supply rates with --pricing to include them.
+```
+
+### Real example (`agent-cost analyze`)
+
+```text
+Analysis: 019feec8-4ee1-7560-9a9f-89952d1af2d3
+──────────────────────────────
+Context growth: 24,072 -> 70,609 tokens (x2.93)
+Largest context sources:
+  tool_output         83.6%
+  base_instructions    5.3%
+  assistant            4.5%
+  developer            3.3%
+Compactions: 1
+Prompt curve: 65K -> 66K -> 66K -> 70K -> 74K -> 80K
+
+Recommendations:
+  - Prompt size is growing steeply; start a fresh session instead of continuing.
+  - Session was already compacted 1x; further work belongs in a new session.
+  - Tool output dominates context; consider truncating or filtering large command output.
+```
+
+## Supported data sources
+
+- **Claude Code** (`~/.claude/projects/**/*.jsonl` or `.json`): real turn-by-turn
+  token usage with `input`, `output`, `cache_read_input_tokens`, and
+  `cache_creation_input_tokens` breakdown, plus tool calls.
+- **Hermes** (`sessions.json`): real `input/output/cache_read/cache_write`
+  totals plus estimated cost when the agent has finalized them.
+- **OpenCode** (`~/.local/share/opencode/opencode.db` SQLite database, or `.json` / `.jsonl` exports):
+  real turn-by-turn token usage, tool calls, and cache stats (`input`, `output`,
+  `cache.read`, `cache.write`).
+- **Codex rollouts** (`~/.codex/sessions/**/*.jsonl`): turns, tool calls,
+  compaction events, prompt-size curve and context-source attribution.
+  Rollouts usually have no token counters, so prompt sizes are estimated from
+  content length (approx. 4 chars/token) and reported as estimates.
+
+Parsing is intentionally read-only: files are only opened and counted, never
+executed or modified. Database connections use read-only SQLite URIs.
+
+## Pricing
+
+Costs are estimated from a built-in price table (see `pricing.py`) covering the
+Claude family (Fable 5, Opus 5/4.8/4.7/4.6/4.5/4.1, Sonnet 5/4.6/4.5, Haiku 4.5,
+plus the Claude 3.x generation), GPT-4o, GPT-5, o1, o3-mini, DeepSeek V3/R1,
+Qwen 2.5 Coder, and Gemini. Anthropic rates are from the
+[official pricing page](https://platform.claude.com/docs/en/about-claude/pricing)
+as of 2026-08-16.
+
+**A model that is not in the table is reported as `n/a`, never guessed.** It is
+excluded from every dollar total, and the report says how many sessions that
+covers. A wrong cost number is worse than no cost number, so there is no
+default rate card to fall back on.
+
+**Billing modes are priced per turn, not per session.** Fast mode and US-pinned
+inference cost more and can be toggled mid-session, so usage is split into
+`(speed, inference_geo)` buckets and each bucket is priced on its own card:
+
+| Mode | Effect | Source |
+|:---|:---|:---|
+| `speed: "fast"` | Opus 5 / Opus 4.8 billed at **$10 / $50** instead of $5 / $25. Other models fall back to standard rates, matching the API. | `usage.speed` |
+| `inference_geo: "us"` | **1.1x** on every token category. `global` / `not_available` are standard priced. | `usage.inference_geo` |
+
+The two stack. `agent-cost inspect` lists the modes when a session used more
+than one.
+
+**On a subscription, pass `--subscription`.** Claude Pro/Max sessions do not
+generate per-token charges, so the transcript's dollar value is what those
+tokens *would* have cost on metered API billing — useful for comparing agents
+and deciding when to restart a session, useless as a bill. The flag relabels
+every figure as API-equivalent value. It has to be explicit: the transcript
+carries no field distinguishing subscription from API usage.
+
+One remaining approximation: `cache_write` uses the 5-minute rate (1.25x input),
+because the usage payload does not record which cache TTL was used — sessions
+on the 1-hour cache (2x input) are undercounted.
+
+Supply your own rates to override any of this:
+
+```bash
+agent-cost --pricing "$(cat my-pricing.json)" compare ~/.claude/projects/
+export AGENT_COST_PRICING="$(cat my-pricing.json)"
+```
+
+Your entries are merged over the built-in table, so overriding one model leaves
+the rest intact. Copy [`pricing.example.json`](pricing.example.json) as a
+starting template. Note that `--pricing` is a global flag and must come *before*
+the subcommand.
+
+Model names resolve by exact match first, then by longest matching prefix, so a
+`claude-opus-4-5` entry also covers `claude-opus-4-5-20260101`, and `gpt-5-mini`
+is never priced as `gpt-5`.
+
+## Roadmap
+
+- [x] `agent-cost compare`: side-by-side agent comparison with `--by-agent` and `--json`
+- [x] Claude Code / Codex / Hermes session parsing
+- [x] OpenCode: SQLite database (`opencode.db`) and JSON export parsing
+- [ ] Support Cursor (`composer.json` / workspace state) log formats
+- [ ] Support Cline / Roo Code conversation history formats
+- [ ] `agent-cost watch`: budget thresholds with warnings before a session blows up
+- [ ] Tool-call-level cost attribution when providers expose per-request usage
+
+## Contributing
+
+Bug reports are especially welcome — particularly a session that parses
+incorrectly. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests, and how to
+add support for a new session format. Please never attach a raw session file to
+an issue; strip it first.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Session files are untrusted input; this tool
+never executes them, never renders them, and never sends data anywhere.

agent_cost_tracker-0.2.1/README.md

@@ -0,0 +1,205 @@
+# agent-cost
+
+[![CI](https://github.com/yingxiangge/agent-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/yingxiangge/agent-cost/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+**Token, cache and context observability for AI coding agents.**
+
+AI coding agents are expensive not because they have no cache — they usually
+have too much of it. `agent-cost` is a read-only CLI that shows you, per
+session or across multiple agents, how many tokens were really burned, where
+the context went, and which agent delivers the best prompt-caching efficiency.
+
+It was built from real-world usage across Codex, Hermes, and Claude Code. Across
+72 real Claude Code sessions (63.7M characters of transcript), the context
+attribution comes out as:
+
+```text
+tool_output   94.8%
+assistant      4.3%
+user           0.5%
+tool_calls     0.1%
+```
+
+Those same sessions total 9.1B billed prompt tokens at a 98.7% cache hit rate —
+a high hit rate does not protect you from unbounded context growth, it only
+changes the unit price.
+
+## Install
+
+```bash
+git clone https://github.com/yingxiangge/agent-cost.git
+cd agent-cost
+pip install -e .
+```
+
+Requires Python 3.10+.
+
+Not on PyPI yet. The distribution will be published as **`agent-cost-tracker`**
+— `agent-cost` is taken on PyPI — while the command it installs stays
+`agent-cost`:
+
+```bash
+pip install agent-cost-tracker
+pipx run --spec agent-cost-tracker agent-cost compare ~/.claude/projects/
+```
+
+## Usage
+
+```bash
+# Compare usage, cache efficiency, and cost across multiple agents or sessions
+agent-cost compare ~/.claude/projects/ ~/.codex/sessions/ ./hermes/
+
+# Output structured JSON for analysis pipelines
+agent-cost compare --json ~/.claude/projects/ ~/.codex/sessions/
+
+# Inspect one session (Claude Code, Hermes, OpenCode, Codex, or a folder)
+agent-cost inspect ~/.codex/sessions/2026/08/11/rollout-*.jsonl
+
+# Context growth and actionable recommendations
+agent-cost analyze ~/.codex/sessions/2026/08/11/
+
+# Aggregate totals across sessions
+agent-cost stats ~/.codex/sessions/2026/08/
+
+# On a Claude Pro/Max subscription: report API-equivalent value, not spend
+agent-cost --subscription compare ~/.claude/projects/
+```
+
+### Real example (`agent-cost compare`)
+
+```text
+Agent Comparison Report
+══════════════════════════════════════════════════════════════════════════════
+AGENT          SESSIONS   TOTAL TOKENS  CACHED %   TOOLS   EST. USD  AVG $/SESS
+-------------------------------------------------------------------------------
+hermes                2      2,071,557     89.9%       0      0.82*        0.41
+claude-code           1         12,590     76.2%       1       0.02        0.02
+opencode              1          8,130     83.1%       2       0.00        0.00
+codex                 1            111      0.0%       1       0.00        0.00
+-------------------------------------------------------------------------------
+TOTAL                 5      2,092,388                        0.84*
+
+n/a / * = model has no rate card, excluded from dollar totals (1 of 5 sessions).
+
+Key Insights:
+  • Highest cache efficiency: hermes (89.9% hit rate).
+  • Most tool intensive: opencode (2 total tool calls).
+  • Prompt caching saved approx. $0.03 across analyzed sessions.
+  • 1 of 5 sessions have no rate card and are excluded from every dollar
+    figure above. Supply rates with --pricing to include them.
+```
+
+### Real example (`agent-cost analyze`)
+
+```text
+Analysis: 019feec8-4ee1-7560-9a9f-89952d1af2d3
+──────────────────────────────
+Context growth: 24,072 -> 70,609 tokens (x2.93)
+Largest context sources:
+  tool_output         83.6%
+  base_instructions    5.3%
+  assistant            4.5%
+  developer            3.3%
+Compactions: 1
+Prompt curve: 65K -> 66K -> 66K -> 70K -> 74K -> 80K
+
+Recommendations:
+  - Prompt size is growing steeply; start a fresh session instead of continuing.
+  - Session was already compacted 1x; further work belongs in a new session.
+  - Tool output dominates context; consider truncating or filtering large command output.
+```
+
+## Supported data sources
+
+- **Claude Code** (`~/.claude/projects/**/*.jsonl` or `.json`): real turn-by-turn
+  token usage with `input`, `output`, `cache_read_input_tokens`, and
+  `cache_creation_input_tokens` breakdown, plus tool calls.
+- **Hermes** (`sessions.json`): real `input/output/cache_read/cache_write`
+  totals plus estimated cost when the agent has finalized them.
+- **OpenCode** (`~/.local/share/opencode/opencode.db` SQLite database, or `.json` / `.jsonl` exports):
+  real turn-by-turn token usage, tool calls, and cache stats (`input`, `output`,
+  `cache.read`, `cache.write`).
+- **Codex rollouts** (`~/.codex/sessions/**/*.jsonl`): turns, tool calls,
+  compaction events, prompt-size curve and context-source attribution.
+  Rollouts usually have no token counters, so prompt sizes are estimated from
+  content length (approx. 4 chars/token) and reported as estimates.
+
+Parsing is intentionally read-only: files are only opened and counted, never
+executed or modified. Database connections use read-only SQLite URIs.
+
+## Pricing
+
+Costs are estimated from a built-in price table (see `pricing.py`) covering the
+Claude family (Fable 5, Opus 5/4.8/4.7/4.6/4.5/4.1, Sonnet 5/4.6/4.5, Haiku 4.5,
+plus the Claude 3.x generation), GPT-4o, GPT-5, o1, o3-mini, DeepSeek V3/R1,
+Qwen 2.5 Coder, and Gemini. Anthropic rates are from the
+[official pricing page](https://platform.claude.com/docs/en/about-claude/pricing)
+as of 2026-08-16.
+
+**A model that is not in the table is reported as `n/a`, never guessed.** It is
+excluded from every dollar total, and the report says how many sessions that
+covers. A wrong cost number is worse than no cost number, so there is no
+default rate card to fall back on.
+
+**Billing modes are priced per turn, not per session.** Fast mode and US-pinned
+inference cost more and can be toggled mid-session, so usage is split into
+`(speed, inference_geo)` buckets and each bucket is priced on its own card:
+
+| Mode | Effect | Source |
+|:---|:---|:---|
+| `speed: "fast"` | Opus 5 / Opus 4.8 billed at **$10 / $50** instead of $5 / $25. Other models fall back to standard rates, matching the API. | `usage.speed` |
+| `inference_geo: "us"` | **1.1x** on every token category. `global` / `not_available` are standard priced. | `usage.inference_geo` |
+
+The two stack. `agent-cost inspect` lists the modes when a session used more
+than one.
+
+**On a subscription, pass `--subscription`.** Claude Pro/Max sessions do not
+generate per-token charges, so the transcript's dollar value is what those
+tokens *would* have cost on metered API billing — useful for comparing agents
+and deciding when to restart a session, useless as a bill. The flag relabels
+every figure as API-equivalent value. It has to be explicit: the transcript
+carries no field distinguishing subscription from API usage.
+
+One remaining approximation: `cache_write` uses the 5-minute rate (1.25x input),
+because the usage payload does not record which cache TTL was used — sessions
+on the 1-hour cache (2x input) are undercounted.
+
+Supply your own rates to override any of this:
+
+```bash
+agent-cost --pricing "$(cat my-pricing.json)" compare ~/.claude/projects/
+export AGENT_COST_PRICING="$(cat my-pricing.json)"
+```
+
+Your entries are merged over the built-in table, so overriding one model leaves
+the rest intact. Copy [`pricing.example.json`](pricing.example.json) as a
+starting template. Note that `--pricing` is a global flag and must come *before*
+the subcommand.
+
+Model names resolve by exact match first, then by longest matching prefix, so a
+`claude-opus-4-5` entry also covers `claude-opus-4-5-20260101`, and `gpt-5-mini`
+is never priced as `gpt-5`.
+
+## Roadmap
+
+- [x] `agent-cost compare`: side-by-side agent comparison with `--by-agent` and `--json`
+- [x] Claude Code / Codex / Hermes session parsing
+- [x] OpenCode: SQLite database (`opencode.db`) and JSON export parsing
+- [ ] Support Cursor (`composer.json` / workspace state) log formats
+- [ ] Support Cline / Roo Code conversation history formats
+- [ ] `agent-cost watch`: budget thresholds with warnings before a session blows up
+- [ ] Tool-call-level cost attribution when providers expose per-request usage
+
+## Contributing
+
+Bug reports are especially welcome — particularly a session that parses
+incorrectly. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests, and how to
+add support for a new session format. Please never attach a raw session file to
+an issue; strip it first.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Session files are untrusted input; this tool
+never executes them, never renders them, and never sends data anywhere.

agent_cost_tracker-0.2.1/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-cost-tracker"
+version = "0.2.1"
+description = "Token, cache and context observability for AI coding agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "yingxiangge" }]
+keywords = ["llm", "tokens", "cost", "observability", "codex", "hermes", "agent", "claude-code", "opencode"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: System :: Monitoring",
+]
+
+[project.urls]
+Homepage = "https://github.com/yingxiangge/agent-cost"
+Repository = "https://github.com/yingxiangge/agent-cost"
+Issues = "https://github.com/yingxiangge/agent-cost/issues"
+Changelog = "https://github.com/yingxiangge/agent-cost/blob/main/CHANGELOG.md"
+
+[project.scripts]
+agent-cost = "agent_cost.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

agent_cost_tracker-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_cost_tracker-0.2.1/src/agent_cost/__init__.py

@@ -0,0 +1,7 @@
+"""Token, cache and context observability for AI coding agents."""
+
+from .models import SessionStats
+from .pricing import estimate_cost
+
+__all__ = ["SessionStats", "estimate_cost"]
+__version__ = "0.1.0"

agent_cost_tracker-0.2.1/src/agent_cost/analyze.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from agent_cost.models import SessionStats
+
+
+def analyze(stats: SessionStats) -> dict:
+    """Derive actionable signals from session statistics."""
+    signals: dict = {"recommendations": [], "context_growth": None, "largest_sources": []}
+
+    samples = [s["estimated_prompt_tokens"] for s in stats.context_samples]
+    if len(samples) >= 4:
+        half = len(samples) // 2
+        first = sum(samples[:half]) / half
+        second = sum(samples[half:]) / (len(samples) - half)
+        ratio = second / first if first else 0.0
+        signals["context_growth"] = {
+            "first_half_avg": round(first),
+            "second_half_avg": round(second),
+            "growth_ratio": round(ratio, 2),
+        }
+        if ratio >= 2.5:
+            signals["recommendations"].append(
+                "Prompt size is growing steeply; start a fresh session instead of continuing."
+            )
+        elif ratio >= 1.6:
+            signals["recommendations"].append(
+                "Context is growing steadily; budget a /compact or a new session soon."
+            )
+
+    if stats.compaction_events:
+        signals["recommendations"].append(
+            f"Session was already compacted {stats.compaction_events}x; further work belongs in a new session."
+        )
+
+    if stats.turns >= 25 and not stats.context_samples:
+        signals["recommendations"].append("High turn count; review whether a new session would be cheaper.")
+
+    has_cache_data = bool(stats.cache_read_tokens or stats.cache_write_tokens)
+    if has_cache_data and stats.cache_hit_rate < 0.4 and stats.prompt_tokens:
+        signals["recommendations"].append(
+            "Low cache hit rate; same-prefix reuse is low, which usually inflates input cost."
+        )
+
+    total_chars = sum(stats.source_chars.values())
+    if total_chars:
+        ranked = sorted(stats.source_chars.items(), key=lambda kv: kv[1], reverse=True)[:4]
+        signals["largest_sources"] = [
+            {"source": k, "percent": round(v * 100 / total_chars, 1)} for k, v in ranked
+        ]
+        if any(k == "tool_output" for k, _ in ranked[:2]):
+            signals["recommendations"].append(
+                "Tool output dominates context; consider truncating or filtering large command output."
+            )
+
+    return signals