code-context-control 2.70.0__py3-none-any.whl → 2.71.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.70.0"
+__version__ = "2.71.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

{code_context_control-2.70.0.dist-info → code_context_control-2.71.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.70.0
+Version: 2.71.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.70.0.dist-info → code_context_control-2.71.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=RHoNXlhdwdnlUA6T21legFhDcTHQXDjk5QNStEgXPho,368519
+cli/c3.py,sha256=Jk3Gb08tbxOLGNOyuKQswhXy3ByZEiTpXjKPYcpY8hc,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
@@ -110,14 +110,14 @@ 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.70.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.71.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
 core/mcp_toml.py,sha256=wfc7c6X7lIW5YpdWFnRK0qQ0M46v2t8j6WzcqfTKhaE,5627
 core/web_security.py,sha256=HwgK5aBATfvRIeO_4gWgzK77gKwGuzVlmiuNGm4gGxI,7884
 oracle/__init__.py,sha256=-OTD7Jh4mUMA4QgPGthPLWXttgZLpkIPhGQ87ZfHBx0,63
-oracle/config.py,sha256=hdN2zKZT1Fhn7HzE19GNcmZ7HwcmS6-xrydaU2mQY5A,5666
+oracle/config.py,sha256=F2m9GfgJbpkmXEecglWF3GYeHtPSVDY6HOXQpiMJ3B8,6324
 oracle/mcp_oracle.py,sha256=B5B-qSxi37outsuRHn1Ns6Gj8e7W593rmL34LMzuE8M,8980
 oracle/oracle_server.py,sha256=oRGODRVWvdBo3KetTXnkrDMzkuwE4UdKIveW43DNmJ8,47710
 oracle/oracle_ui.html,sha256=QZ9jpB7IdDqnP2-e6Q9t1PPguSFHWwB1kf23wT7KsdI,70344
@@ -135,7 +135,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=GK4puRmO6BrojGPA9OKX2IjiAGTNynWtDb9ztZnxIWk,65909
+oracle/services/mobile_api.py,sha256=69oQlEaJD1lI7es6GytK1AVKnxiyjOFL5J1lCzb-FRU,86109
 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
@@ -213,7 +213,7 @@ services/ollama_credentials.py,sha256=EQx0YljYRrRBJ2voALlVTv11UBjfw-A6N7k7EP7fUF
 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=AWmIhaQXa8gcUkDClT2hryKx--C5NsuYlgwaOUYklOg,14872
+services/override_requests.py,sha256=m1GKapR-f6qTJaBhvNxDzq-W_XRxedC1-PXAoQpeob8,23490
 services/parser.py,sha256=CPoIN1FmX7kK-55FnC3jvRy3NLjlnf1armTaD6o7GBg,55203
 services/project_manager.py,sha256=LaNWqBeVMx6wcB6iiOQyRWSWhS-JXzfDApJmHFmTCy8,36477
 services/project_runtime.py,sha256=yyftX48BFjq4B2KcR4KGszDAAa4xR6gn6j0SgTyro1s,11603
@@ -261,8 +261,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.70.0.dist-info/METADATA,sha256=Y76AzLKHzMFVdG6cNoBRpCXSO4HO4x3kNDps4Sa-tDw,25601
-code_context_control-2.70.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-code_context_control-2.70.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.70.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.70.0.dist-info/RECORD,,
+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,,

oracle/config.py

@@ -37,6 +37,15 @@ DEFAULTS = {
     # A global-scope access rule applies to EVERY project on this machine —
     # blast radius beyond the projects the token can even enumerate.
     "mobile_access_global_scope": False,
+    # ── Override Requests (docs/override-requests.md §3.2) ──
+    # The approval inbox. `override` serves the read routes (list / one /
+    # policy); `override_write` is what turns a phone tap into a real grant,
+    # so it is the switch that matters. Both default ON to match the access
+    # pair — the feature is already off by default one layer down, in the
+    # PROJECT policy (`override.enabled: false`, every layer false), which is
+    # what decides whether a request can exist at all.
+    "mobile_override_enabled": True,      # read: request list / one / policy
+    "mobile_override_write": True,        # decide / mute / policy edit
     # Second, tighter budget for security mutations, on top of the shared
     # api_rate_limit_per_min bucket. 0 = share the main bucket only.
     "mobile_security_rate_limit_per_min": 12,

oracle/services/mobile_api.py

@@ -66,6 +66,7 @@ CAPABILITIES = [
     "credentials", "credentials_write",
     "access", "access_write",
     "enforcement", "enforcement_write",
+    "override", "override_write",
 ]
 
 # capability -> config key that gates it. Absent from this map = always on.
@@ -76,6 +77,8 @@ _CAPABILITY_SWITCHES = {
     "access_write": "mobile_access_write",
     "enforcement": "mobile_access_enabled",
     "enforcement_write": "mobile_access_write",
+    "override": "mobile_override_enabled",
+    "override_write": "mobile_override_write",
 }
 
 FEED_TYPES = ("notification", "activity", "edit", "session_stat")
@@ -1616,3 +1619,469 @@ def mobile_enforcement_set():
         pass
     _gw_audit("mobile.enforcement.set_mode", {"mode": result["mode"]})
     return jsonify(result)
+
+
+# ── Override Requests (docs/override-requests.md §8) ──────
+# The approval inbox: the agent asks, the phone answers, the answer is a
+# narrow time-boxed grant rather than a policy change. These routes are
+# deliberately THIN — every decision, refusal and grant-mint lives in
+# services/override_requests.py so the CLI (`c3 override`) and this surface
+# cannot drift apart on the one check that matters (the typed confirmation).
+#
+# The wire contract is frozen in §3.3 and re-asserted by
+# tests/test_mobile_override_routes.py: the request row is serialised through
+# an explicit allowlist, not `dict(row)`, so an internal field added later
+# (e.g. `path_key`) cannot silently start crossing the network.
+
+#: §3.3 field order, verbatim. The mobile client reads these names.
+_OVERRIDE_FIELDS = (
+    "id", "project_path", "session_id", "created_at", "expires_at", "status",
+    "layer", "rule", "rule_class", "scope", "tool", "op", "path", "refusal",
+    "justification", "resolved_at", "decided_by", "decision_note",
+)
+
+#: Decisions made here are always attributed to the phone (§3.3 decided_by).
+_DECIDED_BY = "mobile"
+
+
+def _override_row(row: dict) -> dict:
+    """One request row for the wire. Allowlisted, never the raw dict.
+
+    ``path_key`` is deliberately absent: it is a canonicalised local
+    filesystem identity used for grant matching, and the phone already gets
+    the human-readable ``path``.
+    """
+    out = {k: row.get(k) for k in _OVERRIDE_FIELDS}
+    # Decision extras — present only once decided, so a pending card is exactly
+    # the §3.3 shape and nothing more.
+    for extra in ("grant_id", "grant_mode", "muted"):
+        if row.get(extra) is not None:
+            out[extra] = row.get(extra)
+    return out
+
+
+def _override_audit(action: str, row: dict, *, confirmed: bool = False,
+                    detail_extra: dict | None = None) -> None:
+    """Identifiers and rule globs only — never the justification.
+
+    The justification is agent-supplied untrusted text (§3.3); copying it into
+    the activity log would put attacker-controlled prose into a surface the
+    feed ships verbatim to every client.
+    """
+    detail = {"kind": "override", "action": action,
+              "request_id": row.get("id", ""),
+              "session_id": row.get("session_id", ""),
+              "rule": row.get("rule", ""),
+              "rule_class": row.get("rule_class", ""),
+              "tool": row.get("tool", ""), "op": row.get("op", ""),
+              "via": "oracle-mobile", "caller": _caller(),
+              "confirmed": bool(confirmed)}
+    detail.update(detail_extra or {})
+    project = row.get("project_path") or ""
+    if not project:
+        return
+    try:
+        from services.activity_log import ActivityLog
+        ActivityLog(str(project)).log("access_action", dict(detail))
+    except Exception:
+        pass
+    try:
+        from services.edit_ledger import EditLedger
+        EditLedger(str(project)).log_edit(
+            file=f"override://{row.get('id', '')}",
+            change_type=f"override_{action}",
+            summary=(f"{action} override {row.get('id', '')} "
+                     f"({row.get('rule', '')}) via mobile"),
+            tags=["override", action], detail=dict(detail))
+    except Exception:
+        pass
+
+
+def _override_write_gate():
+    """Capability + rate budget for every override mutation."""
+    gate = _feature_or_404("override") or _feature_or_404("override_write")
+    if gate:
+        return gate
+    return _security_gate()
+
+
+@bp.route("/overrides", methods=["GET"])
+def mobile_overrides_list():
+    """Pending + recently-decided requests, newest first.
+
+    ``project`` is OPTIONAL and omitting it means every project (§15.5): the
+    entire point of the inbox is answering while away from the desk, and a
+    phone that must first pick the right project to discover it has a pending
+    approval defeats that.
+    """
+    gate = _feature_or_404("override")
+    if gate:
+        return gate
+    from services import override_requests as orq
+    raw_project = (request.args.get("project") or "").strip()
+    project_path = ""
+    if raw_project:
+        # A named project must still be one this token can see.
+        resolved, err = _project_or_404(raw_project)
+        if err:
+            return err
+        project_path = str(resolved)
+    status = (request.args.get("status") or "").strip().lower()
+    try:
+        limit = int(request.args.get("limit") or _DEFAULT_LIMIT)
+    except (TypeError, ValueError):
+        limit = _DEFAULT_LIMIT
+    limit = max(1, min(limit, _MAX_LIMIT))
+    try:
+        rows = orq.list_requests(project_path=project_path, status=status,
+                                 limit=limit)
+    except Exception as exc:
+        return _svc_error(exc)
+    if not raw_project:
+        # Cross-project listing must not leak rows for projects this gateway
+        # does not serve — the store is one file across every project on the
+        # machine, including ones the scanner has since dropped.
+        rows = [r for r in rows
+                if _resolve_registered(str(r.get("project_path") or "")) is not None]
+    return jsonify({
+        "requests": [_override_row(r) for r in rows],
+        "count": len(rows),
+        "project": project_path,
+        "status": status,
+        "limit": limit,
+    })
+
+
+@bp.route("/overrides/policy", methods=["GET"])
+def mobile_overrides_policy_get():
+    """The effective (already merged + clamped) `override` section (§3.1).
+
+    Registered BEFORE `/overrides/<id>` would otherwise catch it — Flask
+    matches static rules ahead of converters, but the ordering is made
+    explicit here so a later refactor cannot turn `policy` into a request id.
+    """
+    gate = _feature_or_404("override")
+    if gate:
+        return gate
+    from services import override_policy as opol
+    resolved, err = _project_or_404(request.args.get("project") or "")
+    if err:
+        return err
+    policy = opol.resolve(str(resolved))
+    return jsonify({
+        "path": str(resolved),
+        "policy": policy.as_dict(),
+        "layers": list(opol.LAYER_KEYS),
+        "typed_confirm_layers": sorted(opol.TYPED_CONFIRM_LAYERS),
+        "hard_max_ttl_s": opol.HARD_MAX_TTL_S,
+        "defaults": {"max_ttl_s": opol.DEFAULTS["max_ttl_s"],
+                     "default_uses": opol.DEFAULTS["default_uses"]},
+        "writable": bool(_cfg().get("mobile_override_write", True)),
+        # Verbatim from the spec: policy is a floor, not a promise. Global and
+        # project merge by TIGHTENING, so a layer shown true here can still be
+        # false in effect if the other scope forbids it.
+        "coverage_note": (
+            "Project and global policy merge by tightening only: a layer is "
+            "escalatable iff both scopes allow it, and the numeric limits take "
+            "the smaller value. Grants are honoured on the PreToolUse hook "
+            "surface; the c3_* MCP tools do not consult them yet (P2a)."
+        ),
+    })
+
+
+@bp.route("/overrides/policy", methods=["POST"])
+def mobile_overrides_policy_set():
+    """Edit the project's `override` section.
+
+    Widening — enabling the feature, turning a layer on, raising a ceiling, or
+    allowing session grants — needs a typed confirmation. Tightening never
+    does: making the guard stricter is always allowed to be one tap.
+    """
+    gate = _override_write_gate()
+    if gate:
+        return gate
+    from services import override_policy as opol
+    data = request.get_json(silent=True) or {}
+    resolved, err = _project_or_404(data.get("project") or "")
+    if err:
+        return err
+
+    section = data.get("override")
+    if not isinstance(section, dict):
+        return jsonify({"error": "body needs an 'override' object"}), 400
+    unknown = sorted(set(section) - set(opol.DEFAULTS))
+    if unknown:
+        # §3.1: unknown keys are a hard error, never a silent no-op.
+        return jsonify({
+            "error": f"unknown override key(s): {', '.join(unknown)}",
+            "valid": sorted(opol.DEFAULTS),
+        }), 400
+    layers = section.get("layers")
+    if layers is not None:
+        if not isinstance(layers, dict):
+            return jsonify({"error": "'layers' must be an object"}), 400
+        bad = sorted(set(layers) - set(opol.LAYER_KEYS))
+        if bad:
+            return jsonify({"error": f"unknown layer(s): {', '.join(bad)}",
+                            "valid": list(opol.LAYER_KEYS)}), 400
+
+    current = opol.resolve(str(resolved))
+    widened = _override_widenings(current, section)
+    if widened and not _confirmed(data, "widen"):
+        return jsonify({
+            "error": "this widens what a phone tap can approve: "
+                     + ", ".join(widened),
+            "widens": widened,
+            "needs_confirmation": True, "confirm_with": "widen",
+        }), 400
+
+    try:
+        result = _write_override_section(resolved, section)
+    except (OSError, ValueError) as exc:
+        return _svc_error(exc)
+
+    _override_audit("policy_set",
+                    {"id": "", "project_path": str(resolved), "rule": ""},
+                    confirmed=bool(widened),
+                    detail_extra={"widens": widened,
+                                  "keys": sorted(section)})
+    _gw_audit("mobile.override.policy_set",
+              {"keys": sorted(section), "widens": widened})
+    effective = opol.resolve(str(resolved))
+    return jsonify({"path": str(resolved), "written": result,
+                    "policy": effective.as_dict(), "widened": widened})
+
+
+def _override_widenings(current, section: dict) -> list:
+    """Which requested changes LOOSEN the policy. Names, for the challenge."""
+    out = []
+    if section.get("enabled") and not current.enabled:
+        out.append("enabled")
+    for key, want in (section.get("layers") or {}).items():
+        if want and not current.layers.get(key, False):
+            out.append(f"layers.{key}")
+    for key in ("max_ttl_s", "default_uses", "request_ttl_s",
+                "max_pending_per_session", "max_requests_per_hour"):
+        if key in section:
+            try:
+                if int(section[key]) > int(getattr(current, key)):
+                    out.append(key)
+            except (TypeError, ValueError):
+                pass
+    if section.get("allow_session_grants") and not current.allow_session_grants:
+        out.append("allow_session_grants")
+    return out
+
+
+def _write_override_section(project: Path, section: dict) -> dict:
+    """Merge *section* into the project's `.c3/config.json` `override` block.
+
+    Project scope only. A global override policy governs every project on the
+    machine, and the phone has no affordance for reviewing that blast radius —
+    same call `mobile_enforcement_set` makes about machine-wide discipline.
+    """
+    cfg_file = Path(project) / ".c3" / "config.json"
+    cfg_file.parent.mkdir(parents=True, exist_ok=True)
+    cfg = {}
+    if cfg_file.is_file():
+        try:
+            cfg = json.loads(cfg_file.read_text(encoding="utf-8")) or {}
+        except ValueError as exc:
+            raise ValueError(f"project config is not valid JSON: {exc}") from exc
+    if not isinstance(cfg, dict):
+        raise ValueError("project config is not a JSON object")
+    block = dict(cfg.get("override") or {})
+    for key, value in section.items():
+        if key == "layers":
+            merged = dict(block.get("layers") or {})
+            merged.update({k: bool(v) for k, v in (value or {}).items()})
+            block["layers"] = merged
+        else:
+            block[key] = value
+    cfg["override"] = block
+    tmp = cfg_file.with_name(f"{cfg_file.name}.tmp")
+    tmp.write_text(json.dumps(cfg, indent=2, ensure_ascii=False),
+                   encoding="utf-8")
+    tmp.replace(cfg_file)
+    return block
+
+
+@bp.route("/overrides/<request_id>", methods=["GET"])
+def mobile_override_get(request_id):
+    """One request, full context."""
+    gate = _feature_or_404("override")
+    if gate:
+        return gate
+    from services import override_requests as orq
+    row = orq.get(str(request_id))
+    if row is None:
+        return jsonify({"error": "unknown request"}), 404
+    if _resolve_registered(str(row.get("project_path") or "")) is None:
+        # Same refusal as an unknown id: whether a request exists for a project
+        # this gateway does not serve is not this token's business.
+        return jsonify({"error": "unknown request"}), 404
+    from services import override_policy as opol
+    policy = opol.resolve(str(row.get("project_path") or "."))
+    return jsonify({
+        "request": _override_row(row),
+        # What approving would actually cost, so the card can say it BEFORE
+        # the tap rather than reporting a clamp afterwards.
+        "policy": {
+            "max_ttl_s": policy.max_ttl_s,
+            "default_uses": policy.default_uses,
+            "allow_session_grants": policy.allow_session_grants,
+            "escalatable": policy.escalatable(str(row.get("rule_class") or "")),
+        },
+        "needs_typed_confirm": (
+            str(row.get("rule_class") or "") in opol.TYPED_CONFIRM_LAYERS),
+        "confirm_with": (
+            row.get("rule") if str(row.get("rule_class") or "")
+            in opol.TYPED_CONFIRM_LAYERS else ""),
+    })
+
+
+@bp.route("/overrides/<request_id>/decide", methods=["POST"])
+def mobile_override_decide(request_id):
+    """Approve (minting a grant) or deny one request.
+
+    The typed-confirmation challenges are computed here for the CLIENT's
+    benefit — the authoritative check is inside ``override_requests.decide``,
+    which refuses regardless of what this route believes. Two places compute
+    it; only one enforces it.
+    """
+    gate = _override_write_gate()
+    if gate:
+        return gate
+    from services import override_policy as opol
+    from services import override_requests as orq
+    data = request.get_json(silent=True) or {}
+    decision = str(data.get("decision") or "").strip().lower()
+    if decision not in (orq.DECISION_APPROVE, orq.DECISION_DENY):
+        return jsonify({"error": "decision must be 'approve' or 'deny'"}), 400
+    mode = str(data.get("mode") or orq.MODE_ONCE).strip().lower()
+    if mode not in orq.MODES:
+        return jsonify({"error": f"mode must be one of: "
+                                 f"{', '.join(orq.MODES)}"}), 400
+
+    row = orq.get(str(request_id))
+    if row is None or _resolve_registered(str(row.get("project_path") or "")) is None:
+        return jsonify({"error": "unknown request"}), 404
+    if row.get("status") != orq.STATUS_PENDING:
+        # §12.7: it lapsed while the phone was showing it. 409, and the card
+        # refreshes to the real status instead of silently minting a grant.
+        return jsonify({"error": f"request is {row.get('status')}, not pending",
+                        "request": _override_row(row)}), 409
+
+    project_path = str(row.get("project_path") or ".")
+    policy = opol.resolve(project_path)
+    rule_class = str(row.get("rule_class") or "")
+    confirm = data.get("confirm")
+
+    if decision == orq.DECISION_APPROVE:
+        # (a) approving an access_deny / access_builtin request — the challenge
+        # is the RULE GLOB itself, typed by hand (§8, §11 threat 1).
+        if rule_class in opol.TYPED_CONFIRM_LAYERS and confirm != row.get("rule"):
+            return jsonify({
+                "error": f"approving an {rule_class} request needs the rule "
+                         "glob retyped by hand",
+                "needs_confirmation": True,
+                "confirm_with": row.get("rule"),
+            }), 400
+        # (b) a session grant, and only where policy allows one at all.
+        if mode == orq.MODE_SESSION:
+            if not policy.allow_session_grants:
+                return jsonify({
+                    "error": "session grants are disabled for this project",
+                    "detail": "`override.allow_session_grants` is false — "
+                              "approve once instead.",
+                }), 403
+            if (rule_class not in opol.TYPED_CONFIRM_LAYERS
+                    and confirm != orq.CONFIRM_SESSION):
+                return jsonify({
+                    "error": "a session grant is unlimited-use until it expires",
+                    "needs_confirmation": True,
+                    "confirm_with": orq.CONFIRM_SESSION,
+                }), 400
+
+    requested_ttl = data.get("ttl_s")
+    try:
+        requested_ttl = int(requested_ttl) if requested_ttl is not None else None
+    except (TypeError, ValueError):
+        return jsonify({"error": "ttl_s must be an integer"}), 400
+    requested_uses = data.get("uses")
+    try:
+        requested_uses = int(requested_uses) if requested_uses is not None else None
+    except (TypeError, ValueError):
+        return jsonify({"error": "uses must be an integer"}), 400
+
+    try:
+        result = orq.decide(
+            str(request_id), decision, uses=requested_uses,
+            ttl_s=requested_ttl, note=str(data.get("note") or ""),
+            decided_by=_DECIDED_BY, confirm=confirm, mode=mode,
+            mute=bool(data.get("mute")))
+    except orq.OverrideError as exc:
+        _override_audit(f"{decision}_refused", row)
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return _svc_error(exc)
+
+    _override_audit(decision, result,
+                    confirmed=rule_class in opol.TYPED_CONFIRM_LAYERS,
+                    detail_extra={"mode": mode,
+                                  "grant_id": result.get("grant_id", "")})
+    _gw_audit(f"mobile.override.{decision}",
+              {"request_id": str(request_id), "rule_class": rule_class,
+               "mode": mode})
+
+    payload = {"request": _override_row(result), "decision": decision}
+    if decision == orq.DECISION_APPROVE:
+        granted_ttl = policy.clamp_ttl(requested_ttl)
+        payload["grant"] = {
+            "id": result.get("grant_id", ""),
+            "mode": result.get("grant_mode", mode),
+            "ttl_s": granted_ttl,
+            "uses": policy.clamp_uses(
+                opol.HARD_MAX_USES if mode == orq.MODE_SESSION
+                else requested_uses),
+        }
+        # §8: a client asking for a week gets 15 minutes and is TOLD so.
+        if requested_ttl is not None and granted_ttl < requested_ttl:
+            payload["clamped"] = True
+            payload["clamped_note"] = (
+                f"requested ttl_s={requested_ttl} was clamped to "
+                f"{granted_ttl}s by this project's override.max_ttl_s "
+                f"({policy.max_ttl_s}s).")
+    return jsonify(payload)
+
+
+@bp.route("/overrides/<request_id>/mute", methods=["POST"])
+def mobile_override_mute(request_id):
+    """Deny, and suppress identical requests for this session (§8).
+
+    Never needs a confirmation: muting only ever makes the agent MORE blocked,
+    and deny must always be the cheaper gesture than approve (§9).
+    """
+    gate = _override_write_gate()
+    if gate:
+        return gate
+    from services import override_requests as orq
+    data = request.get_json(silent=True) or {}
+    row = orq.get(str(request_id))
+    if row is None or _resolve_registered(str(row.get("project_path") or "")) is None:
+        return jsonify({"error": "unknown request"}), 404
+    if row.get("status") != orq.STATUS_PENDING:
+        return jsonify({"error": f"request is {row.get('status')}, not pending",
+                        "request": _override_row(row)}), 409
+    try:
+        result = orq.decide(str(request_id), orq.DECISION_DENY,
+                            note=str(data.get("note") or ""),
+                            decided_by=_DECIDED_BY, mute=True)
+    except orq.OverrideError as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return _svc_error(exc)
+    _override_audit("mute", result, detail_extra={"muted": True})
+    _gw_audit("mobile.override.mute", {"request_id": str(request_id)})
+    return jsonify({"request": _override_row(result), "decision": "deny",
+                    "muted": True})

services/override_requests.py

@@ -31,6 +31,11 @@ from services import override_policy as op_policy
 
 STORE_REL = ".c3/oracle/override_requests.json"
 
+#: Mute store (P3, spec §8 "deny + suppress identical requests for this
+#: session"). A SIBLING file rather than a key inside the request store,
+#: because §3.3 freezes that file's shape as a JSON array of request rows.
+MUTES_REL = ".c3/oracle/override_mutes.json"
+
 STATUS_PENDING = "pending"
 STATUS_APPROVED = "approved"
 STATUS_DENIED = "denied"
@@ -45,6 +50,20 @@ JUSTIFICATION_CAP = 400
 DECISION_APPROVE = "approve"
 DECISION_DENY = "deny"
 
+#: Grant shape on approval (§8). ``once`` is the default and the only one that
+#: needs no extra switch; ``session`` is an unlimited-uses grant for the rest
+#: of the request TTL window and is gated on ``allow_session_grants`` plus a
+#: typed confirmation, because it is the closest thing here to a policy change.
+MODE_ONCE = "once"
+MODE_SESSION = "session"
+MODES = (MODE_ONCE, MODE_SESSION)
+
+#: What the client must retype to get a session grant. Not the rule glob —
+#: that challenge already means "I accept this access layer"; this one is a
+#: separate question ("I accept an unlimited-uses grant") and must not be
+#: answerable by the same keystrokes.
+CONFIRM_SESSION = "session"
+
 
 class OverrideError(ValueError):
     """A refusal the agent (or CLI) should see verbatim."""
@@ -149,6 +168,108 @@ def list_requests(*, project_path: str = "", session_id: str = "",
     return out[:limit] if limit else out
 
 
+# ── Mutes — "deny and stop asking" (§8, P3) ────────────────────────────────
+# A mute is the answer to a retry loop: the user denied this exact call once
+# and does not want to be asked again by this session. It is NOT a policy
+# change and NOT a grant — it suppresses a *message*, so its worst case is an
+# agent that stays blocked, which is the safe direction.
+#
+# Scope is deliberately (project, session, layer, rule, tool, op, path_key):
+# byte-identical to the duplicate-suppression key `create()` already uses, so
+# a mute is exactly "duplicate suppression that outlives the pending row".
+# Session-bound because §8 says "for this session" — a new Claude Code session
+# has a new problem and has earned the right to ask once.
+
+def mutes_path() -> Path:
+    return Path.home() / MUTES_REL
+
+
+def mute_key(project_path: str, *, session_id: str, layer: str, rule: str,
+             tool: str, op: str, path_key: str) -> str:
+    """The suppression identity. Same tuple as duplicate detection."""
+    return "\x1f".join([
+        og.path_key(project_path), str(session_id or ""), str(layer or ""),
+        str(rule or ""), str(tool or ""), str(op or ""), str(path_key or ""),
+    ])
+
+
+def load_mutes() -> list:
+    """Every mute row. Corrupt reads as empty — a lost mute only means the
+    agent gets to ask once more, so failing open here is the safe direction
+    (the opposite call from grants, where failing open would be a capability).
+    """
+    path = mutes_path()
+    if not path.is_file():
+        return []
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return []
+    if not isinstance(data, list):
+        return []
+    return [r for r in data if isinstance(r, dict)]
+
+
+def _save_mutes(rows: list) -> None:
+    path = mutes_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp")
+    tmp.write_text(json.dumps(rows, indent=2, ensure_ascii=False),
+                   encoding="utf-8")
+    tmp.replace(path)
+
+
+def is_muted(project_path: str, *, session_id: str, layer: str, rule: str,
+             tool: str, op: str, path_key: str) -> bool:
+    key = mute_key(project_path, session_id=session_id, layer=layer, rule=rule,
+                   tool=tool, op=op, path_key=path_key)
+    return any(r.get("key") == key for r in load_mutes())
+
+
+def add_mute(row: dict) -> dict:
+    """Suppress future requests identical to *row*. Idempotent."""
+    project_path = row.get("project_path", ".")
+    key = mute_key(project_path, session_id=row.get("session_id", ""),
+                   layer=row.get("layer", ""), rule=row.get("rule", ""),
+                   tool=row.get("tool", ""), op=row.get("op", ""),
+                   path_key=row.get("path_key", ""))
+    rows = load_mutes()
+    for existing in rows:
+        if existing.get("key") == key:
+            return existing
+    mute = {
+        "key": key,
+        "project_path": project_path,
+        "session_id": row.get("session_id", ""),
+        "layer": row.get("layer", ""),
+        "rule": row.get("rule", ""),
+        "tool": row.get("tool", ""),
+        "op": row.get("op", ""),
+        "path_key": row.get("path_key", ""),
+        "path": row.get("path", ""),
+        "request_id": row.get("id", ""),
+        "muted_at": og.iso(og.now()),
+    }
+    rows.append(mute)
+    _save_mutes(rows)
+    return mute
+
+
+def clear_mutes(project_path: str = "", session_id: str = "") -> int:
+    """Drop mutes, optionally narrowed. Human surfaces only. Returns count."""
+    rows = load_mutes()
+    key = og.path_key(project_path) if project_path else ""
+    keep = [r for r in rows
+            if (key and og.path_key(r.get("project_path", "")) != key)
+            or (session_id and r.get("session_id") != session_id)]
+    if not key and not session_id:
+        keep = []
+    removed = len(rows) - len(keep)
+    if removed:
+        _save_mutes(keep)
+    return removed
+
+
 # ── Creation — the agent surface (§7) ──────────────────────────────────────
 
 def classify(project_path: str, *, denial=None, layer: str = "",
@@ -210,6 +331,17 @@ def create(project_path: str, *, session_id: str, tool: str, op: str, path,
             f"{op_policy.TAG_NOT_ESCALATABLE} that file is part of the "
             "credential vault or the override policy itself.")
 
+    # A mute is a standing "no, and stop asking" from the user (§8). It is
+    # checked BEFORE the rate limits so a muted retry loop costs the agent's
+    # hourly budget nothing — the user already answered, and the honest
+    # outcome is a refusal that names the reason.
+    if is_muted(project_path, session_id=session_id, layer=gate, rule=rule,
+                tool=tool, op=op, path_key=key):
+        raise OverrideError(
+            f"{op_policy.TAG_NOT_ESCALATABLE} the user denied this exact "
+            "request and muted it for this session. Do not ask again — mark "
+            "the step blocked and tell the user what you needed.")
+
     rows = load()
     _refresh(rows)
     proj_key = og.path_key(project_path)
@@ -293,6 +425,41 @@ def _notify(project_path: str, row: dict, policy) -> None:
         pass  # a missing notification must never fail the request
 
 
+def _notify_decision(project_path: str, row: dict, grant=None) -> None:
+    """Append the OUTCOME to the notification feed (§8).
+
+    The request notification says "someone should decide this"; without a
+    second line the feed never records that anyone did, so a user scrolling
+    back sees an eternally-open question they actually answered from the
+    phone. Severity is deliberately ``info``: the decision is the calm end of
+    the story, and re-alerting on your own tap trains people to ignore the
+    feed.
+    """
+    try:
+        from services.notifications import NotificationStore  # noqa: PLC0415
+        status = row.get("status", "")
+        name = Path(str(row.get("path", ""))).name
+        if status == STATUS_APPROVED:
+            detail = "once" if row.get("grant_mode") != MODE_SESSION \
+                else "for this session"
+            message = (f"Granted {row.get('tool')} {row.get('op')} on {name} "
+                       f"{detail} (rule {row.get('rule')}). "
+                       f"Grant {(grant or {}).get('id', '')} expires "
+                       f"{(grant or {}).get('expires_at', '')}.")
+        else:
+            message = (f"Denied {row.get('tool')} {row.get('op')} on {name} "
+                       f"(rule {row.get('rule')})."
+                       + (" Muted for this session." if row.get("muted") else ""))
+        NotificationStore(str(project_path)).add(
+            agent="override",
+            severity="info",
+            title=f"Override {status}: {name}",
+            message=message,
+        )
+    except Exception:
+        pass  # the decision already happened; a missing feed line never undoes it
+
+
 def withdraw(request_id: str, session_id: str) -> dict:
     """An agent cancelling its OWN pending request (e.g. it found another way)."""
     rows = load()
@@ -315,7 +482,8 @@ def withdraw(request_id: str, session_id: str) -> dict:
 
 def decide(request_id: str, decision: str, *, uses: int | None = None,
            ttl_s: int | None = None, note: str = "", decided_by: str = "cli",
-           confirm: str | None = None) -> dict:
+           confirm: str | None = None, mode: str = MODE_ONCE,
+           mute: bool = False) -> dict:
     """Approve (minting a grant) or deny one request. **Human callers only.**
 
     Approving an ``access_deny`` / ``access_builtin`` request requires the rule
@@ -324,6 +492,8 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
     """
     if decision not in (DECISION_APPROVE, DECISION_DENY):
         raise OverrideError("decision must be 'approve' or 'deny'.")
+    if mode not in MODES:
+        raise OverrideError(f"mode must be one of: {', '.join(MODES)}.")
 
     rows = load()
     _refresh(rows)
@@ -344,12 +514,18 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
         row["resolved_at"] = og.iso(now)
         row["decided_by"] = decided_by
         row["decision_note"] = str(note or "")[:JUSTIFICATION_CAP] or None
+        row["muted"] = bool(mute)
         _save(rows)
+        # Mute AFTER the row is persisted: a mute whose request never landed
+        # as denied would suppress a question the user never actually answered.
+        if mute:
+            add_mute(row)
         og.audit(project_path, og.EV_DENIED, {
             "request_id": request_id, "session_id": row.get("session_id", ""),
             "rule": row.get("rule", ""), "path": row.get("path_key", ""),
-            "decided_by": decided_by,
+            "decided_by": decided_by, "muted": bool(mute),
         })
+        _notify_decision(project_path, row, grant=None)
         return row
 
     policy = op_policy.resolve(project_path)
@@ -363,6 +539,21 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
             f"approving an {layers_key} request needs the rule retyped: "
             f"confirm='{row.get('rule')}'")
 
+    if mode == MODE_SESSION:
+        # Two independent gates, both required. The switch is the user's
+        # standing policy; the challenge is their answer right now.
+        if not policy.allow_session_grants:
+            raise OverrideError(
+                "session grants are disabled for this project "
+                "(`override.allow_session_grants` is false). Approve once "
+                "instead, or change the policy on the desktop.")
+        if confirm != CONFIRM_SESSION and layers_key not in op_policy.TYPED_CONFIRM_LAYERS:
+            raise OverrideError(
+                "a session grant is unlimited-use until it expires: "
+                f"confirm='{CONFIRM_SESSION}'")
+        # Unlimited uses within the (already clamped) TTL window.
+        uses = op_policy.HARD_MAX_USES
+
     grant = og.mint(project_path, session_id=row.get("session_id", ""),
                     layer=row.get("layer", ""), rule=row.get("rule", ""),
                     tool=row.get("tool", ""), op=row.get("op", ""),
@@ -375,5 +566,7 @@ def decide(request_id: str, decision: str, *, uses: int | None = None,
     row["decided_by"] = decided_by
     row["decision_note"] = str(note or "")[:JUSTIFICATION_CAP] or None
     row["grant_id"] = grant["id"]
+    row["grant_mode"] = mode
     _save(rows)
+    _notify_decision(project_path, row, grant=grant)
     return row