claude-code-acp 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

claude_code_acp/__init__.py

@@ -11,7 +11,7 @@ from .agent import ClaudeAcpAgent
 from .client import ClaudeClient, ClaudeEvents
 from .acp_client import AcpClient, AcpClientEvents
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 __all__ = [
     "ClaudeAcpAgent",

claude_code_acp/acp_client.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import logging
 from dataclasses import dataclass
+from pathlib import Path
 from typing import Any, Callable, Coroutine
 
 from acp.client.connection import ClientSideConnection
@@ -30,6 +31,17 @@ logger = logging.getLogger(__name__)
 __all__ = ["AcpClient", "AcpClientEvents"]
 
 
+@dataclass
+class TerminalProcess:
+    """Represents an active terminal process."""
+
+    process: asyncio.subprocess.Process
+    command: str
+    cwd: str
+    output_buffer: list[str]
+    exit_code: int | None = None
+
+
 @dataclass
 class AcpClientEvents:
     """Event handlers for ACP client."""
@@ -41,6 +53,12 @@ class AcpClientEvents:
     on_permission: Callable[[str, dict, list], Coroutine[Any, Any, str]] | None = None
     on_error: Callable[[Exception], Coroutine[Any, Any, None]] | None = None
     on_complete: Callable[[], Coroutine[Any, Any, None]] | None = None
+    # File operation handlers (optional - if not set, operations proceed automatically)
+    on_file_read: Callable[[str], Coroutine[Any, Any, str | None]] | None = None
+    on_file_write: Callable[[str, str], Coroutine[Any, Any, bool]] | None = None
+    # Terminal operation handlers (optional)
+    on_terminal_create: Callable[[str, str], Coroutine[Any, Any, bool]] | None = None
+    on_terminal_output: Callable[[str, str], Coroutine[Any, Any, None]] | None = None
 
 
 class AcpClient:
@@ -94,6 +112,9 @@ class AcpClient:
         self._session_id: str | None = None
         self._text_buffer = ""
         self._initialized = False
+        # Terminal management
+        self._terminals: dict[str, TerminalProcess] = {}
+        self._terminal_counter = 0
 
     # --- Event decorators ---
 
@@ -137,6 +158,55 @@ class AcpClient:
         self.events.on_complete = func
         return func
 
+    def on_file_read(self, func: Callable[[str], Coroutine[Any, Any, str | None]]):
+        """
+        Register handler for file read operations.
+
+        The handler receives (path) and can return:
+        - str: Override the file content with this value
+        - None: Proceed with normal file reading
+
+        This allows intercepting file reads for security or custom handling.
+        """
+        self.events.on_file_read = func
+        return func
+
+    def on_file_write(self, func: Callable[[str, str], Coroutine[Any, Any, bool]]):
+        """
+        Register handler for file write operations.
+
+        The handler receives (path, content) and should return:
+        - True: Allow the write to proceed
+        - False: Block the write
+
+        This allows intercepting file writes for security or confirmation prompts.
+        """
+        self.events.on_file_write = func
+        return func
+
+    def on_terminal_create(self, func: Callable[[str, str], Coroutine[Any, Any, bool]]):
+        """
+        Register handler for terminal creation requests.
+
+        The handler receives (command, cwd) and should return:
+        - True: Allow the terminal to be created
+        - False: Block the terminal creation
+
+        This allows intercepting shell command execution for security.
+        """
+        self.events.on_terminal_create = func
+        return func
+
+    def on_terminal_output(self, func: Callable[[str, str], Coroutine[Any, Any, None]]):
+        """
+        Register handler for terminal output.
+
+        The handler receives (terminal_id, output) when new output is available.
+        This allows displaying or logging terminal output in real-time.
+        """
+        self.events.on_terminal_output = func
+        return func
+
     # --- Connection management ---
 
     async def connect(self) -> None:
@@ -179,6 +249,15 @@ class AcpClient:
 
     async def disconnect(self) -> None:
         """Disconnect from the ACP agent."""
+        # Clean up all terminals
+        for terminal_id, terminal in list(self._terminals.items()):
+            try:
+                terminal.process.kill()
+                await terminal.process.wait()
+            except Exception:
+                pass
+        self._terminals.clear()
+
         if self._connection:
             await self._connection.close()
             self._connection = None
@@ -331,33 +410,268 @@ class AcpClient:
                     outcome={"outcome": "selected", "option_id": selected_id}
                 )
 
-            async def write_text_file(self, **kwargs) -> None:
-                """Handle write file requests (stub)."""
-                pass
-
-            async def read_text_file(self, **kwargs) -> dict:
-                """Handle read file requests (stub)."""
-                return {"content": ""}
+            async def write_text_file(
+                self,
+                path: str,
+                content: str,
+                **kwargs,
+            ) -> None:
+                """
+                Handle write file requests from the agent.
+
+                The agent requests the client to write a file to disk.
+                This enables the agent to create/modify files in the user's filesystem.
+
+                Args:
+                    path: The file path to write to.
+                    content: The content to write.
+                """
+                # Check if handler wants to intercept/block the write
+                if client.events.on_file_write:
+                    allowed = await client.events.on_file_write(path, content)
+                    if not allowed:
+                        logger.info(f"File write blocked by handler: {path}")
+                        return
+
+                try:
+                    file_path = Path(path)
+                    # Create parent directories if they don't exist
+                    file_path.parent.mkdir(parents=True, exist_ok=True)
+                    # Write the file
+                    file_path.write_text(content, encoding="utf-8")
+                    logger.debug(f"Wrote file: {path}")
+                except Exception as e:
+                    logger.error(f"Failed to write file {path}: {e}")
+                    raise
+
+            async def read_text_file(
+                self,
+                path: str,
+                **kwargs,
+            ) -> dict:
+                """
+                Handle read file requests from the agent.
+
+                The agent requests the client to read a file from disk.
+                This enables the agent to access files in the user's filesystem.
+
+                Args:
+                    path: The file path to read.
+
+                Returns:
+                    A dict with 'content' key containing the file content.
+                """
+                # Check if handler wants to override the content
+                if client.events.on_file_read:
+                    override = await client.events.on_file_read(path)
+                    if override is not None:
+                        logger.debug(f"File read overridden by handler: {path}")
+                        return {"content": override}
+
+                try:
+                    file_path = Path(path)
+                    if not file_path.exists():
+                        logger.warning(f"File not found: {path}")
+                        return {"content": "", "error": f"File not found: {path}"}
+                    content = file_path.read_text(encoding="utf-8")
+                    logger.debug(f"Read file: {path} ({len(content)} chars)")
+                    return {"content": content}
+                except Exception as e:
+                    logger.error(f"Failed to read file {path}: {e}")
+                    return {"content": "", "error": str(e)}
+
+            async def create_terminal(
+                self,
+                command: str = "",
+                args: list[str] | None = None,
+                cwd: str | None = None,
+                env: dict[str, str] | None = None,
+                **kwargs,
+            ) -> dict:
+                """
+                Create a terminal and execute a command.
+
+                The agent requests the client to run a shell command.
+                This enables command execution in the user's environment.
+
+                Args:
+                    command: The command to execute.
+                    args: Command arguments.
+                    cwd: Working directory (defaults to client cwd).
+                    env: Additional environment variables.
+
+                Returns:
+                    A dict with 'terminal_id' for tracking the process.
+                """
+                work_dir = cwd or client.cwd
+                full_command = command
+                if args:
+                    full_command = f"{command} {' '.join(args)}"
+
+                # Check if handler wants to block the terminal creation
+                if client.events.on_terminal_create:
+                    allowed = await client.events.on_terminal_create(full_command, work_dir)
+                    if not allowed:
+                        logger.info(f"Terminal creation blocked by handler: {full_command}")
+                        return {"terminal_id": "", "error": "Terminal creation blocked"}
+
+                try:
+                    # Create the subprocess
+                    process = await asyncio.create_subprocess_shell(
+                        full_command,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.STDOUT,
+                        cwd=work_dir,
+                        env={**dict(env or {})} if env else None,
+                    )
 
-            async def create_terminal(self, **kwargs) -> dict:
-                """Handle terminal creation (stub)."""
-                return {"terminal_id": "stub"}
+                    # Generate terminal ID
+                    client._terminal_counter += 1
+                    terminal_id = f"terminal-{client._terminal_counter}"
 
-            async def terminal_output(self, **kwargs) -> dict:
-                """Handle terminal output requests (stub)."""
-                return {"output": ""}
+                    # Store the terminal
+                    client._terminals[terminal_id] = TerminalProcess(
+                        process=process,
+                        command=full_command,
+                        cwd=work_dir,
+                        output_buffer=[],
+                    )
 
-            async def release_terminal(self, **kwargs) -> None:
-                """Handle terminal release (stub)."""
-                pass
+                    logger.debug(f"Created terminal {terminal_id}: {full_command}")
+                    return {"terminal_id": terminal_id}
 
-            async def wait_for_terminal_exit(self, **kwargs) -> dict:
-                """Handle terminal exit wait (stub)."""
-                return {"exit_code": 0}
+                except Exception as e:
+                    logger.error(f"Failed to create terminal: {e}")
+                    return {"terminal_id": "", "error": str(e)}
 
-            async def kill_terminal(self, **kwargs) -> None:
-                """Handle terminal kill (stub)."""
-                pass
+            async def terminal_output(
+                self,
+                terminal_id: str = "",
+                **kwargs,
+            ) -> dict:
+                """
+                Get output from a terminal.
+
+                Args:
+                    terminal_id: The terminal to get output from.
+
+                Returns:
+                    A dict with 'output' containing available output.
+                """
+                terminal = client._terminals.get(terminal_id)
+                if not terminal:
+                    return {"output": "", "error": f"Terminal not found: {terminal_id}"}
+
+                try:
+                    # Try to read available output (non-blocking)
+                    if terminal.process.stdout:
+                        try:
+                            # Read with a short timeout
+                            output = await asyncio.wait_for(
+                                terminal.process.stdout.read(4096),
+                                timeout=0.1,
+                            )
+                            if output:
+                                decoded = output.decode("utf-8", errors="replace")
+                                terminal.output_buffer.append(decoded)
+
+                                # Notify handler if registered
+                                if client.events.on_terminal_output:
+                                    await client.events.on_terminal_output(terminal_id, decoded)
+
+                                return {"output": decoded}
+                        except asyncio.TimeoutError:
+                            pass
+
+                    # Return buffered output if no new output
+                    if terminal.output_buffer:
+                        return {"output": "".join(terminal.output_buffer)}
+                    return {"output": ""}
+
+                except Exception as e:
+                    logger.error(f"Failed to get terminal output: {e}")
+                    return {"output": "", "error": str(e)}
+
+            async def release_terminal(
+                self,
+                terminal_id: str = "",
+                **kwargs,
+            ) -> None:
+                """
+                Release a terminal without killing it.
+
+                The terminal continues running but we stop tracking it.
+
+                Args:
+                    terminal_id: The terminal to release.
+                """
+                if terminal_id in client._terminals:
+                    logger.debug(f"Released terminal: {terminal_id}")
+                    del client._terminals[terminal_id]
+
+            async def wait_for_terminal_exit(
+                self,
+                terminal_id: str = "",
+                **kwargs,
+            ) -> dict:
+                """
+                Wait for a terminal to exit and return its exit code.
+
+                Args:
+                    terminal_id: The terminal to wait for.
+
+                Returns:
+                    A dict with 'exit_code'.
+                """
+                terminal = client._terminals.get(terminal_id)
+                if not terminal:
+                    return {"exit_code": -1, "error": f"Terminal not found: {terminal_id}"}
+
+                try:
+                    # Read remaining output while waiting
+                    if terminal.process.stdout:
+                        remaining = await terminal.process.stdout.read()
+                        if remaining:
+                            decoded = remaining.decode("utf-8", errors="replace")
+                            terminal.output_buffer.append(decoded)
+                            if client.events.on_terminal_output:
+                                await client.events.on_terminal_output(terminal_id, decoded)
+
+                    # Wait for process to exit
+                    exit_code = await terminal.process.wait()
+                    terminal.exit_code = exit_code
+                    logger.debug(f"Terminal {terminal_id} exited with code {exit_code}")
+                    return {"exit_code": exit_code}
+
+                except Exception as e:
+                    logger.error(f"Failed to wait for terminal exit: {e}")
+                    return {"exit_code": -1, "error": str(e)}
+
+            async def kill_terminal(
+                self,
+                terminal_id: str = "",
+                **kwargs,
+            ) -> None:
+                """
+                Kill a terminal process.
+
+                Args:
+                    terminal_id: The terminal to kill.
+                """
+                terminal = client._terminals.get(terminal_id)
+                if not terminal:
+                    return
+
+                try:
+                    terminal.process.kill()
+                    await terminal.process.wait()
+                    logger.debug(f"Killed terminal: {terminal_id}")
+                except Exception as e:
+                    logger.error(f"Failed to kill terminal: {e}")
+
+                # Remove from tracking
+                if terminal_id in client._terminals:
+                    del client._terminals[terminal_id]
 
             async def ext_method(self, method: str, params: dict) -> dict:
                 """Handle extension methods."""

claude_code_acp/agent.py

@@ -73,6 +73,7 @@ class Session:
     permission_mode: PermissionMode = "default"
     cancelled: bool = False
     tool_use_cache: dict[str, ToolUseBlock] = field(default_factory=dict)
+    mcp_servers: dict[str, Any] = field(default_factory=dict)
 
 
 class ClaudeAcpAgent(Agent):
@@ -141,12 +142,16 @@ class ClaudeAcpAgent(Agent):
         """Create a new Claude session."""
         session_id = str(uuid4())
 
+        # Convert ACP MCP servers to Claude SDK format
+        sdk_mcp_servers = self._convert_mcp_servers(mcp_servers)
+
         self._sessions[session_id] = Session(
             session_id=session_id,
             cwd=cwd,
+            mcp_servers=sdk_mcp_servers,
         )
 
-        logger.info(f"New session created: {session_id} in {cwd}")
+        logger.info(f"New session created: {session_id} in {cwd} with {len(sdk_mcp_servers)} MCP servers")
 
         return NewSessionResponse(
             session_id=session_id,
@@ -224,11 +229,12 @@ class ClaudeAcpAgent(Agent):
 
         logger.info(f"Prompt for session {session_id}: {prompt_text[:100]}...")
 
-        # Build Claude options with permission callback for bidirectional communication
+        # Build Claude options with MCP servers and permission callback
         options = ClaudeAgentOptions(
             cwd=session.cwd,
             permission_mode=session.permission_mode,
             include_partial_messages=True,
+            mcp_servers=session.mcp_servers if session.mcp_servers else {},
         )
 
         # Add permission callback if not bypassing permissions
@@ -237,6 +243,7 @@ class ClaudeAcpAgent(Agent):
                 cwd=session.cwd,
                 permission_mode=session.permission_mode,
                 include_partial_messages=True,
+                mcp_servers=session.mcp_servers if session.mcp_servers else {},
                 can_use_tool=self._create_permission_handler(session_id),
             )
 
@@ -300,6 +307,68 @@ class ClaudeAcpAgent(Agent):
 
         return "\n".join(parts)
 
+    def _convert_mcp_servers(
+        self,
+        acp_servers: list[HttpMcpServer | SseMcpServer | McpServerStdio],
+    ) -> dict[str, Any]:
+        """Convert ACP MCP server configs to Claude SDK format."""
+        sdk_servers: dict[str, Any] = {}
+
+        for i, server in enumerate(acp_servers):
+            if isinstance(server, dict):
+                server_type = server.get("type")
+                name = server.get("name", f"mcp-server-{i}")
+
+                if server_type == "stdio":
+                    # Stdio MCP server
+                    sdk_servers[name] = {
+                        "type": "stdio",
+                        "command": server.get("command", ""),
+                        "args": server.get("args", []),
+                        "env": server.get("env", {}),
+                    }
+                elif server_type == "sse":
+                    # SSE MCP server
+                    sdk_servers[name] = {
+                        "type": "sse",
+                        "url": server.get("url", ""),
+                    }
+                elif server_type == "http":
+                    # HTTP MCP server
+                    sdk_servers[name] = {
+                        "type": "http",
+                        "url": server.get("url", ""),
+                    }
+
+                logger.info(f"Added MCP server: {name} ({server_type})")
+
+            elif hasattr(server, "type"):
+                # Pydantic model
+                name = getattr(server, "name", f"mcp-server-{i}")
+                server_type = server.type
+
+                if server_type == "stdio":
+                    sdk_servers[name] = {
+                        "type": "stdio",
+                        "command": getattr(server, "command", ""),
+                        "args": getattr(server, "args", []),
+                        "env": getattr(server, "env", {}),
+                    }
+                elif server_type == "sse":
+                    sdk_servers[name] = {
+                        "type": "sse",
+                        "url": getattr(server, "url", ""),
+                    }
+                elif server_type == "http":
+                    sdk_servers[name] = {
+                        "type": "http",
+                        "url": getattr(server, "url", ""),
+                    }
+
+                logger.info(f"Added MCP server: {name} ({server_type})")
+
+        return sdk_servers
+
     async def _handle_message(self, session_id: str, message: Message) -> None:
         """Convert and emit a Claude message as ACP updates."""
         if self._conn is None:

{claude_code_acp-0.3.2.dist-info → claude_code_acp-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-acp
-Version: 0.3.2
+Version: 0.3.4
 Summary: ACP-compatible agent for Claude Code (Python version)
 Project-URL: Homepage, https://github.com/yazelin/claude-code-acp-py
 Project-URL: Repository, https://github.com/yazelin/claude-code-acp-py
@@ -234,6 +234,43 @@ gemini = AcpClient(command="gemini", args=["--experimental-acp"])
 ts_claude = AcpClient(command="npx", args=["@zed-industries/claude-code-acp"])
 ```
 
+### File Operation Handlers
+
+AcpClient supports intercepting file read/write operations for security or custom handling:
+
+```python
+@client.on_file_read
+async def handle_read(path: str) -> str | None:
+    """Intercept file reads. Return content to override, or None to proceed."""
+    print(f"📖 Reading: {path}")
+    return None  # Proceed with normal read
+
+@client.on_file_write
+async def handle_write(path: str, content: str) -> bool:
+    """Intercept file writes. Return True to allow, False to block."""
+    print(f"📝 Writing: {path}")
+    response = input("Allow write? [y/N]: ")
+    return response.lower() == "y"
+```
+
+### Terminal Operation Handlers
+
+AcpClient supports intercepting terminal/shell execution for security:
+
+```python
+@client.on_terminal_create
+async def handle_terminal(command: str, cwd: str) -> bool:
+    """Intercept shell commands. Return True to allow, False to block."""
+    print(f"🖥️ Command: {command} in {cwd}")
+    response = input("Allow execution? [y/N]: ")
+    return response.lower() == "y"
+
+@client.on_terminal_output
+async def handle_output(terminal_id: str, output: str) -> None:
+    """Receive terminal output in real-time."""
+    print(output, end="")
+```
+
 ### AcpClient vs ClaudeClient
 
 | Feature | `ClaudeClient` | `AcpClient` |

claude_code_acp-0.3.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+claude_code_acp/__init__.py,sha256=JSAUndeyZn-6EYXtA0MJMNj8fMiiuYFLGftwY2ERxVw,828
+claude_code_acp/__main__.py,sha256=zuAdIOmaCsDeRxj2yIl_qMx-74QFaA3nWiS8gti0og0,118
+claude_code_acp/acp_client.py,sha256=p2mmRB1Z1DaEGCkBznbLeKe_zUqrZOJMGCm17IW0gkE,25064
+claude_code_acp/agent.py,sha256=PuWPFhBlOSkdYCt4yuxSxI1i9gVy_FwvabkmDYyiHLA,23421
+claude_code_acp/client.py,sha256=jKi6tPNqNu0GWTsXxVa1BREGE1wkm_kbIEDulXKGDHE,10680
+claude_code_acp-0.3.4.dist-info/METADATA,sha256=TuTB5bpDj3UGmu06kIvJOabLYX_X_ZEu1zIR6vuoQr0,14940
+claude_code_acp-0.3.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claude_code_acp-0.3.4.dist-info/entry_points.txt,sha256=cc_pkg_V_1zctD5CUqjATCxglkf5-UArEMfN3q9We-A,57
+claude_code_acp-0.3.4.dist-info/licenses/LICENSE,sha256=5NCM9Q9UTfsn-VyafO7htdlYyPPO8H-NHYrO5UV9sT4,1064
+claude_code_acp-0.3.4.dist-info/RECORD,,

claude_code_acp-0.3.2.dist-info/RECORD

@@ -1,10 +0,0 @@
-claude_code_acp/__init__.py,sha256=Bn3jxHrGAiiY_tVo_OL083Y6pqGIHyoNBLFMVtcwYn4,828
-claude_code_acp/__main__.py,sha256=zuAdIOmaCsDeRxj2yIl_qMx-74QFaA3nWiS8gti0og0,118
-claude_code_acp/acp_client.py,sha256=E0e8XBco3cBV4sPi4txXpS13WPXRDodwYqHpXmCJd4A,12572
-claude_code_acp/agent.py,sha256=qos32gnMAilOlz6ebllkmuJZS3UgpbAtAZw58r3SYig,20619
-claude_code_acp/client.py,sha256=jKi6tPNqNu0GWTsXxVa1BREGE1wkm_kbIEDulXKGDHE,10680
-claude_code_acp-0.3.2.dist-info/METADATA,sha256=xILl5S_FH4TNyHro7VlLq65BbZSGxfr3s3LlfmzgDF4,13729
-claude_code_acp-0.3.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-claude_code_acp-0.3.2.dist-info/entry_points.txt,sha256=cc_pkg_V_1zctD5CUqjATCxglkf5-UArEMfN3q9We-A,57
-claude_code_acp-0.3.2.dist-info/licenses/LICENSE,sha256=5NCM9Q9UTfsn-VyafO7htdlYyPPO8H-NHYrO5UV9sT4,1064
-claude_code_acp-0.3.2.dist-info/RECORD,,