token-diet-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{token_diet_cli-0.1.0 → token_diet_cli-0.2.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 josephrotts
+Copyright (c) 2026 joseoper
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{token_diet_cli-0.1.0 → token_diet_cli-0.2.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: token-diet-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: Diagnostic tools and methodology to audit and optimize token footprint in AI coding workflows
-Author-email: josephrotts <387283+josephrotts@users.noreply.github.com>
+Author-email: joseoper <joseoper@users.noreply.github.com>
 License: MIT
 Keywords: tokens,llm,claude,gemini,codex,opencode,developer-tools
 Classifier: Development Status :: 4 - Beta
@@ -37,8 +37,10 @@ Worse, some local tools install hidden `pre-commit` hooks that send your entire
 
 `token-diet` scans your repository or workstation in milliseconds to:
 - **Audit prompt size:** Flags instruction files that exceed context budgets (`[OK]`, `[WARN]`, `[ALERT]`).
-- **Catch rogue git hooks:** Detects and disables silent LLM review hooks in `.git/hooks/pre-commit` (`--fix-hooks`).
-- **Guard CI pipelines:** Fails PR builds if prompt expansions exceed token thresholds (`--strict`, `--max-tokens`).
+- **Catch rogue git hooks:** Detects and disables silent LLM review hooks in the active hooks directory (`--fix-hooks`), including linked worktrees, submodules, and repositories using `core.hooksPath`.
+- **Locate the bloat:** Breaks a Markdown directive down per level-2 heading so you know which section to trim (`--sections`).
+- **Audit MCP overhead:** Reports the context cost of every declared MCP server in `opencode.json`, `.mcp.json`, and `mcp.json` (`--mcp`).
+- **Guard CI pipelines:** Fails PR builds if prompt expansions exceed token thresholds or regress past a saved baseline (`--strict`, `--max-tokens`, `--baseline`, `--max-delta`).
 - **Zero dependencies:** Pure Python standard library (Python >= 3.8). Runs in < 10ms.
 
 ---
@@ -47,9 +49,9 @@ Worse, some local tools install hidden `pre-commit` hooks that send your entire
 
 ### Via Homebrew (macOS & Linux)
 ```bash
-brew install josephrotts/tap/token-diet
+brew install joseoper/tap/token-diet
 # Or:
-brew tap josephrotts/tap
+brew tap joseoper/tap
 brew install token-diet
 ```
 
@@ -69,7 +71,7 @@ uv tool install token-diet-cli
 
 ### Running Directly from Source (No Installation Needed)
 ```bash
-git clone https://github.com/josephrotts/token-diet.git
+git clone https://github.com/joseoper/token-diet.git
 cd token-diet
 PYTHONPATH=src python3 -m token_diet
 ```
@@ -179,6 +181,60 @@ Emit structured JSON for automated pipelines, threshold assertions, or telemetry
 token-diet --json
 ```
 
+### 8. Locate Prompt Bloat per Heading (`--sections`)
+A monolithic directive rarely bloats evenly. This breakdown attributes bytes and estimated tokens to every level-2 (`##`) heading, so you know exactly which section to compress or move into an on-demand skill:
+
+```bash
+token-diet --sections AGENTS.md
+```
+
+```
+SECTION BREAKDOWN: MARKDOWN HEADING FOOTPRINT
+================================================================================
+AGENTS.md  (23,914 B / ~5,978 tokens)
+  Line | Heading                                  |     Bytes |    Tokens |   Status
+--------------------------------------------------------------------------------
+     1 | (preamble)                               |       412 |       103 |              [OK]
+    12 | Core Directives                          |    19,220 |     4,805 |           [ALERT]
+    98 | Additional Protocols                      |     4,282 |     1,070 |            [WARN]
+--------------------------------------------------------------------------------
+```
+
+Content before the first `##` heading is grouped as `(preamble)`, and deeper headings (`###`) stay attributed to their parent section. Combine with `--json` for machine-readable output.
+
+### 9. Audit MCP Server Overhead (`--mcp`)
+Every declared MCP server consumes context, and some configs inline large tool schemas. `token-diet` discovers local `opencode.json`, `.mcp.json`, `mcp.json`, `.cursor/mcp.json`, and `.vscode/mcp.json` files and reports the payload cost per server:
+
+```bash
+token-diet --mcp
+```
+
+```
+MCP SERVER PAYLOAD AUDIT
+================================================================================
+opencode.json  [opencode]  (2 server(s))
+Server                         | Transport | Tools |     Bytes |    Tokens |   Status
+--------------------------------------------------------------------------------
+engram                         | local     |    12 |    18,430 |     4,607 |           [ALERT]
+web-search                     | remote    |     0 |       142 |        35 |              [OK]
+--------------------------------------------------------------------------------
+```
+
+Config-declared `tools` blocks are counted and included in each server's payload. Schemas fetched by a server at runtime are not visible to a local audit; the reported figure is the local injection cost floor.
+
+### 10. Fail on Regression vs a Saved Baseline (`--baseline`, `--max-delta`)
+Record a baseline once, then gate every pull request against it. This catches slow, incremental growth that a fixed threshold never notices:
+
+```bash
+# Save the baseline on your default branch
+token-diet --json > token-baseline.json
+
+# Fail if the total grows more than 5% in a pull request
+token-diet --baseline token-baseline.json --max-delta 5
+```
+
+`--baseline` accepts any `--json` report (`{"summary": {"total_tokens": N}}`) or a minimal `{"total_tokens": N}` file. `--max-delta` exits with code `1` only when tokens **increase** beyond the given percentage; a decrease, an unchanged total, or growth exactly at the budget passes.
+
 ---
 
 ## Health Status Indicators
@@ -188,7 +244,7 @@ token-diet --json
 | 🟢 `[OK]` | `< 4 KB` | `< 1,000 tokens` | **Optimal Context:** Fits cleanly within prompt cache. Preserves fast, cheap inference. |
 | 🟡 `[WARN]` | `4 KB – 16 KB` | `1,000 – 4,000 tokens` | **Moderate Size:** Acceptable, but review for duplicate instructions or unneeded verbosity. |
 | 🔴 `[ALERT]` | `> 16 KB` | `> 4,000 tokens` | **Severe Prompt Bloat:** Monolithic rules degrade reasoning and waste context budget every turn. Decouple into On-Demand Skills. |
-| 🚨 `[HOOK ALERT]` | — | — | **Hidden Token Bleed:** Local `.git/hooks/pre-commit` sends code to cloud LLMs on every `git commit`. Replace with static linters. |
+| 🚨 `[HOOK ALERT]` | — | — | **Hidden Token Bleed:** The active `pre-commit` hook sends code to cloud LLMs on every `git commit`. Replace with static linters. |
 
 ---
 
@@ -256,9 +312,18 @@ token-diet/
 │   └── token_diet/            # Core Python package (Zero external dependencies)
 │       ├── __init__.py
 │       ├── __main__.py
-│       └── cli.py             # CLI implementation and footprint engine
+│       ├── baseline.py        # Baseline comparison & regression budget gate
+│       ├── cli.py             # CLI implementation and footprint engine
+│       ├── git_hooks.py       # Worktree, gitdir and core.hooksPath resolution
+│       ├── mcp_audit.py       # MCP config discovery & payload accounting
+│       ├── metrics.py         # Shared byte thresholds and token estimation
+│       └── sections.py        # Per-heading Markdown footprint breakdown
 ├── tests/
-│   └── test_token_audit.py    # Automated unit test suite (TDD)
+│   ├── test_baseline.py       # Baseline budget unit tests
+│   ├── test_git_hooks.py      # Hook resolution unit tests
+│   ├── test_mcp_audit.py      # MCP payload unit tests
+│   ├── test_sections.py       # Section breakdown unit tests
+│   └── test_token_audit.py    # Core engine and CLI integration tests
 ├── .gitignore
 ├── AGENTS.md                  # Agent-friendly repository directives
 ├── CONTRIBUTING.md            # Contribution guidelines & engineering principles
@@ -269,7 +334,7 @@ token-diet/
 
 ---
 
-## Core Methodology: The 5 Vectors of Token Leakage
+## Core Methodology: The 6 Vectors of Token Leakage
 
 Token Diet is built on empirical analysis of how developer environments silently deplete API quotas:
 
@@ -278,6 +343,7 @@ Token Diet is built on empirical analysis of how developer environments silently
 3. **Reasoning Effort Inflation:** Running frontier models at `high` reasoning effort for simple syntax or diagnostic queries generates thousands of hidden chain-of-thought tokens. *Solution: Default to `medium` or `low`.*
 4. **Static MCP Schemas:** Registering dozens of MCP tools serializes massive JSON parameter schemas into system prompts. *Solution: Prune unused tool servers and enforce lazy-loading.*
 5. **Prompt Cache Invalidation:** Injecting dynamic timestamps or changing session IDs at the start of instructions destroys provider prompt caching discounts (up to 90%). *Solution: Maintain immutable instruction prefixes.*
+6. **In-Session Runtime Inefficiencies:** Agents loading entire 1,500-line files to check one function, overwriting whole files instead of focused diffs, or running uncompacted 100k+ token threads. *Solution: Enforce active runtime hygiene (grep-first, line-range reads, targeted diffs, and context compaction thresholds; see [Remediation Playbook Phase 4](docs/remediation-playbook.md#phase-4-in-session-runtime-hygiene-active-execution-guards)).*
 
 ---
 

{token_diet_cli-0.1.0 → token_diet_cli-0.2.0}/README.md

@@ -14,8 +14,10 @@ Worse, some local tools install hidden `pre-commit` hooks that send your entire
 
 `token-diet` scans your repository or workstation in milliseconds to:
 - **Audit prompt size:** Flags instruction files that exceed context budgets (`[OK]`, `[WARN]`, `[ALERT]`).
-- **Catch rogue git hooks:** Detects and disables silent LLM review hooks in `.git/hooks/pre-commit` (`--fix-hooks`).
-- **Guard CI pipelines:** Fails PR builds if prompt expansions exceed token thresholds (`--strict`, `--max-tokens`).
+- **Catch rogue git hooks:** Detects and disables silent LLM review hooks in the active hooks directory (`--fix-hooks`), including linked worktrees, submodules, and repositories using `core.hooksPath`.
+- **Locate the bloat:** Breaks a Markdown directive down per level-2 heading so you know which section to trim (`--sections`).
+- **Audit MCP overhead:** Reports the context cost of every declared MCP server in `opencode.json`, `.mcp.json`, and `mcp.json` (`--mcp`).
+- **Guard CI pipelines:** Fails PR builds if prompt expansions exceed token thresholds or regress past a saved baseline (`--strict`, `--max-tokens`, `--baseline`, `--max-delta`).
 - **Zero dependencies:** Pure Python standard library (Python >= 3.8). Runs in < 10ms.
 
 ---
@@ -24,9 +26,9 @@ Worse, some local tools install hidden `pre-commit` hooks that send your entire
 
 ### Via Homebrew (macOS & Linux)
 ```bash
-brew install josephrotts/tap/token-diet
+brew install joseoper/tap/token-diet
 # Or:
-brew tap josephrotts/tap
+brew tap joseoper/tap
 brew install token-diet
 ```
 
@@ -46,7 +48,7 @@ uv tool install token-diet-cli
 
 ### Running Directly from Source (No Installation Needed)
 ```bash
-git clone https://github.com/josephrotts/token-diet.git
+git clone https://github.com/joseoper/token-diet.git
 cd token-diet
 PYTHONPATH=src python3 -m token_diet
 ```
@@ -156,6 +158,60 @@ Emit structured JSON for automated pipelines, threshold assertions, or telemetry
 token-diet --json
 ```
 
+### 8. Locate Prompt Bloat per Heading (`--sections`)
+A monolithic directive rarely bloats evenly. This breakdown attributes bytes and estimated tokens to every level-2 (`##`) heading, so you know exactly which section to compress or move into an on-demand skill:
+
+```bash
+token-diet --sections AGENTS.md
+```
+
+```
+SECTION BREAKDOWN: MARKDOWN HEADING FOOTPRINT
+================================================================================
+AGENTS.md  (23,914 B / ~5,978 tokens)
+  Line | Heading                                  |     Bytes |    Tokens |   Status
+--------------------------------------------------------------------------------
+     1 | (preamble)                               |       412 |       103 |              [OK]
+    12 | Core Directives                          |    19,220 |     4,805 |           [ALERT]
+    98 | Additional Protocols                      |     4,282 |     1,070 |            [WARN]
+--------------------------------------------------------------------------------
+```
+
+Content before the first `##` heading is grouped as `(preamble)`, and deeper headings (`###`) stay attributed to their parent section. Combine with `--json` for machine-readable output.
+
+### 9. Audit MCP Server Overhead (`--mcp`)
+Every declared MCP server consumes context, and some configs inline large tool schemas. `token-diet` discovers local `opencode.json`, `.mcp.json`, `mcp.json`, `.cursor/mcp.json`, and `.vscode/mcp.json` files and reports the payload cost per server:
+
+```bash
+token-diet --mcp
+```
+
+```
+MCP SERVER PAYLOAD AUDIT
+================================================================================
+opencode.json  [opencode]  (2 server(s))
+Server                         | Transport | Tools |     Bytes |    Tokens |   Status
+--------------------------------------------------------------------------------
+engram                         | local     |    12 |    18,430 |     4,607 |           [ALERT]
+web-search                     | remote    |     0 |       142 |        35 |              [OK]
+--------------------------------------------------------------------------------
+```
+
+Config-declared `tools` blocks are counted and included in each server's payload. Schemas fetched by a server at runtime are not visible to a local audit; the reported figure is the local injection cost floor.
+
+### 10. Fail on Regression vs a Saved Baseline (`--baseline`, `--max-delta`)
+Record a baseline once, then gate every pull request against it. This catches slow, incremental growth that a fixed threshold never notices:
+
+```bash
+# Save the baseline on your default branch
+token-diet --json > token-baseline.json
+
+# Fail if the total grows more than 5% in a pull request
+token-diet --baseline token-baseline.json --max-delta 5
+```
+
+`--baseline` accepts any `--json` report (`{"summary": {"total_tokens": N}}`) or a minimal `{"total_tokens": N}` file. `--max-delta` exits with code `1` only when tokens **increase** beyond the given percentage; a decrease, an unchanged total, or growth exactly at the budget passes.
+
 ---
 
 ## Health Status Indicators
@@ -165,7 +221,7 @@ token-diet --json
 | 🟢 `[OK]` | `< 4 KB` | `< 1,000 tokens` | **Optimal Context:** Fits cleanly within prompt cache. Preserves fast, cheap inference. |
 | 🟡 `[WARN]` | `4 KB – 16 KB` | `1,000 – 4,000 tokens` | **Moderate Size:** Acceptable, but review for duplicate instructions or unneeded verbosity. |
 | 🔴 `[ALERT]` | `> 16 KB` | `> 4,000 tokens` | **Severe Prompt Bloat:** Monolithic rules degrade reasoning and waste context budget every turn. Decouple into On-Demand Skills. |
-| 🚨 `[HOOK ALERT]` | — | — | **Hidden Token Bleed:** Local `.git/hooks/pre-commit` sends code to cloud LLMs on every `git commit`. Replace with static linters. |
+| 🚨 `[HOOK ALERT]` | — | — | **Hidden Token Bleed:** The active `pre-commit` hook sends code to cloud LLMs on every `git commit`. Replace with static linters. |
 
 ---
 
@@ -233,9 +289,18 @@ token-diet/
 │   └── token_diet/            # Core Python package (Zero external dependencies)
 │       ├── __init__.py
 │       ├── __main__.py
-│       └── cli.py             # CLI implementation and footprint engine
+│       ├── baseline.py        # Baseline comparison & regression budget gate
+│       ├── cli.py             # CLI implementation and footprint engine
+│       ├── git_hooks.py       # Worktree, gitdir and core.hooksPath resolution
+│       ├── mcp_audit.py       # MCP config discovery & payload accounting
+│       ├── metrics.py         # Shared byte thresholds and token estimation
+│       └── sections.py        # Per-heading Markdown footprint breakdown
 ├── tests/
-│   └── test_token_audit.py    # Automated unit test suite (TDD)
+│   ├── test_baseline.py       # Baseline budget unit tests
+│   ├── test_git_hooks.py      # Hook resolution unit tests
+│   ├── test_mcp_audit.py      # MCP payload unit tests
+│   ├── test_sections.py       # Section breakdown unit tests
+│   └── test_token_audit.py    # Core engine and CLI integration tests
 ├── .gitignore
 ├── AGENTS.md                  # Agent-friendly repository directives
 ├── CONTRIBUTING.md            # Contribution guidelines & engineering principles
@@ -246,7 +311,7 @@ token-diet/
 
 ---
 
-## Core Methodology: The 5 Vectors of Token Leakage
+## Core Methodology: The 6 Vectors of Token Leakage
 
 Token Diet is built on empirical analysis of how developer environments silently deplete API quotas:
 
@@ -255,6 +320,7 @@ Token Diet is built on empirical analysis of how developer environments silently
 3. **Reasoning Effort Inflation:** Running frontier models at `high` reasoning effort for simple syntax or diagnostic queries generates thousands of hidden chain-of-thought tokens. *Solution: Default to `medium` or `low`.*
 4. **Static MCP Schemas:** Registering dozens of MCP tools serializes massive JSON parameter schemas into system prompts. *Solution: Prune unused tool servers and enforce lazy-loading.*
 5. **Prompt Cache Invalidation:** Injecting dynamic timestamps or changing session IDs at the start of instructions destroys provider prompt caching discounts (up to 90%). *Solution: Maintain immutable instruction prefixes.*
+6. **In-Session Runtime Inefficiencies:** Agents loading entire 1,500-line files to check one function, overwriting whole files instead of focused diffs, or running uncompacted 100k+ token threads. *Solution: Enforce active runtime hygiene (grep-first, line-range reads, targeted diffs, and context compaction thresholds; see [Remediation Playbook Phase 4](docs/remediation-playbook.md#phase-4-in-session-runtime-hygiene-active-execution-guards)).*
 
 ---
 

{token_diet_cli-0.1.0 → token_diet_cli-0.2.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "token-diet-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "Diagnostic tools and methodology to audit and optimize token footprint in AI coding workflows"
 readme = "README.md"
 requires-python = ">=3.8"
 license = { text = "MIT" }
 authors = [
-    { name = "josephrotts", email = "387283+josephrotts@users.noreply.github.com" }
+    { name = "joseoper", email = "joseoper@users.noreply.github.com" }
 ]
 keywords = ["tokens", "llm", "claude", "gemini", "codex", "opencode", "developer-tools"]
 classifiers = [

token_diet_cli-0.2.0/src/token_diet/__init__.py

@@ -0,0 +1,80 @@
+"""
+token-diet: Diagnostic tools and methodology to audit and optimize token footprint in AI coding workflows.
+"""
+
+from token_diet.cli import (
+    estimate_tokens,
+    audit_file,
+    detect_local_prompts,
+    audit_git_hooks,
+    fix_git_hooks,
+    classify_size,
+    resolve_target_paths,
+    audit_known_prompts,
+    summarize_footprint,
+    main,
+    DEFAULT_PROMPT_PATHS,
+    LOCAL_PROMPT_CANDIDATES,
+    THRESHOLD_WARN_BYTES,
+    THRESHOLD_ALERT_BYTES,
+)
+from token_diet.baseline import (
+    check_budget,
+    compare_tokens,
+    extract_total_tokens,
+    load_baseline,
+)
+from token_diet.git_hooks import (
+    AI_HOOK_KEYWORDS,
+    has_ai_invocation,
+    read_core_hooks_path,
+    resolve_common_dir,
+    resolve_git_dir,
+    resolve_hooks_dir,
+)
+from token_diet.mcp_audit import (
+    MCP_CONFIG_CANDIDATES,
+    audit_mcp_config,
+    audit_mcp_overhead,
+    discover_mcp_configs,
+)
+from token_diet.sections import (
+    audit_sections,
+    audit_sections_for_paths,
+    split_sections,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "estimate_tokens",
+    "audit_file",
+    "detect_local_prompts",
+    "audit_git_hooks",
+    "fix_git_hooks",
+    "classify_size",
+    "resolve_target_paths",
+    "audit_known_prompts",
+    "summarize_footprint",
+    "main",
+    "DEFAULT_PROMPT_PATHS",
+    "LOCAL_PROMPT_CANDIDATES",
+    "THRESHOLD_WARN_BYTES",
+    "THRESHOLD_ALERT_BYTES",
+    "AI_HOOK_KEYWORDS",
+    "has_ai_invocation",
+    "read_core_hooks_path",
+    "resolve_common_dir",
+    "resolve_git_dir",
+    "resolve_hooks_dir",
+    "check_budget",
+    "compare_tokens",
+    "extract_total_tokens",
+    "load_baseline",
+    "MCP_CONFIG_CANDIDATES",
+    "audit_mcp_config",
+    "audit_mcp_overhead",
+    "discover_mcp_configs",
+    "audit_sections",
+    "audit_sections_for_paths",
+    "split_sections",
+]

token_diet_cli-0.2.0/src/token_diet/baseline.py

@@ -0,0 +1,120 @@
+"""
+baseline.py
+
+Baseline comparison and regression budget gatekeeper logic for token-diet.
+"""
+
+import json
+import math
+import os
+from typing import Any, Dict, Optional
+
+
+def extract_total_tokens(payload: Any) -> Optional[int]:
+    """
+    Extract total estimated tokens from a numeric value or report dictionary.
+
+    Returns an integer token count if valid and non-negative, else None.
+    Rejects booleans, negative numbers, and non-numeric values.
+    """
+    if isinstance(payload, bool):
+        return None
+    if isinstance(payload, (int, float)):
+        if math.isnan(payload) or math.isinf(payload):
+            return None
+        if payload < 0:
+            return None
+        return int(payload)
+    if isinstance(payload, dict):
+        token_val = payload.get("total_tokens")
+        if token_val is None and isinstance(payload.get("summary"), dict):
+            token_val = payload["summary"].get("total_tokens")
+        return extract_total_tokens(token_val)
+    return None
+
+
+def load_baseline(filepath: str) -> Dict[str, Any]:
+    """
+    Load baseline token count from a JSON report file.
+
+    Returns a dict with 'ok', 'tokens', 'path', and 'error'.
+    Never raises an exception.
+    """
+    if not os.path.exists(filepath):
+        return {
+            "ok": False,
+            "tokens": None,
+            "path": filepath,
+            "error": f"Baseline file not found: {filepath}",
+        }
+
+    try:
+        with open(filepath, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception as e:
+        return {
+            "ok": False,
+            "tokens": None,
+            "path": filepath,
+            "error": f"Failed to parse baseline JSON: {e}",
+        }
+
+    tokens = extract_total_tokens(data)
+    if tokens is None:
+        return {
+            "ok": False,
+            "tokens": None,
+            "path": filepath,
+            "error": "No valid token count found in baseline file",
+        }
+
+    return {
+        "ok": True,
+        "tokens": tokens,
+        "path": filepath,
+        "error": None,
+    }
+
+
+def compare_tokens(current_tokens: int, baseline_tokens: int) -> Dict[str, Any]:
+    """
+    Compare current tokens against baseline tokens and compute delta metrics.
+
+    Returns a dict with baseline_tokens, current_tokens, delta_tokens,
+    delta_percent (rounded to 2 decimal places), and direction.
+    """
+    delta_tokens = current_tokens - baseline_tokens
+    if baseline_tokens > 0:
+        delta_percent = round(delta_tokens / baseline_tokens * 100.0, 2)
+    else:
+        delta_percent = 0.0
+
+    if delta_tokens > 0:
+        direction = "increase"
+    elif delta_tokens < 0:
+        direction = "decrease"
+    else:
+        direction = "unchanged"
+
+    return {
+        "baseline_tokens": baseline_tokens,
+        "current_tokens": current_tokens,
+        "delta_tokens": delta_tokens,
+        "delta_percent": delta_percent,
+        "direction": direction,
+    }
+
+
+def check_budget(current_tokens: int, baseline_tokens: int, max_delta_percent: float) -> Dict[str, Any]:
+    """
+    Check if token growth exceeds the maximum allowed delta percentage budget.
+
+    Budget is exceeded only when direction is 'increase' and delta_percent
+    is strictly greater than max_delta_percent.
+    """
+    comparison = compare_tokens(current_tokens, baseline_tokens)
+    max_delta = float(max_delta_percent)
+    exceeded = comparison["direction"] == "increase" and comparison["delta_percent"] > max_delta
+    comparison["max_delta_percent"] = max_delta
+    comparison["exceeded"] = exceeded
+    return comparison