cctx-cli 1.7.0__tar.gz → 1.8.0__tar.gz

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 <!-- version list -->
 
+## v1.8.0 (2026-06-11)
+
+### Bug Fixes
+
+- Add _FANOUT_WASTE_DIFF template so MANAGED_HEADINGS stays in sync
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Ruff lint — move imports to top, break long lines in test file
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+### Features
+
+- Add FindingKind.FANOUT_WASTE + KIND_LABEL + MANAGED_HEADINGS
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Fan-out waste classifier (M16 #89) ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Fan_out classifier — Signal A (overlap) + Signal B (retry)
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+- Wire fan_out classifier into diagnostician, add _patch_fanout_costs
+  ([#110](https://github.com/jacquardlabs/cctx/pull/110),
+  [`0123588`](https://github.com/jacquardlabs/cctx/commit/01235884bde2158307441c71f38d4cf96a2d8481))
+
+
 ## v1.7.0 (2026-06-11)
 
 ### Bug Fixes

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cctx-cli
-Version: 1.7.0
+Version: 1.8.0
 Summary: Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md
 Author: Jacquard Labs
 License-Expression: MIT

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/cctx/__init__.py

@@ -1,3 +1,3 @@
 """cctx: profile, debug, and optimize Claude Code and Agent SDK sessions."""
 
-__version__ = "1.7.0"
+__version__ = "1.8.0"

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/cctx/diagnostician/__init__.py

@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING
 from cctx.diagnostician import inflection
 from cctx.diagnostician.patterns import (
     dead_end,
+    fan_out,
     retry_loop,
     scope_creep,
     stale_context,
@@ -41,6 +42,45 @@ def _patch_costs(findings: list[Finding], model: str | None) -> list[Finding]:
     return result
 
 
+def _patch_fanout_costs(
+    findings: list[Finding],
+    subagent_costs: list[SubagentAttribution],
+) -> list[Finding]:
+    """Fill cost_usd on FANOUT_WASTE findings from subagent attribution data.
+
+    For overlap findings: picks the cheaper of the two subagents as waste.
+    For retry findings: attributes the full cost of the failed subagent.
+    Populates evidence['subagent_session_ids'] so run()'s dedup pass works.
+    """
+    cost_map = {a.session_id: a.total_cost_usd for a in subagent_costs}
+    result: list[Finding] = []
+    for f in findings:
+        if f.kind is FindingKind.FANOUT_WASTE:
+            signal = f.evidence.get("signal")
+            if signal == "overlap":
+                pair = [sid for sid in f.evidence.get("overlap_pair", []) if sid is not None]
+                if pair:
+                    cheaper_cost, cheaper_sid = min(
+                        (cost_map.get(sid, 0.0), sid) for sid in pair
+                    )
+                    f = dataclasses.replace(
+                        f,
+                        cost_usd=round(cheaper_cost, 4),
+                        evidence={**f.evidence, "subagent_session_ids": [cheaper_sid]},
+                    )
+            elif signal == "retry":
+                failed_sid = f.evidence.get("failed_session_id")
+                if failed_sid is not None:
+                    cost = cost_map.get(failed_sid, 0.0)
+                    f = dataclasses.replace(
+                        f,
+                        cost_usd=round(cost, 4),
+                        evidence={**f.evidence, "subagent_session_ids": [failed_sid]},
+                    )
+        result.append(f)
+    return result
+
+
 def _compute_own_cost(trace: SessionTrace, model: str | None) -> float:
     """Parent-turns-only cost — does not recurse into subagents.
 
@@ -111,17 +151,32 @@ def run(trace: SessionTrace) -> Diagnosis:
         *stale_context.classify(trace),
         *tool_thrash.classify(trace),
         *dead_end.classify(trace),
+        *fan_out.classify(trace),
     ]
     findings.sort(key=lambda f: f.first_turn)
 
     inflection_turn = inflection.detect(findings)
     findings = _patch_costs(findings, trace.primary_model)
 
+    # Fan-out cost patching requires attributions first.
+    subagent_costs = _collect_attributions(trace)
+    findings = _patch_fanout_costs(findings, subagent_costs)
+
     total_cost = round(_compute_inclusive_cost(trace), 4)
-    waste_cost = sum(f.cost_usd for f in findings if f.cost_usd is not None)
-    waste_cost = min(waste_cost, total_cost)
 
-    subagent_costs = _collect_attributions(trace)
+    # Deduplicate fan-out waste: a subagent flagged by both overlap AND retry
+    # must not be double-counted. Collect unique wasted session IDs, sum once.
+    cost_map = {a.session_id: a.total_cost_usd for a in subagent_costs}
+    wasted_sids: set[str] = set()
+    for f in findings:
+        if f.kind is FindingKind.FANOUT_WASTE:
+            wasted_sids.update(f.evidence.get("subagent_session_ids", []))
+    fanout_waste = sum(cost_map.get(sid, 0.0) for sid in wasted_sids)
+    other_waste = sum(
+        f.cost_usd for f in findings
+        if f.cost_usd is not None and f.kind is not FindingKind.FANOUT_WASTE
+    )
+    waste_cost = min(other_waste + fanout_waste, total_cost)
 
     return Diagnosis(
         session_id=trace.session_id,

cctx_cli-1.8.0/cctx/diagnostician/patterns/fan_out.py

@@ -0,0 +1,175 @@
+"""Fan-out waste classifier.
+
+classify(trace) -> list[Finding]
+
+Signal A — OVERLAP: Two Agent calls with Jaccard >= 0.65 on word 3-grams,
+    both prompts >= 50 words.
+Signal B — RETRY: Agent ToolResult is_error=True followed by the next Agent
+    call with Jaccard >= 0.50 on word 3-grams, both prompts >= 30 words.
+
+Signal C (unused-result) is deferred — the 6-gram approach fires false
+positives on paraphrased references and is not ship-ready.
+
+cost_usd is set to None here; _patch_fanout_costs() in diagnostician/__init__.py
+fills it in from SubagentAttribution data after run() collects attributions.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cctx.models import Confidence, Finding, FindingKind, Severity
+
+if TYPE_CHECKING:
+    from cctx.models import SessionTrace, ToolUse
+
+# ---------------------------------------------------------------------------
+# Thresholds — documented here, not tuned at runtime
+# ---------------------------------------------------------------------------
+
+OVERLAP_JACCARD: float = 0.65   # minimum Jaccard on word 3-grams for overlap
+OVERLAP_MIN_WORDS: int = 50     # both prompts must be this long
+
+RETRY_JACCARD: float = 0.50     # minimum Jaccard for failed-retry detection
+RETRY_MIN_WORDS: int = 30       # both prompts must be this long
+
+
+# ---------------------------------------------------------------------------
+# N-gram helpers
+# ---------------------------------------------------------------------------
+
+def _word_ngrams(text: str, n: int) -> set[tuple[str, ...]]:
+    words = text.lower().split()
+    if len(words) < n:
+        return set()
+    return {tuple(words[i : i + n]) for i in range(len(words) - n + 1)}
+
+
+def _jaccard(a: set, b: set) -> float:
+    if not a or not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def _get_prompt(tu: ToolUse) -> str:
+    return tu.tool_input.get("prompt") or tu.tool_input.get("description") or ""
+
+
+# ---------------------------------------------------------------------------
+# Signal A — Overlapping subagent prompts
+# ---------------------------------------------------------------------------
+
+def _signal_overlap(agent_calls: list[tuple[int, ToolUse]]) -> list[Finding]:
+    findings: list[Finding] = []
+    for i in range(len(agent_calls)):
+        turn_i, tu_i = agent_calls[i]
+        p_i = _get_prompt(tu_i)
+        words_i = p_i.split()
+        if len(words_i) < OVERLAP_MIN_WORDS:
+            continue
+        ng_i = _word_ngrams(p_i, 3)
+        for j in range(i + 1, len(agent_calls)):
+            turn_j, tu_j = agent_calls[j]
+            p_j = _get_prompt(tu_j)
+            words_j = p_j.split()
+            if len(words_j) < OVERLAP_MIN_WORDS:
+                continue
+            ng_j = _word_ngrams(p_j, 3)
+            score = _jaccard(ng_i, ng_j)
+            if score < OVERLAP_JACCARD:
+                continue
+            findings.append(Finding(
+                kind=FindingKind.FANOUT_WASTE,
+                severity=Severity.MEDIUM,
+                confidence=Confidence.MEDIUM,
+                first_turn=min(turn_i, turn_j),
+                last_turn=max(turn_i, turn_j),
+                evidence={
+                    "signal": "overlap",
+                    "overlap_pair": [tu_i.subagent_session_id, tu_j.subagent_session_id],
+                    "jaccard": round(score, 3),
+                    "prompt_a": p_i[:80],
+                    "prompt_b": p_j[:80],
+                    "subagent_session_ids": [],  # filled by _patch_fanout_costs
+                },
+                cost_usd=None,
+                summary=f"Overlapping subagent prompts (Jaccard {score:.2f})",
+            ))
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Signal B — Failed subagent re-spawned with similar prompt
+# ---------------------------------------------------------------------------
+
+def _signal_retry(
+    agent_calls: list[tuple[int, ToolUse]],
+    result_map: dict[str, tuple[bool, str]],  # tool_use_id -> (is_error, content)
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for k, (turn_k, tu_k) in enumerate(agent_calls):
+        is_error, _content = result_map.get(tu_k.tool_use_id, (False, ""))
+        if not is_error:
+            continue
+        # Only check the immediate next Agent call (by list order = turn order)
+        if k + 1 >= len(agent_calls):
+            continue
+        turn_next, tu_next = agent_calls[k + 1]
+        p_failed = _get_prompt(tu_k)
+        p_retry = _get_prompt(tu_next)
+        if len(p_failed.split()) < RETRY_MIN_WORDS or len(p_retry.split()) < RETRY_MIN_WORDS:
+            continue
+        score = _jaccard(_word_ngrams(p_failed, 3), _word_ngrams(p_retry, 3))
+        if score < RETRY_JACCARD:
+            continue
+        findings.append(Finding(
+            kind=FindingKind.FANOUT_WASTE,
+            severity=Severity.HIGH,
+            confidence=Confidence.HIGH,
+            first_turn=turn_k,
+            last_turn=turn_next,
+            evidence={
+                "signal": "retry",
+                "failed_session_id": tu_k.subagent_session_id,
+                "jaccard": round(score, 3),
+                "failed_prompt": p_failed[:80],
+                "retry_prompt": p_retry[:80],
+                "subagent_session_ids": [],  # filled by _patch_fanout_costs
+            },
+            cost_usd=None,
+            summary=f"Failed subagent re-spawned with similar prompt (Jaccard {score:.2f})",
+        ))
+    return findings
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def _classify_impl(trace: SessionTrace) -> list[Finding]:
+    # Collect Agent ToolUse in turn order
+    agent_calls: list[tuple[int, ToolUse]] = []
+    result_map: dict[str, tuple[bool, str]] = {}
+
+    for turn in trace.turns:
+        for tu in turn.tool_uses:
+            if tu.tool_name == "Agent":
+                agent_calls.append((turn.turn_number, tu))
+        for tr in turn.tool_results:
+            if tr.tool_name == "Agent":
+                result_map[tr.tool_use_id] = (tr.is_error, tr.content)
+
+    if len(agent_calls) < 2:
+        return []
+
+    findings: list[Finding] = [
+        *_signal_overlap(agent_calls),
+        *_signal_retry(agent_calls, result_map),
+    ]
+    return findings
+
+
+def classify(trace: SessionTrace) -> list[Finding]:
+    try:
+        return _classify_impl(trace)
+    except Exception:
+        return []

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/cctx/models.py

@@ -172,6 +172,7 @@ class FindingKind(str, Enum):
     STALE_CONTEXT = "stale_context"
     TOOL_THRASH   = "tool_thrash"
     DEAD_END      = "dead_end"
+    FANOUT_WASTE  = "fanout_waste"
     PROJECT_PATTERN = "project_pattern"
 
 
@@ -181,6 +182,7 @@ KIND_LABEL: dict[FindingKind, str] = {
     FindingKind.STALE_CONTEXT: "STALE CONTEXT",
     FindingKind.TOOL_THRASH:   "TOOL THRASH",
     FindingKind.DEAD_END:      "DEAD END",
+    FindingKind.FANOUT_WASTE:  "FANOUT WASTE",
     FindingKind.PROJECT_PATTERN: "PROJECT PATTERN",
 }
 
@@ -194,6 +196,7 @@ MANAGED_HEADINGS: dict[FindingKind, str] = {
     FindingKind.STALE_CONTEXT: "## Context hygiene",
     FindingKind.TOOL_THRASH:   "## Tool-call discipline",
     FindingKind.DEAD_END:      "## Exploration discipline",
+    FindingKind.FANOUT_WASTE:  "## Fan-out discipline",
 }
 
 # Project-specific patterns use a heading that embeds tool+key, so the managed

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/cctx/recommender/claude_md.py

@@ -57,6 +57,15 @@ _DEAD_END_DIFF = """\
 +approaches already ruled out, and pick a meaningfully different one. Sunk effort on a
 +failing approach is not a reason to continue it."""
 
+_FANOUT_WASTE_DIFF = """\
++## Fan-out discipline
++
++Before spawning multiple subagents in parallel, state what each one will return
++and verify the tasks don't overlap. After each subagent completes, confirm its
++result is actually consumed by the parent before spawning retries. Retry only
++after changing something meaningful about the task — identical re-spawns waste
++the full subagent cost with no new information."""
+
 _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     # kind → (description, diff_body, target_file)
     FindingKind.RETRY_LOOP:    ("Add retry discipline rule", _RETRY_LOOP_DIFF, "CLAUDE.md"),
@@ -64,6 +73,7 @@ _TEMPLATES: dict[FindingKind, tuple[str, str, str]] = {
     FindingKind.STALE_CONTEXT: ("Add context hygiene rule", _STALE_CONTEXT_DIFF, "CLAUDE.md"),
     FindingKind.TOOL_THRASH:   ("Add tool-call discipline rule", _TOOL_THRASH_DIFF, "CLAUDE.md"),
     FindingKind.DEAD_END:      ("Add exploration discipline rule", _DEAD_END_DIFF, "CLAUDE.md"),
+    FindingKind.FANOUT_WASTE:  ("Add fan-out discipline rule", _FANOUT_WASTE_DIFF, "CLAUDE.md"),
 }
 
 

{cctx_cli-1.7.0 → cctx_cli-1.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctx-cli"
-version = "1.7.0"
+version = "1.8.0"
 description = "Diagnose Claude Code sessions — find what went wrong, what it cost, and what to add to CLAUDE.md"
 readme = "README.md"
 requires-python = ">=3.10"