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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.71.0
+Version: 2.73.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.73.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.73.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

code_context_control-2.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.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.73.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-context-control"
-version = "2.71.0"
+version = "2.73.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.73.0}/services/override_policy.py

@@ -93,6 +93,11 @@ DEFAULTS = {
     "max_requests_per_hour": 20,
     "notify_severity": "critical",
     "allow_session_grants": False,
+    # The command run when a request is DECIDED, so the asking agent hears
+    # about it (services/override_wake.py). None = nobody is listening, which
+    # is the pre-2.73 behaviour and the reason a grant could expire unused
+    # while the user assumed their tap had done something.
+    "wake": None,
 }
 
 _VALID_KEYS = frozenset(DEFAULTS)
@@ -193,6 +198,7 @@ class OverridePolicy:
     max_requests_per_hour: int = 20
     notify_severity: str = "critical"
     allow_session_grants: bool = False
+    wake: dict | None = None
     warnings: tuple = ()
     corrupt_scopes: tuple = ()
 
@@ -221,6 +227,11 @@ class OverridePolicy:
             "max_requests_per_hour": self.max_requests_per_hour,
             "notify_severity": self.notify_severity,
             "allow_session_grants": self.allow_session_grants,
+            # The spec itself never crosses the wire. It is an argv the box
+            # will run, and it can carry a conversation id or a path that says
+            # more about this machine than a policy screen needs to. A phone
+            # only needs to know whether anything is listening.
+            "wake_configured": bool(self.wake),
             "warnings": list(self.warnings),
             "corrupt_scopes": list(self.corrupt_scopes),
         }
@@ -255,6 +266,18 @@ def _validate(section: dict):
             return _CORRUPT
         if any(not isinstance(v, bool) for v in layers.values()):
             return _CORRUPT
+    if "wake" in section:
+        # Lazy import: override_wake reads a resolved policy back out of this
+        # module on the fire path, and a module-level import would close that
+        # loop. A validator we cannot even load reads as corrupt, not as
+        # "probably fine" — this key names a command the machine will run.
+        try:
+            from services import override_wake as owake  # noqa: PLC0415
+            valid = owake.validate_spec(section["wake"])
+        except Exception:
+            return _CORRUPT
+        if not valid:
+            return _CORRUPT
     return section
 
 
@@ -350,6 +373,14 @@ def resolve(project_path: str = ".") -> OverridePolicy:
             if key in s:
                 values[key] = s[key]
 
+    # `wake` is not a permission, so it has no tightening direction to merge
+    # along — it is "who to tell", and the nearest scope is the one that knows.
+    # Project last, so a project's own wake replaces the machine-wide default
+    # rather than firing both.
+    for s in sections:
+        if "wake" in s:
+            values["wake"] = s["wake"]
+
     return OverridePolicy(warnings=tuple(warnings), **values)
 
 

{code_context_control-2.71.0 → code_context_control-2.73.0}/services/override_requests.py

@@ -460,6 +460,22 @@ def _notify_decision(project_path: str, row: dict, grant=None) -> None:
         pass  # the decision already happened; a missing feed line never undoes it
 
 
+def _wake(project_path: str, row: dict, grant=None, policy=None) -> dict:
+    """Tell the asking session a human answered (§7.1).
+
+    The notification feed tells the *user* what they decided. Nothing told the
+    *agent*, which is how an approved grant expired unused on 2026-08-08 with
+    everyone believing the tap had worked. Failure here is swallowed on
+    purpose: the decision is already on disk and the agent's ``action='status'``
+    path still works — a wake is a shortcut past waiting, not the mechanism.
+    """
+    try:
+        from services import override_wake as owake  # noqa: PLC0415
+        return owake.fire(project_path, row, grant, policy=policy)
+    except Exception as exc:
+        return {"fired": False, "reason": f"wake unavailable: {exc}"}
+
+
 def withdraw(request_id: str, session_id: str) -> dict:
     """An agent cancelling its OWN pending request (e.g. it found another way)."""
     rows = load()
@@ -526,6 +542,10 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
             "decided_by": decided_by, "muted": bool(mute),
         })
         _notify_decision(project_path, row, grant=None)
+        # A denial is news too: without it the agent sits in `wait` until the
+        # request lapses, then reports a timeout for a question that was
+        # answered in two seconds.
+        row["wake"] = _wake(project_path, row)
         return row
 
     policy = op_policy.resolve(project_path)
@@ -569,4 +589,8 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
     row["grant_mode"] = mode
     _save(rows)
     _notify_decision(project_path, row, grant=grant)
+    # AFTER _save: the woken agent's very first move is to retry the blocked
+    # call, which reads this store. Waking before persisting would race the
+    # agent against the decision it was told about.
+    row["wake"] = _wake(project_path, row, grant, policy=policy)
     return row