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

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

@@ -158,12 +158,14 @@ classDiagram
 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
+`NativeExecutionHost()` plus `NoIsolation()` when `AGENTSHELL_ISOLATION_POLICY` is unset. The
+environment accepts `none` or `linux-pid-namespace` as a process-wide construction default;
+explicit `isolation_policy=` takes precedence, and invalid or empty values raise `ValueError`.
+`LinuxPidNamespaceIsolation` is a 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 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.3.0/README.md → agent_shell_py-0.3.1/PKG-INFO

@@ -1,3 +1,12 @@
+Metadata-Version: 2.5
+Name: agent-shell-py
+Version: 0.3.1
+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
@@ -74,13 +83,24 @@ separately.
 
 ### Execution host and isolation
 
-Existing callers remain unchanged. Omitting both settings means
-`NativeExecutionHost()` plus `NoIsolation()`:
+Existing callers remain unchanged when `AGENTSHELL_ISOLATION_POLICY` is unset. Omitting both
+constructor settings then means `NativeExecutionHost()` plus `NoIsolation()`:
 
 ```python
 shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
 ```
 
+Set a process-wide deployment default without changing Python call sites:
+
+```bash
+export AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace
+```
+
+The accepted values are `none` and `linux-pid-namespace`. AgentShell reads the value when each
+shell is constructed. An empty or unknown value raises `ValueError` rather than silently disabling
+isolation. An explicit constructor policy takes precedence over the environment, so a caller can
+still force one shell to use `NoIsolation()` or a custom policy.
+
 To protect the AgentShell owner from broad same-user cleanup commands such as `pkill -f`,
 explicitly request Linux PID namespace isolation:
 

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

@@ -1,12 +1,3 @@
-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
@@ -83,13 +74,24 @@ separately.
 
 ### Execution host and isolation
 
-Existing callers remain unchanged. Omitting both settings means
-`NativeExecutionHost()` plus `NoIsolation()`:
+Existing callers remain unchanged when `AGENTSHELL_ISOLATION_POLICY` is unset. Omitting both
+constructor settings then means `NativeExecutionHost()` plus `NoIsolation()`:
 
 ```python
 shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
 ```
 
+Set a process-wide deployment default without changing Python call sites:
+
+```bash
+export AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace
+```
+
+The accepted values are `none` and `linux-pid-namespace`. AgentShell reads the value when each
+shell is constructed. An empty or unknown value raises `ValueError` rather than silently disabling
+isolation. An explicit constructor policy takes precedence over the environment, so a caller can
+still force one shell to use `NoIsolation()` or a custom policy.
+
 To protect the AgentShell owner from broad same-user cleanup commands such as `pkill -f`,
 explicitly request Linux PID namespace isolation:
 

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

@@ -52,14 +52,24 @@ management. All are async. Invocation has three independent choices:
 
 ### Execution Host and Isolation Policy
 
-Existing code is backward-compatible: omitting both execution settings selects native execution
-with no isolation.
+Existing code is backward-compatible: when `AGENTSHELL_ISOLATION_POLICY` is unset, omitting both
+execution settings selects native execution with no isolation.
 
 ```python
 shell = AgentShell(agent_type=AgentType.CODEX)
 # Equivalent to NativeExecutionHost() + NoIsolation()
 ```
 
+For a process-wide deployment default, set the environment before constructing a shell:
+
+```bash
+export AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace
+```
+
+Accepted values are `none` and `linux-pid-namespace`. Empty or unknown values raise `ValueError`.
+An explicit `isolation_policy=` object wins over the environment, which remains the way to select
+a custom policy or override the deployment default for one shell.
+
 Opt into direct-signal protection when an agent may run broad same-user cleanup commands such as
 `pkill -f`:
 

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

@@ -150,7 +150,7 @@ class AgentShell:
         self,
         agent_type: AgentType,
         execution_host: ExecutionHost | None = None,      # default NativeExecutionHost()
-        isolation_policy: IsolationPolicy | None = None,  # default NoIsolation()
+        isolation_policy: IsolationPolicy | None = None,  # env setting, then NoIsolation()
     ): ...
     # raises ValueError for an AgentType with no registered adapter
 
@@ -212,6 +212,11 @@ AgentShell's ancestors from direct same-user signals sent inside the child names
 filesystem, credential, network, tool, resource, or general security sandbox. Background
 descendants terminate when the namespace ends.
 
+When `isolation_policy` is omitted, `AgentShell` reads `AGENTSHELL_ISOLATION_POLICY` at
+construction. The accepted values are `none` and `linux-pid-namespace`; if the variable is absent,
+the default remains `NoIsolation`. Empty or unknown values raise `ValueError`. Passing an explicit
+policy object takes precedence over the environment.
+
 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

{agent_shell_py-0.3.0 → agent_shell_py-0.3.1}/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.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.3.1'
+__version_tuple__ = version_tuple = (0, 3, 1)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.3.0 → agent_shell_py-0.3.1}/src/agent_shell/shell.py

@@ -1,4 +1,5 @@
 import asyncio
+import os
 from pathlib import Path
 from typing import AsyncIterator
 
@@ -13,6 +14,7 @@ from agent_shell.adapters.pi_adapter import PiAdapter
 from agent_shell.execution import (
     ExecutionHost,
     IsolationPolicy,
+    LinuxPidNamespaceIsolation,
     NativeExecutionHost,
     NoIsolation,
 )
@@ -37,6 +39,22 @@ _ADAPTERS: dict[AgentType, type[AgentAdapter]] = {
         AgentType.GROK: GrokAdapter,
 }
 
+_ISOLATION_POLICY_ENV = "AGENTSHELL_ISOLATION_POLICY"
+
+
+def _isolation_policy_from_environment() -> IsolationPolicy:
+    value = os.environ.get(_ISOLATION_POLICY_ENV)
+    if value is None:
+        return NoIsolation()
+    if value == "none":
+        return NoIsolation()
+    if value == "linux-pid-namespace":
+        return LinuxPidNamespaceIsolation()
+    raise ValueError(
+        f"Unsupported {_ISOLATION_POLICY_ENV} value {value!r}: "
+        "expected 'none' or 'linux-pid-namespace'"
+    )
+
 
 class AgentShell():
     def __init__(
@@ -49,7 +67,9 @@ class AgentShell():
             execution_host if execution_host is not None else NativeExecutionHost()
         )
         self.isolation_policy = (
-            isolation_policy if isolation_policy is not None else NoIsolation()
+            isolation_policy
+            if isolation_policy is not None
+            else _isolation_policy_from_environment()
         )
         self._adapter = self._resolve_adapter(agent_type=agent_type)
 

{agent_shell_py-0.3.0 → agent_shell_py-0.3.1}/tests/conftest.py

@@ -4,6 +4,12 @@ import pytest
 from agent_shell import process_cleanup
 
 
+@pytest.fixture(autouse=True)
+def isolate_agentshell_environment(monkeypatch):
+    """Keep deployment-level AgentShell configuration explicit in each test."""
+    monkeypatch.delenv("AGENTSHELL_ISOLATION_POLICY", raising=False)
+
+
 @pytest.fixture(autouse=True)
 def isolate_process_group_registry():
     """Give every test an isolated guardian registry and close anything it leaks."""

{agent_shell_py-0.3.0 → agent_shell_py-0.3.1}/tests/integration/test_process_lifecycle.py

@@ -510,6 +510,27 @@ async def test_agentshell_applies_the_requested_pid_isolation(fake_cli, tmp_path
     assert response.response == ""
 
 
+async def test_agentshell_applies_pid_isolation_selected_by_environment(
+        fake_cli, tmp_path, monkeypatch):
+    # Arrange — exercise the deployment-level configuration through the public AgentShell
+    # boundary. Namespace PID 2 proves the selected policy reached the real CLI process.
+    monkeypatch.setenv(
+        "AGENTSHELL_ISOLATION_POLICY",
+        "linux-pid-namespace",
+    )
+    shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+    fake_cli(stdout=[OK_RESULT_EVENT[ClaudeCodeAdapter]], required_pid=2)
+
+    # Act
+    try:
+        response = await shell.execute(cwd=str(tmp_path), prompt="ping")
+    except IsolationUnavailableError as error:
+        pytest.skip(str(error))
+
+    # Assert
+    assert response.response == ""
+
+
 @pytest.mark.parametrize("adapter_cls", ADAPTERS)
 async def test_cancelled_agent_shell_stream_kills_the_real_process_tree(
         adapter_cls, fake_cli, tmp_path):

{agent_shell_py-0.3.0 → agent_shell_py-0.3.1}/tests/unit/test_shell.py

@@ -8,12 +8,52 @@ from agent_shell.adapters.cursor_adapter import CursorAdapter
 from agent_shell.adapters.grok_adapter import GrokAdapter
 from agent_shell.adapters.opencode_adapter import OpenCodeAdapter
 from agent_shell.adapters.pi_adapter import PiAdapter
-from agent_shell.execution import NativeExecutionHost, NoIsolation
+from agent_shell.execution import (
+    LinuxPidNamespaceIsolation,
+    NativeExecutionHost,
+    NoIsolation,
+)
 from agent_shell.models.agent import AgentResponse, AgentType
 from agent_shell.shell import AgentShell
 
 
 class TestExecutionDefaults:
+    def test_environment_can_select_linux_pid_namespace_isolation(self, monkeypatch):
+        # Arrange
+        monkeypatch.setenv(
+            "AGENTSHELL_ISOLATION_POLICY",
+            "linux-pid-namespace",
+        )
+
+        # Act
+        shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+        # Assert
+        assert isinstance(shell.isolation_policy, LinuxPidNamespaceIsolation)
+
+    @pytest.mark.parametrize("value", ["", "container"])
+    def test_invalid_environment_is_rejected_instead_of_disabling_isolation(
+            self, monkeypatch, value):
+        # Arrange
+        monkeypatch.setenv("AGENTSHELL_ISOLATION_POLICY", value)
+
+        # Act / Assert
+        with pytest.raises(
+            ValueError,
+            match="AGENTSHELL_ISOLATION_POLICY",
+        ):
+            AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+    def test_environment_can_explicitly_select_no_isolation(self, monkeypatch):
+        # Arrange
+        monkeypatch.setenv("AGENTSHELL_ISOLATION_POLICY", "none")
+
+        # Act
+        shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+        # Assert
+        assert isinstance(shell.isolation_policy, NoIsolation)
+
     def test_existing_constructor_defaults_to_native_without_isolation(self):
         # Arrange / Act
         shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
@@ -38,6 +78,23 @@ class TestExecutionDefaults:
         assert shell.execution_host is host
         assert shell.isolation_policy is policy
 
+    def test_explicit_isolation_policy_overrides_environment(self, monkeypatch):
+        # Arrange
+        monkeypatch.setenv(
+            "AGENTSHELL_ISOLATION_POLICY",
+            "linux-pid-namespace",
+        )
+        policy = NoIsolation()
+
+        # Act
+        shell = AgentShell(
+            agent_type=AgentType.CLAUDE_CODE,
+            isolation_policy=policy,
+        )
+
+        # Assert
+        assert shell.isolation_policy is policy
+
 
 class TestResolveAdapter:
     def test_resolves_claude_code(self):