pi-ptc-subagents 3.4.0 → 5.0.0

package/CHANGELOG.md

@@ -5,6 +5,177 @@ 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.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
+
+- **The `ptc_subagent` call row shows the dispatch, not its argument dump.** The tool had no
+  renderer, so pi fell back to its raw argument serialisation — one enormous
+  `ptc_subagent task="…\\n\\n…"` line of JSON-escaped prose (2026-10-19 field report). It now
+  registers a `renderCall`: collapsed it reads as a heading (agent, foreground/background and
+  read-only flags, and a pinned `model` when one was passed) with one task preview line and
+  `… 还有 N 行`; `ctrl+e` expands `label` / `why` rows and the task block — the first task line
+  plus up to the existing `MAX_LOG_LINES_EXPANDED` continuation lines, so no new cap is
+  introduced. Follows ADR-0013's "no escaped JSON in the call row" rule.
+- **`whyEnabled`, a default-on switch for the dispatch `why` block.** `~/.pi/agent/ptc.json` takes a
+  boolean `whyEnabled`; when it is `false`, a `why` passed to `pi.dispatch` / `ptc_subagent` is
+  dropped instead of delivered, and both the foreground result and the background record say that a
+  suppression happened. **The switch fails on:** a non-boolean value, an unparseable file, or a file
+  that is not a JSON object all leave the feature ON — a broken value must never remove it. A broken
+  _key_ is reported once at `session_start` with the path, the key and the type that arrived; a broken
+  _file_ is already reported by the default-mode reader, so one typo produces one notice. The
+  `why` argument stays on the schema either way, so a running program is never rejected for passing
+  an argument whose value the switch drops. `DispatchResult.whySuppressed` and
+  `TaskRecord.whySuppressed` record **that a reason was withheld, never what it was** — a background
+  dispatch returns a handle rather than a result, so without the record it would have no way at all
+  to say so. See ADR-0043.
+- **`/ptc why on|off`**, a session-scoped override for the switch above. It records one session entry
+  and never writes `ptc.json` — the difference is "about this conversation" against "about every
+  future one". A resumed session restores the last record; a new one starts from the file. Bare
+  `/ptc why` reports the value _and_ which of the two is in force, and an argument that is neither
+  `on` nor `off` warns and changes nothing. See ADR-0043.
+- **A succeeded background task's completion notification now states its report channel.** The
+  `<bg-task-notification>` for a `succeeded` record gains a `<report-channel>` child —
+  `tool`, `prompt-json`, `none` or `opted-out`, the same **total** field ADR-0032 defines —
+  rendered between `<error-message>` and `<output-ref>`. Before this, a model that wanted to
+  know whether a finished child had honoured the report contract had to poll `ptc_task_output`;
+  the push it already receives now answers it, once per finished child. The element is absent from
+  every other event because only a `succeeded` close declares a channel: a running task has not
+  reported _yet_, and a `failed` / `lost` / `canceled` close has no report claim to state
+  (`none` and `opted-out` are claims about a finished child, not the absence of one). See
+  ADR-0022 §7 as amended (2026-10-19).
+
+### Changed
+
+- **BREAKING — a dispatch's `goal` is now `why`.** `pi.dispatch` and `ptc_subagent` took an
+  optional `goal` since 3.4.0; that argument is now `why`, and the child's block is now
+  `<pi-ptc-why>` instead of `<pi-ptc-goal>`. A PTC program that passes `goal` must pass `why`.
+  The block's **wording is unchanged** — it still reads "This goal is context for doing it well" —
+  because that sentence was held constant across ADR-0042's 180 runs and renaming the tag does not
+  re-test the contrast; rewriting the sentence would change what was held still. See ADR-0043.
+  The rename is not cosmetic: in the agent ecosystem `goal` names an objective or a loop, a thing
+  worked toward over time, which is not what this argument holds — the reason one slice was cut out.
+  `background` was the other candidate and was unavailable, because the dispatch schema already
+  carries a `background` argument meaning "detach the child". No compatibility alias is kept: the
+  only consumer is a model reading the live schema each session, and a second name for one value
+  would cost exactly the comprehension this change buys back.
+- **The background-dispatch guide now says which model a dispatched child runs, and that it is
+  not the caller's.** The child is a fresh `pi` subprocess, so its model resolves — first match
+  wins — as the dispatch's `model` argument, then the named agent definition's frontmatter
+  `model:`, then pi's own global default; the calling session's current model (and therefore a
+  provider switched to mid-session) is **not** inherited. Recorded after the 2026-10-19 field
+  report: the parent had switched provider, and the child it dispatched afterwards ran on pi's
+  default provider and hit a 429. No behaviour change — the resolution order is what the code
+  already did, and the guide states it so the failure is also preventable. See the background
+  dispatch guide, `docs/usage/bgdispatch.md`.
+- **The TUI task panel now shows why a background task failed.** The `task-output` panel prints
+  the record's failure reason as an `error: …` line first in the output block — ahead of the
+  preview or the empty-output placeholder — and the `task-list` panel appends one to each
+  `failed` / `lost` row whose record carries an `errorMessage`, so a child that died before
+  writing output stays legible in the panel instead of as an empty preview, without a
+  `ptc_task_output` call. A `lost` record carries the sweep's reason
+  (`session_ended_while_running` / `lost_on_session_restart`) and gets the row too; a
+  `canceled` task carries no reason and does not. Both rows reuse the panel's existing
+  `MAX_ERROR_CHARS` bound (120, first non-blank line), so no new cap or number is added, and
+  neither annotation counts against the panel's row caps — see ADR-0022 §11. A settled
+  failure's empty-output placeholder also stops claiming `(no output yet)`: with a reason on the
+  record it reads `(no output)`, while a page with no recorded reason keeps the `yet` (this
+  payload carries no status to tell a live task from an unlabelled close).
+
+### Fixed
+
+- **A background task that failed with an empty log now says why — on the notification, in
+  `ptc_task_output`, and in the host log.** A 2026-10-19 field report: a child was rate-limited
+  (429) before writing anything, its output log was 0 bytes, the `TaskRecord` carried the reason
+  in `errorMessage`, and the parent agent received only `status="failed"` — it read the empty
+  log as an infrastructure fault and could not act on the real one. Three surfaces now carry the
+  cause. A `<bg-task-notification>` whose record carries an `errorMessage` gains an optional
+  `<error-message>` (head-truncated to at most 1024 code points, an ellipsis marking the cut, and
+  XML-escaped; absent when the record has no such text), so the push that announces the failure
+  states it. `ptc_task_output`
+  renders the reason as an `error=…` line ahead of a failed/lost task's body and exposes the
+  record's `errorMessage` on the codemode projection as `error_message` (and on `details` as
+  `errorMessage`), so the pull after the push reads the same reason. The background pump logs a `logger.warn` with the
+  task id and the failure reason, so the host operator no longer sees only an empty child log. The
+  terminal empty-output fallback also stops saying "yet": a terminal task reads
+  `(no output; task <id> is <status>)`, while `running` / `stopping` keep
+  `(no output yet; …)`. See ADR-0022 §7 as amended (2026-10-19).
+
 ## [3.4.0] - 2026-10-19
 
 ### Added

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
@@ -169,6 +196,12 @@ per row, with the withheld amount stated in-band. A scalar is one line (`→ 47`
 bounds ([ADR-0012](./docs/adr/0012-model-facing-result-text.md)): a compact value under 100
 characters stays on one line, every line caps at 200. Nothing is ever printed as escaped JSON.
 
+The `ptc_subagent` call row follows the same rule: it reads as a heading — agent, state flags, and
+a pinned model when the caller set one — plus one task preview line and a withheld count, and
+`ctrl+e` expands the `label` / `why` rows and the task block (the first task line plus up to
+`MAX_LOG_LINES_EXPANDED` continuation lines). A dispatch's long prose is never dumped as its
+JSON-escaped argument string.
+
 ## Images
 
 An image read _inside_ a program — `await tools.read({ path: "shot.png" })` — is attached to
@@ -186,11 +219,20 @@ and reaches `read` / `bash` / `edit` / `write` / `grep` / `find` / `ls` through
 …) stay directly callable. Turn it off for one session with `/ptc off` (also `/ptc on`, `/ptc`
 for status), permanently with `{ "defaultMode": false }` in `~/.pi/agent/ptc.json`.
 
+A dispatch may also carry the caller's **reason** for the slice: an optional `why` on
+`pi.dispatch` / `ptc_subagent`, which reaches the child as its own `<pi-ptc-why>` block after the
+host's policy block, and never widens the task. It is on by default. Turn it off for one session
+with `/ptc why off` (`/ptc why` reports the current value and whether it came from the session or
+the file), or permanently with `{ "whyEnabled": false }` in `~/.pi/agent/ptc.json`. A value that is
+not a boolean leaves the block **on** and says so at startup — a default-on switch that could turn
+itself off on a typo is the wrong direction. A `why` that was dropped is reported on the dispatch
+result (`whySuppressed`), never silently ([ADR-0043](./docs/adr/0043-a-why-switch-and-a-name.md)).
+
 Which model-facing tools this package registers is **detected, not configured** — there is no
 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;
@@ -291,6 +301,21 @@ interface TaskRecord {
    * tier was asked for, which is the same claim the foreground result's absent field makes.
    */
   readOnlyTier?: ReadOnlyTier;
+  /**
+   * ADR-0043: `true` when the caller passed a `why` and this session's switch dropped it, so the
+   * child's prompt carried no `<pi-ptc-why>` block. Written at SPAWN, alongside `readOnlyTier`,
+   * because it too is a fact about the request rather than about the child's output.
+   *
+   * **The dropped value is deliberately not here.** ADR-0042 declined to persist `why` on the
+   * TaskRecord because the value is a caller-held fact, not a host-measured one. That reasoning
+   * reaches the value and stops at the event: "a suppression happened" is observed by the host and
+   * is the only thing a background caller can otherwise not learn, since a background dispatch
+   * returns a handle and has no result to put it on.
+   *
+   * Absent means no `why` was passed, which is the same claim the foreground
+   * `DispatchResult.whySuppressed`'s absence makes — the two fronts state one fact, not two.
+   */
+  whySuppressed?: true;
   /**
    * Host-observed token usage for this child (ADR-0032's counter, moved to its own carrier).
    * Written on every terminal close for any child the host actually started — independent of
@@ -300,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)
@@ -410,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 {
@@ -477,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
@@ -524,6 +593,23 @@ interface DispatchDeps {
    * can dereference the bytes (BG-07).
    */
   outputStorage?: OutputStorage;
+  /**
+   * ADR-0043: whether the caller may hand the child a `why`. Absent means ON, which is this
+   * package's default and the state ADR-0042's measurement was taken in — so every existing
+   * zero-argument call site keeps the behaviour it had before the switch existed.
+   *
+   * The FILE is read ONCE, at extension load, and carried here rather than consulted per call for
+   * the reason #73 already records for `optInBindings`: a switch read per call would let the third
+   * dispatch of a run see a different answer from the first, with nothing in the transcript
+   * recording that it changed.
+   *
+   * "Read once" is about this file, not about the value being frozen for the session — `/ptc why`
+   * overwrites this exact field mid-session by design (spec D8, ADR-0043), and the `whyConfig`
+   * JSDoc in `index.ts` carries that half. What keeps the two together is that the write is
+   * recorded: `/ptc why` appends a session entry, so a program that saw the value change knows
+   * from the transcript that a user changed it rather than finding it had moved underneath a run.
+   */
+  whyEnabled?: boolean;
 }
 /**
  * ADR-0041: the two read-only tiers. `strict` narrows what the child can be handed;
@@ -710,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;
@@ -819,6 +912,43 @@ interface DefaultModeConfig {
  * on** — the caller should surface the problem rather than silently changing behavior.
  */
 export declare function readDefaultModeConfig(agentDir: string): DefaultModeConfig;
+/** Result of reading the `why` switch, with enough detail to warn about a broken file. */
+interface WhyEnabledConfig {
+  whyEnabled: boolean;
+  source: "file" | "default" | "invalid";
+  error?: string;
+}
+/**
+ * Read `whyEnabled` from the agent-dir config file — ADR-0043's switch for the dispatch caller's
+ * reason.
+ *
+ * The three outcomes are borrowed from {@link readDefaultModeConfig} rather than invented, because
+ * this package already decided what a broken boolean in this file means and a second answer for the
+ * same file would be a second failure vocabulary:
+ *
+ * - Absent file, absent key → **on**. This package is default-on (CONTEXT.md), and ADR-0042's
+ *   measurement is why the block exists at all.
+ * - A non-boolean value, or a file that is not a JSON object, or unparseable JSON → reported as
+ *   `invalid` **and still resolved to on**.
+ *
+ * That last line is the one worth stating plainly: a broken value must never be able to take the
+ * feature away. A switch whose parse failure silently removes a block the user never asked to
+ * remove is worse than one that ignores the typo and says so — the failure here is LOUD (a
+ * `session_start` warning naming the path and the key) and the behaviour is UNCHANGED.
+ *
+ * **A file too broken to parse is not this function's to report**, and an earlier draft got that
+ * wrong in a way `tests/extension.test.ts` caught: this reader raised its own "not valid JSON" and
+ * `readDefaultModeConfig` raised the identical sentence for the same file, so one typo produced
+ * two notices. Two identical warnings train a user to ignore warnings, which defeats the loudness
+ * the previous paragraph is buying. The file's parse belongs to the reader that owns
+ * `defaultMode`; this one reports only what is wrong with the `whyEnabled` KEY, exactly as
+ * `readOptInBindingsConfig` draws the same boundary for `optInBindings`.
+ *
+ * What this key does NOT do: it stays off the model-facing schema either way. The parameter keeps
+ * its place in `DISPATCH_PARAMETERS` so a running program is never rejected for passing an argument
+ * whose value this switch decides to drop.
+ */
+export declare function readWhyEnabledConfig(agentDir: string): WhyEnabledConfig;
 /** Result of reading the opt-in binding config, with enough detail to warn about a broken file. */
 interface OptInBindingsConfig {
   optInBindings: readonly BuiltinBindingName[];
@@ -1597,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
@@ -1736,6 +1874,19 @@ export interface PtcSubagentsOptions {
   codemodeActivation?: CodemodeActivationResolution;
 }
 export default function ptcSubagents(pi: ExtensionAPI, options?: PtcSubagentsOptions): void;
+/**
+ * `customType` for this session's `why` record (`pi.appendEntry`).
+ *
+ * Separate from `PTC_MODE_ENTRY_TYPE` and it has to be: both readers scan the SAME entry list
+ * backwards for their own type, so a shared one would let `/ptc why off` restore as a mode record
+ * on the next `session_start` -- and `/ptc off` restore as a `why` decision. Two entry types, two
+ * independent switches, and neither recoverable as the other.
+ *
+ * Declared here rather than beside `PTC_MODE_ENTRY_TYPE` in `src/mode/ptc-mode.ts` because that
+ * module is PTC MODE's state machine; this switch has nothing to say about the loadout, and
+ * everything it touches lives in this file.
+ */
+export declare const PTC_WHY_ENTRY_TYPE = "ptc-why";
 //#endregion
 export type { Binding, BindingContext, BindingTable, CodemodePresence, CodemodeSwitch, CodemodeSwitchResolution, CodemodeSwitchSource, CreateBuiltinBindingsOptions, DefaultModeConfig, DetectedSurface, LegacySurfaceKey, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, OptInBindingName, OptInBindingsConfig, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
 //# sourceMappingURL=index.d.ts.map