agent-shell-py 0.2.0__tar.gz → 0.2.2__tar.gz

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/AGENTS.md

@@ -11,6 +11,7 @@ classDiagram
         +execute(cwd, prompt, ...) AgentResponse
         +stream(cwd, prompt, ...) AsyncIterator~StreamEvent~
         +health_check(cwd, model, timeout) HealthCheckResult
+        +list_models(cwd, timeout) list~str~
         +add_mcp_server(spec) None
         +remove_mcp_server(name) None
         +list_mcp_servers() list~MCPServerSpec~
@@ -22,6 +23,7 @@ classDiagram
         +stream(cwd, prompt, ...) AsyncIterator~StreamEvent~
         +cancel() None
         +health_check(cwd, model, timeout) HealthCheckResult
+        +list_models(cwd, timeout) list~str~
         +add_mcp_server(spec) None
         +remove_mcp_server(name) None
         +list_mcp_servers() list~MCPServerSpec~
@@ -32,6 +34,7 @@ classDiagram
         +execute(cwd, prompt, ...) AgentResponse
         +stream(cwd, prompt, ...) AsyncIterator~StreamEvent~
         +cancel() None
+        +list_models(cwd, timeout) list~str~
         +add_mcp_server(spec) None
         +remove_mcp_server(name) None
         +list_mcp_servers() list~MCPServerSpec~
@@ -125,6 +128,12 @@ stream; `adapters/health.py` wraps it for the health probe, and `adapters/respon
 for `execute()`'s stream-to-`AgentResponse` collection (used by every adapter — each `execute()`
 is a single delegating call into it).
 
+`list_models(cwd, timeout)` asks the selected CLI for its current account/workspace-aware model
+catalog and returns exact `list[str]` selectors that can be passed unchanged to `execute()` or
+`stream()`. It sends no inference prompt, imports no harness SDK, invokes no separate refresh
+command, and never substitutes a static catalog. "Available" means advertised as selectable; use
+`health_check(model=...)` when actual execution must be proven.
+
 ## Supported Agents
 
 - [x] Claude Code
@@ -172,9 +181,14 @@ Tests validate real functionality, not code coverage metrics. Three tiers, each
 |------|-------|-----------|----------------|
 | **Unit** | Isolated functions (`_parse_event`, adapter resolution, input validation) | Yes | No |
 | **Integration** | Full flow through `AgentShell` -> `Adapter` -> parser with mocked subprocess | Yes | No |
-| **E2E** | Real CLI agent calls, real API costs | No (local only) | Yes |
+| **E2E** | Real CLI calls; usually real API costs | No (local only) | Yes |
+
+The model-discovery E2E test is the exception: it calls all six real CLIs but only reads
+metadata, so it sends no inference request and incurs no model-token cost.
 
-Integration tests mirror the E2E tests exactly but substitute a mocked subprocess emitting captured NDJSON fixtures. This means CI validates the entire class interaction chain without credentials or API spend. E2E tests exist as a local smoke test to confirm the real agents still behave as expected.
+Integration tests mirror the E2E tests but substitute mocked subprocesses emitting captured CLI
+output fixtures. This lets CI validate the full class interaction chain without credentials or API
+spend. E2E tests remain local smoke tests for the real agents.
 
 All tests follow the **AAA pattern** (Arrange, Act, Assert).
 

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.2.0
+Version: 0.2.2
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE
@@ -13,8 +13,8 @@ and returning the output that can be used programatically as a unified contract
 
 ## Features
 
-- **One unified contract** — the same `execute` / `stream` / `health_check` API across every
-  agent; swap the backend without changing a line of consuming code.
+- **One unified contract** — the same `execute`, `stream`, `health_check`, and
+  `list_models` API across every agent; swap the backend without changing consuming code.
 - **Six CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, and Cursor behind a
   common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
@@ -22,6 +22,8 @@ and returning the output that can be used programatically as a unified contract
 - **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.
+- **Model discovery** — retrieve the exact account/workspace-aware model strings accepted by
+  each CLI, without inference calls, SDK dependencies, or static catalogs.
 - **Health checks** — confirm an agent + model combination actually works before you rely on
   it, read from the event stream rather than unreliable exit codes.
 - **Portable tool control** — one canonical allow/deny vocabulary
@@ -42,6 +44,39 @@ or with pip:
 pip install agent-shell-py
 ```
 
+## Agent skills
+
+![Skill_Banner](docs/assets/skill_banner.png)
+
+The repository includes reusable skills that teach coding agents how to use AgentShell:
+
+- `invoking-cli-agents` — invoke, stream, resume, and restrict CLI agents.
+- `delegating-code-review` — delegate an independent code review through AgentShell.
+
+Install them interactively with the Vercel Skills CLI:
+
+```bash
+npx skills add ScottRBK/agent-shell
+```
+
+Or install both skills globally for every coding agent supported by AgentShell:
+
+```bash
+npx skills add ScottRBK/agent-shell --global \
+  --skill '*' \
+  --agent claude-code opencode github-copilot codex pi cursor \
+  --yes
+```
+
+Install only the core AgentShell skill with:
+
+```bash
+npx skills add ScottRBK/agent-shell --skill invoking-cli-agents
+```
+
+The skills provide agent instructions. Install `agent-shell-py` and the chosen coding-agent CLIs
+separately.
+
 ## Examples
 
 ### Execute
@@ -115,6 +150,33 @@ async for event in shell.stream(
         print(f"[{event.type}] {event.content}")
 ```
 
+### Model discovery
+
+Ask the selected CLI which model strings it currently advertises, then pass one back
+unchanged. Discovery sends no inference prompt and has no model-token cost.
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+models = await shell.list_models(cwd="/path/to/project")
+selected_model = models[0]
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Review this project",
+    model=selected_model,
+)
+```
+
+"Available" means advertised as selectable for the current harness, account, and workspace.
+It does not prove quota, entitlement, credentials, or provider health. The harness's order and
+aliases such as `auto` and `default` are preserved. A genuine empty catalog returns `[]`;
+discovery failures are raised instead of being mistaken for an empty catalog.
+
+See the
+[agent parameter comparison](docs/development/agent_parameter_comparison.md#model-discovery)
+for each harness's underlying discovery mechanism.
+
 ### Health check
 
 Verify an agent + model combination actually works before relying on it. It sends a

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/README.md

@@ -4,8 +4,8 @@ and returning the output that can be used programatically as a unified contract
 
 ## Features
 
-- **One unified contract** — the same `execute` / `stream` / `health_check` API across every
-  agent; swap the backend without changing a line of consuming code.
+- **One unified contract** — the same `execute`, `stream`, `health_check`, and
+  `list_models` API across every agent; swap the backend without changing consuming code.
 - **Six CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, and Cursor behind a
   common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
@@ -13,6 +13,8 @@ and returning the output that can be used programatically as a unified contract
 - **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.
+- **Model discovery** — retrieve the exact account/workspace-aware model strings accepted by
+  each CLI, without inference calls, SDK dependencies, or static catalogs.
 - **Health checks** — confirm an agent + model combination actually works before you rely on
   it, read from the event stream rather than unreliable exit codes.
 - **Portable tool control** — one canonical allow/deny vocabulary
@@ -33,6 +35,39 @@ or with pip:
 pip install agent-shell-py
 ```
 
+## Agent skills
+
+![Skill_Banner](docs/assets/skill_banner.png)
+
+The repository includes reusable skills that teach coding agents how to use AgentShell:
+
+- `invoking-cli-agents` — invoke, stream, resume, and restrict CLI agents.
+- `delegating-code-review` — delegate an independent code review through AgentShell.
+
+Install them interactively with the Vercel Skills CLI:
+
+```bash
+npx skills add ScottRBK/agent-shell
+```
+
+Or install both skills globally for every coding agent supported by AgentShell:
+
+```bash
+npx skills add ScottRBK/agent-shell --global \
+  --skill '*' \
+  --agent claude-code opencode github-copilot codex pi cursor \
+  --yes
+```
+
+Install only the core AgentShell skill with:
+
+```bash
+npx skills add ScottRBK/agent-shell --skill invoking-cli-agents
+```
+
+The skills provide agent instructions. Install `agent-shell-py` and the chosen coding-agent CLIs
+separately.
+
 ## Examples
 
 ### Execute
@@ -106,6 +141,33 @@ async for event in shell.stream(
         print(f"[{event.type}] {event.content}")
 ```
 
+### Model discovery
+
+Ask the selected CLI which model strings it currently advertises, then pass one back
+unchanged. Discovery sends no inference prompt and has no model-token cost.
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+models = await shell.list_models(cwd="/path/to/project")
+selected_model = models[0]
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Review this project",
+    model=selected_model,
+)
+```
+
+"Available" means advertised as selectable for the current harness, account, and workspace.
+It does not prove quota, entitlement, credentials, or provider health. The harness's order and
+aliases such as `auto` and `default` are preserved. A genuine empty catalog returns `[]`;
+discovery failures are raised instead of being mistaken for an empty catalog.
+
+See the
+[agent parameter comparison](docs/development/agent_parameter_comparison.md#model-discovery)
+for each harness's underlying discovery mechanism.
+
 ### Health check
 
 Verify an agent + model combination actually works before relying on it. It sends a

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/docs/development/agent_parameter_comparison.md

@@ -1,10 +1,10 @@
 # Agent CLI Parameter Comparison
 
 Comparison of headless/non-interactive configuration across supported CLI coding agents.
-Last updated: 2026-07-26
+Last updated: 2026-08-02
 
 > The summary matrix below has no Pi or Cursor column (it predates both adapters); see the
-> per-agent detail sections and the `disallowed_tools` table for those two.
+> per-agent detail sections, the model-discovery section, and the `disallowed_tools` table.
 
 > Every "measured 2026-07-26" claim below comes from a real three-call run per agent (first
 > turn, resume on the returned id, then a session-less turn), recorded by the resume e2e tests
@@ -26,6 +26,58 @@ Last updated: 2026-07-26
 | **Auto-approve** | `--dangerously-skip-permissions` | `--yolo` | `--yolo` / `--allow-all` | Auto in `run` mode |
 | **Session resume** | `--resume` | `exec resume <id>` | `--resume` | `-s <id>` |
 
+## Model discovery
+
+Every adapter exposes the same account/workspace-aware API:
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+models = await shell.list_models(cwd="/path/to/project")
+selected_model = models[0]
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Do the work",
+    model=selected_model,
+)
+```
+
+`list_models()` returns `list[str]`. Each string is the exact selector accepted by that
+same adapter's `execute(model=...)` and `stream(model=...)`; callers do not translate it.
+Discovery reads CLI metadata and makes no inference call.
+
+| Harness | Discovery mechanism | Returned selector |
+|---|---|---|
+| Claude Code | stream-JSON `initialize` control request | `models[].value` |
+| OpenCode | `opencode models` | each complete output line |
+| Copilot CLI | headless JSON-RPC `models.list` | `models[].id` |
+| Codex | `codex debug models` | visible model `slug` |
+| Pi | `pi --no-approve --list-models` | `provider/model` |
+| Cursor | `cursor-agent models` | ID before the first ` - ` |
+
+Important semantics:
+
+- "Available" means advertised as selectable for the current harness, account, and
+  workspace. It does not guarantee current quota, entitlement, credentials, or provider
+  health. Use `health_check(model=...)` when actual execution must be proven.
+- Claude and Copilot are invoked directly as CLIs. Their SDK documentation was protocol
+  evidence only; AgentShell imports no harness SDKs and adds no runtime dependency.
+- Claude runs in print mode with `--no-session-persistence`, so discovery is not saved as a
+  resumable session.
+- Codex filters the refreshed JSON catalog to `visibility == "list"`. Its documented
+  `debug models` command is experimental, so integration and local E2E tests guard drift.
+- Pi model IDs are provider-qualified because IDs can repeat across providers. Discovery
+  does not run the mutating `pi update --models` command.
+- The harness's order and aliases such as `auto` or `default` are preserved.
+- A genuine empty catalog returns `[]`. Authentication, timeout, non-zero exit, and
+  malformed protocol/output failures are surfaced with actionable errors.
+- AgentShell does not cache or replace results with a static fallback catalog.
+
+The behavior was verified against all six installed CLIs on 2026-08-02 without inference
+spend. CI covers captured real outputs through `AgentShell`; a local E2E test checks all six
+real discovery commands.
+
 ## Claude Code
 
 - **Headless mode**: `-p` / `--print`

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/pyproject.toml

@@ -23,7 +23,7 @@ packages = ["src/agent_shell"]
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 markers = [
-    "e2e: end-to-end tests that call real CLI agents (requires credentials, costs money)",
+    "e2e: real CLI tests (may require credentials and incur API costs)",
 ]
 
 [dependency-groups]

{agent_shell_py-0.2.0/agent-skills → agent_shell_py-0.2.2/skills}/invoking-cli-agents/SKILL.md

@@ -1,6 +1,12 @@
 ---
 name: invoking-cli-agents
-description: Use when programmatically invoking a CLI coding agent (Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor) from Python, delegating a task to a sub-agent, orchestrating several agents, streaming an agent's output, resuming an agent session, restricting which tools an agent may use, or checking whether an agent/model is healthy. Keywords: AgentShell, headless agent, subprocess, allowed_tools, disallowed_tools, read-only agent, session_id, cost, output_tokens.
+description: >-
+  Use when invoking a CLI coding agent from Python, delegating to a sub-agent, discovering
+  available model strings, orchestrating agents, streaming output, resuming sessions,
+  restricting tools, or checking agent/model health. Supports Claude Code, OpenCode,
+  Copilot CLI, Codex, Pi, and Cursor. Keywords: AgentShell, list_models, headless agent,
+  model discovery, subprocess, allowed_tools, disallowed_tools, session_id, cost,
+  output_tokens.
 ---
 
 # Invoking CLI Agents with AgentShell
@@ -20,6 +26,7 @@ passes `model` strings through verbatim and does not manage credentials.
 - You need to orchestrate multi-step workflows across agents
 - You want to stream agent output in real-time
 - You need to restrict what tools a delegated agent can run
+- You need the exact model strings currently advertised by a selected CLI
 - You want to check whether an agent/model combination works before relying on it
 
 ## When NOT to Use
@@ -36,8 +43,32 @@ uv add agent-shell-py
 ## Core Concepts
 
 AgentShell has two invocation methods — `execute()` collects a complete response, `stream()`
-yields events in real-time — plus helpers for health checks and MCP server management. All
-are async.
+yields events in real-time — plus helpers for model discovery, health checks, and MCP server
+management. All are async.
+
+### Discover Available Model Strings
+
+Use `list_models()` before selecting a model dynamically. It returns exact strings that the
+same shell accepts through `execute(model=...)` and `stream(model=...)`.
+
+```python
+shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)
+
+models = await shell.list_models(cwd="/path/to/project")
+selected_model = models[0]
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Review this project",
+    model=selected_model,
+)
+```
+
+Discovery reads CLI metadata. It sends no inference prompt and incurs no model-token cost.
+"Available" means the CLI advertises the selector for the current account/workspace; it does
+not prove quota or entitlement. Use `health_check(model=selected_model)` for that stronger
+inference check, which may incur cost. Preserve the returned string unchanged, including
+such as `auto` or `default`.
 
 ### Execute: Run and Collect
 
@@ -276,6 +307,8 @@ succeeded = saw_ok and error is None         # absent result => succeeded stays
 
 ## Other Capabilities
 
+- **Model discovery** — `await shell.list_models(cwd)` returns exact selectable strings.
+  A genuine empty catalog returns `[]`; discovery failures are raised.
 - **Health check** — `await shell.health_check(cwd, model=...)` returns a `HealthCheckResult`.
   It sends its *own* trivial no-tool prompt to confirm the agent/model completes a turn — it does
   **not** run your prompt, so use the stream-based check above when you care about a specific
@@ -305,7 +338,8 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | Whitelist tools (Claude/Copilot/Pi) | `allowed_tools=["Read", "Glob"]` |
 | Deny tools (Claude/OpenCode/Copilot/Pi) | `disallowed_tools=["edit", "bash"]` |
 | Track usage | Read `response.output_tokens` (portable) or `response.cost` |
-| Use a specific model | `model="sonnet"` |
+| Discover selectable models | `await shell.list_models(cwd)` |
+| Use a specific model | Pass one returned string as `model=...` |
 | Increase reasoning depth | `effort="high"` (not OpenCode or Cursor) |
 | See agent thinking | `include_thinking=True` in `stream()` |
 | Check an agent/model works | `await shell.health_check(cwd, model=...)` |
@@ -316,6 +350,8 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | Mistake | Fix |
 |---------|-----|
 | Passing a non-existent `cwd` | Validate the path exists first (else `ValueError`) |
+| Hard-coding a public model catalog | Use `await shell.list_models(cwd)` |
+| Altering a discovered model string | Pass it back unchanged as `model=...` |
 | Forgetting `await` | Both `execute()` and the `stream()` iterator are async |
 | `allowed_tools=[]` to disable tools | Empty list is falsy → full access. Use a non-empty list or `disallowed_tools` |
 | `allowed_tools` with the default `auto_approve=True` as a safety boundary | `--dangerously-skip-permissions` bypasses it. Set `auto_approve=False`, or use `disallowed_tools` |

{agent_shell_py-0.2.0/agent-skills → agent_shell_py-0.2.2/skills}/invoking-cli-agents/api-reference.md

@@ -3,7 +3,7 @@
 - [Models](#models) — `AgentType`, `AgentResponse`, `AgentExecutionError`, `StreamEvent`,
   `MCPServerSpec`, `HealthCheckResult`
 - [StreamEvent types](#event-types)
-- [AgentShell class](#agentshell-class) — `execute`, `stream`, `health_check`, MCP management
+- [AgentShell class](#agentshell-class) — invocation, model discovery, health, MCP management
 - [AgentAdapter protocol](#agentadapter-protocol)
 - [Agent-specific notes](#agent-specific-notes)
 
@@ -163,11 +163,28 @@ class AgentShell:
     ) -> HealthCheckResult: ...
     # Sends a trivial no-tool prompt; healthy iff the LAST result event is "ok" and no error.
 
+    async def list_models(
+        self, cwd: str, timeout: float = 30.0,
+    ) -> list[str]: ...
+    # Returns exact selectors accepted by execute(model=...) and stream(model=...).
+
     async def add_mcp_server(self, mcp_server: MCPServerSpec) -> None: ...
     async def remove_mcp_server(self, mcp_server_name: str) -> None: ...
     async def list_mcp_servers(self) -> list[MCPServerSpec]: ...
 ```
 
+### Model discovery semantics
+
+`list_models()` reads the selected CLI's account/workspace-aware catalog without sending an
+inference prompt. It preserves harness order and aliases such as `auto` and `default`. Pi
+selectors are provider-qualified (`provider/model`) because model IDs can repeat across
+providers.
+
+A returned string is advertised as selectable, not guaranteed runnable at that moment. Use
+`health_check(model=...)` to validate credentials, entitlement, quota, and provider health.
+A genuine empty catalog returns `[]`; timeout, authentication, CLI, and malformed-output
+failures are raised. AgentShell does not cache or substitute a static catalog.
+
 ### disallowed_tools canonical vocabulary
 
 `disallowed_tools` accepts these canonical names; each adapter maps them to native deny
@@ -198,6 +215,7 @@ class AgentAdapter(Protocol):
     async def cancel(self) -> None: ...
 
     async def health_check(self, cwd, model=None, timeout=60.0) -> HealthCheckResult: ...
+    async def list_models(self, cwd, timeout=30.0) -> list[str]: ...
     async def add_mcp_server(self, mcp_server: MCPServerSpec) -> None: ...
     async def remove_mcp_server(self, mcp_server_name: str) -> None: ...
     async def list_mcp_servers(self) -> list[MCPServerSpec]: ...

{agent_shell_py-0.2.0 → agent_shell_py-0.2.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.2.0'
-__version_tuple__ = version_tuple = (0, 2, 0)
+__version__ = version = '0.2.2'
+__version_tuple__ = version_tuple = (0, 2, 2)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/src/agent_shell/adapters/agent_adapter_protocol.py

@@ -48,6 +48,13 @@ class AgentAdapter(Protocol):
     ) -> HealthCheckResult:
         ...
 
+    async def list_models(
+            self,
+            cwd: str,
+            timeout: float = 30.0,
+    ) -> list[str]:
+        ...
+
     async def add_mcp_server(self, mcp_server: MCPServerSpec) -> None:
         ...
 

{agent_shell_py-0.2.0 → agent_shell_py-0.2.2}/src/agent_shell/adapters/claude_code_adapter.py

@@ -7,10 +7,20 @@ import warnings
 from pathlib import Path
 from typing import AsyncIterator
 
-from agent_shell.models.agent import AgentResponse, StreamEvent, MCPServerSpec, MCPServerType, HealthCheckResult
-from agent_shell.process_cleanup import (register_process_group, kill_process_group,
-                                         release_process)
+from agent_shell.models.agent import (
+    AgentResponse,
+    HealthCheckResult,
+    MCPServerSpec,
+    MCPServerType,
+    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
@@ -104,18 +114,12 @@ class ClaudeCodeAdapter():
         logger.debug("Command: %s", cmd)
         logger.info("Process started (cwd=%s)", os.path.abspath(cwd))
 
-        process = await asyncio.create_subprocess_exec(
-                *cmd,
-                stdin=asyncio.subprocess.DEVNULL,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-                cwd=os.path.abspath(cwd),
-                preexec_fn=os.setsid,
+        process = await create_grouped_process(
+            cmd,
+            cwd=os.path.abspath(cwd),
         )
 
         self._active_processes.append(process)
-        # setsid makes the child a session leader, so pgid == pid
-        register_process_group(process.pid)
 
         # Drain stderr concurrently with stdout. Reading it only after the stdout loop can
         # deadlock: a child that fills its stderr pipe buffer (~64KB) mid-run blocks on that
@@ -226,7 +230,7 @@ class ClaudeCodeAdapter():
 
     async def cancel(self) -> None:
         for process in self._active_processes:
-            kill_process_group(process.pid)
+            kill_process_group(process)
         self._active_processes.clear()
 
     async def health_check(
@@ -237,6 +241,77 @@ class ClaudeCodeAdapter():
     ) -> HealthCheckResult:
         return await run_health_probe(self, cwd, model=model, timeout=timeout)
 
+    async def list_models(
+            self,
+            cwd: str,
+            timeout: float = 30.0,
+    ) -> list[str]:
+        cmd = [
+            "claude",
+            "--print",
+            "--no-session-persistence",
+            "--output-format", "stream-json",
+            "--verbose",
+            "--input-format", "stream-json",
+            "--tools", "",
+            "--permission-mode", "dontAsk",
+        ]
+        request = {
+            "request_id": "agent-shell-models",
+            "type": "control_request",
+            "request": {"subtype": "initialize"},
+        }
+        input_data = (json.dumps(request) + "\n").encode("utf-8")
+        returncode, stdout, stderr = await run_model_command(
+            cmd,
+            cwd,
+            timeout,
+            input_data=input_data,
+        )
+        if returncode != 0:
+            message = format_stderr(stderr) or f"exit code {returncode}"
+            raise RuntimeError(f"Claude model discovery failed: {message}")
+
+        output = decode_model_output(stdout, "Claude model discovery")
+        for line in output.splitlines():
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError as error:
+                raise RuntimeError(
+                    "Claude model discovery returned invalid JSON"
+                ) from error
+            if not isinstance(event, dict):
+                raise RuntimeError("Claude model discovery returned invalid JSON")
+            if event.get("type") != "control_response":
+                continue
+
+            response = event.get("response")
+            if not isinstance(response, dict):
+                raise RuntimeError("Claude model discovery returned an invalid response")
+            if response.get("request_id") != "agent-shell-models":
+                continue
+            if response.get("subtype") != "success":
+                raise RuntimeError("Claude model discovery request failed")
+
+            payload = response.get("response")
+            models = payload.get("models", []) if isinstance(payload, dict) else None
+            if not isinstance(models, list):
+                raise RuntimeError("Claude model discovery returned no model list")
+
+            model_values: list[str] = []
+            for model in models:
+                value = model.get("value") if isinstance(model, dict) else None
+                if not isinstance(value, str) or not value:
+                    raise RuntimeError(
+                        "Claude model discovery returned an invalid model entry"
+                    )
+                model_values.append(value)
+            return model_values
+
+        raise RuntimeError("Claude model discovery returned no initialization response")
+
     async def add_mcp_server(self, mcp_server: MCPServerSpec) -> None:
         # Pre-remove for overwrite semantics; ignore failure (server may not exist).
         await self._run_mcp_command(