pi-ptc-subagents 4.0.0 → 5.0.1

package/CHANGELOG.md

@@ -5,6 +5,116 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.1] - 2026-10-20
+
+### Changed
+
+- **pi 1.3.0 is now measured, not merely claimed.** The package declares
+  `@earendil-works/pi-coding-agent: ">=0.86.0"`, so it has always _claimed_ to work on every pi
+  release in that range — but 1.3.0, published on 2026-10-19, had never been measured. The
+  differential table's measured versions stopped at 1.2.0 and the compatibility matrix's version
+  list did not name it. pi 1.3.0 was installed on its own and the forty codemode-switch cases were
+  driven through **its own** `DefaultPackageManager.resolve()`: it answered identically to 1.2.0 on
+  all forty, and the static capability probe answered ✓ on all sixteen capability points. The
+  1.3.0 column is that measurement, not an inference from 1.2.0 being older. A user on pi 1.3.0
+  now has a version whose behaviour this package has actually observed rather than assumed.
+- **The test toolchain moves to vitest 5, and the compatibility matrix can measure the version the
+  repository currently pins.** `vitest` 4.1.11 → 5.0.5, `@vitest/coverage-v8` 4.1.11 → 5.0.5,
+  `vite-plus` 0.3.3 → 1.3.0, `oxfmt` 0.70.0 → 0.73.0, `oxlint` 1.85.0 → 1.89.0, `@types/node`
+  22.20.4 → 26.6.5. The coverage provider and the test runner have to move together —
+  `@vitest/coverage-v8@5.0.5` declares `vitest: 5.0.5` as a peer, and the mismatched pair is what
+  produced 79 unhandled rejections (one per test file) in the upgrade's own CI. Separately,
+  `scripts/pi-compat-matrix.mjs` decided "this devDependency entry was not found" by asking
+  whether **replacing the version changed the text** — and replacing `1.3.0` with `1.3.0` does
+  not change the text, so the matrix could not measure the version the repository currently pins.
+  It asks whether the pattern matched now, and a test that _runs_ the function pins that.
+- **The toolchain bump reformats 26 markdown files.** oxfmt 0.73 changed list-continuation
+  indentation and thematic-break fences. No prose changed. The files it touched carry a single
+  unpaired `---` rather than a YAML frontmatter block, so the site's frontmatter stripping never
+  matched them and does not match `***` either; the three files that do carry real frontmatter are
+  untouched.
+
+### Fixed
+
+- **Nothing in the published package's behaviour changed.** The runtime code, the tool
+  descriptions, the argument and result shapes and the declared peer range are all as 5.0.0
+  shipped them; this release carries development-side and documentation-side work only.
+
+## [5.0.0] - 2026-10-19
+
+### Added
+
+- **A dispatch reports the model its child actually ran.** The model used to be resolved inside the
+  child and never came back: neither `pi.dispatch`'s `DispatchResult` nor a background
+  `TaskRecord` said which provider or model served the call, so a wrong-model delegation could
+  only be inferred from a failure after the fact. Both now carry an optional observed-model pair —
+  observed by the host from the child's own assistant turns (last turn wins), not taken from the
+  request — and the model-facing surfaces state the same fact as a `model: provider/id` line on
+  `ptc_subagent` and `ptc_task_output` and as a `model=` fact in a refusal. A transcript that
+  carries only a model id reports the id alone; the absence of both means no observed assistant turn
+  named the pair — no turn, a supported pi that does not report it, or an old record — not "the
+  model is unknown". A background record gains the pair at the same terminal close that writes
+  `usage`, so a failed or canceled close that named a model still states it. The pair is named
+  `observedProvider` / `observedModel` (ADR-0045): the result's `model` input is the requested
+  model, and two different facts no longer share a name. Records written before the rename are
+  still read (the field rename itself is breaking for program-visible result shapes — see the
+  rename entry under Changed). The rendered value is stripped of ANSI escape sequences and
+  control characters and head-capped at 200 characters before it enters model-facing text,
+  because the pair is untrusted child wire data. See
+  ADR-0044, ADR-0016 §"The child's model", and ADR-0022 §3 as amended.
+- **The `ptc_subagent` call row states the model a generalist dispatch will inherit.** When the
+  call names no model and no agent (a generalist child, where a definition cannot pin the tier),
+  the request row says `model=inherit` and its expanded view names the provider/id the caller's
+  session is on; a named agent gets no such claim, and a pinned `model` is stated as before. This
+  is a request fact captured at the call's first render, so a later model switch does not change
+  an already-rendered row — and it is not the observed model, which still appears only after the
+  child ran. ADR-0044.
+
+### Changed
+
+- **BREAKING — the observed-model fields are named `observedProvider` / `observedModel`.**
+  `DispatchResult.provider` / `model` and `TaskRecord.provider` / `model` carried the observed
+  model, while the input's `model` is the requested model; the shared name made two different
+  facts look comparable. The output fields are renamed, the input keeps its name, the child wire
+  and the model-facing `model:` text are unchanged, and a record written before the rename is
+  normalized on read so its observation is not lost. No aliases: the old result keys are removed,
+  which is why this is breaking for program-visible result shapes. See ADR-0045.
+- **BREAKING — a dispatch that names no model now runs on the caller session's current model, not
+  pi's global default.** `pi.dispatch` and `ptc_subagent` resolve the child's model first match
+  wins: the dispatch's `model` argument, then the agent definition's frontmatter `model:`, then
+  the calling session's **current** model, then pi's configured default. A session that switched
+  provider or model mid-conversation now carries that switch into its next dispatched child — the
+  background-dispatch guide previously said the opposite, and that statement is what this changes.
+  Resolution is a snapshot at spawn: a model switched after the child starts does not change it, a
+  nested dispatch inherits the child's own session model, and re-running the dispatch is how a
+  caller picks up a new model. Tiers 1–2 are unchanged, so pinning the model at the call site or in
+  the definition is the explicit opt-out; no config key and no `model: "inherit"` sentinel is
+  added. A direct library caller with no context model, an older pi, or a session started without a
+  model all fall through to pi's default exactly as before — the session read is structural, so
+  the declared 0.86.0 floor gains no new pi type dependency. See ADR-0044 for the decision and its
+  rejected alternatives.
+
+### Fixed
+
+- **A failed foreground dispatch no longer loses the child's own failure.** The child is a pi
+  subprocess: a rate limit or a model error can make it exit 0 after writing
+  `stopReason: "error"` and an `errorMessage` on its assistant turn. The foreground loop
+  discarded that text and reported the generic `dispatch produced no final text`, while the
+  background registry already recorded the child's reason (issue #70's rule). The close decision now
+  returns the child's reported error verbatim, using the background registry's rule — the child's
+  own error outranks the exit-code and truncation inference — with cancellation still first:
+  cancelled, then exit-0-with-text (fulfilled), then the child's error, then exit-0-without-text,
+  then truncation. It logs one warning on that newly diagnosed path only. `stderr` is no longer
+  described as guaranteed; `errorMessage` is the structured failure channel. This is
+  foreground/background parity: one verdict and one sentence for one failure. See ADR-0044
+  Decision 3 and ADR-0016 §Decision 3.
+- **`ptc_subagent refused the call: undefined` is gone.** A rejected dispatch without an
+  `errorMessage` used to render the literal string `undefined`, telling the model nothing the
+  dispatcher knew. The refusal now states the cause plus bounded facts the result already carries —
+  whether a child ran or the harness declined to start, the exit code, turns, report channel, and
+  the observed model when there is one — tail-bounded to 800 characters so a provider's actionable
+  status code survives the cut. See ADR-0044 Decision 3.
+
 ## [4.0.0] - 2026-10-19
 
 ### Added
@@ -443,7 +553,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md) §3 as amended).
 
   **A pi older than 0.99.0 is unaffected.** `ToolExposure` does not exist there — `grep -r
-exposure` over `pi-coding-agent@0.86.1`'s `dist/` returns nothing, and so does
+  exposure` over `pi-coding-agent@0.86.1`'s `dist/` returns nothing, and so does
   `AgentSession._getCallableTools` — so the field is ignored and the tools are declared to the
   model, which is correct: such a pi ships no `codemode`, resolves to `full` anyway, and has
   nothing that could call a `codemode`-reach tool. Measured across 0.86.1 / 0.87.1 / 0.99.0 /
@@ -1055,7 +1165,7 @@ exposure` over `pi-coding-agent@0.86.1`'s `dist/` returns nothing, and so does
   immediately instead of queueing.** The dispatcher used to read `maxParallelSubCalls`
   (default 10) and FIFO-queue the overflow; per ADR-0016 §2 the N+1th concurrent
   `pi.dispatch` now resolves at once with `{ status: "rejected", errorMessage:
-"dispatch concurrency limit reached" }`. The cap applies to `pi.dispatch` only and
+  "dispatch concurrency limit reached" }`. The cap applies to `pi.dispatch` only and
   has its own counter; builtin binding fan-out keeps DSH's `maxParallelSubCalls` (10)
   FIFO-queueing semantics (ADR-0004), so in-flight builtin calls never consume
   dispatch slots.

package/README.md

@@ -79,11 +79,12 @@ const result = await tools["pi.dispatch"]({
 // result.status: "fulfilled" | "rejected"  (the binding never throws)
 // result.text:   final assistant text
 // result.usage:  { input, output, cacheRead, cacheWrite, cost, turns }
+// result.observedProvider?, result.observedModel?: the provider/model the child actually ran
 // result.exitCode, result.durationMs, result.stderr?, result.errorMessage?
 ```
 
 **Fan out in parallel** with the rest of PTC's tools — dispatch is a binding, not a
-model-visible lifecycle tool, so the dispatcher handles concurrency the same way it does for
+model-facing lifecycle tool, so the dispatcher handles concurrency the same way it does for
 any other tool call:
 
 ```ts
@@ -116,6 +117,32 @@ at 20 findings with the withheld count stated in-band.
 - `signal` — when the parent run is cancelled, every in-flight child gets `SIGTERM` then
   `SIGKILL` after a 5-second grace window.
 
+### The child's model
+
+A dispatched child is a fresh `pi` subprocess and resolves its own model, first match wins:
+
+1. the dispatch's `model` argument;
+2. the named agent definition's frontmatter `model:`;
+3. **the caller session's current model** — read from the pi session that spawns the child;
+4. pi's configured default.
+
+Tier 3 is the behaviour change of [ADR-0044](./docs/adr/0044-a-dispatch-inherits-the-session-model.md):
+a session that switched provider or model mid-conversation carries that switch into the children it
+dispatches, instead of silently running them on pi's global default. Resolution happens once, at
+spawn — a model switched afterwards does not change a child that is already running, and a nested
+dispatch inherits the child's own session model. Pin the model at the call site or in the agent
+definition to opt out; there is no config key for it, and a direct library caller (or a pi that
+exposes no session model) falls back to pi's default exactly as before.
+
+The result says which model the child actually ran: `observedProvider` / `observedModel` on a foreground
+`DispatchResult`, the same optional pair on a background task record (which `ptc_task_output`
+renders as a line), and a `model: provider/id` line in `ptc_subagent`'s text. Absence means no
+observed assistant turn named the pair — no turn, a supported pi that does not report it, or an
+old record — never "unknown model". When the child reported its own failure, a
+rejected dispatch now states that error verbatim as `errorMessage` instead of the generic
+`dispatch produced no final text`, so the foreground failure path matches the background one. Full
+guide: [`docs/usage/bgdispatch.md`](./docs/usage/bgdispatch.md#which-model-the-child-runs).
+
 ### Background dispatch
 
 Foreground `pi.dispatch` blocks the program until the child exits. Pass `background: true` to
@@ -205,7 +232,7 @@ Which model-facing tools this package registers is **detected, not configured**
 setting for it ([ADR-0034](./docs/adr/0034-surface-is-detected-not-set.md)). The short version:
 a pi whose `codemode` is loaded _and_ callable by the model gets the `subagents` surface
 (`ptc_subagent` on top; the program pair underneath at `codemode` reach); every other pi gets
-`full` (`ptc_run_code` / `ptc_workflow` model-visible). To use the `subagents` surface, put
+`full` (`ptc_run_code` / `ptc_workflow` model-facing). To use the `subagents` surface, put
 `codemode` in your tool list (`pi --tools read,bash,edit,write,codemode`, or `"defaultTools":
 ["read", "bash", "edit", "write", "+codemode"]`). To keep this package out of your sessions
 entirely, run `pi config` and disable its extensions there.

package/dist/index.d.ts

@@ -37,6 +37,14 @@ interface ParsedAgentEvent {
       };
     };
     model?: string;
+    /**
+     * Provider that served this assistant turn. pi >= 1.0.0 puts the resolved provider on the
+     * assistant message, so a host can report which model actually ran the child (dispatches
+     * otherwise run on pi's configured default, which the caller never sees). Optional and
+     * structurally read -- the 0.86.0 floor's type surface may not declare it, and an absent
+     * field must mean "not observed" rather than a parse failure.
+     */
+    provider?: string;
     stopReason?: string;
     errorMessage?: string;
   };
@@ -218,11 +226,13 @@ interface TaskSpawnSource {
  * Session-level row tracking the lifecycle of one background child. 20 pre-ownership fields since
  * the 2026-10-16 #199 amendment (19 ADR-0022 §3 originals — its "21 fields" heading is an
  * authoring miscount — plus `usage`), two optional ADR-0023 owner-identity fields, two ADR-0032
- * report fields and ADR-0041's `readOnlyTier`; 25 today, persisted as-is. Optional fields are
+ * report fields, ADR-0041's `readOnlyTier`, ADR-0043's `whySuppressed` and the host-observed
+ * `observedProvider` / `observedModel` pair (ADR-0045); 28 today, persisted as-is. Optional fields are
  * absent on records still `running` (e.g. `finishedAt` / `exitCode` / `outputRef` are written at
  * transition time, not at spawn) and `ownerPid` / `ownerBootMs` are absent on pre-upgrade
  * legacy records. The `report` / `reportChannel` pair is absent unless the record reached
- * `succeeded` (ADR-0032); `usage` is written on every terminal close once a child started.
+ * `succeeded` (ADR-0032); `usage` and the observed-model pair are written on every terminal
+ * close once a child started.
  */
 interface TaskRecord {
   id: ULID;
@@ -315,6 +325,27 @@ interface TaskRecord {
    * Absent on records written before this field existed, and on children that never started.
    */
   usage?: DispatchUsage;
+  /**
+   * The provider that actually served this child, observed by the pump off the child's assistant
+   * `message_end` events (last turn wins). Persisted at the terminal close, on every outcome the
+   * close can produce -- a failed or canceled child still ran a model, and that is the fact the
+   * model-observability fix exists to state. Named `observedProvider` because the input's `model`
+   * is the requested model, not this one (ADR-0045).
+   *
+   * ABSENT means no assistant turn NAMED a provider -- not "the child ran on an unknown
+   * provider". It covers a child with no observed assistant turn, a supported older pi that
+   * does not report the pair on assistant messages (the wire field arrives with pi 1.0.0; the
+   * declared floor is 0.86.0), and a record written before these fields existed. A background
+   * dispatch that names no model runs on pi's configured default; `ptc_task_output` projects
+   * this pair back so a caller can finally see which default that was.
+   */
+  observedProvider?: string;
+  /**
+   * The model id the child actually ran, observed like {@link observedProvider}. Present even
+   * when `observedProvider` is absent: a transcript may carry a model without a provider, and a
+   * half-observation is still an observation.
+   */
+  observedModel?: string;
 }
 /**
  * Per-subscriber cursor for one TaskRecord (ADR-0022 §5). Cursor is per-subscriber (not per-task)
@@ -425,6 +456,9 @@ type TaskCommand = {
   report?: ChildReport;
   reportChannel: ChildReportChannel;
   usage?: DispatchUsage;
+  /** ADR-0045: the observed model names; a legacy on-disk record is normalized on read. */
+  observedProvider?: string;
+  observedModel?: string;
 };
 /** Outcome of one successful command: the persisted record, emitted events, and cursor. */
 interface TransitionResult {
@@ -492,6 +526,26 @@ interface OutputStorage {
   outputRef(taskId: ULID): string;
 }
 //#endregion
+//#region src/runtime/session-model.d.ts
+/**
+ * The caller session's current model, as a dispatch can learn it.
+ *
+ * ADR-0044: a dispatch that names no model at the call site and whose agent markdown names
+ * none inherits the model the caller's session is currently running. That fact lives on pi's
+ * tool-execution context (`ctx.model`) rather than in this package, so this module is the one
+ * structural reader of it -- kept separate so 0.86.0's type surface (which may not declare the
+ * field) cannot turn the read into a compile error on the declared floor.
+ *
+ * The value is a SNAPSHOT taken when the dispatch starts: a model switch after the spawn does
+ * not retro-change a child that is already running, and a nested dispatch inherits the child's
+ * own context model (which is what the child runs with, not the grandparent's).
+ */
+/** One provider + model id pair, e.g. `deepseek` + `deepseek-flash`. */
+interface SessionModel {
+  readonly provider: string;
+  readonly id: string;
+}
+//#endregion
 //#region src/runtime/dispatch.d.ts
 /**
  * Per-run in-flight `pi.dispatch` counter (ADR-0016 §2 + ADR-0022 §9). The dispatcher's
@@ -742,6 +796,13 @@ interface BindingContext {
    * output storage) so the binding's `dispatch()` call shares them.
    */
   dispatchDeps?: DispatchDeps;
+  /**
+   * ADR-0044: the caller session's current model, read by the host off pi's tool-execution
+   * context. The `pi.dispatch` binding forwards it into the `DispatchContext` so a dispatch
+   * that names no model explicitly inherits the session's. Absent for direct library callers
+   * and for a pi too old to pass `ctx.model`: both keep the pre-ADR-0044 behaviour.
+   */
+  sessionModel?: SessionModel;
 }
 interface Binding {
   readonly name: string;
@@ -1666,6 +1727,14 @@ interface RunPtcProgramOptions {
    * against this run's `dispatchConcurrency` for their whole lifetime.
    */
   dispatchDeps?: DispatchDeps;
+  /**
+   * ADR-0044: the caller session's current model, read by the entrypoint off pi's
+   * tool-execution context. Threaded to every binding call's context so `pi.dispatch` can
+   * inherit it when the call site and the agent markdown both name no model. Absent means
+   * no inheritance -- exactly the pre-ADR-0044 behaviour, which is what every direct library
+   * caller and every pi too old to pass `ctx.model` gets.
+   */
+  sessionModel?: SessionModel;
   /**
    * Optional worker pool (ADR-0017). Absent = spawn a fresh worker and terminate it
    * at run end (the original cold-start path). Present = the dispatcher acquires a