code-context-control 2.110.0__tar.gz → 2.111.0__tar.gz

{code_context_control-2.110.0 → code_context_control-2.111.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.110.0
+Version: 2.111.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.110.0 → code_context_control-2.111.0}/cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.110.0"
+__version__ = "2.111.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -1536,6 +1536,40 @@ def cmd_search_eval(args):
         sys.exit(1)
 
 
+def cmd_shell_eval(args):
+    """Run the c3_shell output-shaping suite and compare it to its baseline.
+
+    Exit status 1 when the baseline is violated (a must_pass case failed, an
+    aggregate fell under its floor or rose over its ceiling). See
+    docs/shell-eval.md.
+    """
+    from services.bench import shell_eval as she
+
+    try:
+        report = she.run_suite(args.suite, baseline=args.baseline)
+    except FileNotFoundError as e:
+        raise RuntimeError(str(e))
+
+    if args.update_baseline:
+        path = args.baseline or she.BUNDLED_BASELINES.get(report.suite)
+        if not path:
+            raise RuntimeError(
+                f"suite {report.suite!r} has no bundled baseline; pass --baseline PATH")
+        floors = json.loads(args.floors) if args.floors else None
+        ceilings = json.loads(args.ceilings) if args.ceilings else None
+        she.write_baseline(report, path, floors=floors, ceilings=ceilings)
+        report.baseline_violations, report.baseline_warnings = she.compare_to_baseline(
+            report, she.load_baseline(path))
+        print(f"baseline written: {path}")
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(report.render())
+    if report.baseline_violations:
+        sys.exit(1)
+
+
 def _benchmark_extract_preview(full_path: Path, compressor: CodeCompressor, pattern: str = "", max_lines: int = 50) -> str:
     """Approximate c3_filter behavior for local benchmarking without MCP startup."""
     import re as _re
@@ -9200,6 +9234,7 @@ def main():
         "map": cmd_map,
         "stats": cmd_stats,
         "search-eval": cmd_search_eval,
+        "shell-eval": cmd_shell_eval,
         "benchmark": cmd_benchmark,
         "session-benchmark": cmd_session_benchmark,
         "benchmark-e2e": cmd_benchmark_e2e,

{code_context_control-2.110.0 → code_context_control-2.111.0}/cli/commands/parser.py

@@ -59,6 +59,19 @@ def build_parser(version: str, parse_cli_ide_arg):
                                help='With --update-baseline: JSON object of metric floors, e.g. \'{"mrr": 0.85}\'')
     p_search_eval.add_argument("--json", action="store_true", help="Emit the full report as JSON")
 
+    p_shell_eval = subparsers.add_parser(
+        "shell-eval", help="Run the c3_shell output-shaping suite (docs/shell-eval.md)")
+    p_shell_eval.add_argument("--suite", default="fixture",
+                              help="'fixture' (synthetic outputs, CI gate) or a .jsonl path")
+    p_shell_eval.add_argument("--baseline", default=None, help="Baseline JSON to compare against / write")
+    p_shell_eval.add_argument("--update-baseline", action="store_true",
+                              help="Write aggregates + per-case status to the baseline (floors/ceilings are kept)")
+    p_shell_eval.add_argument("--floors", default=None,
+                              help='With --update-baseline: JSON object of metric floors, e.g. \'{"must_keep_retention": 0.9}\'')
+    p_shell_eval.add_argument("--ceilings", default=None,
+                              help='With --update-baseline: JSON object of metric ceilings, e.g. \'{"bytes_p95": 18432}\'')
+    p_shell_eval.add_argument("--json", action="store_true", help="Emit the full report as JSON")
+
     p_compress = subparsers.add_parser("compress", help="Compress a file")
     p_compress.add_argument("file", help="File to compress")
     p_compress.add_argument("--mode", choices=["map", "dense_map", "smart", "diff"], default="smart")

{code_context_control-2.110.0 → code_context_control-2.111.0}/cli/tools/_helpers.py

@@ -81,7 +81,7 @@ def show_token_ratios(svc) -> bool:
 def finalize_with_tokens(finalize, svc, tool_name: str, args: dict,
                          response: str, summary: str = "", *,
                          raw_tokens=None, optimized_tokens=None,
-                         duration_ms=None, **finalize_kwargs) -> str:
+                         duration_ms=None, detail=None, **finalize_kwargs) -> str:
     """Finalize a tool response with STRUCTURED token accounting.
 
     This is the primary accounting path: tools pass explicitly measured
@@ -100,6 +100,10 @@ def finalize_with_tokens(finalize, svc, tool_name: str, args: dict,
     ``estimated_saved_vs_full_read`` in session token_usage and in the
     per-tool telemetry JSONL (.c3/tool_telemetry.jsonl).
 
+    ``detail`` is an optional flat dict of tool-specific facts about this
+    call; it lands under the telemetry record's ``detail`` key (see
+    SessionManager.record_tool_tokens).
+
     Failure-safe: accounting errors never break the tool response. Any extra
     keyword args (e.g. response_tokens) are forwarded to ``finalize``.
     """
@@ -107,10 +111,11 @@ def finalize_with_tokens(finalize, svc, tool_name: str, args: dict,
         session_mgr = getattr(svc, "session_mgr", None)
         if session_mgr is not None and (
                 raw_tokens is not None or optimized_tokens is not None
-                or duration_ms is not None):
+                or duration_ms is not None or detail):
             session_mgr.record_tool_tokens(
                 tool_name, raw_tokens=raw_tokens,
-                optimized_tokens=optimized_tokens, duration_ms=duration_ms)
+                optimized_tokens=optimized_tokens, duration_ms=duration_ms,
+                detail=detail)
     except Exception:
         pass
     return finalize(tool_name, args, response, summary, **finalize_kwargs)

{code_context_control-2.110.0 → code_context_control-2.111.0}/cli/tools/shell.py

@@ -27,6 +27,7 @@ from pathlib import Path
 
 from cli._shell_writes import shell_write_targets
 from cli.tools import _grants
+from cli.tools._helpers import finalize_with_tokens
 from cli.tools.filter import handle_filter
 from core import count_tokens
 from services import access_guard
@@ -366,6 +367,149 @@ def _dependency_hint(cmd: str, result: dict) -> str:
     )
 
 
+# ── Command classification (telemetry only) ─────────────────────────────────
+#
+# A coarse label per call so .c3/tool_telemetry.jsonl can say which KIND of
+# command carries the tokens and the wall time. Measured 2026-09-04 over 7,278
+# shell_exec events: file-read/search 48%, python 10%, git 10%, tests 5%,
+# ops/device 4%, build/lint 4%. Best-effort: the first word after any leading
+# `cd … &&` / `VAR=… ;` prefix, plus a few substring tells. Never used to
+# change behaviour.
+
+_CLASS_PREFIX = re.compile(
+    r"""^(?:\s*(?:cd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*|\w+=(?:"[^"]*"|'[^']*'|\S*)\s*;?\s*))*""")
+_CLASS_TESTS = re.compile(
+    r"\b(?:pytest|python\s+-m\s+(?:pytest|unittest)|npm\s+test|vitest|jest|cargo\s+test|go\s+test)\b")
+_CLASS_TABLE = {
+    "file-read": {"cat", "head", "tail", "sed", "grep", "rg", "find", "ls", "wc",
+                  "awk", "tree", "type", "less", "more", "stat", "file", "du"},
+    "git": {"git"},
+    "python": {"python", "python3", "py", "pythonw", "pip", "uv"},
+    "build": {"npm", "npx", "node", "pnpm", "yarn", "tsc", "eslint", "vite",
+              "gradlew", "cargo", "go", "make", "ruff", "mypy", "pyright",
+              "dotnet", "mvn", "gradle"},
+    "ops": {"curl", "wget", "adb", "powershell", "pwsh", "schtasks", "tasklist",
+            "taskkill", "netstat", "ps", "kill", "sleep", "timeout", "ssh",
+            "scp", "docker", "systemctl", "sc"},
+    "echo": {"echo", "printf", "test", "[", "true", "false"},
+    "gh": {"gh"},
+    "c3": {"c3", "c3-mcp"},
+}
+
+
+def _cmd_class(cmd: str) -> str:
+    """Coarse command class for telemetry (see table above)."""
+    try:
+        if _CLASS_TESTS.search(cmd):
+            return "tests"
+        rest = _CLASS_PREFIX.sub("", cmd.strip())
+        head = rest.split(None, 1)[0] if rest.split() else ""
+        head = head.rsplit("/", 1)[-1].rsplit("\\", 1)[-1].lower()
+        if head.endswith(".exe"):
+            head = head[:-4]
+        if head.startswith("python"):
+            head = "python"
+        for label, names in _CLASS_TABLE.items():
+            if head in names:
+                return label
+        return "other"
+    except Exception:
+        return "other"
+
+
+def _longest_line(*texts: str) -> int:
+    longest = 0
+    for text in texts:
+        if not text:
+            continue
+        for line in text.split("\n"):
+            if len(line) > longest:
+                longest = len(line)
+    return longest
+
+
+def render_shell_response(cmd: str, result: dict, svc, *,
+                          filter_output: bool = True, warn: str = "",
+                          capped_note: str = "", touched_files=(),
+                          cred_names=(), swept_ghosts=()) -> tuple[str, dict]:
+    """Turn a finished command into the body the agent reads, plus its stats.
+
+    Pure with respect to the subprocess: ``result`` is the dict _run_sync
+    returns (exit_code, stdout, stderr, duration_ms, timed_out, shell), so
+    the shell-eval harness (services/bench/shell_eval.py) can feed captured
+    or synthetic streams through exactly the code path a live call uses.
+    Runs the same auto-filter handle_shell always ran — only stdout, only when
+    it has more than _FILTER_THRESHOLD_LINES newlines, never for a git
+    diagnostic — and assembles the same sections in the same order.
+
+    ``stats`` is what telemetry records about the call (see
+    SessionManager.record_tool_tokens ``detail``): stdout_bytes and
+    stderr_bytes are measured BEFORE filtering so a later budget phase can
+    size the band it changes; longest_line is the tell for the single-line
+    monsters (minified bundles, JSONL) that a newline-count trigger never
+    sees; filtered/spilled/output_id describe what this renderer did.
+    """
+    raw_stdout = result.get("stdout") or ""
+    raw_stderr = result.get("stderr") or ""
+    stats: dict = {
+        "exit_code": result.get("exit_code"),
+        "timed_out": bool(result.get("timed_out")),
+        "stdout_bytes": len(raw_stdout.encode("utf-8", errors="replace")),
+        "stderr_bytes": len(raw_stderr.encode("utf-8", errors="replace")),
+        "longest_line": _longest_line(raw_stdout, raw_stderr),
+        "filtered": False,
+        "spilled": False,
+        "output_id": None,
+        "cmd_class": _cmd_class(cmd),
+    }
+
+    stdout = raw_stdout
+    filtered_note = ""
+    if (filter_output and raw_stdout.count("\n") > _FILTER_THRESHOLD_LINES
+            and not _GIT_DIAGNOSTIC.search(cmd)):
+        try:
+            stdout = handle_filter(
+                "", raw_stdout, "", 50, "smart", True,
+                svc, lambda *a, **kw: a[2],
+            )
+            filtered_note = " [stdout filtered]"
+            stats["filtered"] = True
+        except Exception:
+            stdout = raw_stdout
+
+    if result.get("timed_out"):
+        status = "TIMEOUT"
+    elif result.get("exit_code") == 0:
+        status = "OK"
+    else:
+        status = f"FAIL({result.get('exit_code')})"
+
+    body = (
+        f"{warn}{capped_note}"
+        f"[c3_shell:{status}] {result.get('duration_ms', 0)}ms{filtered_note}\n"
+        f"$ {cmd}\n"
+        f"--- stdout ---\n{stdout.rstrip()}\n"
+    )
+    if raw_stderr.strip():
+        body += f"--- stderr ---\n{raw_stderr.rstrip()}\n"
+    dependency_hint = _dependency_hint(cmd, result)
+    if dependency_hint:
+        body += f"--- hint ---\n{dependency_hint}\n"
+    if touched_files:
+        body += f"--- ledger ---\nlogged {len(touched_files)} file(s)\n"
+    if cred_names:
+        body += f"--- creds ---\ninjected: {', '.join(cred_names)}\n"
+    if swept_ghosts:
+        body += (
+            f"--- ghost-sweep ---\nremoved {len(swept_ghosts)} stray 0-byte "
+            f"file(s): {', '.join(swept_ghosts)}\n"
+        )
+
+    stats["response_bytes"] = len(body.encode("utf-8", errors="replace"))
+    stats["response_tokens"] = count_tokens(body) if body else 0
+    return body, stats
+
+
 # ── Access Guard advisory scanner (T2c) ────────────────────────────────────
 # ADVISORY ONLY — this is best-effort, NEVER enforcement. A shell command can
 # reach paths through subshells, variables, globs, quoting, and indirection
@@ -753,22 +897,6 @@ async def handle_shell(cmd: str, cwd: str, timeout: int, filter_output: bool,
                 except Exception:
                     pass
 
-    raw_stdout = result["stdout"]
-    filtered_note = ""
-    if (filter_output and raw_stdout.count("\n") > _FILTER_THRESHOLD_LINES
-            and not _GIT_DIAGNOSTIC.search(cmd)):
-        try:
-            filtered = await asyncio.to_thread(
-                handle_filter,
-                "", raw_stdout, "", 50, "smart", True,
-                svc, lambda *a, **kw: a[2],
-            )
-            result["stdout_raw_bytes"] = len(raw_stdout)
-            result["stdout"] = filtered
-            filtered_note = " [stdout filtered]"
-        except Exception:
-            pass
-
     touched_files: list[str] = []
     if log:
         touched_files = _maybe_refresh_ledger(
@@ -796,51 +924,41 @@ async def handle_shell(cmd: str, cwd: str, timeout: int, filter_output: bool,
             warn = granted + "\n"
         else:
             warn = "[c3_shell:warn] destructive pattern detected — verify before re-running\n"
+    capped_note = ""
     if capped_from:
         # Named at the moment of the mistake, not in documentation nobody
         # reads at the moment they need it. The alternative IS the escape
         # hatch, so the line says which one.
-        warn += (
+        capped_note = (
             f"[c3_shell:capped] timeout={capped_from}s was requested but this "
             f"MCP client kills a tool call at {_ceiling}s; ran with {timeout}s. "
             f"For longer work use the native Bash tool with "
             f"run_in_background, which is not bound by this limit.\n"
         )
 
+    body, stats = await asyncio.to_thread(
+        render_shell_response, cmd, result, svc,
+        filter_output=filter_output, warn=warn, capped_note=capped_note,
+        touched_files=touched_files, cred_names=cred_names,
+        swept_ghosts=swept_ghosts,
+    )
+
     if result["timed_out"]:
         status = "TIMEOUT"
     elif result["exit_code"] == 0:
         status = "OK"
     else:
         status = f"FAIL({result['exit_code']})"
-
-    body = (
-        f"{warn}"
-        f"[c3_shell:{status}] {result['duration_ms']}ms{filtered_note}\n"
-        f"$ {cmd}\n"
-        f"--- stdout ---\n{result['stdout'].rstrip()}\n"
-    )
-    if result["stderr"].strip():
-        body += f"--- stderr ---\n{result['stderr'].rstrip()}\n"
-    dependency_hint = _dependency_hint(cmd, result)
-    if dependency_hint:
-        body += f"--- hint ---\n{dependency_hint}\n"
-    if touched_files:
-        body += f"--- ledger ---\nlogged {len(touched_files)} file(s)\n"
-    if cred_names:
-        body += f"--- creds ---\ninjected: {', '.join(cred_names)}\n"
-    if swept_ghosts:
-        body += (
-            f"--- ghost-sweep ---\nremoved {len(swept_ghosts)} stray 0-byte "
-            f"file(s): {', '.join(swept_ghosts)}\n"
-        )
-
     summary = f"shell {status} in {result['duration_ms']}ms"
-    resp_tokens = count_tokens(body) if body else 0
-    return finalize(
-        "c3_shell",
+    # Telemetry: duration was always measured and never recorded (null on
+    # 100% of records before 2.111.0); the stats dict is the per-call detail
+    # a later budget phase is sized against.
+    return finalize_with_tokens(
+        finalize, svc, "c3_shell",
         {"cmd": cmd[:120], "cwd": work_cwd},
         body,
         summary,
-        response_tokens=resp_tokens,
+        duration_ms=result.get("duration_ms"),
+        detail=stats,
+        response_tokens=stats.get("response_tokens", 0),
     )

{code_context_control-2.110.0 → code_context_control-2.111.0}/code_context_control.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.110.0
+Version: 2.111.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0

{code_context_control-2.110.0 → code_context_control-2.111.0}/code_context_control.egg-info/SOURCES.txt

@@ -277,6 +277,7 @@ services/watcher.py
 services/win_subprocess.py
 services/bench/__init__.py
 services/bench/search_eval.py
+services/bench/shell_eval.py
 services/bench/external/__init__.py
 services/bench/external/aider_polyglot.py
 services/bench/external/swe_bench.py
@@ -311,6 +312,7 @@ tests/test_ci_runner.py
 tests/test_ci_workflow.py
 tests/test_circuit_breaker.py
 tests/test_claude_md_merge.py
+tests/test_claude_md_updater.py
 tests/test_cli_smoke.py
 tests/test_compressor_large_file.py
 tests/test_confirm_guard.py
@@ -436,7 +438,9 @@ tests/test_service_durability.py
 tests/test_session_benchmark.py
 tests/test_session_budget.py
 tests/test_shell_creds.py
+tests/test_shell_eval.py
 tests/test_shell_robustness.py
+tests/test_shell_telemetry_s0.py
 tests/test_shell_write_ledger.py
 tests/test_shell_writes.py
 tests/test_subproject_clear_scope.py

{code_context_control-2.110.0 → code_context_control-2.111.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.110.0"
+version = "2.111.0"
 description = "Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub."
 readme = "README.md"
 requires-python = ">=3.10"

{code_context_control-2.110.0 → code_context_control-2.111.0}/services/agents.py

@@ -650,11 +650,12 @@ class ClaudeMdUpdaterAgent(BackgroundAgent):
 
         for action_type, data in actions:
             if action_type == "staleness":
-                # Regenerate the auto-generated sections
+                # Regenerate the auto-generated sections — inside the managed
+                # block, so user content around it survives.
                 try:
                     result = self.claude_md.generate(include_sessions=True)
                     if result.get("content") and self.auto_apply:
-                        self._write_claude_md(result["content"])
+                        self._write_managed_body(result["content"])
                         applied.append("Regenerated CLAUDE.md (stale)")
                     elif result.get("content"):
                         applied.append(f"CLAUDE.md is stale ({len(data.get('issues', []))} issues) — regeneration available")
@@ -810,16 +811,59 @@ class ClaudeMdUpdaterAgent(BackgroundAgent):
             self._write_claude_md("\n".join(lines))
         return additions
 
-    def _write_claude_md(self, content: str):
-        """Write content to the instructions file and update hash."""
+    def _md_path(self):
+        return self.claude_md.project_path / self.claude_md.instructions_file
+
+    def _write_managed_body(self, body: str) -> bool:
+        """Write regenerated C3 content INTO the managed block.
+
+        ``generate()`` returns the block body, not a whole file. Writing it
+        raw (2.110.0 and earlier) dropped the ``C3:BEGIN``/``C3:END`` markers
+        and everything the user kept outside them; the next ``c3 install-mcp``
+        then re-wrapped the template as a legacy doc, so a committed
+        CLAUDE.md went dirty on every session start. The merge in
+        ``write_c3_instruction_doc`` is the same one the installer uses.
+        """
+        from services.claude_md import write_c3_instruction_doc
+
         try:
-            md_path = self.claude_md.project_path / self.claude_md.instructions_file
+            final = write_c3_instruction_doc(self._md_path(), body,
+                                             project_path=self.claude_md.project_path,
+                                             source="claude_md_updater")
+            self._last_content_hash = hashlib.md5(final.encode()).hexdigest()
+            self._last_update_time = time.time()
+            return True
+        except Exception:
+            return False
+
+    def _write_claude_md(self, content: str) -> bool:
+        """Write a WHOLE instructions file (compaction, promotions) and update hash.
+
+        Refuses when the file on disk carries the managed-block markers and
+        ``content`` does not: that is a block body, and writing it here would
+        strip the markers — route it through ``_write_managed_body``.
+        """
+        from services.claude_md import C3_BLOCK_BEGIN
+
+        try:
+            md_path = self._md_path()
             md_path.parent.mkdir(parents=True, exist_ok=True)
+            if md_path.exists() and C3_BLOCK_BEGIN not in content:
+                existing = md_path.read_text(encoding="utf-8", errors="replace")
+                if C3_BLOCK_BEGIN in existing:
+                    return False
             md_path.write_text(content, encoding="utf-8")
             self._last_content_hash = hashlib.md5(content.encode()).hexdigest()
             self._last_update_time = time.time()
+        except Exception:
+            return False
+        try:
+            from services.artifact_defs import note_pending_write
+            note_pending_write(self.claude_md.project_path, self.claude_md.instructions_file,
+                               "claude_md_updater")
         except Exception:
             pass
+        return True
 
     def get_status(self) -> dict:
         """Extended status including updater-specific metrics."""