patchbai 0.1.2__tar.gz → 0.2.0__tar.gz

{patchbai-0.1.2 → patchbai-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patchbai
-Version: 0.1.2
+Version: 0.2.0
 Summary: A Textual TUI for managing multiple Claude Code agent sessions
 Project-URL: Homepage, https://github.com/jimmymills/patchbai
 Project-URL: Repository, https://github.com/jimmymills/patchbai
@@ -118,6 +118,15 @@ the ideas.
   the actual `claude` CLI, or your shell, in any panel. Mode-C custom
   widgets let the orchestrator ship Python at runtime when the curated
   widget library isn't enough.
+- **Approve tool calls without leaving the room.** When a child wants
+  to use a tool that isn't auto-approved, a modal pops in patchbai with
+  the tool name and full arguments. Approve once, deny once, always
+  allow this tool for any agent named X (persisted to disk), or always
+  deny. The agent's status flips to `awaiting permission` and the
+  request also surfaces inline in its `AgentTranscript` panel so you
+  can clear it without opening the modal. Launch with
+  `--bypass-permissions` for "trust everything"; flip mid-session with
+  `/bypass-permissions` and `/require-permissions`.
 
 ## Concept
 
@@ -167,6 +176,7 @@ exactly one panel — the agent can shrink it but cannot hide its own input.
 | `Markdown` | Renders markdown from a string or file. |
 | `Notebook` | Editable scratch buffer; persists to `<cwd>/.patchbai/scratch/<name>.md`. |
 | `Terminal` | Real PTY — drop into `claude`, `$SHELL`, or any command. Opaque to the orchestrator. |
+| `SystemUsage` | Compact CPU + RAM gauges with auto-refresh and threshold-colored bars. Uses `psutil` if installed; otherwise async `top` / `vm_stat` shell-out on macOS. |
 
 The orchestrator can also register **custom widgets** by emitting Python
 source in the `custom_widgets` block of a `set_layout` call. The source
@@ -242,6 +252,8 @@ metadata reference — lives in
 | `/resume` | Open the resume picker for a past orchestrator session. |
 | `/rename` | Rename the current session's title. |
 | `/cd <path>` | Change the workspace cwd. |
+| `/bypass-permissions` | Switch the running session to bypass-all-permissions mode (no modals). |
+| `/require-permissions` | Switch back to permission-modal mode. |
 | `/help` | Show the slash-command list. |
 
 `ctrl-c` while the chat is focused interrupts the orchestrator without
@@ -566,8 +578,6 @@ the last good layout stays mounted.
 - **Claude Agent SDK only.** The agent abstraction is designed to
   accommodate other harnesses (Codex, Aider, Gemini CLI), but only the
   Claude adapter ships.
-- **No modal "approve this tool call?" UX.** Children inherit your
-  `~/.claude/settings.json` permissions, optionally narrowed at spawn.
 
 ## License
 

{patchbai-0.1.2 → patchbai-0.2.0}/README.md

@@ -83,6 +83,15 @@ the ideas.
   the actual `claude` CLI, or your shell, in any panel. Mode-C custom
   widgets let the orchestrator ship Python at runtime when the curated
   widget library isn't enough.
+- **Approve tool calls without leaving the room.** When a child wants
+  to use a tool that isn't auto-approved, a modal pops in patchbai with
+  the tool name and full arguments. Approve once, deny once, always
+  allow this tool for any agent named X (persisted to disk), or always
+  deny. The agent's status flips to `awaiting permission` and the
+  request also surfaces inline in its `AgentTranscript` panel so you
+  can clear it without opening the modal. Launch with
+  `--bypass-permissions` for "trust everything"; flip mid-session with
+  `/bypass-permissions` and `/require-permissions`.
 
 ## Concept
 
@@ -132,6 +141,7 @@ exactly one panel — the agent can shrink it but cannot hide its own input.
 | `Markdown` | Renders markdown from a string or file. |
 | `Notebook` | Editable scratch buffer; persists to `<cwd>/.patchbai/scratch/<name>.md`. |
 | `Terminal` | Real PTY — drop into `claude`, `$SHELL`, or any command. Opaque to the orchestrator. |
+| `SystemUsage` | Compact CPU + RAM gauges with auto-refresh and threshold-colored bars. Uses `psutil` if installed; otherwise async `top` / `vm_stat` shell-out on macOS. |
 
 The orchestrator can also register **custom widgets** by emitting Python
 source in the `custom_widgets` block of a `set_layout` call. The source
@@ -207,6 +217,8 @@ metadata reference — lives in
 | `/resume` | Open the resume picker for a past orchestrator session. |
 | `/rename` | Rename the current session's title. |
 | `/cd <path>` | Change the workspace cwd. |
+| `/bypass-permissions` | Switch the running session to bypass-all-permissions mode (no modals). |
+| `/require-permissions` | Switch back to permission-modal mode. |
 | `/help` | Show the slash-command list. |
 
 `ctrl-c` while the chat is focused interrupts the orchestrator without
@@ -531,8 +543,6 @@ the last good layout stays mounted.
 - **Claude Agent SDK only.** The agent abstraction is designed to
   accommodate other harnesses (Codex, Aider, Gemini CLI), but only the
   Claude adapter ships.
-- **No modal "approve this tool call?" UX.** Children inherit your
-  `~/.claude/settings.json` permissions, optionally narrowed at spawn.
 
 ## License
 

patchbai-0.2.0/patchbai/__main__.py

@@ -0,0 +1,32 @@
+import argparse
+import sys
+
+from patchbai.app import PatchbaiApp
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="patchbai",
+        description="Multi-agent Textual TUI for Claude Agent SDK.",
+    )
+    parser.add_argument(
+        "--bypass-permissions",
+        action="store_true",
+        help=(
+            "Run all sessions (orchestrator + child agents) with "
+            "permission_mode=bypassPermissions. Default behavior is to "
+            "ask for confirmation via a Textual modal before every "
+            "tool call."
+        ),
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parse_args(argv if argv is not None else sys.argv[1:])
+    PatchbaiApp(bypass_permissions=args.bypass_permissions).run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{patchbai-0.1.2 → patchbai-0.2.0}/patchbai/agents/manager.py

@@ -1,12 +1,21 @@
+import asyncio
 import dataclasses
 import time
 import uuid
 from pathlib import Path
 from typing import Callable
 
-from claude_agent_sdk import ClaudeAgentOptions
+from claude_agent_sdk import (
+    CanUseTool,
+    ClaudeAgentOptions,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    ToolPermissionContext,
+)
 
 from patchbai.agents.child_tools import build_child_mcp_server
+from patchbai.agents.permission_grants import PermissionGrants
+from patchbai.agents.permission_inbox import PermissionInbox
 from patchbai.agents.request_inbox import RequestInbox
 from patchbai.agents.sdk_adapter import SDKAdapter
 from patchbai.agents.session import AgentSession
@@ -17,6 +26,8 @@ from patchbai.events import (
     AgentStateChanged,
     DirectMessageToAgent,
     EventBus,
+    PermissionRequested,
+    PermissionResolved,
 )
 from patchbai.persistence.agents_index import AgentsIndex
 from patchbai.persistence.transcript_store import AgentTranscript, TranscriptEntry
@@ -31,12 +42,15 @@ class AgentManager:
         cwd: Path,
         bus: EventBus,
         adapter_factory: Callable[[], SDKAdapter],
+        permission_grants: PermissionGrants | None = None,
     ) -> None:
         self._cwd = cwd
         self._bus = bus
         self._adapter_factory = adapter_factory
+        self._grants = permission_grants
         self._sessions: dict[str, AgentSession] = {}
         self._inboxes: dict[str, RequestInbox] = {}
+        self._perm_inboxes: dict[str, PermissionInbox] = {}
         self._index = AgentsIndex(cwd=cwd)
         # Any agent persisted as still-running belongs to a previous (dead)
         # process. Flip those rows to ERROR so the AgentTable seed doesn't
@@ -107,27 +121,42 @@ class AgentManager:
         self._inboxes[info.id] = RequestInbox(
             on_pending_changed=_on_pending_changed,
         )
+
+        def _on_perm_changed(count: int, _session=session) -> None:
+            if count > 0:
+                _session._mark_awaiting_permission()
+            else:
+                _session._mark_done_permission()
+
+        self._perm_inboxes[info.id] = PermissionInbox(
+            on_pending_changed=_on_perm_changed,
+        )
         self._sessions[info.id] = session
         return session
 
     def _build_options(
         self, info: AgentInfo, *, resume_session_id: str | None = None,
     ) -> ClaudeAgentOptions:
-        # Bypass permissions for now: there's no Textual modal to render
-        # the SDK's permission prompts in plan 2, so the child would hang.
-        # The orchestrator can still narrow what a child may do via the
-        # allowed_tools / disallowed_tools args on the spawn_agent MCP tool.
-        # A proper can_use_tool callback that pops a Textual approval modal
-        # is plan-3 work.
+        # Permission posture: presence of self._grants is the gate.
+        #   - None  → permission_mode="bypassPermissions" (preserves the
+        #     original behavior; equivalent to launching with
+        #     --bypass-permissions).
+        #   - obj   → drop bypass, attach can_use_tool that consults the
+        #     grants store first and falls back to the modal flow.
         child_mcp = build_child_mcp_server(
             agent_id=info.id, bus=self._bus, inbox=self._inboxes[info.id],
         )
         opts = info.spawn_options or {}
         kwargs: dict = {
             "cwd": opts.get("cwd") or info.cwd,
-            "permission_mode": "bypassPermissions",
             "mcp_servers": {"patchbai_child": child_mcp},
         }
+        if self._grants is None:
+            kwargs["permission_mode"] = "bypassPermissions"
+        else:
+            kwargs["can_use_tool"] = self._make_can_use_tool(
+                agent_id=info.id, agent_name=info.name,
+            )
         if opts.get("allowed_tools") is not None:
             kwargs["allowed_tools"] = opts["allowed_tools"]
         if opts.get("disallowed_tools") is not None:
@@ -140,6 +169,65 @@ class AgentManager:
             kwargs["resume"] = resume_session_id
         return ClaudeAgentOptions(**kwargs)
 
+    def _make_can_use_tool(self, *, agent_id: str, agent_name: str) -> CanUseTool:
+        bus = self._bus
+        grants = self._grants
+        get_perm_inbox = self._perm_inboxes.get
+        # 30 minutes — long enough to step away briefly, short enough that a
+        # forgotten prompt doesn't strand the session forever.
+        TIMEOUT_S = 30 * 60
+
+        async def callback(
+            tool_name: str,
+            tool_input: dict,
+            ctx: ToolPermissionContext,
+        ):
+            assert grants is not None  # invariant when callback is wired
+            decision = grants.lookup(agent_name=agent_name, tool_name=tool_name)
+            if decision == "allow":
+                return PermissionResultAllow()
+            if decision == "deny":
+                return PermissionResultDeny(message="denied by saved rule")
+
+            inbox = get_perm_inbox(agent_id)
+            if inbox is None:
+                return PermissionResultDeny(message="agent gone", interrupt=True)
+            request_id = inbox.register(
+                tool_name=tool_name, tool_input=tool_input,
+                title=getattr(ctx, "title", None),
+                description=getattr(ctx, "description", None),
+            )
+            bus.publish(PermissionRequested(
+                agent_id=agent_id, agent_name=agent_name,
+                request_id=request_id, tool_name=tool_name,
+                tool_input=tool_input,
+                title=getattr(ctx, "title", None),
+                description=getattr(ctx, "description", None),
+            ))
+            try:
+                result = await inbox.wait(request_id, timeout_s=TIMEOUT_S)
+            except asyncio.CancelledError:
+                task = asyncio.current_task()
+                if task is not None and task.cancelling() > 0:
+                    raise  # real task cancellation — must propagate
+                bus.publish(PermissionResolved(
+                    agent_id=agent_id, request_id=request_id,
+                    behavior="cancelled",
+                ))
+                return PermissionResultDeny(message="cancelled", interrupt=True)
+            except asyncio.TimeoutError:
+                bus.publish(PermissionResolved(
+                    agent_id=agent_id, request_id=request_id, behavior="deny",
+                ))
+                return PermissionResultDeny(message="timed out")
+            bus.publish(PermissionResolved(
+                agent_id=agent_id, request_id=request_id,
+                behavior="allow" if isinstance(result, PermissionResultAllow) else "deny",
+            ))
+            return result
+
+        return callback
+
     def _on_session_id(self, agent_id: str, session_id: str) -> None:
         # The first ResultMessage carries the SDK session id. Capture it on
         # the persisted info so a fresh process can pass it back as resume=
@@ -196,6 +284,9 @@ class AgentManager:
     async def kill(self, agent_id: str) -> None:
         session = self._sessions.pop(agent_id, None)
         self._inboxes.pop(agent_id, None)
+        perm_inbox = self._perm_inboxes.pop(agent_id, None)
+        if perm_inbox is not None:
+            perm_inbox.cancel_all()
         if session is not None:
             await session.stop()
 
@@ -213,6 +304,9 @@ class AgentManager:
     def get_inbox(self, agent_id: str) -> RequestInbox | None:
         return self._inboxes.get(agent_id)
 
+    def get_permission_inbox(self, agent_id: str) -> PermissionInbox | None:
+        return self._perm_inboxes.get(agent_id)
+
     def set_archived(self, agent_id: str, *, archived: bool) -> None:
         """Toggle the archived flag for an agent. Persists to agents.json and
         publishes AgentArchiveChanged so listeners (e.g., AgentTable) can
@@ -258,7 +352,6 @@ class AgentManager:
         # resurrect it via SDK resume so the user's message lands on a real
         # conversation. Schedule on the running loop because EventBus
         # handlers must be sync.
-        import asyncio
         try:
             loop = asyncio.get_running_loop()
         except RuntimeError:

patchbai-0.2.0/patchbai/agents/permission_grants.py

@@ -0,0 +1,98 @@
+"""Persistent + session-scoped grant rules for tool permissions.
+
+DESIGN TRADEOFF (revisit when convenient):
+This module keys persistent grants by ``(agent_name, tool_name)``. The
+agent_name is the literal "orchestrator" for the user's main session and
+the user-supplied name for child agents. Respawning a child of the same
+name reuses prior decisions — convenient in the common case, surprising
+if a name is reused with different intent.
+
+A future revision could swap the disk-backed lookup for an in-memory one
+keyed by ``agent_id`` (scoped to one live spawn). The interface here is
+intentionally narrow so the swap touches only this file.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Literal
+
+from patchbai.persistence.atomic import write_json_atomic
+from patchbai.persistence.paths import project_state_dir
+
+log = logging.getLogger(__name__)
+
+Behavior = Literal["allow", "deny"]
+Scope = Literal["persistent", "session"]
+
+
+def _grants_path(cwd: Path) -> Path:
+    return project_state_dir(cwd) / "permission_grants.json"
+
+
+class PermissionGrants:
+    """Disk-backed allow/deny rules keyed by (agent_name, tool_name).
+
+    `remember(scope="session")` rules live in-memory only and evaporate on
+    process exit. `remember(scope="persistent")` rules are serialized to
+    `<cwd>/.patchbai/permission_grants.json`.
+    """
+
+    def __init__(self, *, cwd: Path) -> None:
+        self._cwd = Path(cwd)
+        self._disk: dict[tuple[str, str], Behavior] = {}
+        self._session: dict[tuple[str, str], Behavior] = {}
+        self._load_disk()
+
+    def lookup(self, *, agent_name: str, tool_name: str) -> Behavior | None:
+        # Disk wins over session — disk represents an explicit "always" the
+        # user chose earlier, session is "for this run." If both exist, the
+        # persistent decision is more authoritative.
+        key = (agent_name, tool_name)
+        return self._disk.get(key) or self._session.get(key)
+
+    def remember(
+        self,
+        *,
+        agent_name: str,
+        tool_name: str,
+        behavior: Behavior,
+        scope: Scope = "persistent",
+    ) -> None:
+        key = (agent_name, tool_name)
+        if scope == "persistent":
+            self._disk[key] = behavior
+            self._write_disk()
+        else:
+            self._session[key] = behavior
+
+    def clear(self) -> None:
+        self._disk.clear()
+        self._session.clear()
+        try:
+            _grants_path(self._cwd).unlink()
+        except FileNotFoundError:
+            pass
+
+    def _load_disk(self) -> None:
+        path = _grants_path(self._cwd)
+        if not path.exists():
+            return
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+            for entry in raw.get("grants", []):
+                key = (entry["agent_name"], entry["tool_name"])
+                self._disk[key] = entry["behavior"]
+        except (json.JSONDecodeError, OSError, KeyError, TypeError):
+            log.exception("permission_grants.json unreadable; starting empty")
+            self._disk.clear()
+
+    def _write_disk(self) -> None:
+        data = {
+            "version": 1,
+            "grants": [
+                {"agent_name": a, "tool_name": t, "behavior": b}
+                for (a, t), b in sorted(self._disk.items())
+            ],
+        }
+        write_json_atomic(_grants_path(self._cwd), data)

patchbai-0.2.0/patchbai/agents/permission_inbox.py

@@ -0,0 +1,91 @@
+import asyncio
+import logging
+import uuid
+from dataclasses import dataclass
+from typing import Callable
+
+from claude_agent_sdk import PermissionResult
+
+log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class PendingPermission:
+    request_id: str
+    tool_name: str
+    tool_input: dict
+    title: str | None = None
+    description: str | None = None
+
+
+class PermissionInbox:
+    """Per-session registry of pending can_use_tool callbacks.
+
+    Sibling to RequestInbox: same register/wait/resolve shape, different
+    payload (PermissionResult vs str) and different blocker semantics — the
+    AgentSession flips into AWAITING_PERMISSION while count > 0.
+
+    `on_pending_changed`, if provided, is called synchronously after every
+    transition that changes the pending count.
+    """
+
+    def __init__(
+        self,
+        *,
+        on_pending_changed: Callable[[int], None] | None = None,
+    ) -> None:
+        self._records: dict[str, PendingPermission] = {}
+        self._futures: dict[str, asyncio.Future] = {}
+        self._on_pending_changed = on_pending_changed
+
+    def register(
+        self,
+        *,
+        tool_name: str,
+        tool_input: dict,
+        title: str | None = None,
+        description: str | None = None,
+    ) -> str:
+        request_id = uuid.uuid4().hex[:12]
+        loop = asyncio.get_running_loop()
+        self._futures[request_id] = loop.create_future()
+        self._records[request_id] = PendingPermission(
+            request_id=request_id, tool_name=tool_name, tool_input=tool_input,
+            title=title, description=description,
+        )
+        self._notify()
+        return request_id
+
+    def resolve(self, request_id: str, result: PermissionResult) -> None:
+        future = self._futures.get(request_id)
+        if future is not None and not future.done():
+            future.set_result(result)
+
+    async def wait(self, request_id: str, *, timeout_s: float) -> PermissionResult:
+        future = self._futures.get(request_id)
+        if future is None:
+            raise KeyError(f"unknown request_id: {request_id}")
+        try:
+            return await asyncio.wait_for(future, timeout=timeout_s)
+        finally:
+            self._futures.pop(request_id, None)
+            self._records.pop(request_id, None)
+            self._notify()
+
+    def cancel_all(self) -> None:
+        """Cancel every pending future. Used by AgentManager.kill /
+        OrchestratorSession.stop."""
+        for fut in self._futures.values():
+            if not fut.done():
+                fut.cancel()
+
+    def pending(self) -> list[PendingPermission]:
+        return list(self._records.values())
+
+    def _notify(self) -> None:
+        if self._on_pending_changed is None:
+            return
+        try:
+            self._on_pending_changed(len(self._futures))
+        except Exception:
+            log.exception("PermissionInbox.on_pending_changed handler raised")

{patchbai-0.1.2 → patchbai-0.2.0}/patchbai/agents/session.py

@@ -49,6 +49,7 @@ class AgentSession:
         self._idle_event.set()
         self._send_lock = asyncio.Lock()
         self._pre_wait_state: AgentState | None = None
+        self._pre_perm_state: AgentState | None = None
 
     @property
     def session_id(self) -> str | None:
@@ -205,6 +206,31 @@ class AgentSession:
             return
         self._set_state(target)
 
+    def _mark_awaiting_permission(self) -> None:
+        """Enter AWAITING_PERMISSION, snapshotting the prior state.
+
+        Idempotent. Composes with _mark_waiting: a session can transition
+        RUNNING → AWAITING_PERMISSION → WAITING → AWAITING_PERMISSION
+        → RUNNING and end up where it started. Skipped if terminal.
+        """
+        if self.info.state.is_terminal:
+            return
+        if self.info.state == AgentState.AWAITING_PERMISSION:
+            return
+        self._pre_perm_state = self.info.state
+        self._set_state(AgentState.AWAITING_PERMISSION)
+
+    def _mark_done_permission(self) -> None:
+        """Exit AWAITING_PERMISSION, restoring the pre-permission state."""
+        if self.info.state != AgentState.AWAITING_PERMISSION:
+            self._pre_perm_state = None
+            return
+        target = self._pre_perm_state or AgentState.RUNNING
+        self._pre_perm_state = None
+        if target.is_terminal:
+            return
+        self._set_state(target)
+
     def _set_state(self, new_state: AgentState) -> None:
         old = self.info.state
         if old == new_state:

{patchbai-0.1.2 → patchbai-0.2.0}/patchbai/agents/state.py

@@ -6,6 +6,7 @@ class AgentState(str, Enum):
     IDLE = "idle"
     RUNNING = "running"
     WAITING = "waiting"
+    AWAITING_PERMISSION = "awaiting_permission"
     DONE = "done"
     ERROR = "error"