code-context-control 2.101.0__tar.gz → 2.109.0__tar.gz

{code_context_control-2.101.0/code_context_control.egg-info → code_context_control-2.109.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.101.0
+Version: 2.109.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
@@ -47,6 +47,8 @@ Provides-Extra: vector
 Requires-Dist: scikit-learn>=1.3.0; extra == "vector"
 Requires-Dist: numpy>=1.24.0; extra == "vector"
 Requires-Dist: chromadb>=0.4.24; extra == "vector"
+Provides-Extra: rerank
+Requires-Dist: flashrank>=0.2.10; extra == "rerank"
 Provides-Extra: tui
 Requires-Dist: textual>=0.50.0; extra == "tui"
 Provides-Extra: telemetry

{code_context_control-2.101.0 → code_context_control-2.109.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.101.0"
+__version__ = "2.109.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -591,21 +591,21 @@ def _check_c3_health(project_path: str) -> dict:
         issues.append(f"missing directories: {', '.join(missing_dirs)}")
         info["missing_dirs"] = missing_dirs
 
-    # Index presence and basic stats
-    index_file = c3_dir / "index" / "index.json"
-    if not index_file.exists():
-        issues.append("code index not built")
-        info["index_files"] = 0
-        info["index_chunks"] = 0
-    else:
-        try:
-            data = json.loads(index_file.read_text(encoding="utf-8"))
-            info["index_files"] = len(data.get("documents", {}))
-            info["index_chunks"] = len(data.get("chunks", {}))
-        except Exception:
-            issues.append("code index corrupt")
-            info["index_files"] = 0
-            info["index_chunks"] = 0
+    # Index presence and basic stats (services/index_store; index.json is
+    # the pre-2.107.0 layout and counts as "present, needs a rebuild").
+    try:
+        from services.index_store import IndexStore
+        store = IndexStore(c3_dir / "index")
+        n_docs, n_chunks = store.counts()
+    except Exception:
+        store, n_docs, n_chunks = None, 0, 0
+    info["index_files"] = n_docs
+    info["index_chunks"] = n_chunks
+    if n_docs == 0:
+        if (c3_dir / "index" / "index.json").exists():
+            issues.append("code index in the pre-2.107.0 layout; run `c3 index` to migrate")
+        else:
+            issues.append("code index not built")
 
     # Stale file changes (tracked by the watcher inside CodeIndex)
     # The watcher writes pending changes to .c3/index/changes.json
@@ -1500,6 +1500,42 @@ def cmd_stats(args):
     return common_cmd_stats(args, _command_deps())
 
 
+def cmd_search_eval(args):
+    """Run the c3_search relevance suite and compare it to its baseline.
+
+    Exit status 1 when the baseline is violated (a must_pass case failed, a
+    canary leaked, or an aggregate fell under its floor), so the command can
+    stand in a pre-push gate. See docs/search-eval.md.
+    """
+    from services.bench import search_eval as se
+
+    try:
+        report = se.run_suite(args.suite, repo=args.repo, rebuild=args.rebuild,
+                              semantic=args.semantic, baseline=args.baseline,
+                              rerank=getattr(args, "rerank", "off"))
+    except FileNotFoundError as e:
+        raise RuntimeError(str(e))
+
+    if args.update_baseline:
+        path = args.baseline or se.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
+        se.write_baseline(report, path, floors=floors)
+        # Re-compare so the printed verdict reflects the file just written.
+        report.baseline_violations, report.baseline_warnings = se.compare_to_baseline(
+            report, se.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
@@ -4212,6 +4248,7 @@ def cmd_pipe(args):
 
 
 from services.claude_md import C3_COMPACT_WORKFLOW as _SHARED_C3_COMPACT_WORKFLOW
+from services.claude_md import VSCODE_INSTRUCTIONS_FILE
 from services.claude_md import VSCODE_SESSION_INIT as _VSCODE_SESSION_INIT
 from services.claude_md import adapt_workflow_for_ide as _adapt_workflow_for_ide
 
@@ -4433,14 +4470,27 @@ def _toml_section_bool_value(toml_path: Path, section: str, key: str) -> bool |
     return None
 
 
-def _ensure_instruction_workflow(instructions_path: Path, template: str, required_markers: list[str]) -> str:
-    """Ensure an instructions file has required C3 workflow markers.
+def _ensure_instruction_workflow(instructions_path: Path, template: str,
+                                 required_markers: list[str],
+                                 project_path: str = "") -> str:
+    """Ensure an instructions file carries the CURRENT C3 workflow.
 
     Returns one of: "written", "updated", "kept".
+
+    Marker PRESENCE used to mean "up to date", which is why this function
+    could report `kept` on a doc generated four releases ago: the markers are
+    stable words like "SEARCH FIRST" and "c3_edit", so they survive every
+    template change. A doc carrying the managed sentinels is now refreshed
+    through ``merge_c3_block`` — the same non-destructive regeneration
+    CLAUDE.md and AGENTS.md get — and `kept` means the block already matches
+    byte for byte (v2.102.0). A marker-less legacy doc keeps the old
+    prepend-and-preserve path, which ``write_c3_instruction_doc`` handles.
     """
+    from services.claude_md import C3_BLOCK_BEGIN, merge_c3_block, wrap_c3_block, write_c3_instruction_doc
+
     if not instructions_path.exists():
-        instructions_path.parent.mkdir(parents=True, exist_ok=True)
-        instructions_path.write_text(template, encoding="utf-8")
+        write_c3_instruction_doc(instructions_path, template,
+                                 project_path=project_path or None)
         return "written"
 
     try:
@@ -4448,6 +4498,14 @@ def _ensure_instruction_workflow(instructions_path: Path, template: str, require
     except Exception:
         existing = ""
 
+    # Managed doc → regenerate the block in place, preserving user content.
+    if C3_BLOCK_BEGIN in existing:
+        if merge_c3_block(existing, wrap_c3_block(template)) == existing:
+            return "kept"
+        write_c3_instruction_doc(instructions_path, template,
+                                 project_path=project_path or None)
+        return "updated"
+
     if all(marker in existing for marker in required_markers):
         return "kept"
 
@@ -4460,7 +4518,8 @@ def _ensure_instruction_workflow(instructions_path: Path, template: str, require
     return "updated"
 
 
-def _ensure_codex_agents_workflow(agents_md_path: Path) -> str:
+def _ensure_codex_agents_workflow(agents_md_path: Path,
+                                  project_path: str = "") -> str:
     """Ensure AGENTS.md contains the mandatory C3 workflow for Codex sessions."""
     required_markers = [
         "C3 Tools",
@@ -4474,10 +4533,12 @@ def _ensure_codex_agents_workflow(agents_md_path: Path) -> str:
         "c3_memory",
         "c3_filter",
     ]
-    return _ensure_instruction_workflow(agents_md_path, _AGENTS_MD_CONTENT, required_markers)
+    return _ensure_instruction_workflow(agents_md_path, _AGENTS_MD_CONTENT,
+                                        required_markers, project_path)
 
 
-def _ensure_vscode_instructions_workflow(instructions_path: Path) -> str:
+def _ensure_vscode_instructions_workflow(instructions_path: Path,
+                                         project_path: str = "") -> str:
     """Ensure VS Code Copilot instructions include the latest C3 workflow markers."""
     required_markers = [
         "C3 Tools",
@@ -4491,7 +4552,9 @@ def _ensure_vscode_instructions_workflow(instructions_path: Path) -> str:
         "c3_memory",
         "c3_filter",
     ]
-    return _ensure_instruction_workflow(instructions_path, _COPILOT_INSTRUCTIONS_CONTENT, required_markers)
+    return _ensure_instruction_workflow(instructions_path,
+                                        _COPILOT_INSTRUCTIONS_CONTENT,
+                                        required_markers, project_path)
 
 
 def _safe_read_json(path: Path, label: str = "") -> dict:
@@ -4957,6 +5020,7 @@ back to native tools as the task progresses.
 - **Bitbucket** (v2.30.0+, when `c3 bitbucket login` has run): `c3_bitbucket(action='list_prs|get_pr|merge_pr|...')` — self-hosted Bitbucket Data Center / Server. Token in OS keyring; mutating actions auto-log to the edit ledger.
 - **Cross-project** (v2.31.0+): `c3_project(action='list|scan|search|read|edit|...', project='<name|path>')` — discover and operate on OTHER c3-installed projects. Reads run freely; writes (edit/shell/memory) need `allow_write=true`.
 - **Masked paths** (v2.63.0+): content prefixed `[c3-mask:transformed]` is a policy-transformed VIEW, not the file. Values may be synthetic, rows withheld, bodies stripped — don't copy literals out of it or infer completeness from it. Masked paths are read-only and refuse shell/git/validate/impact/filter/delegate (`[c3-mask:unsupported]`). That's policy, not a transient error — report the block instead of routing around it.
+- **Confirm holds** (v2.97.0+): `[c3-access:confirm]` is a PAUSE, not a block — a human must approve this exact write. Since v2.100.0 the agent-config files (`.mcp.json`, instruction docs, `.claude` hook/skill/agent/command bodies) hold by default in EVERY C3 project, reads stay open. Read the S8 tail: it names the filed request (`c3_override(action='wait', request_id='...', timeout_s=180)`, then retry the same call once if approved), or names a surface that files one, or gives a reason to obey. Never retry before a decision and never route around a hold via the shell.
 
 ## Self-Check
 If you haven't called a c3_* tool in several turns during active development, re-engage
@@ -5034,10 +5098,20 @@ def _instruction_documents_for_project() -> list[tuple[str, str]]:
 
     Used by uninstall/cleanup paths, so it must keep listing legacy docs
     (GEMINI.md — profile removed in v2.52; empty template, never generated).
+
+    ``.github/copilot-instructions.md`` was absent from this list until
+    v2.102.0, and that absence was the whole bug: the managed-block sync
+    that regenerates CLAUDE.md and AGENTS.md on every install-mcp never
+    touched it, while ``_ensure_vscode_instructions_workflow`` reported
+    `kept` on marker presence alone. In a vscode-primary project the third
+    git-tracked instruction doc silently drifted a release behind on every
+    template change — v2.100.0's agent-config confirm tier reached the
+    Claude Code and Codex docs and never reached Copilot's.
     """
     return [
         ("CLAUDE.md", _CLAUDE_MD_CONTENT),
         ("AGENTS.md", _AGENTS_MD_CONTENT),
+        (VSCODE_INSTRUCTIONS_FILE, _COPILOT_INSTRUCTIONS_CONTENT),
         ("GEMINI.md", ""),
     ]
 
@@ -5692,7 +5766,8 @@ def cmd_install_mcp(args):
     if profile.name == "vscode":
         # 1. Ensure copilot-instructions.md has the latest C3 workflow markers
         instructions_path = target / ".github" / "copilot-instructions.md"
-        vs_state = _ensure_vscode_instructions_workflow(instructions_path)
+        vs_state = _ensure_vscode_instructions_workflow(instructions_path,
+                                                        str(target))
         if vs_state == "written":
             print(f"Wrote {instructions_path}")
         elif vs_state == "updated":
@@ -5731,7 +5806,8 @@ def cmd_install_mcp(args):
     # ── Codex AGENTS.md enforcement file ──────────────────────
     if profile.name == "codex":
         agents_md_path = target / "AGENTS.md"
-        agents_state = _ensure_codex_agents_workflow(agents_md_path)
+        agents_state = _ensure_codex_agents_workflow(agents_md_path,
+                                                     str(target))
         if agents_state == "written":
             print(f"Wrote {agents_md_path}")
         elif agents_state == "updated":
@@ -9123,6 +9199,7 @@ def main():
         "claudemd": cmd_claudemd,
         "map": cmd_map,
         "stats": cmd_stats,
+        "search-eval": cmd_search_eval,
         "benchmark": cmd_benchmark,
         "session-benchmark": cmd_session_benchmark,
         "benchmark-e2e": cmd_benchmark_e2e,

{code_context_control-2.101.0 → code_context_control-2.109.0}/cli/commands/common.py

@@ -26,25 +26,48 @@ class CommandDeps:
 
 
 def cmd_index(args, deps: CommandDeps):
-    """Rebuild the code index."""
+    """Rebuild the code index.
+
+    ``--max-files`` defaults to None so an unset flag falls through to
+    ``CodeIndex.build_index``, which reads ``index_max_files`` from
+    ``.c3/config.json`` (2000 by default). Passing a hard-coded number here
+    would shadow that config for every caller who did not type the flag.
+
+    A truncated index is reported, never silent: the caller who sees only
+    "Files Indexed: 500" has no way to know 1400 files were skipped, and a
+    partial index answers searches with confident absences.
+    """
     config = deps.load_config()
     project_path = config.get("project_path", ".")
 
     deps.print_header("Rebuilding Code Index")
     indexer = deps.CodeIndex(project_path)
-    result = indexer.build_index(max_files=args.max_files or 500)
+    result = indexer.build_index(max_files=args.max_files)
+
+    capped = result.get("files_capped", 0) or 0
+    candidates = result["files_indexed"] + capped
 
     if deps.HAS_RICH:
         table = deps.Table(title="Index Results")
         table.add_column("Metric", style="cyan")
         table.add_column("Value", style="green")
-        table.add_row("Files Indexed", str(result["files_indexed"]))
+        files_cell = str(result["files_indexed"])
+        if capped:
+            files_cell = f"{result['files_indexed']} of {candidates}"
+        table.add_row("Files Indexed", files_cell)
         table.add_row("Chunks Created", str(result["chunks_created"]))
         table.add_row("Unique Symbols", str(result["unique_symbols"]))
+        if capped:
+            table.add_row("Files Skipped (cap)", str(capped))
         deps.console.print(table)
     else:
         print(f"  Files: {result['files_indexed']}, Chunks: {result['chunks_created']}, Symbols: {result['unique_symbols']}")
 
+    if capped:
+        print(f"  [!] Indexed {result['files_indexed']} of {candidates} candidate files "
+              f"(cap: index_max_files={result.get('max_files')}). {capped} skipped.")
+        print("      Raise index_max_files in .c3/config.json for full coverage.")
+
 
 def cmd_compress(args, deps: CommandDeps):
     """Compress a file and show results."""

{code_context_control-2.101.0 → code_context_control-2.109.0}/cli/commands/parser.py

@@ -34,7 +34,30 @@ def build_parser(version: str, parse_cli_ide_arg):
                            help="Only report whether a newer version exists; don't install")
 
     p_index = subparsers.add_parser("index", help="Rebuild code index")
-    p_index.add_argument("--max-files", type=int, default=500)
+    p_index.add_argument("--max-files", type=int, default=None,
+                         help="Cap files indexed this run. Unset reads "
+                              "index_max_files from .c3/config.json (2000).")
+
+    p_search_eval = subparsers.add_parser(
+        "search-eval", help="Run the c3_search relevance suite (docs/search-eval.md)")
+    p_search_eval.add_argument("--suite", default="fixture",
+                               help="'fixture' (synthetic repo, CI gate), 'golden' (this repo), or a .jsonl path")
+    p_search_eval.add_argument("--repo", default=None,
+                               help="Project to evaluate; overrides the suite header (real repos only)")
+    p_search_eval.add_argument("--semantic", choices=["off", "auto", "on"], default="auto",
+                               help="off: skip semantic cases; auto: run when embeddings are ready; "
+                                    "on: build embeddings first (needs Ollama)")
+    p_search_eval.add_argument("--rerank", choices=["off", "on"], default="off",
+                               help="on: attach the FlashRank reranker (needs the `rerank` extra) to measure it "
+                                    "against the same suite; off: the project's own config decides")
+    p_search_eval.add_argument("--rebuild", action="store_true",
+                               help="Rebuild the code index before running (real repos; fixtures always rebuild)")
+    p_search_eval.add_argument("--baseline", default=None, help="Baseline JSON to compare against / write")
+    p_search_eval.add_argument("--update-baseline", action="store_true",
+                               help="Write aggregates + per-query status to the baseline (floors are kept)")
+    p_search_eval.add_argument("--floors", default=None,
+                               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_compress = subparsers.add_parser("compress", help="Compress a file")
     p_compress.add_argument("file", help="File to compress")

{code_context_control-2.101.0 → code_context_control-2.109.0}/cli/hook_access_guard.py

@@ -6,9 +6,11 @@ dispatcher's deny-beats-allow merge makes a deny here final. hook_dispatch
 treats this module as _FAIL_CLOSED: if it fails to import or raises, write-
 class native tools are denied instead of sailing through.
 
-Bash coverage is a best-effort, existence-gated token scan — advisory by
-design (docs/access-guard.md §3/§6); it catches an agent naming a denied
-path, not an adversary hiding one.
+Bash coverage is a best-effort token scan — advisory by design
+(docs/access-guard.md §3/§6); it catches an agent naming a denied path, not
+an adversary hiding one. Two passes: every path-shaped token as a READ
+(existence-gated), then the command's WRITE targets as writes (v2.102.0), so
+a redirect into a confirm-held or read-only file holds like any other write.
 """
 import os
 import re
@@ -29,6 +31,16 @@ try:
 except Exception:  # pragma: no cover — telemetry is never load-bearing
     access_telemetry = None
 
+# The same write-target extractor the edit ledger uses after the fact. Its
+# absence degrades the shell branch to the read-only scan, never to a crash.
+try:
+    from _shell_writes import shell_write_targets
+except Exception:  # pragma: no cover — package-style import (dispatcher, tests)
+    try:
+        from cli._shell_writes import shell_write_targets
+    except Exception:
+        shell_write_targets = None
+
 _WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
 _READ_TOOLS = {"Read", "SearchText"}
 _SEARCH_TOOLS = {"Grep", "Glob", "FindFiles"}
@@ -206,21 +218,41 @@ def _record(denial, tool: str, operation: str, path: str,
 
 
 def _override_allows(base: str, denial, *, tool: str, op: str, path: str,
-                     session_id: str):
+                     session_id: str, peek: bool = False):
     """A live override grant covering this exact call, or None (spec §5).
 
     Lazy import and policy-before-grants ordering keep the hot path free: a
     project that never turned overrides on pays one dict lookup and never
     opens the grants file. Any failure returns None — the denial stands.
+
+    ``peek`` looks without consuming; see ``_granted`` for why.
     """
     try:
         from services import override_grants as og  # noqa: PLC0415 — lazy
         return og.gate_access(base, denial, tool=tool, op=op, path=path,
-                              session_id=session_id)
+                              session_id=session_id, peek=peek)
     except Exception:
         return None  # fail closed: no grant, ordinary denial
 
 
+def _granted(line: str, defer: bool, consume) -> dict:
+    """The allow-by-grant output.
+
+    Under the dispatcher (``defer`` True) the use is NOT burned here: the
+    provisional line goes out with an ``_on_allow`` callable, and
+    hook_dispatch runs it only once every PreToolUse sub-hook has voted
+    allow. Before v2.102.0 this hook consumed first and a strict-mode
+    discipline deny from hook_pretool_enforce then won the merge — grant
+    spent, nothing written, and the user asked twice for one edit. Run
+    standalone (``defer`` False) the use was already consumed by the peek-
+    less lookup, so the line is final.
+    """
+    out = {"additionalContext": line}
+    if defer:
+        out["_on_allow"] = consume
+    return out
+
+
 def _confirm_request(base: str, denial, *, tool: str, op: str, path: str,
                      session_id: str) -> tuple:
     """Auto-file an Override Request for a ``confirm`` denial (S8).
@@ -349,7 +381,68 @@ def _scan_shell(cmd: str, base: str):
     return None, ""
 
 
-def run(payload: dict, project_path: Path | None = None) -> dict | None:
+def _scan_shell_writes(cmd: str, base: str, session_id: str,
+                       defer: bool) -> dict | None:
+    """WRITE-class verdict for the files a shell command writes (v2.102.0).
+
+    ``_scan_shell`` evaluates every token as a READ. Confirm holds, read_only
+    rules and the builtin write-denies are all write-class, so ``cat >>
+    CLAUDE.md``, ``sed -i`` on .mcp.json or a heredoc into a hook body sailed
+    through with no hold — the one bypass docs/confirm-guard.md could only
+    ask the agent not to use. Targets come from the extractor the edit
+    ledger already trusts after the fact (cli/_shell_writes), with the same
+    best-effort caveat: a missed target costs a missed hold, a false one
+    costs a hold the human clears in one tap. Synthetic spelling denials are
+    skipped exactly as the read scan skips them (a token that is not a path
+    must not veto the command); the corrupt-config deny-all still refuses.
+
+    Grant identity is ``tool="Bash", op="write", path=<target>`` — bound to
+    the file, not the command text, the same stated limitation as the
+    shell_warn layer. Several held targets need several grants; the command
+    runs only when every one is covered, and the uses are burned together
+    (or not at all) by the dispatcher's settle step.
+    """
+    if shell_write_targets is None:
+        return None
+    lines, consumers = [], []
+    for target in shell_write_targets(cmd, base):
+        denial = ag.check(target, "write", base)
+        if denial is None:
+            continue
+        if denial.rule.startswith("<") and denial.rule != "<corrupt-config>":
+            continue
+        granted = _override_allows(base, denial, tool="Bash", op="write",
+                                   path=target, session_id=session_id,
+                                   peek=defer)
+        if granted:
+            lines.append(granted)
+            if defer:
+                consumers.append(lambda t=target, d=denial: _override_allows(
+                    base, d, tool="Bash", op="write", path=t,
+                    session_id=session_id))
+            continue
+        _record(denial, "Bash", "write", target, base, session_id)
+        if denial.kind == "confirm":
+            rid, note = _confirm_request(base, denial, tool="Bash", op="write",
+                                         path=target, session_id=session_id)
+            return _deny(ag.refusal(denial, target, "write", surface="hook",
+                                    tool="Bash", request_id=rid,
+                                    request_note=note)
+                         + " (best-effort shell scan)")
+        return _deny(ag.refusal(denial, target, "write", surface="hook",
+                                tool="Bash") + " (best-effort shell scan)")
+    if not lines:
+        return None
+
+    def _settle():
+        got = [fn() for fn in consumers]
+        return "\n".join(got) if all(got) else None
+
+    return _granted("\n".join(lines), bool(consumers), _settle)
+
+
+def run(payload: dict, project_path: Path | None = None,
+        defer_consume: bool = False) -> dict | None:
     tool = normalize_tool_name(payload.get("tool_name", ""))
     tool_input = payload.get("tool_input", {}) or {}
     base = str(project_path if project_path is not None else Path.cwd())
@@ -363,9 +456,13 @@ def run(payload: dict, project_path: Path | None = None) -> dict | None:
         denial = ag.check(fp, op, base)
         if denial:
             granted = _override_allows(base, denial, tool=tool, op=op,
-                                       path=fp, session_id=session_id)
+                                       path=fp, session_id=session_id,
+                                       peek=defer_consume)
             if granted:
-                return {"additionalContext": granted}
+                return _granted(granted, defer_consume,
+                                lambda: _override_allows(
+                                    base, denial, tool=tool, op=op, path=fp,
+                                    session_id=session_id))
             _record(denial, tool, op, fp, base, session_id)
             if denial.kind == "confirm":
                 # A confirm hold files its own request (grants were consulted
@@ -401,6 +498,6 @@ def run(payload: dict, project_path: Path | None = None) -> dict | None:
             return _deny(ag.refusal(denial, tok, "read",
                                     surface="hook", tool=tool)
                          + " (best-effort shell scan)")
-        return None
+        return _scan_shell_writes(cmd, base, session_id, defer_consume)
 
     return None

{code_context_control-2.101.0 → code_context_control-2.109.0}/cli/hook_dispatch.py

@@ -36,6 +36,7 @@ emit a short "[c3:hook-error] ..." additionalContext warning so enforcement
 cannot silently stop enforcing.
 """
 import importlib
+import inspect
 import json
 import sys
 from pathlib import Path
@@ -166,6 +167,16 @@ def _routes(event: str, raw_tool: str, norm_tool: str, host: str = HOST_CLAUDE):
 
 _RUN_CACHE: dict = {}
 
+# PreToolUse sub-hooks that consult override grants. Under the dispatcher
+# they are asked to DEFER consumption (`defer_consume=True`): each returns a
+# provisional allow carrying an `_on_allow` callable, and `_settle_grants`
+# runs those only once every sub-hook has voted allow. Before v2.102.0 the
+# access guard consumed a grant first and a strict-mode discipline deny from
+# the next sub-hook then won the merge — grant spent, nothing written, the
+# user asked twice for one edit. The same hole ran the other way for a
+# discipline grant followed by a policy deny.
+_DEFER_CONSUME = {"hook_access_guard", "hook_pretool_enforce"}
+
 # Modules whose failure must DENY rather than fall through (fail closed).
 # Scoped to write-class tools + shell: a broken guard must not let mutations
 # sail through, but read-class fail-open avoids bricking whole sessions.
@@ -189,6 +200,77 @@ def _fail_closed_deny(module_name: str, err: str) -> dict:
     }
 
 
+def _is_deny(out) -> bool:
+    hso = out.get("hookSpecificOutput") if isinstance(out, dict) else None
+    return isinstance(hso, dict) and hso.get("permissionDecision") == "deny"
+
+
+def _call_run(run_fn, module_name: str, event: str, payload: dict,
+              project_path):
+    """Invoke a sub-hook, asking the grant-aware ones to defer consumption.
+
+    Signature-checked rather than assumed: tests stub these modules with
+    two-argument lambdas, and a legacy single-file hook must keep working.
+    """
+    if event == "pretool" and module_name in _DEFER_CONSUME:
+        try:
+            accepts = "defer_consume" in inspect.signature(run_fn).parameters
+        except (TypeError, ValueError):
+            accepts = False
+        if accepts:
+            return run_fn(payload, project_path, defer_consume=True)
+    return run_fn(payload, project_path)
+
+
+def _grant_lost_deny() -> dict:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                "[c3-override:spent] the override grant that would have "
+                "allowed this call was used up between check and use (a "
+                "concurrent call spent it). The rule stands — ask again "
+                "with c3_override if it is still needed."
+            ),
+        }
+    }
+
+
+def _settle_grants(outputs: list) -> list:
+    """Burn deferred grant uses — only when the merged verdict is allow.
+
+    Any deny among the outputs means the call will not run, so every
+    `_on_allow` is dropped unrun and the grants stay live for the retry. On
+    an allow each consumer runs; the line it returns replaces the
+    provisional one (it carries the post-consumption uses count). A consumer
+    that finds nothing left — the grant was spent by a concurrent call
+    between peek and settle — turns its allow into a deny: the call must
+    not proceed on a grant that no longer exists.
+    """
+    denied = any(_is_deny(o) for o in outputs)
+    settled = []
+    for out in outputs:
+        if not isinstance(out, dict):
+            settled.append(out)
+            continue
+        consume = out.pop("_on_allow", None)
+        if consume is None or denied:
+            settled.append(out)
+            continue
+        try:
+            line = consume()
+        except Exception as exc:
+            log_hook_error("hook_dispatch:settle", exc)
+            line = None
+        if line:
+            out["additionalContext"] = str(line)
+            settled.append(out)
+        else:
+            settled.append(_grant_lost_deny())
+    return settled
+
+
 def _load_run(module_name: str):
     """Import cli.<module_name> and return its run() (cached).
 
@@ -353,7 +435,7 @@ def dispatch(event: str, payload: dict, project_path: Path | None = None) -> dic
                 outputs.append(_fail_closed_deny(module_name, err))
             continue
         try:
-            out = run_fn(payload, project_path)
+            out = _call_run(run_fn, module_name, event, payload, project_path)
             if out:
                 outputs.append(out)
         except Exception as exc:
@@ -368,7 +450,15 @@ def dispatch(event: str, payload: dict, project_path: Path | None = None) -> dic
         # Critical state-layer warnings (corrupt enforcement_state.json)
         # become visible instead of silently disabling enforcement.
         warnings.extend(_hook_utils.drain_state_warnings())
+        # A PreToolUse deny is final — merge keeps the first deny and no
+        # allow readmits it — so the sub-hooks after it have nothing to add,
+        # and running them could only spend a grant or log a block for a
+        # call that will not happen.
+        if event == "pretool" and outputs and _is_deny(outputs[-1]):
+            break
 
+    if event == "pretool":
+        outputs = _settle_grants(outputs)
     return merge_outputs(outputs, warnings, event=event, host=host)