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

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

@@ -105,6 +105,21 @@ classDiagram
         +launch(command, cwd, env, stdin, isolation_policy) NativeRunHandle
     }
 
+    class HerdrExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
+    class TmuxExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
+    class TerminalWindowExecutionHost {
+        <<experimental>>
+        +launch(command, cwd, env, stdin, isolation_policy) RunHandle
+    }
+
     class IsolationPolicy {
         <<Protocol>>
         +prepare(command, env) PreparedLaunch
@@ -140,6 +155,9 @@ classDiagram
     AgentShell --> ExecutionHost : selects
     AgentShell --> IsolationPolicy : selects
     NativeExecutionHost ..|> ExecutionHost : satisfies
+    HerdrExecutionHost ..|> ExecutionHost : satisfies
+    TmuxExecutionHost ..|> ExecutionHost : satisfies
+    TerminalWindowExecutionHost ..|> ExecutionHost : satisfies
     NativeExecutionHost --> NativeRunHandle : creates
     NativeRunHandle ..|> RunHandle : satisfies
     NoIsolation ..|> IsolationPolicy : satisfies
@@ -157,13 +175,25 @@ 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`.
 
+`HerdrExecutionHost`, `TmuxExecutionHost`, and `TerminalWindowExecutionHost` are experimental,
+opt-in APIs. Their constructors, placement options, supported platforms, and lifecycle behaviour
+may change in a later minor release. `NativeExecutionHost` remains the backwards-compatible
+default, and an unavailable experimental host never silently falls back to it.
+
 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 directly signal AgentShell's ancestors.
+The default `mount_proc=True` also hides those ancestors through a private `/proc` mount.
+Explicit `mount_proc=False` retains the PID boundary and descendant cleanup while inheriting the
+outer `/proc` view, exposing process metadata and potentially confusing tools that use its PIDs.
+It does not create a private mount namespace. The environment value `linux-pid-namespace` remains
+strict; each policy probes its own requested mode. 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 → agent_shell_py-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-shell-py
-Version: 0.3.0
+Version: 0.3.2
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE
@@ -83,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:
 
@@ -103,17 +114,146 @@ shell = AgentShell(
 ```
 
 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.
+that child namespace cannot signal AgentShell's ancestor processes. With the default private
+`/proc` mount they cannot see those ancestors either. 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.
+
+`LinuxPidNamespaceIsolation()` mounts a private `/proc` view by default, so tools such as `ps`
+show namespace PIDs. In a restricted container where that mount is denied but the PID namespace
+itself is available, opt into the inherited outer `/proc` view explicitly:
+
+```python
+isolation_policy=LinuxPidNamespaceIsolation(mount_proc=False)
+```
+
+The PID and signal boundary, PID 1 reaper, and descendant cleanup are retained, but `/proc` and
+`ps` can then expose outer PID information that disagrees with the child's `os.getpid()`. The
+selected mode is checked during the availability probe and still fails closed when unavailable;
+it does not create a private mount namespace. The environment setting
+`AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace` always selects the default `mount_proc=True`
+mode; use the explicit constructor for the opt-in mode.
 
 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.
+`NativeExecutionHost` remains the default. Execution hosts are opt-in and do not add Python
+dependencies.
+
+> [!WARNING]
+> `HerdrExecutionHost`, `TmuxExecutionHost`, and `TerminalWindowExecutionHost` are experimental.
+> They are opt-in, and their constructors, placement options, supported platforms, and lifecycle
+> behaviour may change in a later minor release as real-world usage expands. Explicit requests
+> continue to fail closed when their external prerequisite or requested policy is unavailable;
+> AgentShell never silently substitutes `NativeExecutionHost`.
+
+#### Herdr execution host (experimental)
+
+An opt-in `HerdrExecutionHost` runs each command in a
+uniquely owned Herdr pane while preserving the same adapter API:
+
+```python
+from agent_shell import HerdrExecutionHost
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=HerdrExecutionHost(),
+)
+```
+
+The `herdr` executable is an optional external prerequisite; AgentShell does not install a Python
+Herdr client or silently fall back to native execution. Herdr host v1 supports `NoIsolation()`
+only, and supports `DEVNULL` or `PIPE` stdin. A private, standard-library bridge carries the
+command, environment, output, status, and cancellation between the host and the Herdr worker, so
+secrets are not placed in the worker's launcher arguments. `RunHandle.pid` identifies the bridge
+worker, while the target CLI's normal or signal return status is preserved. Every run cleans up
+only its own Herdr pane, workspace, and bridge directory. Cleanup is bounded (five seconds by
+default; configure `cleanup_timeout=` when constructing the host). Model discovery and MCP
+configuration are local management operations and do not create Herdr panes.
+
+On Linux, both the bridge worker and its target use a parent-death guard, so an abrupt Herdr pane
+or worker exit cannot leave the target running. Other Unix platforms use the normal bridge
+disconnect cleanup but do not provide this kernel-level guard; an abrupt worker or pane death may
+therefore require external cleanup.
+
+#### tmux execution host (experimental)
+
+For a visible tmux run, opt into `TmuxExecutionHost` (the `tmux` executable itself is an optional
+system prerequisite):
+
+```python
+from agent_shell import TmuxExecutionHost, TmuxPlacement
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=TmuxExecutionHost(),
+)
+```
+
+By default, each run creates and owns one uniquely named tmux session and pane. Placement can be
+chosen explicitly: `TmuxPlacement.new_session(name=None)` creates an owned session, while
+`TmuxPlacement.new_window(session, focus=False)` borrows an existing session and owns only the
+new window. `TmuxPlacement.current_session(focus=False)` is a convenience for creating a window
+in the current tmux session and fails clearly when called outside tmux. `focus` defaults to false,
+so creating a window does not change the user's active window.
+
+A private, one-shot stdlib bridge keeps stdout and stderr as separate raw streams for the adapter
+while mirroring output into the pane; the command, working directory, environment, and prompt are
+sent over the private Unix socket, so secrets are not placed in the tmux command line.
+`RunHandle.pid` identifies the bridge/worker that owns the lifecycle, while `returncode` is the
+target CLI's exact exit or signal status.
+
+Version 1 supports `NoIsolation` and `DEVNULL` or `PIPE` stdin only. Unsupported isolation
+policies and arbitrary file descriptors fail closed before a tmux session is created. Completed,
+cancelled, abandoned, and interpreter-exit runs clean up their AgentShell-owned resource: a new
+session for session placement, or exactly the new window for borrowed-session placement. The host
+never kills unrelated tmux sessions or windows. Missing sessions, explicit name collisions, and
+unidentifiable windows fail closed without falling back to a new session. If tmux is unavailable,
+`TmuxUnavailableError` is raised and AgentShell does not silently fall back to the native host.
+Model discovery and MCP configuration remain local management operations.
+
+#### Terminal-window execution host (experimental)
+
+To watch a headless run in a new local graphical terminal window, inject the host into
+`AgentShell`:
+
+```python
+from agent_shell import TerminalWindowExecutionHost
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=TerminalWindowExecutionHost(),
+)
+```
+
+The host is Linux-focused in v1 and needs an installed terminal emulator plus a usable X11 or
+Wayland session. It discovers `x-terminal-emulator`, `gnome-terminal`, `konsole`, `kitty`,
+`alacritty`, `foot`, `wezterm`, or `xterm` in that order. These are optional external
+prerequisites; AgentShell has no terminal-emulator or Python runtime dependency. A caller can
+inject a `TerminalWindowLauncher` strategy (for example, `SubprocessTerminalLauncher`) for a
+different emulator or platform. If no launcher or graphical session is available, the request
+raises `TerminalWindowUnavailableError` and does not fall back to native execution.
+For a simple local override, set `AGENTSHELL_TERMINAL_LAUNCHER` to an executable name or path;
+strategies are preferred when custom argument conventions are needed.
+
+Each run opens a one-shot worker. The worker receives the command, environment, and prompt-bearing
+CLI arguments over a private mode-0700 directory and Unix socket; only the non-secret socket path
+is passed to the terminal launcher. Raw stdout and stderr bytes are forwarded unchanged to
+AgentShell and mirrored to the visible terminal. `RunHandle.pid` is the worker PID, and the
+target command's exact exit or signal status is returned.
+
+Only `NoIsolation` and `DEVNULL`/`PIPE` stdin are supported in v1. Other isolation policies and
+arbitrary file descriptors are rejected before launch. Runs are headless and machine-controlled
+despite being visible. Completed windows and transport resources close by default; there is no
+hold-open option in v1. Cancellation is sent through the private socket, and abandoning the
+owner cleans the worker, socket, and temporary directory where interpreter shutdown permits.
+
+Execution host and isolation policy remain separate axes, avoiding one host class per host/policy
+combination. Optional hosts fail closed when a requested isolation policy cannot be transported.
 
 ### Execute
 

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

@@ -74,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:
 
@@ -94,17 +105,146 @@ shell = AgentShell(
 ```
 
 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.
+that child namespace cannot signal AgentShell's ancestor processes. With the default private
+`/proc` mount they cannot see those ancestors either. 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.
+
+`LinuxPidNamespaceIsolation()` mounts a private `/proc` view by default, so tools such as `ps`
+show namespace PIDs. In a restricted container where that mount is denied but the PID namespace
+itself is available, opt into the inherited outer `/proc` view explicitly:
+
+```python
+isolation_policy=LinuxPidNamespaceIsolation(mount_proc=False)
+```
+
+The PID and signal boundary, PID 1 reaper, and descendant cleanup are retained, but `/proc` and
+`ps` can then expose outer PID information that disagrees with the child's `os.getpid()`. The
+selected mode is checked during the availability probe and still fails closed when unavailable;
+it does not create a private mount namespace. The environment setting
+`AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace` always selects the default `mount_proc=True`
+mode; use the explicit constructor for the opt-in mode.
 
 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.
+`NativeExecutionHost` remains the default. Execution hosts are opt-in and do not add Python
+dependencies.
+
+> [!WARNING]
+> `HerdrExecutionHost`, `TmuxExecutionHost`, and `TerminalWindowExecutionHost` are experimental.
+> They are opt-in, and their constructors, placement options, supported platforms, and lifecycle
+> behaviour may change in a later minor release as real-world usage expands. Explicit requests
+> continue to fail closed when their external prerequisite or requested policy is unavailable;
+> AgentShell never silently substitutes `NativeExecutionHost`.
+
+#### Herdr execution host (experimental)
+
+An opt-in `HerdrExecutionHost` runs each command in a
+uniquely owned Herdr pane while preserving the same adapter API:
+
+```python
+from agent_shell import HerdrExecutionHost
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=HerdrExecutionHost(),
+)
+```
+
+The `herdr` executable is an optional external prerequisite; AgentShell does not install a Python
+Herdr client or silently fall back to native execution. Herdr host v1 supports `NoIsolation()`
+only, and supports `DEVNULL` or `PIPE` stdin. A private, standard-library bridge carries the
+command, environment, output, status, and cancellation between the host and the Herdr worker, so
+secrets are not placed in the worker's launcher arguments. `RunHandle.pid` identifies the bridge
+worker, while the target CLI's normal or signal return status is preserved. Every run cleans up
+only its own Herdr pane, workspace, and bridge directory. Cleanup is bounded (five seconds by
+default; configure `cleanup_timeout=` when constructing the host). Model discovery and MCP
+configuration are local management operations and do not create Herdr panes.
+
+On Linux, both the bridge worker and its target use a parent-death guard, so an abrupt Herdr pane
+or worker exit cannot leave the target running. Other Unix platforms use the normal bridge
+disconnect cleanup but do not provide this kernel-level guard; an abrupt worker or pane death may
+therefore require external cleanup.
+
+#### tmux execution host (experimental)
+
+For a visible tmux run, opt into `TmuxExecutionHost` (the `tmux` executable itself is an optional
+system prerequisite):
+
+```python
+from agent_shell import TmuxExecutionHost, TmuxPlacement
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=TmuxExecutionHost(),
+)
+```
+
+By default, each run creates and owns one uniquely named tmux session and pane. Placement can be
+chosen explicitly: `TmuxPlacement.new_session(name=None)` creates an owned session, while
+`TmuxPlacement.new_window(session, focus=False)` borrows an existing session and owns only the
+new window. `TmuxPlacement.current_session(focus=False)` is a convenience for creating a window
+in the current tmux session and fails clearly when called outside tmux. `focus` defaults to false,
+so creating a window does not change the user's active window.
+
+A private, one-shot stdlib bridge keeps stdout and stderr as separate raw streams for the adapter
+while mirroring output into the pane; the command, working directory, environment, and prompt are
+sent over the private Unix socket, so secrets are not placed in the tmux command line.
+`RunHandle.pid` identifies the bridge/worker that owns the lifecycle, while `returncode` is the
+target CLI's exact exit or signal status.
+
+Version 1 supports `NoIsolation` and `DEVNULL` or `PIPE` stdin only. Unsupported isolation
+policies and arbitrary file descriptors fail closed before a tmux session is created. Completed,
+cancelled, abandoned, and interpreter-exit runs clean up their AgentShell-owned resource: a new
+session for session placement, or exactly the new window for borrowed-session placement. The host
+never kills unrelated tmux sessions or windows. Missing sessions, explicit name collisions, and
+unidentifiable windows fail closed without falling back to a new session. If tmux is unavailable,
+`TmuxUnavailableError` is raised and AgentShell does not silently fall back to the native host.
+Model discovery and MCP configuration remain local management operations.
+
+#### Terminal-window execution host (experimental)
+
+To watch a headless run in a new local graphical terminal window, inject the host into
+`AgentShell`:
+
+```python
+from agent_shell import TerminalWindowExecutionHost
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(
+    agent_type=AgentType.CLAUDE_CODE,
+    execution_host=TerminalWindowExecutionHost(),
+)
+```
+
+The host is Linux-focused in v1 and needs an installed terminal emulator plus a usable X11 or
+Wayland session. It discovers `x-terminal-emulator`, `gnome-terminal`, `konsole`, `kitty`,
+`alacritty`, `foot`, `wezterm`, or `xterm` in that order. These are optional external
+prerequisites; AgentShell has no terminal-emulator or Python runtime dependency. A caller can
+inject a `TerminalWindowLauncher` strategy (for example, `SubprocessTerminalLauncher`) for a
+different emulator or platform. If no launcher or graphical session is available, the request
+raises `TerminalWindowUnavailableError` and does not fall back to native execution.
+For a simple local override, set `AGENTSHELL_TERMINAL_LAUNCHER` to an executable name or path;
+strategies are preferred when custom argument conventions are needed.
+
+Each run opens a one-shot worker. The worker receives the command, environment, and prompt-bearing
+CLI arguments over a private mode-0700 directory and Unix socket; only the non-secret socket path
+is passed to the terminal launcher. Raw stdout and stderr bytes are forwarded unchanged to
+AgentShell and mirrored to the visible terminal. `RunHandle.pid` is the worker PID, and the
+target command's exact exit or signal status is returned.
+
+Only `NoIsolation` and `DEVNULL`/`PIPE` stdin are supported in v1. Other isolation policies and
+arbitrary file descriptors are rejected before launch. Runs are headless and machine-controlled
+despite being visible. Completed windows and transport resources close by default; there is no
+hold-open option in v1. Cancellation is sent through the private socket, and abandoning the
+owner cleans the worker, socket, and temporary directory where interpreter shutdown permits.
+
+Execution host and isolation policy remain separate axes, avoiding one host class per host/policy
+combination. Optional hosts fail closed when a requested isolation policy cannot be transported.
 
 ### Execute
 

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

@@ -47,19 +47,30 @@ yields events in real-time — plus helpers for model discovery, health checks,
 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)
+- `execution_host`: where/how the process is owned (native by default; experimental visible hosts
+  are available explicitly)
 - `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.
+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`:
 
@@ -73,15 +84,36 @@ shell = AgentShell(
 ```
 
 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
+With the default private `/proc` mount, the CLI cannot see AgentShell's ancestors; both modes keep
+those ancestors outside the CLI's direct signal boundary. Use
+`LinuxPidNamespaceIsolation(mount_proc=False)` in a restricted container where the private proc
+mount is denied; that mode inherits outer `/proc` visibility while retaining the PID boundary,
+reaper, and descendant cleanup. The environment value `linux-pid-namespace` always selects the
+strict default (`mount_proc=True`). 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.
+management operations.
+
+### Experimental Execution Hosts
+
+`NativeExecutionHost` remains the backwards-compatible default. Three visible execution hosts
+are shipped as **experimental, opt-in APIs**:
+
+- `HerdrExecutionHost()` creates and owns a one-shot Herdr pane/workspace.
+- `TmuxExecutionHost()` creates an owned tmux session by default; `TmuxPlacement` can instead
+  select a named or current session and own only the newly-created window.
+- `TerminalWindowExecutionHost()` opens a headless, machine-controlled run in a graphical
+  terminal window through an injectable launcher.
+
+Their constructors, placement options, platform support, and lifecycle behaviour may change in a
+later minor release. They require optional external executables, support only `NoIsolation` in
+their first version, and fail closed rather than silently falling back to native execution. Use
+the stable default when visible placement is not required. See the execution-host section in
+[`api-reference.md`](api-reference.md) before selecting an experimental host.
 
 ### Discover Available Model Strings
 

{agent_shell_py-0.3.0 → agent_shell_py-0.3.2}/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
 
@@ -188,6 +188,16 @@ class AgentShell:
 ## Execution Hosts and Isolation
 
 ```python
+from agent_shell import (
+    HerdrExecutionHost,
+    SubprocessTerminalLauncher,
+    TerminalWindowExecutionHost,
+    TerminalWindowLauncher,
+    TerminalWindowUnavailableError,
+    TmuxExecutionHost,
+    TmuxPlacement,
+    TmuxUnavailableError,
+)
 from agent_shell.execution import (
     ExecutionHost,
     IsolationPolicy,
@@ -203,19 +213,67 @@ from agent_shell.execution import (
 
 `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.
+Agent adapters use handles internally; existing `execute()` and `stream()` callers do not need to
+manage them. `NativeExecutionHost` remains the backwards-compatible default.
+
+> **Experimental hosts:** `HerdrExecutionHost`, `TmuxExecutionHost`, and
+> `TerminalWindowExecutionHost` are opt-in experimental APIs. Their constructors, placement
+> options, supported platforms, and lifecycle behaviour may change in a later minor release. An
+> explicit request fails closed when its prerequisite or requested policy is unavailable; none of
+> these hosts silently falls back to native execution.
+
+| Host | Placement | Optional prerequisite | First-version limits |
+|------|-----------|-----------------------|----------------------|
+| `NativeExecutionHost` | Current local process environment | None | Composes with the selected isolation policy |
+| `HerdrExecutionHost` **(experimental)** | Owned one-shot Herdr pane/workspace | `herdr` executable | `NoIsolation`; `DEVNULL` or `PIPE` stdin |
+| `TmuxExecutionHost` **(experimental)** | Owned session, or owned window in a borrowed session | `tmux` executable | `NoIsolation`; `DEVNULL` or `PIPE` stdin |
+| `TerminalWindowExecutionHost` **(experimental)** | New graphical terminal window | Supported or injected terminal launcher | Linux-focused; headless/machine-controlled; `NoIsolation`; `DEVNULL` or `PIPE` stdin |
+
+Tmux placement is explicit when the default owned session is not suitable:
+
+```python
+TmuxExecutionHost()  # uniquely named, AgentShell-owned session
+TmuxExecutionHost(placement=TmuxPlacement.new_session(name="review"))
+TmuxExecutionHost(placement=TmuxPlacement.new_window("existing", focus=False))
+TmuxExecutionHost(placement=TmuxPlacement.current_session(focus=False))
+```
+
+The terminal host discovers a small built-in set of Linux terminal emulators. Set
+`AGENTSHELL_TERMINAL_LAUNCHER` for a simple executable override, or inject a
+`TerminalWindowLauncher`/`SubprocessTerminalLauncher` when the emulator needs custom arguments.
+Its visible window mirrors the agent's raw streams, but the agent remains headless and controlled
+by AgentShell; this is not the agent CLI's interactive harness interface.
 
 `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.
+user + PID namespaces, with a tiny PID 1 reaper and the CLI at PID 2 or later. Its constructor is:
+
+```python
+LinuxPidNamespaceIsolation(*, mount_proc: bool = True)
+```
+
+The default mounts a private `/proc` view, while `mount_proc=False` omits only that mount. The
+opt-in mode retains the PID and direct-signal boundary, PID 1 reaper, and descendant cleanup, but
+inherits the outer `/proc` view; `ps` and `/proc` can then expose host PID information that differs
+from the child's `os.getpid()`. This is useful in restricted containers where the private proc
+mount is denied, and it does not create a private mount namespace. The argument must be a real
+`bool`; other values raise `TypeError`.
+
+Both modes protect AgentShell's ancestors from direct same-user signals sent inside the child
+namespace. The policy is not a 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
-`health_check()`; model discovery and MCP configuration remain local management operations.
+back to `NoIsolation`; the availability probe uses the selected `mount_proc` mode. The environment
+setting `AGENTSHELL_ISOLATION_POLICY=linux-pid-namespace` selects the strict default
+`mount_proc=True` mode; use an explicit policy object for `mount_proc=False`. The host/policy
+selection applies to `execute()`, `stream()`, and `health_check()`; model discovery and MCP
+configuration remain local management operations.
 
 ### Model discovery semantics
 

agent_shell_py-0.3.2/src/agent_shell/__init__.py

@@ -0,0 +1,33 @@
+"""Public package exports for AgentShell."""
+
+from agent_shell.herdr import (
+    HerdrClient,
+    HerdrExecutionHost,
+    HerdrPane,
+    HerdrUnavailableError,
+)
+from agent_shell.terminal_window import (
+    SubprocessTerminalLauncher,
+    TerminalWindowExecutionHost,
+    TerminalWindowLauncher,
+    TerminalWindowRunHandle,
+    TerminalWindowUnavailableError,
+    discover_terminal_launcher,
+)
+from agent_shell.tmux import TmuxExecutionHost, TmuxPlacement, TmuxUnavailableError
+
+__all__ = [
+    "HerdrClient",
+    "HerdrExecutionHost",
+    "HerdrPane",
+    "HerdrUnavailableError",
+    "SubprocessTerminalLauncher",
+    "TerminalWindowExecutionHost",
+    "TerminalWindowLauncher",
+    "TerminalWindowRunHandle",
+    "TerminalWindowUnavailableError",
+    "TmuxExecutionHost",
+    "TmuxPlacement",
+    "TmuxUnavailableError",
+    "discover_terminal_launcher",
+]

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