pi-ptc-subagents 1.5.1 → 2.0.0

package/CHANGELOG.md

@@ -5,9 +5,152 @@ 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).
 
-## [Unreleased]
+## [2.0.0] - 2026-10-10
 
-(nothing yet)
+### Added
+
+- **`ptc_run_code` and `ptc_workflow` reach the line where pi's `codemode` orchestrates.** A
+  session on the `subagents` surface used to hold `ptc_subagent` and the lifecycle face with no
+  program behind them: pi's `codemode` was composing tool calls, and the one capability its
+  QuickJS sandbox cannot provide — spawning a process — was unreachable, because `pi.dispatch`,
+  background tasks and the frozen six-name environment all live inside the PTC worker. Both tools
+  are now registered there at `codemode` reach, which makes them **callable from a `codemode`
+  script without being declared to the model**: `AgentSession._isDeclarable` admits `direct` and
+  `model-only` only, so the request pi sends still carries exactly one orchestrator and it is
+  pi's. Verified end to end on a real pi 1.1.0 session — a `codemode` script enumerates all six
+  `ptc_*` tools in `ALL_TOOLS` and successfully calls `await tools.ptc_run_code({ code: … })`,
+  while the payload carries only the subagent face
+  ([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
+  `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 /
+  0.99.1 / 0.99.2 / 1.0.0 / 1.0.4 / 1.1.0.
+
+  **Naming either tool in `--tools` or `defaultTools` overrides this.** A tool named there is
+  recorded in pi's `toolsAdded`, which the prompt projection filters only against `hidden` and
+  never against `codemode` — so it is declared to the model regardless of its exposure. That is
+  a user's explicit choice and is left alone; it is recorded here because the exposure field does
+  not survive it.
+
+### Changed
+
+- **Surface detection asks pi for the loadout instead of reconstructing it.** The third question —
+  will `codemode` be **active**, i.e. callable by the model — used to be answered by parsing
+  `--tools` / `--exclude-tools` / `--no-tools` / `--no-builtin-tools` out of `process.argv`,
+  merging `defaultTools` across the user-scope and project-scope settings files, and replaying pi's
+  precedence over the result. That is deleted. At `session_start` — the first moment pi's runtime is
+  bound — `getActiveTools()` answers directly, and pi has already applied both the command line and
+  its project-trust decision to what it returns. Registration moves to the same event, where pi
+  adds a tool from it and refreshes its own registry; the command-line reader, the `defaultTools`
+  merge, the precedence replay and the differential test that held them honest all go with it
+  ([ADR-0035](./docs/adr/0035-ask-pi-for-the-loadout.md)).
+
+  **What this fixes.** A project's `defaultTools` was read off disk with no trust check, while pi
+  drops project settings for any project it has not been told to trust. An untrusted project could
+  therefore name `codemode` and put the session on the `subagents` surface — whose
+  `ptc_run_code` and `ptc_workflow` are registered at `codemode` reach, so with no `codemode`
+  running they are reachable from nowhere (#131). A trusted project that configures `codemode` that
+  way keeps the `subagents` surface, exactly as before.
+
+  **What does not change.** The MCP auto-enable evidence stays a file-side read, because pi
+  activates `codemode` from inside its own `session_start` handler and extension order is not ours
+  to choose — measured across pi 0.86.1 → 1.1.0, a read from ours is too early to see it, and the
+  existing cross-check catches it when it lands. The **codemode switch** axis also stays as it is;
+  it may also be collapsible into the live registry, but that loses the distinction between "not
+  shipped" and "not loaded", and it is a separate decision. Behaviour is otherwise unchanged on
+  every pi this package supports, verified from 0.86.1 upward under both trust decisions.
+
+- **BREAKING: the `surfaceMode` setting is removed, and the surface is detected only.** Which
+  model-facing tools this package registers is now a pure function of what pi is — three probes
+  (does this pi ship `codemode`, will pi load it, can the model call it), with `full` as the
+  fallback for every case a probe cannot answer
+  ([ADR-0034](./docs/adr/0034-surface-is-detected-not-set.md)).
+
+  **What is gone:**
+
+  - the `surfaceMode` key in `~/.pi/agent/ptc.json` (`off` / `subagents` / `full`);
+  - the `off` value — a session that wants none of this package's tools no longer has a way to say
+    so here;
+  - the `/ptc surface [off|subagents|full]` subcommand. **`/ptc off` is unaffected** — it turns PTC
+    _mode_ off, which was never the same thing as the extension surface;
+  - the `surfaceModeConflict` notice about a pinned value disagreeing with detection.
+
+  **Migrating: use pi, not this package.** Run `pi config` and disable this package's extensions
+  there — measured on pi 1.1.0 against this package's own `dist/index.js`, a `packages` entry whose
+  `extensions` is `[]` or `["!dist/index.js"]` is not loaded at all, while `["+dist/index.js"]` and
+  an omitted key are. This is strictly better than any value of a key this package reads, because
+  pi honours it **without loading the extension**: none of this package runs, rather than running
+  and then deciding to register nothing. In a project-level `.pi/settings.json` write
+  `["!dist/index.js"]` rather than `[]` — pi resolves the two scopes with two different functions
+  (`package-manager.js:1850`), where an empty project delta means "no change".
+
+  **Expect one warning on upgrade if you had the key set.** A `ptc.json` carrying `surfaceMode` is
+  reported at session start and the key is **not** honoured — deliberately, including for `"off"`,
+  which is why this package comes back after being switched off. The warning names the file, quotes
+  the value, and points at `pi config`; deleting the key silences it.
+
+- **ADR-0025 decision 3 is amended.** `subagents` does register the programming pair now. What
+  the decision protected — the model being offered one orchestration surface, not two — is
+  unchanged and is now enforced by exposure rather than by an absent tool. `CONTEXT.md`'s
+  _orchestration surface_ and _subagent surface_ entries and the README's surface list say so
+  too.
+
+- **The `codemode` activation probe now reads every CLI flag that can remove the tool.** It reads
+  `--exclude-tools` / `-xt` and `--no-tools` / `-nt` in addition to `--tools` / `-t`, and it applies
+  them in pi's own order: `-t` decides the list and beats `-nt`, while `-xt` vetoes whatever list
+  won. That last one was a real misreading — pi builds the active set as
+  `(tools ?? configured).filter(name => !excluded.has(name))` (`sdk.js:148`), so **exclusion beats
+  inclusion**, and `-t codemode -xt codemode` was previously read as `active`. The direction was the
+  harmful one: under `subagents`, `ptc_run_code` / `ptc_workflow` are at `codemode` reach, so an
+  orchestrator believed to be present but absent is an orchestrator nobody can call.
+  `--no-builtin-tools` is deliberately still not read: it maps to `noTools: "builtin"` and
+  `codemode` is not one of pi's built-in tools, so reading it would be a guess about a flag that
+  cannot move it.
+
+[2.0.0]: https://github.com/a1121611810/pi-ptc-subagents/compare/v1.6.0...v2.0.0
+
+## [1.6.0] - 2026-10-08
+
+### Fixed
+
+- **On pi 1.0, a session with MCP servers was offered two orchestration tools at once.** pi's MCP
+  extension activates pi's own `codemode` tool by itself — MCP tools default to `codemode`
+  exposure so that they are reachable only from scripts — and it does that with a
+  `pi.setActiveTools` call that no settings file records. This package's surface detection
+  ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)) asked whether `codemode` would
+  be _active_ by mirroring pi's loadout resolution alone ([ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)),
+  so on exactly the sessions pi 1.0 is built around it answered _not active_, registered
+  `ptc_run_code` + `ptc_workflow` as well, and handed the model two ways to compose tools. Detection
+  now reads pi's MCP configuration (`<agentDir>/mcp.json`, then `<cwd>/.pi/mcp.json`) as a second
+  evidence source and unions the two, so those sessions resolve `subagents`: `codemode` for
+  orchestration, `ptc_subagent` and the task lifecycle for fan-out.
+  [ADR-0033](./docs/adr/0033-mcp-auto-enable-evidence.md) records the mirror, what it deliberately
+  does not mirror, and the one under-report path that stays open (a server registered through
+  `pi.registerMcpServer()`, which no file records — the drift notice below is what covers it).
+
+### Added
+
+- **A session start warning for an active `codemode` the probes did not predict.** Once per
+  session, and only on a detected surface: if nothing in `settings.json` or a readable `mcp.json`
+  said codemode would be active, the surface defaulted to `full`, and pi's real tool loadout
+  contains `codemode` anyway, the session is now told it is carrying two orchestration surfaces and
+  which setting picks one. Checked at session start and again on the first turn, because
+  pi's MCP extension may activate codemode after this package's own `session_start` runs. It is
+  `TUI`-only, like every other notice in this package.
+- **A named report for an `mcp.json` this package could not read.** A file that is absent is
+  silent, matching pi; a file that exists and cannot be parsed or read is named at session start
+  with its path, and when both files are broken both are named in the one line.
+
+### Changed
+
+- **`CONTEXT.md` gains a `codemode activation` entry** defining the question surface detection asks
+  and its two evidence classes, so "is codemode active" no longer has to be reconstructed from an
+  ADR.
+- ADR-0029 carries an amendment: its under-reporting bound still holds, but the premise it rested
+  on — that the loadout is the only way pi activates codemode — did not.
 
 ## [1.5.1] - 2026-10-08
 

package/README.md

@@ -225,37 +225,40 @@ the session. The mode's rationale and rejected alternatives are in [ADR-0010](./
 { "defaultMode": false }
 ```
 
-**Choosing the surface.** `defaultMode` decides whether the session _enters_ PTC mode; `surfaceMode`
-decides which model-facing tools this package registers at all ([ADR-0025](./docs/adr/0025-extension-surface-is-a-setting.md)):
+**Choosing the surface.** `defaultMode` decides whether the session _enters_ PTC mode. 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)):
 
-```
-/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
-{ "surfaceMode": "subagents" }
-```
-
-- `off` — a stock pi session: no tool, no `/ptc` command, no briefing.
 - `subagents` — `ptc_subagent` plus the three `ptc_task_*` tools, with pi's own `codemode`
-  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 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**
+  doing the orchestration; warns at startup when `codemode` is not in the active tool set and
+  `ptc_run_code` is not declared to the model either (which on a pi below 0.99.0 it is, since
+  `exposure` does not exist there and the pair falls back to being model-visible).
+  `ptc_run_code` / `ptc_workflow` are registered here too, but at `codemode` reach: a `codemode`
+  script can call them, and the model is not shown them. That is what puts `pi.dispatch` and
+  background tasks underneath `codemode`, whose sandbox cannot spawn a process itself.
+- `full` — the rest: `ptc_run_code` / `ptc_workflow` plus the three `ptc_task_*` tools. Also the
+  answer to every "the probe could not tell" case.
+
+**To keep this package out of your sessions, use pi, not this package.** Run `pi config` and
+disable this package's extensions there. Measured on pi 1.1.0 against this package's own
+`dist/index.js`: a `packages` entry whose `extensions` is `[]` or `["!dist/index.js"]` is not
+loaded at all, while `["+dist/index.js"]` and an omitted key are. pi does this **without loading
+the extension**, which no value of a key this package reads could achieve — reading the key
+requires having run the code that reads it.
+
+> In the **project-level** `.pi/settings.json`, write `"extensions": ["!dist/index.js"]` rather than
+> `"extensions": []`. The two settings files are resolved by two different functions in pi
+> (`package-manager.js:1850`): the personal-level path reads `[]` as "load nothing", the
+> project-level path reads it as an empty delta, which means "no change".
+
+**If you had `surfaceMode` in `ptc.json`, it is no longer read** — including `"off"`, so upgrading
+brings this package back. At session start you get one `warning` naming the file and pointing here.
+Delete the key to silence it.
+
+**The surface 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:
+[ADR-0029](./docs/adr/0029-surface-follows-codemode-activation.md)):
 
 | does this pi ship `codemode`? | will pi load it?                               | can the model call it?                        | surface     |
 | ----------------------------- | ---------------------------------------------- | --------------------------------------------- | ----------- |
@@ -264,15 +267,15 @@ retyping the value you already have costs you in-flight state for nothing. Switc
 | 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
+The third column is the one that decides most sessions, and it is why the answer 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.
+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. There is no key
+that overrides this, by design ([ADR-0034](./docs/adr/0034-surface-is-detected-not-set.md)).
 
 > **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
@@ -284,54 +287,45 @@ on.
 > ```
 >
 > 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).
+> from pi's four defaults, so `{ "defaultTools": ["+codemode"] }` means the same thing.
 
 > 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, 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.
-
-**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`, 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
-observes a notice through a real TUI. If you are relying on the notice rather than on your own
-`surfaceMode` key, verify it once.
+> `<agentDir>/settings.json` — in the same order. The activation probe does **not** read the
+> settings at all: it asks pi for its own tool loadout at session start, by which time pi has
+> already applied the command line _and_ its project-trust decision. That matters for a project
+> you have not approved — its `defaultTools` is not evidence of anything, because pi is not
+> reading it either ([ADR-0035](./docs/adr/0035-ask-pi-for-the-loadout.md)).
+
+**A detection you cannot see is the failure this design has**, so the result is reported. The
+outcome is issued through the TUI notification channel at session start — how the probe came out
+and which surface therefore is — but only when the probe could 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. 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 observes a notice through a real TUI.
 
 **On a `--print` session, none of it prints.** `ui.notify` is the TUI channel; measured across
 three `--print` runs that each emit one of these notices, stdout and stderr received **0 bytes**
 each. That makes this page the only channel on which a `--print` user learns why they got the
-surface they got — ADR-0025's decision-4 warning shares the gap, and there the answer is the same
-one line of JSON: set `surfaceMode` yourself and the detection no longer matters.
+surface they got.
 
 **Where it does not run.** Print / JSON / RPC sessions are left exactly as launched, and so is a
 session started with an explicit tool restriction (`--tools`, `--exclude-tools`,
 `--no-builtin-tools`, `--no-extensions`) — the extension does not override what you asked for.
 `--no-extensions` does, however, change the **detected surface**: pi's own `codemode` is a built-in
-extension, so turning extensions off means it will not load, and ADR-0027's table resolves the
-default to `full` — you keep `ptc_run_code` / `ptc_workflow` rather than a `ptc_subagent` with
-nothing to compose with. If you would rather pin the surface regardless, set `"surfaceMode"` in
-`ptc.json`. If another extension changes the tool set while the mode is on, the mode yields and
-tells you.
+extension, so turning extensions off means it will not load, and ADR-0027's table resolves to
+`full` — you keep `ptc_run_code` / `ptc_workflow` rather than a `ptc_subagent` with
+nothing to compose with. If another extension changes the tool set while the mode is on, the mode
+yields and tells you.
 
 **The important consequence:** in a TUI session, bindings come from the loadout recorded _before_
 the mode narrowed it. That is what keeps `tools.read(…)` working — and it is why a `--tools`