paseo-room 0.1.0 → 0.3.0

package/README.md

@@ -64,9 +64,12 @@ starts, its exit code is preserved; a signal is returned using the conventional
 ## Requirements
 
 - Node 22 or newer, macOS or Linux.
-- A running Paseo daemon with CLI and daemon on the same version. Codex and Claude require
-  **0.8.0-beta.1 or newer**; any selection containing Pi requires **0.8.0 or newer**.
-  `paseo-room` checks this before touching anything, and never installs or upgrades Paseo.
+- A running Paseo daemon with CLI and daemon on the same version. Codex requires
+  **0.8.0-beta.1 or newer**; any selection containing Claude or Pi requires **0.8.0 or newer**.
+  Claude also requires Paseo plugins to be enabled explicitly: the generated trusted server plugin
+  is the strong contract carrier, and `paseo-room` never enables plugins for you. The plugin is
+  version-bounded to `>=0.8.0 <0.9.0`. `paseo-room` checks compatibility before touching anything,
+  and never installs or upgrades Paseo.
 - An initialised Codex home (`~/.codex/config.toml`) and/or Claude Code home (`~/.claude`).
   Codex must be new enough for `codex debug models` to print its JSON model catalog: the room
   seats Codex only if it can generate the scrubbed catalog copy.
@@ -85,7 +88,10 @@ starts, its exit code is preserved; a signal is returned using the conventional
 ~/.paseo-room/
   room.json                       # what this CLI created; verify and remove read it
   AUTHENTICATION.md               # exact per-role login commands; contains no secrets
-  room/WORKSPACE_PROTOCOL.md      # the default protocol every seat carries, as one readable file
+  room/WORKSPACE_PROTOCOL.md      # the default protocol Lead and Supervisor carry, as one readable file
+  plugin/                         # Claude only: trusted creation-time system-prompt append carrier
+    paseo-plugin.json             # accepts Paseo >=0.8.0 <0.9.0
+    index.server.ts, server/      # exact provider map + generated role contracts
   roles/codex/<role>/
     config.toml                   # your config.toml + the room's overrides
     role-instructions.md          # readable copy of what this seat was told
@@ -237,18 +243,20 @@ holding older contract text.
 
 **The room never replaces an agent's base prompt.** Codex's `model_instructions_file`,
 Claude's `--system-prompt` and Pi's `SYSTEM.md` / `--system-prompt` all *replace* the vendor
-system prompt; using them would mean
-vendoring a full copy of that prompt and re-vendoring it on every agent release. The role
-contract is additive instead: `developer_instructions` for Codex, `CLAUDE.md` for Claude,
-and the generated Pi `APPEND_SYSTEM.md` passed with `--append-system-prompt` for Pi. Pi keeps
-normal project `AGENTS.md` / `CLAUDE.md` context loading.
-
-Claude's carrier is the weakest of the three, and knowingly so. `CLAUDE.md` is user memory,
-which a project-level `CLAUDE.md` can dilute, and Paseo runs Claude through the Claude Agent
-SDK rather than as a plain CLI process — so there is no provider-owned command line to append
-a stronger prompt through, and no CLI flag is proposed here. The real fix is a
-provider-owned SDK append field in Paseo itself. Until that exists, the room keeps the
-contract short and states the limit instead of implying parity with Codex.
+system prompt; using them would mean vendoring a full copy of that prompt and re-vendoring it
+on every agent release. The role contract is additive instead: `developer_instructions` for
+Codex, a room-owned Paseo creation hook that writes `config.systemPrompt` for Claude, and the
+generated Pi `APPEND_SYSTEM.md` passed with `--append-system-prompt` for Pi. Pi keeps normal
+project `AGENTS.md` / `CLAUDE.md` context loading.
+
+For Claude, Paseo maps `config.systemPrompt` to the Claude Code preset's SDK `append` field,
+so the native prompt remains intact while the generated role contract enters the instruction
+layer. The trusted plugin targets only exact `claude-supervisor`, `claude-lead`, and
+`claude-peer` room providers and skips internal agents; existing caller prompt text is
+preserved. `CLAUDE.md` remains unchanged as a degraded and resume fallback. `verify` fails if
+the plugin is absent, disabled, failed, registered from another path, or drifted, because a
+silently missing carrier is not a guarantee. The hook runs for newly created sessions;
+recreate an existing Claude session after setup or an update.
 
 Pi providers use a strict command tail:
 
@@ -340,7 +348,8 @@ Supervisor reads the exact current `room-<agent>-lead` profile from `list_profil
 materializes every field it defines (agent creation takes no profile id), uses `list_agents(cwd)`
 only to find candidates, then inspects each one's full status for the profile's provider, the
 intended workspace and its mode. For `room-<agent>-peer`, Lead copies provider, mode and
-features exactly, treats model and thinking as protocol-governed defaults, and additionally
+features exactly, keeps the profile's model unless the root workspace protocol routes models,
+chooses the thinking effort for the brief, and additionally
 requires the live seat's daemon-added `paseo.parent-agent-id` to name itself. Ownership must be
 corroborated by parentage or known Human-opened history; an ambiguous candidate goes to
 duplicate recovery and Human escalation instead of being adopted.
@@ -441,10 +450,12 @@ The exact model-facing wording every seat reads lives in the canonical Markdown
   that settles it rather than pre-solving the work; any plan or file list in it is provisional.
   One moving write scope has exactly one owner, and at most one Peer is writable at a time.
   Room tools: on.
-- **Peer** owns one bounded outcome, forms its own technical position from the code and its own
-  verification, may challenge a failed premise with
-  `REOPEN_REQUEST` / `DEPENDENCY_REQUEST` / `BLOCKED`, hands back a reproducible candidate,
-  and never accepts its own difficult change. Room tools: off.
+- **Peer** owns one bounded assignment — writable inside an assigned scope, or read-only
+  against a named candidate, question or area — under exactly one disposition Lead names in the
+  brief (Engineer, Architect, Reviewer or Scout), forms its own technical position from the code
+  and its own verification, may challenge a failed premise with
+  `REOPEN_REQUEST` / `DEPENDENCY_REQUEST` / `BLOCKED`, hands back reproducible evidence either
+  way, and never accepts its own difficult change. Room tools: off.
 
 Human keeps product goals, priority, material cost, external effects and irreversible risk.
 
@@ -465,18 +476,24 @@ Two further limits are deliberately conservative. **One writable Peer per projec
 per moving scope: the room gives you no writer isolation, so separate scopes are not evidence
 of separate working trees, and no workspace protocol relaxes the limit. Concurrent writable
 Peers in isolated worktrees are a deferred decision, not an oversight. And a seat's **model and
-reasoning effort are defaults**: Lead varies them for a brief only where the repository's
-workspace protocol supplies an explicit task-risk policy, and never up to a tier advertising
-automatic delegation. Provider, mode, workspace, parent and feature values are eligibility
-evidence and copied exactly.
-
-Every seat also carries a **default workspace protocol** — topology by difficulty,
-verification, review, repository conventions — so a project has that layer without doing
-anything. Each seat gets the sections that bear on its own work; topology goes to Lead and
-Supervisor, not to Peer. A repository that needs different rules writes
-`docs/WORKSPACE_PROTOCOL.md`, which wins wherever it speaks while the default holds
-wherever it is silent. `~/.paseo-room/room/WORKSPACE_PROTOCOL.md` is the whole default as
-one file, so you can read what is in force and start from it.
+reasoning effort are not one knob**: the model stays the profile's default unless the root
+`WORKSPACE_PROTOCOL.md` explicitly supplies model routing, while the thinking effort is Lead's
+per-brief choice on task risk, uncertainty, context size and verification burden — lowest that
+reliably answers the task, higher for architecture-sensitive or weakly observable work, only an
+option the live Paseo and provider context establishes as supported, and never up to a tier
+advertising automatic delegation. Provider, mode, workspace, parent and feature values are
+eligibility evidence and copied exactly.
+
+Every seat that owns workflow also carries a **default workspace protocol** — topology by
+difficulty, verification, review, repository conventions — so a project has that layer without
+doing anything. It goes to Lead and Supervisor, not to Peer: Lead reads the protocol and quotes
+what bears on an assignment into the brief, including the exact verification command, so a Peer
+spends its attention on one brief rather than on deciding which repository rules apply. A
+repository that needs different rules writes `WORKSPACE_PROTOCOL.md` at its root, which wins
+wherever it speaks while the default holds wherever it is silent — the root, because it is
+agent guidance rather than project documentation. `~/.paseo-room/room/WORKSPACE_PROTOCOL.md` is
+the whole default as one file, so you can read what is in force and start from it. The CLI
+never writes into a repository.
 
 ## Working the room