pi-prompt-template-model 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-03-20
+
+### Added
+- Added delegated-subprocess working directory controls via `cwd` frontmatter (for `subagent` prompts and chain-template defaults) plus runtime `--cwd=<path>` overrides.
+
+### Fixed
+- Rewrote README for clarity: fixed default subagent name (`delegate`, not `worker`), corrected provider priority to include `openai-codex`, merged broken frontmatter table into grouped sections with readable descriptions, cut redundant examples, and tightened prose throughout.
+
 ## [0.6.1] - 2026-03-20
 
 ### Added

package/README.md

@@ -4,40 +4,19 @@
 
 # Prompt Template Model Extension
 
-**Pi prompt templates on steroids.** Adds `model`, `skill`, and `thinking` frontmatter support. Create specialized agent modes that switch to the right model, set thinking level, and inject the right skill, then auto-restore when done.
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                                                                             │
-│  You're using Opus                                                          │
-│       │                                                                     │
-│       ▼                                                                     │
-│  /debug-python  ──►  Extension detects model + skill                        │
-│       │                                                                     │
-│       ▼                                                                     │
-│  Switches to Sonnet  ──►  Queues tmux skill context for next turn           │
-│       │                                                                     │
-│       ▼                                                                     │
-│  Agent responds with Sonnet + tmux expertise                                │
-│       │                                                                     │
-│       ▼                                                                     │
-│  agent_end fires  ──►  Restores Opus                                        │
-│       │                                                                     │
-│       ▼                                                                     │
-│  You're back on Opus                                                        │
-│                                                                             │
-└─────────────────────────────────────────────────────────────────────────────┘
+Adds `model`, `skill`, and `thinking` frontmatter to pi prompt templates. Define slash commands that switch to the right model, set a thinking level, inject skill context, and auto-restore your session when done.
+
+```
+/debug-python my code crashes
+  → switches to Sonnet, loads tmux skill, agent responds
+  → restores your previous model when finished
 ```
 
 ## Why?
 
-Create switchable agent "modes" with a single slash command. Each mode bundles:
+Each prompt template becomes a self-contained agent mode. `/quick-debug` spins up a cheap model with REPL skills. `/deep-analysis` brings in extended thinking with refactoring expertise. When the command finishes, you're back to your daily driver without touching anything.
 
-- **The right model** for the task complexity and cost tradeoff
-- **The right skill** so the agent knows exactly how to approach it
-- **Auto-restore** to your daily driver when done
-
-Instead of manually switching models and hoping the agent picks up on the right skill, you define prompt templates that configure both. `/quick-debug` spins up a cheap fast agent with REPL skills. `/deep-analysis` brings in the heavy hitter with refactoring expertise. Then you're back to your normal setup.
+No more manually switching models, no hoping the agent picks up on the right skill. You define the configuration once, and the slash command handles the rest.
 
 ## Installation
 
@@ -53,11 +32,11 @@ For delegated subagent execution (`subagent` and `inheritContext` frontmatter),
 pi install npm:pi-subagents
 ```
 
-pi-subagents is optional — everything else works without it. If you use `subagent: true` in a prompt template without pi-subagents installed, execution fails fast with a clear error.
+pi-subagents is optional — everything else works without it. Using `subagent: true` without it installed fails fast with a clear error.
 
 ## Quick Start
 
-Add `model` (or omit it to inherit the current session model) and optionally `skill` to any prompt template:
+Add `model` and optionally `skill` to any prompt template:
 
 ```markdown
 ---
@@ -68,124 +47,111 @@ skill: tmux
 Start a Python REPL session and help me debug: $@
 ```
 
-Run `/debug-python some issue` and the agent has:
-- Sonnet as the active model
-- Full tmux skill instructions already loaded
-- Your task ready to go
-
-## Skills as a Cheat Code
+Run `/debug-python some issue` and the agent switches to Sonnet, receives the tmux skill as context, and starts working. When it finishes, your previous model is restored.
 
-Normally, skills work like this: pi lists available skills in the system prompt, the agent sees your task, decides it needs a skill, and uses the read tool to load it. That's an extra round-trip, and the agent might not always pick the right one.
+## Frontmatter Reference
 
-With the `skill` field, you're forcing it:
-
-```markdown
----
-description: Browser testing mode
-model: claude-sonnet-4-20250514
-skill: surf
----
-$@
-```
+All fields are optional. Templates that don't use any extension features (no `model`, `skill`, `thinking`, etc.) are left to pi's default prompt loader.
 
-Here `skill: surf` loads `~/.pi/agent/skills/surf/SKILL.md` and injects its content as a context message on the next turn before the agent handles your task. No decision-making, no read tool, just immediate expertise. It's a forcing function for when you know exactly what workflow the agent needs.
+### Core Fields
 
-## Delegated Subagent Execution
+| Field | Default | What it does |
+|-------|---------|--------------|
+| `model` | current session model | Which model to use. Accepts a single model, a `provider/model-id` pair, or a comma-separated fallback list (see [Model Format](#model-format)). Ignored when `chain` is set. |
+| `skill` | — | Injects a skill's content as a context message before the agent handles your task. No extra round-trip — the agent gets the expertise immediately. See [Skill Resolution](#skill-resolution). |
+| `thinking` | — | Thinking level for the model: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. |
+| `description` | — | Short text shown next to the command in autocomplete. |
+| `chain` | — | Declares a reusable pipeline of templates (`step -> step`). When set, the body is ignored. See [Chain Templates](#chain-templates). |
 
-You can delegate a prompt template directly to the `subagent` extension without metaprompted tool-call instructions.
+### Execution Control
 
-```markdown
----
-model: anthropic/claude-sonnet-4-20250514
-subagent: true
----
-Review and simplify this code: $@
-```
-
-`subagent: true` uses the default `worker` agent. To target a specific agent, set a string value:
-
-```markdown
----
-model: anthropic/claude-sonnet-4-20250514
-subagent: reviewer
-inheritContext: true
----
-Audit this diff for correctness and edge cases: $@
-```
+| Field | Default | What it does |
+|-------|---------|--------------|
+| `restore` | `true` | After the command finishes, switch back to whatever model and thinking level were active before. Set `false` to stay on the new model. |
+| `loop` | — | Run this template multiple times by default (1–999). CLI `--loop` overrides this. See [Loop Execution](#loop-execution). |
+| `fresh` | `false` | When looping, collapse the conversation between iterations to a brief summary instead of carrying the full context forward. Saves tokens on long loops. |
+| `converge` | `true` | When looping, stop early if an iteration makes no file changes. Set `false` to always run every iteration. |
 
-`inheritContext: true` maps to delegated `context: "fork"`. It is valid only when `subagent` is configured.
+### Delegation
 
-Forked subagents receive a default preamble (from the subagent extension's `DEFAULT_FORK_PREAMBLE`) that anchors them to the task and prevents them from continuing the parent conversation.
-
-During execution, a live progress widget appears above the editor showing elapsed time, tool count, token usage, and the current/last tool — matching the native subagent tool card layout. The widget updates in real-time and clears when the run completes, replaced by a styled completion card with task preview, tool call history, output, and usage stats.
-
-You can override delegation at runtime per invocation:
-
-- `--subagent`
-- `--subagent=<name>`
-- `--subagent:<name>`
-
-Runtime flags take precedence for that invocation only. Bare `--subagent` keeps template agent when present, otherwise defaults to `worker`.
-
-## Frontmatter Fields
-
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `model` | No | `current` | Target model(s). If omitted on a non-chain template, execution inherits the current session model. Ignored when `chain` is set. |
-| `chain` | Conditional | - | Chain declaration (`step -> step --loop 2`) for orchestration templates; body is ignored |
-| `skill` | No | - | Skill name to inject as next-turn context message |
-| `thinking` | No | - | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
-| `subagent` | No | - | Delegate execution to subagent mode (`true` for default `worker`, or explicit agent name string) |
-| `inheritContext` | No | `false` | Only with `subagent`; when `true`, delegates with subagent `context: "fork"` |
-
-| `description` | No | - | Shown in autocomplete |
-| `restore` | No | `true` | Restore previous model and thinking level after response |
-| `fresh` | No | `false` | Collapse context between loop iterations (applies when looping via `--loop` or frontmatter `loop`) |
-| `loop` | No | - | Default loop count for this template (`1`-`999`) |
-| `converge` | No | `true` | Loop convergence behavior; set `false` to always run all iterations |
+| Field | Default | What it does |
+|-------|---------|--------------|
+| `subagent` | — | Delegate execution to a subagent instead of running in the current session. `true` uses the default `delegate` agent; a string value like `reviewer` targets that specific agent. Requires [pi-subagents](https://github.com/nicobailon/pi-subagents/). |
+| `inheritContext` | `false` | Only meaningful with `subagent`. When `true`, the subagent receives a fork of the current conversation context instead of starting fresh. |
+| `cwd` | — | Working directory for delegated subagent subprocesses. Must be an absolute path (`~/...` is expanded). Valid with `subagent`, and also on chain templates as the default cwd for delegated steps. |
 
 ## Model Format
 
 ```yaml
-model: claude-sonnet-4-20250514            # Model ID only - auto-selects provider
-model: anthropic/claude-sonnet-4-20250514  # Explicit provider/model
+model: claude-sonnet-4-20250514            # bare model ID — auto-selects provider
+model: anthropic/claude-sonnet-4-20250514  # explicit provider/model
 ```
 
-When you specify just the model ID, the extension picks a provider automatically based on where you have auth configured, preferring: `anthropic` → `github-copilot` → `openrouter`.
+Bare model IDs resolve through a provider priority list: `openai-codex` → `anthropic` → `github-copilot` → `openrouter`. The first provider with valid auth wins.
 
 For explicit control:
 
 ```yaml
 model: anthropic/claude-opus-4-5        # Direct Anthropic API
+model: openai-codex/gpt-5.2             # Via Codex subscription (OAuth)
 model: github-copilot/claude-opus-4-5   # Via Copilot subscription
 model: openrouter/claude-opus-4-5       # Via OpenRouter
 model: openai/gpt-5.2                   # Direct OpenAI API
-model: openai-codex/gpt-5.2             # Via Codex subscription (OAuth)
 ```
 
-## Model Fallback
+### Model Fallback
 
-Specify multiple models as a comma-separated list. The extension tries each one in order and uses the first that resolves and has auth configured.
+Comma-separated lists try each model in order:
 
 ```yaml
 model: claude-haiku-4-5, claude-sonnet-4-20250514
 ```
 
-This tries Haiku first. If it can't be found or has no API key, falls back to Sonnet. Useful when you have multiple provider accounts with different availability, or want a cost-optimized primary with a guaranteed fallback.
+Haiku is tried first. If it can't be found or has no API key, Sonnet is used instead. If the session is already on one of the listed models, that one is kept without switching. When every candidate fails, you get a single error listing what was tried.
 
-You can mix bare model IDs and explicit provider/model specs:
+You can mix bare IDs and explicit provider specs:
 
 ```yaml
 model: anthropic/claude-haiku-4-5, openrouter/claude-haiku-4-5, claude-sonnet-4-20250514
 ```
 
-Here the extension tries Haiku on Anthropic first, then Haiku on OpenRouter, then Sonnet on whatever provider has auth. If you're already on one of the listed models when the command runs, it uses that without switching.
+## Skills
+
+Normally, pi lists available skills in the system prompt, the agent reads your task, decides which skill it needs, and loads it with the read tool. That's an extra round-trip, and the agent might not pick the right one.
+
+The `skill` field bypasses all of that:
+
+```markdown
+---
+description: Browser testing mode
+model: claude-sonnet-4-20250514
+skill: surf
+---
+$@
+```
+
+The skill content is injected as a context message before the agent processes your task. No decision-making, no tool call — immediate expertise. If the skill file can't be found, the command fails fast instead of running without it.
 
-When all candidates fail, a single error notification lists everything that was tried.
+### Skill Resolution
+
+The `skill` field accepts a bare name or a `skill:` prefix:
+
+```yaml
+skill: tmux
+skill: skill:tmux    # equivalent
+```
+
+Resolution order:
+
+1. Registered skill commands from `pi.getCommands()` (source: `"skill"`)
+2. `<cwd>/.pi/skills/<name>/SKILL.md` or `<cwd>/.pi/skills/<name>.md`
+3. `.agents/skills` in the current directory and ancestors (up to the git root)
+4. `~/.pi/agent/skills/<name>/SKILL.md` or `~/.pi/agent/skills/<name>.md`
+5. `~/.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>.md`
 
 ## Inline Model Conditionals
 
-Prompt bodies can embed model-specific instructions directly in the markdown:
+Prompt bodies can include sections that only render for specific models:
 
 ```markdown
 ---
@@ -201,43 +167,28 @@ Do a deeper pass and call out subtle risks.
 </if-model>
 ```
 
-Conditionals are evaluated against the model that actually runs the command. For fallback prompts, that means after candidate resolution; for prompts without `model`, that means the current session model. The same template can render differently depending on which model is active.
-
-Supported matches inside `is="..."`:
-
-- Exact `provider/model-id`
-- Exact bare `model-id`
-- Provider wildcard like `anthropic/*`
-- Comma-separated lists combining any of the above
+Conditionals evaluate against whichever model actually runs — after fallback resolution for multi-model templates, or against the session model when `model` is omitted.
 
-Examples:
+The `is` attribute supports exact model IDs, `provider/model-id` pairs, provider wildcards like `anthropic/*`, and comma-separated combinations:
 
 ```markdown
-<if-model is="anthropic/claude-sonnet-4-20250514">...</if-model>
-<if-model is="claude-sonnet-4-20250514">...</if-model>
-<if-model is="anthropic/*">...</if-model>
-<if-model is="openai/gpt-5.2, anthropic/*">...</if-model>
+<if-model is="anthropic/*">Anthropic-specific instructions</if-model>
+<if-model is="openai/gpt-5.2, anthropic/*">Either OpenAI or Anthropic</if-model>
 ```
 
-`<else>` is the fallback branch for the current `<if-model>` block. Nested blocks are supported.
-
-Conditionals are a raw text preprocessing step, not markdown-aware syntax. If you want to show the directive literally inside a prompt, escape it in the source text, for example with `&lt;if-model is="anthropic/*"&gt;`.
+`<else>` is the fallback branch. Nested `<if-model>` blocks work.
 
 ## Argument Substitution
 
-Prompt bodies support argument placeholders that expand to command arguments:
+Prompt bodies support placeholders that expand to the arguments passed after the command name:
 
-| Placeholder | Description |
-|-------------|-------------|
-| `$1`, `$2`, ... | Positional argument (1-indexed) |
-| `$@` | All arguments joined with spaces |
-| `@$` | Alias for `$@` |
-| `$ARGUMENTS` | Same as `$@` |
+| Placeholder | Expands to |
+|-------------|------------|
+| `$1`, `$2`, ... | The Nth argument (1-indexed) |
+| `$@` or `@$` or `$ARGUMENTS` | All arguments joined with spaces |
 | `${@:N}` | All arguments from position N onward |
 | `${@:N:L}` | L arguments starting from position N |
 
-Example:
-
 ```markdown
 ---
 model: claude-sonnet-4-20250514
@@ -245,168 +196,114 @@ model: claude-sonnet-4-20250514
 Analyze $1 focusing on $2. Additional context: ${@:3}
 ```
 
-Running `/analyze src/main.ts performance edge cases error handling` expands to:
-- `$1` → `src/main.ts`
-- `$2` → `performance`
-- `${@:3}` → `edge cases error handling`
-
-## Skill Resolution
-
-The `skill` field accepts either a bare skill name or a slash-command style name:
-
-```yaml
-skill: tmux
-# also valid
-skill: skill:tmux
-```
-
-Resolution order:
-1. Registered skill commands from `pi.getCommands()` (`source: "skill"`), matched by `skill:name` or `name`
-2. `<cwd>/.pi/skills/<name>/SKILL.md` or `<cwd>/.pi/skills/<name>.md`
-3. `.agents/skills` in `cwd` and ancestor directories (up to git repo root)
-4. `~/.pi/agent/skills/<name>/SKILL.md` or `~/.pi/agent/skills/<name>.md`
-5. `~/.agents/skills/<name>/SKILL.md` or `~/.agents/skills/<name>.md`
-
-If the configured skill file is missing or unreadable, the command fails fast and does not send the prompt body to the model.
-
-## Subdirectories
-
-Organize prompts in subdirectories for namespacing:
-
-```
-~/.pi/agent/prompts/
-├── quick.md                    → /quick (user)
-├── debug-python.md             → /debug-python (user)
-└── frontend/
-    ├── component.md            → /component (user:frontend)
-    └── hook.md                 → /hook (user:frontend)
-```
-
-The subdirectory shows in autocomplete as the source label. Command names are based on filename only. If duplicates exist within the same source layer, the first one found after lexical sorting wins and later duplicates are skipped with a warning. Reserved command names like `model`, `reload`, and `chain-prompts` are also skipped with a warning.
+`/analyze src/main.ts performance edge cases error handling` expands `$1` to `src/main.ts`, `$2` to `performance`, and `${@:3}` to `edge cases error handling`.
 
-## Examples
+## Delegated Subagent Execution
 
-**Cost optimization** - use Haiku for simple summarization:
+Instead of running a prompt in the current session, you can hand it off to a subagent:
 
 ```markdown
 ---
-description: Save progress doc for handoff
-model: claude-haiku-4-5
+model: anthropic/claude-sonnet-4-20250514
+subagent: true
 ---
-Create a progress document that captures everything needed for another 
-engineer to continue this work. Save to ~/Documents/docs/...
+Review and simplify this code: $@
 ```
 
-**Skill injection** - guarantee the agent has REPL expertise:
+`subagent: true` delegates to the default `delegate` agent. To target a specific agent:
 
 ```markdown
 ---
-description: Python debugging session
-model: claude-sonnet-4-20250514
-skill: tmux
+model: anthropic/claude-sonnet-4-20250514
+subagent: reviewer
+inheritContext: true
 ---
-Start a Python REPL and help me debug: $@
+Audit this diff for correctness and edge cases: $@
 ```
 
-**Browser automation** - pair surf skill with a capable model:
+`inheritContext: true` forks the current conversation so the subagent has full context. Without it, the subagent starts fresh.
+
+To force a subagent into a specific working directory, add `cwd`:
 
 ```markdown
 ---
-description: Test user flow in browser
 model: claude-sonnet-4-20250514
-skill: surf
+subagent: browser-screenshoter
+cwd: /tmp/screenshots
 ---
-Test this user flow: $@
+Use url in the prompt to take screenshot: $@
 ```
 
-**Deep thinking** - max thinking for complex analysis:
+The subagent process runs with `/tmp/screenshots` as its working directory. Paths must be absolute (`~/...` is expanded). The directory is validated at execution time.
 
-```markdown
----
-description: Deep code analysis with extended thinking
-model: claude-sonnet-4-20250514
-thinking: high
----
-Analyze this code thoroughly, considering edge cases and potential issues: $@
-```
+During execution, a live progress widget appears above the editor showing elapsed time, tool count, token usage, and the current tool. When the run finishes, it's replaced by a completion card with the task preview, tool call history, output, and usage stats.
 
-**Model fallback** - prefer cheap, fall back to reliable:
+You can override delegation at runtime per invocation with `--subagent`, `--subagent=<name>`, `--subagent:<name>`, or `--cwd=<path>`. `--cwd=<path>` must be absolute after optional `~/...` expansion. Runtime flags take precedence for that invocation only.
 
-```markdown
----
-description: Save progress doc for handoff
-model: claude-haiku-4-5, claude-sonnet-4-20250514
----
-Create a progress document that captures everything needed for another 
-engineer to continue this work. Save to ~/Documents/docs/...
-```
+## Loop Execution
 
-**Cross-provider fallback** - same model, different providers:
+Run a template multiple times with `--loop`:
 
-```markdown
----
-description: Quick analysis
-model: anthropic/claude-haiku-4-5, openrouter/claude-haiku-4-5
----
-$@
+```
+/deslop --loop 5
+/deslop --loop=5
+/deslop --loop          # unlimited — runs until convergence (50-iteration cap)
 ```
 
-**Mode switching** - stay on the new model:
+You can also set a default in frontmatter. CLI `--loop` always overrides:
 
 ```markdown
 ---
-description: Switch to Haiku for this session
-model: claude-haiku-4-5
-restore: false
+loop: 5
 ---
-Switched to Haiku. How can I help?
 ```
 
-## Chaining Templates
+### How looping works
 
-The `/chain-prompts` command runs multiple templates sequentially. Each step switches to its own model (or, if the step has no `model`, to the chain-start model snapshot), renders inline model conditionals against that resolved step model, injects its own skill context message, and conversation context carries forward between steps.
+Each iteration runs the same prompt. By default, context accumulates — iteration 3 sees the full conversation from iterations 1 and 2 and builds on that work.
 
-```
-/chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
-```
+**Convergence**: If an iteration makes no file changes (no `write` or `edit` tool calls), the loop stops early. This is on by default. Use `--no-converge` or `converge: false` to always run every iteration. Bare `--loop` (unlimited) always forces convergence on, since its whole purpose is "run until nothing changes."
+
+**Fresh context**: Add `--fresh` (or `fresh: true` in frontmatter) to collapse the conversation between iterations. Each iteration gets a clean slate with only brief summaries of what previous iterations did. Good for long loops where accumulated context would blow up the token count.
+
+**Status**: The TUI status bar shows `loop 2/5` during execution.
 
-This runs `analyze-code` first, then `fix-plan` (which sees the analysis in conversation context), then `summarize`. The ` -- src/main.ts` part is optional. The literal ` -- ` separator means "shared args start here": everything after it is passed to each step as `$@`, unless that step already has its own inline args.
+Model, thinking level, and skill are maintained throughout. If `restore: true` (the default), everything is restored after the final iteration.
 
-Each step can also receive its own args, overriding the shared args for that step:
+## Chaining Templates
+
+`/chain-prompts` runs multiple templates in sequence. Each step uses its own model, skill, and thinking level, while conversation context flows between them:
 
 ```
-/chain-prompts analyze-code "look at error handling" -> fix-plan "focus on perf" -> summarize
+/chain-prompts analyze-code -> fix-plan -> summarize -- src/main.ts
 ```
 
-Here `analyze-code` gets `$@ = "look at error handling"`, `fix-plan` gets `$@ = "focus on perf"`, and `summarize` has no per-step args so it falls back to the shared args (empty in this case, but conversation context from prior steps is usually enough).
-
-You can mix both:
+This runs `analyze-code`, then `fix-plan` (which sees the analysis), then `summarize`. The ` -- ` separator marks shared args — everything after it is passed to each step as `$@`, unless a step has its own inline args:
 
 ```
 /chain-prompts analyze-code "error handling" -> fix-plan -> summarize -- src/main.ts
 ```
 
-Step 1 uses its per-step args (`"error handling"`), steps 2 and 3 fall back to the shared args (`"src/main.ts"`).
+Step 1 gets `"error handling"` as its args. Steps 2 and 3 fall back to the shared `"src/main.ts"`.
 
-The chain captures your current model and thinking level before starting, and restores them when the chain finishes (or if any step fails mid-chain). Individual template `restore` settings are ignored during chain execution.
+The chain captures your model and thinking level before starting and restores them when finished (or if any step fails).
 
 ### Chain Templates
 
-For reusable pipelines, define a chain in frontmatter instead of typing `/chain-prompts` every time:
+For reusable pipelines, put the chain in frontmatter:
 
 ```markdown
 ---
 description: Review then clean up
 chain: double-check --loop 2 -> deslop --loop 2
 ---
-ignored — chain templates don't use the body
 ```
 
-This registers `/review-then-clean` as a command that runs `double-check` twice, then `deslop` twice. Each step references a separate prompt template. Steps with `model` use their configured model; steps without `model` inherit the chain-start model snapshot (the model active when the chain command began), so behavior stays deterministic even if earlier steps switch models.
+This registers the file's name as a command that runs `double-check` twice, then `deslop` twice. Per-step `--loop N` repeats that step before moving to the next, with per-step convergence (stops early if no changes, unless the step's template has `converge: false`).
 
-Per-step `--loop N` repeats that step N times before moving to the next. Per-step convergence applies: if a step makes no file changes on an iteration, its inner loop stops early (unless the step's template has `converge: false`).
+Steps with a `model` field use their own model. Steps without one inherit a snapshot of whatever model was active when the chain started — not the previous step's model. This keeps behavior deterministic regardless of what earlier steps do.
 
-Chain templates support `loop`, `fresh`, `converge`, and `restore` in their frontmatter for overall execution control:
+Chain templates support `loop`, `fresh`, `converge`, `restore`, and `cwd` in their frontmatter for controlling the overall execution:
 
 ```markdown
 ---
@@ -417,152 +314,125 @@ converge: false
 ---
 ```
 
-This runs the full analyze → fix chain 3 times, with fresh context between iterations and no early stopping. CLI `--loop` overrides frontmatter `loop` when invoking the command.
+This runs the full analyze → fix chain 3 times, with fresh context between iterations and no early stopping. Chain nesting is not supported — steps can't reference other chain templates.
 
-Chain nesting is not supported — a chain template's steps cannot reference other chain templates.
+When a chain template sets `cwd`, it becomes the default delegated subprocess working directory for all delegated steps in that chain. Runtime `--cwd=<path>` overrides the chain template value.
 
-## Loop Execution
-
-Looping uses the `--loop` flag:
-
-```
-/deslop --loop 5
-/deslop --loop=5
-/deslop "focus on performance" --loop 3
-/deslop --loop
-```
-
-`--loop` without a number means unlimited looping until convergence, with a built-in safety cap of 50 iterations.
-
-You can also set a default loop count in frontmatter:
-
-```markdown
----
-model: claude-sonnet-4-20250514
-loop: 5
----
-...
-```
-
-With that template, `/deslop` runs 5 iterations by default. CLI `--loop` overrides frontmatter (`/deslop --loop 3` runs 3 iterations).
-
-The agent runs the same prompt N times. Context accumulates across iterations — by iteration 3, the agent sees the full conversation from iterations 1 and 2 and builds on that work. Use `--fresh` to collapse context between iterations instead (see below).
-
-By default, the loop stops early if an iteration makes no file changes (no `write` or `edit` tool calls), since there's nothing left to improve. Add `--no-converge` to always run all iterations for bounded loops, or set `converge: false` in frontmatter:
-
-```
-/deslop --loop 5 --no-converge
-```
-
-```markdown
----
-model: claude-sonnet-4-20250514
-loop: 5
-converge: false
----
-...
-```
-
-Bare `--loop` always forces convergence on (even with `--no-converge` or `converge: false`) because its intent is "run until no changes." `--loop N` and `--loop=N` support range 1-999. Quoted `"--loop"` is treated as a regular argument.
-
-Model, thinking level, and skill are maintained throughout the loop. If the template has `restore: true` (the default), the original model and thinking level are restored after the final iteration (or if any iteration fails). If `restore: false`, the switched model persists after the loop ends.
-
-### Fresh Context
-
-Add `--fresh` to collapse context between iterations:
-
-```
-/deslop --loop 5 --fresh
-/deslop --fresh      # when frontmatter sets loop: N
-```
-
-Each iteration's conversation is collapsed to a brief summary (files read, files modified, outcome) before the next iteration starts. The agent sees accumulated summaries from all previous iterations but not the full conversation. This saves tokens on long loops and gives each iteration a clean slate for reasoning.
-
-You can also set `fresh: true` in the template frontmatter to make it the default when looped:
-
-```markdown
----
-description: Remove AI slop from code
-model: claude-sonnet-4-20250514
-fresh: true
----
-Review the codebase and improve code quality. $@
-```
-
-### Loop with Chains
-
-Chains support the same looping forms:
+### Looping chains from the CLI
 
 ```
 /chain-prompts analyze -> fix --loop 3
-/chain-prompts analyze -> fix --loop=3
-/chain-prompts analyze -> fix --loop
 /chain-prompts analyze -> fix --loop 3 --fresh
 /chain-prompts analyze -> fix --loop 3 --no-converge
-/chain-prompts analyze -> fix --loop 3 -- src/main.ts
+/chain-prompts analyze -> fix --loop
 ```
 
-This runs the full chain (analyze → fix) three times. The final example adds optional shared args: ` -- src/main.ts` means "pass `src/main.ts` to any step that doesn't already have its own args." If you don't need shared args, leave that part out entirely. Convergence detection applies across all steps in each iteration — if no step made file changes, the loop stops. Each iteration re-reads prompts from disk, so template edits take effect between iterations. The status bar shows `loop 2/3` during execution. Chain frontmatter declarations also support per-step `--loop N` inside the `chain:` value (for example `chain: double-check --loop 3 -> simplify -> deslop`).
+Convergence applies across all steps in each iteration — if no step made file changes, the loop stops. Templates are re-read from disk between iterations, so edits take effect live.
 
 ## Agent Tool
 
-The agent can run prompt templates on its own via the `run-prompt` tool. Disabled by default — enable it with:
+The agent can invoke prompt templates itself via a `run-prompt` tool. It's off by default:
 
 ```
 /prompt-tool on
 ```
 
-Once enabled, the agent sees `run-prompt` in its tool list and can call it with any template command:
+Once enabled, the agent sees `run-prompt` in its tool list:
 
 ```
 run-prompt({ command: "deslop --loop 5 --fresh" })
-run-prompt({ command: "deslop --loop" })
-run-prompt({ command: "deslop --subagent" })
-run-prompt({ command: "deslop --subagent:reviewer" })
 run-prompt({ command: "chain-prompts analyze -> fix --loop 3" })
+run-prompt({ command: "deslop --subagent" })
 ```
 
-The tool queues the command for execution when the agent's current turn ends. All loop, fresh context, and convergence features work the same as when invoked via slash commands.
+The tool queues the command for execution after the agent's current turn ends. All loop, chain, and convergence features work the same as slash commands.
 
-Add guidance to steer when the agent uses it:
+You can add guidance to steer when the agent reaches for it:
 
 ```
 /prompt-tool on Use run-prompt for iterative code improvement tasks
 /prompt-tool guidance Use sparingly, only for multi-pass refinement
 /prompt-tool guidance clear
 /prompt-tool off
-/prompt-tool
+/prompt-tool                   # show current status
 ```
 
 Config persists across sessions in `~/.pi/agent/prompt-template-model.json`.
 
-## Autocomplete Display
+## Autocomplete
 
-Commands show model, thinking level, and skill in the description:
+Commands show their configuration in the autocomplete description:
 
 ```
 /debug-python    Debug Python session [sonnet +tmux] (user)
 /deep-analysis   Deep code analysis [sonnet high] (user)
 /save-progress   Save progress doc [haiku|sonnet] (user)
 /component       Create React component [sonnet] (user:frontend)
-/quick           Quick answer [haiku] (user)
 ```
 
-## Print Mode (`pi -p`)
+## Subdirectories
 
-These commands work in print mode too:
+Organize prompts in subdirectories for namespacing:
+
+```
+~/.pi/agent/prompts/
+├── quick.md                    → /quick (user)
+├── debug-python.md             → /debug-python (user)
+└── frontend/
+    ├── component.md            → /component (user:frontend)
+    └── hook.md                 → /hook (user:frontend)
+```
+
+The subdirectory shows as the source label in autocomplete. Command names are based on filename only. Duplicates within the same source layer are skipped with a warning, as are reserved names like `model`, `reload`, and `chain-prompts`.
+
+## Print Mode
+
+These commands work in `pi -p` too:
 
 ```bash
 pi -p "/debug-python my code crashes on line 42"
 ```
 
-The model switches, a skill context message is injected, the agent responds, and output prints to stdout. Useful for scripting or piping to other tools.
+The model switches, skill is injected, the agent responds, and output goes to stdout. Useful for scripting or piping.
+
+## Examples
+
+**Thinking levels** — max thinking for thorny analysis:
+
+```markdown
+---
+description: Deep code analysis with extended thinking
+model: claude-sonnet-4-20250514
+thinking: high
+---
+Analyze this code thoroughly, considering edge cases and potential issues: $@
+```
+
+**Sticky mode switch** — switch models for the rest of the session:
+
+```markdown
+---
+description: Switch to Haiku for this session
+model: claude-haiku-4-5
+restore: false
+---
+Switched to Haiku. How can I help?
+```
+
+**Cross-provider fallback** — try the same model on different providers:
+
+```markdown
+---
+description: Quick analysis
+model: anthropic/claude-haiku-4-5, openrouter/claude-haiku-4-5
+---
+$@
+```
 
 ## Limitations
 
-- Prompt files are reloaded on session start and whenever an extension-owned prompt command runs. If you add a brand-new prompt file while already inside a session, run another extension-owned command such as `/chain-prompts`, start a new session, or reload pi so the new slash command is registered.
-- Model restore state is in-memory. Closing pi mid-response loses restore state.
-- Model-less templates are only managed by this extension when they use extension features (for example `skill`, `thinking`, loop flags, or inline `<if-model ...>`). Plain prompt templates without extension features stay with pi's default prompt loader to avoid command conflicts.
-- In chains, model-less steps inherit the chain-start model snapshot, not the immediately previous step model. This is intentional for deterministic behavior.
-- Delegated `subagent` prompts require [pi-subagents](https://github.com/nicobailon/pi-subagents/) (`pi install npm:pi-subagents`).
-- The `run-prompt` tool must be explicitly enabled with `/prompt-tool on` before the agent can use it.
+- Prompt files are reloaded on session start and whenever an extension-owned command runs. If you add a new prompt file mid-session, run any extension command (like `/chain-prompts`), start a new session, or reload pi to pick it up.
+- Model restore state is in-memory. Closing pi mid-response loses it.
+- In chains, model-less steps inherit the chain-start model snapshot, not the previous step's model. This is intentional for deterministic behavior.
+- Delegated `subagent` prompts require [pi-subagents](https://github.com/nicobailon/pi-subagents/).
+- `run-prompt` must be explicitly enabled with `/prompt-tool on`.

package/args.ts

@@ -19,6 +19,7 @@ export interface SubagentOverride {
 export interface SubagentOverrideExtraction {
 	args: string;
 	override?: SubagentOverride;
+	cwd?: string;
 }
 
 export function extractLoopCount(argsString: string): LoopExtraction | null {
@@ -164,6 +165,7 @@ export function extractLoopFlags(argsString: string): LoopFlags {
 
 export function extractSubagentOverride(argsString: string): SubagentOverrideExtraction {
 	let override: SubagentOverride | undefined;
+	let cwdRaw: string | undefined;
 	const tokensToRemove: Array<{ start: number; end: number }> = [];
 
 	let i = 0;
@@ -197,10 +199,17 @@ export function extractSubagentOverride(argsString: string): SubagentOverrideExt
 			tokensToRemove.push({ start: tokenStart, end: i });
 			const value = token.includes("=") ? token.slice("--subagent=".length) : token.slice("--subagent:".length);
 			override = value ? { enabled: true, agent: value } : { enabled: true };
+			continue;
+		}
+
+		if (token.startsWith("--cwd=")) {
+			tokensToRemove.push({ start: tokenStart, end: i });
+			const value = token.slice("--cwd=".length);
+			cwdRaw = value || undefined;
 		}
 	}
 
-	if (!override) return { args: argsString.trim() };
+	if (tokensToRemove.length === 0) return { args: argsString.trim() };
 
 	tokensToRemove.sort((a, b) => b.start - a.start);
 	let cleaned = argsString;
@@ -210,7 +219,8 @@ export function extractSubagentOverride(argsString: string): SubagentOverrideExt
 
 	return {
 		args: cleaned.trim(),
-		override,
+		...(override ? { override } : {}),
+		...(cwdRaw !== undefined ? { cwd: cwdRaw } : {}),
 	};
 }
 

package/index.ts

@@ -6,7 +6,7 @@ import { parseChainSteps, parseChainDeclaration, type ChainStep } from "./chain-
 import { generateIterationSummary, didIterationMakeChanges, getIterationEntries } from "./loop-utils.js";
 import { notify, summarizePromptDiagnostics, diagnosticsFingerprint } from "./notifications.js";
 import { preparePromptExecution } from "./prompt-execution.js";
-import { buildPromptCommandDescription, loadPromptsWithModel, readSkillContent, resolveSkillPath, type PromptWithModel } from "./prompt-loader.js";
+import { buildPromptCommandDescription, expandCwdPath, loadPromptsWithModel, readSkillContent, resolveSkillPath, type PromptWithModel } from "./prompt-loader.js";
 import { renderSkillLoaded, type SkillLoadedDetails } from "./skill-loaded-renderer.js";
 import { createToolManager } from "./tool-manager.js";
 import { executeSubagentPromptStep } from "./subagent-step.js";
@@ -372,6 +372,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		converge: boolean,
 		ctx: ExtensionCommandContext,
 		subagentOverride?: SubagentOverride,
+		cwdOverride?: string,
 	) {
 		refreshPrompts(ctx.cwd, ctx);
 		const initialPrompt = prompts.get(name);
@@ -411,10 +412,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 					notify(ctx, `Prompt "${name}" no longer exists`, "error");
 					break;
 				}
+				const effectivePrompt = cwdOverride ? { ...prompt, cwd: cwdOverride } : prompt;
 
 				const iterationStartId = ctx.sessionManager.getLeafId();
 				const stepResult = await executePromptStep(
-					prompt,
+					effectivePrompt,
 					parseCommandArgs(cleanedArgs),
 					ctx,
 					currentModel,
@@ -426,7 +428,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				currentThinking = pi.getThinkingLevel();
 				completedIterations++;
 
-				const iterationChanged = shouldDelegatePrompt(prompt, subagentOverride)
+				const iterationChanged = shouldDelegatePrompt(effectivePrompt, subagentOverride)
 					? stepResult.changed
 					: didIterationMakeChanges(getIterationEntries(ctx, iterationStartId));
 				if (useConverge && (isUnlimited || effectiveMax > 1) && !iterationChanged) {
@@ -483,6 +485,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		shouldRestore: boolean,
 		ctx: ExtensionCommandContext,
 		subagentOverride?: SubagentOverride,
+		cwdOverride?: string,
 	) {
 		const validateChainSteps = (): boolean => {
 			const missingTemplates = steps.filter((step) => !prompts.has(step.name));
@@ -538,6 +541,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 
 				const templates = steps.map((step) => ({
 					...prompts.get(step.name)!,
+					...(cwdOverride ? { cwd: cwdOverride } : {}),
 					stepArgs: step.args,
 					stepLoop: step.loopCount ?? 1,
 				}));
@@ -665,6 +669,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		}
 
 		const subagent = extractSubagentOverride(args);
+		const runtimeCwd = subagent.cwd ? expandCwdPath(subagent.cwd) : undefined;
+		if (subagent.cwd && !runtimeCwd) {
+			notify(ctx, `Invalid --cwd path: must be absolute`, "error");
+			return;
+		}
 		const argsWithoutSubagent = subagent.args;
 
 		if (prompt.chain) {
@@ -696,6 +705,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				return;
 			}
 
+			const cwdOverride = runtimeCwd ?? prompt.cwd;
 			await runSharedChainExecution(
 				steps,
 				parseCommandArgs(cleanedArgs),
@@ -705,26 +715,28 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 				prompt.restore,
 				ctx,
 				subagent.override,
+				cwdOverride,
 			);
 			return;
 		}
 
 		const loop = extractLoopCount(argsWithoutSubagent);
 		if (loop) {
-			await runPromptLoop(name, loop.args, loop.loopCount, loop.fresh, loop.converge, ctx, subagent.override);
+			await runPromptLoop(name, loop.args, loop.loopCount, loop.fresh, loop.converge, ctx, subagent.override, runtimeCwd);
 			return;
 		}
 
 		if (prompt.loop !== undefined) {
 			const flags = extractLoopFlags(argsWithoutSubagent);
-			await runPromptLoop(name, flags.args, prompt.loop, flags.fresh, flags.converge, ctx, subagent.override);
+			await runPromptLoop(name, flags.args, prompt.loop, flags.fresh, flags.converge, ctx, subagent.override, runtimeCwd);
 			return;
 		}
 
+		const effectivePrompt = runtimeCwd ? { ...prompt, cwd: runtimeCwd } : prompt;
 		const savedModel = getCurrentModel(ctx);
 		const savedThinking = pi.getThinkingLevel();
 		const stepResult = await executePromptStep(
-			prompt,
+			effectivePrompt,
 			parseCommandArgs(argsWithoutSubagent),
 			ctx,
 			savedModel,
@@ -732,13 +744,13 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		);
 		if (stepResult === "aborted") return;
 
-		if (!shouldDelegatePrompt(prompt, subagent.override) && prompt.restore) {
+		if (!shouldDelegatePrompt(effectivePrompt, subagent.override) && prompt.restore) {
 			const currentModel = getCurrentModel(ctx);
 			if (savedModel && currentModel && !sameModel(savedModel, currentModel)) {
 				previousModel = savedModel;
 				previousThinking = savedThinking;
 			}
-			if (prompt.thinking && previousThinking === undefined && prompt.thinking !== savedThinking) {
+			if (effectivePrompt.thinking && previousThinking === undefined && effectivePrompt.thinking !== savedThinking) {
 				previousThinking = savedThinking;
 			}
 		}
@@ -840,6 +852,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		refreshPrompts(ctx.cwd, ctx);
 
 		const subagent = extractSubagentOverride(args);
+		const runtimeCwd = subagent.cwd ? expandCwdPath(subagent.cwd) : undefined;
+		if (subagent.cwd && !runtimeCwd) {
+			notify(ctx, `Invalid --cwd path: must be absolute`, "error");
+			return;
+		}
 		const loop = extractLoopCount(subagent.args);
 		const cleanedArgs = loop ? loop.args : subagent.args;
 
@@ -862,6 +879,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			true,
 			ctx,
 			subagent.override,
+			runtimeCwd,
 		);
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",

package/prompt-loader.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import type { ThinkingLevel } from "@mariozechner/pi-agent-core";
 import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 
@@ -45,6 +45,7 @@ export interface PromptWithModel {
 	converge?: boolean;
 	subagent?: true | string;
 	inheritContext?: boolean;
+	cwd?: string;
 	source: PromptSource;
 	subdir?: string;
 	filePath: string;
@@ -331,6 +332,47 @@ function normalizeSubagent(
 	return normalized;
 }
 
+export function expandCwdPath(raw: string): string | undefined {
+	const expanded = raw.startsWith("~/") ? join(homedir(), raw.slice(2)) : raw;
+	return isAbsolute(expanded) ? expanded : undefined;
+}
+
+function normalizeCwd(
+	value: unknown,
+	filePath: string,
+	source: PromptSource,
+	diagnostics: PromptLoaderDiagnostic[],
+): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-cwd",
+				filePath,
+				source,
+				`Ignoring invalid cwd in ${filePath}: expected a string.`,
+			),
+		);
+		return undefined;
+	}
+
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	const expanded = expandCwdPath(trimmed);
+	if (!expanded) {
+		diagnostics.push(
+			createDiagnostic(
+				"invalid-cwd",
+				filePath,
+				source,
+				`Ignoring cwd in ${filePath}: must be an absolute path.`,
+			),
+		);
+		return undefined;
+	}
+	return expanded;
+}
+
 function normalizeInheritContext(
 	value: unknown,
 	filePath: string,
@@ -500,6 +542,7 @@ function loadPromptsWithModelFromDir(
 				const { body } = parsed;
 				const chain = normalizeChain(frontmatter.chain, fullPath, source, diagnostics);
 				let subagent = normalizeSubagent(frontmatter.subagent, fullPath, source, diagnostics);
+				const cwd = normalizeCwd(frontmatter.cwd, fullPath, source, diagnostics);
 				const inheritContext = normalizeInheritContext(frontmatter.inheritContext, fullPath, source, diagnostics);
 				if (chain && subagent !== undefined) {
 					diagnostics.push(
@@ -522,6 +565,16 @@ function loadPromptsWithModelFromDir(
 						),
 					);
 				}
+				if (!chain && subagent === undefined && cwd) {
+					diagnostics.push(
+						createDiagnostic(
+							"invalid-cwd",
+							fullPath,
+							source,
+							`Ignoring cwd in ${fullPath}: frontmatter field "cwd" requires "subagent".`,
+						),
+					);
+				}
 				const hasModelField = Object.hasOwn(frontmatter, "model");
 				const parsedModels = chain ? [] : normalizeModelSpecs(frontmatter.model, fullPath, source, diagnostics);
 				if (!chain && hasModelField && !parsedModels) continue;
@@ -541,6 +594,7 @@ function loadPromptsWithModelFromDir(
 				}
 
 				const safeInheritContext = subagent !== undefined && inheritContext;
+				const safeCwd = (chain || subagent !== undefined) ? cwd : undefined;
 				const description = normalizeStringField("description", frontmatter.description, fullPath, source, diagnostics) ?? "";
 				const skill = chain ? undefined : normalizeStringField("skill", frontmatter.skill, fullPath, source, diagnostics);
 				const thinking = chain ? undefined : normalizeThinking(frontmatter.thinking, fullPath, source, diagnostics);
@@ -576,6 +630,7 @@ function loadPromptsWithModelFromDir(
 					converge: converge === false ? false : undefined,
 					subagent,
 					inheritContext: safeInheritContext || undefined,
+					cwd: safeCwd || undefined,
 					source,
 					subdir: subdir || undefined,
 					filePath: fullPath,
@@ -651,7 +706,8 @@ export function loadPromptsWithModel(cwd: string): LoadPromptsWithModelResult {
 export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const sourceLabel = prompt.subdir ? `(${prompt.source}:${prompt.subdir})` : `(${prompt.source})`;
 	if (prompt.chain) {
-		const details = `[chain: ${prompt.chain}] ${sourceLabel}`;
+		const cwdLabel = prompt.cwd ? ` cwd:${prompt.cwd}` : "";
+		const details = `[chain: ${prompt.chain}${cwdLabel}] ${sourceLabel}`;
 		return prompt.description ? `${prompt.description} ${details}` : details;
 	}
 	const modelLabel = prompt.models.length > 0 ? prompt.models.map((model) => model.split("/").pop() || model).join("|") : "current";
@@ -659,8 +715,9 @@ export function buildPromptCommandDescription(prompt: PromptWithModel): string {
 	const thinkingLabel = prompt.thinking ? ` ${prompt.thinking}` : "";
 	const loopLabel = prompt.loop ? ` loop:${prompt.loop}` : "";
 	const subagentLabel = prompt.subagent ? ` subagent:${prompt.subagent === true ? "delegate" : prompt.subagent}` : "";
+	const cwdLabel = prompt.cwd ? ` cwd:${prompt.cwd}` : "";
 	const inheritContextLabel = prompt.inheritContext ? " fork" : "";
-	const details = `[${modelLabel}${thinkingLabel}${skillLabel}${loopLabel}${subagentLabel}${inheritContextLabel}] ${sourceLabel}`;
+	const details = `[${modelLabel}${thinkingLabel}${skillLabel}${loopLabel}${subagentLabel}${cwdLabel}${inheritContextLabel}] ${sourceLabel}`;
 	return prompt.description ? `${prompt.description} ${details}` : details;
 }
 

package/subagent-step.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import type { AssistantMessage, Message } from "@mariozechner/pi-ai";
 import type { ExtensionAPI, ExtensionContext, ModelRegistry } from "@mariozechner/pi-coding-agent";
@@ -254,6 +255,10 @@ export async function executeSubagentPromptStep(options: DelegatedPromptOptions)
 		throw new Error(prepared.message);
 	}
 	if (prepared.warning) notify(ctx, prepared.warning, "warning");
+	const effectiveCwd = prompt.cwd ?? ctx.cwd;
+	if (effectiveCwd !== ctx.cwd && !existsSync(effectiveCwd)) {
+		throw new Error(`cwd directory does not exist: ${effectiveCwd}`);
+	}
 
 	const request: DelegatedSubagentRequest = {
 		requestId: randomUUID(),
@@ -261,7 +266,7 @@ export async function executeSubagentPromptStep(options: DelegatedPromptOptions)
 		task: prepared.content,
 		context: prompt.inheritContext ? "fork" : "fresh",
 		model: `${prepared.selectedModel.model.provider}/${prepared.selectedModel.model.id}`,
-		cwd: ctx.cwd,
+		cwd: effectiveCwd,
 	};
 
 	if (ctx.hasUI) {
@@ -320,4 +325,3 @@ export async function executeSubagentPromptStep(options: DelegatedPromptOptions)
 	}
 }
 
-