# The pi-chimera ↔ pi-subagents compat contract

This document is the shared contract between the two extensions that came out
of the Workstream 2 split. Both sides must stay standalone and must never
import the other package.

## Background

Before the split, one extension (`pi-chimera`) contained both the multi-agent
coordination machinery and the Codex-compatibility patch. After the split:

- **pi-subagents** holds the multi-agent coordination machinery (control
  plane, `spawn_agent` … `chimera_stats`, budgets, compaction, roles,
  persistence, talk-while-they-work routing).
- **pi-chimera** (name kept) holds only the Codex-compatibility patch: it
  discovers the optional `@howaboua/pi-codex-conversion` package and reports
  the metadata that describes what would be projected into child sessions.

## The capability

The compat extension's value is realized when the multi-agent extension is
also loaded: child sessions can inherit the conversion package's tools. The
handoff is a **documented metadata shape**, computed independently by both
sides from Pi's own tool registry:

```ts
interface InheritedExtensionMetadata {
  extensionPaths: string[];      // source file paths of contributing extensions
  inheritedToolNames: string[];  // tool names from the conversion package
}
```

`collectInheritedExtensionMetadata(allTools, activeToolNames, ownExtensionPath)`
(`extension-inheritance.ts`, identical in both repos) derives it from
`pi.getAllTools()` / `pi.getActiveTools()` (`ToolInfo.sourceInfo`):

- A tool belongs to the conversion package iff `sourceInfo.origin ===
  "package"` AND its source is `npm:@howaboua/pi-codex-conversion`
  (optionally `@<version>`) OR a local path whose `baseDir/package.json` has
  that exact name.
- Conversion tools contribute even when inactive; other extensions
  contribute only when active in the session.
- Tools whose resolved source path equals the caller's own extension file
  are skipped; synthetic `<…>` paths are skipped.

## Why duplication instead of an import

Pi 0.83.0 exposes no cross-extension API: an extension cannot import another
extension's code, call another extension's tools, or subscribe to another
extension's events. The only shared surface is the tool registry
(`pi.getAllTools()`), which both sides already read. Duplicating the tiny
pure contract module (≈90 lines, no dependencies) in both repos is therefore
the cleanest mechanism; the spec explicitly allows it when no better
mechanism exists. The module has no behavior beyond deriving metadata from
the registry, so the two copies cannot drift in observable behavior as long
as both repos keep this document in sync.

## Behavior matrix (must hold; encoded in tests)

| Loaded | Expected |
| --- | --- |
| pi-subagents alone | Full multi-agent behavior; no compat features; no errors. |
| pi-subagents + pi-chimera (compat), no conversion package | Identical to above; compat is inert. |
| pi-subagents + pi-chimera (compat) + `@howaboua/pi-codex-conversion` | Conversion tools are discovered and taken advantage of in child sessions (inherited tool names / extension paths / composite exec projection). |
| conversion package alone (no compat) | Nothing changes; no errors. |

## Verification surfaces

- **pi-chimera** exposes `codex_conversion_metadata` (tool) and
  `/codex-compat` (command) for the metadata; its unit + integration tests
  cover npm-source discovery, local-package-manifest discovery, and the
  inert-without-package behavior.
- **pi-subagents** computes the same metadata in its root bridge and session
  factory; its tests cover conversion tool projection into child sessions
  (`test/fixtures/fake-codex-package/`) and the inert rows of the matrix.