code-context-control 2.71.0__py3-none-any.whl → 2.74.0__py3-none-any.whl

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):

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

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")

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")

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")

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")

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:

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:

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

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.dist-info → code_context_control-2.74.0.dist-info}/METADATA

@@ -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.dist-info → code_context_control-2.74.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 cli/__init__.py,sha256=ec66drCZGNMRU4V6ov0zVhYZph1us12Vn8OvG_LJyRY,22
 cli/_hook_utils.py,sha256=03fDyLvfzF832M7L5B2DgR8KMWXIObpbYxSC3LbhQ04,17229
-cli/c3.py,sha256=Jk3Gb08tbxOLGNOyuKQswhXy3ByZEiTpXjKPYcpY8hc,368519
+cli/c3.py,sha256=esat1rA74wsB9dcct0pWbx1oHarGXQwB4xLzj0sqk2E,368519
 cli/docs.html,sha256=bNymSz7LatnWHjxSXL92QSUtGvB3jBzNHbOV-bRpAOo,142507
 cli/edits.html,sha256=UjAhoCmBmQ89cklGvJqzC6eyNP2tc8H6T-e01DVkLvE,43418
 cli/hook_access_guard.py,sha256=VOW6AJlSiBYg3H_O_EwRrjk8ynF1IqWCcrHrS443Noc,7256
@@ -66,30 +66,31 @@ cli/hub_ui/components/task_board.js,sha256=QiWKmj1NkhkloGlfzZj_tWd7Sgz3xSxwVLp8I
 cli/hub_ui/components/toasts.js,sha256=caj_x3npcM_wMv9E_xEde88jyfXI-jt8RrDQW_yXz5k,3376
 cli/hub_ui/components/topbar.js,sha256=UKzIBCkJ6j4tiBDClL5-D9ScXNEoTs2K6wO9tXy5qkY,4449
 cli/tools/__init__.py,sha256=HO6eVKzDm1KPqsKTHY6lfIsnFnv3C7Bd9o3Q_V88idg,127
+cli/tools/_grants.py,sha256=6fnVm2blQ60j_0jIJFvDTtnXOdrlOy2zc39_s5VA-LY,2899
 cli/tools/_helpers.py,sha256=Yo_ol8bFT2R5ayjT54pXLVZhW_PgpBVoM8I7pDoomCI,7823
 cli/tools/agent.py,sha256=Fp9XLrOqjSP7_Ihq7VXjYXcGoXjw17-Hx3JMvoOVnhc,48105
 cli/tools/artifacts.py,sha256=LkSdjRz1TuYSFD1H_GSsxvhXOogaMt_JMbOnmkLOSUU,7784
 cli/tools/bitbucket.py,sha256=_hgORCW9-IF5xZJaznoONVfaTGKaX8VcU7ALrBeLhWo,27518
-cli/tools/compress.py,sha256=3mLrjYINhBJstkNFjEC3TV1Uif6IKSMycoGPb8VN59s,12670
+cli/tools/compress.py,sha256=IW2I2duAwj1Z2NPG7znX6rDcG3f83r5RvCVpR0yinmY,12881
 cli/tools/credentials.py,sha256=nUsunY09zXYAX-D5oEPD6B2WaWicMLJDNjjxbdce4gE,10566
 cli/tools/delegate.py,sha256=KXy4wZhex9HKixj9HVNIGKsHJHJwiPi6LAP3GRkZoxs,59469
-cli/tools/edit.py,sha256=BqFe9konRKHUp1NUAZiBRyNVm4nGf5vsP2jaF5M5I7Q,26972
+cli/tools/edit.py,sha256=90tC_UOvxETVRItxlEkOnL6gBW0D6X-qzkSGeLKfiOM,26874
 cli/tools/edits.py,sha256=8zM01TzLmjm7ULQlCmXOmitlJd84zQHVzE0z7UHJUdA,5520
 cli/tools/federate.py,sha256=wmC2QN7A6aay3cT7U9LDPYRCZKL1m_T6qFdZzpZmPx4,4650
-cli/tools/filter.py,sha256=99LNCzyky-JE9c9o-MixiQJSlWQMO7mWNERWmJgAVgI,12519
-cli/tools/impact.py,sha256=Nm9Zhee3ufhp6Wq1sRJ3iIn6hartlY4Qey0ds4Ag7iY,7048
+cli/tools/filter.py,sha256=mwNabPe7bCvdsIGFsWc4E1HsfiRYx5ZevnxdsitJTAw,12702
+cli/tools/impact.py,sha256=J6dvMrma1E2jGlhi3dIeQXhdwya5xljrJ92eiRuDaIE,7198
 cli/tools/jira.py,sha256=q85VyzzH_gFsAZaszf-exIAlMZVyJ1q-no8mhIMUn9E,17951
-cli/tools/locks.py,sha256=krhuTmJFFjspIF8ESHwLTRS3sp_WzglvOPFajslySpw,6076
+cli/tools/locks.py,sha256=FvuNxToU-5ZE2m_C6fTrn1jKERoxR4cbtxNb_b8mXqA,5882
 cli/tools/memory.py,sha256=yDDRsEngeFcjb6nXUrhRZXuboasXfixJeyltKhDbZD4,24935
-cli/tools/override.py,sha256=TctImNJfHRqjyAFDLXpi-RbyznYFnvHCKAinjyCFYus,7980
+cli/tools/override.py,sha256=2H0HO8tTN78LE-kklhc5KocNplqDcQbnyRLZAkntUbk,7877
 cli/tools/project.py,sha256=OT2SwzdcQ7Uqc5DHoHZfxcvLGD9K3wQ2dG9uly5cAHw,20406
-cli/tools/read.py,sha256=bCv29i3bYOMfmoiQ-Ahpn8rerigDDNfd_An_p5ItlIU,15578
+cli/tools/read.py,sha256=sqTzn6FDaTQ3TFyP3J8fg61WemOsH-2oLIt19hmZXlI,16091
 cli/tools/search.py,sha256=cW0h5_yK7b1s3aqFKk3Z7nz4GSDhuJYDHdSXUH9uli0,17091
 cli/tools/session.py,sha256=ailQiRqXhi9NcBB3XS3Dv72GEkEZaYivB0bqDlhmgTA,5202
 cli/tools/shell.py,sha256=ZjBN_iID6oGSzjaZ19IAlFik4DP8M0JkD3nh4r0pRdE,26283
 cli/tools/status.py,sha256=TRbiHVaDcrH96m5p1dMtbBlwGxTax3DcUih4dLs9CEw,16158
 cli/tools/tasks.py,sha256=kS0K73c6D5aaKGtarGI8XAYUjzPWBmIQqlsGGg5meJ4,20697
-cli/tools/validate.py,sha256=jQc1aUkgY9_rb2uGl8UY1V_5w9xqmTAjfk11qAuWbwY,13581
+cli/tools/validate.py,sha256=Y7-jMfelMeENJ3GExvC0qshfFmD6PE3aTfOJg8V_qtg,13847
 cli/ui/api.js,sha256=wSviW2AgkSUwLjjQCcgsLHuRYhE56Mkcr2q2xHNq08s,1815
 cli/ui/app.js,sha256=8QwyCxT_6nNqiFibKESA9vgW_s2bVWWKeHU4fFm-Szg,10169
 cli/ui/icons.js,sha256=VT5VVCQtWh_YTxCvf64YBgiwx3vRBBXkEALx8N10dwg,5224
@@ -110,7 +111,7 @@ cli/ui/components/sessions.js,sha256=FIKtil76B8tCkAmcFV7hlj6GQ_DCJK2jCzvEmdK7NBE
 cli/ui/components/settings.js,sha256=ATbAjBlVIwCNpxq7s191b49a_INQV38iwmySqtJLYwY,79066
 cli/ui/components/sidebar.js,sha256=K2ym2kUgpbyG-EBA_wBIIiqQY8qTatsiBZwzseMWuIQ,9939
 cli/ui/components/tasks.js,sha256=vyKQ3uwoppMwvdEaHlhWXW4oWcAisx4NveqzMhsYqHo,38438
-code_context_control-2.71.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.74.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
 core/__init__.py,sha256=TSDCEcM4V7gcZVM3w2ykJaqEUch4Dkon-rivV17T73s,2501
 core/config.py,sha256=YmkcZwedz_lfDM0ZuI_f4xpe98ixPLcSQFcTCHgRiRg,19206
 core/ide.py,sha256=V6VVMVsFdmmcsMyxikjQp7z9xa42CWiHKS-ya-MAcG4,6172
@@ -135,7 +136,7 @@ oracle/services/insight_engine.py,sha256=lwcdXtjt3CSZLqHVpXx6SG5gDhZYUKwXt4Z8dGy
 oracle/services/local_session.py,sha256=51iKUPTM2C4kuk-rnHpjvuc688ofD6AzjTMrd_RYw6E,5263
 oracle/services/memory_reader.py,sha256=rSEmoIXQu2JkolHJIQWpn0piPJpyuf1KZvW_9liQwkU,3727
 oracle/services/memory_writer.py,sha256=hpvYsxjhl293jEjGcRKfjG5njUaAOXKqbmJaUu1WdUU,6997
-oracle/services/mobile_api.py,sha256=69oQlEaJD1lI7es6GytK1AVKnxiyjOFL5J1lCzb-FRU,86109
+oracle/services/mobile_api.py,sha256=9gyDvJ7vKZ1nVb2k8AbjcquIfmPXzPT1lGkWkFG0OdQ,91712
 oracle/services/project_scanner.py,sha256=gHpXihRZSu2gXCp4vvOWp5gMAsmfINE9ESiqVF1uV3A,5587
 oracle/services/review_agent.py,sha256=m_fzoHowpiibf0_iz3dF72LWSrwB_FbDd1am-SbeWXg,11273
 oracle/services/tool_executor.py,sha256=xtAkBWkclh_FwOgzprjGkyRIV8-A7Lc3bz0UFPShrv0,1113
@@ -160,7 +161,7 @@ oracle/ui/chat/send.js,sha256=k2qGN_asb7FTjcLa204Zjq4X_QWHIKHQnI33IEuxvaQ,11558
 oracle/ui/chat/stream_renderer.js,sha256=RZndI2mu5xbzZF-4NG9jeOqXTcmIqfZqxgkrBvTzWmk,29861
 oracle/ui/chat/toolbar.js,sha256=ZDexIIpGwsQ6XsY4Tyo082rJoofdD_JBTV97-mLQUVM,12027
 services/__init__.py,sha256=3Kn4cZweLm7at8wFdBdZ-Zwo8hHcnVIsmY5f29nzi2Y,116
-services/access_guard.py,sha256=sMm3Y7fBtGOadYAYdGJXaxHlsAxR7kRGO5iGIK4rKZk,51281
+services/access_guard.py,sha256=RKvbW12aRLUwkPPssxmLWpSk7_z4DDeB8S7g1BNg2hc,52947
 services/access_telemetry.py,sha256=9pOCLS9LgDtM7Z4cCEyl7osxhj-m3wsPubcXolBKuV4,9568
 services/activity_log.py,sha256=PNGeEYlw1Aux-mRU4pKCQdbsSuzLvOg7MYiq-cb4n8g,4473
 services/agent_base.py,sha256=a-gdSd_jtZtbjXo1WS8CnWCagXgKaGZd5ShcG6s0kT4,4809
@@ -206,14 +207,15 @@ services/memory_grounder.py,sha256=vM7_n_Ezkkc3oGQ1MECUT9Bpt2K1fsNx2kWiumAW6Qc,1
 services/memory_queue.py,sha256=sSFh2oU_BLbv90jXhPbRWNIS2nlUi468-INw96GFIwU,3852
 services/memory_scorer.py,sha256=32wccyVFBgcNwKdjwj_7RDnPukxSWBng8ohsRPTpQMM,9497
 services/metrics.py,sha256=X4D5TgcQSFaFLbBoa1s3bAWf00DMMjq3IrOACrK-uDg,3289
-services/notifications.py,sha256=-yriAkWmISBRZY1JZznYyYl2FZnMeMlh9564faH99Dk,14281
+services/notifications.py,sha256=DwwE07-BI5-9s7G00onsiIyy0XHjppDFjWZ0SESoftQ,15508
 services/ollama_bridge.py,sha256=16ukWS98H4wFulOphUJDuXhN61GCiay793XLoyxTU-s,17455
 services/ollama_client.py,sha256=UiC5Abca622-ac-4goCkAjwo7iUye9g9JGFMN6Ea08M,7983
 services/ollama_credentials.py,sha256=EQx0YljYRrRBJ2voALlVTv11UBjfw-A6N7k7EP7fUFE,2770
 services/output_filter.py,sha256=lknQHs38JlRtXU4Ogoru6sveNokSKBQPfZXhf-fE0xM,21736
 services/override_grants.py,sha256=ZONuzlzjJ1iljfphX27RmPKLjibxoSARQcAAjRxVUJE,20203
-services/override_policy.py,sha256=bDXxCf7miDmsl0AGAh1xBopiS1CAgE5352aCKJIUc4w,14714
-services/override_requests.py,sha256=m1GKapR-f6qTJaBhvNxDzq-W_XRxedC1-PXAoQpeob8,23490
+services/override_policy.py,sha256=fbOCgNTidNy4LuALATWHp2LcAr1KllPXm2e5pEwSOE4,16326
+services/override_requests.py,sha256=HttGRNf9DdrhhR5coORu5q8lMbmEABPqbOMyhCfe4Po,25106
+services/override_wake.py,sha256=HjSOXQTDi0irgeMyrTqngL7xLcSOOIgYsVW9yxod4ps,10363
 services/parser.py,sha256=CPoIN1FmX7kK-55FnC3jvRy3NLjlnf1armTaD6o7GBg,55203
 services/project_manager.py,sha256=LaNWqBeVMx6wcB6iiOQyRWSWhS-JXzfDApJmHFmTCy8,36477
 services/project_runtime.py,sha256=yyftX48BFjq4B2KcR4KGszDAAa4xR6gn6j0SgTyro1s,11603
@@ -261,8 +263,8 @@ tui/screens/search_view.py,sha256=MMHjVdlk3HZSuDBSvq8IGrqv_Mh5Us6YqXQ80bcWSMk,19
 tui/screens/session_view.py,sha256=eZ1eDwHTvPOck1wCCviixtOaCxIkBT_95ytNNNriGNA,5991
 tui/screens/stats.py,sha256=p81PjzdaIv7hllb8f45-rlVe4lJZwSdIMqu7e86_u5s,6223
 tui/screens/ui_view.py,sha256=1QJCgLh2YfgWIpvzRG1KOGXYEaOYX6ojN61Azjf2oX0,2125
-code_context_control-2.71.0.dist-info/METADATA,sha256=JuTLloJ5Se5rtnIAWk4-e37C8-RD2QnEWs42Zw5VM_U,25601
-code_context_control-2.71.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-code_context_control-2.71.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.71.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.71.0.dist-info/RECORD,,
+code_context_control-2.74.0.dist-info/METADATA,sha256=lg_WYK9ceV_WdNnzUCdBi_xz-FMsOicT8srl04sbDTE,25601
+code_context_control-2.74.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+code_context_control-2.74.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
+code_context_control-2.74.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
+code_context_control-2.74.0.dist-info/RECORD,,

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.

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 "

services/notifications.py

@@ -43,7 +43,8 @@ class NotificationStore:
         self._collapsed = False
 
     def add(self, agent: str, severity: str, title: str, message: str,
-            ai_enhanced: bool = False, replace_if_unacked: bool = False) -> dict | None:
+            ai_enhanced: bool = False, replace_if_unacked: bool = False,
+            kind: str = "", ref_id: str = "") -> dict | None:
         """Append a notification. Dedup: an identical (agent, title, message)
         that is still unacknowledged collapses into the existing record — its
         ``count`` is bumped and ``last_seen`` refreshed instead of appending a
@@ -54,6 +55,13 @@ class NotificationStore:
             already exists, update its message/severity in-place (bumping
             count/last_seen) instead of appending a new entry. Use for
             high-frequency agents (budget, index, key-file drift) to prevent pile-up.
+        kind: machine-readable class for clients that ROUTE on a tap rather
+            than parse the title — 'override' for an approval request. Omitted
+            from the record when empty, so every existing producer and every
+            stored line is unchanged.
+        ref_id: the id of the thing the notification is ABOUT (e.g. the
+            override request), which is not the notification's own ``id``.
+            A client needs both: ``id`` to acknowledge, ``ref_id`` to navigate.
         Returns the entry if written/updated, None if deduped.
         """
         with self._lock:
@@ -75,6 +83,13 @@ class NotificationStore:
                         existing["last_seen"] = now.isoformat()
                         existing["count"] = _entry_count(existing) + 1
                         existing["ai_enhanced"] = ai_enhanced
+                        # Refresh the routing fields too: an in-place update
+                        # keeps the record but the thing it points AT may have
+                        # changed (a new request id under the same title).
+                        if kind:
+                            existing["kind"] = kind
+                        if ref_id:
+                            existing["ref_id"] = ref_id
                         self._write_all(entries)
                         return existing
                     # Same notification still pending — collapse into the
@@ -108,6 +123,12 @@ class NotificationStore:
                 "acknowledged": False,
                 "ai_enhanced": ai_enhanced,
             }
+            # Additive only: absent keys rather than empty ones, so a client
+            # can test presence and old lines stay byte-identical in shape.
+            if kind:
+                entry["kind"] = kind
+            if ref_id:
+                entry["ref_id"] = ref_id
             with open(self._file, "a", encoding="utf-8") as f:
                 f.write(json.dumps(entry) + "\n")
             return entry

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)
 
 

services/override_requests.py

@@ -420,6 +420,12 @@ def _notify(project_path: str, row: dict, policy) -> None:
                   f"{Path(row['path']).name}?",
             message=(f"Blocked by rule {row['rule']} ({row['rule_class']}). "
                      f"Approve once: c3 override approve {row['id']}"),
+            # A phone routes on these, not on the title. Without them a tap
+            # opens the app and drops the user wherever they were last —
+            # which, for the one notification that exists to be answered, is
+            # the same as not delivering it (§9).
+            kind="override",
+            ref_id=row["id"],
         )
     except Exception:
         pass  # a missing notification must never fail the request
@@ -460,6 +466,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 +548,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 +595,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

services/override_wake.py

@@ -0,0 +1,241 @@
+"""Wake the asking session when a human decides its override request.
+
+WHY THIS EXISTS — a measured failure, not a hypothetical
+--------------------------------------------------------
+2026-08-08, live end-to-end run. An agent asked for an override at 00:36Z,
+ended its turn, and the user approved from the phone at 00:42:32Z. The grant
+was minted correctly and expired unused at 00:57:32Z, because *nothing told
+the agent*. Before this module there were exactly two ways an agent could
+learn its request had been answered: block in ``c3_override(action='wait')``
+— capped at 180s per call, and useless once the turn ends — or call
+``action='status'`` later, which requires something to have already woken it.
+A decision was a write to disk that nobody was listening for. Grants are
+capped at 900s, so an idle agent misses the whole window by construction.
+
+WHAT IT DOES
+------------
+On every decision (approve *and* deny), run one configured command. That is
+the whole feature. The command is how the local orchestrator pokes whatever
+runs the agent — a chat message that re-invokes it, a queue write, a webhook
+via ``curl``. C3 does not know or care which; wiring an agent runtime in here
+would make this file grow a backend per orchestrator and rot.
+
+THREE THINGS THAT ARE DELIBERATE
+--------------------------------
+**argv, never a shell string.** ``command`` must be a list. There is no
+``shell=True`` anywhere in this file and no string form to fall back to, so a
+placeholder carrying a quote or a semicolon is an argument, not syntax.
+Placeholders are substituted per-element after the list is fixed, so no
+substitution can ever add an argument.
+
+**Config-only, and only from a file a human owns.** The spec is read from the
+``override.wake`` section of ``.c3/config.json``. Agents cannot write that
+file — the builtin ``read_only **/.c3/**`` rule denies it — and
+``override_policy.forbidden_target`` refuses to let any grant cover it, so
+this cannot be self-approved either. The mobile policy route rejects the
+``wake`` key outright (``mobile_api._WAKE_KEY``): a bearer token is not
+permission to choose what command this machine runs.
+
+**Synchronous, with a short timeout.** Backgrounding it looks kinder to the
+caller and silently loses the wake: ``c3 override approve`` exits the instant
+``decide()`` returns, taking any daemon thread with it. So the decision waits
+— bounded by ``timeout_s`` (default 10, hard max 60) — and the wake command's
+job is to hand off fast, not to do work.
+
+A wake that fails never unwinds a decision. The approval already happened;
+the agent falling back to ``action='status'`` is a slower path, not a wrong
+one. Every outcome, success or failure, lands in ``.c3/overrides.jsonl``.
+"""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from services import override_grants as og
+
+#: Lifecycle events, appended to the same audit the rest of the feature uses.
+EV_WOKE = "woke"
+EV_WAKE_FAILED = "wake_failed"
+
+DEFAULT_TIMEOUT_S = 10
+MAX_TIMEOUT_S = 60
+
+#: Statuses a wake may be requested for. ``expired`` is absent on purpose:
+#: nothing decided it, so there is no news to deliver.
+VALID_ON = ("approved", "denied")
+
+_VALID_KEYS = frozenset({"command", "cwd", "timeout_s", "on"})
+
+
+def validate_spec(spec) -> bool:
+    """True iff *spec* is a usable ``override.wake`` section.
+
+    Called from ``override_policy._validate``, which treats the whole
+    ``override`` section as corrupt when this returns False — the same
+    fail-closed reading every other key gets. A wake we cannot parse must not
+    degrade into "no wake, carry on quietly": that is the bug this feature
+    exists to fix, reintroduced as a typo.
+    """
+    if spec is None:
+        return True
+    if not isinstance(spec, dict) or set(spec) - _VALID_KEYS:
+        return False
+    command = spec.get("command")
+    if not isinstance(command, list) or not command:
+        return False
+    if any(not isinstance(a, str) or not a for a in command):
+        return False
+    if "cwd" in spec and not isinstance(spec["cwd"], str):
+        return False
+    if "timeout_s" in spec:
+        t = spec["timeout_s"]
+        if isinstance(t, bool) or not isinstance(t, int) or t < 1:
+            return False
+    on = spec.get("on")
+    if on is not None:
+        if not isinstance(on, list) or not on:
+            return False
+        if set(on) - set(VALID_ON):
+            return False
+    return True
+
+
+def wake_message(row: dict, grant=None) -> str:
+    """The line the woken agent reads. Written for a machine, not a human.
+
+    It names the decision, the identifiers needed to act on it, and — the part
+    that matters — exactly one next step. An agent woken with "something
+    happened" burns a turn rediscovering what; an agent woken with "retry the
+    same call once" does the thing the user tapped approve to make happen.
+    """
+    name = Path(str(row.get("path", ""))).name
+    call = f"{row.get('tool', '')} {row.get('op', '')} on {name}"
+    rid = row.get("id", "")
+    if row.get("status") == "approved":
+        g = grant or {}
+        return (
+            f"[c3-override] APPROVED {rid} — {call}. "
+            f"Grant {g.get('id', '')}, {g.get('uses_remaining', '?')} use(s), "
+            f"expires {g.get('expires_at', '')}. "
+            f"Retry the SAME call once, now, then report the outcome. "
+            f"The grant is single-use and session-bound; it dies unused if you wait."
+        )
+    muted = " The user also muted it: do not ask again this session." \
+        if row.get("muted") else ""
+    return (
+        f"[c3-override] DENIED {rid} — {call}."
+        f"{muted} Do not retry and do not re-ask: mark the step blocked and "
+        f"tell the user what you needed it for."
+    )
+
+
+def _fields(project_path: str, row: dict, grant=None) -> dict:
+    g = grant or {}
+    return {
+        "request_id": str(row.get("id", "")),
+        "session_id": str(row.get("session_id", "")),
+        "status": str(row.get("status", "")),
+        "decided_by": str(row.get("decided_by", "")),
+        "tool": str(row.get("tool", "")),
+        "op": str(row.get("op", "")),
+        "path": str(row.get("path", "")),
+        "path_key": str(row.get("path_key", "")),
+        "rule": str(row.get("rule", "")),
+        "rule_class": str(row.get("rule_class", "")),
+        "layer": str(row.get("layer", "")),
+        "grant_id": str(g.get("id", "")),
+        "project": str(project_path),
+        "project_name": Path(str(project_path)).name,
+        "message": wake_message(row, grant),
+    }
+
+
+def _subst(arg: str, fields: dict) -> str:
+    """``{name}`` → value, by explicit replace.
+
+    Not ``str.format``: the message and the rule glob both routinely contain
+    braces, and a format call would raise KeyError on ``{'a': 1}`` in a
+    justification — turning a wake into a silent no-op for the one request
+    whose refusal quoted a dict.
+    """
+    out = arg
+    for key, value in fields.items():
+        token = "{" + key + "}"
+        if token in out:
+            out = out.replace(token, value)
+    return out
+
+
+def fire(project_path: str, row: dict, grant=None, *, policy=None) -> dict:
+    """Run the configured wake command. Returns a small result dict.
+
+    ``{"fired": False, "reason": ...}`` when there is nothing to do — no spec,
+    or a status this spec does not subscribe to. Never raises.
+    """
+    try:
+        spec = getattr(policy, "wake", None)
+        if spec is None:
+            from services import override_policy as opol  # noqa: PLC0415
+            spec = getattr(opol.resolve(str(project_path)), "wake", None)
+        if not spec:
+            return {"fired": False, "reason": "no wake configured"}
+        if not validate_spec(spec):
+            return {"fired": False, "reason": "invalid wake spec"}
+
+        status = str(row.get("status", ""))
+        on = spec.get("on") or list(VALID_ON)
+        if status not in on:
+            return {"fired": False, "reason": f"status {status!r} not in on={on}"}
+
+        fields = _fields(project_path, row, grant)
+        argv = [_subst(a, fields) for a in spec["command"]]
+        timeout = min(int(spec.get("timeout_s", DEFAULT_TIMEOUT_S)),
+                      MAX_TIMEOUT_S)
+        cwd = spec.get("cwd") or str(project_path)
+        if not Path(cwd).is_dir():
+            og.audit(project_path, EV_WAKE_FAILED, {
+                "request_id": fields["request_id"], "reason": "cwd missing",
+                "cwd": cwd,
+            })
+            return {"fired": False, "reason": f"cwd does not exist: {cwd}"}
+    except Exception as exc:  # config reading must never break a decision
+        return {"fired": False, "reason": f"wake setup failed: {exc}"}
+
+    try:
+        proc = subprocess.run(  # noqa: S603 — argv list, shell=False, from a
+            argv,               # human-owned config file (see module docstring)
+            cwd=cwd,
+            timeout=timeout,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            shell=False,
+        )
+    except subprocess.TimeoutExpired:
+        og.audit(project_path, EV_WAKE_FAILED, {
+            "request_id": fields["request_id"],
+            "session_id": fields["session_id"],
+            "reason": "timeout", "timeout_s": timeout, "argv0": argv[0],
+        })
+        return {"fired": True, "ok": False, "reason": f"timed out after {timeout}s"}
+    except Exception as exc:
+        og.audit(project_path, EV_WAKE_FAILED, {
+            "request_id": fields["request_id"],
+            "session_id": fields["session_id"],
+            "reason": type(exc).__name__, "detail": str(exc)[:200],
+            "argv0": argv[0],
+        })
+        return {"fired": True, "ok": False, "reason": str(exc)}
+
+    ok = proc.returncode == 0
+    og.audit(project_path, EV_WOKE if ok else EV_WAKE_FAILED, {
+        "request_id": fields["request_id"],
+        "session_id": fields["session_id"],
+        "status": status,
+        "exit_code": proc.returncode,
+        # argv0 only. The rest can carry a conversation id or a token-shaped
+        # argument, and the audit log is read by more eyes than the config is.
+        "argv0": argv[0],
+        **({"stderr": (proc.stderr or b"").decode("utf-8", "replace")[:300]}
+           if not ok else {}),
+    })
+    return {"fired": True, "ok": ok, "exit_code": proc.returncode}