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

{agent_shell_py-0.2.2 → agent_shell_py-0.2.4}/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,9 @@ 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 |
+| Grok | `grok mcp add --scope user` subprocess | `~/.grok/config.toml` (managed by CLI) |
 
-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.
+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`. Grok listing reads user-scope `mcp_servers` entries from `~/.grok/config.toml` directly for the same reason. 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.
 
 ## Test Philosophy
 
@@ -183,7 +185,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.2 → agent_shell_py-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-shell-py
-Version: 0.2.2
+Version: 0.2.4
 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.
 
@@ -279,6 +279,36 @@ print(f"Session: {response.session_id}")
 > only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
 > `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
 
+### 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
 
 Register MCP servers for any supported agent through a unified API. All adapters use user-scope configuration so registrations persist across the agent's `execute`/`stream` calls.
@@ -318,7 +348,7 @@ 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` 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, Codex, and Grok. Claude Code reads user-scope entries directly from `~/.claude.json`, and Grok from `~/.grok/config.toml`, 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`.
 
 ## Logging
 

{agent_shell_py-0.2.2 → agent_shell_py-0.2.4}/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.
 
@@ -270,6 +270,36 @@ print(f"Session: {response.session_id}")
 > only `model=None`/`"auto"` works. MCP servers are declared in `.cursor/mcp.json`; the
 > `add`/`remove`/`list` MCP methods raise `NotImplementedError`.
 
+### 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
 
 Register MCP servers for any supported agent through a unified API. All adapters use user-scope configuration so registrations persist across the agent's `execute`/`stream` calls.
@@ -309,7 +339,7 @@ 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` 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, Codex, and Grok. Claude Code reads user-scope entries directly from `~/.claude.json`, and Grok from `~/.grok/config.toml`, 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`.
 
 ## Logging
 

{agent_shell_py-0.2.2 → agent_shell_py-0.2.4}/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-02
+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
@@ -20,9 +21,9 @@ Last updated: 2026-08-02
 | **Allowed tools** | `--allowed-tools` | No direct flag | `--allow-tool`, `--available-tools` | `tools` in config |
 | **Disallowed tools** | `--disallowed-tools` | `web_search` config only | `--deny-tool` | `OPENCODE_PERMISSION` env / `permission` config |
 | **Stream output** | `--output-format stream-json` | `--json` (NDJSON) | `--output-format=json` (JSONL) | `--format json` |
-| **Working dir** | cwd + `--add-dir` | `--cd` / `-C` | cwd (no flag) | cwd (no flag) |
+| **Working dir** | cwd + `--add-dir` | `--cd` / `-C` | cwd / `-C` | cwd |
 | **System prompt** | `--system-prompt` / `--append-system-prompt` | No flag (files only) | No flag (files only) | `instructions` in config |
-| **Budget** | `--max-budget-usd` | No direct flag | No direct flag | No direct flag |
+| **Budget** | `--max-budget-usd` | No direct flag | `--max-ai-credits` | No direct flag |
 | **Auto-approve** | `--dangerously-skip-permissions` | `--yolo` | `--yolo` / `--allow-all` | Auto in `run` mode |
 | **Session resume** | `--resume` | `exec resume <id>` | `--resume` | `-s <id>` |
 
@@ -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
 
@@ -123,23 +125,32 @@ real discovery commands.
 
 ## Copilot CLI (GitHub)
 
-- **Headless mode**: `-p` / `--prompt` for one-shot, `--acp --stdio` for programmatic JSON-RPC
-- **Model**: `--model` (default `claude-sonnet-4.5`)
-- **Effort**: `--effort low|medium|high` or `--reasoning-effort low|medium|high`
-- **Allowed tools**: `--allow-tool`, `--deny-tool`, `--available-tools`, `--excluded-tools`, `--allow-all-tools`
-- **Auto-approve**: `--allow-all` / `--yolo`, `--autopilot`
+- **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`.
+- **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
+  permissions
+- **Agent mode**: `--mode interactive|plan|autopilot`; `--autopilot` is the shortcut
 - **Output format**: `--output-format=json` (JSONL)
 - **Silent mode**: `--silent` suppresses stats, prints only response
-- **Working directory**: Uses cwd (no flag), ACP mode uses `newSession` parameter
-- **System prompt**: No CLI flag, uses `.github/copilot-instructions.md` and `AGENTS.md` files
-- **Budget**: No per-run flag, auto-compacts at 95% token limit
+- **Working directory**: CLI supports `-C <directory>`; AgentShell sets subprocess `cwd`
+- **System prompt**: No CLI flag; uses `.github/copilot-instructions.md` and `AGENTS.md` files
+- **AI credit budget**: `--max-ai-credits <credits>` limits credits for the session
+- **Token budget**: No per-run flag; auto-compacts at 95% of the token limit
 - **Path permissions**: `--allow-all-paths`, `--disallow-temp-dir`
 - **URL permissions**: `--allow-all-urls`, `--allow-url`, `--deny-url`
-- **Session**: `--resume`, `--continue`, plus `--session-id=<uuid>` to start a NEW session under
-  a chosen id. The adapter resumes with `--resume <id>`. The resumed run reports the SAME
-  `sessionId`, and an unknown id is rejected ("No session, task, or name matched"), so id
-  identity is real evidence the CLI continued that session (measured 2026-07-26)
-- **ACP mode**: `--acp --stdio` or `--acp --port 3000` for JSON-RPC integration
+- **Session**: `--resume`, `--continue`, and `--session-id <id>`. The latter resumes an existing
+  session or task, or assigns a UUID to a new session. AgentShell resumes with `--resume <id>`.
+  The resumed run reports the SAME `sessionId`, and an unknown id is rejected
+  ("No session, task, or name matched"), so id identity is real evidence the CLI continued that
+  session (measured 2026-07-26).
+- **ACP mode**: `--acp` uses stdio by default. Copilot CLI 1.0.78 also accepts hidden
+  `--stdio` and `--port <port>` transport options; they are not shown by `copilot --help`.
 
 ## OpenCode
 
@@ -189,6 +200,54 @@ real discovery commands.
 - **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
@@ -244,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.2 → agent_shell_py-0.2.4}/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
 
@@ -335,8 +337,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.2 → agent_shell_py-0.2.4}/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.2 → agent_shell_py-0.2.4}/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.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)
 
 __commit_id__ = commit_id = None

{agent_shell_py-0.2.2 → agent_shell_py-0.2.4}/src/agent_shell/adapters/copilot_cli_adapter.py

@@ -44,6 +44,21 @@ _DISALLOWED_TOOL_MAP = {
     "edit": ["write"],
 }
 
+_COPILOT_EFFORTS = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
+
+
+def _normalize_effort(effort: str | None) -> str | None:
+    if effort is None:
+        return None
+
+    normalized = effort.lower() if isinstance(effort, str) else None
+    if normalized not in _COPILOT_EFFORTS:
+        choices = ", ".join(_COPILOT_EFFORTS)
+        raise ValueError(
+            f"Unsupported Copilot effort {effort!r}; accepted choices: {choices}"
+        )
+    return normalized
+
 
 def _json_rpc_frame(message: dict) -> bytes:
     payload = json.dumps(message, separators=(",", ":")).encode("utf-8")
@@ -160,6 +175,7 @@ class CopilotCLIAdapter:
             session_id: str | None = None,
             disallowed_tools: list[str] | None = None,
     ) -> AsyncIterator[StreamEvent]:
+        effort = _normalize_effort(effort)
         cmd = [
             "copilot", "-p", prompt,
             "--output-format", "json",