pi-ptc-subagents 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,97 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+(nothing yet)
+
+## [1.5.0] - 2026-10-08
+
+### Added
+
+- **`verify:dist` is now part of the release gate.** `scripts/verify-dist-render.mjs` is the only
+  check that exercises the _built_ artifact, and it ran nowhere: not in CI, not in the publish
+  workflow, not in `prepublishOnly`. A feature in this project's own history passed three review
+  rounds and 696 tests and then failed this script on the release artifact. It now runs on every
+  pull request, in `publish.yml` before the publish step, and in `prepublishOnly`
+  ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §D).
+- **`THIRD_PARTY_NOTICES.md`**, stating what is derived from DeepSeek Harness (MIT, Copyright (c)
+  2026 DeepSeek) and from `pi` (MIT), and shipped inside the npm tarball rather than only on
+  GitHub. The MIT notice is an obligation for the source excerpts in `docs/research/`, not a
+  courtesy.
+- **A dispatched child returns a _child report_ instead of prose alone.** `summary` in the child's
+  own words, `findings` each carrying the independent thing that supports the claim,
+  `files_touched`, and the token usage **the host measured**. The child's prose is kept alongside
+  the report, never replaced by it ([ADR-0032](./docs/adr/0032-child-report.md)).
+- **Two delivery channels, and the result names which one delivered it.** A declared
+  `ptc_child_report` tool (the reliable one) or a fenced JSON block in the child's final text (the
+  fallback, for installs where this package does not load in the child). `reportChannel` is
+  **always** present — `tool`, `prompt-json`, `none` or `opted-out` — because a degradation a
+  caller cannot see is a silent failure, and "ran but did not comply" must not read as "returned
+  nothing".
+- **The report contract is on by default** and an agent opts out with one frontmatter line,
+  `childReport: false`. An opted-out agent reads as `opted-out`, not `none`: nobody was asked is a
+  different claim from having been asked and ignored.
+- **`ptc_subagent` renders the report** where the model reads it, bounded at 20 findings /
+  20 files / 150 characters of evidence per finding, each bound stated in-band when it withholds.
+  This is the first real reader of that tool's declared `structuredContent` — on the `subagents`
+  surface there is no `codemode` to read it.
+
+### Changed
+
+- `src/tools/subagent.ts` gained the OCR rule anchor it never had. It was resolving to the `**`
+  catch-all and being reviewed against the generic floor only.
+- **The repository is public, and `main` is writable only by the maintainer.** Everything else is
+  a pull request that needs CI green and one approving review. Release authority is enforced by a
+  `refs/tags/v*` ruleset plus the npm package's "Require two-factor authentication and disallow
+  tokens" setting, so it no longer depends on where a credential file is kept
+  ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §A–§B).
+- **The next version published from here carries an npm provenance attestation.** Under trusted
+  publishing npm generates it automatically once the source repository is public, with no workflow
+  change — so the `homepage` and `repository` fields that pointed at a private GitHub now resolve,
+  and the missing provenance badge that ADR-0018 §7 recorded as expected is no longer expected.
+- **`node scripts/preview-ptc-render.mjs` requires `PI_ROOT`.** It imported pi's theme from a hard-coded
+  path on one developer's machine, so following the README from anywhere else failed inside a
+  module loader. It now reads the install directory from the environment and, when it is missing or
+  wrong, says so with the commands to find it.
+- **The DSH citations in `docs/research/` point at the public upstream repository** instead of a
+  temporary local extraction, so a reader can follow them. The baseline is tag `dsh-v0.2.0-rc.2`
+  — the release the research actually read. `src/runtime/limits.ts:4` named `0.1.6-alpha.2`; the
+  constants are byte-identical across both tags, so only the version label changed and no behaviour
+  did ([ADR-0031](./docs/adr/0031-open-source-and-publish-authority.md) §C).
+
+## [1.4.0] - 2026-10-03
+
+### Added
+
+- **`/ptc surface off|subagents|full` switches the extension surface without a new session.** The
+  surface was configurable only by hand-editing `~/.pi/agent/ptc.json` and restarting, because it is
+  read once in the extension factory and pi has no way to unregister a tool. The new subcommand
+  writes the key and then performs pi's own `/reload`, which clears pi's extension cache and
+  re-runs every factory — the same path the built-in takes, from inside the extension. A malformed
+  `ptc.json` is reported and left byte-for-byte alone, `defaultMode` in the same file survives, and
+  setting the value that is already there writes nothing and does not reload
+  ([ADR-0030](./docs/adr/0030-surface-switch-reloads.md)).
+
+### Fixed
+
+- **A default pi session no longer starts with no orchestration tool at all.** The detected surface
+  followed two questions — does this pi ship a `codemode` directory, and will pi load it — and on a
+  stock pi 1.0.0 install the answer to both is yes, so the surface resolved to `subagents`. But pi
+  registers `codemode` with `defaultActive: false`: it joins the model's tool list only when a
+  loadout names it, and a session that configured nothing has no such loadout. Since the
+  `subagents` surface deliberately does not register `ptc_run_code`, the result was a session
+  holding `ptc_subagent` and three `ptc_task_*` tools with no way to compose any of them, plus a
+  startup warning on **every** session. The detection now asks a third question — whether `codemode`
+  will actually be in the tool list, read from `--tools` and from `defaultTools` in the project and
+  user settings the way pi resolves them — and `subagents` is chosen only on positive evidence that
+  the model can call the tool. The default on an unconfigured install is now `full`, with no
+  warning. To opt into `subagents`, add `codemode` to `defaultTools` or `--tools`
+  ([ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)).
+- **The "pi does not register codemode" startup notice no longer hard-codes the wrong surface.** With
+  a fifth cell in the table, the detected surface is not always `subagents` in that branch, and the
+  message named `SurfaceModeConfig.detected` — a field populated only when an explicit `surfaceMode`
+  overrode detection, so on the very path the notice fires from it would have printed `undefined`.
+  It reports the surface the session actually built.
+
 ## [1.3.0] - 2026-10-02
 
 ### Fixed

package/README.md

@@ -4,13 +4,21 @@ DSH-style **PTC mode** (Programmable Tool Calling) for [pi](https://pi.dev):
 the model writes a JS/TS program that calls pi's tools from inside a worker,
 and only the program's return value plus its logs come back to the model.
 
+**Source is open.** This repository is public and the source is here — `dist/` on npm is the
+compiled form of what you read below. Contributions go through pull requests: see
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the gate your PR has to pass, and
+[SECURITY.md](./SECURITY.md) before reporting anything. Releases are cut from `main` by the
+maintainer only; if you find something you think needs a release, open an issue and say so.
+
 ## Status
 
-Pre-1.0, but functional: `ptc_run_code` and `ptc_workflow` are registered and run
+Functional and actively used: `ptc_run_code` and `ptc_workflow` are registered and run
 programs through the same tested worker machinery (dispatcher, wire protocol,
 budgets, built-in bindings). The implementation is written clean-room from
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) PTC
-behaviour (tracked as a wayfinder map in this repo's issues).
+behaviour — see [ADR-0002](./docs/adr/0002-source-strategy.md) for how that boundary is
+kept, and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for the attribution that
+follows from it.
 
 ## Install
 
@@ -72,6 +80,23 @@ const [read, scoutA, scoutB] = await Promise.all([
 ]);
 ```
 
+**The child report.** A dispatched child returns more than prose. Under the report contract ([ADR-0032](./docs/adr/0032-child-report.md)) a child hands back a **child report** — a `summary` in its own words, `findings` each carrying the independent thing that supports the claim, the `files_touched` it is sure about, and the token usage **the host measured** (never a number the child made up). The child's prose is kept alongside the report, never replaced by it.
+
+The report travels one of two channels. It prefers a declared `ptc_child_report` tool, whose payload the host reads back as JSON. If that tool is not available to the child, the host still reads a fenced JSON block from its final message. Either way the result **names the channel that delivered it**:
+
+```ts
+const r = await tools["pi.dispatch"]({ agent: "scout", task: "survey the auth code" });
+if (r.reportChannel === "none") {
+  // The child ran and did not comply. r.text is its prose; treat it as unbacked.
+} else {
+  for (const f of r.report?.findings ?? []) console.log(f.what, "←", f.evidence);
+}
+```
+
+`reportChannel` is **always present** — `"tool"`, `"prompt-json"` or `"none"` — because a degradation a caller cannot see is a silent failure, and "ran but did not comply" must not read as "returned nothing". `ptc_subagent` renders the same report into the text the model reads, bounded at 20 findings with the withheld count stated in-band.
+
+The contract is **on by default**. An agent opts out with one line of frontmatter, `childReport: false`, and then its channel reads `"opted-out"` — nobody was asked, which is a different claim from having been asked and ignored.
+
 **Bounded.** Three knobs keep fan-out from running away:
 
 - `PtcConfig.dispatchConcurrency` (default **8**) — hard cap on concurrently in-flight dispatch **in one pi session**. It is one counter, not one per run: foreground `pi.dispatch`, the top-level `ptc_subagent` front, and live background children all spend it, and a background child holds its slot for its whole lifetime. The N+1th concurrent call resolves immediately with `{ status: "rejected", errorMessage: "dispatch concurrency limit reached" }` instead of queuing or spawning — so a call over the cap is not made to wait for a slot to come back.
@@ -201,8 +226,12 @@ the session. The mode's rationale and rejected alternatives are in [ADR-0010](./
 ```
 
 **Choosing the surface.** `defaultMode` decides whether the session _enters_ PTC mode; `surfaceMode`
-decides which model-facing tools this package registers at all. It is read once, at startup, so a
-surface change needs a new session ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)):
+decides which model-facing tools this package registers at all ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)):
+
+```
+/ptc surface              # report the current surface and where it came from
+/ptc surface subagents    # write the key and reload so it applies now
+```
 
 ```jsonc
 // ~/.pi/agent/ptc.json
@@ -214,31 +243,60 @@ surface change needs a new session ([ADR-0025](./docs/adr/0025-extension-surface
   doing the orchestration; warns at startup when `codemode` is not in the active tool set.
 - `full` — today's set: `ptc_run_code` / `ptc_workflow` plus the three `ptc_task_*` tools.
 
-**The default is detected, and it is not `full` everywhere.** With no `surfaceMode` key, the surface
-follows two questions, not one ([ADR-0026](./docs/adr/0026-surface-default-is-detected.md),
-[ADR-0027](./docs/adr/0027-codemode-switch-decides-surface.md)):
-
-| does this pi ship `codemode`? | will pi load it?                               | surface     |
-| ----------------------------- | ---------------------------------------------- | ----------- |
-| yes                           | yes (default, or `+builtin:codemode`)          | `subagents` |
-| yes                           | no (`-builtin:codemode`, or `--no-extensions`) | `full`      |
-| no                            | —                                              | `full`      |
+The command exists because the alternative is editing JSON by hand and starting a new session: the
+surface is read once in the extension factory and pi has no way to unregister a tool, so a change
+cannot apply in place. `/ptc surface` writes the key and then performs pi's own `/reload`, which
+re-runs every extension factory ([ADR-0030](./docs/adr/0030-surface-switch-reloads.md)). Two things
+it will not do silently: a malformed `ptc.json` is reported and left exactly as it was, and an
+unchanged value does not reload — a reload replaces every extension instance in the session, so
+retyping the value you already have costs you in-flight state for nothing. Switching to
+`subagents` or `off` also ends a running PTC mode, which the command says before it does it.
+
+**The default is detected, and it follows three questions, not one**
+([ADR-0026](./docs/adr/0026-surface-default-is-detected.md),
+[ADR-0027](./docs/adr/0027-codemode-switch-decides-surface.md),
+[ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)). With no `surfaceMode` key:
+
+| does this pi ship `codemode`? | will pi load it?                               | can the model call it?                        | surface     |
+| ----------------------------- | ---------------------------------------------- | --------------------------------------------- | ----------- |
+| yes                           | yes (default, or `+builtin:codemode`)          | yes (`--tools …,codemode`, or `defaultTools`) | `subagents` |
+| yes                           | yes (default, or `+builtin:codemode`)          | no — **the default on a stock install**       | `full`      |
+| yes                           | no (`-builtin:codemode`, or `--no-extensions`) | —                                             | `full`      |
+| no                            | —                                              | —                                             | `full`      |
+
+The third column is the one that decides most sessions, and it is why the default is `full` on a pi
+that has never been configured. pi ships `codemode` and loads it by default, but registers it
+**inactive** (`defaultActive: false`) — it joins the model's tool list only when a loadout names it.
+Handing orchestration to a tool the model cannot call is the failure this avoids, so `subagents` is
+chosen only on positive evidence.
 
 Setting the key always wins. A probe that cannot answer falls back to `full` — the safe direction,
 since `subagents` as a failure mode would take away the orchestration tool the session was relying
 on.
 
-> Upgrading onto pi 0.99.1 or newer without setting the key moves you to `subagents`. `codemode`
-> ships **inactive** (`defaultActive: false`), so until you add it to your tool list you get a
-> subagent front with no orchestrator, and the startup warning says so. If you would rather keep
-> today's tools, set `{ "surfaceMode": "full" }`.
+> **To use the `subagents` surface, put `codemode` in your tool list.** Without that you get
+> `ptc_run_code` / `ptc_workflow` and no startup warning, which is the correct answer for a session
+> that never asked for delegation:
+>
+> ```jsonc
+> // ~/.pi/agent/settings.json
+> { "defaultTools": ["read", "bash", "edit", "write", "+codemode"] }
+> ```
+>
+> or per launch, `pi --tools read,bash,edit,write,codemode`. A list made only of modifiers starts
+> from pi's four defaults, so `{ "defaultTools": ["+codemode"] }` means the same thing. If you would
+> rather pin the surface regardless of what pi is doing, set `{ "surfaceMode": "subagents" }` —
+> and note that pinning it does not activate `codemode`, so a pinned `subagents` on a session that
+> never configured it still warns, by design ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)
+> decision 4).
 
 > Turning pi's `codemode` **off** — `"extensions": ["-builtin:codemode"]`, or launching with
 > `--no-extensions` — brings the PTC surfaces back on its own. Before ADR-0027 it did not: the
 > detection asked only whether the extension directory exists, so a pi told not to load it still
 > counted as an orchestrator and you got `ptc_subagent` with nothing to compose with. The switch is
 > read from the same three places pi reads it — the command line, `<cwd>/.pi/settings.json`, and
-> `<agentDir>/settings.json` — in the same order.
+> `<agentDir>/settings.json` — in the same order, and the activation probe reads the first two plus
+> `--tools`.
 
 No file, or a value outside that set, falls back to the detected default and says so at startup
 rather than half-applying: which tools exist is not something to change on a guess.
@@ -246,13 +304,13 @@ rather than half-applying: which tools exist is not something to change on a gue
 **A detection you cannot see is the failure this design has**, so the result is reported. With no
 `surfaceMode` key, the outcome is issued through the TUI notification channel at session start —
 how the probe came out and which surface the default therefore is — but only when the probe could
-not answer. A pi that ships `codemode` and is detected as `subagents` is the expected case and says
-nothing. A second notice is issued when the probe and pi's own tool registry disagree, which is the
-case the probe structurally cannot see: it walks the filesystem, so under `--exclude-tools codemode`
-it answers `present` for a tool this session does not have (and the mirror: a restructured `dist`
-answers `not-found` for one pi plainly registers). A third notice covers ADR-0027: a settings file
-that could not be read, and an explicit `surfaceMode` that disagrees with the table — the pinned
-value still wins, and the notice only says so. What is **not**
+not answer. A pi that ships `codemode`, loads it, and has it in the tool list is the expected case
+and says nothing. A second notice is issued when the probe and pi's own tool registry disagree, which
+is the case the probe structurally cannot see: it walks the filesystem, so under
+`--exclude-tools codemode` it answers `present` for a tool this session does not have (and the
+mirror: a restructured `dist` answers `not-found` for one pi plainly registers). A third notice
+covers ADR-0027: a settings file that could not be read, and an explicit `surfaceMode` that
+disagrees with the table — the pinned value still wins, and the notice only says so. What is **not**
 established is that either line actually paints in a real pi TUI: a pty capture at review time
 showed neither the notice nor a control marker, and a TUI quits on stdin EOF before a toast
 renders, so that is an unmeasured end to end rather than a broken one. No test in this repository
@@ -305,7 +363,8 @@ pnpm run test:ui      # vp test --ui (local browser UI; not for CI)
 pnpm exec vp test --run tests/render-ptc.test.ts  # renderer unit tests only
 pnpm run build        # vp pack + declaration emit
 pnpm run verify:dist  # exercise renderCall/renderResult through the built dist (no LLM needed)
-node scripts/preview-ptc-render.mjs   # print the rendered rows with real theme colors
+PI_ROOT=<global-node-modules>/@earendil-works/pi-coding-agent \
+  node scripts/preview-ptc-render.mjs   # print the rendered rows with real theme colors
 ```
 
 Tooling: [oxc](https://oxc.rs) — `oxlint` + `oxfmt` (official defaults) — alongside
@@ -313,6 +372,14 @@ Tooling: [oxc](https://oxc.rs) — `oxlint` + `oxfmt` (official defaults) — al
 
 See ADR-0009 for the Vitest adoption decision (reopens ADR-0008's earlier deferment).
 
+## Credits
+
+Built clean-room from the PTC behaviour of
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (MIT,
+Copyright (c) 2026 DeepSeek), read at tag `dsh-v0.2.0-rc.2`, and hosted by
+[pi](https://pi.dev) (`earendil-works/pi`, MIT). Full attribution, and what is
+derived from what, is in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
 ## License
 
-Apache-2.0
+Apache-2.0. See [LICENSE](./LICENSE) and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-Party Notices
+
+`pi-ptc-subagents` is licensed under [Apache-2.0](./LICENSE). It depends on the third-party
+software listed below. Each project remains under its own license; nothing in this file changes
+those terms.
+
+## What is actually derived from what
+
+This project implements DSH's **PTC** (Programmable Tool Calling) mode as a `pi` extension. It is
+a clean-room implementation: see [ADR-0002](docs/adr/0002-source-strategy.md). What the code
+_derives_ from DeepSeek Harness is the **behavioural contract** — the tool surface, the
+`run_code` semantics, the numeric limits — and the **research notes under `docs/research/` cite
+it, line by line, from the public source.** Those notes reproduce substantial portions of DSH's
+source, which is why the attribution below is a licence obligation rather than a courtesy.
+
+| Project                                                                                                            | Licence | Role                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------- |
+| [`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness)                                  | MIT     | Behavioural reference and citation target for the PTC contract. Read at tag **`dsh-v0.2.0-rc.2`**. |
+| [`earendil-works/pi`](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`) | MIT     | The host this extension loads into. Peer dependency, not vendored.                                 |
+
+## DeepSeek Harness
+
+```
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Citations in `docs/research/upstream-20260930/` name paths inside that repository, pinned to
+`dsh-v0.2.0-rc.2`. Upstream also carries its own `THIRD_PARTY_NOTICES.md` for its dependency
+closure; that closure is upstream's concern, and this package depends on the harness only through
+reading it, not through importing it.
+
+## Runtime dependency
+
+| Package                                            | Licence       |
+| -------------------------------------------------- | ------------- |
+| [`minimatch`](https://github.com/isaacs/minimatch) | BlueOak-1.0.0 |
+
+`minimatch` is the only runtime (`dependencies`) entry; everything else is a `devDependency` or a
+`peerDependency` on the host.

package/dist/index.d.ts

@@ -41,6 +41,27 @@ interface ParsedAgentEvent {
     errorMessage?: string;
   };
   message_text?: string;
+  /**
+   * `tool_execution_end` carries the executed tool's name (`pi-agent-core`'s
+   * `ToolExecutionEndEvent`, alongside `toolCallId` and `isError`).
+   */
+  toolName?: string;
+  /** The tool call this event closes; carried through because the wire carries it. */
+  toolCallId?: string;
+  /** Whether that call was treated as an error; a failed call's payload is not a report. */
+  isError?: boolean;
+  /**
+   * The executed tool's full `AgentToolResult`, verbatim. `result.structuredContent` is where a
+   * tool that DECLARES an `outputSchema` puts its machine-readable value (ADR-0032's tool
+   * channel), and this repo already depends on that reaching it for three other tools.
+   *
+   * Typed `unknown` rather than a hand-written mirror of `AgentToolResult`: what arrives is
+   * whatever the child actually wrote, and the one reader of it validates through
+   * `validateChildReport` rather than trusting the shape to have survived the wire.
+   */
+  result?: {
+    structuredContent?: unknown;
+  };
 }
 /**
  * Opaque per-handle state owned by the adapter that produced it. The dispatch code
@@ -111,6 +132,76 @@ interface ChildProcessLifecycle {
   stderr(handle: ChildHandle): Promise<string>;
 }
 //#endregion
+//#region src/runtime/child-report.d.ts
+/**
+ * The child report's types (ADR-0032, `CONTEXT.md` §child report).
+ *
+ * These four declarations used to live in `dispatch.ts` next to the extraction that produces
+ * them. They moved here so the *persisted* `TaskRecord` field (`task-storage.ts`, Layer 1) can
+ * name the shape without a type-only import back up into the dispatch layer — a record that
+ * stores a report has to be able to say what a report is, and the storage layer is below the
+ * dispatcher, not above it. `dispatch.ts` re-exports all four, so every existing import site
+ * (and the report tool's) keeps working unchanged.
+ *
+ * The EXTRACTION stays in `dispatch.ts`. This module owns vocabulary, not parsing.
+ *
+ * #101 added the last two constants here, and the reason is the same one: ADR-0032's "the
+ * contract has exactly one home". The report tool's NAME and the SHAPE it demands are both
+ * needed by two modules that must not know about each other — `dispatch.ts`, which has to put
+ * the tool in the child's argv and read its `structuredContent` back, and the tool declaration
+ * in `src/tools/`, which must not import `dispatch.ts` (that edge has broken this repo's tests
+ * once; see `CHILD_REPORT_MAX_FINDINGS` below for why). Neither can reach the other's module, so
+ * both read the text from here, which imports nothing at all.
+ */
+/** One claim the child makes, with the evidence it rests on. */
+interface ChildReportFinding {
+  what: string;
+  evidence: string;
+}
+/**
+ * Which channel a {@link ChildReport} arrived over (ADR-0032 "The channel is always stated").
+ *
+ * `tool` is the report tool's `structuredContent`, read off `tool_execution_end`; `prompt-json`
+ * is the fenced block in the child's final assistant message, which is the channel that still
+ * works when this package does not load in the child at all; `none` means the contract was on and
+ * the child did not comply.
+ *
+ * `opted-out` is the fourth value, added by ticket #102, and it is the one that keeps `none`
+ * honest. Without it, an agent that opted out and a child that ignored the contract would produce
+ * the same string, and ADR-0032 has already said which of those two is a defect — so a reader
+ * could not tell "nobody asked" from "it did not comply". A field whose value cannot distinguish
+ * those is the silent failure `docs/testing-constraints.md` #3 forbids.
+ */
+type ChildReportChannel = "tool" | "prompt-json" | "none" | "opted-out";
+/**
+ * What the child DECLARES. `files_touched` is snake_case on purpose: this object is produced by a
+ * model emitting JSON, and renaming it on the way in would mean the wire text and the type
+ * disagree. The child's prose is returned alongside it, never replaced by it.
+ */
+interface ChildReportPayload {
+  summary: string;
+  findings: ChildReportFinding[];
+  files_touched: string[];
+}
+/**
+ * The child report as the host stamps it: the payload the child declared, plus `usage`, which is
+ * what the host OBSERVED and read off the child's own `message_end` usage blocks.
+ *
+ * `usage` is deliberately not on {@link ChildReportPayload}. A model cannot know its token
+ * count, so a child-declared `usage` would be a fabricated number that happened to look like a
+ * measurement — `docs/testing-constraints.md` #4 requires the expected value to point at an
+ * independent source, and the host's counter is that source. Anything the child puts under
+ * `usage` is read and discarded.
+ */
+interface ChildReport extends ChildReportPayload {
+  usage: {
+    input: number;
+    output: number;
+    cost: number;
+    turns: number;
+  };
+}
+//#endregion
 //#region src/runtime/task-storage.d.ts
 /**
  * The 6-state TaskRecord status (ADR-0022 §2). `queued` is deliberately absent in v1
@@ -167,6 +258,26 @@ interface TaskRecord {
   ownerPid?: number;
   /** ADR-0023: wall-clock ms when the owning runtime instance started; pairs with `ownerPid`. */
   ownerBootMs?: number;
+  /**
+   * ADR-0032: the child report a background child produced, read off its final message by the
+   * same extraction the foreground loop runs and stamped onto the record at the terminal
+   * transition — so `ptc_task_output` can hand a background child back with the same shape a
+   * foreground `DispatchResult` carries.
+   *
+   * **Both report fields are ABSENT unless the record reached `succeeded`** (the registry writes
+   * them; see `resolve-exit` in `task-registry.ts`). Absent is a claim in its own right: a child
+   * that is still running has not reported *yet*, and a child that failed did not report at all.
+   * Neither is the same claim as "ran and complied with nothing to say", which is what a
+   * `succeeded` record carrying `reportChannel: "none"` states.
+   */
+  report?: ChildReport;
+  /**
+   * ADR-0032 "The channel is always stated": which channel delivered `report`, and — when there
+   * is no `report` — the explicit marker that the child ignored the contract. Written with
+   * `report` and only on a `succeeded` record, so `reportChannel === undefined` never has to be
+   * read as "none".
+   */
+  reportChannel?: ChildReportChannel;
 }
 /**
  * Per-subscriber cursor for one TaskRecord (ADR-0022 §5). Cursor is per-subscriber (not per-task)
@@ -273,6 +384,8 @@ type TaskCommand = {
   outputBytes?: number;
   outputPreview?: string;
   childError?: string;
+  report?: ChildReport;
+  reportChannel: ChildReportChannel;
 };
 /** Outcome of one successful command: the persisted record, emitted events, and cursor. */
 interface TransitionResult {
@@ -556,7 +669,7 @@ export declare function readDefaultModeConfig(agentDir: string): DefaultModeConf
  * orchestration question back to pi, `subagents` keeps only the subagent face and lets pi's
  * `codemode` orchestrate, `full` keeps today's set.
  */
-declare const SURFACE_MODES: readonly ["off", "subagents", "full"];
+export declare const SURFACE_MODES: readonly ["off", "subagents", "full"];
 type SurfaceMode = (typeof SURFACE_MODES)[number];
 /**
  * Whether the pi that launched us will actually LOAD its `codemode` extension.
@@ -602,6 +715,38 @@ export declare function resolveCodemodeSwitch(argv: readonly string[], projectSe
  * `join(this.cwd, CONFIG_DIR_NAME)` and `this.agentDir`.
  */
 export declare function readCodemodeSwitch(agentDir: string, cwd: string, argv?: readonly string[]): CodemodeSwitchResolution;
+/**
+ * Whether `codemode` will be CALLABLE, as a third question distinct from whether pi ships the
+ * directory (ADR-0026) and whether it will load the extension (ADR-0027).
+ *
+ * - `"active"` — a loadout names it, so the model can call it.
+ * - `"inactive"` — nothing names it, which on a real install is the DEFAULT: pi registers
+ *   `codemode` with `defaultActive: false` and activates it only when a loadout says so.
+ *
+ * `"inactive"` is what every failure of this probe on the positive side resolves to, and that is
+ * the design rather than a fallback: `subagents` is chosen only on positive evidence that the tool
+ * is callable. See ADR-0029, "The bound that makes the weaker guarantee sufficient".
+ */
+type CodemodeActivation = "active" | "inactive";
+/** How the answer was decided, so a test can tell a configured answer from pi's default. */
+type CodemodeActivationSource = "cli" | "project" | "user" | "default" | "invalid";
+/** The answer plus enough provenance to explain it in a notice. */
+interface CodemodeActivationResolution {
+  activation: CodemodeActivation;
+  source: CodemodeActivationSource;
+  /** Set when a settings file could not be read as a JSON object; the answer still resolves. */
+  error?: string;
+}
+/**
+ * Resolve whether `codemode` will be in the model's tool list, in the order pi resolves the
+ * loadout: the command-line allowlist, then the merged `defaultTools`, then pi's own default.
+ *
+ * The last of those is the load-bearing one and is what makes absence of evidence mean
+ * `inactive`: pi registers `codemode` inactive, so a session that configured nothing does not get
+ * it, and delegating orchestration to a tool the model cannot call is the failure this exists to
+ * prevent.
+ */
+export declare function resolveCodemodeActivation(argv: readonly string[], projectSettings: unknown, userSettings: unknown): CodemodeActivationResolution;
 /**
  * Whether an explicit `surfaceMode` disagrees with what the table above decided.
  *
@@ -656,6 +801,11 @@ interface SurfaceModeConfig {
    * {@link codemode}: an explicit key short-circuits the probe, so there is nothing to report.
    */
   codemodeSwitch?: CodemodeSwitchResolution;
+  /**
+   * Whether `codemode` will be in the model's tool list (ADR-0029), the third axis of the
+   * detected table. Absent for the same reason as {@link codemodeSwitch}.
+   */
+  codemodeActivation?: CodemodeActivationResolution;
   /**
    * What the four-case table decided, carried even when an explicit key overrode it — that
    * difference is exactly what {@link surfaceModeConflict} reports on.
@@ -679,7 +829,36 @@ interface SurfaceModeConfig {
  * short-circuits, where the user paid a `realpathSync` plus up to three `statSync` and two
  * settings reads to set one line of JSON and get a constant.
  */
-export declare function readSurfaceModeConfig(agentDir: string, presence?: CodemodePresence, codemodeSwitch?: CodemodeSwitchResolution, cwd?: string): SurfaceModeConfig;
+export declare function readSurfaceModeConfig(agentDir: string, presence?: CodemodePresence, codemodeSwitch?: CodemodeSwitchResolution, codemodeActivation?: CodemodeActivationResolution, cwd?: string): SurfaceModeConfig;
+/** Outcome of writing `surfaceMode` for `/ptc surface`. */
+type SurfaceModeWrite = {
+  ok: true;
+  path: string;
+  /** The value already in the file, or `undefined` when there was none. */
+  previous: SurfaceMode | undefined;
+  /** False when the file already said this, in which case NOTHING was written. */
+  changed: boolean;
+} | {
+  ok: false;
+  path: string;
+  error: string;
+};
+/**
+ * Write one `surfaceMode` key into the agent-dir config, preserving every other key.
+ *
+ * Three rules, each of which is a way a naive rewrite goes wrong:
+ *
+ * - **A malformed file is never overwritten.** An unparseable `ptc.json` is a file the user may
+ *   be mid-edit on, and this command is not a licence to replace it with something valid that
+ *   drops whatever was in it. The read side already reports that shape rather than acting on it
+ *   ({@link readSurfaceModeConfig}), and the write side has to agree.
+ * - **Other keys survive.** `defaultMode` lives in the same file (ADR-0010), and a command that
+ *   wrote `{"surfaceMode": …}` wholesale would silently reset the user's mode preference.
+ * - **An unchanged value writes nothing.** `/ptc surface full` on a session already at `full`
+ *   should not touch the file's mtime, and — more to the point — should not trigger the reload
+ *   that would follow, since a reload replaces every extension instance for no reason.
+ */
+export declare function setSurfaceMode(agentDir: string, value: unknown): SurfaceModeWrite;
 /** Why the mode declined to turn on. Surfaced in the entry notification / debug logs. */
 type ModeBlockReason = "not-tui" | "config-off" | "tools-unavailable" | "restricted-session";
 /** Either the loadout to apply, or the reason the mode stayed off. */
@@ -791,10 +970,32 @@ export declare function buildPtcSkillsSection(skills: readonly Skill[], format?:
 /**
  * PTC run limits and spawn-time hardening, in one frozen `DEFAULT_CONFIG`.
  *
- * The numbers are DSH's (`dsh-v0.1.6-alpha.2`, `@deepseek-ai/dsh-ptc-runtime-node`)
- * carried over verbatim — see ADR-0003 (output budget), ADR-0004 (pending calls) and
- * ADR-0005 (execution boundary, F1–F4). Tests assert against these constants rather
- * than repeating the literals, so a future re-sync only has to change this file.
+ * The numbers are DSH's (`dsh-v0.2.0-rc.2`, `@deepseek-ai/dsh-ptc-runtime-node`,
+ * `NodePtcRuntime.Config` defaults) carried over verbatim — see ADR-0003 (output budget),
+ * ADR-0004 (pending calls) and ADR-0005 (execution boundary, F1–F4). Tests assert against
+ * these constants rather than repeating the literals, so a future re-sync only has to change
+ * this file.
+ *
+ * The baseline was `dsh-v0.1.6-alpha.2` until 2026-10-03. That tag was never the source of
+ * these numbers — the research the values came from read a `0.2.0-rc.2` checkout, and the
+ * values are byte-identical in both tags (verified field by field: 120000 / 600000 /
+ * 67108864 / 134217728 / 128 / 3000, in `packages/ptc-runtime/ptc-runtime-node/src/index.ts`).
+ * So the correction is to the version label only; no constant changed. The prior label was
+ * wrong for a different reason worth keeping in mind: it was read off this comment rather
+ * than off the research, and `docs/research/ptc-upstream-parity-audit-20260930.md` had
+ * already recorded the mismatch (and that this file's self-description was the stale side).
+ *
+ * **These limits match a generation of the upstream that upstream has since deprecated.**
+ * `dsh-v0.0.x` through `v0.1.6-alpha.2` ran a PTC program on `worker_threads` inside the host
+ * process; DSH superseded that on 2026-09-11 and moved Node PTC into a separate process in
+ * `v0.1.7-rc.1`, which also renamed the packages into the `ptc-runtime` family with no legacy
+ * aliases. The numeric defaults did not change across that move — which is why they still match
+ * — but the *shape* around them did, and this file configures the superseded shape (ADR-0005's
+ * worker boundary, not a process boundary). So "the numbers are DSH's" is true of two versions
+ * and describes an architecture upstream no longer recommends. Upstream's own README warns that
+ * there will be compatibility-breaking changes; the parity audit's recommendations 1-3 (upgrade
+ * pi, compare against its built-in `codemode`, and re-base this project's position) are the open
+ * work, and none of them is a comment fix.
  *
  * Deliberately absent:
  * - `syncTimeoutMs` / `maxConcurrentAgents` / `maxTotalAgents` — workflow-engine caps