merge: merge origin/gamma/refactor and origin/feature/teamhoa/r05-r06 into feature/delta-team/epic-R04

application/conversations/__init__.py

@@ -1 +1,12 @@
-"""Application conversations package: turn lifecycle orchestration and agent execution."""
+"""Application conversations package: turn lifecycle orchestration, agent execution, and tool approval policy."""
+
+from .conversation_application_service import (
+    ConversationApplicationService,
+)
+from .tool_policy_gateway import ConfirmGate, ToolPolicyGateway
+
+__all__ = [
+    "ConversationApplicationService",
+    "ToolPolicyGateway",
+    "ConfirmGate",
+]

application/conversations/tool_policy_gateway.py

@@ -0,0 +1,83 @@
+"""ToolPolicyGateway - one confirm/deny decision path for every tool call
+(R05-T03).
+
+Today "does this tool call need the user's OK first" is answered by a
+different hand-written check per engine:
+
+* ``core/chat_agent.py::run_cowork`` — ``name in ("run_command",
+  "install_package")``, a literal tuple.
+* ``core/code_agent.py::run_code`` — ``name in (WRITE_TOOLS | MS365_WRITE_TOOLS)``,
+  a set built from two other hand-maintained sets.
+* MCP/connector tools (``core/mcp_client.py``, ``core/ext_connectors.py``) —
+  no check at all; ``chat_agent.py`` calls ``extra_executor(name, args)``
+  directly.
+
+Three answers to the same question, and the third one is a real gap: an MCP
+tool that deletes files or calls an external API today runs with zero
+confirmation even when the user turned "confirm before running commands" on.
+
+This gateway answers the question from data (:class:`~domain.tools.tool_descriptor.ToolCapability`
+via a :class:`~domain.tools.tool_registry.ToolRegistry`) instead of a literal
+name list, so registering a tool with the right capability is what gates it -
+nothing to remember at each new call site. R05-T04 is what actually registers
+MCP/connector tools with a capability; this module only needs the mechanism
+to exist.
+
+Pure Python: no Qt, no direct dialog. The actual approval prompt stays exactly
+what it is today - a ``gate`` object with a ``.request(payload) -> bool``
+method, supplied by the presentation layer (Settings' "confirm before running
+commands" wires it up, or None for auto-run) - this module only decides
+WHEN to ask it, never how to render the question.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Protocol
+
+from cowork_local.domain.tools import ToolCapability, ToolRegistry
+
+
+class ConfirmGate(Protocol):
+    """Shape of the existing ``PermissionGate`` both engines already use."""
+
+    def request(self, payload: Dict[str, Any]) -> bool: ...
+
+
+class ToolPolicyGateway:
+    """Decides whether a tool call needs approval, for ONE calling surface.
+
+    ``gated_capabilities`` is what makes this per-surface: Cowork only ever
+    asked about ``run_command``/``install_package`` (capability ``EXECUTE``),
+    while the Code tab additionally confirms plain file writes (capability
+    ``WRITE``). Passing the wrong set here would silently change which tools
+    prompt for approval - see the callers in ``core/chat_agent.py`` and
+    ``core/code_agent.py`` for the exact sets that preserve today's behavior.
+    """
+
+    def __init__(self, registry: ToolRegistry, gated_capabilities: ToolCapability) -> None:
+        self._registry = registry
+        self._gated_capabilities = gated_capabilities
+
+    def requires_confirmation(self, name: str) -> bool:
+        """True when ``name``'s declared capabilities overlap this surface's
+        gated set. An unregistered tool never requires confirmation through
+        this path - callers that must fail safe on unknown tools check
+        ``name in registry`` themselves (see R05-T04's MCP wrapping, which
+        registers every tool it exposes before any call can reach here)."""
+        return bool(self._registry.capabilities_for(name) & self._gated_capabilities)
+
+    def allow(self, name: str, gate: Optional[ConfirmGate], payload: Dict[str, Any]) -> bool:
+        """True when the call may proceed.
+
+        ``gate is None`` preserves each engine's existing "no gate wired -
+        auto-run" behavior; a tool outside ``gated_capabilities`` is never
+        asked about, matching read-only tools "never confirm" today.
+        ``payload`` is whatever ``gate.request(...)`` already expects at that
+        call site (the two engines use slightly different dict shapes) - this
+        gateway only decides WHETHER to call it, never reshapes the payload.
+        """
+        if gate is None or not self.requires_confirmation(name):
+            return True
+        return bool(gate.request(payload))
+
+
+__all__ = ["ToolPolicyGateway", "ConfirmGate"]