"""Blocking gateway approval wait for :mod:`tools.approval`. Mirrors the CLI's synchronous ``input()`` flow: the agent thread enqueues a pending approval, the gateway notifies the user, and the thread blocks until ``/approve`` / ``/deny`` resolves it or the approval timeout elapses. Multiple threads (parallel subagents, execute_code RPC handlers) can block concurrently — each gets its own ``threading.Event``; ``/approve`` resolves the oldest, ``/approve all`` every pending entry. Queue state (``_gateway_queues``, ``_lock``) is owned by ``tools.approval`` and reached through that module at call time. """ import logging import threading import time import uuid from tools.interrupt import get_interrupt_reason, is_interrupted from tools import approval_context as _ctx from tools.approval_human_wait import activity_heartbeat, human_wait_window logger = logging.getLogger("tools.approval") class _ApprovalEntry: """One pending dangerous-command approval inside a gateway session.""" __slots__ = ("acknowledged", "cancelled", "data", "event", "expired", "observers", "reason", "result", "settle") def __init__(self, data: dict): self.event = threading.Event() self.data = dict(data) self.data.setdefault("request_id", uuid.uuid4().hex) self.acknowledged = False # Surface hook run once when the wait ends by ANY path (answer, timeout, interrupt, /approve from # another client): the tui_gateway withdraws its open server→client request through it. self.settle = None self.observers = [] self.result: str | None = None # "once"|"session"|"always"|"deny" # Free-text reason from ``/deny `` so the agent can adapt, not just hear "denied". self.reason: str | None = None # Why the prompt was withdrawn with nobody answering (interrupt cause, session teardown); # followers and teardown read it so a withdrawn prompt never renders as a user deny. self.cancelled: str | None = None # The prompt timed out unanswered; followers woken by its event adopt that timeout. self.expired = False def _poll_event(event: threading.Event, session_key: str, *, interrupt_log: str, timeout_s: int | None = None) -> str: """Wait on *event* until it fires, the turn is interrupted, or approvals.timeout elapses; returns ``"set"`` | ``"interrupted"`` | ``"timeout"``. Polls in ~1s slices so activity heartbeats reach the agent's inactivity tracker every ~10s — otherwise the gateway watchdog kills the agent while the user is still responding (mirrors ``_wait_for_process()`` cadence). The loop is recorded as human-wait time so the concurrent batch deadline excludes it. Any interrupt (/stop, inactivity timeout, delegation teardown) ends the wait fail-closed: the command does not run. Who caused it is read from the per-thread interrupt-cause channel (``get_interrupt_reason()``, a trusted fixed category), never inferred from message text, so the caller can report a withdrawn prompt without inventing a user refusal.""" deadline = time.monotonic() + max(_ctx._get_approval_timeout() if timeout_s is None else timeout_s, 0) heartbeat = activity_heartbeat("waiting for user approval") with human_wait_window(session_key): while True: # The poll loop below is verifiably blocked on a human answer (the user tapping approve/deny on # the gateway surface), bounded by the approval timeout. Record it as human-wait time so the # concurrent batch deadline excludes it (#79719). if is_interrupted(): logger.info(interrupt_log, session_key) return "interrupted" remaining = deadline - time.monotonic() if remaining <= 0: return "timeout" if event.wait(timeout=min(1.0, remaining)): return "set" heartbeat() def _cancel_cause(state: str, entry) -> str | None: """Why the wait ended with nobody answering: the turn was interrupted (cause from the per-thread channel — a user /stop or a parent's delegation teardown), the entry was withdrawn with a stamped cause (leader interrupted, session torn down), or the turn ended under the prompt (notifier unregistered, result never set). ``None`` for a real answer or a plain timeout.""" if state == "interrupted": return get_interrupt_reason() or "turn interrupted" if state == "set" and entry.result is None: return entry.cancelled or "the turn ended before the prompt was answered" return None def _finish(payload: dict, resolved: bool, choice: str | None, reason, **extra) -> dict: """Fire the post hook and build the decision dict. Unresolved (timeout) and a None choice both mean the user never answered; ``cancelled`` carries the cause when the prompt was withdrawn rather than answered.""" _ctx._fire_approval_hook("post_approval_response", **payload, choice=_hook_choice(resolved, choice, extra), **extra) return {"resolved": resolved, "choice": choice, "reason": reason, **extra} def _hook_choice(resolved: bool, choice: str | None, extra: dict) -> str: """Observer-facing outcome of a wait: the choice, else ``cancelled`` / ``timeout``.""" if extra.get("cancelled"): return "cancelled" return (choice or "timeout") if resolved else "timeout" def _await_coalesced_leader(session_key: str, leader, payload: dict): """Wait on an already-pending identical approval instead of re-prompting. Adopts the leader's decision: ``session``/``always`` → approval (same dict shape as a direct resolution; persistence stays the caller's and is idempotent across leader and followers); ``deny`` → denial carrying the leader's reason; leader timeout / our own deadline → unresolved. ``once`` returns ``None``: single-use consent covers only the leader's execution, so the caller must issue a fresh prompt. Hooks fire with ``coalesced=True`` so observers see the follower's lifecycle without a duplicate prompt.""" _ctx._fire_approval_hook("pre_approval_request", **payload, coalesced=True) # The leader's captured timeout (when stamped), so a config edit mid-wait can't end the follower first. state = _poll_event(leader.event, session_key, timeout_s=leader.data.get("timeout_s"), interrupt_log="Coalesced approval wait interrupted — " "returning deny for session %s") if state == "set" and leader.result is None and leader.expired: state = "timeout" cancelled = _cancel_cause(state, leader) if state == "interrupted": # Deny only OUR follower; the leader thread handles its own signal. choice, resolved = "deny", True elif state == "timeout": choice, resolved = None, False else: choice = leader.result resolved = choice is not None if choice == "once": # The post hook fires for the fresh prompt's own lifecycle, not here. return None extra = {"cancelled": cancelled} if cancelled else {} return _finish(payload, resolved, choice, getattr(leader, "reason", None), coalesced=True, **extra) def _await_gateway_decision(session_key: str, notify_cb, approval_data: dict, *, surface: str = "gateway") -> dict: """Enqueue *approval_data*, notify the user, and block until resolved or timed out. Shared by the terminal command guard, the execute_code guard, the plugin escalation gate, and MCP elicitation. Returns ``{"resolved", "choice", "reason"}`` or ``{"resolved": False, "choice": None, "notify_failed": True}`` when the notify callback raised. Persisting the choice and building the tool-facing result stay with the caller. Identical concurrent approvals (same command text + pattern-key set) are coalesced: parallel tool calls would otherwise fire N identical prompts the user must /approve N times while the agent sits wedged. Followers adopt the leader's ``session``/``always``/``deny``/timeout; a ``once`` covers only the leader, so the followers fall through to ONE fresh prompt they coalesce on.""" from tools import approval as _approval from agent.terminal_approval_batch import approval_published, preparing_terminal_approval, register_prepared_approval primary_key = approval_data.get("pattern_key", "") if surface == "gateway": surface = _ctx.gateway_approval_surface() payload = { "command": approval_data.get("command", ""), "description": approval_data.get("description", ""), "pattern_key": primary_key, "pattern_keys": list(approval_data.get("pattern_keys", [primary_key])), "session_key": session_key, "surface": surface, } keys = list(approval_data.get("pattern_keys") or []) entry = _ApprovalEntry(approval_data) # Captured before the entry is published: a coalesced follower can find it while the pre-request # hooks still run, and must wait this same timeout rather than re-read a since-edited config. timeout_s = entry.data["timeout_s"] = _ctx._get_approval_timeout() def _enqueue() -> None: register_prepared_approval(session_key, entry) _approval._gateway_queues.setdefault(session_key, []).append(entry) # The leader lookup and our enqueue are ONE critical section: split, two identical requests both # miss each other, both enqueue and the user gets duplicate prompts. A ``once`` releases the # followers to prompt for themselves; they re-coalesce behind whichever re-prompts first, so the # user still sees one prompt at a time (the answered leader is already off the queue). while True: with _approval._lock: leader = None if not preparing_terminal_approval(): leader = next((e for e in _approval._gateway_queues.get(session_key, []) if e.data.get("command") == approval_data.get("command") and list(e.data.get("pattern_keys") or []) == keys), None) if leader is None: _enqueue() break adopted = _await_coalesced_leader(session_key, leader, payload) if adopted is not None: return adopted def _drop_entry(state: str) -> str | None: """Leave the queue and return the choice committed so far. Reading ``entry.result`` and removing the entry are one critical section under the approval lock: ``resolve_gateway_approval`` commits under the same lock, so a choice that landed after the deadline check but before this removal is still ours to honour, and one arriving later finds no entry (the client is told nothing was pending instead of being acked "ok" while the agent denies).""" with _approval._lock: choice = entry.result queue = _approval._gateway_queues.get(session_key, []) if entry in queue: queue.remove(entry) if not queue: _approval._gateway_queues.pop(session_key, None) settle, entry.settle = entry.settle, None observers, entry.observers = entry.observers, [] if choice is None and state in ("timeout", "notify_failed"): # Coalesced followers block on this event: wake them with the leader's outcome rather than # leaving them waiting their own full timeout on a prompt that no longer exists. entry.expired = state == "timeout" if state == "notify_failed": entry.cancelled = "the approval prompt could not be delivered" entry.event.set() if settle is not None or observers: # ``request.cancel`` carries a RequestCancelReason: a choice committed from another surface is # ``resolved``; a withdrawn entry (woken with no choice — session torn down, turn ended, client # cannot answer) is ``session_closed``; never the raw poll-state token "set". if state == "timeout" and choice is not None: reason = "resolved" elif state == "set": reason = "resolved" if choice is not None else "session_closed" else: reason = state for callback in ([settle] if settle is not None else []) + observers: try: callback(reason) except Exception: logger.debug("approval settle hook failed", exc_info=True) return choice from tools.human_input_hooks import human_input_request with human_input_request("approval", prompt=payload["command"], session_key=session_key) as human: # Plugins hear about the request before the gateway does (real-time observers). _ctx._fire_approval_hook("pre_approval_request", **payload) # Bridges sync agent thread → async gateway. try: notify_cb(dict(entry.data)) approval_published() except Exception as exc: logger.warning("Gateway approval notify failed: %s", exc) _drop_entry("notify_failed") _ctx._fire_approval_hook("post_approval_response", **payload, choice="notify_failed") human.outcome = "notify_failed" return {"resolved": False, "choice": None, "notify_failed": True} state = _poll_event(entry.event, session_key, timeout_s=timeout_s, interrupt_log="Approval wait interrupted — returning deny for session %s") cancelled = _cancel_cause(state, entry) if state == "interrupted": # Coalesced followers wake with the cause instead of a deny nobody issued. entry.cancelled = cancelled entry.event.set() choice = _drop_entry(state) if state == "interrupted": # Our own decision stays a fail-closed deny. choice = "deny" # A choice that landed in the gap between the deadline check and leaving the queue is an answer, # not a timeout (#112548) — the same first-settlement rule as server_requests.send(). resolved = state != "timeout" or choice is not None extra = {"cancelled": cancelled} if cancelled else {} human.outcome = _hook_choice(resolved, choice, extra) return _finish(payload, resolved, choice, entry.reason, **extra)