@justjoshn/pi-pstack 0.15.36-pi.11 → 0.15.36-pi.12

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.15.36-pi.12] - 2026-11-04
+
+Each item below was checked against Cursor CLI 2026.10.22 with pstack and cursor-team-kit loaded, through its bundle and live runs. `parity/pi-pstack-behavior-parity/` in the repository records the evidence and the decisions.
+
+- A mode keeps its skill in context on every request until the user leaves it, as a Cursor Custom Mode does, and sends Cursor's notices: entered, the per-turn reminder, and an exit or switch notice once. The previous version sent the body on one request only, so models that replay the system prompt lost it.
+- A background completion arrives as Cursor's system notification: its preamble, a title from the first line of the prompt (80 characters at most), and its follow-up request. The background launch text and the Agent ID line use Cursor's wording.
+- Task, TodoWrite, and AskQuestion descriptions carry Cursor's usage rules, and AskQuestion needs two options per question. The model list adds Cursor's rules for user-requested models.
+- Add Cursor's built-in `explore` subagent type, a file-search specialist with Pi's search tools and no Task tool. team-kit's thermo-nuclear agent text, which names it, is upstream's again.
+- Every subagent hears Cursor's reminder that it runs under a parent and spawns no subagents unless asked.
+- Add `GenerateImage`, Cursor's image tool, on Pi's image models. It is offered when an image model is available and saves each image to the session's artifacts folder. `teach` asks for the image tool again, as upstream does.
+- Stop attaching `typescript-best-practices` when a `.ts` file is read. Cursor loads a skill that sets `paths` and `disable-model-invocation` only when invoked by name.
+- Plan mode follows Cursor's: its instructions, `CreatePlan {plan, name, overview, todos}` writing Cursor's plan file, edits to markdown files only, `SwitchMode` with the user's consent, and a build-locally, build-in-a-worker, or propose-changes choice after a saved plan. `create_plan` is gone.
+- A `/loop` wake that comes due during a run fires once when the run settles. A fixed tick was dropped before, and an agent-paced wake that landed during another run stopped the loop.
+- `make-bot-ui` describes webhook routines as they behave: no default expiry, and `sessionStrategy: "new_session"` for webhooks.
+
 ## [0.15.36-pi.11] - 2026-11-04
 
 - Title a background completion notice with the Task `description`, as Cursor names a subagent, instead of a slice of its prompt.

package/README.md

@@ -1,6 +1,6 @@
 # pstack for Pi (pi-pstack)
 
-pi-pstack is pstack 0.15.36 for Pi 1.5.0: rigorous agent workflows (`/poteto-mode` and its playbooks), the principle skills, and the review, research, and verification skills, plus the full soft-dependency team-kit set (`deslop`, `control-cli`, `control-ui`, CI/PR helpers, thermo-nuclear review, and the rest) vendored in so you do not install a separate team-kit package. A small extension provides the host features the skills call by name: `/name` skill commands, `/mode`, `/plan`, the `Task` subagent tool with local worktree workers, forks, and `agent_status`, `TodoWrite`, `AskQuestion`, the model rule, `/loop`, subscriptions and webhook routines, and `visualize`.
+pi-pstack is pstack 0.15.36 for Pi 1.5.0: rigorous agent workflows (`/poteto-mode` and its playbooks), the principle skills, and the review, research, and verification skills, plus the full soft-dependency team-kit set (`deslop`, `control-cli`, `control-ui`, CI/PR helpers, thermo-nuclear review, and the rest) vendored in so you do not install a separate team-kit package. A small extension provides the host features the skills call by name: `/name` skill commands, `/mode`, `/plan`, the `Task` subagent tool with local worktree workers, forks, and `agent_status`, `TodoWrite`, `AskQuestion`, `GenerateImage`, `SwitchMode`, the model rule, `/loop`, subscriptions and webhook routines, and `visualize`.
 
 ## Get set up
 
@@ -27,9 +27,9 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 | You type | What happens |
 |---|---|
 | `/poteto-mode <task>` | The skill attaches to that one message. Every skill Pi loaded works this way: pstack's (`/how`, `/why`, `/arena`, `/interrogate`, `/principle-prove-it-works`, `/deslop`) and your own, such as a `/<handle>-mode` skill from `/automate-me`. `/skill:<name>` works too. |
-| `/mode poteto-mode [task]` | Keeps the skill in context on every turn. The skill body rides the first request after entry, then each later request gets a reminder that names the skill file, so a long session does not re-send 21 KB every turn. The footer shows a badge with the skill's `icon` and `color` metadata, such as a yellow `♛ mode: poteto-mode` (other skills get `⚡`). `/mode off` exits and `/mode` reports. Any loaded skill can back a mode. |
-| `/plan [task]` | Plan mode: the agent gets read-only tools (`read`, `grep`, `find`, `ls`, the sandboxed `bash_readonly`, `create_plan`, `AskQuestion`, `TodoWrite`, `agent_status`, `Task`, whose launches run readonly: a fresh one runs here with no worktree, and a resume or fork stays where its agent ran, and `stop_agent`), investigates, and writes a plan with goal, verified steps, and risks. `create_plan` saves it under the agent dir's `plans/` as a `.plan.md` file, so the user can read it. Writes are blocked. A bare `/plan` enters plan mode. `/plan build` leaves plan mode and starts the work from the saved file, as the plan menu does; `/plan off` restores your tools. The footer shows `plan`. |
-| `/loop 30m <prompt>` | Runs the prompt now, then again every 30 minutes from each fire, so a long run does not push the next tick out. A tick that lands while a run is still going is skipped rather than queued, so one long run cannot leave a backlog of stale ticks; the next tick after it settles runs. The interval can come first or last, written as `30m`, `10 minutes`, or `every 10 minutes`. Without an interval the agent picks each wake with the `Loop` tool, and the loop ends when it picks none and no background subagent is still running. `/loop stop` or Escape during a run ends it. The prompt can be a skill command, such as `/loop 1h /poteto-mode run the audit tick`. When a playbook says to arm `/loop`, the agent starts it with the `Loop` tool. Intervals go up to 24 days. |
+| `/mode poteto-mode [task]` | Keeps the skill in context on every turn until you leave the mode: the skill rides every request in its own system-prompt section, which Pi re-sends only when it changes. The first request after entry says the user entered the mode, later requests carry a reminder that names the skill file, and the request after `/mode off` or a switch to another mode says the user left it. The footer shows a badge with the skill's `icon` and `color` metadata, such as a yellow `♛ mode: poteto-mode` (other skills get `⚡`). `/mode off` exits and `/mode` reports. Any loaded skill can back a mode. |
+| `/plan [task]` | Plan mode: the agent researches with read-only tools (`read`, `grep`, `find`, `ls`, the sandboxed `bash_readonly`, `AskQuestion`, `TodoWrite`, `agent_status`, `Task`, whose launches run readonly: a fresh one runs here with no worktree, and a resume or fork stays where its agent ran, and `stop_agent`), asks its clarifying questions early, and presents the plan with `CreatePlan` (`plan`, `name`, `overview`, `todos`). `CreatePlan` writes the plan file under `<pstack dir>/plans/` (`<name>-<8 hex>.plan.md`: the chat id in a comment, the todos as front matter, then the plan), one file per plan name in a chat. `edit` and `write` work on markdown files only, so the agent refines the plan in its file. After a run that saved a plan, an interactive session asks `Yes, build locally`, `Yes, build in cloud` (in a git repository: a background isolated worker builds it on its own branch), or `No, propose changes`. `/plan build` builds the saved plan too, and `/plan off` restores your tools. A bare `/plan` enters plan mode. The footer shows `plan`. |
+| `/loop 30m <prompt>` | Runs the prompt now, then again every 30 minutes from each fire, so a long run does not push the next tick out. A tick that comes due while a run is still going fires once when that run settles; several missed ticks still fire once. The interval can come first or last, written as `30m`, `10 minutes`, or `every 10 minutes`. Without an interval the agent picks each wake with the `Loop` tool, and the loop ends when it picks none and no background subagent is still running. `/loop stop` or Escape during a run ends it. The prompt can be a skill command, such as `/loop 1h /poteto-mode run the audit tick`. When a playbook says to arm `/loop`, the agent starts it with the `Loop` tool. Intervals go up to 24 days. |
 | `/routines` | Lists webhook routines with their URL, credential file, and status. |
 | `/setup-pstack` | Configures the per-role models. |
 | `/poteto-help <question>` | Answers a question about pstack and hands you a prompt to send. |
@@ -40,18 +40,17 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 
 | Feature | Behavior |
 |---|---|
-| `Task` (`description`, `prompt`, `subagent_type`, `model`, `run_in_background`, `resume`, `fork`, `fork_turns`, `readonly`, `file_attachments`, `environment`, `cloud_base_branch`) | Starts a separate `pi --mode rpc` process per subagent, so this Pi process can steer and abort it. Foreground calls return the response and an agent ID. Background calls return at once, and a `<task>` notification arrives after your turn ends, titled by the call's `description`; print and JSON runs wait for pending notifications before exiting, unless aborted. Several calls in one message run in parallel. A subagent's own subagents cannot spawn more. A run lock per agent ID keeps out a second writer, even from another Pi process (Limits notes the stale-lock race). Children inherit the parent's project-trust decision. Foreground usage counts toward the session totals. The Task card leads with the call's `description`, then the agent type and the model that ran, and while a foreground child works it shows its last few tool steps and latest line instead of a blank wait. |
+| `Task` (`description`, `prompt`, `subagent_type`, `model`, `run_in_background`, `resume`, `fork`, `fork_turns`, `readonly`, `file_attachments`, `environment`, `cloud_base_branch`) | Starts a separate `pi --mode rpc` process per subagent, so this Pi process can steer and abort it. Foreground calls return the response and an agent ID. Background calls return at once, and a `<system_notification>` with a `<task>` block arrives after your turn ends, titled by the first line of the prompt (80 characters at most) and followed by a request to do any follow-up work; the notification card shows the call's `description`. Print and JSON runs wait for pending notifications before exiting, unless aborted. Several calls in one message run in parallel. A subagent's own subagents cannot spawn more, and every subagent is told to spawn none unless asked. A run lock per agent ID keeps out a second writer, even from another Pi process (Limits notes the stale-lock race). Children inherit the parent's project-trust decision. Foreground usage counts toward the session totals. The Task card leads with the call's `description`, then the agent type and the model that ran, and while a foreground child works it shows its last few tool steps and latest line instead of a blank wait. |
 | `resume` | Sends a follow-up to an idle agent with its context, model, type, and directory. The root chat can resume or fork a descendant that a worktree worker started inside that worktree, and the descendant still runs where it first ran. On an agent running in this Pi process, it delivers the prompt as a steer and returns at once. A readonly or plan-mode call cannot steer a writable agent. An agent running in another Pi process is refused. This is how a playbook "messages" a worker. Pi's own `/resume` command reopens a chat session instead. |
 | `fork` | Starts a new agent whose transcript begins as a copy of an idle agent's transcript, in that agent's directory (its worktree for an isolated worker), so it sees the built checkout and uncommitted changes. Type, model, and readonly default from the source; readonly can be added, never lifted. `fork_turns: N` (only with `fork`) copies just the first N user turns. `fork` excludes `resume`, `environment`, and `cloud_base_branch`. Pi's own `/fork` command branches the chat session instead. |
 | `stop_agent` | `agent_id`. Stops a running subagent. One this Pi process owns gets an RPC abort, then a kill after a grace period. One another of your Pi processes owns gets a signal to the live pid in its run lock. An idle or finished agent is left alone, and the result says so. |
 | `agent_status` | Reads a subagent's state (`running` while its run lock names a live pid, `idle`, or `missing`), type, model, directory, branch, times, and last reply, without waking it. It also shows whether the agent is readonly, the agent it was forked from, its pid while running, and its transcript. Without `agent_id` it lists the workspace's 20 newest agents. In the root chat that includes every descendant, isolated workers too. |
-| Subagent types | `generalPurpose` (default), `poteto-agent` (a background delegate that reads poteto-mode first), `ci-watcher` (a background PR check watcher), `comment-sicko`, and `thermo-nuclear-code-quality-review`, the last four read from `agents/*.md`. Unknown types fail with the list. |
+| Subagent types | The built-in `generalPurpose` (default) and `explore` (a file-search specialist the caller tells how thorough to be, with `grep`, `find`, and `ls` on and no `Task`), then `poteto-agent` (a background delegate that reads poteto-mode first), `ci-watcher` (a background PR check watcher), `comment-sicko`, and `thermo-nuclear-code-quality-review`, the last four read from `agents/*.md`. Unknown types fail with the list. |
 | Models | A Pi model spec such as `claude-opus-5-5:xhigh` or `xai/grok-4.7:high`, model parameters such as `claude-opus-5-5[effort=high]` or `grok-4.7[fast=true]` (picks a listed `-fast` id of that model), `fast` for the parent model's listed `-fast` variant when it has one, else the parent model, or `inherit`, `inherit-parent`, `auto`, or nothing for the parent model. A model Pi does not list, or a thinking level the model does not support, fails with the allowed list. A bare model id that several providers offer resolves to the parent chat's provider when it offers that id, and otherwise fails with the choices. Older rules that wrote `claude-opus-5-5-xhigh` still resolve. The system prompt's `pstack_subagents` section lists the types, the parent model, and the models with their levels. |
 | Isolated workers (`environment: "cloud"`) | The subagent runs in a new git worktree at `<pstack dir>/workspaces/<workspace folder>/worktrees/<agent id>` on branch `pstack/<agent id>`, from `cloud_base_branch` (`origin/<branch>` when that remote-tracking ref exists, else a local branch or other ref) or your HEAD commit, so uncommitted changes do not reach it. The result and the card name the branch to merge, and `resume` and `fork` run in the same worktree. It fails clearly outside a git repository, in a repository with no commits, or when the base does not resolve. The worker shares the root chat's workspace state, so it sees the same projects, stores, and subagent transcripts. It also shares this machine's ports, processes, writable caches, simulators, and credentials. Assign separate ports, output directories, and writable caches to concurrent runtime lanes. `swarm` and `orchestrate` spawn worktree workers by default. |
 | `readonly: true` | The child gets `read`, `grep`, `find`, `ls`, `TodoWrite`, and a read-only `bash`, and no MCP. That shell runs each command in an OS sandbox ([`@anthropic-ai/sandbox-runtime`](https://github.com/anthropics/sandbox-runtime): `sandbox-exec` on macOS, bubblewrap on Linux) that blocks every file write and all network access, so `git log` works and `touch` or `curl` fail. Where no sandbox can start, the command fails rather than running unsandboxed. |
-| `TodoWrite` | `todos` with `id`, `content`, `status`, and `merge`. The list follows the session branch and shows above the editor. |
-| `AskQuestion` | `title`, and per question `id`, `prompt`, `options` (`id`, `label`, optional `description`), and `allow_multiple`, through Pi's select dialog. Every question ends with `Other: (type to answer)`; a typed answer comes back as `other` with its text. In print and JSON runs, including subagents, each question comes back skipped. |
-| Path-scoped skills | A skill whose frontmatter declares `paths` or `globs` (also under `metadata`) attaches once per session when the agent reads or edits a matching file, the way a path-scoped rule attaches. The shipped `typescript-best-practices` skill attaches on `.ts` and `.tsx` files this way. |
+| `TodoWrite` | `todos` with `id`, `content`, `status`, and `merge`. Its description says when to keep a list, the four states, and one task in progress at a time. The list follows the session branch, shows above the editor, and rides every request's system prompt. |
+| `AskQuestion` | `title`, and per question `id`, `prompt`, `options` (at least two, each `id`, `label`, optional `description`), and `allow_multiple`, through Pi's select dialog. It is for decisions only the user can make, and a recommended option goes first with `(Recommended)`. Every question ends with `Other: (type to answer)`; a typed answer comes back as `other` with its text. In print and JSON runs, including subagents, each question comes back skipped. |
 | Always-applied rules | The two team-kit rules are in `pstack_host` as their shipped text on every request, alongside the same rules as hidden skills. |
 | The model rule | `<pstack dir>/pstack-models.md`, plain Markdown with one line per role, added to every request's system prompt. A `pstack-models.mdc` from an earlier version is moved there once, without its frontmatter, and kept as `pstack-models.mdc.migrated`. |
 | Subscriptions | `subscribe_github_pr` (`scope` `pr` with `prUrl`, `repo` with `repo`, or `author` with `author` and `repo`) polls with `gh` every 60 seconds and wakes the chat when a PR's state, head, mergeability, review decision, reviews, or comments change, or when a check concludes or its conclusion changes; the first poll is a baseline. `subscribe_timer` takes a `name`, a `prompt`, and a 5-field `cron` or `delaySeconds`, either with `once`; `sessionStrategy` `wake_self` queues a wake for this owning session. With `new_session`, a live owner starts a background Task and receives its notification. An offline owner permits a detached run with a recorded outcome. Both reuse the model, thinking level, and project-trust decision the timer was created with. Re-subscribing an existing timer name returns `created: false`. `list_subscriptions` and `unsubscribe` manage them. The authoritative registry is `<pstack dir>/durable/<workspace>/subscriptions.json`. Any session in that workspace can list or cancel subscriptions. Session history does not recreate cancelled or completed subscriptions. Owner-directed events wait for the creating session rather than waking another workspace session. A detached run records its own final message, shown by `list_subscriptions`. A timer does not expire unless `expiresInHours` says so (at most 30 days); `0` means no expiry. A GitHub watch keeps a 7-day default because it is this port's own surface. |
@@ -60,7 +59,8 @@ Remove the package with `pi remove ./extensions/pi-pstack`. Its state lives in `
 | Stores and projects | The system prompt names "the current agent's store" (per session), "the root agent's store" (the main chat's, named to every subagent however deep), and the workspace's `projects/` folder, where a program's Project is `<slug>/notes.md` (its tracker) and `<slug>/store/`. |
 | `visualize` | `title`, `kind` (`bar` or `line`), `labels`, `series` (`name`, `values`), and `unit` render a Unicode chart in the result and write a standalone SVG to the session's artifacts folder. |
 | Transcripts | The system prompt names this workspace's Pi session directory, the current session file, and this workspace's subagent transcripts. |
-| Image generation | Pi's codemode `models.generateImages()`, when codemode is on and an image model is configured; otherwise skills fall back to a Mermaid diagram. |
+| `GenerateImage` | Generates an image (`description` of at least six words, `filename`, `reference_image_paths`, `aspect_ratio`) on Pi's image models through `ctx.modelRegistry.generateImages()`. It is offered when an image model is available (for example an OpenRouter image model), not to readonly subagents or in plan mode, and saves each image to the session's artifacts folder. Without an image model, the host section tells skills to draw a Mermaid diagram instead. |
+| `SwitchMode` | `target_mode_id` (`plan` or `agent`) and `explanation`. The agent proposes entering or leaving plan mode, and the switch happens only after you confirm it. Offered in interactive and RPC sessions. |
 
 Subagent transcripts are Pi sessions in `<pstack dir>/workspaces/<workspace folder>/subagents/`, with the agent ID in each file name, next to a small record that `resume`, `fork`, and `agent_status` read. Records belong to the main chat's shared workspace state, so the root chat can act on a descendant that ran in a worktree. Children inherit your installed extensions and MCP servers, and local ones run in your working directory. Give each local subagent that writes its own git worktree, or launch it with `environment: "cloud"`, because a child process does not isolate the filesystem. A child exits on its own if its parent Pi process dies.
 

package/agents/thermo-nuclear-code-quality-review.md

@@ -20,4 +20,4 @@ You are a **Task subagent**. The parent agent already collected git output and c
 
 ## Parent orchestration
 
-Typical flow: collect `git diff <base>...HEAD` (default base `main`) and the full contents of changed files with this chat's own tools (`bash`, `read`, `grep`), or with one `Task` `generalPurpose` / `poteto-agent` helper when the tree is large. Then invoke this agent with `subagent_type: "thermo-nuclear-code-quality-review"` and a user prompt containing `### Git / diff output` and `### Changed file contents`. Do not invent Task types such as `shell` or `explore`; only the types in `<pstack_subagents>` exist.
+Typical flow: in **one** message, run two `Task` calls in parallel — `subagent_type: "shell"` and `subagent_type: "explore"` — to collect `git diff <base>...HEAD` output and full contents of changed files (default base `main`). Then invoke this agent with `subagent_type: "thermo-nuclear-code-quality-review"` and a user prompt containing `### Git / diff output` and `### Changed file contents`.

package/docs/native-gaps.md

@@ -41,7 +41,7 @@ thin adapter over `RpcClient`.
 
 ## 2. The skill block `/mode` sends
 
-`modeSection` (`src/mode.ts:52-58`) strips frontmatter with Pi's exported `stripFrontmatter` (`dist/index.d.ts:50`) and
+`modeSkill` (`src/mode.ts:102`) strips frontmatter with Pi's exported `stripFrontmatter` (`dist/index.d.ts:50`) and
 wraps the body in the `<skill name="..." location="...">` block Pi's own `/skill:name` expansion builds
 (`AgentSession._expandSkillCommand`, `dist/core/agent-session.js:1739`). Pi exports `parseSkillBlock` and
 `formatSkillsForPrompt` (`dist/index.d.ts:3,23`), which parse a block and format the skills catalog; neither formats

package/docs/parity-status.md

@@ -8,23 +8,24 @@ This page records what `pi-pstack` reproduces from Cursor `pstack` 0.15.36 and i
 - Installed Cursor CLI at the time of the reference capture: `2026.10.22-27dcf5f`.
 - Native implementation: this package, which pins its upstream provenance in `package.json.pstackSource`.
 
-A path and byte comparison of the tracked trees shows every pstack skill, both pstack agents, all 18 team-kit skills, both team-kit agents, and both team-kit rules in this package. Seventeen team-kit skill files are byte-identical; `workflow-from-chats` describes Pi paths instead of Cursor paths. The changed pstack files are host translations. One upstream paragraph has no counterpart: `poteto-help`'s Claude Code install path and its `docs/harness/claude-code.md` adapter, because this package targets Pi only. The two non-portable frontmatter keys Cursor ships (`icon`/`color` on `poteto-mode`, `paths` on `typescript-best-practices`) are kept under `metadata`, the Agent Skills extension point; the port reads both, and it attaches `typescript-best-practices` by path through `src/path-skills.ts`.
+A path and byte comparison of the tracked trees shows every pstack skill, both pstack agents, all 18 team-kit skills, both team-kit agents, and both team-kit rules in this package. Seventeen team-kit skill files are byte-identical; `workflow-from-chats` describes Pi paths instead of Cursor paths. The changed pstack files are host translations. One upstream paragraph has no counterpart: `poteto-help`'s Claude Code install path and its `docs/harness/claude-code.md` adapter, because this package targets Pi only. The two non-portable frontmatter keys Cursor ships (`icon`/`color` on `poteto-mode`, `paths` on `typescript-best-practices`) are kept under `metadata`, the Agent Skills extension point. The port reads `icon` and `color` for the mode badge. `paths` stays as metadata only, because Cursor loads a `paths` skill that sets `disable-model-invocation` only when it is invoked by name. team-kit's thermo-nuclear agent changes only where it names the plugin that ships its rubric.
 
 ## Native translations
 
 | Cursor dependency | Pi mechanism |
 | --- | --- |
 | Skill invocation and the slash menu | `pi.getCommands()` plus `/name` to `/skill:name` input rewriting, with TUI completions |
-| Custom Mode | `/mode <skill>`, a branch-persisted entry, the skill attached once on the entering request, and a path-naming reminder in a `pstack_mode` prompt section on every later request |
-| Plan mode | `/plan`, a reduced tool set, `bash_readonly` in an OS sandbox, a `create_plan` artifact under `plans/`, and `/plan build` |
+| Custom Mode | `/mode <skill>`, a branch-persisted entry, the skill in a `pstack_mode_skill` prompt section on every request while the mode is on, and Cursor's entered, reminder, and exit or switch notices in `pstack_mode` |
+| Plan mode | `/plan` and `SwitchMode`, Cursor's plan-mode instructions in `pstack_plan`, a reduced tool set with `bash_readonly` in an OS sandbox and markdown-only `edit` and `write`, `CreatePlan` writing Cursor's plan file under `plans/`, and a build prompt after a saved plan (`/plan build` too) |
 | Always-applied model rule | `pstack-models.md` read before every request and injected as `pstack_models` |
-| Task subagents | One `pi --mode rpc` process per agent, with resume, steer, fork, `fork_turns`, readonly, attachments, background notices, and local worktrees |
-| Agent types | The four bundled agent Markdown files, loaded into the child system prompt |
+| Task subagents | One `pi --mode rpc` process per agent, with resume, steer, fork, `fork_turns`, readonly, attachments, Cursor's result and completion texts, Cursor's subagent reminder, and local worktrees |
+| Agent types | Cursor's built-in `generalPurpose` and `explore`, then the four bundled agent Markdown files, loaded into the child system prompt |
 | Project and agent stores | Workspace state folders named in the host system prompt |
 | Todo list | `TodoWrite` with branch reconstruction and a TUI widget |
-| Structured questions | `AskQuestion` over Pi select and input dialogs |
-| `/loop` | `Loop` tool and `/loop` command. A fixed interval is wall-clock from each fire, like Cursor's sleep loop, and accepts the interval first or last (`5m`, `10 minutes`, `every 10 minutes`). An interval-less loop is agent-paced through `Loop` `wake_in`. |
-| Path-scoped skills | `src/path-skills.ts` attaches a loaded skill once per session when the session reads or edits a file matching its `paths`/`globs` (also under `metadata`), the way Cursor files a skill under `fileGlobbed` |
+| Structured questions | `AskQuestion` over Pi select and input dialogs, with Cursor's schema minimums and usage rules |
+| Image generation (`GenerateImage`) | `GenerateImage` on `ctx.modelRegistry.generateImages()`, offered when an image model is available |
+| `/loop` | `Loop` tool and `/loop` command. A fixed interval is wall-clock from each fire, like Cursor's sleep loop, and accepts the interval first or last (`5m`, `10 minutes`, `every 10 minutes`). An interval-less loop is agent-paced through `Loop` `wake_in`. A wake that comes due mid-run fires once when the run settles, as Cursor's monitored shell output notifies after the turn. |
+| Path-scoped skills | None needed. pstack's only `paths` skill also sets `disable-model-invocation`, and Cursor loads such a skill only by name, which Pi does natively |
 | Always-applied rules | The two shipped rule bodies are read into `pstack_host` verbatim on every request, not paraphrased |
 | Todo list state | `TodoWrite` writes branch entries, and the current list rides in the `pstack_todos` prompt section on every request, so a compacted context still sees it |
 | Automations | Durable timer, GitHub, and webhook subscriptions with a detached supervisor |
@@ -44,6 +45,19 @@ A live Cursor CLI session with both plugins loaded produced these contracts.
 
 Pi returns the child's final text with a transcript path and usage, and reports background completion as a `pstack/task` notification. The payload shape differs because the hosts are different; the observable workflow, a subagent result arriving after the parent turn, is preserved.
 
+## Repairs in 0.15.36-pi.12
+
+A fresh reverse engineering of Cursor CLI 2026.10.22 with pstack and cursor-team-kit loaded found these differences. The repository's `parity/pi-pstack-behavior-parity/` holds the findings, the decision trail, and `probe-cursor.sh`, which reruns every Cursor probe. Each change has a test that failed on the earlier code.
+
+- A Custom Mode keeps its skill in context for the whole session in Cursor (its docs, and `durable_skill_blocks` in the CLI's conversation state). pi-pstack sent the body on one request, so a model that replays the system prompt lost it after a turn. The skill now rides every request, and Cursor's exit and switch notice is sent once after a mode ends.
+- A background completion uses Cursor's `<system_notification>` text, a title from the prompt's first line (80 characters at most), and its follow-up request; the launch text and Agent ID line use Cursor's words. An earlier repair had titled it by `description`, which Cursor shows in its UI but not in the model-facing notice.
+- Task, TodoWrite, and AskQuestion carry Cursor's usage rules; AskQuestion needs two options per question.
+- `explore` exists, and every subagent hears Cursor's subagent reminder. team-kit's thermo-nuclear agent text is upstream's again.
+- `GenerateImage` exists on Pi's image models. pstack's `teach` and `ketchup` reach for an image tool, which codemode, off by default, did not provide.
+- The path-skills module is gone. A live probe showed Cursor never surfaces a `paths` skill that sets `disable-model-invocation`, which is `typescript-best-practices`.
+- Plan mode follows Cursor's instructions and `CreatePlan` contract, allows markdown edits, offers `SwitchMode`, and asks whether to build a saved plan.
+- A `/loop` wake that comes due mid-run fires once after the run instead of being dropped, which had also stalled agent-paced loops.
+
 ## Repairs in 0.15.36-pi.11
 
 Each code change has a regression in the package suite. Text restorations are recorded here and checked against the reference by the parity audit.
@@ -85,10 +99,11 @@ Each code change has a regression in the package suite. Text restorations are re
 These are not closed by extension code.
 
 - **Background workers stop when the chat exits.** A Pi subagent is a child process of the chat, so quitting or shutting the session stops the agents it started and reports how many. Whether a Cursor background subagent outlives its parent is unobserved; the CLI changelog says cancelling the prompt stops its subagents, and only the cloud-agent product promises work after the laptop closes. A `new_session` subscription fire is Pi's one detached path, and it starts a fresh run rather than continuing a subagent.
-- **A mode carries its body once, then a reminder.** Cursor attaches the skill body on the turn that enters the mode and sends a path-naming reminder every turn after, in a user-message field. Pi rebuilds its prompt per request, so the body rides the first request after entry as a `pstack_mode` section and later requests carry the reminder. A process restart re-sends the body once, since the new process cannot know the conversation already saw it.
+- **A mode's skill rides the system prompt.** Cursor attaches the skill to the user message that enters the mode and keeps it durable in the conversation; its notices travel in user-message fields. Pi carries the skill and the notices in system-prompt sections, which reach the model on every request and survive compaction, so the model sees the same text in a different place.
 - **A fork needs an idle source.** Cursor exposes `fork` only on its internal and cloud-agent protos, never on the CLI Task schema, and no doc states whether a fork may start while the source runs. A Pi fork runs in the source's directory or worktree, so a running source is refused; the orchestrate playbook says to wait for its completion notification.
-- **Plan mode's restriction is stricter than the host's.** Cursor's inspected CLI carries no client-side plan-mode filter, and its docs recommend stating read-only intent in the prompt, so the restriction on that surface is prompt or backend side; no source shows a plan-mode network rule. Pi enforces a tool allowlist and a sandboxed shell that also denies network, so `gh`, `curl`, and package queries can fail while planning.
-- **No host-managed plan review UI.** The plan is a file the agent writes with `create_plan`, and `/plan build` starts the work from it. Cursor also renders a plan review menu with "build locally", "build in cloud", and "no, propose changes", and can hand the plan to a cloud agent. Pi has no equivalent UI, and its plan review is the file plus the reply.
+- **Plan mode's restriction is stricter than the host's.** Cursor's plan mode keeps every tool and restricts by instruction: edit only markdown files, run only read-only commands. Pi enforces the same rules with a tool allowlist, markdown-only `edit` and `write`, and a sandboxed shell that also denies network, so `gh`, `curl`, and package queries can fail while planning. Allowing network in a read-only shell would also open a path for remote changes, so the sandbox keeps it closed.
+- **The plan review is a dialog, not a card.** Cursor renders the plan with a build menu. Pi shows the same three choices in a select dialog after the run that saved the plan, and "build in cloud" starts a background isolated worktree worker, Pi's counterpart to a cloud agent, rather than a remote VM.
+- **One loop at a time.** Cursor's local `/loop` runs one shell loop per purpose, so several can run at once. pi-pstack runs one loop per session; a new `/loop` or `Loop` call replaces the running one. pstack's playbooks arm one audit loop at a time.
 - **benny's default cadence still needs its owning session open.** `wake_self` timers and webhook routines park while the owner is offline. A timer or webhook routine created with `sessionStrategy: "new_session"` runs detached with no chat open, but a detached run is one-shot: it must do the work in that run, because a background `Task` ends with it. Cursor automations run in the cloud and can hand work to anything. So benny keeps `wake_self` by default and setup names the tradeoff before switching.
 - **A routines listener is local, one port per workspace.** Cursor hosts each routine URL. Pi binds a loopback port per workspace, so two workspaces serve routines at once only because the default port falls back to an ephemeral one that the workspace then reuses and reports. A sender outside the machine still needs its own forwarding path.
 - **Cloud execution is local.** Cursor documents cloud VMs for its cloud product, but the inspected CLI schema omits `environment` and a requested cloud Task ran on the same machine and directory. Pi's `environment: "cloud"` goes further with a git worktree and a separate local process. Neither runs with the laptop off or provides a remote VM.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justjoshn/pi-pstack",
-  "version": "0.15.36-pi.11",
-  "description": "pstack 0.15.36 for Pi with its soft-dependency team-kit skills vendored in: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, and visualize",
+  "version": "0.15.36-pi.12",
+  "description": "pstack 0.15.36 for Pi with its soft-dependency team-kit skills vendored in: rigorous agent workflows and principles as Pi skills, with the host features they use: subagents, todos, modes, plan mode, the model rule, /loop, subscriptions and routines, AskQuestion, SwitchMode, image generation, and visualize",
   "type": "module",
   "license": "MIT",
   "pstackSource": {

package/skills/make-bot-ui/SKILL.md

@@ -20,7 +20,7 @@ Call `subscribe_webhook`. Set these fields:
 The routine slug is the kebab-case form of the name.
 The result gives the routine URL, `http://127.0.0.1:<port>/routines/<slug>`, and the credential file path. Use the path the result names, such as `~/.pi/agent/pstack/routines/<slug>/credentials.json` (`PI_CODING_AGENT_DIR` moves it).
 The result does not include the sender key.
-The routine targets the owning Pi session and expires at the `expiresAt` the result names. The durable supervisor keeps the listener available after the chat exits. Wakes received while the owner is offline park until that session is restored. Keep the owner running for immediate UI actions, and check the routine with `list_subscriptions`. A timer with `sessionStrategy: "new_session"` can start detached work while the owner is offline. A webhook does not use that strategy.
+By default the routine wakes the owning Pi session, which keeps its context across presses the way a bot does. The durable supervisor keeps the listener available after the chat exits. Wakes received while the owner is offline park until that session is restored. Keep the owner running for immediate UI actions, and check the routine with `list_subscriptions`. To act on presses with no chat open, pass `sessionStrategy: "new_session"`: each accepted POST starts a fresh detached run without the owner's context, which must do the work itself. The routine does not expire unless `expiresInHours` sets a limit.
 
 ## Copy the URL and the sender key
 

package/skills/teach/SKILL.md

@@ -14,7 +14,7 @@ Teach sits on top of `how` and `why`. Get your bearings on what the work is and
 2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git plus a source or two) so `why` records the skipped categories per its own contract, and widen it only when the reasons are the point.
 3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
 4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
-5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for image generation (Pi codemode's `models.generateImages()` when codemode is on and an image model is configured, otherwise a Mermaid diagram) and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
+5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
 
 Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.
 

package/src/ask.ts

@@ -9,17 +9,22 @@ export const OTHER_ID = 'other';
 const SKIPPED = 'skipped (no one can answer questions in this session; decide yourself and say what you chose)';
 
 export const AskParams = Type.Object({
-  title: Type.Optional(Type.String({ description: 'Short heading shown above the questions' })),
+  title: Type.Optional(Type.String({ description: 'Optional title for the questions form' })),
   questions: Type.Array(
     Type.Object({
-      id: Type.String({ description: 'Stable identifier for the question' }),
-      prompt: Type.String({ description: 'The question shown to the user' }),
-      options: Type.Array(Type.Object({ id: Type.String(), label: Type.String(), description: Type.Optional(Type.String({ description: 'Detail shown after the label' })) }), {
-        description: 'Choices the user picks from',
-      }),
-      allow_multiple: Type.Optional(Type.Boolean({ description: 'Let the user pick several options' })),
+      id: Type.String({ description: 'Unique identifier for this question' }),
+      prompt: Type.String({ description: 'The question text to display to the user, without the options.' }),
+      options: Type.Array(
+        Type.Object({
+          id: Type.String({ description: 'Unique identifier for this option' }),
+          label: Type.String({ description: 'Display text for this option' }),
+          description: Type.Optional(Type.String({ description: 'Detail shown after the label' })),
+        }),
+        { minItems: 2, description: 'Array of answer options (minimum 2 required)' },
+      ),
+      allow_multiple: Type.Optional(Type.Boolean({ description: 'If true, the user can select several options. Defaults to false.' })),
     }),
-    { description: 'Questions asked one after another' },
+    { minItems: 1, description: 'Questions to present to the user, one after another (minimum 1 required)' },
   ),
 });
 export type Question = Static<typeof AskParams>['questions'][number];
@@ -102,8 +107,17 @@ export function registerAskQuestion(pi: ExtensionAPI): void {
   pi.registerTool({
     name: 'AskQuestion',
     label: 'Ask question',
-    description:
-      'Ask the user one or more structured multiple-choice questions and wait for the answers. Each answer comes back as option IDs, or as other with the text the user typed. Use it for a genuine product or preference choice, not for a fact you can check yourself.',
+    description: [
+      "Collect structured multiple-choice answers from the user. Use this tool only when you are blocked on a decision that is genuinely the user's to make: one you cannot resolve from the request, the code, or sensible defaults.",
+      '',
+      'Usage notes:',
+      '- Give each question at least 2 options.',
+      '- The user can always pick "Other" and type an answer, which comes back as other with the text.',
+      '- Set allow_multiple: true to let the user pick several options.',
+      '- If you recommend an option, put it first and end its label with "(Recommended)".',
+      '',
+      'Prefer this tool over listing options in your reply text as letters, numbers, or bullets.',
+    ].join('\n'),
     promptSnippet: 'Structured multiple-choice questions for the user',
     parameters: AskParams,
     exposure: 'model-only',

package/src/generate-image.ts

@@ -0,0 +1,98 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, resolve } from 'node:path';
+
+import { detectSupportedImageMimeTypeFromFile, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+export const GENERATE_IMAGE = 'GenerateImage';
+
+const ASPECT_RATIOS = ['1:1', '4:3', '3:4', '16:9', '9:16'] as const;
+const EXTENSIONS: Record<string, string> = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif', 'image/webp': '.webp' };
+
+// Cursor's GenerateImage rules: explicit requests only, no data charts, a concrete description, and no Markdown echo.
+const DESCRIPTION = [
+  'Generate an image file from a text description.',
+  '',
+  'Use this tool only when the user explicitly asks for an image; do not generate images just to be helpful. Do not use it for data-heavy visuals such as charts, plots, or tables; make those with code or the visualize tool.',
+  '',
+  'Describe the image concretely first: the subjects, layout, style, colors, any text, and constraints, in at least 6 words. A description of 3 words or fewer is rejected. Set aspect_ratio when the user asks for one, and pass reference images in reference_image_paths.',
+  'The result shows the generated image and names the saved file, so do not repeat the image as Markdown in your reply.',
+].join('\n');
+
+const Params = Type.Object({
+  description: Type.String({ description: 'A detailed description of the image, at least 6 words. Descriptions of 3 words or fewer are rejected.' }),
+  filename: Type.Optional(Type.String({ description: "Optional file name for the image, such as 'diagram.png', without a directory. Defaults to a timestamped name." })),
+  reference_image_paths: Type.Optional(Type.Array(Type.String(), { description: 'Optional paths of reference images to use as additional inputs.' })),
+  aspect_ratio: Type.Optional(Type.Enum(ASPECT_RATIOS, { type: 'string', description: 'Optional aspect ratio: "1:1", "4:3", "3:4", "16:9", or "9:16".' })),
+});
+
+type ImageBlock = { type: 'image'; data: string; mimeType: string };
+
+async function referenceImage(path: string, cwd: string): Promise<ImageBlock> {
+  const absolute = isAbsolute(path) ? path : resolve(cwd, path);
+  const mimeType = await detectSupportedImageMimeTypeFromFile(absolute);
+  if (mimeType === null) throw new Error(`reference_image_paths: ${absolute} is not a PNG, JPEG, GIF, or WebP image.`);
+  return { type: 'image', data: readFileSync(absolute).toString('base64'), mimeType };
+}
+
+/** The saved file name: the requested name without any directory, with the extension the image data has. */
+export function imageFileName(requested: string | undefined, mimeType: string, index: number, now: Date): string {
+  const extension = EXTENSIONS[mimeType] ?? '.png';
+  const base = requested === undefined || basename(requested).trim() === '' ? `image-${now.toISOString().replace(/[:.]/g, '-')}` : basename(requested, extname(requested));
+  return `${base}${index === 0 ? '' : `-${index + 1}`}${extension}`;
+}
+
+/** The first image model Pi can call with the configured credentials. */
+async function imageModel(ctx: ExtensionContext) {
+  const [model] = await ctx.modelRegistry.getAvailableOfType('image');
+  return model;
+}
+
+/** Cursor's GenerateImage on Pi's image models, offered when one is available. Images save to the session's artifacts folder. */
+export interface GenerateImageOptions {
+  artifactsDir: (ctx: ExtensionContext) => string;
+  /** False where the session may not write files: a readonly subagent, or plan mode. */
+  mayOffer: () => boolean;
+}
+
+export function registerGenerateImage(pi: ExtensionAPI, options: GenerateImageOptions): void {
+  pi.registerTool({
+    name: GENERATE_IMAGE,
+    label: 'Generate image',
+    description: DESCRIPTION,
+    promptSnippet: 'Generate an image file from a text description',
+    parameters: Params,
+    defaultActive: false,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (params.description.trim().split(/\s+/).length <= 3) throw new Error('Describe the image in at least 6 words. Descriptions of 3 words or fewer are rejected.');
+      const model = await imageModel(ctx);
+      if (model === undefined) throw new Error('No image model is available. Configure one, such as an OpenRouter image model, to generate images.');
+      const references = await Promise.all((params.reference_image_paths ?? []).map((path) => referenceImage(path, ctx.cwd)));
+      const text = params.aspect_ratio === undefined ? params.description.trim() : `${params.description.trim()}\n\nAspect ratio: ${params.aspect_ratio}.`;
+      const result = await ctx.modelRegistry.generateImages(model, { input: [{ type: 'text', text }, ...references] }, signal === undefined ? undefined : { signal });
+      if (result.stopReason !== 'stop') throw new Error(`Image generation failed: ${result.errorMessage ?? result.stopReason}`);
+      const images = result.output.filter((block): block is ImageBlock => block.type === 'image');
+      if (images.length === 0) throw new Error('The image model returned no image.');
+      const dir = options.artifactsDir(ctx);
+      mkdirSync(dir, { recursive: true });
+      const now = new Date();
+      const paths = images.map((image, index) => {
+        const path = join(dir, imageFileName(params.filename, image.mimeType, index, now));
+        writeFileSync(path, Buffer.from(image.data, 'base64'));
+        return path;
+      });
+      return {
+        content: [{ type: 'text' as const, text: `Generated ${paths.length === 1 ? 'an image' : `${paths.length} images`} with ${model.provider}/${model.id}, saved to ${paths.join(', ')}.` }, ...images],
+        details: { paths, model: `${model.provider}/${model.id}` },
+      };
+    },
+  });
+
+  // The tool is on only while an image model is available, as Cursor offers GenerateImage only where it can run.
+  pi.on('session_start', async (_event, ctx) => {
+    if (!options.mayOffer() || (await imageModel(ctx)) === undefined) return;
+    const active = pi.getActiveTools();
+    if (!active.includes(GENERATE_IMAGE)) pi.setActiveTools([...active, GENERATE_IMAGE]);
+  });
+}

package/src/index.ts

@@ -1,13 +1,15 @@
+import { basename } from 'node:path';
+
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
 import { registerAskQuestion } from './ask.ts';
 import { aliasAutocomplete } from './autocomplete.ts';
 import { childIdentity } from './child-env.ts';
+import { registerGenerateImage } from './generate-image.ts';
 import { registerLoop } from './loop.ts';
 import { registerMode } from './mode.ts';
 import { canAsk, isOneShot } from './modes.ts';
-import { createPathSkills } from './path-skills.ts';
 import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
@@ -23,10 +25,14 @@ import { registerVisualize } from './visualize.ts';
 const WATCHDOG_MS = 1_000;
 const ORPHAN_EXIT_MS = 5_000;
 
-/** In a subagent, the agent definition body joins the system prompt as the agent's own instructions. */
+// What Cursor tells every subagent in a system reminder, minus its sentence about Cursor Canvas files.
+const SUBAGENT_REMINDER = 'You are running as a subagent under a parent agent. Do not spawn additional subagents unless requested by the user or by your instructions.';
+
+/** In a subagent, Cursor's subagent reminder, and the agent definition body as the agent's own instructions. */
 function agentSection(agents: readonly AgentDefinition[]): Record<string, string> {
+  if (childIdentity.depth === 0) return {};
   const prompt = agents.find((agent) => agent.type === childIdentity.agentType)?.prompt ?? '';
-  return prompt === '' ? {} : { pstack_agent: prompt };
+  return { pstack_subagent: SUBAGENT_REMINDER, ...(prompt === '' ? {} : { pstack_agent: prompt }) };
 }
 
 function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly AgentDefinition[]): Record<string, string> {
@@ -97,9 +103,11 @@ export default function piPstack(pi: ExtensionAPI): void {
   });
 
   const mode = registerMode(pi);
-  const plan = registerPlanMode(pi);
+  const plan = registerPlanMode(pi, { buildInWorker: (planFile, request) => task.startBackground(`Build ${basename(planFile)}`, request, { environment: 'cloud' }) });
   registerVisualize(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()) });
-  const task = registerTask(pi, { agents, depth: childIdentity.depth, planMode: plan.enabled });
+  registerGenerateImage(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()), mayOffer: () => !childIdentity.readonly && !plan.enabled() });
+  const ownType = agents.find((agent) => agent.type === childIdentity.agentType);
+  const task = registerTask(pi, { agents, depth: childIdentity.depth, canSpawn: childIdentity.depth < 2 && ownType?.spawns !== false, planMode: plan.enabled });
   registerAgentStatus(pi);
   registerSubscriptions(pi, {
     runFresh: async (prompt, name, meta) => {
@@ -112,25 +120,21 @@ export default function piPstack(pi: ExtensionAPI): void {
   });
   const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
   const todos = registerTodoWrite(pi);
-  const pathSkills = createPathSkills(pi);
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);
   if (childIdentity.readonly) registerReadonlyShell(pi);
 
   pi.on('before_agent_start', (event, ctx) => {
-    const modeText = mode.section();
     const loopText = loop.section();
     const planText = plan.section();
     const todoText = todos.section();
-    const pathSkillText = pathSkills.section();
     Object.assign(
       event.systemPromptOptions.sections,
       hostSections(pi, ctx, agents),
-      modeText === undefined ? {} : { pstack_mode: modeText },
+      mode.sections(),
       loopText === undefined ? {} : { pstack_loop: loopText },
       planText === undefined ? {} : { pstack_plan: planText },
       todoText === undefined ? {} : { pstack_todos: todoText },
-      pathSkillText === undefined ? {} : { pstack_path_skills: pathSkillText },
     );
   });
 

package/src/loop.ts

@@ -75,6 +75,8 @@ interface Loop {
   iteration: number;
   nextWakeMs?: number;
   timer?: ReturnType<typeof setTimeout>;
+  /** A wake came due while a run was going; it fires once when that run settles. */
+  due?: boolean;
 }
 
 const formatMs = (ms: number) => (ms % 86_400_000 === 0 ? `${ms / 86_400_000}d` : ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1_000)}s`);
@@ -107,39 +109,45 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     clear();
     notify(ctx, `Loop stopped: ${reason}`);
   };
-  const fire = (first = false) => {
+  const run = () => {
     if (loop === undefined) return;
-    // A scheduled tick that lands mid-run is skipped rather than queued, so one long run cannot leave a pile of stale ticks.
-    if (!first && lastCtx !== undefined && !lastCtx.isIdle()) {
-      if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
-      return;
-    }
-    const { timer: _timer, nextWakeMs: _wake, ...rest } = loop;
-    loop = { ...rest, iteration: rest.iteration + 1 };
+    loop = { ...loop, iteration: loop.iteration + 1, due: false };
     // Expansion lets a loop run a skill or template each time.
     pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true });
-    // A fixed loop is wall-clock from each fire, like the reference's sleep loop: a long run does not push the next tick out.
-    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+  };
+  /**
+   * A timer fired. A fixed loop keeps its wall-clock cadence, like Cursor's sleep-and-echo shell loop, so a long run
+   * does not push the next tick out. A wake that lands while a run is going is delivered once that run settles, as
+   * Cursor's monitored shell output notifies after the turn, and several such wakes fire once, not once each.
+   */
+  const tick = () => {
+    if (loop === undefined) return;
+    const { timer: _spent, nextWakeMs: _wake, ...rest } = loop;
+    loop = rest.intervalMs === undefined ? rest : { ...rest, timer: setTimeout(tick, rest.intervalMs) };
+    if (lastCtx !== undefined && !lastCtx.isIdle()) loop = { ...loop, due: true };
+    else run();
   };
   const settled = (ctx: ExtensionContext, aborted: boolean) => {
     lastCtx = ctx;
     if (loop === undefined) return;
     if (aborted) return stop(ctx, 'the run was aborted.');
+    if (loop.due === true) return run();
     if (loop.timer !== undefined) return;
     if (loop.intervalMs !== undefined) {
       // An armed fixed loop has no timer yet; its first tick waits for this turn to end.
-      loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+      loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
       return;
     }
     const delay = loop.nextWakeMs;
-    if (delay !== undefined) loop = { ...loop, timer: setTimeout(fire, delay) };
+    if (delay !== undefined) loop = { ...loop, timer: setTimeout(tick, delay) };
     else if (!options.hasPendingWork()) stop(ctx, 'the agent scheduled no next wake.');
   };
   const start = (ctx: ExtensionContext, prompt: string, intervalMs: number | undefined) => {
     if (loop !== undefined) stop(ctx, 'replaced by a new /loop.');
     lastCtx = ctx;
     loop = { prompt, iteration: 0, ...(intervalMs === undefined ? {} : { intervalMs }) };
-    fire(true);
+    run();
+    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
   };
   /** An agent arms a loop mid-turn, so its first run waits for this turn to settle and then for the first delay. */
   const arm = (ctx: ExtensionContext, prompt: string, schedule: { intervalMs: number } | { firstWakeMs: number }) => {