code-context-control 2.66.0__tar.gz → 2.70.0__tar.gz

{code_context_control-2.66.0/code_context_control.egg-info → code_context_control-2.70.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.66.0
+Version: 2.70.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
@@ -186,7 +186,7 @@ Twelve tabs. The dashboard above shows token savings, indexed files, the live se
 
 ## The MCP tool suite
 
-C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
+C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 
 | Tool | What it does |
 |---|---|
@@ -201,6 +201,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_memory` | Fact store with categories, recall, graph queries, `index`→`fetch` two-step |
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
+| `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter |
@@ -211,7 +212,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |
 
-Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task`.
+Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task` / `c3_locks`.
 
 On Windows `c3_shell` uses Git Bash when available. Git Bash bundles no `jq`; use `python -m json.tool` for portable JSON formatting.
 
@@ -242,12 +243,61 @@ c3 access mask activate                         # purge pre-mask artifacts, buil
 - **Masked means read-only, always.** Cropped rows have no inverse, so an edit in transformed coordinates would corrupt the one file you protected.
 - **Four deterministic presets, no LLM in the read path:** `redact_secrets`, `redact_columns` (salted one-way pseudonyms — joins survive, no reverse dictionary), `sample_rows`, `signatures_only`.
 - **Rule changes are human-only** (UI tab or CLI) and ledger-logged. Agents have no mutation surface.
+- **Built-ins can be switched off when you need to** (v2.65.0). `**/.env*`, `**/.c3/**`, `**/.claude/settings*.json` and `**/.git/**` yield to `c3 access builtin disable <glob>`, which makes you retype the glob first. It takes **two keys** — a config entry *and* a keyring attestation — so an agent that manages to write `config.json` still cannot grant itself write access to your settings. The credential vault stays absolute.
 - **Honest coverage.** This guards *cooperative* agents against mistakes and prompt injection. It is not a sandbox — a raw shell outside C3's tools still sees the real bytes.
 
 → [Access Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/access-guard.md) · [Mask Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/mask-guard.md)
 
 ---
 
+## Agent Locks — several agents, one repo (v2.65.0)
+
+Guards answer *may the agent touch this?* Locks answer *is someone already touching it?*
+
+Two agents editing one file used to be silent data loss. `c3_edit` serialized
+same-file edits with an in-process lock, but every session runs its own `c3-mcp`
+server — so two sessions could interleave read → replace → write and lose an edit
+with no error on either side. Create mode was worse: both agents "succeeded" and
+one file won.
+
+Now there are two mechanisms, because they solve different problems:
+
+- **Torn writes** — a cross-process file lock, held across create, single-edit and
+  batch alike. No daemon, no configuration, nothing to switch on.
+- **Overlapping work** — a *lease*. `c3_edit` takes one on the file it edits,
+  carrying the intent from your edit summary. A second agent gets told who holds
+  it and why:
+
+```text
+[c3-lock:held] services/router.py is held by claude-code:a3f19c2b.
+  intent: "refactor retry backoff"
+  lease expires in 6m12s.
+```
+
+```bash
+c3 locks list                              # who holds what, across the project
+c3 locks force-release services/router.py  # break a stuck lease (human-only, audited)
+```
+
+- **TTL is the real release mechanism.** Agents forget to release, so nothing
+  assumes they will — a crashed agent can never wedge a repo.
+- **Acquisition is all-or-nothing** over a sorted path list, so two agents grabbing
+  the same pair in opposite order cannot deadlock.
+- **`force-release` bumps a fencing counter**, so a holder that comes back is stale
+  by construction rather than by hope. It lives in the CLI and the Hub, never in
+  the agent-facing tool.
+- **The Hub's Locks tab badges a project it cannot read as `UNREADABLE`**, not as
+  zero leases — "all clear" is a different claim from "we don't know".
+- **Honest coverage, again.** Leases gate C3's own tool surfaces. A raw `c3_shell`
+  redirect, a non-Claude agent, or a human in an editor is *not* covered, and the
+  UI says so on screen.
+
+Set `locks.enabled: false` in `.c3/config.json` to opt out.
+
+→ [Agent Locks](https://github.com/drknowhow/code-context-control/blob/main/docs/agent-locks.md)
+
+---
+
 ## Integrations
 
 | | What you get | Guide |
@@ -319,6 +369,8 @@ C3 also records real per-tool usage to `.c3/tool_telemetry.jsonl`, so estimates
 ## Security & privacy
 
 - **All web servers bind `127.0.0.1` by default** and are guarded against browser-based attacks even on loopback — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface is opt-in and warned at startup. *(Hardening added in v2.33.0.)*
+- **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires the **Discovery Bearer token on every method, GETs included**, validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (QR code carrying URL + token). Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
+- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, `set_builtin_disabled`, and the raw-content access preview.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`; even then request bodies, local variables, and prompts are stripped.
 - **LLM memory distillation is local-first.** Cloud distillation (v2.51.0) is off by default and opt-in per project.
 - **API keys** for third-party providers are read from the environment and never persisted by C3.

{code_context_control-2.66.0 → code_context_control-2.70.0}/README.md

@@ -123,7 +123,7 @@ Twelve tabs. The dashboard above shows token savings, indexed files, the live se
 
 ## The MCP tool suite
 
-C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
+C3 exposes **21 tools** as a native MCP server. Your IDE calls them directly:
 
 | Tool | What it does |
 |---|---|
@@ -138,6 +138,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_memory` | Fact store with categories, recall, graph queries, `index`→`fetch` two-step |
 | `c3_session` | Snapshot, restore, log decisions, compact history |
 | `c3_impact` | Blast-radius analysis before editing shared symbols |
+| `c3_locks` | Agent leases — who is working on which file, so two agents don't collide (v2.65.0) |
 | `c3_delegate` | Offload heavy work to local Ollama / Codex / Gemini |
 | `c3_agent` | Workflows: `review_changes`, `investigate`, `preflight`, `prepare_context`, `validate_compress` |
 | `c3_edits` | Edit-ledger queries, version diffs, restore points, per-branch filter |
@@ -148,7 +149,7 @@ C3 exposes **20 tools** as a native MCP server. Your IDE calls them directly:
 | `c3_jira` | Jira Cloud + Data Center — JQL, issues, transitions (v2.56.0) |
 | `c3_project` | Cross-project discovery & operations; guarded writes (v2.31.0) |
 
-Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task`.
+Every tool is **read-only safe in plan mode** except `c3_edit`, `c3_shell`, `c3_artifacts(action='restore')`, `c3_delegate` with write delegation enabled, and write actions on `c3_bitbucket` / `c3_jira` / `c3_credentials` / `c3_project` / `c3_task` / `c3_locks`.
 
 On Windows `c3_shell` uses Git Bash when available. Git Bash bundles no `jq`; use `python -m json.tool` for portable JSON formatting.
 
@@ -179,12 +180,61 @@ c3 access mask activate                         # purge pre-mask artifacts, buil
 - **Masked means read-only, always.** Cropped rows have no inverse, so an edit in transformed coordinates would corrupt the one file you protected.
 - **Four deterministic presets, no LLM in the read path:** `redact_secrets`, `redact_columns` (salted one-way pseudonyms — joins survive, no reverse dictionary), `sample_rows`, `signatures_only`.
 - **Rule changes are human-only** (UI tab or CLI) and ledger-logged. Agents have no mutation surface.
+- **Built-ins can be switched off when you need to** (v2.65.0). `**/.env*`, `**/.c3/**`, `**/.claude/settings*.json` and `**/.git/**` yield to `c3 access builtin disable <glob>`, which makes you retype the glob first. It takes **two keys** — a config entry *and* a keyring attestation — so an agent that manages to write `config.json` still cannot grant itself write access to your settings. The credential vault stays absolute.
 - **Honest coverage.** This guards *cooperative* agents against mistakes and prompt injection. It is not a sandbox — a raw shell outside C3's tools still sees the real bytes.
 
 → [Access Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/access-guard.md) · [Mask Guard](https://github.com/drknowhow/code-context-control/blob/main/docs/mask-guard.md)
 
 ---
 
+## Agent Locks — several agents, one repo (v2.65.0)
+
+Guards answer *may the agent touch this?* Locks answer *is someone already touching it?*
+
+Two agents editing one file used to be silent data loss. `c3_edit` serialized
+same-file edits with an in-process lock, but every session runs its own `c3-mcp`
+server — so two sessions could interleave read → replace → write and lose an edit
+with no error on either side. Create mode was worse: both agents "succeeded" and
+one file won.
+
+Now there are two mechanisms, because they solve different problems:
+
+- **Torn writes** — a cross-process file lock, held across create, single-edit and
+  batch alike. No daemon, no configuration, nothing to switch on.
+- **Overlapping work** — a *lease*. `c3_edit` takes one on the file it edits,
+  carrying the intent from your edit summary. A second agent gets told who holds
+  it and why:
+
+```text
+[c3-lock:held] services/router.py is held by claude-code:a3f19c2b.
+  intent: "refactor retry backoff"
+  lease expires in 6m12s.
+```
+
+```bash
+c3 locks list                              # who holds what, across the project
+c3 locks force-release services/router.py  # break a stuck lease (human-only, audited)
+```
+
+- **TTL is the real release mechanism.** Agents forget to release, so nothing
+  assumes they will — a crashed agent can never wedge a repo.
+- **Acquisition is all-or-nothing** over a sorted path list, so two agents grabbing
+  the same pair in opposite order cannot deadlock.
+- **`force-release` bumps a fencing counter**, so a holder that comes back is stale
+  by construction rather than by hope. It lives in the CLI and the Hub, never in
+  the agent-facing tool.
+- **The Hub's Locks tab badges a project it cannot read as `UNREADABLE`**, not as
+  zero leases — "all clear" is a different claim from "we don't know".
+- **Honest coverage, again.** Leases gate C3's own tool surfaces. A raw `c3_shell`
+  redirect, a non-Claude agent, or a human in an editor is *not* covered, and the
+  UI says so on screen.
+
+Set `locks.enabled: false` in `.c3/config.json` to opt out.
+
+→ [Agent Locks](https://github.com/drknowhow/code-context-control/blob/main/docs/agent-locks.md)
+
+---
+
 ## Integrations
 
 | | What you get | Guide |
@@ -256,6 +306,8 @@ C3 also records real per-tool usage to `.c3/tool_telemetry.jsonl`, so estimates
 ## Security & privacy
 
 - **All web servers bind `127.0.0.1` by default** and are guarded against browser-based attacks even on loopback — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface is opt-in and warned at startup. *(Hardening added in v2.33.0.)*
+- **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires the **Discovery Bearer token on every method, GETs included**, validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (QR code carrying URL + token). Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
+- **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, `set_builtin_disabled`, and the raw-content access preview.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`; even then request bodies, local variables, and prompts are stripped.
 - **LLM memory distillation is local-first.** Cloud distillation (v2.51.0) is off by default and opt-in per project.
 - **API keys** for third-party providers are read from the environment and never persisted by C3.

{code_context_control-2.66.0 → code_context_control-2.70.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.66.0"
+__version__ = "2.70.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):
@@ -261,6 +261,7 @@ _C3_MCP_ALLOW = [
     "mcp__c3__c3_bitbucket",
     "mcp__c3__c3_jira", "mcp__c3__c3_credentials",
     "mcp__c3__c3_project", "mcp__c3__c3_task", "mcp__c3__c3_artifacts",
+    "mcp__c3__c3_override",
 ]
 
 # Obsolete MCP tool names from earlier C3 versions. `c3 permissions clean`
@@ -6209,6 +6210,299 @@ def _enforce_audit(result: dict, project_path: str) -> None:
         pass
 
 
+_OVERRIDE_DEFAULT_TOOL = {"read": "Read", "write": "Edit"}
+
+
+def cmd_override(args):
+    """`c3 override` — Override Requests: allow one blocked call, once.
+
+    The human half of docs/override-requests.md. Every verb here mints or
+    inspects a *grant*; none of them edits policy. That separation is the
+    entire point of the feature: today the only way to unblock an agent is to
+    weaken a rule permanently, and a guard that spends its life in `advisory`
+    is not a guard.
+
+    No agent surface reaches this command, and no approval here can touch the
+    'never' rows of spec §2 — the credential vault, Tier-0 absolute denies, or
+    the catastrophic shell blocks.
+    """
+    sub = getattr(args, "override_cmd", None)
+    if not sub:
+        print("Usage: c3 override <policy|grant|list|revoke|check|sweep> ...")
+        print("       c3 override policy    # what is escalatable right now")
+        return
+
+    from services import override_grants as og
+    from services import override_policy as opol
+
+    project_path = str(Path(getattr(args, "project_path", ".") or ".").resolve())
+    policy = opol.resolve(project_path)
+    for warn in policy.warnings:
+        print(f"  [warn] {warn}")
+
+    if sub == "policy":
+        _override_show(policy, project_path, opol)
+    elif sub == "grant":
+        _override_grant(args, policy, project_path, og, opol)
+    elif sub == "list":
+        _override_list(args, project_path, og)
+    elif sub == "check":
+        _override_check(args, policy, project_path, og, opol)
+    elif sub == "revoke":
+        gid = getattr(args, "grant_id", "")
+        print("  Revoked." if og.revoke(project_path, gid)
+              else f"  No live grant with id '{gid}'.")
+    elif sub == "sweep":
+        print(f"  Dropped {og.sweep_expired(project_path)} expired/spent grant(s).")
+    elif sub == "requests":
+        _override_requests(args, project_path)
+    elif sub in ("approve", "deny"):
+        _override_decide(args, sub, project_path)
+
+
+def _override_requests(args, project_path: str) -> None:
+    from services import override_requests as orq
+
+    rows = orq.list_requests(
+        project_path="" if getattr(args, "all_projects", False) else project_path,
+        status=getattr(args, "status", "") or "")
+    print_header("Override requests")
+    if not rows:
+        print("  (none)")
+        return
+    for r in rows:
+        note = f"  note: {r['decision_note']}" if r.get("decision_note") else ""
+        print(f"  {r['id']}  {r['status']:<9} {r['tool']} {r['op']} {r['path']}")
+        print(f"  {'':18s} rule {r['rule']} ({r['rule_class']}) · session "
+              f"{r['session_id']} · expires {r['expires_at']}{note}")
+        if r.get("justification"):
+            print(f"  {'':18s} the agent wrote: \"{r['justification']}\"")
+            print(f"  {'':18s} (untrusted — it may be repeating text it read "
+                  f"from a file)")
+    print("\n  Approve: c3 override approve <id>   Refuse: c3 override deny <id>")
+
+
+def _override_decide(args, decision: str, project_path: str) -> None:
+    from services import override_requests as orq
+
+    try:
+        row = orq.decide(getattr(args, "request_id", ""), decision,
+                         uses=getattr(args, "uses", None),
+                         ttl_s=getattr(args, "ttl_s", None),
+                         note=getattr(args, "note", "") or "",
+                         decided_by="cli",
+                         confirm=getattr(args, "confirm", None))
+    except orq.OverrideError as exc:
+        print(f"  {exc}")
+        return
+    except ValueError as exc:
+        print(f"  Error: {exc}")
+        return
+
+    if decision == "deny":
+        print(f"  Denied {row['id']}. The block stands.")
+        return
+    print_header("Override approved")
+    print(f"  Request : {row['id']}   Grant: {row.get('grant_id', '?')}")
+    print(f"  Allows  : {row['tool']} {row['op']} on {row['path']}")
+    print(f"  Session : {row['session_id']}")
+    print(f"\n  The rule {row['rule']} is still in force. One retry of this "
+          "exact call, in")
+    print("  that session, on that exact path — nothing else.")
+
+
+def _override_show(policy, project_path: str, opol) -> None:
+    print_header("Override Requests")
+    state = "on" if policy.enabled else "off"
+    print(f"  Enabled : {state}   (channel: {policy.channel})")
+    print(f"  Project : {project_path}")
+    print("\n  Escalatable layers:")
+    for key in opol.LAYER_KEYS:
+        on = policy.escalatable(key)
+        mark = "*" if on else " "
+        extra = "  (approval needs the rule typed by hand)" \
+            if key in opol.TYPED_CONFIRM_LAYERS else ""
+        print(f"   {mark} {key:18s} {'yes' if on else 'no':3s}{extra}")
+    print("\n  Limits:")
+    print(f"    grant TTL   : <= {policy.max_ttl_s}s (hard ceiling "
+          f"{opol.HARD_MAX_TTL_S}s)")
+    print(f"    uses        : {policy.default_uses} "
+          f"(session grants: {'allowed' if policy.allow_session_grants else 'off'})")
+    print(f"    request TTL : {policy.request_ttl_s}s")
+    print(f"    rate        : {policy.max_pending_per_session} pending/session, "
+          f"{policy.max_requests_per_hour}/hour")
+    if policy.corrupt_scopes:
+        print(f"\n  FAILING CLOSED — corrupt scope(s): "
+              f"{', '.join(policy.corrupt_scopes)}")
+    print("\n  Never escalatable, at any setting: the credential vault, "
+          ".c3/secrets.enc,")
+    print("  .c3/cred_state.json, the dispatcher fail-closed deny, and the "
+          "catastrophic")
+    print("  shell blocks. Policy lives in .c3/config.json 'override' "
+          "(human-edited).")
+
+
+def _override_identify(args, project_path: str, opol):
+    """(gate, layer_key, rule, tool, op, error) for the call being approved.
+
+    Derived from the denial the path ACTUALLY produces, not from what the
+    caller claims: a grant whose rule string does not match the rule that
+    denies would never match at consume time, and a silently-useless grant is
+    worse than a refusal.
+    """
+    op = getattr(args, "op", "read") or "read"
+    tool = getattr(args, "tool", None) or _OVERRIDE_DEFAULT_TOOL[op]
+    layer = getattr(args, "layer", None)
+    target = getattr(args, "target", "")
+
+    if layer == "discipline":
+        return (opol.GATE_DISCIPLINE, opol.LAYER_DISCIPLINE,
+                opol.RULE_DISCIPLINE, tool, "write", None)
+    if layer == "shell":
+        return (opol.GATE_SHELL, opol.LAYER_SHELL_WARN,
+                opol.RULE_SHELL_WARN, tool, op, None)
+
+    from services import access_guard as ag
+    denial = ag.check(target, op, project_path)
+    if denial is None:
+        return (None, None, None, tool, op,
+                f"`{target}` is not blocked for {op} — nothing to approve.")
+    layer_key = opol.rule_class_for_denial(denial)
+    if layer_key is None:
+        return (None, None, None, tool, op,
+                f"{opol.TAG_NOT_ESCALATABLE} `{denial.rule}` can never be "
+                f"overridden — no config value and no approval reaches it.")
+    gate = opol.GATE_FOR_LAYER_KEY[layer_key]
+    if layer and layer != gate:
+        return (None, None, None, tool, op,
+                f"--layer {layer} does not match the layer that denied "
+                f"({gate}, rule `{denial.rule}`).")
+    return gate, layer_key, denial.rule, tool, op, None
+
+
+def _override_grant(args, policy, project_path: str, og, opol) -> None:
+    gate, layer_key, rule, tool, op, err = _override_identify(
+        args, project_path, opol)
+    if err:
+        print(f"  {err}")
+        return
+    if not policy.enabled:
+        print("  Overrides are disabled for this project.")
+        print("  Enable by hand in .c3/config.json — the 'override' section, "
+              "\"enabled\": true,")
+        print(f"  plus \"layers\": {{\"{layer_key}\": true}}. Nothing is "
+              "escalatable by default.")
+        return
+    if not policy.escalatable(layer_key):
+        print(f"  The '{layer_key}' layer is not escalatable "
+              f"(override.layers.{layer_key} is false).")
+        print("  Opt in per layer, deliberately — that is the point of the "
+              "default.")
+        return
+    if (layer_key in opol.TYPED_CONFIRM_LAYERS
+            and getattr(args, "confirm", None) != rule):
+        print(f"  This approves ONE call against an {layer_key} rule "
+              f"({rule}).")
+        print(f"  Retype the rule to confirm:  --confirm '{rule}'")
+        return
+    try:
+        grant = og.mint(project_path, session_id=getattr(args, "session_id", ""),
+                        layer=gate, rule=rule, tool=tool, op=op,
+                        path=getattr(args, "target", ""),
+                        ttl_s=getattr(args, "ttl_s", None),
+                        uses=getattr(args, "uses", None),
+                        granted_by="cli", policy=policy)
+    except ValueError as exc:
+        print(f"  Error: {exc}")
+        return
+
+    print_header("Override granted")
+    print(f"  Id      : {grant['id']}")
+    print(f"  Allows  : {tool} {op} on {grant['path_key']}")
+    print(f"  Layer   : {gate}   Rule: {rule}")
+    print(f"  Session : {grant['session_id']}")
+    print(f"  Expires : {grant['expires_at']}   Uses: "
+          f"{grant['uses_remaining']}")
+    if getattr(args, "ttl_s", None) and grant.get("expires_at"):
+        print(f"  (TTL clamped to override.max_ttl_s = {policy.max_ttl_s}s "
+              f"where it exceeded it)")
+    print(f"\n  The rule {rule} is still in force. This grant authorises one "
+          "retry of")
+    print("  this exact call, in this session, on this exact path, and "
+          "nothing else.")
+    _override_audit(grant, project_path)
+
+
+def _override_list(args, project_path: str, og) -> None:
+    grants = og.active(project_path, getattr(args, "session_id", "") or "")
+    print_header("Live override grants")
+    if not grants:
+        print("  (none)")
+    for g in grants:
+        print(f"  {g.get('id', '?'):18s} {g.get('tool', '?')} "
+              f"{g.get('op', '?')} {g.get('path_key', '?')}")
+        print(f"  {'':18s} rule {g.get('rule', '?')} · session "
+              f"{g.get('session_id', '?')} · expires {g.get('expires_at', '?')}"
+              f" · {g.get('uses_remaining', 0)} use(s) left")
+    tail = int(getattr(args, "audit", 0) or 0)
+    if tail:
+        print("\n  Audit (.c3/overrides.jsonl):")
+        for line in og.read_audit(project_path, tail):
+            print(f"    {line.get('ts', '?')}  {line.get('event', '?'):12s} "
+                  f"{line.get('grant_id', '')} {line.get('path', '')}")
+
+
+def _override_check(args, policy, project_path: str, og, opol) -> None:
+    gate, layer_key, rule, tool, op, err = _override_identify(
+        args, project_path, opol)
+    if err:
+        print(f"  {err}")
+        return
+    if not policy.escalatable(layer_key):
+        print(f"  Denied — the '{layer_key}' layer is not escalatable, so no "
+              "grant is even consulted.")
+        return
+    hit = og.find(project_path, session_id=getattr(args, "session_id", ""),
+                  layer=gate, rule=rule, tool=tool, op=op,
+                  path=getattr(args, "target", ""))
+    if hit:
+        print(f"  Allowed by {hit['id']} — {hit['uses_remaining']} use(s) "
+              f"left, expires {hit['expires_at']}.")
+        print("  (`check` never consumes a use.)")
+    else:
+        print("  Denied — no live grant matches this exact "
+              "session/layer/rule/tool/op/path.")
+
+
+def _override_audit(grant: dict, project_path: str) -> None:
+    """Ledger + activity entry. The JSONL audit is written by the service."""
+    try:
+        from services.activity_log import ActivityLog
+        ActivityLog(project_path).log("access_action", {
+            "kind": "override", "action": "grant", "grant_id": grant["id"],
+            "layer": grant["layer"], "rule": grant["rule"],
+            "tool": grant["tool"], "op": grant["op"],
+            "path": grant["path_key"], "session_id": grant["session_id"],
+            "expires_at": grant["expires_at"],
+            "uses": grant["uses_remaining"], "granted_by": grant["granted_by"],
+        })
+    except Exception:
+        pass
+    try:
+        from services.edit_ledger import EditLedger
+        EditLedger(project_path).log_edit(
+            file=f"override://{grant['id']}",
+            change_type="override_grant",
+            summary=(f"granted {grant['tool']} {grant['op']} on "
+                     f"{grant['path_key']} once (rule {grant['rule']}, "
+                     f"expires {grant['expires_at']}) via `c3 override`"),
+            tags=["override", "access"],
+            detail={"kind": "override", **grant},
+        )
+    except Exception:
+        pass
+
+
 def cmd_access(args):
     """Access Guard rule management — human-only mutation surface (spec §1)."""
     sub = getattr(args, "access_cmd", None)
@@ -7994,6 +8288,7 @@ def main():
         "creds": cmd_creds,
         "access": cmd_access,
         "enforce": cmd_enforce,
+        "override": cmd_override,
         "locks": cmd_locks,
         "oracle": cmd_oracle,
         "upgrade": cmd_upgrade,

{code_context_control-2.66.0 → code_context_control-2.70.0}/cli/commands/parser.py

@@ -472,6 +472,108 @@ def build_parser(version: str, parse_cli_ide_arg):
     lk_sweep = locks_subs.add_parser("sweep", help="Drop expired leases now")
     lk_sweep.add_argument("--path", dest="project_path", default=".")
 
+    # ── Override Requests (v2.69.0, docs/override-requests.md) ──────────
+    # Human-only approval surface. A grant is single-use, session-bound,
+    # path-exact and TTL-capped, and it never edits policy: the rule that
+    # denied the call is still in force the moment the grant is spent.
+    # There is no agent-facing path to any verb in this command.
+    p_override = subparsers.add_parser(
+        "override",
+        help="Override Requests — allow one blocked call once, without weakening the rule",
+    )
+    override_subs = p_override.add_subparsers(dest="override_cmd")
+
+    ov_policy = override_subs.add_parser(
+        "policy", help="Show the effective `override` policy and which layers are escalatable"
+    )
+    ov_policy.add_argument("--path", dest="project_path", default=".",
+                           help="Project directory (default: current)")
+
+    ov_grant = override_subs.add_parser(
+        "grant", help="Mint a single-use grant for one blocked call (human approval)"
+    )
+    ov_grant.add_argument("target", help="The exact path that was blocked")
+    ov_grant.add_argument("--session", dest="session_id", required=True,
+                          help="Claude Code session id the grant is bound to — a grant never crosses sessions")
+    ov_grant.add_argument("--op", choices=["read", "write"], default="read",
+                          help="Operation to allow (default: read)")
+    ov_grant.add_argument("--tool", default=None,
+                          help="Exact tool name (default: Read for --op read, Edit for --op write)")
+    ov_grant.add_argument("--layer", choices=["access", "discipline", "mask", "shell"],
+                          default=None,
+                          help="Force a layer. Default: derive it from the denial the path actually produces")
+    ov_grant.add_argument("--ttl", type=int, default=None, dest="ttl_s",
+                          help="Seconds until the grant expires (clamped to override.max_ttl_s, hard ceiling 900)")
+    ov_grant.add_argument("--uses", type=int, default=None,
+                          help="Uses allowed (default 1; >1 needs override.allow_session_grants)")
+    ov_grant.add_argument("--confirm", default=None,
+                          help="Required for deny/builtin rules: retype the rule glob by hand")
+    ov_grant.add_argument("--path", dest="project_path", default=".",
+                          help="Project directory (default: current)")
+
+    ov_list = override_subs.add_parser("list", help="Live grants for this project")
+    ov_list.add_argument("--session", dest="session_id", default="",
+                         help="Only grants bound to this session id")
+    ov_list.add_argument("--audit", type=int, default=0, metavar="N",
+                         help="Also print the last N lines of .c3/overrides.jsonl")
+    ov_list.add_argument("--path", dest="project_path", default=".",
+                         help="Project directory (default: current)")
+
+    ov_revoke = override_subs.add_parser("revoke", help="Drop a live grant before it is used")
+    ov_revoke.add_argument("grant_id", help="Grant id (grt_…)")
+    ov_revoke.add_argument("--path", dest="project_path", default=".",
+                           help="Project directory (default: current)")
+
+    ov_check = override_subs.add_parser(
+        "check", help="Would a grant cover this call right now? (never consumes one)"
+    )
+    ov_check.add_argument("target", help="Path to test")
+    ov_check.add_argument("--session", dest="session_id", required=True)
+    ov_check.add_argument("--op", choices=["read", "write"], default="read")
+    ov_check.add_argument("--tool", default=None)
+    ov_check.add_argument("--layer", choices=["access", "discipline", "mask", "shell"],
+                          default=None)
+    ov_check.add_argument("--path", dest="project_path", default=".",
+                          help="Project directory (default: current)")
+
+    ov_sweep = override_subs.add_parser("sweep", help="Drop expired / spent grants now")
+    ov_sweep.add_argument("--path", dest="project_path", default=".",
+                          help="Project directory (default: current)")
+
+    # Requests: what agents have ASKED for. Deciding is human-only and lives
+    # here (and, later, on the phone) — never on the c3_override agent tool.
+    ov_requests = override_subs.add_parser(
+        "requests", help="Override requests agents have asked for"
+    )
+    ov_requests.add_argument("--status", default="",
+                             help="pending | approved | denied | expired | withdrawn")
+    ov_requests.add_argument("--all", dest="all_projects", action="store_true",
+                             help="Every project, not just this one")
+    ov_requests.add_argument("--path", dest="project_path", default=".",
+                             help="Project directory (default: current)")
+
+    ov_approve = override_subs.add_parser(
+        "approve", help="Approve one request — mints a single-use grant"
+    )
+    ov_approve.add_argument("request_id", help="Request id (ovr_…)")
+    ov_approve.add_argument("--ttl", type=int, default=None, dest="ttl_s",
+                            help="Seconds until the grant expires (clamped to override.max_ttl_s)")
+    ov_approve.add_argument("--uses", type=int, default=None,
+                            help="Uses allowed (default 1)")
+    ov_approve.add_argument("--note", default="",
+                            help="Note recorded with the decision")
+    ov_approve.add_argument("--confirm", default=None,
+                            help="Required for deny/builtin rules: retype the rule glob by hand")
+    ov_approve.add_argument("--path", dest="project_path", default=".",
+                            help="Project directory (default: current)")
+
+    ov_deny = override_subs.add_parser("deny", help="Refuse one request")
+    ov_deny.add_argument("request_id", help="Request id (ovr_…)")
+    ov_deny.add_argument("--note", default="",
+                         help="Note the agent will see with the refusal")
+    ov_deny.add_argument("--path", dest="project_path", default=".",
+                         help="Project directory (default: current)")
+
     # ── Tool discipline / enforcement mode (v2.66.0) ────────────────────
     # LAYER C: how hard C3 pushes the agent toward c3_* tools. Distinct from
     # `c3 access` (path policy — a security boundary) and from