feat: register shell.exec tool — PowerShell full-mode access for Cato

- Register shell.exec in agent_loop.py via _register_shell_tools()
- Auto-upgrade powershell/pwsh commands to full mode (unrestricted, any cwd)
- Gateway/sandbox modes still clamped to workspace root
- exec-approvals.json created with powershell, pwsh, cmd in allowlist
- TOOLS.md updated: shell.exec usage, PowerShell examples, elevation note

Cato now has full elevated PowerShell access on this Windows Server machine.
Verified: powershell -Command whoami returns Administrator.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Cato

cato/agent_loop.py

@@ -135,6 +135,21 @@ async def _academic_pubmed(args: dict) -> str:
     register_tool("academic.pubmed", _academic_pubmed)
 
 
+def _register_shell_tools() -> None:
+    """Register shell.exec tool action — PowerShell and general shell execution."""
+    try:
+        from .tools.shell import ShellTool
+    except ImportError:
+        return
+
+    tool = ShellTool()
+
+    async def _shell_exec(args: dict) -> str:
+        return await tool.execute(args)
+
+    register_tool("shell.exec", _shell_exec)
+
+
 def _register_python_executor_tools() -> None:
     """Register python.execute tool action (Skill 7)."""
     try:
@@ -400,6 +415,9 @@ def __init__(
         # Register Python executor tool action (Skill 7)
         _register_python_executor_tools()
 
+        # Register shell execution tool action (shell.exec)
+        _register_shell_tools()
+
         # Register memory fact tool actions (Skill 2)
         _register_memory_tools(memory=memory)
 

cato/tools/shell.py

@@ -64,18 +64,28 @@ def __init__(self) -> None:
     async def execute(self, args: dict[str, Any]) -> str:
         """Dispatch from agent_loop tool registry (receives raw args dict)."""
         command = args.get("command", "")
-        mode = args.get("mode", "gateway")
         timeout = min(int(args.get("timeout", 30)), _MAX_TIMEOUT)
         cwd = args.get("cwd") or str(_DEFAULT_WORKSPACE)
 
-        # Clamp cwd to workspace root to prevent directory traversal
-        workspace_root = _CATO_DIR / "workspace"
-        if cwd:
-            cwd_path = Path(cwd).resolve()
-            try:
-                cwd_path.relative_to(workspace_root.resolve())
-            except ValueError:
-                cwd = str(workspace_root)
+        # Auto-upgrade to full mode for PowerShell commands so they can run
+        # anywhere on the system with unrestricted access.
+        first_word = shlex.split(command)[0].lower() if command.strip() else ""
+        base_cmd = Path(first_word).name
+        if base_cmd in ("powershell", "powershell.exe", "pwsh", "pwsh.exe"):
+            mode = "full"
+        else:
+            mode = args.get("mode", "gateway")
+
+        # Only clamp cwd to workspace root in sandbox/gateway mode.
+        # Full mode (PowerShell) may need to operate anywhere on the system.
+        if mode != "full":
+            workspace_root = _CATO_DIR / "workspace"
+            if cwd:
+                cwd_path = Path(cwd).resolve()
+                try:
+                    cwd_path.relative_to(workspace_root.resolve())
+                except ValueError:
+                    cwd = str(workspace_root)
 
         result = await self._run(command=command, mode=mode, timeout=timeout, cwd=cwd)
         return json.dumps(result)