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

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

@@ -38,6 +38,16 @@ classDiagram
         -_parse_event(event, include_thinking) list~StreamEvent~
     }
 
+    class AgentExecutionError {
+        <<Exception>>
+        +str reason
+        +str response
+        +float cost
+        +str session_id
+        +float duration
+        +int output_tokens
+    }
+
     class MCPServerSpec {
         +str name
         +MCPServerType type
@@ -74,13 +84,13 @@ classDiagram
         +float duration
         +str session_id
         +int output_tokens
+        +str error
     }
 
     class AgentType {
         <<StrEnum>>
         CLAUDE_CODE
         OPENCODE
-        GEMINI_CLI
         COPILOT_CLI
         CODEX
         PI
@@ -90,7 +100,8 @@ classDiagram
     AgentShell --> AgentAdapter : delegates to
     AgentShell --> AgentType : resolves via
     ClaudeCodeAdapter ..|> AgentAdapter : satisfies
-    AgentShell ..> AgentResponse : returns
+    AgentShell ..> AgentResponse : returns on success
+    AgentShell ..> AgentExecutionError : raises on failure
     AgentShell ..> HealthCheckResult : returns
     AgentShell ..> StreamEvent : yields
     AgentShell ..> MCPServerSpec : accepts/returns
@@ -102,7 +113,17 @@ The adapter pattern uses Python's `Protocol` (structural typing) rather than ABC
 
 `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).
 
-`health_check(cwd, model, timeout)` probes an agent + model combination with a trivial prompt and returns `HealthCheckResult(healthy, exception)`. The verdict is derived from the normalised event stream (healthy = a `result` event with no `error`), not exit codes — which are unreliable, since some CLIs exit 0 on failure. The shared logic lives once in `adapters/health.py`; each adapter delegates to it.
+`health_check(cwd, model, timeout)` probes an agent + model combination with a trivial prompt
+and returns `HealthCheckResult(healthy, exception)`. The verdict is derived from the normalised
+event stream (healthy = the LAST `result` event says `content == "ok"` and no `error` event
+arrived — pi emits one `result` per agent loop, and its auto-retry runs more than one), not exit
+codes — which are unreliable, since some CLIs exit 0 on failure. `execute()` judges a run by the
+same rule and raises `AgentExecutionError` when it fails, carrying whatever partial
+response/cost/session/token data the run produced. The success/failure verdict lives once in
+`adapters/outcome.py`, shared by both surfaces so they report identical reasons for the same
+stream; `adapters/health.py` wraps it for the health probe, and `adapters/response.py` wraps it
+for `execute()`'s stream-to-`AgentResponse` collection (used by every adapter — each `execute()`
+is a single delegating call into it).
 
 ## Supported Agents
 
@@ -112,14 +133,13 @@ The adapter pattern uses Python's `Protocol` (structural typing) rather than ABC
 - [x] Codex
 - [x] Pi
 - [x] Cursor
-- [ ] Gemini CLI
 
 ## MCP Server Configuration
 
 `AgentShell` exposes a unified API for registering MCP servers across all supported agents:
 
 ```python
-from agent_shell import AgentShell
+from agent_shell.shell import AgentShell
 from agent_shell.models.agent import AgentType, MCPServerSpec, MCPServerType
 
 shell = AgentShell(agent_type=AgentType.CLAUDE_CODE)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.1.17
+Version: 0.2.0
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE
@@ -17,8 +17,8 @@ and returning the output that can be used programatically as a unified contract
   agent; swap the backend without changing a line of 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`, or async-iterate normalized `StreamEvent`s
-  with optional thinking/reasoning.
+- **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
+  or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
 - **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.
@@ -77,6 +77,22 @@ follow_up = await shell.execute(
 > `output_tokens` is a cost measure: the billed output-token count, which **includes reasoning
 > tokens** (they are billed at the output rate). It is reported consistently across all adapters.
 
+### Failure handling
+
+`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.
+
+```python
+from agent_shell.models.agent import AgentExecutionError
+
+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"
+```
+
 ### Stream
 
 ```python

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

@@ -8,8 +8,8 @@ and returning the output that can be used programatically as a unified contract
   agent; swap the backend without changing a line of 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`, or async-iterate normalized `StreamEvent`s
-  with optional thinking/reasoning.
+- **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
+  or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
 - **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.
@@ -68,6 +68,22 @@ follow_up = await shell.execute(
 > `output_tokens` is a cost measure: the billed output-token count, which **includes reasoning
 > tokens** (they are billed at the output rate). It is reported consistently across all adapters.
 
+### Failure handling
+
+`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.
+
+```python
+from agent_shell.models.agent import AgentExecutionError
+
+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"
+```
+
 ### Stream
 
 ```python

{agent_shell_py-0.1.17 → agent_shell_py-0.2.0}/agent-skills/delegating-code-review/SKILL.md

@@ -29,8 +29,17 @@ instruction in the prompt — restrict the tools. But mind how the two controls
   The whitelist is *inert under the default `auto_approve=True`* (`--dangerously-skip-permissions`
   auto-approves everything), so the `auto_approve=False` is what makes it bite:
   `allowed_tools=["Read", "Glob", "Grep", "Bash"], auto_approve=False`.
-- **OpenCode / Codex** — they ignore `allowed_tools`; use the enforced denylist instead:
-  `disallowed_tools=["edit"]`.
+- **OpenCode** — it ignores `allowed_tools`, but its denylist **is** genuinely enforced (a
+  per-subprocess `OPENCODE_PERMISSION` env var), and deny beats `auto_approve`, so keep the
+  default `auto_approve=True`: `disallowed_tools=["edit"]`.
+- **Codex / Cursor** — **in-library tool scoping gives you nothing here.** They ignore
+  `allowed_tools`, *and* they cannot enforce `disallowed_tools=["edit"]`. Codex can only deny
+  `web_search`; anything else prints
+  `UserWarning: Codex can only deny web_search; ignoring ['edit']` and the reviewer then runs
+  with unrestricted write access. Cursor has no per-call deny at all (its tool policy lives in
+  `.cursor/cli.json`). If a Codex/Cursor reviewer must not write, enforce it outside the
+  library: capture `git diff` yourself and pass it in the prompt, run the reviewer under an
+  OS-level read-only sandbox, and/or use a different agent type when read-only really matters.
 
 **This is defence-in-depth, not a sandbox.** Any reviewer that keeps `bash` (for `git diff`) can
 still write via the shell, and in-library scoping doesn't cover MCP-provided tools. For a *hard*
@@ -60,6 +69,27 @@ Flag issues by severity: CRITICAL, WARNING, or SUGGESTION.""",
 
 The reviewer will run `git diff` itself, read surrounding code for context, and report findings.
 
+## Handling a Failed Review
+
+A failed reviewer run raises `AgentExecutionError` instead of returning a response — catch it
+so a crashed or rate-limited reviewer doesn't look like a silent "no issues found":
+
+```python
+from agent_shell.models.agent import AgentExecutionError
+
+try:
+    review = await reviewer.execute(
+        cwd="/path/to/project",
+        prompt="Review the uncommitted changes in this repository.",
+        allowed_tools=["Read", "Glob", "Grep", "Bash"],
+        auto_approve=False,
+        model="sonnet",
+    )
+except AgentExecutionError as e:
+    print(f"review failed: {e}")   # e.g. "500 model name=... failed to load"
+    raise
+```
+
 ## Review a Specific Commit or Range
 
 Point the reviewer at a particular changeset — only the prompt changes.
@@ -96,7 +126,9 @@ clarification = await reviewer.execute(
 ## Cross-Agent Review
 
 Use a different agent or model than the one that wrote the code for genuine independence.
-OpenCode ignores `allowed_tools`, so restrict it with `disallowed_tools` instead.
+OpenCode ignores `allowed_tools`, so restrict it with `disallowed_tools` instead — that deny
+*is* enforced. Don't swap `AgentType.CODEX` or `AgentType.CURSOR` into this example expecting
+the same protection: they drop the deny with only a `UserWarning`.
 
 ```python
 reviewer = AgentShell(agent_type=AgentType.OPENCODE)
@@ -112,10 +144,9 @@ Flag issues by severity: CRITICAL, WARNING, or SUGGESTION.""",
 ```
 
 > OpenCode reports `cost` as `0.0` for many models — use `output_tokens` if you need a usage
-> figure. And `execute()` gives no failure signal: an empty `review.response` likely means the
-> reviewer failed. If a reliable verdict matters, `stream()` and require a `result` event with
-> `content == "ok"` — OpenCode can truncate a review with no terminal event and no error (see the
-> core skill's Error Handling).
+> figure. And a failed reviewer run raises `AgentExecutionError` rather than returning — wrap
+> the call (see [Handling a Failed Review](#handling-a-failed-review) below), since OpenCode can
+> truncate a review with no terminal event and no error (see the core skill's Error Handling).
 
 ## Prompt Patterns
 
@@ -155,9 +186,10 @@ For each gap, describe the test case that should exist and why it matters.
 |---------|-----|
 | Relying on a "do not modify files" prompt instruction for safety | Enforce it (whitelist + `auto_approve=False`, or `disallowed_tools`) |
 | Whitelisting tools but leaving the default `auto_approve=True` | `--dangerously-skip-permissions` makes the whitelist inert — set `auto_approve=False` |
-| Assuming `allowed_tools` restricts OpenCode | OpenCode ignores it — use `disallowed_tools` |
+| Assuming `allowed_tools` restricts OpenCode, Codex, or Cursor | All three ignore it |
+| `disallowed_tools` to keep a Codex/Cursor reviewer read-only | It only warns; sandbox instead |
 | Believing `disallowed_tools=["edit"]` makes the reviewer read-only | It doesn't — the model writes via `bash`; also deny `bash` (and OS-sandbox for a hard guarantee) |
 | Not giving the reviewer `Bash`/git access | Without it the reviewer can't run `git diff` — keep `bash`, or pass the diff in the prompt |
-| Not checking for empty responses from `execute()` | `execute()` gives no failure signal — an empty `review.response` likely means failure; use `stream()` to detect it |
+| Not catching `AgentExecutionError` | A failed reviewer run raises, it does not return |
 | Reviewing with the same model that wrote the code | Use a different model or agent type for independence |
 | Ignoring the review and committing anyway | At minimum, address all CRITICAL items first |

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

@@ -1,6 +1,6 @@
 ---
 name: invoking-cli-agents
-description: Use when programmatically invoking a CLI coding agent (Claude Code, OpenCode, Copilot CLI, Codex, Pi) 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 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.
 ---
 
 # Invoking CLI Agents with AgentShell
@@ -15,7 +15,7 @@ passes `model` strings through verbatim and does not manage credentials.
 
 ## When to Use
 
-- You need to invoke Claude Code, OpenCode, Copilot CLI, Codex, or Pi from Python
+- You need to invoke Claude Code, OpenCode, Copilot CLI, Codex, Pi, or Cursor from Python
 - You want to delegate a coding task to a sub-agent and collect the result
 - You need to orchestrate multi-step workflows across agents
 - You want to stream agent output in real-time
@@ -120,11 +120,11 @@ Both `execute()` and `stream()` take the same parameters.
 |-----------|------|---------|---------|
 | `cwd` | `str` | required | Working directory (must exist, else `ValueError`) |
 | `prompt` | `str` | required | Task or question for the agent |
-| `allowed_tools` | `list[str] \| None` | `None` | Whitelist of tools (agent-native names). `None` = all tools. Honoured by Claude Code, Copilot CLI, Pi; ignored by OpenCode and Codex. **Only actually enforced when `auto_approve=False`** (see Tool Restriction). |
+| `allowed_tools` | `list[str] \| None` | `None` | Whitelist of tools (agent-native names). `None` = all tools. Honoured by Claude Code, Copilot CLI, Pi; ignored by OpenCode, Codex and Cursor. **Only actually enforced when `auto_approve=False`** (see Tool Restriction). |
 | `disallowed_tools` | `list[str] \| None` | `None` | Denylist using a canonical vocabulary (see Tool Restriction). Deny takes precedence over allow **and** over `auto_approve`, but covers only built-in tools. Enforcement varies per agent; unenforceable denies emit a `UserWarning`. |
 | `model` | `str \| None` | `None` | Model alias or name, passed to the CLI verbatim (e.g. `"sonnet"`, `"opencode/big-pickle"`) |
-| `effort` | `str \| None` | `None` | Reasoning effort: `"low"`, `"medium"`, `"high"`, etc. Claude Code, Copilot, Codex, Pi. **Ignored by OpenCode.** |
-| `include_thinking` | `bool` | `False` | Yield `thinking` events in `stream()`. Claude Code, Copilot, Pi. **Dropped by `execute()`** (which keeps only text). |
+| `effort` | `str \| None` | `None` | Reasoning effort: `"low"`, `"medium"`, `"high"`, etc. Claude Code, Copilot, Codex, Pi. **Ignored by OpenCode** (silently) **and Cursor** (warns). |
+| `include_thinking` | `bool` | `False` | Yield `thinking` events in `stream()`. Claude Code, Copilot, Pi, Cursor. **Dropped by `execute()`** (which keeps only text). |
 | `auto_approve` | `bool` | `True` | Skip tool permission prompts. Mapped on every adapter (Pi *requires* a trust decision — the default avoids a hang). **On Claude Code the default `True` sends `--dangerously-skip-permissions`, which bypasses `allowed_tools`.** |
 | `session_id` | `str \| None` | `None` | Resume a previous session |
 
@@ -143,7 +143,7 @@ AgentType.OPENCODE      # OpenCode CLI
 AgentType.COPILOT_CLI   # GitHub Copilot CLI
 AgentType.CODEX         # OpenAI Codex CLI
 AgentType.PI            # Pi coding agent
-AgentType.GEMINI_CLI    # enum value only — NO adapter (raises ValueError at construction)
+AgentType.CURSOR        # Cursor CLI (cursor-agent)
 ```
 
 Capabilities differ by agent. `output_tokens` is populated on all of them; the rest varies:
@@ -155,6 +155,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 |
 
 A `✅` for `allowed_tools` means the flag is passed — but it only *enforces* with
 `auto_approve=False`; `disallowed_tools` covers only built-in tools. See Tool Restriction.
@@ -188,7 +189,9 @@ response = await shell.execute(
     auto_approve=False,
 )
 
-# OpenCode / Codex ignore allowed_tools — use the enforced denylist instead.
+# OpenCode ignores allowed_tools, but its denylist IS enforced — use that instead. (Codex and
+# Cursor ignore BOTH controls: Codex can deny only web_search, Cursor nothing at all, so for
+# those two in-library scoping buys you nothing — restrict them outside the library.)
 # Keep auto_approve at its default True: on OpenCode, auto_approve=False makes `opencode run`
 # auto-reject prompts and can silently abort the turn. (auto_approve=False is only for the
 # whitelist path above, on Claude Code / Copilot / Pi.)
@@ -211,28 +214,41 @@ response = await shell.execute(
 
 ## Error Handling
 
-AgentShell raises exceptions for its own preconditions, but **CLI agent failures are reported
-as events, not exceptions.**
+AgentShell raises exceptions for its own preconditions **and** for a failed agent run:
 
 ```python
 # cwd validation - raises ValueError if directory doesn't exist
-# Unsupported agent (e.g. AgentType.GEMINI_CLI) - raises ValueError at construction
+# Unsupported agent - an AgentType with no registered adapter raises ValueError
 # KeyboardInterrupt - AgentShell cancels the subprocess cleanly, then re-raises
 ```
 
-`execute()` returns an `AgentResponse` with whatever text accumulated (possibly empty) and
-**no failure signal** — an empty `response` usually means the agent failed. To detect failures,
-use `stream()` and treat success as a **positive** signal, the way the library's own
-`health_check` does: a `result` event with `content == "ok"` arrived **and** no `error` event.
+A run counts as failed when any of: an `error` event was emitted; the terminal `result` event
+has `content == "error"`; or no terminal `result` event arrived at all (a killed, truncated, or
+aborted run — OpenCode in particular can drop the tail and still exit 0). `execute()` raises
+`AgentExecutionError` for all three; `str(e)` is the bare reason (e.g. `"500 model
+name=qwen3.6-27b-8Q failed to load"`), and the exception also carries whatever partial data the
+run produced before failing:
 
-Failure shows up three ways, and the positive-signal check below catches all three: (1) an
-`error` event; (2) a `result` event with `content == "error"` — how a bad model or usage limit
-often surfaces, sometimes with *no* separate `error` event; (3) *no* `result` event at all —
-a turn can truncate with no terminal event and no error (OpenCode in particular can drop the
-tail and still exit 0), leaving a partial response that looks fine. Never infer success from
-"got some text and no error event." Treat a missing `result` event as failure (and consider a
-retry). Neither `execute()` nor `stream()` has a timeout, so wrap the call in `asyncio.wait_for`
-to guard against a hang.
+```python
+from agent_shell.models.agent import AgentExecutionError
+
+try:
+    response = await shell.execute(cwd=project_path, prompt="do something")
+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)
+else:
+    print(response.response)
+```
+
+`stream()` has no exception equivalent — it yields the raw events and leaves the verdict to the
+caller. Apply the same rule as a **positive** signal, the way the library's own `health_check`
+does: success is the LAST `result` event carrying `content == "ok"` **and** no `error` event —
+the loop below already does this, since each `result` overwrites the verdict. (An agent that
+retries a transient fault emits a failing `result` and then a good one.) Never infer
+success from "got some text and no error event." Neither `execute()` nor `stream()` has a
+timeout, so wrap the call in `asyncio.wait_for` to guard against a hang.
 
 ```python
 saw_ok = False
@@ -254,8 +270,9 @@ succeeded = saw_ok and error is None         # absent result => succeeded stays
   event of every adapter. It reads `0` when the `result` event never arrives (a truncated turn),
   so it is not a standalone liveness check — pair it with the success check above.
 - `cost` — real for Claude Code and paid Pi providers; frequently `0.0` for OpenCode,
-  Copilot, and Codex (they don't report it). Don't treat `cost == 0` as "the call failed".
-- `duration` — real only for Claude Code and Copilot CLI; `0.0` elsewhere.
+  Copilot, Codex, and always `0.0` for Cursor (they don't report it). Don't treat
+  `cost == 0` as "the call failed".
+- `duration` — real for Claude Code, Copilot CLI, and Cursor; `0.0` elsewhere.
 
 ## Other Capabilities
 
@@ -264,7 +281,7 @@ 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 raises `NotImplementedError`).
+  the underlying CLI's MCP config (Pi and Cursor raise `NotImplementedError`).
 
 See [api-reference.md](api-reference.md) for their full signatures and the `MCPServerSpec` model.
 
@@ -286,10 +303,10 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | Stream events live | `async for event in shell.stream(cwd, prompt)` |
 | Continue a conversation | Pass `session_id=response.session_id` |
 | Whitelist tools (Claude/Copilot/Pi) | `allowed_tools=["Read", "Glob"]` |
-| Deny tools on any agent (enforced) | `disallowed_tools=["edit", "bash"]` |
+| 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"` |
-| Increase reasoning depth | `effort="high"` (not OpenCode) |
+| 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=...)` |
 | Cancel a running agent | `KeyboardInterrupt` (handled automatically) |
@@ -302,14 +319,14 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | 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` |
-| Relying on `allowed_tools` with OpenCode/Codex | They ignore it. Use `disallowed_tools` |
+| Relying on `allowed_tools` with OpenCode/Codex/Cursor | Ignored; only OpenCode's deny works |
 | Trusting a `prompt` instruction ("don't edit files") as a guarantee | Enforce it (`disallowed_tools`, or whitelist + `auto_approve=False`) |
 | Assuming `disallowed_tools` sandboxes the agent | It covers only built-in tools; MCP/other-named tools bypass it. OS-sandbox for a hard guarantee |
 | Treating `cost == 0` as failure | Many agents don't report cost; use `output_tokens` |
-| Expecting `execute()` to expose thinking or detect failure | Use `stream()` for both |
+| Expecting `execute()` to expose thinking | Use `stream()` with `include_thinking=True` |
+| 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 |
-| Using `AgentType.GEMINI_CLI` | No adapter — raises `ValueError` at construction |
 
 ## API Reference
 

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

@@ -1,6 +1,7 @@
 # AgentShell API Reference
 
-- [Models](#models) — `AgentType`, `AgentResponse`, `StreamEvent`, `MCPServerSpec`, `HealthCheckResult`
+- [Models](#models) — `AgentType`, `AgentResponse`, `AgentExecutionError`, `StreamEvent`,
+  `MCPServerSpec`, `HealthCheckResult`
 - [StreamEvent types](#event-types)
 - [AgentShell class](#agentshell-class) — `execute`, `stream`, `health_check`, MCP management
 - [AgentAdapter protocol](#agentadapter-protocol)
@@ -16,15 +17,15 @@ from agent_shell.models.agent import AgentType
 class AgentType(StrEnum):
     CLAUDE_CODE = "claude_code"
     OPENCODE = "opencode"
-    GEMINI_CLI = "gemini_cli"   # enum only — NO adapter (raises ValueError)
     COPILOT_CLI = "copilot_cli"
     CODEX = "codex"
     PI = "pi"
+    CURSOR = "cursor"
 ```
 
 ### AgentResponse
 
-Returned by `execute()`.
+Returned by `execute()` on success.
 
 ```python
 @dataclass
@@ -36,6 +37,29 @@ class AgentResponse:
     output_tokens: int = 0   # Generated tokens (reasoning-inclusive; populated on all agents)
 ```
 
+### AgentExecutionError
+
+Raised by `execute()` — never returned — when the run failed: an `error` event was emitted, the
+terminal `result` event had `content == "error"`, or no terminal `result` event arrived at all
+(a killed, truncated, or aborted run). `str(e)` is the bare reason (e.g. `"500 model
+name=qwen3.6-27b-8Q failed to load"`). The constructor arguments double as attributes, carrying
+whatever partial data the run produced before failing.
+
+```python
+from agent_shell.models.agent import AgentExecutionError
+
+class AgentExecutionError(Exception):
+    def __init__(
+        self,
+        reason: str,              # str(e) == reason; also e.reason
+        response: str = "",       # text produced before the failure, if any
+        cost: float = 0.0,
+        session_id: str | None = None,
+        duration: float = 0.0,
+        output_tokens: int = 0,
+    ): ...
+```
+
 ### StreamEvent
 
 Yielded by `stream()`.
@@ -49,6 +73,7 @@ class StreamEvent:
     duration: float = 0.0    # Elapsed seconds (on "result" events, where supported)
     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)
 ```
 
 ### MCPServerSpec
@@ -91,14 +116,23 @@ Canonical event types emitted by `stream()`:
 |------|------|---------|--------------|
 | `system` | Session starts | `""` | `session_id` is set |
 | `text` | Agent produces output | Response text (may arrive in chunks) | |
-| `thinking` | Agent reasons (requires `include_thinking=True`; Claude Code / Copilot / Pi) | Chain-of-thought text | |
-| `tool_use` | Agent invokes a tool | Tool name (Codex: the command string) | |
-| `result` | Agent finishes | `"ok"` on success, `"error"` on agent-level failure | `cost`, `duration`, `output_tokens`, `session_id` populated where supported |
-| `error` | Agent or CLI process fails | Error message / stderr tail (last 500 chars) | |
+| `thinking` | Agent reasons (requires `include_thinking=True`; Claude Code / Copilot / Pi / Cursor) | Chain-of-thought text | |
+| `tool_use` | Agent invokes a tool | Tool name (Codex, and Cursor shell calls: the command) | |
+| `result` | Agent finishes | `"ok"` or `"error"` | see the note below |
+| `error` | Agent or CLI process fails | Error message, or stderr head+tail (500 chars each) | |
+
+> 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.
 
 > Codex emits the session-start event as `type="session"` (not `"system"`). If you branch on
 > the session event across agents, match both.
 
+> Long stderr is **not** tail-only. `format_stderr` keeps the first 500 *and* the last 500
+> characters, joined by a `... [truncated] ...` marker, so a reason stated up front
+> (cursor-agent's `Cannot use this model: <name>`) survives alongside a trailing stack trace.
+> A stderr of 1000 characters or fewer is passed through whole, with no marker.
+
 ## AgentShell Class
 
 ```python
@@ -106,7 +140,7 @@ from agent_shell.shell import AgentShell
 
 class AgentShell:
     def __init__(self, agent_type: AgentType): ...
-    # raises ValueError for an AgentType with no adapter (e.g. GEMINI_CLI)
+    # raises ValueError for an AgentType with no registered adapter
 
     async def execute(
         self,
@@ -120,13 +154,14 @@ class AgentShell:
         session_id: str | None = None,          # Resume previous session
         disallowed_tools: list[str] | None = None,  # Canonical denylist (enforced; deny > allow)
     ) -> AgentResponse: ...
+    # Raises AgentExecutionError if the run failed; see the Models section above.
 
     def stream(self, ...) -> AsyncIterator[StreamEvent]: ...   # same parameters as execute()
 
     async def health_check(
         self, cwd: str, model: str | None = None, timeout: float = 60.0,
     ) -> HealthCheckResult: ...
-    # Sends a trivial no-tool prompt; healthy iff a result=="ok" event arrives and no error.
+    # Sends a trivial no-tool prompt; healthy iff the LAST result event is "ok" and no error.
 
     async def add_mcp_server(self, mcp_server: MCPServerSpec) -> None: ...
     async def remove_mcp_server(self, mcp_server_name: str) -> None: ...
@@ -156,6 +191,7 @@ class AgentAdapter(Protocol):
     async def execute(self, cwd, prompt, allowed_tools=None, model=None, effort=None,
                       include_thinking=False, auto_approve=True, session_id=None,
                       disallowed_tools=None) -> AgentResponse: ...
+    # Raises AgentExecutionError if the run failed.
 
     def stream(self, ...) -> AsyncIterator[StreamEvent]: ...   # same signature as execute()
 
@@ -199,3 +235,24 @@ class AgentAdapter(Protocol):
 - `effort` → `--thinking` (levels: off/minimal/low/medium/high/xhigh); `auto_approve` → `--approve` / `--no-approve` (one is always sent, else `pi -p` hangs on a trust prompt).
 - `cost` is real for paid providers (`0.0` on local); `duration` is `0.0`.
 - MCP-management methods raise `NotImplementedError`.
+
+### Cursor
+- `model` → `--model` (e.g. `"sonnet-4-thinking"`, `"gpt-5"`); parameterised models take bracket
+  overrides, e.g. `"claude-opus-4-8[context=1m,effort=high]"`. A Free plan exposes only `auto`.
+- `allowed_tools` **and** `disallowed_tools` are both **ignored** (both warn). Cursor has no
+  per-call tool policy of any kind — it lives in `.cursor/cli.json` — so *nothing* in this library
+  can scope a Cursor agent; restrict it outside (read-only mount, container). `disallowed_tools`
+  warns on every call; `allowed_tools` and `effort` warn once per adapter instance.
+- `effort` is **ignored** (warns): Cursor has no effort flag, only the model bracket-override
+  above, which the adapter does not inject. `include_thinking` **is** honoured — Cursor streams
+  reasoning as `thinking` deltas.
+- `auto_approve` → `--force`; without it tools auto-*reject* but the run still completes (exit 0).
+  `--trust` is always sent regardless: untrusted, `cursor-agent` exits 1 with zero stdout and a
+  plain-text "Workspace Trust Required" on stderr.
+- Session resume is `--resume=<id>` (the `=` form binds the id, whose CLI arg is optional). The
+  resumed run reports the SAME id — but an unknown id is **accepted**, creating a session under
+  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`).