code-context-control 2.71.0__tar.gz → 2.74.0__tar.gz

{code_context_control-2.71.0/code_context_control.egg-info → code_context_control-2.74.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.71.0
+Version: 2.74.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.71.0 → code_context_control-2.74.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.71.0"
+__version__ = "2.74.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

code_context_control-2.74.0/cli/tools/_grants.py

@@ -0,0 +1,61 @@
+"""Override grants on the MCP content surface (override-requests.md P2a).
+
+The hooks have consulted grants since P1. The `c3_*` content tools have not:
+they called the evaluator and refused without ever asking whether the user
+had already approved this exact call. §13's coverage matrix recorded that as
+"not yet — P2a", which meant an approved request did nothing for any agent
+working through MCP — the grant was minted, and then no one looked at it.
+
+This module is the single place those tools ask. It is deliberately thin:
+all the policy ordering, TTL clamping, use accounting and audit lives in
+`services.override_grants.gate_access`, which is the same call the hooks
+make. Two implementations of "may I" is how the two surfaces drift apart.
+
+`session_id` lives here for the same reason. It was duplicated in edit.py,
+locks.py and override.py, each carrying a comment saying it must match the
+others exactly — and P2a makes that invariant load-bearing rather than
+merely tidy: a grant is minted under the session id `c3_override` computed
+and consumed under the one `c3_edit` computes. If those two ever disagree,
+every approval silently fails to apply.
+"""
+
+import os
+
+
+def session_id(svc) -> str:
+    """This agent's identity, for leases and for grants.
+
+    Falls back to the process id, never to "". Two agents that both resolved
+    to "" would count as ONE session and stop blocking each other — the exact
+    opposite of what a lock is for. Each Claude Code session runs its own
+    c3-mcp process, so the pid is a faithful stand-in.
+
+    It is also the right identity for c3_project: that proxy builds a runtime
+    for the TARGET project but runs inside the CALLER's process, so the pid
+    keeps the edit attributed to the agent that actually asked for it.
+    """
+    session = getattr(getattr(svc, "session_mgr", None), "current_session", None) or {}
+    return str(session.get("id", "") or "") or f"pid-{os.getpid()}"
+
+
+def allow(svc, denial, *, tool: str, op: str, path) -> str | None:
+    """The `[c3-override:granted]` line when a live grant permits this exact
+    call, or None to stay denied.
+
+    Consumes a use on success — so callers must invoke this only when they
+    are about to proceed, never speculatively. Ordering inside `gate_access`
+    is policy first, grants second, so a grant is void the instant the policy
+    or its layer is switched off (§12.8).
+
+    Fail-closed by construction: any error resolving the grant store leaves
+    the caller on its ordinary refusal path. A grant that cannot be read is
+    not a grant.
+    """
+    if denial is None:
+        return None
+    try:
+        from services import override_grants as og  # noqa: PLC0415 — lazy
+        return og.gate_access(svc.project_path, denial, tool=tool, op=op,
+                              path=str(path), session_id=session_id(svc))
+    except Exception:
+        return None

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/compress.py

@@ -8,6 +8,7 @@ import sys
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
+from cli.tools import _grants
 from cli.tools._helpers import finalize_with_tokens, show_token_ratios
 from core import count_tokens
 from services import access_guard
@@ -118,7 +119,9 @@ def _compress_single(file_path: str, mode: str, svc, finalize, maybe_facts) -> s
     # Access Guard: read verdict up front — covers the map/dense_map paths
     # that never reach compressor.compress_file (docs/access-guard.md §3).
     _verdict = access_guard.verdict(file_path, "read", svc.project_path)
-    if _verdict.denial:
+    if _verdict.denial and not _grants.allow(svc, _verdict.denial,
+                                             tool="c3_compress", op="read",
+                                             path=file_path):
         return finalize("c3_compress", {"file_path": file_path, "mode": mode},
                         access_guard.refusal(_verdict.denial, file_path, "read"),
                         "access-denied")

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/edit.py

@@ -22,25 +22,22 @@ import threading
 from contextlib import contextmanager
 from pathlib import Path
 
+from cli.tools import _grants
 from services import access_guard, agent_locks
 from services import credential_store as _cs
 from services.task_store import _FileLock
 
 
 def _session_id(svc) -> str:
-    """This agent's lease identity.
+    """This agent's lease identity — see `cli.tools._grants.session_id`.
 
-    Falls back to the process id, never to "". Two agents that both resolved
-    to "" would count as ONE session and stop blocking each other — the exact
-    opposite of what a lock is for. Each Claude Code session runs its own
-    c3-mcp process, so the pid is a faithful stand-in.
-
-    It is also the right identity for c3_project: that proxy builds a runtime
-    for the TARGET project but runs inside the CALLER's process, so the pid
-    keeps the edit attributed to the agent that actually asked for it.
+    Was defined here and copied into locks.py and override.py, each with a
+    comment saying it had to match. P2a makes that invariant load-bearing:
+    a grant is minted under the id c3_override computes and consumed under
+    the one c3_edit computes, so a divergence would make every approval
+    silently fail to apply. One definition, three callers.
     """
-    session = getattr(getattr(svc, "session_mgr", None), "current_session", None) or {}
-    return str(session.get("id", "") or "") or f"pid-{os.getpid()}"
+    return _grants.session_id(svc)
 
 # ── Same-file serialization ───────────────────────────────────────────────
 # In-process locks, keyed by resolved absolute path string.
@@ -325,7 +322,8 @@ def handle_edit(file_path: str, old_string: str, new_string: str,
     # (never replaces) any dedicated vault-file guard.
     op = "write" if path.exists() else "create"
     denial = access_guard.check(str(path), op, svc.project_path)
-    if denial:
+    if denial and not _grants.allow(svc, denial, tool="c3_edit", op=op,
+                                    path=str(path)):
         return finalize("c3_edit", {"file": file_path},
                         access_guard.refusal(denial, file_path, op),
                         "access-denied")

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/filter.py

@@ -10,6 +10,7 @@ import json
 import re
 from pathlib import Path
 
+from cli.tools import _grants
 from cli.tools._helpers import finalize_with_tokens, show_token_ratios
 from core import count_tokens
 from services import access_guard
@@ -31,7 +32,9 @@ def handle_filter(file_path: str, text: str, pattern: str, max_lines: int,
     # Access Guard: read verdict (docs/access-guard.md §3), checked before
     # existence so probes can't distinguish missing from denied (R2).
     denial = access_guard.check(file_path, "read", svc.project_path)
-    if denial:
+    _granted = _grants.allow(svc, denial, tool="c3_filter", op="read",
+                             path=file_path) if denial else None
+    if denial and not _granted:
         return finalize("c3_filter", {"file": file_path},
                         access_guard.refusal(denial, file_path, "read"),
                         "access-denied")

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/impact.py

@@ -9,6 +9,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from cli.tools import _grants
 from services import access_guard
 
 _SKIP_DIRS = frozenset({
@@ -115,7 +116,8 @@ def handle_impact(target: str, file_path: str, mode: str, svc, finalize) -> str:
     # Access Guard: refuse outright when the named source file is read-denied.
     if file_path:
         denial = access_guard.check(file_path, "read", str(project))
-        if denial:
+        if denial and not _grants.allow(svc, denial, tool="c3_impact",
+                                        op="read", path=file_path):
             return finalize("c3_impact", {"target": target, "mode": mode},
                             access_guard.refusal(denial, file_path, "read"),
                             "access-denied")

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/locks.py

@@ -12,17 +12,14 @@ and letting go early instead of waiting out the TTL.
 force_release is deliberately absent: it is a human override that bumps the
 fencing counter, and it lives in `c3 locks force-release` / the Hub tab.
 """
-import os
-
+from cli.tools import _grants
 from services import agent_locks as al
 
 
 def _session_id(svc) -> str:
-    """Must match cli/tools/edit.py._session_id exactly — a lease taken by
-    c3_edit has to be recognised as ours by c3_locks, and vice versa. Never ""
-    (see the note there: two anonymous agents would stop blocking each other)."""
-    session = getattr(getattr(svc, "session_mgr", None), "current_session", None) or {}
-    return str(session.get("id", "") or "") or f"pid-{os.getpid()}"
+    """A lease taken by c3_edit has to be recognised as ours by c3_locks, and
+    vice versa — so both read the one definition in `_grants`."""
+    return _grants.session_id(svc)
 
 
 def _split(paths: str) -> list:

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/override.py

@@ -12,9 +12,9 @@ Layers that can never be escalated (the credential vault, Tier-0 denies, the
 dispatcher fail-closed deny, catastrophic shell blocks) are refused at
 creation with `[c3-override:not-escalatable]` and never reach a human.
 """
-import os
 import time
 
+from cli.tools import _grants
 from services import access_guard as ag
 from services import override_policy as opol
 from services import override_requests as orq
@@ -28,9 +28,8 @@ _DEFAULT_TOOL = {"read": "Read", "write": "Edit"}
 
 
 def _session_id(svc) -> str:
-    """Must match cli/tools/edit.py._session_id — the grant is bound to it."""
-    session = getattr(getattr(svc, "session_mgr", None), "current_session", None) or {}
-    return str(session.get("id", "") or "") or f"pid-{os.getpid()}"
+    """The identity the grant is bound to — one definition, in `_grants`."""
+    return _grants.session_id(svc)
 
 
 def _fmt(row: dict) -> str:

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/read.py

@@ -6,6 +6,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 from typing import Any
 
+from cli.tools import _grants
 from cli.tools._helpers import finalize_with_tokens, maybe_related_facts
 from core import count_tokens
 from services import access_guard
@@ -123,8 +124,14 @@ def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
     # before existence so probes get the same refusal whether or not the
     # target exists (R2). Batch members hit this via the per-file dispatch,
     # so allowed members are served and denied ones carry the S1 line inline.
+    # A live grant (P2a) is consulted only on the DENIAL branch. The masked
+    # branch below is untouched on purpose: a mask is not a refusal to be
+    # lifted, it is a different view being served, and "approve once" has no
+    # meaning for it. Widening that is a separate decision, not a side effect.
     _verdict = access_guard.verdict(file_path, "read", svc.project_path)
-    if _verdict.denial:
+    if _verdict.denial and not _grants.allow(svc, _verdict.denial,
+                                             tool="c3_read", op="read",
+                                             path=file_path):
         resp = access_guard.refusal(_verdict.denial, file_path, "read")
         if finalize is None:
             return resp

{code_context_control-2.71.0 → code_context_control-2.74.0}/cli/tools/validate.py

@@ -8,6 +8,7 @@ import subprocess
 import sys
 from pathlib import Path
 
+from cli.tools import _grants
 from services import access_guard
 
 
@@ -169,7 +170,8 @@ async def _validate_one(file_path: str, svc) -> tuple:
     # Access Guard: read verdict (docs/access-guard.md §3) — the S1 refusal
     # becomes the batch line for this member; other members are still served.
     denial = access_guard.check(file_path, "read", svc.project_path)
-    if denial:
+    if denial and not _grants.allow(svc, denial, tool="c3_validate",
+                                    op="read", path=file_path):
         return ("SKIP", access_guard.refusal(denial, file_path, "read"))
     full = Path(svc.project_path) / file_path
     if not full.exists():
@@ -250,7 +252,8 @@ async def _validate_single(file_path: str, svc, finalize) -> str:
     """Original single-file validation path."""
     # Access Guard: read verdict, checked before existence (R2 probe parity).
     denial = access_guard.check(file_path, "read", svc.project_path)
-    if denial:
+    if denial and not _grants.allow(svc, denial, tool="c3_validate",
+                                    op="read", path=file_path):
         return finalize("c3_validate", {"file_path": file_path},
                         access_guard.refusal(denial, file_path, "read"),
                         "access-denied")

{code_context_control-2.71.0 → code_context_control-2.74.0/code_context_control.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.71.0
+Version: 2.74.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.71.0 → code_context_control-2.74.0}/code_context_control.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ cli/hub_ui/components/task_board.js
 cli/hub_ui/components/toasts.js
 cli/hub_ui/components/topbar.js
 cli/tools/__init__.py
+cli/tools/_grants.py
 cli/tools/_helpers.py
 cli/tools/agent.py
 cli/tools/artifacts.py
@@ -222,6 +223,7 @@ services/output_filter.py
 services/override_grants.py
 services/override_policy.py
 services/override_requests.py
+services/override_wake.py
 services/parser.py
 services/project_manager.py
 services/project_runtime.py
@@ -352,7 +354,9 @@ tests/test_oracle_subproject_awareness.py
 tests/test_oracle_ui_bundle.py
 tests/test_output_filter.py
 tests/test_override_grants.py
+tests/test_override_grants_mcp.py
 tests/test_override_requests.py
+tests/test_override_wake.py
 tests/test_permissions.py
 tests/test_pm_api.py
 tests/test_project_manager.py

{code_context_control-2.71.0 → code_context_control-2.74.0}/oracle/services/mobile_api.py

@@ -46,6 +46,7 @@ import hashlib
 import json
 import os
 import threading
+import time
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -58,10 +59,13 @@ from oracle.services.tool_registry import _c3_version
 
 # 2: /info reports EFFECTIVE capabilities (filtered by the config switches)
 # rather than a static list, so a client can gate its UI instead of probing.
-API_VERSION = 2
+# 3: /feed accepts `wait` (long-poll). Advertised as the `feed_wait`
+#    capability so a client can choose to hold a connection open instead of
+#    polling, rather than discovering support by timing a request.
+API_VERSION = 3
 
 CAPABILITIES = [
-    "feed", "projects", "health", "pm", "pm_events", "digest",
+    "feed", "feed_wait", "projects", "health", "pm", "pm_events", "digest",
     "notifications_ack",
     "credentials", "credentials_write",
     "access", "access_write",
@@ -90,6 +94,38 @@ _SOURCE_CAP = 1000
 _MAX_LIMIT = 200
 _DEFAULT_LIMIT = 50
 
+# ── Long-poll (`/feed?wait=`) ─────────────────────────────
+#
+# WHY: the phone's only delivery paths were two pollers — every 15s while the
+# app is open, and Android WorkManager's ~15-MINUTE floor once it is closed.
+# An override request with a 10-minute TTL could therefore expire before the
+# phone was ever told it existed (observed 2026-08-07). `wait` lets a client
+# hold one request open and be answered the moment something lands, turning
+# "up to 15 seconds" into "about a second" without spending a request every
+# 15s to get it.
+#
+# It is NOT push, and nothing here should be read as a claim that it is: a
+# process Android has frozen cannot hold a socket. This narrows the live
+# window. FCM or a foreground service is what would close the closed-app one.
+_MAX_WAIT_S = 30
+# Re-scan cadence while holding. The scan is skipped unless an mtime moved,
+# so this is a stat() per second, not a feed rebuild per second.
+_WAIT_TICK_S = 1.0
+# Each waiter parks a server thread for up to _MAX_WAIT_S, and the Oracle
+# serves the desktop UI and discovery off the same pool. Past the cap `wait`
+# degrades to an ordinary immediate answer rather than queueing behind other
+# waiters. One phone needs one slot; four leaves room for the watch and a
+# spare.
+_MAX_WAITERS = 4
+_waiters = threading.Semaphore(_MAX_WAITERS)
+
+#: Files whose mtime means "the feed may have changed" — the same set
+#: ``_last_activity`` reports on, kept literal in both places on purpose. Here
+#: it is a correctness input: a file missing from this tuple is a wake that
+#: never returns early.
+_FEED_FILES = ("activity_log.jsonl", "edit_ledger.jsonl",
+               "notifications.jsonl", "pm/pm.json")
+
 bp = Blueprint("mobile", __name__, url_prefix="/api/mobile")
 
 # Wired by oracle_server at import time (configure) and startup (init_services).
@@ -489,6 +525,54 @@ def _feed_items_for(path: str, name: str, types: set, severities: set,
     return items
 
 
+def _feed_mtime(targets: list) -> float:
+    """Newest mtime across every target's feed files. 0.0 when none exist."""
+    latest = 0.0
+    for t in targets:
+        c3 = Path(t["path"]) / ".c3"
+        for rel in _FEED_FILES:
+            try:
+                latest = max(latest, (c3 / rel).stat().st_mtime)
+            except OSError:
+                continue
+    return latest
+
+
+def _hold_for_items(targets: list, collect, wait_s: int):
+    """Block up to *wait_s* for the feed to produce something.
+
+    Returns ``(items, waited_seconds)``. Rebuilding the feed every tick would
+    be a full history read per target, so the loop watches mtimes and only
+    pays for a rebuild when one moves. An mtime that moves without producing a
+    matching item — a severity this client filters out, say — re-baselines
+    instead of re-scanning on every subsequent tick.
+
+    Returns immediately when every waiter slot is taken. The caller then
+    behaves exactly as if ``wait`` had not been passed: a slower client, not a
+    wrong one.
+    """
+    started = time.monotonic()
+    if not _waiters.acquire(blocking=False):
+        return [], 0.0
+    try:
+        seen = _feed_mtime(targets)
+        deadline = started + wait_s
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return [], time.monotonic() - started
+            time.sleep(min(_WAIT_TICK_S, remaining))
+            current = _feed_mtime(targets)
+            if current == seen:
+                continue
+            seen = current
+            found = collect()
+            if found:
+                return found, time.monotonic() - started
+    finally:
+        _waiters.release()
+
+
 @bp.route("/feed")
 def mobile_feed():
     """Merged cross-project feed, newest first.
@@ -496,11 +580,14 @@ def mobile_feed():
     Query: types (csv of notification|activity|edit|session_stat, default
     all), project (optional single project), severity (csv, notifications
     only), since (exclusive watermark — "only newer than"), before
-    (exclusive pagination cursor), limit (default 50, max 200).
+    (exclusive pagination cursor), limit (default 50, max 200), wait
+    (seconds, 0-30 — hold the request open until something matches).
 
     Response: {items, next_cursor, truncated}. Cursor is the ts of the last
     returned item; identical-ts items can repeat across pages, so clients
-    dedup by item id.
+    dedup by item id. A `wait` request also carries `waited_s`, and an empty
+    `items` after a full hold is the normal, expected answer — the client
+    reconnects with the same watermark.
     """
     if _scanner is None:
         return jsonify({"error": "not initialized"}), 500
@@ -523,6 +610,18 @@ def mobile_feed():
     except (TypeError, ValueError):
         limit = _DEFAULT_LIMIT
 
+    try:
+        wait_s = max(0, min(_MAX_WAIT_S, int(request.args.get("wait", 0))))
+    except (TypeError, ValueError):
+        wait_s = 0
+    # Holding open only makes sense against a watermark. Without `since` the
+    # first scan matches history and returns instantly, so a client that
+    # forgot it would silently get the old behaviour and never learn why its
+    # push felt slow; with `before` this is a pagination cursor, where waiting
+    # is meaningless.
+    if before or not since:
+        wait_s = 0
+
     project_arg = (request.args.get("project") or "").strip()
     if project_arg:
         resolved, err = _project_or_404(project_arg)
@@ -536,10 +635,17 @@ def mobile_feed():
                    if p.get("has_c3") and p.get("path")
                    and (Path(p["path"]) / ".c3").is_dir()]
 
-    items: list[dict] = []
-    for t in targets:
-        items.extend(_feed_items_for(t["path"], t["name"], types, severities,
-                                     since, before))
+    def collect() -> list:
+        out: list[dict] = []
+        for t in targets:
+            out.extend(_feed_items_for(t["path"], t["name"], types,
+                                       severities, since, before))
+        return out
+
+    items = collect()
+    waited = 0.0
+    if not items and wait_s:
+        items, waited = _hold_for_items(targets, collect, wait_s)
 
     items.sort(key=lambda i: i["ts"], reverse=True)
     truncated = len(items) > limit
@@ -548,6 +654,9 @@ def mobile_feed():
         "items": page,
         "next_cursor": page[-1]["ts"] if truncated and page else None,
         "truncated": truncated,
+        # Only when the client asked to hold, so the response shape is
+        # byte-identical for every client that did not.
+        **({"waited_s": round(waited, 2)} if wait_s else {}),
     })
 
 
@@ -1634,6 +1743,10 @@ def mobile_enforcement_set():
 # (e.g. `path_key`) cannot silently start crossing the network.
 
 #: §3.3 field order, verbatim. The mobile client reads these names.
+#: The one `override` key no remote surface may write. See the refusal in
+#: `mobile_overrides_policy_set` for why it is a 403 rather than a 400.
+_WAKE_KEY = "wake"
+
 _OVERRIDE_FIELDS = (
     "id", "project_path", "session_id", "created_at", "expires_at", "status",
     "layer", "rule", "rule_class", "scope", "tool", "op", "path", "refusal",
@@ -1809,6 +1922,17 @@ def mobile_overrides_policy_set():
     section = data.get("override")
     if not isinstance(section, dict):
         return jsonify({"error": "body needs an 'override' object"}), 400
+    if _WAKE_KEY in section:
+        # `wake` is an argv this machine will execute. Everything else on this
+        # route widens what a tap can approve; this one would decide what runs
+        # when it does. A bearer token from a phone is authentication, not
+        # physical presence, so it stays a desktop edit to a human-owned file.
+        return jsonify({
+            "error": "'wake' cannot be set from the phone — it names a "
+                     "command this machine runs. Edit .c3/config.json on the "
+                     "desktop.",
+            "key": _WAKE_KEY,
+        }), 403
     unknown = sorted(set(section) - set(opol.DEFAULTS))
     if unknown:
         # §3.1: unknown keys are a hard error, never a silent no-op.

{code_context_control-2.71.0 → code_context_control-2.74.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.71.0"
+version = "2.74.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.71.0 → code_context_control-2.74.0}/services/access_guard.py

@@ -709,11 +709,12 @@ def _override_offer(denial: Denial, path, operation: str, tool: str) -> str:
     that can never be escalated: an agent must not learn from a refusal that
     a request surface exists for the credential vault (§6).
 
-    Restricted to the hook surface on purpose. The offer promises that a human
-    'yes' makes the retry work, and today only the PreToolUse gates consult
-    grants — the ``c3_*`` content surfaces do not (see §13, phase P2a). An
-    offer on a surface that would still refuse after approval is worse than
-    no offer.
+    Restricted to the hook surface on purpose — see ``refusal``. The rule was
+    written when only the PreToolUse gates consulted grants; P2a taught the
+    ``c3_*`` content surfaces to consult them too, so extending the offer to
+    the MCP surface is now defensible. It is deliberately NOT done here: that
+    is a separate, wider change (every c3_* refusal grows a line) and belongs
+    in its own review, not smuggled in beside a fix for the branch ordering.
     """
     try:
         from services import override_policy as _op  # noqa: PLC0415 — cycle
@@ -738,7 +739,26 @@ def refusal(denial: Denial, path, operation: str, *, surface: str = "mcp",
     the agent it may ASK (docs/override-requests.md §6). The pinned strings
     above are unchanged: the append is absent unless the project opted in,
     which is off by default.
+
+    The append happens HERE, once, for every kind — not inside a branch. It
+    used to live at the tail of the deny branch, which sits below the mask and
+    read-only early returns, so those two kinds could never carry an offer on
+    any surface even though `rule_class_for_denial` marks both escalatable.
+    `access_readonly` was the only layer anyone had turned on, so in practice
+    the invitation half of Override Requests had never fired once.
     """
+    body = _refusal_body(denial, path, operation, surface=surface,
+                         tool=tool, project=project)
+    # Hook only, still: the offer promises that a 'yes' makes the retry work,
+    # and the proxy surface answers for a DIFFERENT project's policy.
+    if surface == "hook":
+        return body + _override_offer(denial, path, operation, tool)
+    return body
+
+
+def _refusal_body(denial: Denial, path, operation: str, *, surface: str,
+                  tool: str, project: str) -> str:
+    """The pinned string itself, with no override append."""
     p, glob, scope = _cap(path), denial.rule, denial.scope
     if denial.kind == _KIND_MASK:
         if operation in ("write", "create", "delete"):
@@ -762,12 +782,20 @@ def refusal(denial: Denial, path, operation: str, *, surface: str = "mcp",
             "`c3 access list` or the Access tab."
         )
     if denial.kind == _KIND_READ_ONLY:
+        # `{operation}`, not a hardcoded "write". A read-only rule blocks the
+        # whole write class, and for a file that does not exist yet the tools
+        # call that operation `create`. Saying "write" told the agent to ask
+        # the user to approve `op='write'`, the approval was minted for
+        # `write`, and the grant matcher — which compares op exactly — then
+        # refused the `create` the tool actually attempted. A real approval
+        # was spent and silently discarded (§4 near_miss).
         return (
-            f"{TAG_READ_ONLY} write denied for {p} by Access Guard rule "
+            f"{TAG_READ_ONLY} {operation} denied for {p} by Access Guard rule "
             f"'{glob}' ({scope} scope). The effective policy is read-only; "
-            "reads are evaluated separately. Do not retry the write. Mark "
-            "the affected step blocked and continue with unaffected files; "
-            "report the skip. Rules: `c3 access list` or the Access tab."
+            f"reads are evaluated separately. Do not retry the {operation}. "
+            "Mark the affected step blocked and continue with unaffected "
+            "files; report the skip. Rules: `c3 access list` or the Access "
+            "tab."
         )
     if surface == "hook":
         return (
@@ -776,7 +804,7 @@ def refusal(denial: Denial, path, operation: str, *, surface: str = "mcp",
             "decision, not a transient error — do not retry through another "
             "tool or the shell. Mark the affected step blocked and continue "
             "with unaffected files. Rules: `c3 access list`."
-        ) + _override_offer(denial, path, operation, tool)
+        )
     if surface == "proxy":
         return (
             f"{TAG_DENIED} {operation} denied for {p} through project "