agent-shell-py 0.2.5__tar.gz → 0.3.0__tar.gz

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/AGENTS.md

@@ -8,6 +8,8 @@ A lightweight, async Python package that executes CLI coding agents headlessly a
 classDiagram
     class AgentShell {
         -AgentAdapter _adapter
+        +ExecutionHost execution_host
+        +IsolationPolicy isolation_policy
         +execute(cwd, prompt, ...) AgentResponse
         +stream(cwd, prompt, ...) AsyncIterator~StreamEvent~
         +health_check(cwd, model, timeout) HealthCheckResult
@@ -49,6 +51,8 @@ classDiagram
         +str session_id
         +float duration
         +int output_tokens
+        +int returncode
+        +int signal
     }
 
     class MCPServerSpec {
@@ -88,8 +92,39 @@ classDiagram
         +str session_id
         +int output_tokens
         +str error
+        +int returncode
+        +int signal
     }
 
+    class ExecutionHost {
+        <<Protocol>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
+    class NativeExecutionHost {
+        +launch(command, cwd, env, stdin, isolation_policy) NativeRunHandle
+    }
+
+    class IsolationPolicy {
+        <<Protocol>>
+        +prepare(command, env) PreparedLaunch
+    }
+
+    class NoIsolation
+    class LinuxPidNamespaceIsolation
+
+    class RunHandle {
+        <<Protocol>>
+        +int pid
+        +int returncode
+        +wait() int
+        +communicate(input) tuple
+        +cancel() None
+        +release() None
+    }
+
+    class NativeRunHandle
+
     class AgentType {
         <<StrEnum>>
         CLAUDE_CODE
@@ -98,9 +133,17 @@ classDiagram
         CODEX
         PI
         CURSOR
+        GROK
     }
 
     AgentShell --> AgentAdapter : delegates to
+    AgentShell --> ExecutionHost : selects
+    AgentShell --> IsolationPolicy : selects
+    NativeExecutionHost ..|> ExecutionHost : satisfies
+    NativeExecutionHost --> NativeRunHandle : creates
+    NativeRunHandle ..|> RunHandle : satisfies
+    NoIsolation ..|> IsolationPolicy : satisfies
+    LinuxPidNamespaceIsolation ..|> IsolationPolicy : satisfies
     AgentShell --> AgentType : resolves via
     ClaudeCodeAdapter ..|> AgentAdapter : satisfies
     AgentShell ..> AgentResponse : returns on success
@@ -112,7 +155,16 @@ classDiagram
     ClaudeCodeAdapter ..> StreamEvent : parses NDJSON into
 ```
 
-The adapter pattern uses Python's `Protocol` (structural typing) rather than ABC, so adapters satisfy the contract implicitly without inheritance. Each adapter manages its own subprocess lifecycle, translating agent-specific CLI flags and NDJSON output into the shared `StreamEvent`/`AgentResponse` models.
+The adapter pattern uses Python's `Protocol` (structural typing) rather than ABC, so adapters satisfy the contract implicitly without inheritance. Each adapter translates agent-specific CLI flags and NDJSON output into the shared `StreamEvent`/`AgentResponse` models, while the selected `ExecutionHost` owns process creation and returns a per-run `RunHandle`.
+
+Execution location and protection are separate axes. Existing callers default to
+`NativeExecutionHost()` plus `NoIsolation()`. `LinuxPidNamespaceIsolation` is an opt-in direct
+signal boundary: a tiny init/reaper is PID 1 and the CLI is PID 2 or later, so child-namespace
+processes cannot see or signal AgentShell's ancestors. It requires Linux, `unshare`, and enabled
+unprivileged user/PID namespaces; an unavailable explicit request raises
+`IsolationUnavailableError` and never falls back. This is not a general sandbox and does not
+restrict filesystem, credentials, network, tools, or resources. The host/policy applies to
+`execute()`, `stream()`, and `health_check()`; model discovery and MCP configuration remain local.
 
 `output_tokens` is a cost measure — the billed output-token count, which **includes reasoning tokens** (billed at the output rate). Each adapter normalises this so the value is consistent across agents (e.g. OpenCode reports reasoning in a sibling field, so its adapter adds it back).
 

agent_shell_py-0.2.5/README.md → agent_shell_py-0.3.0/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.5
+Name: agent-shell-py
+Version: 0.3.0
+Summary: A lightweight abstraction for executing CLI coding agents headlessly
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
 # Agent Shell
 Agent Shell is a light weight abstraction for executing a cli coding agent headlessly
 and returning the output that can be used programatically as a unified contract
@@ -10,6 +19,8 @@ and returning the output that can be used programatically as a unified contract
   behind a common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
   or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
+- **Composable execution policy** — preserve native execution by default, or opt into Linux PID
+  namespace isolation without changing an agent adapter.
 - **Session resumption** — continue any conversation by passing back its `session_id`.
 - **Normalized cost & tokens** — consistent `cost` and `output_tokens` (reasoning included)
   regardless of how each CLI reports them.
@@ -70,6 +81,40 @@ separately.
 
 ## Examples
 
+### Execution host and isolation
+
+Existing callers remain unchanged. Omitting both settings means
+`NativeExecutionHost()` plus `NoIsolation()`:
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+```
+
+To protect the AgentShell owner from broad same-user cleanup commands such as `pkill -f`,
+explicitly request Linux PID namespace isolation:
+
+```python
+from agent_shell.execution import LinuxPidNamespaceIsolation
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    isolation_policy=LinuxPidNamespaceIsolation(),
+)
+```
+
+The policy runs a tiny namespace init as PID 1 and the real CLI as PID 2 or later. Processes in
+that child namespace cannot see or signal AgentShell's ancestor processes. The feature requires
+Linux, the `unshare` command, and kernel support for unprivileged user/PID namespaces. If any are
+unavailable, launching raises `IsolationUnavailableError`; it never silently falls back.
+
+This is **direct-signal protection, not a sandbox**. It does not restrict files, credentials,
+network access, tools, or resource consumption. Any background descendants are also terminated
+when the isolated namespace ends. `execute()`, `stream()`, and `health_check()` use the selected
+host/policy; model discovery and MCP configuration remain local management operations.
+
+`NativeExecutionHost` is currently the only host implementation. Host and isolation are separate
+so future tmux/Herdr hosts can compose with policies without creating one class per combination.
+
 ### Execute
 
 ```python
@@ -108,7 +153,9 @@ follow_up = await shell.execute(
 `execute()` raises `AgentExecutionError` instead of returning when a run failed — an `error`
 event was emitted, the terminal `result` had `content == "error"`, or no terminal `result`
 arrived at all. `str(e)` is the bare reason; the exception also carries whatever partial
-`response`/`cost`/`session_id`/`duration`/`output_tokens` the run produced before failing.
+`response`/`cost`/`session_id`/`duration`/`output_tokens` the run produced before failing. When
+the CLI process itself exits unsuccessfully, `returncode` is also populated; signal termination
+uses Python's negative-returncode convention and supplies the positive signal number separately.
 
 ```python
 from agent_shell.models.agent import AgentExecutionError
@@ -117,6 +164,7 @@ try:
     response = await shell.execute(cwd="/path/to/project", prompt="Fix the failing test")
 except AgentExecutionError as e:
     print(f"run failed: {e}")   # e.g. "500 model name=qwen3.6-27b-8Q failed to load"
+    print(e.returncode, e.signal)  # e.g. -15, 15 for SIGTERM; otherwise None when unavailable
 ```
 
 ### Stream

agent_shell_py-0.2.5/PKG-INFO → agent_shell_py-0.3.0/README.md

@@ -1,12 +1,3 @@
-Metadata-Version: 2.4
-Name: agent-shell-py
-Version: 0.2.5
-Summary: A lightweight abstraction for executing CLI coding agents headlessly
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
 # Agent Shell
 Agent Shell is a light weight abstraction for executing a cli coding agent headlessly
 and returning the output that can be used programatically as a unified contract
@@ -19,6 +10,8 @@ and returning the output that can be used programatically as a unified contract
   behind a common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
   or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
+- **Composable execution policy** — preserve native execution by default, or opt into Linux PID
+  namespace isolation without changing an agent adapter.
 - **Session resumption** — continue any conversation by passing back its `session_id`.
 - **Normalized cost & tokens** — consistent `cost` and `output_tokens` (reasoning included)
   regardless of how each CLI reports them.
@@ -79,6 +72,40 @@ separately.
 
 ## Examples
 
+### Execution host and isolation
+
+Existing callers remain unchanged. Omitting both settings means
+`NativeExecutionHost()` plus `NoIsolation()`:
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+```
+
+To protect the AgentShell owner from broad same-user cleanup commands such as `pkill -f`,
+explicitly request Linux PID namespace isolation:
+
+```python
+from agent_shell.execution import LinuxPidNamespaceIsolation
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    isolation_policy=LinuxPidNamespaceIsolation(),
+)
+```
+
+The policy runs a tiny namespace init as PID 1 and the real CLI as PID 2 or later. Processes in
+that child namespace cannot see or signal AgentShell's ancestor processes. The feature requires
+Linux, the `unshare` command, and kernel support for unprivileged user/PID namespaces. If any are
+unavailable, launching raises `IsolationUnavailableError`; it never silently falls back.
+
+This is **direct-signal protection, not a sandbox**. It does not restrict files, credentials,
+network access, tools, or resource consumption. Any background descendants are also terminated
+when the isolated namespace ends. `execute()`, `stream()`, and `health_check()` use the selected
+host/policy; model discovery and MCP configuration remain local management operations.
+
+`NativeExecutionHost` is currently the only host implementation. Host and isolation are separate
+so future tmux/Herdr hosts can compose with policies without creating one class per combination.
+
 ### Execute
 
 ```python
@@ -117,7 +144,9 @@ follow_up = await shell.execute(
 `execute()` raises `AgentExecutionError` instead of returning when a run failed — an `error`
 event was emitted, the terminal `result` had `content == "error"`, or no terminal `result`
 arrived at all. `str(e)` is the bare reason; the exception also carries whatever partial
-`response`/`cost`/`session_id`/`duration`/`output_tokens` the run produced before failing.
+`response`/`cost`/`session_id`/`duration`/`output_tokens` the run produced before failing. When
+the CLI process itself exits unsuccessfully, `returncode` is also populated; signal termination
+uses Python's negative-returncode convention and supplies the positive signal number separately.
 
 ```python
 from agent_shell.models.agent import AgentExecutionError
@@ -126,6 +155,7 @@ try:
     response = await shell.execute(cwd="/path/to/project", prompt="Fix the failing test")
 except AgentExecutionError as e:
     print(f"run failed: {e}")   # e.g. "500 model name=qwen3.6-27b-8Q failed to load"
+    print(e.returncode, e.signal)  # e.g. -15, 15 for SIGTERM; otherwise None when unavailable
 ```
 
 ### Stream

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/docs/development/info.md

@@ -61,8 +61,9 @@ uv run pytest tests/e2e -v
 
 > [!WARNING]
 > E2E tests may mutate real user configuration files. MCP tests can call an agent's real
-> `mcp add` and `mcp remove` commands, affecting files such as `~/.claude.json`,
-> `~/.config/opencode/opencode.json`, `~/.copilot/mcp-config.json`, or Codex configuration.
+> MCP commands or edit its config directly, affecting files such as `~/.claude.json`,
+> `~/.config/opencode/opencode.json`, `~/.copilot/mcp-config.json`, `~/.cursor/mcp.json`,
+> or Codex configuration.
 > Tests use unique names and `finally` cleanup where implemented, but forced termination,
 > a CLI crash, or a machine failure can prevent cleanup. The CLI may also rewrite config
 > formatting even when the temporary entry is removed. Review the selected E2E test before

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/skills/invoking-cli-agents/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   restricting tools, or checking agent/model health. Supports Claude Code, OpenCode,
   Copilot CLI, Codex, Pi, Cursor, and Grok. Keywords: AgentShell, list_models, headless
   agent, model discovery, subprocess, allowed_tools, disallowed_tools, session_id, cost,
-  output_tokens.
+  output_tokens, execution host, PID namespace, isolation policy.
 ---
 
 # Invoking CLI Agents with AgentShell
@@ -44,7 +44,44 @@ uv add agent-shell-py
 
 AgentShell has two invocation methods — `execute()` collects a complete response, `stream()`
 yields events in real-time — plus helpers for model discovery, health checks, and MCP server
-management. All are async.
+management. All are async. Invocation has three independent choices:
+
+- `agent_type`: which CLI (Claude Code, Codex, etc.)
+- `execution_host`: where/how the process is owned (`NativeExecutionHost` today)
+- `isolation_policy`: what protection surrounds it (`NoIsolation` or Linux PID isolation)
+
+### Execution Host and Isolation Policy
+
+Existing code is backward-compatible: omitting both execution settings selects native execution
+with no isolation.
+
+```python
+shell = AgentShell(agent_type=AgentType.CODEX)
+# Equivalent to NativeExecutionHost() + NoIsolation()
+```
+
+Opt into direct-signal protection when an agent may run broad same-user cleanup commands such as
+`pkill -f`:
+
+```python
+from agent_shell.execution import LinuxPidNamespaceIsolation
+
+shell = AgentShell(
+    agent_type=AgentType.CODEX,
+    isolation_policy=LinuxPidNamespaceIsolation(),
+)
+```
+
+The Linux policy puts a tiny init/reaper at namespace PID 1 and the actual CLI at PID 2 or later.
+The CLI cannot see or signal AgentShell's ancestor processes. It requires Linux, `unshare`, and
+kernel support for unprivileged user/PID namespaces. An unavailable requested policy raises
+`IsolationUnavailableError` before the CLI starts; AgentShell never silently falls back.
+
+This policy is **not a sandbox**: filesystem, credentials, network, agent tools, and resource use
+remain available. Background descendants cannot outlive the isolated namespace. It applies to
+`execute()`, `stream()`, and `health_check()`; `list_models()` and MCP configuration are local
+management operations. `NativeExecutionHost` is the only shipped host today. Tmux and Herdr are
+future host possibilities, not current APIs.
 
 ### Discover Available Model Strings
 
@@ -117,6 +154,7 @@ async for event in shell.stream(
         print(event.content)
     elif event.type == "error":
         print(f"[error] {event.content}")
+        print(event.returncode, event.signal)  # populated for process-level failures
     elif event.type == "result":
         print(f"Done ({event.content}). Cost: ${event.cost:.4f}, {event.output_tokens} tok")
 ```
@@ -187,7 +225,7 @@ Capabilities differ by agent. `output_tokens` is populated on all of them; the r
 | Copilot CLI | ✅ | ⚠️ `bash`, `edit` only | ✅ | ❌ `0.0` | ✅ real | ✅ |
 | Codex | ❌ | ⚠️ `web_search` only | ✅ | ❌ `0.0` | ❌ `0.0` | ✅ |
 | Pi | ✅ | ⚠️ `bash`, `edit`, `read` | ✅ | ⚠️ paid providers only | ❌ `0.0` | ❌ raises |
-| Cursor | ❌ warns | ❌ none — warns | ❌ warns | ❌ `0.0` | ✅ real | ❌ raises |
+| Cursor | ❌ warns | ❌ none — warns | ❌ warns | ❌ `0.0` | ✅ real | ✅ user-scope |
 | Grok | ✅ | ✅ all canonical | ✅ | ⚠️ may be `0.0` | ✅ real | ✅ user-scope |
 
 A `✅` for `allowed_tools` means the flag is passed — but it only *enforces* with
@@ -271,6 +309,7 @@ except AgentExecutionError as e:
     print(f"failed: {e}")               # str(e) == e.reason, the bare cause
     print(e.response)                   # text produced before the failure, if any
     print(e.cost, e.session_id, e.duration, e.output_tokens)
+    print(e.returncode, e.signal)       # -15 and 15 for SIGTERM; None if not process-derived
 else:
     print(response.response)
 ```
@@ -347,6 +386,7 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | See agent thinking | `include_thinking=True` in `stream()` |
 | Check an agent/model works | `await shell.health_check(cwd, model=...)` |
 | Cancel a running agent | `KeyboardInterrupt` (handled automatically) |
+| Protect the owner from broad process kills | `isolation_policy=LinuxPidNamespaceIsolation()` |
 
 ## Common Mistakes
 
@@ -366,6 +406,8 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | Not catching `AgentExecutionError` | `execute()` raises on a failed run — catch it |
 | Ignoring `UserWarning` on a deny | An unenforceable deny is warned, not applied — the tool is NOT blocked |
 | Ignoring `session_id` for multi-step work | Without it, each call starts fresh |
+| Treating PID isolation as a sandbox | It only blocks direct signalling of ancestors; separately restrict files, network, credentials, tools, and resources |
+| Assuming isolation silently degrades | Requested isolation raises `IsolationUnavailableError` when unavailable; catch it or fail the operation |
 
 ## API Reference
 

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/skills/invoking-cli-agents/api-reference.md

@@ -4,6 +4,7 @@
   `MCPServerSpec`, `HealthCheckResult`
 - [StreamEvent types](#event-types)
 - [AgentShell class](#agentshell-class) — invocation, model discovery, health, MCP management
+- [Execution hosts and isolation](#execution-hosts-and-isolation)
 - [AgentAdapter protocol](#agentadapter-protocol)
 - [Agent-specific notes](#agent-specific-notes)
 
@@ -58,6 +59,8 @@ class AgentExecutionError(Exception):
         session_id: str | None = None,
         duration: float = 0.0,
         output_tokens: int = 0,
+        returncode: int | None = None,  # raw process status; negative means signal
+        signal: int | None = None,      # positive signal number for signal termination
     ): ...
 ```
 
@@ -75,6 +78,8 @@ class StreamEvent:
     session_id: str | None = None  # On session-start and "result" events
     output_tokens: int = 0   # Cumulative generated tokens (on "result" events)
     error: str | None = None # Why a failing "result" failed, when recoverable (Pi)
+    returncode: int | None = None  # Set on process-level "error" events
+    signal: int | None = None      # Positive signal number when returncode is negative
 ```
 
 ### MCPServerSpec
@@ -124,7 +129,8 @@ Canonical event types emitted by `stream()`:
 
 > A `result` event carries `cost`, `duration`, `output_tokens` and `session_id` on the agents
 > that report them. On a failing result, `error` holds the reason when the adapter recovered a
-> structured one (Pi); it is `None` otherwise.
+> structured one (Pi); it is `None` otherwise. A process-level `error` also carries
+> `returncode`; if a signal terminated it, `returncode` is negative and `signal` is positive.
 
 > Codex emits the session-start event as `type="session"` (not `"system"`). If you branch on
 > the session event across agents, match both.
@@ -140,7 +146,12 @@ Canonical event types emitted by `stream()`:
 from agent_shell.shell import AgentShell
 
 class AgentShell:
-    def __init__(self, agent_type: AgentType): ...
+    def __init__(
+        self,
+        agent_type: AgentType,
+        execution_host: ExecutionHost | None = None,      # default NativeExecutionHost()
+        isolation_policy: IsolationPolicy | None = None,  # default NoIsolation()
+    ): ...
     # raises ValueError for an AgentType with no registered adapter
 
     async def execute(
@@ -174,6 +185,38 @@ class AgentShell:
     async def list_mcp_servers(self) -> list[MCPServerSpec]: ...
 ```
 
+## Execution Hosts and Isolation
+
+```python
+from agent_shell.execution import (
+    ExecutionHost,
+    IsolationPolicy,
+    IsolationUnavailableError,
+    LinuxPidNamespaceIsolation,
+    NativeExecutionHost,
+    NativeRunHandle,
+    NoIsolation,
+    PreparedLaunch,
+    RunHandle,
+)
+```
+
+`ExecutionHost` creates a `RunHandle` for one command. The handle exposes `pid`, `stdin`,
+`stdout`, `stderr`, `returncode`, `wait()`, `communicate()`, `cancel()`, and `release()`.
+`NativeExecutionHost` is currently the only concrete host. Agent adapters use handles internally;
+existing `execute()` and `stream()` callers do not need to manage them.
+
+`NoIsolation` preserves historical native execution. `LinuxPidNamespaceIsolation` uses rootless
+user + PID namespaces, with a tiny PID 1 reaper and the CLI at PID 2 or later. It protects
+AgentShell's ancestors from direct same-user signals sent inside the child namespace. It is not a
+filesystem, credential, network, tool, resource, or general security sandbox. Background
+descendants terminate when the namespace ends.
+
+The Linux policy requires `unshare` and supporting kernel configuration. An explicit request that
+cannot be satisfied raises `IsolationUnavailableError` before launching the CLI and never falls
+back to `NoIsolation`. The host/policy selection applies to `execute()`, `stream()`, and
+`health_check()`; model discovery and MCP configuration remain local management operations.
+
 ### Model discovery semantics
 
 `list_models()` reads the selected CLI's account/workspace-aware catalog without sending an
@@ -273,8 +316,11 @@ class AgentAdapter(Protocol):
   it rather than failing (like Pi; unlike Claude Code, OpenCode, Copilot and Codex, which all
   reject one). A matching id is therefore not proof a prior transcript was continued.
 - `duration` and `output_tokens` are real (`usage.outputTokens`); `cost` is always `0.0` — Cursor
-  reports no cost. MCP-management methods raise `NotImplementedError` (`cursor-agent mcp` has no
-  add/remove, and its `list` returns only name+status, which cannot rebuild an `MCPServerSpec`).
+  reports no cost.
+- MCP add/remove/list are supported by directly managing user-scope `~/.cursor/mcp.json`, because
+  `cursor-agent mcp` has no add/remove subcommands and its list output lacks full configuration.
+  Writes are atomic and user-only. Same-transport updates preserve Cursor-native fields that
+  `MCPServerSpec` cannot represent.
 
 ### Grok
 - Headless: `grok -p --output-format streaming-messages-json` (full assistant blocks; not

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/src/agent_shell/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.5'
-__version_tuple__ = version_tuple = (0, 2, 5)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.2.5 → agent_shell_py-0.3.0}/src/agent_shell/adapters/claude_code_adapter.py

@@ -1,12 +1,24 @@
 import asyncio
 import codecs
 import json
-import os
 import logging
+import os
 import warnings
 from pathlib import Path
 from typing import AsyncIterator
 
+from agent_shell.adapters.health import run_health_probe
+from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
+from agent_shell.adapters.process_failure import process_failure_event
+from agent_shell.adapters.response import collect_response
+from agent_shell.adapters.stderr_format import format_stderr
+from agent_shell.adapters.tool_denial import resolve_disallowed_tools
+from agent_shell.execution import (
+    ExecutionHost,
+    IsolationPolicy,
+    NativeExecutionHost,
+    NoIsolation,
+)
 from agent_shell.models.agent import (
     AgentResponse,
     HealthCheckResult,
@@ -15,15 +27,8 @@ from agent_shell.models.agent import (
     StreamEvent,
 )
 from agent_shell.process_cleanup import (
-    create_grouped_process,
-    kill_process_group,
     release_process,
 )
-from agent_shell.adapters.health import run_health_probe
-from agent_shell.adapters.model_discovery import decode_model_output, run_model_command
-from agent_shell.adapters.response import collect_response
-from agent_shell.adapters.stderr_format import format_stderr
-from agent_shell.adapters.tool_denial import resolve_disallowed_tools
 
 logger = logging.getLogger("agent_shell.claude_code_adapter")
 
@@ -38,8 +43,18 @@ _DISALLOWED_TOOL_MAP = {
 }
 
 class ClaudeCodeAdapter():
-    def __init__(self):
+    def __init__(
+            self,
+            execution_host: ExecutionHost | None = None,
+            isolation_policy: IsolationPolicy | None = None,
+    ):
         self._active_processes = []
+        self._execution_host = (
+            execution_host if execution_host is not None else NativeExecutionHost()
+        )
+        self._isolation_policy = (
+            isolation_policy if isolation_policy is not None else NoIsolation()
+        )
 
     async def execute(
             self,
@@ -114,9 +129,10 @@ class ClaudeCodeAdapter():
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        process = await create_grouped_process(
+        process = await self._execution_host.launch(
             cmd,
             cwd=os.path.abspath(cwd),
+            isolation_policy=self._isolation_policy,
         )
 
         self._active_processes.append(process)
@@ -174,10 +190,10 @@ class ClaudeCodeAdapter():
             child_exited = True
 
             stderr = await stderr_task
-            if stderr and process.returncode != 0:
-                error_msg = format_stderr(stderr)
-                logger.warning("Process exited with code %d: %s", process.returncode, error_msg)
-                yield StreamEvent(type="error", content=error_msg)
+            failure = process_failure_event(process.returncode, stderr)
+            if failure is not None:
+                logger.warning("Process failed (%d): %s", process.returncode, failure.content)
+                yield failure
         finally:
             # Teardown must live here, not after the read loop: on an exception, or when the
             # consumer abandons the stream, the normal path never runs and the still-running
@@ -188,8 +204,8 @@ class ClaudeCodeAdapter():
             # the child is still alive and still registered until a later turn of the loop, and
             # if the loop is torn down first (asyncio.run cancelling pending tasks) it never
             # runs at all. That last case is what the atexit net in process_cleanup covers.
-            release_process(process, self._active_processes, stderr_task,
-                            child_exited=child_exited)
+            await release_process(process, self._active_processes, stderr_task,
+                                  child_exited=child_exited)
 
     def _parse_event(self, event: dict, include_thinking: bool) -> list[StreamEvent]:
         t = event.get("type", "")
@@ -229,9 +245,10 @@ class ClaudeCodeAdapter():
         return events
 
     async def cancel(self) -> None:
-        for process in self._active_processes:
-            kill_process_group(process)
+        processes = list(self._active_processes)
         self._active_processes.clear()
+        for process in processes:
+            await process.cancel()
 
     async def health_check(
             self,
@@ -437,5 +454,3 @@ class ClaudeCodeAdapter():
         return {"returncode": process.returncode, "stdout": stdout_text, "stderr": stderr_text}
 
                 
-
-