agent-shell-py 0.2.3__tar.gz → 0.2.5__tar.gz

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/AGENTS.md

@@ -142,6 +142,7 @@ command, and never substitutes a static catalog. "Available" means advertised as
 - [x] Codex
 - [x] Pi
 - [x] Cursor
+- [x] Grok
 
 ## MCP Server Configuration
 
@@ -170,8 +171,19 @@ All adapters write to user-scope configuration:
 | OpenCode | direct JSON file write | `~/.config/opencode/opencode.json` |
 | Copilot CLI | direct JSON file write | `~/.copilot/mcp-config.json` |
 | Codex | `codex mcp add` subprocess | Codex config |
-
-Adds are idempotent (overwrite existing entries with the same name). Removes warn rather than raise when the named server is not found. Claude Code listing reads the user-scope `mcpServers` entries from `~/.claude.json` directly, avoiding the health checks and human-readable output of `claude mcp list`. MCP is not implemented for Pi or Cursor — all three methods raise `NotImplementedError`. Pi manages capability via `pi install` extensions (which needs investigation before wiring up); Cursor's `mcp` subcommands are login/list/list-tools/enable/disable only (no add/remove — servers are declared in `.cursor/mcp.json`), and `mcp list` reports only `name: status`, not the transport an `MCPServerSpec` needs.
+| Cursor | direct JSON file write | `~/.cursor/mcp.json` |
+| Grok | `grok mcp add --scope user` subprocess | `~/.grok/config.toml` (managed by CLI) |
+
+Adds are idempotent (update existing entries with the same name). Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport, and writes its file
+atomically with user-only permissions. Removes warn rather than raise when the named server is not
+found. Claude Code listing reads the user-scope `mcpServers`
+entries from `~/.claude.json` directly, avoiding the health checks and human-readable output of
+`claude mcp list`. Cursor manages user-scope MCP entries directly in `~/.cursor/mcp.json` because
+its `mcp` subcommands have no add/remove commands. Grok listing reads user-scope `mcp_servers`
+entries from `~/.grok/config.toml` directly for the same reason. Pi's MCP add/remove/list methods
+raise `NotImplementedError`. Pi manages capability via `pi install` extensions, which needs
+investigation before wiring up.
 
 ## Test Philosophy
 
@@ -183,7 +195,7 @@ Tests validate real functionality, not code coverage metrics. Three tiers, each
 | **Integration** | Full flow through `AgentShell` -> `Adapter` -> parser with mocked subprocess | Yes | No |
 | **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
+The model-discovery E2E test is the exception: it calls all seven real CLIs but only reads
 metadata, so it sends no inference request and incurs no model-token cost.
 
 Integration tests mirror the E2E tests but substitute mocked subprocesses emitting captured CLI

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.2.3
+Version: 0.2.5
 Summary: A lightweight abstraction for executing CLI coding agents headlessly
 License-Expression: MIT
 License-File: LICENSE
@@ -15,8 +15,8 @@ and returning the output that can be used programatically as a unified contract
 
 - **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.
+- **Seven CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor, and Grok
+  behind a common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
   or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
 - **Session resumption** — continue any conversation by passing back its `session_id`.
@@ -64,7 +64,7 @@ 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 \
+  --agent claude-code opencode github-copilot codex pi cursor grok \
   --yes
 ```
 
@@ -213,10 +213,10 @@ response = await shell.execute(
   `mcp__server__tool`, or a harness-specific name like `Write`, or Copilot's `view`).
 - Deny takes precedence over auto-approve on every backend that supports it.
 - Where a backend cannot enforce a deny, the adapter emits a `UserWarning` listing the
-  ignored tools rather than failing silently. Coverage varies: Claude and OpenCode enforce
-  all five canonical names; Copilot enforces only `bash`/`edit` canonically (use a verbatim
-  name for its other tools); Codex can only deny `web_search`; Cursor cannot enforce any
-  per-call deny (its tool policy lives in `.cursor/cli.json`).
+  ignored tools rather than failing silently. Coverage varies: Claude, OpenCode, and Grok
+  enforce all five canonical names; Copilot enforces only `bash`/`edit` canonically (use a
+  verbatim name for its other tools); Codex can only deny `web_search`; Cursor cannot
+  enforce any per-call deny (its tool policy lives in `.cursor/cli.json`).
 - Denying `edit` or `read` is **best-effort**: a model can still modify or read files through
   the shell, so also deny `bash` when you need a hard file boundary.
 
@@ -276,8 +276,39 @@ print(f"Session: {response.session_id}")
 > tools are auto-*rejected* but the run still completes. `allowed_tools`, `effort`, and
 > `disallowed_tools` are **ignored** — Cursor exposes no per-call tool policy or effort flag
 > (tool policy lives in `.cursor/cli.json`), so each emits a `UserWarning`. On a Free plan
-> only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
-> `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
+> only `model=None`/`"auto"` works. MCP add/remove/list are supported by directly managing
+> the user-scope `~/.cursor/mcp.json` file because `cursor-agent mcp` has no add/remove
+> subcommands.
+
+### Grok
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.GROK)
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Can you tell me about this project?",
+    model="grok-4.5",
+)
+
+print(response.response)
+print(f"Session: {response.session_id}")
+print(f"Cost: ${response.cost:.4f}")
+```
+
+> **Note:** Grok runs headlessly via `grok -p --output-format streaming-messages-json`
+> (full assistant blocks — not token-delta `streaming-json`, which would break
+> newline-joined text collection). With `auto_approve=True` (the default) the adapter
+> passes `--always-approve`. `effort` maps to `--reasoning-effort`, `allowed_tools` to
+> `--tools`, and `disallowed_tools` to `--disallowed-tools` (canonical `bash` maps to
+> `run_terminal_cmd` — the working deny id, not init.tools' `run_terminal_command`).
+> The terminal `result` event carries cost (may be `0` on some auth paths), duration, and
+> raw `usage.output_tokens` (reasoning is already inside that figure when reported).
+> MCP add/remove/list are supported via `grok mcp` with **user scope only**
+> (`~/.grok/config.toml`).
 
 ## MCP Servers
 
@@ -318,7 +349,14 @@ await shell.add_mcp_server(MCPServerSpec(
 ))
 ```
 
-`add_mcp_server` overwrites an existing server with the same name. `remove_mcp_server` warns rather than raises when the named server is not found. `list_mcp_servers()` works for Claude Code, OpenCode, Copilot CLI, and Codex. Claude Code reads user-scope entries directly from `~/.claude.json`, so listing does not launch configured servers for health checks. MCP is not supported for Pi or Cursor — neither CLI exposes an add/remove subcommand, so all three MCP methods raise `NotImplementedError`.
+`add_mcp_server` adds or updates a server with the same name. Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport. The configuration
+is written atomically with user-only permissions. `remove_mcp_server` warns rather than raises
+when the named server is not found. `list_mcp_servers()` works for
+Claude Code, OpenCode, Copilot CLI, Codex, Cursor, and Grok. Claude Code reads user-scope
+entries directly from `~/.claude.json`, Cursor from `~/.cursor/mcp.json`, and Grok from
+`~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP
+is not supported for Pi; all three MCP methods raise `NotImplementedError`.
 
 ## Logging
 

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/README.md

@@ -6,8 +6,8 @@ and returning the output that can be used programatically as a unified contract
 
 - **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.
+- **Seven CLI agents** — Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor, and Grok
+  behind a common adapter protocol.
 - **Execute or stream** — get one `AgentResponse` (raises `AgentExecutionError` on a failed run),
   or async-iterate normalized `StreamEvent`s with optional thinking/reasoning.
 - **Session resumption** — continue any conversation by passing back its `session_id`.
@@ -55,7 +55,7 @@ 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 \
+  --agent claude-code opencode github-copilot codex pi cursor grok \
   --yes
 ```
 
@@ -204,10 +204,10 @@ response = await shell.execute(
   `mcp__server__tool`, or a harness-specific name like `Write`, or Copilot's `view`).
 - Deny takes precedence over auto-approve on every backend that supports it.
 - Where a backend cannot enforce a deny, the adapter emits a `UserWarning` listing the
-  ignored tools rather than failing silently. Coverage varies: Claude and OpenCode enforce
-  all five canonical names; Copilot enforces only `bash`/`edit` canonically (use a verbatim
-  name for its other tools); Codex can only deny `web_search`; Cursor cannot enforce any
-  per-call deny (its tool policy lives in `.cursor/cli.json`).
+  ignored tools rather than failing silently. Coverage varies: Claude, OpenCode, and Grok
+  enforce all five canonical names; Copilot enforces only `bash`/`edit` canonically (use a
+  verbatim name for its other tools); Codex can only deny `web_search`; Cursor cannot
+  enforce any per-call deny (its tool policy lives in `.cursor/cli.json`).
 - Denying `edit` or `read` is **best-effort**: a model can still modify or read files through
   the shell, so also deny `bash` when you need a hard file boundary.
 
@@ -267,8 +267,39 @@ print(f"Session: {response.session_id}")
 > tools are auto-*rejected* but the run still completes. `allowed_tools`, `effort`, and
 > `disallowed_tools` are **ignored** — Cursor exposes no per-call tool policy or effort flag
 > (tool policy lives in `.cursor/cli.json`), so each emits a `UserWarning`. On a Free plan
-> only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
-> `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
+> only `model=None`/`"auto"` works. MCP add/remove/list are supported by directly managing
+> the user-scope `~/.cursor/mcp.json` file because `cursor-agent mcp` has no add/remove
+> subcommands.
+
+### Grok
+
+```python
+from agent_shell.shell import AgentShell
+from agent_shell.models.agent import AgentType
+
+shell = AgentShell(agent_type=AgentType.GROK)
+
+response = await shell.execute(
+    cwd="/path/to/project",
+    prompt="Can you tell me about this project?",
+    model="grok-4.5",
+)
+
+print(response.response)
+print(f"Session: {response.session_id}")
+print(f"Cost: ${response.cost:.4f}")
+```
+
+> **Note:** Grok runs headlessly via `grok -p --output-format streaming-messages-json`
+> (full assistant blocks — not token-delta `streaming-json`, which would break
+> newline-joined text collection). With `auto_approve=True` (the default) the adapter
+> passes `--always-approve`. `effort` maps to `--reasoning-effort`, `allowed_tools` to
+> `--tools`, and `disallowed_tools` to `--disallowed-tools` (canonical `bash` maps to
+> `run_terminal_cmd` — the working deny id, not init.tools' `run_terminal_command`).
+> The terminal `result` event carries cost (may be `0` on some auth paths), duration, and
+> raw `usage.output_tokens` (reasoning is already inside that figure when reported).
+> MCP add/remove/list are supported via `grok mcp` with **user scope only**
+> (`~/.grok/config.toml`).
 
 ## MCP Servers
 
@@ -309,7 +340,14 @@ await shell.add_mcp_server(MCPServerSpec(
 ))
 ```
 
-`add_mcp_server` overwrites an existing server with the same name. `remove_mcp_server` warns rather than raises when the named server is not found. `list_mcp_servers()` works for Claude Code, OpenCode, Copilot CLI, and Codex. Claude Code reads user-scope entries directly from `~/.claude.json`, so listing does not launch configured servers for health checks. MCP is not supported for Pi or Cursor — neither CLI exposes an add/remove subcommand, so all three MCP methods raise `NotImplementedError`.
+`add_mcp_server` adds or updates a server with the same name. Cursor preserves native fields
+that `MCPServerSpec` cannot represent when an update keeps the same transport. The configuration
+is written atomically with user-only permissions. `remove_mcp_server` warns rather than raises
+when the named server is not found. `list_mcp_servers()` works for
+Claude Code, OpenCode, Copilot CLI, Codex, Cursor, and Grok. Claude Code reads user-scope
+entries directly from `~/.claude.json`, Cursor from `~/.cursor/mcp.json`, and Grok from
+`~/.grok/config.toml`, so listing does not launch configured servers for health checks. MCP
+is not supported for Pi; all three MCP methods raise `NotImplementedError`.
 
 ## Logging
 

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/docs/development/agent_parameter_comparison.md

@@ -1,10 +1,11 @@
 # Agent CLI Parameter Comparison
 
 Comparison of headless/non-interactive configuration across supported CLI coding agents.
-Last updated: 2026-08-05
+Last updated: 2026-08-08
 
-> The summary matrix below has no Pi or Cursor column (it predates both adapters); see the
-> per-agent detail sections, the model-discovery section, and the `disallowed_tools` table.
+> The summary matrix below has no Pi, Cursor, or Grok column (it predates those adapters);
+> see the 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
@@ -55,6 +56,7 @@ Discovery reads CLI metadata and makes no inference call.
 | Codex | `codex debug models` | visible model `slug` |
 | Pi | `pi --no-approve --list-models` | `provider/model` |
 | Cursor | `cursor-agent models` | ID before the first ` - ` |
+| Grok | `grok models` | name after optional `* `, before `(default)` |
 
 Important semantics:
 
@@ -74,9 +76,9 @@ Important semantics:
   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.
+The behavior was verified against the installed CLIs on 2026-08-08 without inference
+spend (Grok included). CI covers captured real outputs through `AgentShell`; a local E2E
+test checks all seven real discovery commands.
 
 ## Claude Code
 
@@ -126,9 +128,9 @@ real discovery commands.
 - **Headless mode**: `-p` / `--prompt` for one-shot; `--acp` for Agent Client Protocol
 - **Model**: `--model <model>`; use `auto` to let Copilot choose
 - **Effort**: `--effort` / `--reasoning-effort` with choices
-  `none|minimal|low|medium|high|xhigh|max`. AgentShell accepts effort values
-  case-insensitively, validates them against these choices, and passes the normalized lowercase
-  value to Copilot via `--effort`.
+  `none|minimal|low|medium|high|xhigh|max`. AgentShell treats `None` and `""` as omitted, so
+  Copilot uses its default. Explicit values, including `"none"`, are accepted case-insensitively,
+  validated against these choices, and passed to Copilot via `--effort` in lowercase.
 - **Allowed tools**: `--allow-tool`, `--deny-tool`, `--available-tools`,
   `--excluded-tools`, `--allow-all-tools`
 - **Auto-approve**: `--allow-all-tools`; `--allow-all` / `--yolo` also grant path and URL
@@ -191,13 +193,61 @@ real discovery commands.
   cursor-agent ACCEPTS an unknown id — `--resume=<never-seen-uuid>` starts a session under that
   id and echoes it back rather than failing, so id identity proves the flag was passed through
   and honoured, not that a prior transcript was replayed (measured 2026-07-26)
-- **MCP**: `cursor-agent mcp` = login/list/list-tools/enable/disable only (no add/remove);
-  servers declared in `.cursor/mcp.json`. All three adapter MCP methods raise
-  `NotImplementedError` — including `list_mcp_servers`, because `mcp list` emits only
-  `name: status` and cannot rebuild an `MCPServerSpec`
+- **MCP**: `cursor-agent mcp` = login/list/list-tools/enable/disable only (no add/remove).
+  The adapter manages user-scope servers directly in `~/.cursor/mcp.json`, which provides the
+  transport details that `mcp list` omits. Writes are atomic and user-only; same-transport
+  updates preserve Cursor-native fields that `MCPServerSpec` cannot represent.
 - **Usage**: the terminal `result` event carries `usage.outputTokens` (undocumented but real)
   and `duration_ms`; there is no cost field, so `cost` is `0.0`
 
+## Grok (xAI Grok Build)
+
+Flags below are the ones the adapter actually emits (`_build_command` in
+`src/agent_shell/adapters/grok_adapter.py`); this is not a full survey of the Grok CLI.
+Measured against grok 1.0.0 (3cd0d0cbce) on 2026-08-08.
+
+- **Headless mode**: `-p` / `--single <PROMPT>` with
+  `--output-format streaming-messages-json` (Anthropic Messages NDJSON on stdout).
+  The adapter deliberately does **not** use `streaming-json`: that format emits token
+  `text.data` fragments, and execute()'s `"\n".join` over text events would explode
+  replies (same class of bug as issue #6; pi waits for `text_end`, copilot uses full
+  `assistant.message`)
+- **Model**: `-m` / `--model` (e.g. `grok-4.5`). `grok models` prints plain text
+  (`Default model:` + `Available models:` list); the adapter returns the bare selectors
+- **Effort**: `--reasoning-effort` / `--effort`
+  (`none|minimal|low|medium|high|xhigh|max`)
+- **Allowed tools**: `--tools` (comma-joined native tool ids such as `read_file,list_dir`)
+- **Disallowed tools**: `--disallowed-tools` (comma-joined). Canonical map (measured):
+  `bash`→`run_terminal_cmd` (NOT `run_terminal_command` — that id appears in
+  `system/init.tools` but is a no-op as a deny), `edit`→`search_replace,write`,
+  `read`→`read_file`, `web_search`/`web_fetch` one-to-one
+- **Auto-approve**: `--always-approve`
+- **Output format**: adapter uses `streaming-messages-json` only
+- **Working directory**: process cwd (also has `--cwd`, unused by the adapter)
+- **Session**: `--resume` / `-r` `[SESSION_ID_OR_TITLE]`, `--continue`, `--session-id`
+  (new id only). The adapter resumes with `--resume <id>`. `system/init` and `result`
+  carry `session_id`; a resumed run should report the same id (see e2e resume test)
+- **Usage / cost**: terminal `result` carries `total_cost_usd` (may be `0` on some
+  OAuth/pool paths), `duration_ms`, and `usage.output_tokens`. When
+  `usage.reasoning_tokens` is present it is a **subset** of `output_tokens` (Grok's
+  `total_tokens` math uses `output_tokens` alone) — AgentShell reports raw
+  `output_tokens` and must not add them. `duration = duration_ms/1000`
+- **Stream events (adapter mapping)** — Cursor/Claude-shaped:
+  - `system/init` → `StreamEvent(type="system", session_id=...)`
+  - `assistant.message.content[]` text blocks → `StreamEvent(type="text")`
+  - thinking blocks → `StreamEvent(type="thinking")` when `include_thinking`
+  - `tool_use` / `server_tool_use` blocks → `StreamEvent(type="tool_use", content=name)`
+  - `result` → `StreamEvent(type="result", content="ok"|"error", ...)` via `is_error`;
+    optional `errors[]` populates `StreamEvent.error`
+- **MCP**: full CLI — `grok mcp add|remove|list|enable|disable|doctor`. Adapter uses
+  `grok mcp add --scope user` (add-or-update; no pre-remove) and
+  `grok mcp remove --scope user` (unscoped remove can hit project config). Listing reads
+  `~/.grok/config.toml` `[mcp_servers.*]` (stdio: `command`/`args`/`env`; http:
+  `url`/`headers`)
+- **Auth**: `grok login` or `XAI_API_KEY`. Model listing works while logged in via
+  grok.com account; execution requires auth
+- **Project rules**: reads `AGENTS.md` and `CLAUDE.md` (Claude Code compatible)
+
 ## Pi
 
 Flags below are the ones the adapter actually emits (`_build_command` in
@@ -253,6 +303,7 @@ through **verbatim** (e.g. `mcp__server__tool`, or a harness-specific name like
 | Codex | `-c web_search="disabled"` only | no name-based deny; web_search key verified on codex-cli 0.133.0 but version-fragile (upstream `web_search_mode`), guarded by an e2e test; every other canonical/verbatim name warns and is ignored |
 | Cursor | none (no per-call flag) | tool policy is config-file only (`.cursor/cli.json`); the adapter has no `canonical → native` map, so **every** deny (canonical or verbatim) warns and is ignored |
 | Pi | `--exclude-tools` (comma-joined) | `edit` → `edit,write`; no web tool, so those warn |
+| Grok | `--disallowed-tools` (comma-joined) | `bash`→`run_terminal_cmd` (not init.tools' `run_terminal_command`); `edit`→`search_replace,write`; `read`→`read_file`; web tools one-to-one |
 
 When an adapter cannot honor a requested canonical deny it emits a `UserWarning` listing
 the ignored names rather than silently dropping the deny (fail-loud). A caller who knows a

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/skills/invoking-cli-agents/SKILL.md

@@ -4,8 +4,8 @@ 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,
+  Copilot CLI, Codex, Pi, Cursor, and Grok. Keywords: AgentShell, list_models, headless
+  agent, model discovery, subprocess, allowed_tools, disallowed_tools, session_id, cost,
   output_tokens.
 ---
 
@@ -21,7 +21,7 @@ passes `model` strings through verbatim and does not manage credentials.
 
 ## When to Use
 
-- You need to invoke Claude Code, OpenCode, Copilot CLI, Codex, Pi, or Cursor from Python
+- You need to invoke Claude Code, OpenCode, Copilot CLI, Codex, Pi, Cursor, or Grok 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
@@ -151,11 +151,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, Codex and Cursor. **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, Grok; ignored by OpenCode, Codex and Cursor. **Only actually enforced when `auto_approve=False`** on some agents (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** (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). |
+| `effort` | `str \| None` | `None` | Reasoning effort: `"low"`, `"medium"`, `"high"`, etc. Claude Code, Copilot, Codex, Pi, Grok. **Ignored by OpenCode** (silently) **and Cursor** (warns). |
+| `include_thinking` | `bool` | `False` | Yield `thinking` events in `stream()`. Claude Code, Copilot, Pi, Cursor, Grok. **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 |
 
@@ -175,6 +175,7 @@ AgentType.COPILOT_CLI   # GitHub Copilot CLI
 AgentType.CODEX         # OpenAI Codex CLI
 AgentType.PI            # Pi coding agent
 AgentType.CURSOR        # Cursor CLI (cursor-agent)
+AgentType.GROK          # xAI Grok Build CLI (grok)
 ```
 
 Capabilities differ by agent. `output_tokens` is populated on all of them; the rest varies:
@@ -187,6 +188,7 @@ Capabilities differ by agent. `output_tokens` is populated on all of them; the r
 | 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 |
+| Grok | ✅ | ✅ all canonical | ✅ | ⚠️ may be `0.0` | ✅ real | ✅ user-scope |
 
 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.
@@ -300,10 +302,10 @@ succeeded = saw_ok and error is None         # absent result => succeeded stays
 - `output_tokens` — the portable "how much did it generate" signal; populated on the `result`
   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, 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.
+- `cost` — real for Claude Code, Grok (usually), and paid Pi providers; frequently `0.0` for
+  OpenCode, Copilot, Codex, and always `0.0` for Cursor (they don't report it). Grok may also
+  report `0.0` on some OAuth/pool paths. Don't treat `cost == 0` as "the call failed".
+- `duration` — real for Claude Code, Copilot CLI, Cursor, and Grok; `0.0` elsewhere.
 
 ## Other Capabilities
 
@@ -314,7 +316,8 @@ succeeded = saw_ok and error is None         # absent result => succeeded stays
   **not** run your prompt, so use the stream-based check above when you care about a specific
   call's outcome.
 - **MCP server management** — `add_mcp_server`, `remove_mcp_server`, `list_mcp_servers` manage
-  the underlying CLI's MCP config (Pi and Cursor raise `NotImplementedError`).
+  user-scope MCP configuration. Pi raises `NotImplementedError`; Cursor is managed directly
+  through `~/.cursor/mcp.json` because `cursor-agent mcp` has no add/remove subcommands.
 
 See [api-reference.md](api-reference.md) for their full signatures and the `MCPServerSpec` model.
 
@@ -335,8 +338,8 @@ logging.getLogger("agent_shell").addHandler(logging.StreamHandler())
 | Get a complete answer | `await shell.execute(cwd, prompt)` |
 | 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 (Claude/OpenCode/Copilot/Pi) | `disallowed_tools=["edit", "bash"]` |
+| Whitelist tools (Claude/Copilot/Pi/Grok) | `allowed_tools=["Read", "Glob"]` |
+| Deny tools (Claude/OpenCode/Copilot/Pi/Grok) | `disallowed_tools=["edit", "bash"]` |
 | Track usage | Read `response.output_tokens` (portable) or `response.cost` |
 | Discover selectable models | `await shell.list_models(cwd)` |
 | Use a specific model | Pass one returned string as `model=...` |

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/skills/invoking-cli-agents/api-reference.md

@@ -21,6 +21,7 @@ class AgentType(StrEnum):
     CODEX = "codex"
     PI = "pi"
     CURSOR = "cursor"
+    GROK = "grok"
 ```
 
 ### AgentResponse
@@ -274,3 +275,20 @@ class AgentAdapter(Protocol):
 - `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`).
+
+### Grok
+- Headless: `grok -p --output-format streaming-messages-json` (full assistant blocks; not
+  token-delta `streaming-json`, which would break newline-joined text collection).
+- `model` → `-m` / `--model` (e.g. `"grok-4.5"`). `list_models()` parses `grok models` text.
+- `allowed_tools` → `--tools`; `disallowed_tools` → `--disallowed-tools` with all five canonical
+  names. **Important:** `bash` maps to `run_terminal_cmd` (the working deny id). Init lists the
+  shell tool as `run_terminal_command`, but denying that longer name is a no-op on grok 1.0.0.
+  `edit` → `search_replace,write`.
+- `effort` → `--reasoning-effort`; `auto_approve` → `--always-approve`; `include_thinking` is
+  honoured from assistant thinking blocks.
+- Session resume → `--resume <id>`. `system/init` and `result` carry `session_id`.
+- `cost` comes from `result.total_cost_usd` (may be `0.0` on some OAuth/pool paths);
+  `duration` from `duration_ms`; `output_tokens` is raw `usage.output_tokens` (reasoning is a
+  subset when present — do not add `reasoning_tokens`).
+- MCP via `grok mcp add|remove --scope user` only (unscoped remove can hit project config).
+  `list_mcp_servers()` reads `~/.grok/config.toml`.

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

{agent_shell_py-0.2.3 → agent_shell_py-0.2.5}/src/agent_shell/adapters/copilot_cli_adapter.py

@@ -48,7 +48,7 @@ _COPILOT_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
 
 
 def _normalize_effort(effort: str | None) -> str | None:
-    if effort is None:
+    if effort is None or effort == "":
         return None
 
     normalized = effort.lower() if isinstance(effort, str) else None