playmaker-cli 0.4.0__tar.gz → 0.5.1__tar.gz

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-07-27
+
+### Fixed
+
+- **The bundled coach skill taught agy model names agy no longer accepts.**
+  `agy models` switched from quoted display strings (`"Claude Opus 4.6
+  (Thinking)"`) to bare slugs (`claude-opus-4-6-thinking`), so every agy
+  dispatch the skill proposed failed model validation. The skill now says to
+  read the live roster from `agy models` instead of spelling names from
+  memory. It also recommended `codex -m gpt-5-codex`, which fails on accounts
+  whose plan lacks that model; codex dispatches now default to the account's
+  own default model. Both fixes landed on main just after v0.5.0 was tagged —
+  this release exists because the skill ships inside the wheel, so doc fixes
+  are not live until published.
+
+## [0.5.0] - 2026-07-27
+
+### Changed
+
+- **Sub-agent permissions are configurable, and Claude no longer skips them by
+  default.** 0.4 passed `--dangerously-skip-permissions` to every Claude
+  dispatch because the alternative was believed to be a run that stalls on the
+  first prompt. That is not what happens: a headless `claude -p` without
+  permissions answers "I need your permission" and returns immediately, having
+  changed nothing. There is also a middle tier, verified against claude 2.x:
+  `--permission-mode acceptEdits` lets the agent edit files and run commands
+  inside the dispatch `--cwd` while claude itself refuses anything outside it.
+
+  That is the new default. `[agents.claude]` now accepts `permission_mode`,
+  `allowed_tools` and `disallowed_tools`, and `yolo = true` restores the old
+  no-boundary behaviour in one line. The 0.4 spelling `skip_permissions = true`
+  is still honoured; `skip_permissions = false` now falls through to the
+  default mode instead of producing a run that does nothing.
+
+  **Upgrade note:** a subtask that needs to write outside its `--cwd` will now
+  be refused. Point `--cwd` at the right directory, or set `yolo = true`.
+
+### Added
+
+- `[agents.codex] sandbox` — forwarded to `codex exec -s`
+  (`read-only` / `workspace-write` / `danger-full-access`). Codex needs no
+  permission-skipping flag: `codex exec` is already non-interactive and
+  sandboxes the model's shell itself, and playmaker never passed it one.
+- `[agents.agy] sandbox` — forwarded to `agy --sandbox`. agy has no per-mode
+  permission flag, so it keeps `yolo = true` as its default.
+
 ## [0.4.0] - 2026-07-27
 
 ### Added

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: playmaker-cli
-Version: 0.4.0
+Version: 0.5.1
 Summary: Playing-coach CLI for orchestrating Claude Code, Codex and Antigravity sub-agents in parallel.
 Project-URL: Homepage, https://github.com/vladsafedev/playmaker
 Project-URL: Repository, https://github.com/vladsafedev/playmaker
@@ -22,7 +22,7 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: rich>=13.7
-Requires-Dist: typer>=0.12
+Requires-Dist: typer>=0.27.0
 Description-Content-Type: text/markdown
 
 # playmaker
@@ -41,9 +41,9 @@ parses their native session files, and pings you when they land.
 ```console
 $ B=dashboard                      # one label for the whole fan-out
 
-$ playmaker dispatch codex  --batch $B --model gpt-5-codex -p "Add PATCH /users/:id …"
+$ playmaker dispatch codex  --batch $B -p "Add PATCH /users/:id …"
 session: 9f2c1a4e-…  pid: 48211  (detached)
-$ playmaker dispatch agy    --batch $B --model "Gemini 3.5 Flash (High)" -p "pytest coverage for …"
+$ playmaker dispatch agy    --batch $B --model gemini-3.6-flash-high -p "pytest coverage for …"
 session: 4b1f9c02-…  pid: 48219  (detached)
 $ playmaker dispatch claude --batch $B --model sonnet -p "Update the API docs for …"
 session: c07d5511-…  pid: 48244  (detached)
@@ -87,28 +87,54 @@ The catch: doing this by hand — terminal tabs, jumping between tools,
 copy-pasting context — is friction. `playmaker` removes the friction; the
 [coach skill](#the-coach-skill) provides the discipline.
 
-## ⚠️ Sub-agents skip permission prompts by default
+## Permissions
 
-By default, playmaker launches Claude and Antigravity sub-agents with
-`--dangerously-skip-permissions` (and Gemini with `--yolo`). This is
-deliberate: a headless agent has no human at the keyboard, so without these
-flags a detached run stalls at the first tool-approval prompt and finishes
-having written nothing.
+A detached agent has nobody at the keyboard to approve a tool prompt, so you
+decide up front what it may do. Left alone, a headless Claude simply answers
+*"I need your permission"* and finishes having changed nothing — so the choice
+is real, not a formality.
 
-It also means a dispatched agent can run commands and edit files **without
-asking**. Only dispatch prompts you'd be comfortable running unattended, in
-working directories you trust.
+By default playmaker asks for the weakest setting that still lets the work
+finish: **the agent is free inside the directory you dispatched it to, and
+Claude itself refuses anything outside it.**
 
-To opt out for Claude, set this in `~/.playmaker/config.toml`:
+| `[agents.claude] permission_mode` | inside `--cwd` | outside `--cwd` |
+|---|---|---|
+| `"plan"` | reads and plans, no writes | — |
+| `"acceptEdits"` *(default)* | edits files, runs commands | refused |
+| `"bypassPermissions"` | anything | anything |
+
+Narrow it further with an allowlist — Claude Code's own tool syntax:
 
 ```toml
 [agents.claude]
-skip_permissions = false
+permission_mode = "acceptEdits"
+allowed_tools = ["Read", "Edit", "Write", "Bash(pytest:*)"]
+disallowed_tools = ["WebFetch"]
 ```
 
-— with the caveat above: detached runs will then stall on the first permission
-prompt, so this only really makes sense alongside `--sync` workflows or
-allowlist rules you've configured in Claude Code itself.
+**Or skip the whole thing.** One line, no boundary, including the
+working-directory one:
+
+```toml
+[agents.claude]
+yolo = true
+```
+
+That is a reasonable trade for prompts and directories you'd run unattended
+anyway — just make it a decision rather than a default you inherited.
+
+The other agents differ, because their CLIs do:
+
+- **codex** needs none of this. `codex exec` is already non-interactive and
+  sandboxes the model's shell itself, so playmaker passes no bypass flag at
+  all. Override its policy with `sandbox = "read-only" | "workspace-write" |
+  "danger-full-access"`.
+- **agy** has no middle tier — no per-mode flag exists, so a detached run
+  either auto-approves or comes back having done nothing. It therefore
+  defaults to `yolo = true`; layer `sandbox = true` on top for agy's own
+  terminal restrictions.
+- **gemini** (legacy) runs with `--yolo`.
 
 ## Install
 
@@ -142,8 +168,8 @@ playmaker agents          # which agent CLIs are reachable
 | Agent | Install | Notes |
 |---|---|---|
 | **Claude Code** | `npm i -g @anthropic-ai/claude-code` | `--model sonnet` / `opus` / `haiku` |
-| **Codex CLI** | `npm i -g @openai/codex` | `--model gpt-5-codex` |
-| **Antigravity (`agy`)** | bundled with [Antigravity](https://antigravity.google) | models are display names: `--model "Claude Opus 4.6 (Thinking)"` — see `agy models` |
+| **Codex CLI** | `npm i -g @openai/codex` | the model roster depends on your plan; omit `--model` to use the account default |
+| **Antigravity (`agy`)** | bundled with [Antigravity](https://antigravity.google) | `--model claude-opus-4-6-thinking` — the roster moves, so read it from `agy models` |
 | **Gemini CLI** (legacy) | `npm i -g @google/gemini-cli` | still supported, superseded by `agy` |
 
 At least one is required; `playmaker agents` tells you which it can see.
@@ -203,13 +229,15 @@ still live — that's the cheap path for "almost right, fix Y". Start fresh with
 
 ```mermaid
 flowchart LR
-    C["🧑‍🏫 coach<br/>your Claude Code session"] -->|dispatch| P(("playmaker"))
-    P --> A1["claude -p<br/><i>--model sonnet</i>"]
+    C["coach<br/>your Claude Code session"] -->|dispatch| P(("playmaker"))
+    P --> A1["claude -p<br/>--model sonnet"]
     P --> A2["codex exec"]
     P --> A3["agy -p"]
-    A1 & A2 & A3 --> S[("state.db<br/>outputs/ · logs/")]
-    S -->|list · thread · summary| C
-    S -.->|batch drained| N["🔔 one ping"]
+    A1 --> S[("state.db<br/>outputs/ + logs/")]
+    A2 --> S
+    A3 --> S
+    S -->|"list / thread / summary"| C
+    S -.->|"batch drained"| N["one ping"]
 ```
 
 Each dispatch is a detached OS process with its own quota; playmaker owns the
@@ -324,6 +352,8 @@ input the coach skill uses to route each subtask.
 Handlers for other agent CLIs are especially welcome — see
 [CONTRIBUTING.md](CONTRIBUTING.md) for the `AgentHandler` contract and what you
 need to know about a CLI before writing one.
+[SECURITY.md](SECURITY.md) covers which credentials the quota probes read and
+what a dispatched agent is allowed to do.
 
 ```bash
 uv run pytest

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/README.md

@@ -14,9 +14,9 @@ parses their native session files, and pings you when they land.
 ```console
 $ B=dashboard                      # one label for the whole fan-out
 
-$ playmaker dispatch codex  --batch $B --model gpt-5-codex -p "Add PATCH /users/:id …"
+$ playmaker dispatch codex  --batch $B -p "Add PATCH /users/:id …"
 session: 9f2c1a4e-…  pid: 48211  (detached)
-$ playmaker dispatch agy    --batch $B --model "Gemini 3.5 Flash (High)" -p "pytest coverage for …"
+$ playmaker dispatch agy    --batch $B --model gemini-3.6-flash-high -p "pytest coverage for …"
 session: 4b1f9c02-…  pid: 48219  (detached)
 $ playmaker dispatch claude --batch $B --model sonnet -p "Update the API docs for …"
 session: c07d5511-…  pid: 48244  (detached)
@@ -60,28 +60,54 @@ The catch: doing this by hand — terminal tabs, jumping between tools,
 copy-pasting context — is friction. `playmaker` removes the friction; the
 [coach skill](#the-coach-skill) provides the discipline.
 
-## ⚠️ Sub-agents skip permission prompts by default
+## Permissions
 
-By default, playmaker launches Claude and Antigravity sub-agents with
-`--dangerously-skip-permissions` (and Gemini with `--yolo`). This is
-deliberate: a headless agent has no human at the keyboard, so without these
-flags a detached run stalls at the first tool-approval prompt and finishes
-having written nothing.
+A detached agent has nobody at the keyboard to approve a tool prompt, so you
+decide up front what it may do. Left alone, a headless Claude simply answers
+*"I need your permission"* and finishes having changed nothing — so the choice
+is real, not a formality.
 
-It also means a dispatched agent can run commands and edit files **without
-asking**. Only dispatch prompts you'd be comfortable running unattended, in
-working directories you trust.
+By default playmaker asks for the weakest setting that still lets the work
+finish: **the agent is free inside the directory you dispatched it to, and
+Claude itself refuses anything outside it.**
 
-To opt out for Claude, set this in `~/.playmaker/config.toml`:
+| `[agents.claude] permission_mode` | inside `--cwd` | outside `--cwd` |
+|---|---|---|
+| `"plan"` | reads and plans, no writes | — |
+| `"acceptEdits"` *(default)* | edits files, runs commands | refused |
+| `"bypassPermissions"` | anything | anything |
+
+Narrow it further with an allowlist — Claude Code's own tool syntax:
 
 ```toml
 [agents.claude]
-skip_permissions = false
+permission_mode = "acceptEdits"
+allowed_tools = ["Read", "Edit", "Write", "Bash(pytest:*)"]
+disallowed_tools = ["WebFetch"]
 ```
 
-— with the caveat above: detached runs will then stall on the first permission
-prompt, so this only really makes sense alongside `--sync` workflows or
-allowlist rules you've configured in Claude Code itself.
+**Or skip the whole thing.** One line, no boundary, including the
+working-directory one:
+
+```toml
+[agents.claude]
+yolo = true
+```
+
+That is a reasonable trade for prompts and directories you'd run unattended
+anyway — just make it a decision rather than a default you inherited.
+
+The other agents differ, because their CLIs do:
+
+- **codex** needs none of this. `codex exec` is already non-interactive and
+  sandboxes the model's shell itself, so playmaker passes no bypass flag at
+  all. Override its policy with `sandbox = "read-only" | "workspace-write" |
+  "danger-full-access"`.
+- **agy** has no middle tier — no per-mode flag exists, so a detached run
+  either auto-approves or comes back having done nothing. It therefore
+  defaults to `yolo = true`; layer `sandbox = true` on top for agy's own
+  terminal restrictions.
+- **gemini** (legacy) runs with `--yolo`.
 
 ## Install
 
@@ -115,8 +141,8 @@ playmaker agents          # which agent CLIs are reachable
 | Agent | Install | Notes |
 |---|---|---|
 | **Claude Code** | `npm i -g @anthropic-ai/claude-code` | `--model sonnet` / `opus` / `haiku` |
-| **Codex CLI** | `npm i -g @openai/codex` | `--model gpt-5-codex` |
-| **Antigravity (`agy`)** | bundled with [Antigravity](https://antigravity.google) | models are display names: `--model "Claude Opus 4.6 (Thinking)"` — see `agy models` |
+| **Codex CLI** | `npm i -g @openai/codex` | the model roster depends on your plan; omit `--model` to use the account default |
+| **Antigravity (`agy`)** | bundled with [Antigravity](https://antigravity.google) | `--model claude-opus-4-6-thinking` — the roster moves, so read it from `agy models` |
 | **Gemini CLI** (legacy) | `npm i -g @google/gemini-cli` | still supported, superseded by `agy` |
 
 At least one is required; `playmaker agents` tells you which it can see.
@@ -176,13 +202,15 @@ still live — that's the cheap path for "almost right, fix Y". Start fresh with
 
 ```mermaid
 flowchart LR
-    C["🧑‍🏫 coach<br/>your Claude Code session"] -->|dispatch| P(("playmaker"))
-    P --> A1["claude -p<br/><i>--model sonnet</i>"]
+    C["coach<br/>your Claude Code session"] -->|dispatch| P(("playmaker"))
+    P --> A1["claude -p<br/>--model sonnet"]
     P --> A2["codex exec"]
     P --> A3["agy -p"]
-    A1 & A2 & A3 --> S[("state.db<br/>outputs/ · logs/")]
-    S -->|list · thread · summary| C
-    S -.->|batch drained| N["🔔 one ping"]
+    A1 --> S[("state.db<br/>outputs/ + logs/")]
+    A2 --> S
+    A3 --> S
+    S -->|"list / thread / summary"| C
+    S -.->|"batch drained"| N["one ping"]
 ```
 
 Each dispatch is a detached OS process with its own quota; playmaker owns the
@@ -297,6 +325,8 @@ input the coach skill uses to route each subtask.
 Handlers for other agent CLIs are especially welcome — see
 [CONTRIBUTING.md](CONTRIBUTING.md) for the `AgentHandler` contract and what you
 need to know about a CLI before writing one.
+[SECURITY.md](SECURITY.md) covers which credentials the quota probes read and
+what a dispatched agent is allowed to do.
 
 ```bash
 uv run pytest

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "playmaker-cli"
-version = "0.4.0"
+version = "0.5.1"
 description = "Playing-coach CLI for orchestrating Claude Code, Codex and Antigravity sub-agents in parallel."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -35,7 +35,7 @@ classifiers = [
     "Topic :: Utilities",
 ]
 dependencies = [
-    "typer>=0.12",
+    "typer>=0.27.0",
     "rich>=13.7",
 ]
 
@@ -50,7 +50,7 @@ playmaker = "playmaker.cli:app"
 [dependency-groups]
 dev = [
     "ruff>=0.4",
-    "pytest>=8",
+    "pytest>=9.1.1",
 ]
 
 [build-system]

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/skills/playmaker-coach/SKILL.md

@@ -7,7 +7,9 @@ description: Playing-coach orchestration of Claude/Codex/Antigravity (agy) sub-a
 
 Use the `playmaker` CLI as a facade to dispatch sub-tasks to Codex / Antigravity (`agy`) / a sibling Claude, monitor them, read their threads, review their diffs, and feed back. The coach (this thread) does its own portion of the work in parallel.
 
-> **`agy` (Antigravity CLI)** does not only serve Google models: `agy models` exposes **Gemini 3.5 Flash (Low/Medium/High)**, **Gemini 3.1 Pro (Low/High)**, **Claude Sonnet 4.6 (Thinking)**, **Claude Opus 4.6 (Thinking)**, and **GPT-OSS 120B (Medium)**. Opus via agy runs on *Google's* quota pool — top-tier Claude work that does not touch the Anthropic subscription's scarce Opus weekly bucket. Model names are the exact display strings (quote them in bash): `--model "Claude Opus 4.6 (Thinking)"`.
+> **`agy` (Antigravity CLI)** does not only serve Google models: alongside the Gemini Flash and Pro tiers, `agy models` carries **Claude Sonnet and Opus** and a **GPT-OSS** mid-tier. Opus via agy runs on *Google's* quota pool — top-tier Claude work that does not touch the Anthropic subscription's scarce Opus weekly bucket: `--model claude-opus-4-6-thinking`.
+>
+> **Never write an agy model name from memory — run `agy models` and copy a line.** Both the roster *and its spelling* move with Antigravity releases: names used to be quoted display strings like `"Claude Opus 4.6 (Thinking)"` and are now bare slugs. playmaker validates `--model` against the live roster and fails the dispatch on a stale name, so a wrong guess costs you a round-trip.
 
 **The point of the coach pattern:** all available models do useful work in parallel under your direction. The coach's job is *orchestration*, not *production*. A coach that does its own implementation, runs its own codebase recon, and reviews everything line by line burns the same budget delegation was meant to save. Treat your own context window as the most expensive resource on the table — every byte you read or generate yourself is a byte that could have come from a cheaper model. Push out as much as you can: implementation, recon, summarization, even drafting the per-subtask prompts when the task is large enough.
 
@@ -20,7 +22,7 @@ All Claude work — coach, internal sub-agents, external `claude -p` — draws f
 2. **Internal sub-agents — the `Task`/`Agent` tool in THIS session.** Run inside this session, **write files** (they inherit the coach's permission mode), return their result straight into the coach's context, and run in parallel. They draw on the same subscription, so the gate is "is weekly quota healthy?" — glance at `playmaker quotas`. **Use them freely** for Claude-side chunks the coach will fold back in directly; spawn several at once, don't be shy.
 
 3. **External dispatch — `playmaker dispatch <agent>`.** Separate OS processes, tracked in playmaker (`list`/`watch`/`thread`/`continue`):
-   - **`claude -p` (sibling Claude):** same subscription. Its key lever is the model bucket — **Sonnet is a separate weekly bucket from Opus**, usually idle while Opus depletes, so default **`--model sonnet`** to spare the scarce Opus bucket (**`--model haiku`** for trivial mechanical work). It **can write files** (playmaker forwards `--dangerously-skip-permissions`; see §10). Use it over an internal sub-agent when you want a **tracked, detached work-stream** you can monitor/continue independently of the coach's turn.
+   - **`claude -p` (sibling Claude):** same subscription. Its key lever is the model bucket — **Sonnet is a separate weekly bucket from Opus**, usually idle while Opus depletes, so default **`--model sonnet`** to spare the scarce Opus bucket (**`--model haiku`** for trivial mechanical work). It **can write files** — playmaker runs it in `acceptEdits`, so it edits and runs commands freely inside `--cwd` and is refused outside it (see §10). Use it over an internal sub-agent when you want a **tracked, detached work-stream** you can monitor/continue independently of the coach's turn.
    - **`codex` / `agy`:** each on its own subscription/quota — the right home for **write-heavy** parallel implementation that can leave the Anthropic subscription. `agy` is special: besides Gemini tiers it carries **Claude Sonnet/Opus 4.6 (Thinking)** on Google's pool, so even "must be Claude-quality" work can leave the Anthropic quota.
 
 **Routing cheat-sheet for Claude-side work:**
@@ -31,7 +33,7 @@ All Claude work — coach, internal sub-agents, external `claude -p` — draws f
 | is an independent stream you'll monitor / continue separately | **external `dispatch claude --model sonnet`** | tracked & detached; Sonnet's own weekly bucket spares Opus |
 | is heavy reasoning only the coach can do | **coach** | top-tier Opus, serial |
 | is write-heavy and can leave Claude | **codex / agy** | their own quotas |
-| needs top-tier Claude but the Anthropic Opus weekly is precious | **`dispatch agy --model "Claude Opus 4.6 (Thinking)"`** | Opus quality on Google's pool |
+| needs top-tier Claude but the Anthropic Opus weekly is precious | **`dispatch agy --model claude-opus-4-6-thinking`** | Opus quality on Google's pool |
 
 **Sonnet is your cheap parallel Claude worker** — a separate weekly bucket that usually sits idle while Opus depletes. Reach for it (via `dispatch claude --model sonnet`, or by pointing an internal sub-agent at Sonnet) instead of burning Opus on mid-tier work.
 
@@ -69,7 +71,7 @@ Codebase exploration ("find where the User entity lives, list its existing field
 Pattern: dispatch a recon subtask with an explicit deliverable.
 
 ```bash
-playmaker dispatch agy --model "Gemini 3.5 Flash (Low)" --cwd $(pwd) --sync \
+playmaker dispatch agy --model gemini-3.6-flash-low --cwd $(pwd) --sync \
   --prompt "Recon only — do not edit any files. In apps/backend/, locate: (a) the User entity/schema and the migration tooling used (Prisma vs TypeORM vs other), (b) the auth middleware that resolves the current user, (c) where DTOs are defined for user PATCH endpoints if any. Report under 200 words as a numbered list with file paths and line ranges."
 ```
 
@@ -89,9 +91,9 @@ Break the task into 2-5 subtasks (don't go finer-grained than that on first run
 
 1. Sort *models* (not agents) by remaining capacity — freshest at the top. A provider with one fresh model and one depleted model is two separate buckets.
 2. **Tier-match each subtask to the cheapest model that can finish it cleanly:**
-   - **Architectural / spec judgment / cross-module integration:** top tier (Opus, agy "Claude Opus 4.6 (Thinking)" / "Gemini 3.1 Pro (High)", Codex top-tier). The coach lives here; agy-Opus is the overflow lane when the Anthropic Opus weekly is precious.
-   - **Pattern-following implementation, well-scoped CRUD, mechanical refactor, test scaffolding, writing inside an existing convention:** mid tier (Claude Sonnet, agy "Claude Sonnet 4.6 (Thinking)" / "Gemini 3.5 Flash (High)" / "Gemini 3.1 Pro (Low)", mid-tier Codex). This is where the bulk of delegated implementation goes.
-   - **Recon, summarization, mechanical loops over many files, name normalization:** cheap tier (agy "Gemini 3.5 Flash (Low)"/"(Medium)", **Claude Haiku**, Sonnet for recon-with-judgment).
+   - **Architectural / spec judgment / cross-module integration:** top tier (Opus, agy `claude-opus-4-6-thinking` / `gemini-3.1-pro-high`, Codex top-tier). The coach lives here; agy-Opus is the overflow lane when the Anthropic Opus weekly is precious.
+   - **Pattern-following implementation, well-scoped CRUD, mechanical refactor, test scaffolding, writing inside an existing convention:** mid tier (Claude Sonnet, agy `claude-sonnet-4-6` / `gemini-3.5-flash-high` / `gemini-3.1-pro-low`, mid-tier Codex). This is where the bulk of delegated implementation goes.
+   - **Recon, summarization, mechanical loops over many files, name normalization:** cheap tier (agy's lowest Flash tiers, **Claude Haiku**, Sonnet for recon-with-judgment).
 
    For Claude specifically, tier is orthogonal to **lane** (see "Execution lanes"): pick the model tier here, then decide *internal sub-agent* (coach integrates the result) vs *external `-p`* (tracked detached stream).
 3. Pass the model explicitly: `playmaker dispatch <agent> --model <name> ...`. Without `--model`, the agent CLI uses its default — which is usually fine but means the coach gives up control over tier-matching. **For sibling Claude, default to `--model sonnet`** (Haiku for trivial mechanical work); never omit it and let the CLI pick Opus — that burns the scarce shared Opus weekly bucket.
@@ -112,7 +114,7 @@ To make a subtask finishable, every dispatch must carry:
 2. **Acceptance criteria as a check the agent runs itself.** A green command — `npx prisma validate`, `pnpm test users.spec.ts`, `tsc --noEmit`, an `eslint` pass on a specific file. The agent is told to keep iterating until that command exits 0 and to surface its output in the final answer. This replaces coach-side review for ~80% of the work.
 3. **Done definition in one sentence**, written so the coach can confirm it in seconds without reading the diff line by line. "Column added, migration generated, prisma validate green." If the coach can't write such a sentence, the subtask isn't sized right yet — split or specify further before dispatching.
 4. **Context the agent needs but doesn't have.** Spec section excerpts, naming conventions, the one related file it should mirror. Paste these into the prompt; don't make the agent find them by reading half the repo. If your team keeps durable notes (a docs folder, a wiki, a notes vault), pass the *exact* paths worth reading rather than asking the agent to go looking.
-5. **Match to capability.** Codex / agy-Gemini do well on pattern-following, well-scoped CRUD, test scaffolding, mechanical refactors, and writing within an existing convention. They do poorly on architectural decisions across files they haven't been pointed at, novel API design, and judging whether a spec rule applies. Keep those for the coach — or for agy's "Claude Opus 4.6 (Thinking)" when the subtask genuinely needs top-tier judgment but should not burn the Anthropic Opus weekly. If a profile in `.playmaker/agents/<name>.md` exists, trust its guidance over these defaults.
+5. **Match to capability.** Codex / agy-Gemini do well on pattern-following, well-scoped CRUD, test scaffolding, mechanical refactors, and writing within an existing convention. They do poorly on architectural decisions across files they haven't been pointed at, novel API design, and judging whether a spec rule applies. Keep those for the coach — or for agy's `claude-opus-4-6-thinking` when the subtask genuinely needs top-tier judgment but should not burn the Anthropic Opus weekly. If a profile in `.playmaker/agents/<name>.md` exists, trust its guidance over these defaults.
 
 A useful smell test before dispatching: *"If this came back done, would I review by running one command and reading one paragraph — or would I need to read the whole diff and think hard about whether it's right?"* If the latter, re-scope before sending.
 
@@ -121,7 +123,7 @@ Output the plan as a short proposal:
 Plan:
 - Coach (me): schema design + integration glue
 - Codex: FastAPI handlers in apps/api/
-- agy (Gemini 3.5 Flash High): pytest tests + README
+- agy (gemini-3.6-flash-high): pytest tests + README
 
 Quotas: Claude session 93% / weekly 80%, Codex 100%,
         agy Gemini 5h 100% / weekly 96%, Claude/GPT 5h 88% / weekly 71%.
@@ -151,7 +153,11 @@ playmaker dispatch <agent> --model <name> --prompt "<scoped prompt>" --cwd $(pwd
 
 Always pass `--cwd $(pwd)` — `playmaker`'s default is the *coach process's* current dir, which is not always what you want.
 
-Always pass `--model` when you've made a tier-matching decision in step 3. Without it, the agent CLI uses its own default (which may be its top-tier model, defeating the load-distribution effort). Model name is what the agent's native CLI accepts: `claude --model sonnet`, `codex exec -m gpt-5-codex`, `agy --model "Gemini 3.5 Flash (High)"` — agy takes the exact display names from `agy models` and they contain spaces, so **always quote them**. Note: agy's own default is a top-tier model, another reason never to omit `--model` on agy dispatches meant to be cheap.
+Always pass `--model` when you've made a tier-matching decision in step 3. Without it, the agent CLI uses its own default (which may be its top-tier model, defeating the load-distribution effort). Model name is what the agent's native CLI accepts: `claude --model sonnet`, `agy --model gemini-3.6-flash-high` — for agy, copy the line from `agy models` rather than typing it.
+
+Two exceptions to "always pass `--model`":
+- **codex** — its model roster depends on the account plan, and an unavailable name fails the whole dispatch (`codex turn failed: … not supported when using Codex with a ChatGPT account`). Omitting `--model` uses whatever that account actually has, which is usually what you want.
+- **agy** — its own default is a top-tier model, so omitting `--model` on a dispatch meant to be cheap silently spends the expensive bucket. Always pass it here.
 
 **agy prompt discipline:** the agy agent's shell lives in a private scratch directory, not the workspace. playmaker automatically prepends a workspace preamble to every agy dispatch, but reinforce it: word file instructions with paths relative to the workspace root or absolute paths, never "in the current directory".
 
@@ -163,8 +169,8 @@ Always pass `--model` when you've made a tier-matching decision in step 3. Witho
 
 ```bash
 B=admin-dashboard   # any short label shared across this fan-out
-playmaker dispatch codex --batch "$B" --model gpt-5-codex --prompt "..." --cwd $(pwd)
-playmaker dispatch agy   --batch "$B" --model "Gemini 3.5 Flash (High)" --prompt "..." --cwd $(pwd)
+playmaker dispatch codex --batch "$B" --prompt "..." --cwd $(pwd)
+playmaker dispatch agy   --batch "$B" --model gemini-3.6-flash-high --prompt "..." --cwd $(pwd)
 ```
 
 `playmaker continue <id> --model <name>` overrides the model for one follow-up turn while keeping the live session; without `--model` it inherits the parent session's model.
@@ -173,7 +179,7 @@ For sequential delegation (e.g. "I'll do schema first, then Codex builds on top"
 
 ```bash
 git commit -am "checkpoint: schema before backend dispatch"
-playmaker dispatch codex --model gpt-5-codex --prompt "..." --cwd $(pwd) --sync   # blocks, prints output
+playmaker dispatch codex --prompt "..." --cwd $(pwd) --sync   # blocks, prints output
 ```
 
 ### 6. Coach's own work
@@ -219,14 +225,14 @@ Read `summary` first. If you need more context to judge: `playmaker thread <id>`
 
 If `playmaker dispatch` returns an error (binary missing, auth bad, agent unavailable), don't silently retry. Surface it, propose a re-routed plan ("Codex unavailable; want me to give the backend to Claude instead?"), and wait for user confirmation.
 
-**Sibling-Claude writes are enabled** — playmaker forwards `--dangerously-skip-permissions`, so external `claude -p` dispatch/resume runs headless with permissions skipped and *can* edit files in a detached session. (This is configurable; a user who set `skip_permissions = false` will see detached runs stall on the first tool prompt.)
+**Sibling-Claude writes are enabled, but bounded.** playmaker dispatches `claude -p` with `--permission-mode acceptEdits` by default: it edits files and runs commands inside the dispatch `--cwd` without asking, and claude itself refuses anything outside that directory. So **keep every path in the prompt inside `--cwd`** — a subtask that legitimately needs to touch a sibling repo or a dotfile in `$HOME` will come back refused, and the fix is a different `--cwd` (or the user's `yolo = true`), not a re-prompt.
 
 Both Claude lanes are on the subscription, so pick by **where the work lives**, not cost:
 - **Coach folds the result in directly → internal sub-agent (Task tool).** In-session, write-capable, returns into context. Default choice for "more Claude."
 - **Independent stream you'll monitor / continue separately → `playmaker dispatch claude --model sonnet`.** Tracked, detached; Sonnet's separate weekly bucket spares Opus.
 - **Work that can leave the Claude family → Codex / agy** (their own quotas).
 
-If a dispatch comes back with zero file changes, check `playmaker summary <id>`: a leftover "click Allow" pivot means the local `claude` is older than the skip-permissions wiring or overrides it — fall back to an internal sub-agent or Codex/agy for that subtask. For **agy** specifically, a "done" with no file changes usually means the files landed in agy's private scratch dir (`~/.gemini/antigravity-cli/scratch/`) — the prompt referred to "the current directory" instead of workspace paths; re-dispatch with explicit paths.
+If a dispatch comes back with zero file changes, check `playmaker summary <id>`. Two common causes for Claude: the subtask tried to write outside `--cwd` and was refused (re-dispatch with the right `--cwd`), or the run needed a permission the configured mode doesn't grant — a "I need your permission" answer, not a crash. For **agy** specifically, a "done" with no file changes usually means the files landed in agy's private scratch dir (`~/.gemini/antigravity-cli/scratch/`) — the prompt referred to "the current directory" instead of workspace paths; re-dispatch with explicit paths.
 
 ## Reading discipline
 
@@ -263,9 +269,9 @@ playmaker watch                                 # Rich live TUI of sessions
 
 Every command takes `--json` for machine-readable output.
 
-`--model NAME` is forwarded to the agent's native CLI: `claude --model sonnet`, `codex exec -m gpt-5-codex`, `agy --model "Claude Opus 4.6 (Thinking)"` (display names from `agy models`, always quoted). Without it the agent CLI uses its own default. Model is stored on the session row, so detached re-runs and `continue` inherit it; `continue --model X` overrides for that one turn.
+`--model NAME` is forwarded to the agent's native CLI: `claude --model sonnet`, `agy --model claude-opus-4-6-thinking`, `codex -m <whatever that account has>`. Without it the agent CLI uses its own default. Model is stored on the session row, so detached re-runs and `continue` inherit it; `continue --model X` overrides for that one turn.
 
-agy model roster (from `agy models`): `Gemini 3.5 Flash (Low)` / `(Medium)` / `(High)`, `Gemini 3.1 Pro (Low)` / `(High)`, `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, `GPT-OSS 120B (Medium)`. Re-check the roster with `agy models` when in doubt — it changes with Antigravity releases.
+**The agy roster is not documented here on purpose** — it changes with Antigravity releases, and so does the spelling convention. Run `agy models` and copy a line. At the time of writing it returns bare slugs in the shape `gemini-3.6-flash-{low,medium,high}`, `gemini-3.1-pro-{low,high}`, `claude-sonnet-4-6`, `claude-opus-4-6-thinking`, `gpt-oss-120b-medium` — but treat that as an example of the *shape*, not a list to copy from.
 
 ## Anti-patterns
 

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/src/playmaker/agents/agy.py

@@ -1,12 +1,15 @@
 """Antigravity CLI (`agy`) handler.
 
 Empirically (agy 1.1.1):
-- oneshot: `agy -p "<prompt>" [--model "<display name>"] [--dangerously-skip-permissions]
+- oneshot: `agy -p "<prompt>" [--model <name>] [--dangerously-skip-permissions]
   [--print-timeout 60m] [--log-file <path>]`; stdout is the final response as
   plain text (no JSON envelope).
 - resume: `agy --conversation <uuid> -p "..."` — keeps the same conversation id.
-- models are addressed by *display name* from `agy models`, e.g.
-  "Claude Opus 4.6 (Thinking)", "Gemini 3.5 Flash (Low)".
+- `--model` takes a name from `agy models` verbatim, e.g.
+  "claude-opus-4-6-thinking", "gemini-3.6-flash-high". Both the roster and its
+  *spelling* move with Antigravity releases — earlier builds took display names
+  like "Claude Opus 4.6 (Thinking)" — which is why _validate_model() reads the
+  live list instead of trusting a hardcoded one.
 - the conversation id is NOT printed to stdout; it is recovered from the CLI
   debug log (`--log-file`) via the `Created conversation <uuid>` line, which
   appears a few seconds in — that is our early on_session_started signal.
@@ -34,7 +37,7 @@ import time
 from pathlib import Path
 
 from playmaker.agents.base import DispatchResult, SessionStartedCallback, Turn
-from playmaker.config import agent_setting
+from playmaker.config import agent_setting, yolo_enabled
 
 AGY_BRAIN_ROOT = Path("~/.gemini/antigravity-cli/brain").expanduser()
 
@@ -53,7 +56,7 @@ class AgyHandler:
     @staticmethod
     @functools.lru_cache(maxsize=1)
     def available_models() -> tuple[str, ...]:
-        """Exact model display names agy accepts, from `agy models`.
+        """Exact model names agy accepts, from `agy models`.
 
         agy resolves an unknown `--model` to its default *silently* (no error,
         wrong model runs), so we validate against this list before dispatch.
@@ -146,10 +149,13 @@ class AgyHandler:
         cmd = ["agy", "-p", full_prompt, "--log-file", str(log_path)]
         if conversation_id:
             cmd += ["--conversation", conversation_id]
-        # Detached runs have no human to approve tool prompts (same rationale
-        # as the claude handler). Opt out via [agents.agy] skip_permissions.
-        if agent_setting("agy", "skip_permissions", True):
+        # agy has no middle tier: unlike claude there is no per-mode permission
+        # flag, so a detached run either skips the prompts or answers nothing.
+        # `--sandbox` is orthogonal and can be layered on top.
+        if yolo_enabled("agy", default=True):
             cmd.append("--dangerously-skip-permissions")
+        if agent_setting("agy", "sandbox", False):
+            cmd.append("--sandbox")
         # agy's built-in print timeout is 5m — too short for real subtasks.
         cmd += ["--print-timeout", str(agent_setting("agy", "print_timeout", "60m"))]
         if model:

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/src/playmaker/agents/claude.py

@@ -17,7 +17,36 @@ import subprocess
 from pathlib import Path
 
 from playmaker.agents.base import DispatchResult, SessionStartedCallback, Turn
-from playmaker.config import agent_setting
+from playmaker.config import agent_list_setting, agent_setting, yolo_enabled
+
+# What a sub-agent is allowed to do without a human at the keyboard.
+# Verified against claude 2.x in `-p` mode:
+#   default       -> the agent writes nothing and answers "I need permission";
+#                    it does NOT hang, it just returns having done nothing.
+#   acceptEdits   -> edits and commands proceed inside the working directory,
+#                    and anything outside it is refused by claude itself.
+#   bypassPermissions / --dangerously-skip-permissions -> no boundary at all.
+# acceptEdits is the default here because it is the weakest mode that still
+# lets a detached run finish its work.
+DEFAULT_PERMISSION_MODE = "acceptEdits"
+
+
+def permission_args() -> list[str]:
+    """Permission flags for a headless run, from [agents.claude] in config.toml."""
+    if yolo_enabled("claude"):
+        return ["--dangerously-skip-permissions"]
+
+    mode = agent_setting("claude", "permission_mode", DEFAULT_PERMISSION_MODE)
+    args = ["--permission-mode", str(mode)]
+    # Comma-separated rather than variadic: `--allowedTools A B` would swallow
+    # the positional prompt that follows.
+    allowed = agent_list_setting("claude", "allowed_tools")
+    if allowed:
+        args += ["--allowedTools", ",".join(allowed)]
+    disallowed = agent_list_setting("claude", "disallowed_tools")
+    if disallowed:
+        args += ["--disallowedTools", ",".join(disallowed)]
+    return args
 
 
 class ClaudeHandler:
@@ -53,13 +82,7 @@ class ClaudeHandler:
             "stream-json",
             "--verbose",
         ]
-        # Detached runs have no human to approve tool prompts; without this
-        # the agent stalls on the first file write and ends its turn with
-        # zero changes. Skipping permissions is what makes sibling-Claude
-        # usable for write-heavy subtasks in headless mode. Opt out via
-        # [agents.claude] skip_permissions = false in ~/.playmaker/config.toml.
-        if agent_setting("claude", "skip_permissions", True):
-            cmd.append("--dangerously-skip-permissions")
+        cmd += permission_args()
         if model:
             cmd += ["--model", model]
         cmd.append(full_prompt)
@@ -169,9 +192,8 @@ class ClaudeHandler:
             "--output-format",
             "json",
         ]
-        # See dispatch(): detached resume has no human to approve prompts.
-        if agent_setting("claude", "skip_permissions", True):
-            cmd.append("--dangerously-skip-permissions")
+        # See dispatch(): detached resume has no human to approve prompts either.
+        cmd += permission_args()
         if model:
             cmd += ["--model", model]
         cmd.append(full_prompt)

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/src/playmaker/agents/codex.py

@@ -23,10 +23,23 @@ import time
 from pathlib import Path
 
 from playmaker.agents.base import DispatchResult, SessionStartedCallback, Turn
+from playmaker.config import agent_setting
 
 CODEX_SESSIONS_ROOT = Path("~/.codex/sessions").expanduser()
 
 
+def sandbox_args() -> list[str]:
+    """Codex's own sandbox policy, from [agents.codex] sandbox in config.toml.
+
+    Unlike claude and agy, codex needs no permission-skipping flag: `codex exec`
+    is already non-interactive and confines the model's shell commands with its
+    own sandbox. We pass `-s` only when a specific policy was configured;
+    otherwise codex's own default applies.
+    """
+    policy = agent_setting("codex", "sandbox")
+    return ["-s", str(policy)] if policy else []
+
+
 class CodexHandler:
     name = "codex"
 
@@ -58,6 +71,7 @@ class CodexHandler:
             "-o",
             str(last_msg_path),
         ]
+        cmd += sandbox_args()
         if model:
             cmd += ["-m", model]
         cmd.append(full_prompt)

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/src/playmaker/cli.py

@@ -131,8 +131,8 @@ def dispatch(
         "--model",
         "-m",
         help="forwarded to the agent CLI's --model (e.g. claude 'opus'/'sonnet', "
-        "codex 'gpt-5-codex', agy 'Claude Opus 4.6 (Thinking)' / 'Gemini 3.5 Flash "
-        "(High)' — display names from `agy models`); omitted = agent default",
+        "agy 'claude-opus-4-6-thinking' — exact names from `agy models`); "
+        "omitted = agent default, which is the safe choice for codex",
     ),
     sync: bool = typer.Option(
         False,
@@ -949,22 +949,44 @@ sound = true
 # (terminal-notifier only). Any app name `open -a` accepts.
 editor = "Zed"
 
+# How much each sub-agent may do while nobody is watching. A detached agent
+# cannot answer a permission prompt, so every agent needs *some* answer here.
+
 [agents.claude]
 binary = "claude"
-# Headless dispatch passes --dangerously-skip-permissions so unattended runs
-# are not blocked by tool-permission prompts. Set to false to keep Claude
-# Code's normal permission checks (detached runs will then stall on the first
-# tool prompt and finish without writing anything).
-skip_permissions = true
+# "acceptEdits" (default): the agent edits files and runs commands freely
+#   inside the dispatch --cwd, and claude itself refuses anything outside it.
+# "plan": read and plan only, no writes.
+# "bypassPermissions": no boundary at all — same as yolo below.
+permission_mode = "acceptEdits"
+# Optional allowlist/denylist, narrower than the mode. Tool syntax is Claude
+# Code's own, e.g. "Bash(pytest:*)" to permit one command family.
+# allowed_tools = ["Read", "Edit", "Write", "Bash(pytest:*)"]
+# disallowed_tools = ["WebFetch"]
+#
+# Escape hatch: skip every check, including the working-directory boundary.
+# Only for prompts and directories you would run unattended.
+# yolo = true
 
 [agents.codex]
 binary = "codex"
+# codex exec is already non-interactive and sandboxes the model's shell itself,
+# so it needs no permission flag. Set a policy to override its default:
+# "read-only" | "workspace-write" | "danger-full-access"
+# sandbox = "workspace-write"
 
 [agents.agy]
 binary = "agy"
-# Antigravity CLI. Model names are display strings from `agy models`,
-# e.g. "Claude Opus 4.6 (Thinking)", "Gemini 3.5 Flash (High)".
-skip_permissions = true
+# Antigravity CLI. Model names come from `agy models` verbatim, e.g.
+# "claude-opus-4-6-thinking", "gemini-3.6-flash-high". The roster changes
+# with Antigravity releases, so read it rather than copying from docs.
+#
+# agy has no per-mode permission flag — a detached run either auto-approves or
+# comes back having done nothing — so this defaults to on.
+yolo = true
+# Layer agy's own terminal restrictions on top.
+# sandbox = true
+#
 # Forwarded to agy --print-timeout; the CLI's own default (5m) is too short
 # for real subtasks.
 print_timeout = "60m"

{playmaker_cli-0.4.0 → playmaker_cli-0.5.1}/src/playmaker/config.py

@@ -28,3 +28,25 @@ def setting(section: str, key: str, default: Any = None) -> Any:
     """Look up [<section>] <key>, falling back to `default`."""
     value = load_config().get(section, {})
     return value.get(key, default) if isinstance(value, dict) else default
+
+
+def yolo_enabled(agent: str, *, default: bool = False) -> bool:
+    """Whether this agent is configured to skip its permission checks entirely.
+
+    `yolo` is the current spelling; `skip_permissions` is the 0.4 name and is
+    still honoured so existing configs keep working.
+    """
+    value = agent_setting(agent, "yolo")
+    if value is None:
+        value = agent_setting(agent, "skip_permissions")
+    return default if value is None else bool(value)
+
+
+def agent_list_setting(agent: str, key: str) -> list[str]:
+    """A list-valued agent setting, tolerating a plain string in the TOML."""
+    value = agent_setting(agent, key)
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [v.strip() for v in value.split(",") if v.strip()]
+    return [str(v) for v in value]

playmaker_cli-0.5.1/tests/test_claude.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import playmaker.config as config
+from playmaker.agents.claude import ClaudeHandler
+
+
+class _FakeStream:
+    def __init__(self, lines: list[str]) -> None:
+        self._lines = lines
+
+    def __iter__(self):
+        return iter(self._lines)
+
+    def read(self) -> str:
+        return "".join(self._lines)
+
+
+class _FakePopen:
+    """Stand-in for subprocess.Popen over claude's stream-json output."""
+
+    def __init__(self, lines: list[str], returncode: int = 0, stderr: str = "") -> None:
+        self._lines = lines
+        self.returncode = returncode
+        self._stderr = stderr
+        self.cmd: list[str] = []
+        self.stdout = None
+        self.stderr = None
+
+    def __call__(self, cmd, **kwargs):
+        self.cmd = cmd
+        self.stdout = _FakeStream(self._lines)
+        self.stderr = _FakeStream([self._stderr])
+        return self
+
+    def wait(self) -> int:
+        return self.returncode
+
+
+def _events(*objs: dict) -> list[str]:
+    return [json.dumps(o) + "\n" for o in objs]
+
+
+INIT = {"type": "system", "subtype": "init", "session_id": "sess-123"}
+
+
+def test_dispatch_returns_the_result_event_text(monkeypatch, tmp_path) -> None:
+    fake = _FakePopen(
+        _events(
+            INIT,
+            {"type": "assistant", "message": {"content": [{"type": "text", "text": "hi"}]}},
+            {"type": "result", "subtype": "success", "result": "DONE", "total_cost_usd": 0.12},
+        )
+    )
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+
+    result = ClaudeHandler().dispatch(prompt="do it", cwd=tmp_path)
+
+    assert result.agent_session_id == "sess-123"
+    assert result.initial_output == "DONE"
+    assert result.cost_usd == 0.12
+
+
+def test_dispatch_fires_the_session_callback_before_the_run_ends(monkeypatch, tmp_path) -> None:
+    # The early callback is what lets `playmaker get` find a detached session
+    # within a second instead of after the agent finishes.
+    fake = _FakePopen(_events(INIT, {"type": "result", "subtype": "success", "result": "ok"}))
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+    seen: list[str] = []
+
+    ClaudeHandler().dispatch(prompt="p", cwd=tmp_path, on_session_started=seen.append)
+
+    assert seen == ["sess-123"]
+
+
+def test_dispatch_surfaces_the_error_from_the_result_event(monkeypatch, tmp_path) -> None:
+    # claude -p reports overload/rate-limit/refusal in the final result event
+    # with an EMPTY stderr, so without this the failure was a blank message.
+    fake = _FakePopen(
+        _events(
+            INIT,
+            {"type": "result", "subtype": "error_during_execution", "is_error": True,
+             "result": "Claude AI usage limit reached"},
+        ),
+        returncode=1,
+    )
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+
+    with pytest.raises(RuntimeError, match="usage limit reached"):
+        ClaudeHandler().dispatch(prompt="p", cwd=tmp_path)
+
+
+def test_dispatch_falls_back_to_raw_stdout_rather_than_failing_blank(
+    monkeypatch, tmp_path
+) -> None:
+    # No stderr, no result event: the raw first lines are the only diagnostic
+    # left, and they beat the blank "claude failed (exit 1):" this replaced.
+    fake = _FakePopen(_events(INIT), returncode=1)
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+
+    with pytest.raises(RuntimeError, match="sess-123"):
+        ClaudeHandler().dispatch(prompt="p", cwd=tmp_path)
+
+
+def test_dispatch_prefers_stderr_over_the_stream_events(monkeypatch, tmp_path) -> None:
+    fake = _FakePopen(_events(INIT), returncode=1, stderr="command not found: claude")
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+
+    with pytest.raises(RuntimeError, match="command not found"):
+        ClaudeHandler().dispatch(prompt="p", cwd=tmp_path)
+
+
+def test_dispatch_without_a_session_id_is_an_error(monkeypatch, tmp_path) -> None:
+    fake = _FakePopen(_events({"type": "result", "subtype": "success", "result": "ok"}))
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+
+    with pytest.raises(RuntimeError, match="missing session_id"):
+        ClaudeHandler().dispatch(prompt="p", cwd=tmp_path)
+
+
+def test_dispatch_bounds_the_agent_to_the_cwd_by_default(monkeypatch, tmp_path) -> None:
+    fake = _FakePopen(_events(INIT, {"type": "result", "subtype": "success", "result": "ok"}))
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+    monkeypatch.setattr(config, "load_config", dict)
+
+    ClaudeHandler().dispatch(prompt="p", cwd=tmp_path, model="sonnet")
+
+    assert "--dangerously-skip-permissions" not in fake.cmd
+    assert fake.cmd[fake.cmd.index("--permission-mode") + 1] == "acceptEdits"
+    assert fake.cmd[fake.cmd.index("--model") + 1] == "sonnet"
+
+
+def test_dispatch_yolo_is_opt_in(monkeypatch, tmp_path) -> None:
+    fake = _FakePopen(_events(INIT, {"type": "result", "subtype": "success", "result": "ok"}))
+    monkeypatch.setattr("playmaker.agents.claude.subprocess.Popen", fake)
+    monkeypatch.setattr(config, "load_config", lambda: {"agents": {"claude": {"yolo": True}}})
+
+    ClaudeHandler().dispatch(prompt="p", cwd=tmp_path)
+
+    assert "--dangerously-skip-permissions" in fake.cmd
+    assert "--permission-mode" not in fake.cmd

playmaker_cli-0.5.1/tests/test_permissions.py

@@ -0,0 +1,127 @@
+"""How each handler answers 'what may this agent do unattended?'."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import playmaker.config as config
+from playmaker.agents.claude import permission_args
+from playmaker.agents.codex import sandbox_args
+
+
+@pytest.fixture
+def configured(monkeypatch):
+    """Install a fake config.toml body for the duration of a test."""
+
+    def _set(cfg: dict) -> None:
+        monkeypatch.setattr(config, "load_config", lambda: cfg)
+
+    return _set
+
+
+def test_claude_defaults_to_accept_edits(configured) -> None:
+    configured({})
+
+    assert permission_args() == ["--permission-mode", "acceptEdits"]
+
+
+def test_claude_permission_mode_is_configurable(configured) -> None:
+    configured({"agents": {"claude": {"permission_mode": "plan"}}})
+
+    assert permission_args() == ["--permission-mode", "plan"]
+
+
+def test_claude_yolo_replaces_the_mode_entirely(configured) -> None:
+    configured({"agents": {"claude": {"yolo": True, "permission_mode": "plan"}}})
+
+    assert permission_args() == ["--dangerously-skip-permissions"]
+
+
+def test_claude_honours_the_legacy_skip_permissions_name(configured) -> None:
+    # 0.4 configs in the wild say skip_permissions; they must keep working.
+    configured({"agents": {"claude": {"skip_permissions": True}}})
+
+    assert permission_args() == ["--dangerously-skip-permissions"]
+
+
+def test_claude_skip_permissions_false_no_longer_means_do_nothing(configured) -> None:
+    # In 0.4 this produced a run that wrote nothing. It now falls through to
+    # the default mode, which can actually finish the work.
+    configured({"agents": {"claude": {"skip_permissions": False}}})
+
+    assert permission_args() == ["--permission-mode", "acceptEdits"]
+
+
+def test_claude_tool_lists_are_comma_joined(configured) -> None:
+    # Comma-joined on purpose: claude's --allowedTools is variadic and would
+    # otherwise swallow the positional prompt that follows it.
+    configured(
+        {
+            "agents": {
+                "claude": {
+                    "allowed_tools": ["Read", "Edit", "Bash(pytest:*)"],
+                    "disallowed_tools": ["WebFetch"],
+                }
+            }
+        }
+    )
+
+    args = permission_args()
+
+    assert args[args.index("--allowedTools") + 1] == "Read,Edit,Bash(pytest:*)"
+    assert args[args.index("--disallowedTools") + 1] == "WebFetch"
+
+
+def test_claude_tool_list_accepts_a_plain_string(configured) -> None:
+    configured({"agents": {"claude": {"allowed_tools": "Read, Edit"}}})
+
+    args = permission_args()
+
+    assert args[args.index("--allowedTools") + 1] == "Read,Edit"
+
+
+def test_codex_passes_no_sandbox_flag_by_default(configured) -> None:
+    configured({})
+
+    assert sandbox_args() == []
+
+
+def test_codex_sandbox_policy_is_forwarded(configured) -> None:
+    configured({"agents": {"codex": {"sandbox": "read-only"}}})
+
+    assert sandbox_args() == ["-s", "read-only"]
+
+
+def test_agy_yolo_defaults_on_because_it_has_no_middle_tier(configured) -> None:
+    configured({})
+
+    assert config.yolo_enabled("agy", default=True) is True
+    assert config.yolo_enabled("claude") is False
+
+
+def test_agy_yolo_can_be_turned_off(configured) -> None:
+    configured({"agents": {"agy": {"yolo": False}}})
+
+    assert config.yolo_enabled("agy", default=True) is False
+
+
+def test_shipped_config_template_is_valid_toml_and_matches_the_defaults() -> None:
+    # `playmaker init` writes this verbatim, so a typo here reaches every new
+    # user, and a drift from the handler defaults is a documentation lie.
+    import tomllib
+
+    from playmaker.agents.claude import DEFAULT_PERMISSION_MODE
+    from playmaker.cli import _DEFAULT_CONFIG
+
+    cfg = tomllib.loads(_DEFAULT_CONFIG)
+
+    assert cfg["agents"]["claude"]["permission_mode"] == DEFAULT_PERMISSION_MODE
+    assert cfg["agents"]["agy"]["yolo"] is True
+    assert "yolo" not in cfg["agents"]["claude"]  # the escape hatch stays commented out
+    assert "sandbox" not in cfg["agents"]["codex"]
+    assert cfg["notifications"]["editor"]

playmaker_cli-0.5.1/tests/test_state.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import sqlite3
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+import playmaker.state as state
+
+
+@pytest.fixture
+def db(monkeypatch, tmp_path: Path):
+    """Point the module-level paths at a throwaway home and initialise it."""
+    home = tmp_path / ".playmaker"
+    monkeypatch.setattr(state, "PLAYMAKER_HOME", home)
+    monkeypatch.setattr(state, "DB_PATH", home / "state.db")
+    monkeypatch.setattr(state, "LOGS_DIR", home / "logs")
+    monkeypatch.setattr(state, "OUTPUTS_DIR", home / "outputs")
+    monkeypatch.setattr(state, "AGENTS_DIR", home / "agents")
+    state.init_db()
+    return home
+
+
+def test_init_db_creates_the_directory_layout(db: Path) -> None:
+    assert (db / "state.db").is_file()
+    assert (db / "logs").is_dir()
+    assert (db / "outputs").is_dir()
+    assert (db / "agents").is_dir()
+
+
+def test_init_db_is_idempotent(db: Path) -> None:
+    sid = state.insert_session(agent="codex", prompt="p", cwd="/tmp")
+
+    state.init_db()
+
+    assert state.get_session(sid) is not None
+
+
+def test_insert_and_get_round_trip(db: Path) -> None:
+    sid = state.insert_session(
+        agent="agy",
+        prompt="do the thing",
+        cwd="/repo",
+        files=["a.py", "b.py"],
+        model="Claude Opus 4.6 (Thinking)",
+        batch_id="dash",
+    )
+
+    row = state.get_session(sid)
+
+    assert row is not None
+    assert row["agent"] == "agy"
+    assert row["status"] == "pending"
+    assert row["model"] == "Claude Opus 4.6 (Thinking)"
+    assert row["batch_id"] == "dash"
+    assert row["files"] == '["a.py", "b.py"]'
+
+
+def test_get_session_accepts_the_short_id_the_cli_prints(db: Path) -> None:
+    # `playmaker list` shows only the first 8 characters, so lookup by prefix
+    # is the normal way a user refers to a session.
+    sid = state.insert_session(agent="codex", prompt="p", cwd="/repo")
+
+    row = state.get_session(sid[:8])
+
+    assert row is not None
+    assert row["id"] == sid
+
+
+def test_get_session_unknown_id_returns_none(db: Path) -> None:
+    assert state.get_session("nope-not-here") is None
+
+
+def test_update_session_writes_only_named_fields(db: Path) -> None:
+    sid = state.insert_session(agent="claude", prompt="p", cwd="/repo")
+
+    state.update_session(sid, status="done", exit_code=0, cost_usd=0.42)
+
+    row = state.get_session(sid)
+    assert row is not None
+    assert (row["status"], row["exit_code"], row["cost_usd"]) == ("done", 0, 0.42)
+    assert row["prompt"] == "p"
+
+
+def test_update_session_with_no_fields_is_a_noop(db: Path) -> None:
+    sid = state.insert_session(agent="claude", prompt="p", cwd="/repo")
+
+    state.update_session(sid)
+
+    assert state.get_session(sid)["status"] == "pending"
+
+
+def test_list_sessions_filters_and_orders_newest_first(db: Path) -> None:
+    old = state.insert_session(agent="codex", prompt="old", cwd="/repo")
+    new = state.insert_session(agent="codex", prompt="new", cwd="/repo")
+    other = state.insert_session(agent="agy", prompt="other", cwd="/repo")
+    state.update_session(old, status="done", started_at="2020-01-01T00:00:00")
+    state.update_session(new, status="running", started_at="2030-01-01T00:00:00")
+
+    assert [r["id"] for r in state.list_sessions(agent="codex")] == [new, old]
+    assert [r["id"] for r in state.list_sessions(status="done")] == [old]
+    assert {r["id"] for r in state.list_sessions()} == {old, new, other}
+    assert len(state.list_sessions(limit=1)) == 1
+
+
+def test_list_batch_returns_only_that_batch_oldest_first(db: Path) -> None:
+    first = state.insert_session(agent="codex", prompt="a", cwd="/r", batch_id="dash")
+    second = state.insert_session(agent="agy", prompt="b", cwd="/r", batch_id="dash")
+    state.insert_session(agent="claude", prompt="c", cwd="/r", batch_id="other")
+    state.update_session(first, started_at="2020-01-01T00:00:00")
+    state.update_session(second, started_at="2030-01-01T00:00:00")
+
+    assert [r["id"] for r in state.list_batch("dash")] == [first, second]
+    assert state.list_batch("nothing") == []
+
+
+def test_init_db_migrates_a_database_without_model_and_batch_columns(
+    monkeypatch, tmp_path: Path
+) -> None:
+    # Databases created before 0.3/0.4 lack these columns; init_db must add
+    # them in place rather than leaving every query broken.
+    home = tmp_path / ".playmaker"
+    home.mkdir()
+    monkeypatch.setattr(state, "PLAYMAKER_HOME", home)
+    monkeypatch.setattr(state, "DB_PATH", home / "state.db")
+    monkeypatch.setattr(state, "LOGS_DIR", home / "logs")
+    monkeypatch.setattr(state, "OUTPUTS_DIR", home / "outputs")
+    monkeypatch.setattr(state, "AGENTS_DIR", home / "agents")
+    legacy = sqlite3.connect(home / "state.db")
+    legacy.execute(
+        """
+        CREATE TABLE sessions (
+            id TEXT PRIMARY KEY, agent TEXT NOT NULL, agent_session_id TEXT,
+            prompt TEXT NOT NULL, cwd TEXT NOT NULL, files TEXT,
+            status TEXT NOT NULL, started_at TEXT NOT NULL, finished_at TEXT,
+            exit_code INTEGER, cost_usd REAL, duration_seconds REAL,
+            output_path TEXT, session_file_path TEXT, parent_id TEXT, pid INTEGER
+        )
+        """
+    )
+    legacy.execute(
+        "INSERT INTO sessions (id, agent, prompt, cwd, status, started_at) "
+        "VALUES ('old-1', 'codex', 'p', '/repo', 'done', '2020-01-01T00:00:00')"
+    )
+    legacy.commit()
+    legacy.close()
+
+    state.init_db()
+
+    row = state.get_session("old-1")
+    assert row is not None
+    assert row["model"] is None
+    assert row["batch_id"] is None
+    assert state.insert_session(agent="agy", prompt="p", cwd="/r", batch_id="b")