# Upstream Compatibility

This document records the current Pi target and Codex compatibility decisions.

Review date: 2026-07-30.

Re-verified against the installed `@earendil-works/pi-coding-agent` 0.83.0
package on 2026-08-02. The sources are the package `CHANGELOG.md` and
`dist/core/extensions/types.d.ts`.

## Source record

- Pi target: `@earendil-works/pi-coding-agent` 0.83.0.
- Pi release commit: `845d6ff1f6643aba440341cce877ce1c43ebbc39`.
- Codex baseline: `44d76c6a6dd04fa2efc302b906ac8774267a1272`.
- Codex review end: `355d2a802aaad0d5d003b7bba49f25a05bd1db5a`.
- Codex license: Apache License 2.0.
- Pi license: MIT.

`docs/upstream-lock.json` contains the machine-readable source record.

pi-subagents uses public Pi APIs. It does not change Pi or Codex files.

## Pi 0.83.0 decisions

| Change | pi-subagents action |
|---|---|
| Official `ctx.scopedModels` API | Remove the local declaration file. |
| TypeBox 1.3.7 alias removal | Make no change. pi-subagents does not use the removed aliases. |
| Resource metadata preservation | Accept the change through the Pi update. It helps child extension loading. |
| Concurrent Bash cancellation fixes | Accept the fixes through the Pi update. |
| SDK tool callback access | Use file-backed extension loading and composite tool projection. |
| Tool source metadata | Use public `ToolInfo.sourceInfo` to inherit a loaded optional conversion package. |
| AgentHarness design documents | Make no change. Pi does not provide a public AgentHarness implementation. |

### Confirmed against the installed package

The installed 0.83.0 package confirms each decision:

- `CHANGELOG.md` (0.83.0 Breaking Changes) lists the TypeBox 1.3.7 alias
  removal: `Type.Base`, `Type.Awaited`, `Type.Promise`, `Type.AsyncIterator`,
  `Type.Iterator`, `Type.Options`, and `Value.Mutate`.
- `CHANGELOG.md` (0.83.0 Added) exposes the resolved model scope as
  `ctx.scopedModels`.
- `CHANGELOG.md` (0.83.0 Fixed) preserves resource source metadata after
  extension reloads, and aborts every concurrently running bash command on
  cancellation.
- `dist/core/extensions/types.d.ts` declares `ctx.scopedModels` (line 228),
  `ctx.hasPendingMessages()` (line 240), and `ToolInfo.sourceInfo`
  (line 842).
- The installed package types expose no `AgentHarness`, no parent-turn
  metadata, and no remote-step API. The NOT APPLICABLE rows stand.

## Codex decisions

| Commit | Decision |
|---|---|
| `49025589b0` child developer instructions | Add default child instructions with role precedence. |
| `e597169e9a` registry identity consistency | Keep the existing path and ID indexes. They provide this behavior. |
| `af7f6f4d34` activity start times | Keep the existing child progress times. |
| `4f6d06d485` delegated task retention | Keep child history and graph records outside root model context. |
| `9a6668f674` direct input capability | Keep children parent-owned. Reject direct user input. |
| `03edf16f0b` plaintext collaboration | Keep provider-neutral text tool messages. |
| `1def0a8925` parent turn identifiers | Make no change. Pi has no public parent-turn metadata API. |
| `fe01054a28` remote step environments | Make no change. Pi has no public remote step API. Children keep the root directory. |
| `2f19a57704` multi-agent configuration forms | Make no change. pi-subagents uses one JSON configuration form. |

## Parity matrix

`VERIFIED` means automated evidence passes.

`NOT APPLICABLE` means the Codex feature has no equivalent in the public Pi API.

| Area | pi-subagents behavior | Evidence | Status |
|---|---|---|---|
| Coordination tools | Register nine tools by default. Omit `wait_agent` only when its setting is false. | Contract tests and live smoke | VERIFIED |
| Native orchestration | Keep the root user-facing. Give children narrow, independent scopes. | Prompt and integration tests | VERIFIED |
| Built-in roles | Start without parent history. Apply role reasoning and tool limits. Keep each role as a leaf. | Unit and integration tests | VERIFIED |
| Composite tool projection | Map root `exec` tools to local child tools before role restrictions. | Integration tests and cross-provider smoke | VERIFIED |
| Optional Codex conversion | Pass loaded conversion paths and names. Let the package select model tools and prompts. | Unit and integration tests | VERIFIED |
| Child instructions | Use default instructions when a role has none. Give role instructions higher priority. | Unit and integration tests | VERIFIED |
| Authority | Keep approval and scope decisions with the root and user. | Prompt and integration tests | VERIFIED |
| Forking | Support `none`, `all`, and positive integers. Remove tool data from filtered forks. | Unit and integration tests | VERIFIED |
| Messaging | Keep mailbox order. Start idle follow-up work. Steer active work. | Integration tests | VERIFIED |
| Waiting | Wake for mailbox activity, steering, cancellation, or timeout. | Contract, gap, and integration tests | VERIFIED |
| Codex world state | Pi has no equivalent multi-agent world state or sleeping-thread wake. | — | NOT APPLICABLE |
| Trust | Give children the root trust decision. Ignore project pi-subagents config when untrusted. | Integration tests | VERIFIED |
| Headless UI | Keep registrations in RPC, print, and JSON modes. Do not call UI methods. | End-to-end tests and live smoke | VERIFIED |
| Lifecycle | Handle child shutdown. Isolate abort and disposal failures. | Integration tests | VERIFIED |
| Persistence | Store bounded graph and history records. Reload eligible terminal children when used. | Unit and integration tests | VERIFIED |
| Full-report relay | Persist completed answers out of band. Page them with `get_agent_report`. | Unit and integration tests, live proof | VERIFIED |
| Spend budget | Accumulate weighted spend per tree. Remind at thresholds. Stop new turns at exhaustion. | Unit and integration tests | VERIFIED |
| Turn retry | Retry transient prompt failures with capped exponential backoff. | Unit and integration tests | VERIFIED |
| Compaction | Roll up dropped history. Keep the task envelope and a bounded digest. | Unit and integration tests | VERIFIED |
| Time reminders | Deliver bounded current-time reminders at a configured interval. | Integration tests | VERIFIED |
| Sibling context | Inject bounded sibling inventory lines into child instructions. | Unit and integration tests | VERIFIED |
| Lifecycle journal | Append event records. Derive tree metrics. | Unit and integration tests | VERIFIED |
| Error guidance | Add a fixed next-action hint to failed child notices. | Integration tests | VERIFIED |
| Limits | Bound agents, mailboxes, history, output, residency, and active child turns. | Unit and integration tests | VERIFIED |
| UI | Show a read-only picker. Add `/subagents` only when the command is free. | End-to-end tests | VERIFIED |
| Transport | Let Pi manage provider encryption. Pi has no matching custom-tool metadata fields. | — | NOT APPLICABLE |

## Verification

| Check | Result |
|---|---|
| `npm run check` | Passes formatting, lint, types, 196 tests, and package checks. |
| `npm run smoke` | Passes Pi 0.83.0 RPC, print, and JSON loading. |
| `npm run smoke:cross-provider` | Passes DeepSeek parent and child tool projection. |

## Next upstream review

1. Check for a new `@earendil-works/pi-coding-agent` version.
2. Read the Pi changelog and release commit.
3. Find new Codex multi-agent commits after the recorded review end.
4. Compare each applicable change with the parity matrix.
5. Update this document and `docs/upstream-lock.json`.
6. Run `npm run check` and both smoke scripts.
7. Record the new versions, commits, date, and test count.