vudt15andClaude Sonnet 5
ae4fe72b2e
EPIC R05 (Team Hoa) - one security/approval path for every tool call.
R05-T01 domain/tools/{tool_descriptor,tool_registry}.py
ToolCapability (READ/WRITE/EXECUTE/NETWORK, composable) + ToolDescriptor +
ToolRegistry, replacing three independently-maintained gating lists
(core/tools.py::WRITE_TOOLS, code_agent.py's WRITE_TOOLS|MS365_WRITE_TOOLS,
chat_agent.py's literal ("run_command","install_package") tuple) with one
capability lookup.
R05-T02 infrastructure/filesystem/{file_tools,command_tools,fetch_tools,tool_context}.py
core/tools.py's execute_tool if/elif chain split into per-concern modules.
core/tools.py is now a strangler-fig shim: re-exports ToolContext/ToolError,
dispatches through a {name: handler} dict built from the split modules.
core/tools.py: 566 -> 291 lines.
R05-T03 application/conversations/tool_policy_gateway.py
ToolPolicyGateway.allow(name, gate, payload) - capability-driven ALLOW vs
ask-the-gate decision. Wired into both chat_agent.py::run_cowork and
code_agent.py::run_code, replacing their separate hand-rolled checks.
Verified equivalent to the old hardcoded sets by test.
R05-T04 (behavior change, not just refactor)
MCP/connector tools (core/mcp_client.py, core/ext_connectors.py) reached
chat_agent.py via extra_executor(name, args) with NO permission check at
all. They are now tagged with a conservative default capability
(WRITE|EXECUTE|NETWORK - no MCP tool self-declares risk) and routed through
the SAME ToolPolicyGateway as built-ins. When "confirm before running
commands" is on, MCP/connector calls now prompt like run_command already
did - a real gap closed, and a user-visible change worth calling out.
R05-T05 infrastructure/mcp/mcp_source_manager.py
McpToolSourceManager extracts the connection cache/lock/start-or-skip
lifecycle out of state.py::AppContext (_mcp_connections/_conn_lock) into a
standalone, directly-testable class. AppContext.build_mcp_tools and
_ms365_builtin_connection now call ensure()/stop(); _ext_connections
(unified Connectors) is out of scope for this task and keeps its own lock.
New tests: tests/unit/test_tool_registry_and_policy.py,
test_code_agent_tool_policy.py, test_cowork_extra_tool_policy.py,
test_mcp_source_manager.py (26 new tests).
Suite: 254 passed, 4 pre-existing failures unrelated to R05 (2 EPIC R02
config-security, 2 environment-dependent routing tests - see checklist).
check_imports: PASS. All new files < 400 LOC.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
87 lines
3.4 KiB
Python
87 lines
3.4 KiB
Python
"""ToolCapability / ToolDescriptor - the risk-tagged catalogue entry for one
|
|
tool the agent loop can call (R05-T01).
|
|
|
|
Today a tool is just a name inside ``core/tools.py::TOOL_SPECS`` (a
|
|
``providers.base.ToolSpec`` — name/description/JSON-schema parameters, with
|
|
no notion of risk) plus a hand-written membership test wherever gating is
|
|
needed: ``core/tools.py::WRITE_TOOLS``, ``core/code_agent.py``'s
|
|
``WRITE_TOOLS | MS365_WRITE_TOOLS``, and ``core/chat_agent.py``'s literal
|
|
``name in ("run_command", "install_package")``. Three call sites, three
|
|
independently-maintained lists, and a new tool (or an MCP/connector tool,
|
|
which has no list membership at all - see ``core/mcp_client.py``) is gated
|
|
only if someone remembers to add it everywhere.
|
|
|
|
``ToolDescriptor`` makes the risk an attribute of the tool itself, declared
|
|
once, so ``application/conversations/tool_policy_gateway.py`` (R05-T03) can
|
|
decide ALLOW/CONFIRM/DENY from data instead of a growing set of literal
|
|
tuples.
|
|
|
|
Pure domain code: stdlib only, no Qt, no I/O. ``to_spec``/``from_spec`` are
|
|
the only place this module touches something outside domain/, and that
|
|
something (``providers.base.ToolSpec``) is itself a plain dataclass with no
|
|
further dependencies.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from enum import Flag, auto
|
|
from typing import Any, Dict
|
|
|
|
from cowork_local.providers.base import ToolSpec
|
|
|
|
|
|
class ToolCapability(Flag):
|
|
"""What calling a tool can do to the machine or the network.
|
|
|
|
A ``Flag`` (not a plain ``Enum``) because a single tool can combine risks
|
|
- ``install_package`` writes to the environment, runs pip as a
|
|
subprocess, AND needs network access. Composing three separate booleans
|
|
per call site is exactly the duplication this type replaces.
|
|
"""
|
|
|
|
NONE = 0
|
|
READ = auto()
|
|
WRITE = auto()
|
|
EXECUTE = auto()
|
|
NETWORK = auto()
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ToolDescriptor:
|
|
"""An immutable description of one callable tool.
|
|
|
|
Attributes:
|
|
name: the identifier the model calls (``ToolSpec.name``).
|
|
description: shown to the model, unchanged from ``ToolSpec``.
|
|
parameters: JSON-Schema object for the call's arguments.
|
|
capabilities: the risk this tool carries - see :class:`ToolCapability`.
|
|
"""
|
|
|
|
name: str
|
|
description: str
|
|
parameters: Dict[str, Any] = field(default_factory=dict)
|
|
capabilities: ToolCapability = ToolCapability.NONE
|
|
|
|
def has(self, capability: ToolCapability) -> bool:
|
|
"""True when this tool carries (any bit of) ``capability``."""
|
|
return bool(self.capabilities & capability)
|
|
|
|
def to_spec(self) -> ToolSpec:
|
|
"""Project back to the ``ToolSpec`` shape the model-facing catalogue
|
|
and the provider call actually use - risk tagging is metadata the
|
|
wire format has no room for."""
|
|
return ToolSpec(name=self.name, description=self.description,
|
|
parameters=self.parameters)
|
|
|
|
@classmethod
|
|
def from_spec(cls, spec: ToolSpec,
|
|
capabilities: ToolCapability = ToolCapability.NONE) -> "ToolDescriptor":
|
|
"""Wrap an existing ``ToolSpec`` (built-in, MCP, or connector) with a
|
|
capability tag. The one place callers attach risk to a spec they did
|
|
not author themselves."""
|
|
return cls(name=spec.name, description=spec.description,
|
|
parameters=spec.parameters, capabilities=capabilities)
|
|
|
|
|
|
__all__ = ["ToolCapability", "ToolDescriptor"]
|