code-context-control 2.131.0__py3-none-any.whl → 2.136.0__py3-none-any.whl

cli/c3.py

@@ -91,7 +91,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.131.0"
+__version__ = "2.136.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -1571,6 +1571,51 @@ def cmd_shell_eval(args):
         sys.exit(1)
 
 
+def cmd_delegate_eval(args):
+    """Grade c3_delegate answers per target and name the cheapest passing tier.
+
+    Live by default (every case goes to the real backend and costs what that
+    backend costs); --replay grades a recorded run instead. Exit status 1 when
+    a --floor is given and a target's core pass rate falls under it. See
+    docs/delegate-eval.md.
+    """
+    from services.bench import delegate_eval as de
+
+    targets = [t.strip() for t in (args.targets or "").split(",") if t.strip()]
+    case_ids = [c.strip() for c in (args.cases or "").split(",") if c.strip()]
+    overrides = json.loads(args.config) if getattr(args, "config", None) else None
+    if overrides is not None and not isinstance(overrides, dict):
+        raise RuntimeError("--config must be a JSON object")
+
+    def progress(res):
+        if not args.json:
+            cost = "" if res.cost_usd is None else f" ${res.cost_usd:.4f}"
+            print(f"  {res.target:<16} {res.id:<28} {res.status}{cost} "
+                  f"{res.wall_ms / 1000:.1f}s", flush=True)
+
+    try:
+        report = de.run_suite(
+            args.suite, targets=targets or None, replay=args.replay, record=args.record,
+            case_ids=case_ids or None, floor=args.floor if args.floor is not None else de.DEFAULT_FLOOR,
+            allow_write_delegation=args.allow_write_delegation, delegate_overrides=overrides,
+            progress=progress)
+    except (FileNotFoundError, ValueError) as e:
+        raise RuntimeError(str(e))
+
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(report.render())
+        if args.record and report.mode == "live":
+            print(f"recorded: {args.record}")
+    if args.floor is not None:
+        under = [t for t, a in report.aggregates.items()
+                 if a["pass_rate_core"] is None or a["pass_rate_core"] < args.floor]
+        if under:
+            print(f"under floor {args.floor}: {', '.join(under)}", file=sys.stderr)
+            sys.exit(1)
+
+
 def cmd_map_eval(args):
     """Run the file-map gold suite and compare it to its baseline.
 
@@ -5020,7 +5065,7 @@ back to native tools as the task progresses.
 - **Filter**: `c3_filter(text=...)` — for terminal output >10 lines
 - **Shell**: `c3_shell(cmd, timeout=60)` — structured shell exec (tests/git/build). Auto-filters output, logs git mutations to the ledger. Native Bash for interactive/TTY only
 - **Memory**: `c3_memory(action='recall')` — full recall. `index` + `fetch` for token-efficient two-step retrieval
-- **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|grok|auto')` — offload to other models
+- **Delegate**: `c3_delegate(task, task_type, context|file_path)` — your own provider one tier down (default `backend='host'`, `tier='small'`; Claude Code: Haiku) for bounded answers: summarize a diff/log, explain a function, triage a traceback. `scout=true` lets it look files up itself. Multi-step work: the `c3-scout` (haiku) / `c3-worker` (sonnet) subagents
 - **Local CI** (v2.79.0+): `c3_ci(action='inspect|run|rerun|failures')` — run THIS repo's real `.github/workflows` here instead of pushing for feedback. `run` executes in `needs` order; `failures` gives {file,line,message}; `rerun` retries only what failed. Only `FULL_CI_PASS` means safe to push — `PARTIAL_PASS` means something did not run (other OS, unsupported action, or your selection).
 - **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`.
@@ -5878,6 +5923,20 @@ def cmd_install_mcp(args):
         except Exception as e:
             print(f"Warning: Could not install /terse skill: {e}")
 
+    # ── Downshift subagents (c3-scout on haiku, c3-worker on sonnet) ──
+    if profile.name == "claude-code" and not getattr(args, "no_agents", False):
+        try:
+            from services.delegate_agents import install_delegate_agents
+            for path, action in install_delegate_agents(target):
+                if action == "skipped":
+                    print(f"Kept  {path}  (no C3 marker: yours, left untouched)")
+                elif action == "kept":
+                    print(f"Kept  {path}  (subagent up to date)")
+                else:
+                    print(f"{action.capitalize()} {path}  (subagent)")
+        except Exception as e:
+            print(f"Warning: Could not install c3-scout/c3-worker subagents: {e}")
+
     print(f"IDE: {profile.display_name}")
     print(f"MCP Mode: {mcp_mode}")
     print(f"Server: {server_script}")
@@ -9380,6 +9439,7 @@ def main():
         "search-eval": cmd_search_eval,
         "shell-eval": cmd_shell_eval,
         "map-eval": cmd_map_eval,
+        "delegate-eval": cmd_delegate_eval,
         "benchmark": cmd_benchmark,
         "session-benchmark": cmd_session_benchmark,
         "benchmark-e2e": cmd_benchmark_e2e,

cli/commands/parser.py

@@ -89,6 +89,26 @@ def build_parser(version: str, parse_cli_ide_arg):
                             help='With --update-baseline: JSON object of metric ceilings, e.g. \'{"tokens_p95": 4000}\'')
     p_map_eval.add_argument("--json", action="store_true", help="Emit the full report as JSON")
 
+    p_delegate_eval = subparsers.add_parser(
+        "delegate-eval", help="Grade c3_delegate answers per backend/tier (docs/delegate-eval.md)")
+    p_delegate_eval.add_argument("--suite", default="gold",
+                                 help="'gold' (bundled) or a .jsonl path")
+    p_delegate_eval.add_argument("--targets", default="",
+                                 help="Comma-separated backend[:tier] list, e.g. 'claude:small,claude:medium'")
+    p_delegate_eval.add_argument("--cases", default="", help="Comma-separated case ids (default: all)")
+    p_delegate_eval.add_argument("--replay", default=None,
+                                 help="Grade a recorded run instead of calling backends")
+    p_delegate_eval.add_argument("--record", default=None, help="Write the live answers to this JSON file")
+    p_delegate_eval.add_argument("--floor", type=float, default=None,
+                                 help="Core pass-rate floor; exit 1 when a target falls under it")
+    p_delegate_eval.add_argument("--allow-write-delegation", action="store_true",
+                                 help="Pass allow_write_delegation=true (needed for write-capable backends "
+                                      "when Access Guard rules exist)")
+    p_delegate_eval.add_argument("--config", default=None,
+                                 help='JSON object merged over the delegate config for this run, '
+                                      'e.g. \'{"allow_model_fallback": false}\'')
+    p_delegate_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", "smart", "structure", "outline"], default="map",
@@ -158,6 +178,7 @@ def build_parser(version: str, parse_cli_ide_arg):
     p_install_mcp.add_argument("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     p_install_mcp.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")
     p_install_mcp.add_argument("--include-mcp-wildcard", action="store_true", help="Add mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+    p_install_mcp.add_argument("--no-agents", action="store_true", help="Do not write the c3-scout/c3-worker subagents to .claude/agents (Claude Code only)")
 
     p_mcp_install = subparsers.add_parser("mcp-install", help="Alias for install-mcp")
     p_mcp_install.add_argument("targets", nargs="*", help="Optional project path and/or IDE shorthand")
@@ -166,6 +187,7 @@ def build_parser(version: str, parse_cli_ide_arg):
     p_mcp_install.add_argument("--global-fallback", action="store_true", help="Also install the machine-wide Codex fallback")
     p_mcp_install.add_argument("--permissions", choices=["read-only", "c3-strict", "standard", "permissive"], default=None, help="Apply Claude Code permission tier (Claude Code only)")
     p_mcp_install.add_argument("--include-mcp-wildcard", action="store_true", help="Add mcp__* wildcard so non-C3 MCP servers don't prompt per-call")
+    p_mcp_install.add_argument("--no-agents", action="store_true", help="Do not write the c3-scout/c3-worker subagents to .claude/agents (Claude Code only)")
 
     p_mcp_remove = subparsers.add_parser("mcp-remove", help="Remove an MCP server from your IDE config")
     p_mcp_remove.add_argument("name", help="Name of the MCP server to remove (e.g. 'c3')")

cli/guide/tools.html

@@ -898,10 +898,10 @@ c3_status(view=<span class="str">'sessions'</span>)         <span class="com">#
           <div class="tag-row">
             <span class="badge badge-orange">AI</span>
           </div>
-          <span class="tool-tagline">Offload tasks to Ollama, Codex, Gemini, or Claude CLI</span>
+          <span class="tool-tagline">Hand bounded work to your own provider, one tier down</span>
         </div>
         <div class="tool-card-body">
-          <p class="tool-desc">Delegates tasks to local or remote AI backends to save Claude tokens on routine work (summarization, routing, simple Q&amp;A). Supports automatic backend selection based on task type.</p>
+          <p class="tool-desc">Sends a bounded task (summarize a diff or log, explain a function, triage a traceback, draft a docstring or test cases) to a smaller model from the provider you already run on. In Claude Code that is Haiku by default, through a tool-less <code>claude -p</code> that answers only from the context C3 packs for it. On C3's delegate eval, Haiku passed all 22 bounded cases at about a fifth of Opus's cost.</p>
 
           <table class="params-table">
             <thead><tr><th>Parameter</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
@@ -916,34 +916,61 @@ c3_status(view=<span class="str">'sessions'</span>)         <span class="com">#
                 <td class="param-name">task_type</td>
                 <td class="param-type">string</td>
                 <td class="param-default">"ask"</td>
-                <td class="param-desc"><code>ask</code> general Q&amp;A · <code>summarize</code> summarization · <code>auto</code> let C3 route optimally</td>
+                <td class="param-desc"><code>ask</code> · <code>explain</code> · <code>summarize</code> · <code>review</code> · <code>diagnose</code> · <code>docstring</code> · <code>test</code> · <code>auto</code> · <code>ping</code> (one live call to check auth) · <code>available</code> (CLI versions only)</td>
               </tr>
               <tr>
                 <td class="param-name">context</td>
                 <td class="param-type">string</td>
                 <td class="param-default">""</td>
-                <td class="param-desc">Additional context to include with the task</td>
+                <td class="param-desc">The text the delegate answers from</td>
+              </tr>
+              <tr>
+                <td class="param-name">file_path</td>
+                <td class="param-type">string</td>
+                <td class="param-default">""</td>
+                <td class="param-desc">Comma-separated files C3 reads under Access Guard and packs into the prompt (a file over 8k tokens goes as its map; a masked path is refused)</td>
               </tr>
               <tr>
                 <td class="param-name">backend</td>
                 <td class="param-type">string</td>
-                <td class="param-default">"auto"</td>
-                <td class="param-desc"><code>ollama</code> · <code>codex</code> · <code>gemini</code> · <code>claude</code> · <code>auto</code></td>
+                <td class="param-default">"host"</td>
+                <td class="param-desc"><code>host</code> = your own provider (Claude Code → <code>claude</code>, Codex → <code>codex</code>, Grok Build → <code>grok</code>, Antigravity → <code>gemini</code>) · <code>claude</code> · <code>codex</code> · <code>gemini</code> · <code>grok</code> · <code>ollama</code> · <code>auto</code></td>
+              </tr>
+              <tr>
+                <td class="param-name">tier</td>
+                <td class="param-type">string</td>
+                <td class="param-default">"small"</td>
+                <td class="param-desc"><code>small</code> · <code>medium</code> · <code>large</code> · <code>default</code>. Claude: Haiku / Sonnet / Opus. Codex and Grok: reasoning effort low / medium / high on the account's model. Gemini: flash-lite / flash / pro.</td>
+              </tr>
+              <tr>
+                <td class="param-name">model</td>
+                <td class="param-type">string</td>
+                <td class="param-default">""</td>
+                <td class="param-desc">A model alias or id; overrides the tier</td>
+              </tr>
+              <tr>
+                <td class="param-name">scout</td>
+                <td class="param-type">bool</td>
+                <td class="param-default">false</td>
+                <td class="param-desc">Let the delegate Read/Grep/Glob the project itself, for lookups when you cannot name the files. Claude runs <code>--restricted</code> with Access Guard's read denies; Codex uses its read-only sandbox.</td>
               </tr>
             </tbody>
           </table>
 
           <h4>Examples</h4>
-          <pre><code><span class="com"># Delegate summarization to local Ollama</span>
-c3_delegate(task=<span class="str">'Summarize what this function does'</span>, context=<span class="str">'&lt;function code&gt;'</span>, backend=<span class="str">'ollama'</span>, task_type=<span class="str">'summarize'</span>)
+          <pre><code><span class="com"># Summarize a diff on Haiku (Claude Code host, default tier)</span>
+c3_delegate(task=<span class="str">'Summarize this diff for a changelog in three bullets'</span>, context=<span class="str">'&lt;diff&gt;'</span>, task_type=<span class="str">'summarize'</span>)
+
+<span class="com"># Explain a function on Sonnet</span>
+c3_delegate(task=<span class="str">'What does resolve_host return inside a grok child?'</span>, file_path=<span class="str">'core/host.py'</span>, task_type=<span class="str">'explain'</span>, tier=<span class="str">'medium'</span>)
 
-<span class="com"># Auto-route based on task type</span>
-c3_delegate(task=<span class="str">'What is the purpose of this config key?'</span>, context=<span class="str">'&lt;config snippet&gt;'</span>, backend=<span class="str">'auto'</span>)</code></pre>
+<span class="com"># A lookup the delegate does itself</span>
+c3_delegate(task=<span class="str">'Which functions call charge_card, and where?'</span>, scout=<span class="kw">True</span>)</code></pre>
 
           <div class="callout callout-info">
             <span class="callout-icon">ℹ️</span>
             <div class="callout-body">
-              Requires Ollama running locally for <code>ollama</code> backend. Codex and Gemini backends require their respective CLIs. The <code>claude</code> backend uses the Claude Code CLI in non-interactive print mode (<code>claude -p</code>) — no extra config needed if Claude Code is installed. Use <code>task_type='available'</code> to check which of the 4 backends are reachable.
+              For multi-step work in Claude Code, <code>c3 install-mcp</code> also writes two subagents to <code>.claude/agents</code>: <code>c3-scout</code> (Haiku, read-only) and <code>c3-worker</code> (Sonnet). They run inside your session, so C3's hooks apply to them. Skip them with <code>--no-agents</code>. <code>c3 delegate-eval</code> measures pass rate and cost per backend and tier on your machine.
             </div>
           </div>
         </div>

cli/hook_access_guard.py

@@ -501,3 +501,39 @@ def run(payload: dict, project_path: Path | None = None,
         return _scan_shell_writes(cmd, base, session_id, defer_consume)
 
     return None
+
+
+def main() -> None:
+    """Standalone PreToolUse entry for a ``c3_delegate`` scout run.
+
+    A scout is ``claude -p --restricted`` with Read/Grep/Glob and no C3 MCP
+    server, so the dispatcher's discipline hook (hook_pretool_enforce) would
+    refuse every native read. Only the access guard runs here. It prints a
+    deny and nothing else: grants and search footers are for an agent that
+    can act on them. Any failure denies (fail closed).
+    """
+    import argparse
+    import json
+
+    from _hook_utils import ensure_utf8_stdio
+
+    ensure_utf8_stdio()
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project", required=True)
+    args = parser.parse_args()
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        if not isinstance(payload, dict):
+            raise ValueError("hook payload must be a JSON object")
+        # access_guard canonicalizes the base itself (no direct resolve here).
+        out = run(payload, Path(args.project))
+    except Exception as exc:
+        out = _deny(f"[c3-access:error] scout guard failed ({type(exc).__name__}: {exc}); "
+                    "refusing the call")
+    if isinstance(out, dict) and isinstance(out.get("hookSpecificOutput"), dict):
+        print(json.dumps({"hookSpecificOutput": out["hookSpecificOutput"]}))
+
+
+if __name__ == "__main__":
+    main()

cli/mcp_server.py

@@ -803,13 +803,16 @@ async def c3_status(view: str = "budget", detailed: bool = False,
 
 @mcp.tool()
 async def c3_delegate(task: str, task_type: str = "ask", context: str = "",
-                file_path: str = "", backend: str = "ollama",
+                file_path: str = "", backend: str = "host",
                 allow_write_delegation: bool = False,
+                tier: str = "", model: str = "", scout: bool = False,
                 ctx: Context = None) -> str:
     """OFFLOAD to another model — use when the subtask is local-model-sized or needs a different perspective.
-    backend: ollama|codex|gemini|claude|grok|auto. task_type: auto, summarize, explain, review, ask, test, diagnose, available, codex_check, gemini_check, grok_check, codex_resume.
+    backend: host (default: your own provider, one tier down — Claude Code->claude, Codex->codex, Grok->grok, Antigravity->gemini) | claude|codex|gemini|grok|ollama|auto. task_type: auto, summarize, explain, review, ask, test, diagnose, ping (live auth check), available, codex_check, gemini_check, grok_check, codex_resume.
+    tier: small (default) | medium | large | default. claude: haiku/sonnet/opus; codex/grok: reasoning effort; gemini: flash-lite/flash/pro. model overrides the tier. Context + file_path are packed by C3 under Access Guard; a file over 8k tokens goes as its map, so for line-level questions on a big file paste the excerpt or use scout=true.
+    scout=true: the delegate may Read/Grep/Glob the project itself (claude: read-only, guard-denied paths refused; codex: its read-only sandbox) — for lookups when you cannot name the files.
     grok runs read-only in a temp dir unless delegate.grok_allow_write=true (then --yolo in the project, loading its trusted .grok MCP servers and hooks).
-    allow_write_delegation: explicit user opt-in for write-capable backends (gemini/claude/grok write mode/codex_resume) while Access Guard rules are active; codex is pinned read-only instead."""
+    allow_write_delegation: explicit user opt-in for write-capable backends (gemini/grok write mode/codex_resume) while Access Guard rules are active; codex is pinned read-only instead."""
     svc = _svc(ctx)
 
     def finalize(name, args, resp, summ, **kw):
@@ -825,7 +828,7 @@ async def c3_delegate(task: str, task_type: str = "ask", context: str = "",
     try:
         return await asyncio.to_thread(handle_delegate, task, task_type, context,
                                        file_path, svc, finalize, backend,
-                                       allow_write_delegation)
+                                       allow_write_delegation, tier, model, scout)
     finally:
         svc._agent_progress_cb = None