@signalridge/pi-subagents 1.8.1 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,192 @@
 # Changelog
 
+## 1.9.1
+### Patch Changes
+
+- fabe89a: Document how a workflow now reaches this catalogue.
+  
+  The "One catalogue, including for workflows" section said a workflow script names
+  a key from `agentTiers` directly, with "no second workflow-tier vocabulary and no
+  mapping layer" and `agent({ tier: "low" })` examples. pi-workflows scripts now
+  name a *strength* and a table on that side chooses the tier, so every claim in
+  that section was inverted and its example is rejected before dispatch.
+  
+  The claim it was protecting is still true and is now stated where it belongs:
+  there is no second tier catalogue and no second resolver, a `strengths` value is
+  a key in this catalogue and never carries its own `model`/`thinking`, and a
+  request arriving here is indistinguishable from a spawn that named the key
+  itself. Also notes that the shipped `low`/`medium`/`high` profiles are what
+  pi-workflows' default table maps onto, so renaming them leaves workflows on the
+  ordinary untiered path rather than breaking them.
+  
+  Drops a stale pointer to `workflow.tiers`, a settings key this package no longer
+  reads.
+
+## 1.9.0
+### Minor Changes
+
+- c1b1741: Protocol v4: workflows use the Agent-tier catalogue directly.
+  
+  The wire contract changes, so the three packages move together: `pi-workflows`
+  now declares `"@signalridge/pi-subagents": ">=1.9.0"`, and a peer outside that
+  range fails the startup handshake with a diagnostic naming both packages rather
+  than failing mid-run.
+  
+  The `small | medium | large` workflow-tier vocabulary and its mapping layer are
+  gone. A managed request names an Agent tier — a key in the host's own
+  `agentTiers` catalogue — and `resolveAgentTier()` is the single resolver for
+  every spawn path. Removed with it: the wire's mapped `agentTier` field, the
+  `workflow` settings key (retired with a warning naming it; `agentTiers.defaultTier`
+  replaces `workflow.defaultTier`), and the per-call `model`/`thinking` selectors,
+  which the validator now rejects rather than accepting and ignoring.
+  
+  Every v4 capability is required and every ping carries the host's tier catalogue,
+  so an incomplete peer fails one check instead of five optional ones. Fresh
+  installs ship `low`/`medium`/`high` profiles, all inheriting their model, and a
+  managed call that names no tier falls back to `medium`, so a workflow runs on an
+  unconfigured machine without this package choosing a vendor. Because `medium`
+  inherits, that fallback lands on the parent session's model — it commits to an
+  effort level, not to a vendor, so it does change the thinking level a managed
+  call runs at when the parent session is set higher, and it does not move the
+  work anywhere cheaper. What it buys is a named policy with a durable snapshot
+  and a scope check; a workspace that wants cheaper managed work names a
+  `defaultTier` whose profile pins a model. The fallback is scoped to calls that
+  cannot inherit a parent model rather than being installed as
+  `agentTiers.defaultTier`: a shipped catalogue default would have applied to
+  every ordinary `Agent` spawn as well, silencing `defaultModel` and pinning a
+  thinking level on machines that configured neither. The catalogue no longer
+  ships a `fast` profile; it was the same (model, thinking) pair as `low`, and the
+  one agent that named it (Explore) now names `low`. A user agent file that still
+  says `agentTier: fast` is reported by the existing unknown-reference check when
+  settings and agents load, rather than failing at its first spawn.
+  
+  `agentTiers.defaultTier` therefore has three states, and `/agents → Settings`
+  offers all three rather than rendering two of them as one word: a named tier,
+  `unset` (managed calls reach the shipped fallback), and `none` (recorded as
+  `noDefaultTier`, which withdraws the fallback so managed calls fail closed).
+  `setDefaultAgentTier` takes that choice as a tagged value, so a caller cannot
+  express "no default" without saying which of the two it means.
+  
+  `resolveAgentTier` gained `requireTier` for that fallback, and the two things
+  pre-resolution callers need are both answered by the resolver rather than
+  restated beside it: `agentTierApplies()` for "will a tier own this spawn's
+  model?", and `selectAgentTier()` for the tier key itself, which the managed
+  path needs to label a tombstone and the lifecycle events before the runner has
+  resolved anything.
+  
+  Because a tier now owns model resolution outright, the spawn paths stop
+  pre-resolving one — and with it they stopped producing the model name the agent
+  UI shows. The resolution callback carries that label back instead, so a tier
+  that pins a model still names it in the viewer and the agent list, and a profile
+  that inherits correctly shows none. The label rides beside the snapshot rather
+  than inside it: the snapshot is a durable policy record a managed tombstone
+  persists and revalidates, and a cosmetic string does not belong in it.
+  
+  Workflow resume now keys each cached call on the policy for that call's own tier
+  rather than on a whole-catalogue fingerprint, so defining or editing an unrelated
+  tier no longer forces a full re-execution — but only for a call that names its
+  tier. A call that names none keeps the whole-catalogue key, because the host
+  resolves those as `call > agent frontmatter > defaultTier` and frontmatter is
+  not on this wire: an agent reaches a managed caller as a name. Keyed on
+  `defaultTier`, such a call would be wrong twice over — replaying stale work
+  after an edit to the tier its agent actually declares, and re-executing after an
+  edit to a default it never reached. `agentTierPolicyIdentity()` therefore
+  requires a tier rather than accepting `undefined` and folding the default in, so
+  the wrong call cannot be written. Journal schema v4 and managed tombstone schema
+  v2 are quarantined from older facts rather than migrated.
+  
+  The tier catalogue belongs to the user, names included. The built-in workflows
+  and the ad-hoc script ship with this package, so a tier name they use that the
+  host does not define is dropped in favour of the host's default rather than
+  failing the run — they cannot assert which names exist on someone else's
+  machine. A script the user wrote still fails closed on an undefined tier, since
+  that is a typo in a catalogue they own. Shipped-ness travels with the script
+  rather than with the frame that called it, so a user script that reaches a
+  built-in through `workflow(name)` applies the built-in's rule to the built-in;
+  the authoring skill now says outright that `low`/`medium`/`high` are the shipped
+  profiles rather than names an authored script may assume.
+  
+  The managed routing policy published on the wire reports the default a managed
+  call will actually get, fallback included, so a peer's replay identity cannot
+  disagree with the host's selection; its sorts are code-unit rather than
+  locale-dependent, so the same catalogue fingerprints identically everywhere. The
+  workflow peer re-pings per start and resume instead of pinning the catalogue it
+  saw at session start, and reports the host-selected tier back through an
+  `onTierResolved` callback rather than by mutating the dispatch options.
+  
+  Fixes: a nested spawn no longer relabels an agent's frontmatter tier as
+  caller-requested, which had turned a `scopeModels` warning into a refusal and
+  misattributed the choice; the scheduler no longer freezes a frontmatter tier into
+  a job, so editing the agent file takes effect at fire time; retired managed spawn
+  keys are now bounded instead of growing for the life of a session; a
+  scope refusal for a tier whose profile inherits its model now names the model
+  that would have run instead of the literal `undefined`; and the retired
+  `workflow` key warns once per process rather than on every settings read and
+  every project write.
+  
+  The tier-key predicate and its length bound now have a single definition, in
+  `pi-subagents-protocol`, which `pi-subagents` re-exports. The wire is the
+  narrower of the two gates — a key one accepted and the other rejected could
+  never reach a peer — so a second copy could only ever be a way for them to
+  disagree. That one definition now also governs `blockedProfiles`, which was
+  being validated by a helper that trims first: `" low"` became `"low"` there
+  while the same value in `profiles` or `defaultTier` was refused outright. All
+  three reject.
+  
+  `/agents → Settings` no longer names the fallback tier in the `unset` row's
+  label. Which tier `unset` reaches depends on the catalogue, and a workspace that
+  edits or deletes the shipped `medium` profile leaves it reaching nothing — at
+  which point `unset` and `none` behave identically. The row's description asks
+  the resolver what `unset` would currently resolve to and says that, including
+  when the answer is "nothing".
+  
+  `pi-workflows` also gained the session-lifecycle handling this routing work
+  needed to sit on. The engine has an explicit dispose lifecycle, so a protocol
+  probe or a start that is in flight when a session ends rejects with a disposed
+  error instead of resolving against an engine nobody owns. The tool, command and
+  widget surfaces register exactly once and resolve the *current* engine on each
+  use, rather than closing over the one that existed when they were registered —
+  a session replacement previously left them pointing at a disposed engine. Tool
+  and command handlers report failures as results rather than throwing out of the
+  host's dispatch, and the lifecycle handler accepts `subagents:created` and
+  `subagents:started` so a spawn's identity is recorded from the first event that
+  carries it rather than only at completion.
+
+### Patch Changes
+
+- c1b1741: Durability and containment fixes found in a repository-wide scan.
+  
+  `pi-gpt-fast` rewrote pi's own global `settings.json` with a plain
+  `writeFileSync`. That file is shared with pi and every other extension, and this
+  one is the only writer of it; a torn write would have left the user with no pi
+  configuration at all rather than just no gpt-fast setting. It now writes a temp
+  file and renames, matching every other settings writer in the repository.
+  `pi-goal` gets the same treatment for its cross-project goal state file, which
+  its own settings module already did.
+  
+  `pi-ralph-wiggum` resolved `/ralph start <path>` straight against the session
+  cwd, so `../../notes.md` would create directories and a file outside the project
+  the user opened — silently, before the loop started. This extension drives long
+  unattended loops, so that command is as likely to come from a model as from a
+  person. Task-file paths are now required to stay inside the workspace, on the
+  command, on the `ralph_start` tool, and on the paths read back out of persisted
+  state, so a state file written earlier or edited by hand cannot pull a file in
+  from outside either.
+  
+  The containment test canonicalizes both sides before comparing, because a purely
+  lexical one is defeated by a symlink: every segment of `linked/plan.md` reads as
+  inside the workspace when `linked` is a door out of it. `realpathSync` throws on
+  a path that does not exist yet — the ordinary case, since `start` is usually
+  creating the file — so it resolves the deepest existing ancestor and re-attaches
+  the not-yet-created suffix, which cannot itself be a link. The traversal test
+  matches a `..` segment rather than a `..` prefix; the prefix form also rejected
+  `..notes.md`, an ordinary filename sitting in the workspace.
+  
+  Every remaining bare `catch {}` now says why the error is safe to drop, matching
+  the convention the rest of the repository already follows.
+- Updated dependencies [c1b1741]
+  - @signalridge/pi-subagents-protocol@1.4.0
+
 ## 1.8.1
 ### Patch Changes
 

package/README.md

@@ -26,7 +26,7 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
-- **Cross-extension RPC** — other Pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Protocol v3 adds managed spawning, optional model/thinking/toolset/denylist/thread/worktree hints, owner-scoped stop/quiescence, and standardized reply envelopes; pi-subagents remains the final policy owner. Emits `subagents:ready` on session start
+- **Cross-extension RPC** — other Pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Protocol v4 adds managed spawning, a request-level Agent `tier`, toolset/denylist/thread/worktree hints, owner-scoped stop/quiescence, a published Agent-tier routing policy, and standardized reply envelopes; pi-subagents remains the final policy owner. Pre-schema-v2 managed tombstones are quarantined rather than replayed. Emits `subagents:ready` on session start
 - **Schedule subagents** — pass `schedule` to the `Agent` tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same `subagent-notification` followUp path as manual background completions; manage via `/agents → Scheduled jobs`
 - **Model tiers** — name a (model, thinking) pair once and let the orchestrator pick it by name; the `Agent` tool exposes `tier` and never `model`/`thinking`, so which model runs stays a config decision. Manage the catalogue in `/agents → Model tiers`, pick the default in `/agents → Settings → Default tier`, or set a plain `defaultModel` when one line beats a catalogue
 - **Model scope enforcement** — opt-in validation that subagent model choices stay within your pi `enabledModels` allowlist (sourced from `/scoped-models`, with both global and project-local pi settings honored). Caller-supplied out-of-scope → hard error to orchestrator; frontmatter-pinned out-of-scope → warning + runs anyway (frontmatter authoritative). Toggle via `/agents → Settings → Scope models`
@@ -414,12 +414,12 @@ When background agents complete, they notify the main agent. The **join mode** c
 
 ## Model tiers
 
-A **tier** is one name for a (model, thinking) pair. The host agent picks a tier
-by name and nothing else: the `Agent` tool exposes `tier` and does **not** expose
-`model` or `thinking`, so which model runs is decided by whoever writes
-`subagents.json`, not by the orchestrator improvising per call.
+An **Agent tier** is one name for a (model, thinking) pair. The host agent picks a
+tier by name and nothing else: the `Agent` tool exposes `tier` and does **not**
+expose `model` or `thinking`, so which model runs is decided by the Agent-tier
+catalogue rather than by the orchestrator improvising per call.
 
-Names are yours. `small`/`medium`/`large` below are only an example — `research`,
+Names are yours. The names below are only an example — `research`,
 `cheap`, `nightly` are equally valid keys. Replace the illustrative provider/model
 values with models available in your environment.
 
@@ -428,10 +428,10 @@ values with models available in your environment.
   "agentTiers": {
     "defaultTier": "medium",
     "profiles": {
-      "small":    { "description": "Fast, cheap exploration",        "model": "provider/fast-model", "thinking": "max" },
-      "medium":   { "description": "Ordinary planning and review",   "model": "provider/reasoning-model", "thinking": "max" },
-      "large":    { "description": "Architecture and risky review",  "model": "provider/architecture-model", "thinking": "xhigh" },
-      "research": { "description": "Long-context research",          "model": "provider/long-context-model",       "thinking": "max" }
+      "low":      { "description": "Fast, cheap exploration",       "model": "provider/fast-model", "thinking": "max" },
+      "medium":   { "description": "Ordinary planning and review",  "model": "provider/reasoning-model", "thinking": "max" },
+      "high":     { "description": "Architecture and risky review", "model": "provider/architecture-model", "thinking": "xhigh" },
+      "research": { "description": "Long-context research",         "model": "provider/long-context-model", "thinking": "max" }
     }
   }
 }
@@ -439,7 +439,82 @@ values with models available in your environment.
 
 A profile is all-or-nothing: both `model` and `thinking` are required, and either
 may be the literal `"inherit"` to keep the parent's. `description` is optional and
-defaults to the key; it is what the host reads when choosing between tiers.
+defaults to the key; it is what the host reads when choosing between Agent tiers.
+
+### One catalogue, including for workflows
+
+A managed `pi-workflows` call arrives naming a key from this same `agentTiers`
+catalogue. There is no second tier catalogue and no second resolver: this package
+still owns every model, every thinking level, and the only `resolveAgentTier()`.
+
+What a workflow *script* writes is not that key. A script names a **strength** —
+`low`, `medium`, `high`, pi-workflows' own word for how much effort a step
+deserves — and a `strengths` table on that side chooses which of your tiers it
+runs on:
+
+```js
+// in a workflow script
+await agent("summarize this diff", { strength: "low" })
+await agent("design the migration", { strength: "high" })
+```
+
+```jsonc
+// pi-workflows' own settings, edited with `/workflows strength`
+{ "strengths": { "low": "cheap-search", "high": "deep" } }
+```
+
+The indirection exists so that re-pricing workflow work does not re-price
+everything else. Workflow fan-outs ask for cheap work by the dozen, and so does
+the `Explore` agent and every spawn that names no tier of its own; if the
+workflow side reached your catalogue directly, making a 26-agent fan-out
+affordable would mean editing the tier all of them share. Pointing a strength
+elsewhere leaves your tiers alone.
+
+Nothing about that reaches this side. By the time a request arrives it carries
+one tier key, and this package cannot tell a mapped call apart from a spawn that
+named the key itself. Nor is it a second *policy*: a `strengths` value is a key
+in this catalogue and never carries a `model` or `thinking` of its own — that is
+the line between it and the retired `workflow.tiers` key, which did.
+
+The tier is resolved by the same `resolveAgentTier()` path an ordinary Agent
+spawn uses — same precedence, same model lookup, same thinking clamping, same
+availability checks, same immutable resolution snapshot. A tier the host does not
+define is rejected before dispatch, naming the tiers it does define.
+
+Model and thinking are deliberately absent from the managed request. A tier is
+the only model policy a workflow can express, so there is no second selector that
+could silently win or be silently ignored.
+
+Fresh installs ship an effort ladder: `low`, `medium`, `high`. Every shipped
+profile inherits its model, so a new machine gets a working vocabulary without
+this package ever choosing a vendor for you. Those names are also what
+pi-workflows' shipped default table maps its strengths onto — identity, and only
+where you define the name — so a stock machine runs workflows at the strengths
+their scripts asked for. Rename or remove them and that default simply yields
+nothing: a managed call that names no tier uses the agent's own tier, then
+`agentTiers.defaultTier`, and finally falls back to `medium`.
+
+`medium` inherits its model, so on an unconfigured machine that fallback runs on
+the parent session's model. What it buys is a call with a *named* policy, a
+durable resolution snapshot and a scope check — not cheaper work. If you want
+managed work to run somewhere cheaper, set a `defaultTier` whose profile pins a
+model.
+
+That last fallback is scoped to managed calls. It is deliberately **not** the
+catalogue's `defaultTier`: a shipped default that applied to every ordinary spawn
+would silence [`defaultModel`](#defaultmodel) and pin a thinking level on machines
+that configured neither.
+
+So `Default tier` has three settings, not two, and the menu offers all three:
+
+| Setting | Ordinary spawn | Managed workflow call |
+| --- | --- | --- |
+| a tier name | that tier | that tier |
+| `unset` | `defaultModel`, then the parent session | the shipped `medium` |
+| `none` | `defaultModel`, then the parent session | rejected |
+
+`none` is a policy statement, recorded as `noDefaultTier`; `unset` is the absence
+of one. Deleting the profiles has the same effect on managed calls as `none`.
 
 ### How the host discovers tiers
 
@@ -450,7 +525,7 @@ remember. It sees:
 ```
 Available agent tiers:
 
-- small: Fast, cheap exploration
+- low: Fast, cheap exploration
   model: provider/fast-model
   thinking: max
 ...
@@ -477,6 +552,11 @@ frontmatter are read only to warn that they are stale, and the built-in agents
 pin nothing either. With nothing configured at all, a subagent runs on the
 parent session's model.
 
+A **managed workflow call** cannot take steps 4 and 5 — it has no parent session
+to inherit from — so it gets one extra step between 3 and the end: the shipped
+`medium` fallback. That step exists only for callers that would otherwise fail
+closed, which is why it does not displace `defaultModel` for everyone else.
+
 ### `defaultModel`
 
 Steps 1–3 are a catalogue; step 4 is one line. Set it when the whole point is
@@ -523,7 +603,7 @@ the global file defines. The menu writes the merged catalogue back to the
 project file, so deleting one of several works, but deleting the last one — or
 clearing a `defaultTier` that only global sets — leaves no `agentTiers` key
 behind, and the global value is inherited again on the next start. Remove it
-from `~/.pi/agent/subagents.json` instead. The same is true of `workflow.tiers`.
+from `~/.pi/agent/subagents.json` instead.
 
 ### Refusals
 
@@ -549,22 +629,13 @@ level nobody chose for that pair. A project profile that fails validation blocks
 its global namesake rather than reviving it, and `defaultTier` is a simple
 project-over-global override.
 
-### Not the same as `workflow.tiers`
-
-`pi-workflows` has its own tiers, and they stay fixed at `small | medium | large`.
-That vocabulary is part of the cross-package protocol: it lets a workflow
-definition be validated at parse time and stay portable between machines, neither
-of which survives arbitrary names. The two systems share no fields — a spawn
-records `agentTier`/`agentTierSnapshot` or `tier`/`tierSnapshot`, never one
-standing in for the other.
-
 ### Migrating from `model:`/`thinking:`
 
-Define the profiles once, then replace each agent's `model:`/`thinking:` with
-`tier: <name>`. Files that still carry the old fields load and run — the fields
-are ignored, with a warning naming the file — so the migration can be done one
-agent at a time. Until an agent names a tier it uses `defaultTier`, or the
-parent's model when none is set.
+Define the Agent-tier profiles once, then replace each agent's `model:`/`thinking:`
+with `tier: <name>`. Files that still carry the old fields load and run — the
+fields are ignored, with a warning naming the file — so the migration can be done
+one agent at a time. Until an agent names a tier it uses `agentTiers.defaultTier`,
+then `defaultModel`, or the parent's model when none is set.
 
 Programmatic callers and the legacy RPC may still pass `model`/`thinking`
 directly. That is the escape hatch for code, not a way to configure an agent.
@@ -579,11 +650,11 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 | Model source | Out-of-scope behavior |
 |---|---|
-| Caller-supplied via `Agent({ model: "..." })` | Hard error returned to the orchestrator, listing allowed models |
+| Caller-supplied programmatic `model` (only when no Agent tier applies) | Hard error returned to the orchestrator, listing allowed models |
 | Pinned in agent frontmatter | Warning toast + the pinned model runs (frontmatter is authoritative) |
 | Parent-inherited (neither set) | Warning toast + parent's model runs |
 
-**Design:** `scopeModels` is a guardrail against the orchestrator picking unexpected models at runtime, not a hard policy against user-level config. The "frontmatter is authoritative" guarantee from v0.5.1 still holds for `model:` — caller params can't override frontmatter, and frontmatter pins run even when out of scope (with a visible warning).
+**Design:** `scopeModels` is a guardrail against unexpected runtime model choices, not a hard policy against user-level config. An applicable Agent tier is checked after its single final resolution; compatibility model inputs are checked only on the no-tier path and cannot override a tier.
 
 **Nested spawns** ([nested subagents](#nested-subagents)) apply the same table against the parent's config root. The hard-error case is identical; the warning cases proceed silently, since a subagent session has no UI to toast to.
 
@@ -600,26 +671,9 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 **Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, nested depth `2`, join mode `smart`, defaults enabled).
 
-**Workflow tiers** (`workflow`) are semantic model-plus-thinking profiles used by `@signalridge/pi-workflows` managed spawns. The wire request carries only `"small"`, `"medium"`, or `"large"`; pi-subagents resolves the configured profile at spawn time and records the immutable resolution snapshot in its managed session journal.
-
-```json
-{
-  "workflow": {
-    "defaultTier": "medium",
-    "tiers": {
-      "small": { "model": "inherit", "thinking": "low" },
-      "medium": { "model": "inherit", "thinking": "medium" },
-      "large": { "model": "provider/architecture-model", "thinking": "max" }
-    }
-  }
-}
-```
-
-Replace the illustrative `provider/architecture-model` value with a model available in your environment.
-
-Profiles are complete `model` + `thinking` tuples. Each field may use `inherit`; a project profile replaces the whole matching global tier entry. Malformed or incomplete entries are retained as durable blocked-tier tombstones and fail closed rather than falling back to a built-in profile or merging field-by-field. An explicit `defaultTier` applies when a workflow task omits its tier. Without a task tier or configured default, the parent model and thinking level are inherited. Agent frontmatter remains authoritative for its explicit `model` and `thinking`; thinking is clamped to the selected model's native supported levels.
+The `workflow` settings key is **retired**; a file that still has one is ignored with a warning naming the key. This file holds no workflow routing of its own: a managed `pi-workflows` call arrives naming a key from `agentTiers`, and which key that is was decided on the pi-workflows side by its own `strengths` table — a table of keys into this catalogue, never a second catalogue and never its own `model`/`thinking`. `agentTiers.defaultTier` replaces what `workflow.defaultTier` used to do. See [One catalogue, including for workflows](#one-catalogue-including-for-workflows).
 
-**Default model** (`defaultModel`, unset): the model a subagent runs when no tier picked one — see [`defaultModel`](#defaultmodel) for where it sits in precedence, why an unresolvable value falls back instead of failing, and how `"inherit"` lets a project cancel a global default. **Default tier** (`agentTiers.defaultTier`, unset) is the tier applied when neither the caller nor the agent names one; the profiles it selects from live under [`agentTiers`](#model-tiers).
+**Default model** (`defaultModel`, unset): the model a non-tiered ordinary subagent runs — see [`defaultModel`](#defaultmodel) for where it sits in precedence, why an unresolvable value falls back instead of failing, and how `"inherit"` lets a project cancel a global default. **Default tier** (`agentTiers.defaultTier`, unset) is the tier applied when neither the caller nor the agent names one; the profiles it selects from live under [`agentTiers`](#model-tiers). It has three settings — a tier name, `unset`, and `none` — which the menu offers separately because the last two behave differently for managed workflow calls; see [Model tiers](#model-tiers) for the table.
 
 **Strict agent files** (`strictAgentFiles`, default `false`): normal startup skips unreadable or malformed agent definitions with a warning that includes the file path. Enable it to fail closed during the first `session_start`, using that session's `ctx.cwd`, with the path in the error instead of silently running a surviving lower-priority override. A failed validation leaves no root manager or RPC responder behind. Reloads after startup remain lenient, so an accidental edit cannot terminate an active session; the setting applies on the next pi session.
 
@@ -676,7 +730,7 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount`, optional `owner` |
 | `subagents:scheduled` | Schedule lifecycle change | `{ type: "added" \| "removed" \| "updated" \| "fired" \| "error", … }` (job/agentId/error fields per type) |
 | `subagents:scheduler_ready` | Scheduler bound to session, enabled jobs armed | `sessionId`, `jobCount` |
-| `subagents:ready` | RPC handlers registered and armed — fired on session start; not emitted in a session that excludes pi-subagents | `version: 3`, `capabilities` (`managedSpawn`, `lifecycleOwner`, `ownedStop`, `ownedQuiescence`, `childContext`, `workflowTiers`) |
+| `subagents:ready` | RPC handlers registered and armed — fired on session start; not emitted in a session that excludes pi-subagents | `version: 4`, `capabilities` (`managedSpawn`, `lifecycleOwner`, `ownedStop`, `ownedQuiescence`, `childContext`, `agentTiers`, `managedPolicy` — all required), `routingPolicy` (Agent-tier catalogue + fingerprint) |
 | `subagents:settings_loaded` | Persisted settings applied at extension init | `settings` (merged global + project) |
 | `subagents:settings_changed` | `/agents` → Settings mutation was applied | `settings`, `persisted` (`boolean` — `false` on write failure) |
 
@@ -702,20 +756,20 @@ pi.events.on("subagents:ready", () => {
 
 ### Ping
 
-Check if the subagents extension is loaded and get the protocol version:
+Check if the subagents extension is loaded and get the protocol version and current routing-policy fingerprint:
 
 ```typescript
 const requestId = crypto.randomUUID();
 const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
   unsub();
-  if (reply.success) console.log("Protocol version:", reply.data.version);
+  if (reply.success) console.log("Protocol version:", reply.data.version, "routing policy:", reply.data.routingPolicy.fingerprint);
 });
 pi.events.emit("subagents:rpc:ping", { requestId });
 ```
 
-### Managed spawn (protocol v3)
+### Managed spawn (protocol v4)
 
-Workflow-owned orchestration uses the additive `subagents:rpc:spawn-managed` channel. Its request may include the core identity fields plus optional `tier`, exact `model`, `thinking`, `toolset`, `excludeTools`, `thread`, and `isolation: "worktree"` hints:
+Workflow-owned orchestration uses the `subagents:rpc:spawn-managed` channel. Its request may include the core identity fields plus an optional Agent `tier`, `toolset`, `excludeTools`, `thread`, and `isolation: "worktree"`. There is no per-call `model` or `thinking` — the wire validator rejects them:
 
 ```json
 {
@@ -724,15 +778,14 @@ Workflow-owned orchestration uses the additive `subagents:rpc:spawn-managed` cha
   "type": "Explore",
   "prompt": "Find the relevant files",
   "description": "Find relevant files",
-  "tier": "small",
-  "model": "provider/model:medium",
+  "tier": "low",
   "excludeTools": ["workflow", "workflow_control"],
   "isolation": "worktree",
   "owner": { "extension": "pi-workflows", "runId": "run-id", "nodeId": "node-id", "attemptId": "run-id/node-id/attempt-1" }
 }
 ```
 
-The manager validates and resolves every hint against its own model scope, agent configuration, queue, tool, session, and worktree policy. `spawnKey` is idempotent within a root manager; the same normalized request returns the existing agent id and a conflicting request is rejected. A named managed `thread` re-enters one sequential session only while its effective model, thinking, toolset, denylist, isolation, and agent policy fingerprint remain unchanged; a policy change or concurrent call is rejected rather than silently reusing the old session. Managed agents use the normal Agent execution path, queue, FleetView, activity, transcript, compaction, and lifecycle events. Only the automatic main-session completion nudge is suppressed for an owner-scoped record. Managed requests must carry an attempt-scoped owner, and `stop-owned`/`quiesce-owned` fail closed when exact node/generation metadata is missing. During branch replacement, timed-out records are detached and late callbacks are suppressed.
+The manager validates and resolves the tier, agent configuration, queue, tool, session, and worktree policy against its own Agent-tier catalogue and model scope. The resolved tier and its snapshot are retained on the managed invocation/tombstone. `spawnKey` is idempotent within a root manager; the same normalized request returns the existing agent id and a conflicting request is rejected. A named managed `thread` re-enters one sequential session only while its effective model, thinking, toolset, denylist, isolation, and agent policy fingerprint remain unchanged — including the model and thinking its tier currently resolves to, so switching the session model interrupts a thread whose tier inherits it; a policy change or concurrent call is rejected rather than silently reusing the old session. Managed agents use the normal Agent execution path, queue, FleetView, activity, transcript, compaction, and lifecycle events. Only the automatic main-session completion nudge is suppressed for an owner-scoped record. Managed requests must carry an attempt-scoped owner, and `stop-owned`/`quiesce-owned` fail closed when exact node/generation metadata is missing. During branch replacement, timed-out records are detached and late callbacks are suppressed.
 
 ### Spawn
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-subagents",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "description": "Signalridge's managed subagent runtime with workflow-owned orchestration RPC.",
   "author": "tintinweb and signalridge contributors",
   "license": "MIT",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@sinclair/typebox": "^0.34.50",
     "croner": "^10.0.1",
-    "@signalridge/pi-subagents-protocol": "^1.3.1",
+    "@signalridge/pi-subagents-protocol": "^1.4.0",
     "@signalridge/pi-ui": "^1.3.0",
     "nanoid": "^5.0.0"
   },