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

{agent_shell_py-0.2.4 → 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).
 
@@ -171,9 +223,19 @@ All adapters write to user-scope configuration:
 | OpenCode | direct JSON file write | `~/.config/opencode/opencode.json` |
 | Copilot CLI | direct JSON file write | `~/.copilot/mcp-config.json` |
 | Codex | `codex mcp add` subprocess | Codex config |
+| Cursor | direct JSON file write | `~/.cursor/mcp.json` |
 | Grok | `grok mcp add --scope user` subprocess | `~/.grok/config.toml` (managed by CLI) |
 
-Adds are idempotent (overwrite existing entries with the same name). Removes warn rather than raise when the named server is not found. Claude Code listing reads the user-scope `mcpServers` entries from `~/.claude.json` directly, avoiding the health checks and human-readable output of `claude mcp list`. Grok listing reads user-scope `mcp_servers` entries from `~/.grok/config.toml` directly for the same reason. MCP is not implemented for Pi or Cursor — all three methods raise `NotImplementedError`. Pi manages capability via `pi install` extensions (which needs investigation before wiring up); Cursor's `mcp` subcommands are login/list/list-tools/enable/disable only (no add/remove — servers are declared in `.cursor/mcp.json`), and `mcp list` reports only `name: status`, not the transport an `MCPServerSpec` needs.
+Adds are idempotent (update existing entries with the same name). Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport, and writes its file
+atomically with user-only permissions. Removes warn rather than raise when the named server is not
+found. Claude Code listing reads the user-scope `mcpServers`
+entries from `~/.claude.json` directly, avoiding the health checks and human-readable output of
+`claude mcp list`. Cursor manages user-scope MCP entries directly in `~/.cursor/mcp.json` because
+its `mcp` subcommands have no add/remove commands. Grok listing reads user-scope `mcp_servers`
+entries from `~/.grok/config.toml` directly for the same reason. Pi's MCP add/remove/list methods
+raise `NotImplementedError`. Pi manages capability via `pi install` extensions, which needs
+investigation before wiring up.
 
 ## Test Philosophy
 

{agent_shell_py-0.2.4 → agent_shell_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agent-shell-py
-Version: 0.2.4
+Version: 0.3.0
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE
@@ -19,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.
@@ -79,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
@@ -117,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
@@ -126,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
@@ -276,8 +315,9 @@ print(f"Session: {response.session_id}")
 > tools are auto-*rejected* but the run still completes. `allowed_tools`, `effort`, and
 > `disallowed_tools` are **ignored** — Cursor exposes no per-call tool policy or effort flag
 > (tool policy lives in `.cursor/cli.json`), so each emits a `UserWarning`. On a Free plan
-> only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
-> `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
+> only `model=None`/`"auto"` works. MCP add/remove/list are supported by directly managing
+> the user-scope `~/.cursor/mcp.json` file because `cursor-agent mcp` has no add/remove
+> subcommands.
 
 ### Grok
 
@@ -348,7 +388,14 @@ await shell.add_mcp_server(MCPServerSpec(
 ))
 ```
 
-`add_mcp_server` overwrites an existing server with the same name. `remove_mcp_server` warns rather than raises when the named server is not found. `list_mcp_servers()` works for Claude Code, OpenCode, Copilot CLI, Codex, and Grok. Claude Code reads user-scope entries directly from `~/.claude.json`, and Grok from `~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP is not supported for Pi or Cursor — neither CLI exposes an add/remove subcommand, so all three MCP methods raise `NotImplementedError`.
+`add_mcp_server` adds or updates a server with the same name. Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport. The configuration
+is written atomically with user-only permissions. `remove_mcp_server` warns rather than raises
+when the named server is not found. `list_mcp_servers()` works for
+Claude Code, OpenCode, Copilot CLI, Codex, Cursor, and Grok. Claude Code reads user-scope
+entries directly from `~/.claude.json`, Cursor from `~/.cursor/mcp.json`, and Grok from
+`~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP
+is not supported for Pi; all three MCP methods raise `NotImplementedError`.
 
 ## Logging
 

{agent_shell_py-0.2.4 → agent_shell_py-0.3.0}/README.md

@@ -10,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.
@@ -70,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
@@ -108,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
@@ -117,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
@@ -267,8 +306,9 @@ print(f"Session: {response.session_id}")
 > tools are auto-*rejected* but the run still completes. `allowed_tools`, `effort`, and
 > `disallowed_tools` are **ignored** — Cursor exposes no per-call tool policy or effort flag
 > (tool policy lives in `.cursor/cli.json`), so each emits a `UserWarning`. On a Free plan
-> only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
-> `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
+> only `model=None`/`"auto"` works. MCP add/remove/list are supported by directly managing
+> the user-scope `~/.cursor/mcp.json` file because `cursor-agent mcp` has no add/remove
+> subcommands.
 
 ### Grok
 
@@ -339,7 +379,14 @@ await shell.add_mcp_server(MCPServerSpec(
 ))
 ```
 
-`add_mcp_server` overwrites an existing server with the same name. `remove_mcp_server` warns rather than raises when the named server is not found. `list_mcp_servers()` works for Claude Code, OpenCode, Copilot CLI, Codex, and Grok. Claude Code reads user-scope entries directly from `~/.claude.json`, and Grok from `~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP is not supported for Pi or Cursor — neither CLI exposes an add/remove subcommand, so all three MCP methods raise `NotImplementedError`.
+`add_mcp_server` adds or updates a server with the same name. Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport. The configuration
+is written atomically with user-only permissions. `remove_mcp_server` warns rather than raises
+when the named server is not found. `list_mcp_servers()` works for
+Claude Code, OpenCode, Copilot CLI, Codex, Cursor, and Grok. Claude Code reads user-scope
+entries directly from `~/.claude.json`, Cursor from `~/.cursor/mcp.json`, and Grok from
+`~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP
+is not supported for Pi; all three MCP methods raise `NotImplementedError`.
 
 ## Logging
 

{agent_shell_py-0.2.4 → agent_shell_py-0.3.0}/docs/development/agent_parameter_comparison.md

@@ -128,9 +128,9 @@ test checks all seven real discovery commands.
 - **Headless mode**: `-p` / `--prompt` for one-shot; `--acp` for Agent Client Protocol
 - **Model**: `--model <model>`; use `auto` to let Copilot choose
 - **Effort**: `--effort` / `--reasoning-effort` with choices
-  `none|minimal|low|medium|high|xhigh|max`. AgentShell accepts effort values
-  case-insensitively, validates them against these choices, and passes the normalized lowercase
-  value to Copilot via `--effort`.
+  `none|minimal|low|medium|high|xhigh|max`. AgentShell treats `None` and `""` as omitted, so
+  Copilot uses its default. Explicit values, including `"none"`, are accepted case-insensitively,
+  validated against these choices, and passed to Copilot via `--effort` in lowercase.
 - **Allowed tools**: `--allow-tool`, `--deny-tool`, `--available-tools`,
   `--excluded-tools`, `--allow-all-tools`
 - **Auto-approve**: `--allow-all-tools`; `--allow-all` / `--yolo` also grant path and URL
@@ -193,10 +193,10 @@ test checks all seven real discovery commands.
   cursor-agent ACCEPTS an unknown id — `--resume=<never-seen-uuid>` starts a session under that
   id and echoes it back rather than failing, so id identity proves the flag was passed through
   and honoured, not that a prior transcript was replayed (measured 2026-07-26)
-- **MCP**: `cursor-agent mcp` = login/list/list-tools/enable/disable only (no add/remove);
-  servers declared in `.cursor/mcp.json`. All three adapter MCP methods raise
-  `NotImplementedError` — including `list_mcp_servers`, because `mcp list` emits only
-  `name: status` and cannot rebuild an `MCPServerSpec`
+- **MCP**: `cursor-agent mcp` = login/list/list-tools/enable/disable only (no add/remove).
+  The adapter manages user-scope servers directly in `~/.cursor/mcp.json`, which provides the
+  transport details that `mcp list` omits. Writes are atomic and user-only; same-transport
+  updates preserve Cursor-native fields that `MCPServerSpec` cannot represent.
 - **Usage**: the terminal `result` event carries `usage.outputTokens` (undocumented but real)
   and `duration_ms`; there is no cost field, so `cost` is `0.0`
 

{agent_shell_py-0.2.4 → 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.4 → 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)
 ```
@@ -316,7 +355,8 @@ succeeded = saw_ok and error is None         # absent result => succeeded stays
   **not** run your prompt, so use the stream-based check above when you care about a specific
   call's outcome.
 - **MCP server management** — `add_mcp_server`, `remove_mcp_server`, `list_mcp_servers` manage
-  the underlying CLI's MCP config (Pi and Cursor raise `NotImplementedError`).
+  user-scope MCP configuration. Pi raises `NotImplementedError`; Cursor is managed directly
+  through `~/.cursor/mcp.json` because `cursor-agent mcp` has no add/remove subcommands.
 
 See [api-reference.md](api-reference.md) for their full signatures and the `MCPServerSpec` model.
 
@@ -346,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
 
@@ -365,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.4 → 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.4 → 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.4'
-__version_tuple__ = version_tuple = (0, 2, 4)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None