@tranhoangnguyen0310/pi-flow-external 2.0.0-external.0 → 2.1.0-external.0

package/AGENTS.md

@@ -2,18 +2,18 @@
 
 ## pi-flow external contract
 
-This fork changes the original pi-flow contract: `Agent` is not a generic Pi subagent launcher. It delegates only to external Claude Code, Codex CLI, and Antigravity harnesses.
+This fork changes the original pi-flow contract: `Agent` is not a generic Pi subagent launcher. It delegates only to external Claude Code, Codex CLI, and Antigravity harnesses, plus named Pi harness configurations (below) — in-process, per-model configs registered by the user, not a fourth CLI.
 
-- Ordinary driver tools: `Agent`, read-only `external_help`, `external_runs`, and optional `workflow`. `pi_flow_profile_create` is active only inside `/external profile create`.
+- Ordinary driver tools: `Agent`, read-only `external_help`, `external_runs`, and optional `workflow`. `pi_flow_profile_create` and `pi_flow_harness_create` are active only inside `/external profile create`.
 - User operations use `/external`; `/pi-flow-profile create` is a temporary deprecated alias.
-- Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`. Profile backend/model/thinking metadata remains in `subagents/*.md`. A trusted project may override `defaultHarness` via `.pi/pi-flow-external/settings.json` (that key only, read-only to the extension); explicit call harness > project default > global default.
-- Every `Agent` call requires `description`, `prompt`, and either `role` with optional `harness` (`agy`, `claude`, or `codex`) or the legacy exact-profile `subagent_type`. The selectors cannot be combined. Without `harness`, use the global `defaultHarness` setting (initially `agy`).
-- Valid profiles come from `~/.pi/agent/subagents/*.md` and set `backend: claude`, `backend: codex`, or `backend: agy`. Use matching names such as `claude-*`, `codex-*`, or `agy-*`; the assisted creator enforces that convention.
-- A default roster ships with the extension and seeds once on session start: five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker, one storage profile per backend (18 files, but six advertised roles). Seeding never overwrites existing files and respects later deletions. Roles outside the default roster (such as debugger) are user-created via `/external profile create`.
-- Profiles with `backend: pi` or a missing backend are filtered out and rejected; they belong to Pi's native subagent system and this extension never modifies them.
-- `/external profile clean-up` archives only this extension's own retired default profiles (currently the former `debugger` role) to `subagents/archive/` after user confirmation. Profiles tagged `owner: user` (stamped automatically by `/external profile create`) are the user's property and are never archived, nor are native Pi profiles.
+- Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`. Profile backend/model/thinking metadata remains in `subagents/*.md`. Named Pi harness configurations live in the sibling `$PI_CODING_AGENT_DIR/pi-flow-external/harnesses.json` registry (one shared file, `pi-<label>` keys pinning `model`/`thinking`). Registry writes are atomic per file, but there is no inter-process lock: concurrent writers adding distinct names from separate sessions are last-writer-wins and may drop one update. This is an accepted v1 limitation shared with `settings.json` and `subagents/*.md`, not a bug to re-report. A trusted project may override `defaultHarness` via `.pi/pi-flow-external/settings.json` (that key only, read-only to the extension); explicit call harness > project default > global default. `defaultHarness` may itself name a registered `pi-*` harness.
+- Every `Agent` call requires `description`, `prompt`, and either `role` with optional `harness` (`agy`, `claude`, `codex`, or a registered `pi-*` harness name) or the legacy exact-profile `subagent_type`. The selectors cannot be combined. Without `harness`, use the effective default harness; if that default names a `pi-*` harness that is no longer registered, the call fails with an actionable error rather than silently falling back to `agy`.
+- Valid profiles come from `~/.pi/agent/subagents/*.md` and set `backend: claude`, `backend: codex`, `backend: agy`, or (only when also declaring `harness: <registered pi-* name>`) `backend: pi`. Use matching names such as `claude-*`, `codex-*`, `agy-*`, or `<harness>-*`; the assisted creator enforces that convention.
+- A default roster ships with the extension and seeds once on session start: five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker, one storage profile per CLI backend (18 files, but six advertised roles). Seeding never overwrites existing files and respects later deletions. Roles outside the default roster are user-created via `/external profile create`. Every registered named Pi harness automatically and immediately gets the same six roles too, synthesized in-memory from the identical canonical role source — no per-harness file needed, and no on-disk seeding for pi harnesses.
+- A `backend: pi` profile is external-delegation-eligible only when it also declares `harness: <name>` for a name present in the live `harnesses.json` registry; a bare `backend: pi` profile (no `harness`, or one naming an unregistered config) is filtered out and rejected exactly as before — it belongs to Pi's native subagent system and this extension never modifies it.
+- **Named Pi harness configuration:** a `pi-<label>` entry in `harnesses.json` pinning a `provider/model` id (resolved through Pi's own model registry) and a thinking level (`off|minimal|low|medium|high|xhigh`, always persisted explicitly). It runs in-process via Pi's own SDK, not as a spawned CLI. A pi child loads no project/user extensions, skills, prompt templates, or themes — its entire tool surface is the SDK's own builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` where a tier's default allow-list adds them), curated but never claimed to be an OS sandbox: `danger` tier `bash` is exactly as exposed as on any external CLI. Retry is disabled per child (in-memory, call-scoped, never touching the user's real settings) to honor this extension's no-auto-retry contract, since the underlying SDK otherwise retries transient provider errors on its own. Pi children cannot resume (no persisted session) and have no enforced budget cap — both are deliberate v1 limitations, not oversights. Custom (non-canonical) roles are still authored per harness via `/external profile create`, not shared across harnesses automatically. Follow-up capability expansion (trusted extensions/MCP/skills, shared custom roles, resumable sessions, real budget controls) is tracked in issue #43.
 - Use Pi's native subagent system for Pi-backed scout/reviewer/planner/worker/oracle work.
-- External backends use their own tools and permission mechanisms. Codex tiers map to its `--sandbox` axis. Claude falls back to `--permission-mode auto` when its effective UID is 0 because Claude refuses bypass mode under root. Execution lanes (implementer, debugger, qa, worker) require shell command authority to inspect repositories and run tests; on Claude (where headless edit auto-denies all Bash commands), execution lanes maintain a danger floor so agents are not artificially handcuffed. Antigravity (`agy`) has no granular headless permission mode — its default sandbox denies even read-only tools — so every agy run is unsandboxed (`--dangerously-skip-permissions`) and `readonly`/`edit` on agy are advisory profile-body instructions, not a boundary. Run them only in trusted repositories and state whether the task is read-only or may edit files.
+- External CLI backends use their own tools and permission mechanisms. Codex tiers map to its `--sandbox` axis. Claude falls back to `--permission-mode auto` when its effective UID is 0 because Claude refuses bypass mode under root. Execution lanes (implementer, qa, worker) require shell command authority to inspect repositories and run tests; on Claude and on pi harnesses (where `edit` tier excludes `bash`), execution lanes maintain a danger floor so agents are not artificially handcuffed. Antigravity (`agy`) has no granular headless permission mode — its default sandbox denies even read-only tools — so every agy run is unsandboxed (`--dangerously-skip-permissions`) and `readonly`/`edit` on agy are advisory profile-body instructions, not a boundary. Run them only in trusted repositories and state whether the task is read-only or may edit files.
 - Children receive no parent history by default. `Agent` and workflow `agent()` can opt into `context: {mode: "recent", turns: N}` (last N user turns, including the current one) or `{mode: "full"}` (available post-compaction conversation). Snapshots exclude system instructions, thinking, tool-result metadata, and pending calls; unsupported content/images and more than 1 MiB fail explicitly. Use the smallest sufficient snapshot plus a clear task, absolute paths, and read-only/edit intent. Shared context goes to the external harness and private local evidence; avoid unnecessary sensitive history. `resume` continues an existing child and cannot be combined with sharing. Workflow children select from one frozen parent snapshot, and replay fingerprints include the transferred context.
 - Backend-native nested agents may use a different workspace. Include explicit absolute paths and required context when asking an external backend to delegate further.
 - `Agent` and `workflow` block by default; `background: true` returns a stable handle after validation/registration. Background work is owned by the originating session, not by the launching tool call or a daemon. Blocking-call interruption cancels work; wait interruption only stops waiting. Orderly session shutdown requests cancellation with bounded cleanup. A crash or unconfirmed shutdown leaves unfinished evidence interrupted/uncertain; restart never adopts live work.
@@ -21,7 +21,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 ## Delegation transparency invariants
 
 - Treat each `description` as a concise user-facing task label. Profile descriptions are also user-visible as the declared reason for profile selection.
-- `unsandboxed external CLI` and `external host access` disclose the real execution boundary. Never present a read-only prompt as permission enforcement: on agy every run is unsandboxed regardless of tier, so the profile body — not the tier — is what asks the agent to stay read-only.
+- `unsandboxed external CLI` and `external host access` disclose the real execution boundary for CLI backends; a pi harness delegation discloses `Pi SDK child · host access · curated tools` instead — never call an in-process pi child an "external CLI". Never present a read-only prompt as permission enforcement: on agy every run is unsandboxed regardless of tier, so the profile body — not the tier — is what asks the agent to stay read-only; on pi, the curated tool table bounds which tool *names* exist, but does not make `bash` at `danger` tier any less exposed.
 - Keep direct intent visible during execution. Workflow access belongs once at the workflow level, not on every child row.
 - Parent-context sharing is a disclosure, not a silent optimization: the intent card names the mode before launch, and receipts name the mode and shared/requested turns. Shared conversation content leaves for the external harness and lands in local evidence, so never describe sharing as internal or free.
 - Keep default progress bounded and human-readable. Expanded terminal output shows bounded canonical output and a full-ID `/external runs` route; record paths, backend-event counts, workflow IDs, and journal paths remain advanced evidence.
@@ -40,7 +40,7 @@ This fork changes the original pi-flow contract: `Agent` is not a generic Pi sub
 
 ## Workflow contract
 
-`workflow` remains trusted JavaScript orchestration over the same external-only role roster. Its first statement declares `meta.apiVersion: 1`; missing/unsupported versions fail before child launch. Every workflow `agent()` child uses the same `role`/optional `harness` resolution as `Agent`, with legacy exact-profile `subagent_type` available as an escape hatch. Successful calls return their value; failed, cancelled, and timed-out calls throw structured catchable child errors. Explicitly handled errors permit siblings to finish; escaping errors fail the workflow and drain active siblings.
+`workflow` remains trusted JavaScript orchestration over the same external-only role roster, including registered named Pi harnesses. Its first statement declares `meta.apiVersion: 1`; missing/unsupported versions fail before child launch. Every workflow `agent()` child uses the same `role`/optional `harness` resolution as `Agent`, with legacy exact-profile `subagent_type` available as an escape hatch. A workflow run freezes one resolved profile (and model) snapshot up front — real on-disk profiles plus every registered pi harness's synthesized canonical roles — so a synthesized pi role executes exactly like a real file, and a `harnesses.json` edit mid-run cannot desync what the replay fingerprint recorded from what actually ran. Successful calls return their value; failed, cancelled, and timed-out calls throw structured catchable child errors. Explicitly handled errors permit siblings to finish; escaping errors fail the workflow and drain active siblings.
 
 Replay is explicit through a persisted `scriptPath` plus `resumeFromRunId`. Reuse only the longest unchanged successful prefix; changed or unsuccessful calls and their suffix execute again. Never describe script recomposition as making child reruns free or side-effect-free. There is no live steering or automatic repaired-script retry.
 
@@ -52,7 +52,7 @@ Use workflows for requested fan-out or multi-agent orchestration across Claude/C
 - Test public contracts, trust/security boundaries, process lifecycle, cancellation/timeouts, profile rollback, workflow execution/resume, and receipt integrity.
 - Do not test cosmetic rendering variations, prompt prose fragments, trivial accessors, or a model's interpretation of instructions.
 - Do not repeat the same behavior at unit, integration, and E2E levels. A regression test must replace or extend overlapping coverage.
-- `npm test` must remain deterministic and offline. Real-provider E2E is opt-in and change-triggered through `npm run e2e -- --backend <claude|codex|agy> [--workflow]`.
+- `npm test` must remain deterministic and offline. Real-provider E2E is opt-in and change-triggered through `npm run e2e -- --backend <claude|codex|agy> [--workflow]`, or `npm run e2e -- --backend pi --harness <registered-name> [--workflow]` for a named Pi harness the caller has already registered in their own real `harnesses.json` with real credentials configured.
 
 ## Verification and release
 

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.1.0-external.0] - 2026-09-15
+
+Named Pi harness configurations (`pi-*`): a fourth delegation surface running in-process through Pi's own SDK, selectable exactly like `agy`/`claude`/`codex`. Design: `docs/plans/pi-named-configurations-design.md`; plan: `docs/plans/pi-named-configurations-implementation-plan.md`.
+
+### Added
+
+- Named `pi-*` harness configurations: arbitrary labels pinning any `provider/model` resolvable through Pi's model registry (built-in, self-hosted, or OpenAI-compatible) plus an explicit thinking level, registered in `~/.pi/agent/pi-flow-external/harnesses.json`.
+- `Agent({ role, harness: "pi-<label>" })` and workflow `agent()` treat `pi-*` names as first-class harnesses; the six canonical roles (`explorer`/`planner`/`implementer`/`reviewer`/`qa`/`worker`) are synthesized automatically for every registered pi harness with no per-harness files.
+- A `backend: pi` profile is delegation-eligible only when it declares a registered `harness`; the registry stays authoritative for model/thinking (conflicting on-disk overrides fail rather than silently win).
+- Profile creator gains a harness-declaration branch (`pi_flow_harness_create`) and role profiles targeting an existing pi harness, both smoke-tested through the real runtime with atomic staged writes.
+- Pi runtime contract: curated built-in-only child tools (no extensions/skills/themes), synchronous model/auth/thinking preflights, tier→tool allow-lists, execution-role `edit`→`danger` floor, per-child in-memory retry disable (never touching user settings), observed non-retrying terminal-event + non-whitespace completion, thinking-clamp disclosure, and backend-aware permission labels that never call an in-process child an "external CLI".
+- `/external settings`, `/external doctor`, and `external_help` disclose pi harnesses and their model/thinking; stale or deleted `defaultHarness` fails the delegation explicitly rather than silently rerouting to `agy`.
+- Workflow replay fingerprints include the resolved backend/harness/model/thinking/profile body/tools/effective permission plus an SDK-version policy tag; each workflow freezes one complete profile snapshot (synthesized profiles included) for its run.
+
+### Limitations (v1)
+
+- Pi children are built-in tools only; they do not load project/user extensions, skills, prompt templates, themes, or MCP tools. Expansion tracked in issue #43.
+- Custom (non-canonical) pi roles are authored per harness in v1.
+- Pi children cannot be resumed and enforce no hard budget cap; both are disclosed, not approximated.
+
 ## [2.0.0-external.0] - 2026-09-14
 
 Child observation and workflow-aware supervision. Full design: `docs/plans/2026-09-14-child-observation-and-supervision-design.md`.

package/CONTEXT.md

@@ -4,9 +4,10 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 
 ## Domain language
 
-- **External profile:** A markdown file under `~/.pi/agent/subagents/*.md` whose filename and frontmatter select `backend: claude`, `backend: codex`, or `backend: agy`.
+- **External profile:** A markdown file under `~/.pi/agent/subagents/*.md` whose filename and frontmatter select `backend: claude`, `backend: codex`, `backend: agy`, or (only alongside a registered `harness:`) `backend: pi`.
 - **Native Pi subagent:** A subagent exposed by Pi's native subagent system. This fork intentionally does not route it through `Agent`.
-- **Agent call:** A direct external delegation selected by `role` and optional `harness`, or by legacy exact-profile `subagent_type`.
+- **Agent call:** A direct external delegation selected by `role` and optional `harness` (an external CLI or a registered named Pi harness), or by legacy exact-profile `subagent_type`.
+- **Named Pi harness configuration:** A `pi-<label>` entry in `harnesses.json` pinning a `provider/model` id and a thinking level, run in-process via Pi's own SDK rather than as a spawned CLI. `harness` selects *which* configuration; `backend` (always the literal `"pi"` for these) selects the execution mechanism. The six default roles are synthesized automatically for every registered pi harness from the same canonical source the three CLI backends' default files already come from.
 - **Parent context:** An opt-in frozen text snapshot: `none` (default), `recent` with last N user turns including the current turn, or `full` available post-compaction conversation. It is background for a new external conversation, not a native session clone, system-prompt inheritance, or guaranteed cache reuse. Sharing excludes thinking and pending calls and cannot be combined with child `resume`. Workflow children share one invocation-time snapshot; prior child outputs remain explicit inputs.
 - **Workflow call:** Trusted JavaScript orchestration beginning with `meta.apiVersion: 1` that may fan out several explicit external `agent()` calls. Each child returns a value or throws a catchable `ChildRunError`; escaping child errors fail the workflow and drain siblings.
 - **Background run:** A validated, registered `Agent` or `workflow` invocation that returns a stable handle while work remains owned by the originating session. It is not a daemon or cross-session job.
@@ -23,17 +24,17 @@ This package is a fork of pi-flow whose `Agent` and `workflow` tools are reserve
 ## Routing rule
 
 - Native Pi work -> native subagent tool.
-- Claude Code / Codex CLI / Antigravity work -> this extension's `Agent` or `workflow`.
+- Claude Code / Codex CLI / Antigravity work, and named Pi harness work -> this extension's `Agent` or `workflow`.
 
-The split is global and intentional to avoid tool ambiguity across projects. The ordinary driver sees `Agent`, optional `workflow`, and read-only `external_help`; the profile finalizer is activated only by `/external profile create`. External children start in the requested working directory, but backend-native nested helpers may create or use a separate workspace; prompts that request further nesting should include explicit absolute paths and all required context.
+The split is global and intentional to avoid tool ambiguity across projects. The ordinary driver sees `Agent`, optional `workflow`, and read-only `external_help`; the profile finalizer is activated only by `/external profile create`. External children start in the requested working directory, but backend-native nested helpers may create or use a separate workspace; prompts that request further nesting should include explicit absolute paths and all required context. Named Pi harness children are the one exception to "backend-native nested helpers may use a different workspace": a pi child runs in-process with no extensions, skills, prompts, or themes loaded, so it structurally cannot itself launch a further nested agent.
 
 ## User control surface
 
-User operations are namespaced under `/external`: status, Doctor, settings, profiles, profile creation, profile clean-up, workflows, interactive run navigation, durable run summary/pruning, and help. `/external runs` uses the same registry/readers as `external_runs`, including every cursor-paged workflow child and output/diagnostic page. Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`; profiles remain authoritative for downstream backend/model/thinking metadata. A trusted project may override only `defaultHarness`.
+User operations are namespaced under `/external`: status, Doctor, settings, profiles, profile creation, workflows, interactive run navigation, durable run summary/pruning, and help. `/external runs` uses the same registry/readers as `external_runs`, including every cursor-paged workflow child and output/diagnostic page. Extension-owned concurrency, timeout, and global default-harness settings live in `$PI_CODING_AGENT_DIR/pi-flow-external/settings.json`; profiles remain authoritative for downstream backend/model/thinking metadata. Named Pi harness configurations live in the sibling `pi-flow-external/harnesses.json` registry. A trusted project may override only `defaultHarness`, which may itself name a registered `pi-*` harness.
 
 ## Design stance
 
-Guardrails exist to keep lanes from bleeding into each other (a reviewer that edits, a debugger that fixes), not to constrain how a model works. Role bodies stay short: define the job, state the boundary, then get out of the way and trust the model's judgment on approach, depth, and method. The generic `worker` role covers non-coding tasks with no method constraints at all. The shipped default roster is five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus `worker`; other roles such as `debugger` are user-created through `/external profile create` and still receive the name-based execution permission floor. External agents must not be arbitrarily handcuffed just to satisfy a theoretical safety checklist: what transpires on the ground is what matters. When an external agent needs heightened permissions to inspect, run tests, and execute tools, the system defaults to providing that authority rather than blocking execution.
+Guardrails exist to keep lanes from bleeding into each other (a reviewer that edits, a worker that fixes), not to constrain how a model works. Role bodies stay short: define the job, state the boundary, then get out of the way and trust the model's judgment on approach, depth, and method. The generic `worker` role covers non-coding tasks with no method constraints at all. The shipped default roster is five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus `worker`; other roles are user-created through `/external profile create` and still receive the name-based execution permission floor. External agents must not be arbitrarily handcuffed just to satisfy a theoretical safety checklist: what transpires on the ground is what matters. When an external agent needs heightened permissions to inspect, run tests, and execute tools, the system defaults to providing that authority rather than blocking execution.
 
 Role resolution is mechanical, not model-routed: a profile whose name begins with its declared backend plus `-` exposes the remaining name as its role (`agy-reviewer` -> `reviewer`). The selected role and harness must resolve to that exact profile; unavailable roles report their supported harnesses and never fall back. Nonstandard names remain available only through legacy exact `subagent_type`. The resolved profile stays authoritative for its instructions, model, and permissions.
 
@@ -43,10 +44,12 @@ Workflow replay is explicit and successful-prefix-only. A persisted script resum
 
 Applied to Antigravity (`agy`), that stance is absolute: the harness offers no granular headless permission mode — its default sandbox (`proceed-in-sandbox`) hard-denies even read-only tools like `read_url_content`, and `--dangerously-skip-permissions` is the only unsandboxed mode. So every agy run is unsandboxed, and `readonly`/`edit` on agy profiles are advisory instructions carried by the profile body, never an enforced boundary. We disclose that plainly (`unsandboxed external CLI`) rather than pretend a read-only tier restrains what the harness will actually allow.
 
+Applied to named Pi harness configurations, the same "get out of the way" stance takes a different, honestly-scoped shape: a curated, builtins-only tool surface (no project/user extensions, skills, prompts, or themes) genuinely bounds which tool *names* a pi child can reach — that claim is mechanically true because nothing else loads — but it is not a claim that `bash` at `danger` tier is any less dangerous than on an external CLI once it is granted. `readonly`/`edit` tiers get a real default tool allow-list (`read`/`grep`/`find`/`ls`, plus `edit`/`write` at `edit`) so those tiers are actually usable, not just technically restrictive. Execution-lane roles requested at `edit` are still elevated to `danger` (the same floor as Claude), because `edit` excludes `bash` entirely and an execution lane without shell access cannot do its job.
+
 ## Known inelegance
 
 <!-- ponytail: one-backend-per-file profile format forces role x backend file duplication; extend src/profiles.ts with multi-backend profiles (e.g. backends: [claude, codex, agy] plus per-backend model map) if maintaining N copies of identical role bodies ever hurts -->
-A standardized role roster needs one file per role per backend (e.g. `claude-qa`, `codex-qa`, `agy-qa` with identical bodies) because the profile format binds `backend:` and `model:` to a single file. The duplication is accepted for now; a future format extension could let one role file cover all backends. The same applies to `permission:` tiers: one tier per profile, but backends interpret tiers differently (Claude denies Bash at anything below `danger`), so command-running roles declare `danger` and maintain `danger` as their floor even if an explicit `edit` override is requested. Custom profiles outside the role-name convention get that floor only by declaring `permission: danger`; an undeclared custom profile that meets an `edit` tier still hits headless Bash denials, so `permission: danger` doubles as the lane's "needs shell" capability declaration.
+A standardized role roster needs one file per role per backend (e.g. `claude-qa`, `codex-qa`, `agy-qa` with identical bodies) because the profile format binds `backend:` and `model:` to a single file. The duplication is accepted for now; a future format extension could let one role file cover all backends. Named Pi harnesses partially resolve this for the six canonical roles specifically (synthesized once from a single shared source, applied identically to every registered `pi-*` config, with zero files written) — but a *custom* role outside the six still needs one file per pi harness, exactly like the three CLI backends; a user with several registered pi harnesses wanting the same custom role on all of them still duplicates one file per harness. The same applies to `permission:` tiers: one tier per profile, but backends interpret tiers differently (Claude and pi deny Bash at anything below `danger`), so command-running roles declare `danger` and maintain `danger` as their floor even if an explicit `edit` override is requested. Custom profiles outside the role-name convention get that floor only by declaring `permission: danger`; an undeclared custom profile that meets an `edit` tier still hits headless Bash denials (or, on pi, a curated tool set without `bash`), so `permission: danger` doubles as the lane's "needs shell" capability declaration. Named Pi harnesses also ship with no resume and no enforced budget cap in v1 — both deliberate limitations, tracked alongside the shared-custom-role gap in issue #43, not oversights.
 
 ## Evidence boundary
 

package/README.md

@@ -5,6 +5,7 @@ External agent delegation for [pi](https://github.com/earendil-works/pi) through
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) profiles with `backend: claude`
 - [Codex CLI](https://github.com/openai/codex) profiles with `backend: codex`
 - Antigravity profiles with `backend: agy`
+- Named Pi harness configurations (`pi-<label>`) — in-process, per-model configs you register yourself, not a spawned CLI
 
 The ordinary driver has four tools (`workflow` can be disabled):
 
@@ -13,7 +14,7 @@ The ordinary driver has four tools (`workflow` can be disabled):
 - `external_help` returns role details, permission behavior, or workflow guidance on demand.
 - `external_runs` lists, inspects, waits for, and cancels session-owned runs.
 
-`Agent` and `workflow` accept external roles with an optional harness override. Use pi's native subagent system for Pi-backed agents. The `pi_flow_profile_create` finalizer is active only during `/external profile create`.
+`Agent` and `workflow` accept external roles with an optional harness override — one of the three CLIs, or a registered named Pi harness. Use pi's native subagent system for Pi-backed agents. The `pi_flow_profile_create` and `pi_flow_harness_create` finalizers are active only during `/external profile create`.
 
 ## Install
 
@@ -56,10 +57,11 @@ External agents use the effective permission tier and each harness's native mech
 - Claude: `--permission-mode plan`, `--permission-mode acceptEdits`, or `--dangerously-skip-permissions`
 - Codex: `--sandbox read-only`, `workspace-write`, or `danger-full-access`
 - Antigravity: always `--dangerously-skip-permissions`
+- Named Pi harnesses: a curated `tools:` allow-list (`read`/`grep`/`find`/`ls` at `readonly`; those plus `edit`/`write` at `edit`), or the SDK's own default active tools (`read`/`bash`/`edit`/`write`) at `danger`
 
-Claude refuses bypass mode when its effective UID is `0`; in that case the extension uses `--permission-mode auto`. External execution lanes (like `implementer`, `debugger`, `qa`, and `worker`) require shell execution to inspect repositories, run tests, and verify code. On Claude Code, headless `edit` mode (`acceptEdits`) auto-denies all shell commands; therefore, execution lanes maintain a `danger` floor so the model is not artificially handcuffed by permission blocks. Run external agents only in repositories you trust and state whether each task is read-only or may edit files.
+Claude refuses bypass mode when its effective UID is `0`; in that case the extension uses `--permission-mode auto`. External execution lanes (like `implementer`, `qa`, and `worker`) require shell execution to inspect repositories, run tests, and verify code. On Claude Code and named Pi harnesses, headless/`edit`-tier access excludes shell entirely; therefore, execution lanes maintain a `danger` floor so the model is not artificially handcuffed by permission blocks. Run external agents only in repositories you trust and state whether each task is read-only or may edit files.
 
-The TUI labels a direct run with its effective access, including `unsandboxed external CLI` for danger and all Agy runs, and shows `external host access` while workflow work is active. These labels disclose actual execution authority; they do not turn a read-only prompt into an enforced permission boundary.
+The TUI labels a direct run with its effective access, including `unsandboxed external CLI` for danger and all Agy runs, `Pi SDK child · host access · curated tools` for a danger-tier named Pi harness, and shows `external host access` while workflow work is active. These labels disclose actual execution authority; they do not turn a read-only prompt into an enforced permission boundary.
 
 ## Quick start
 
@@ -95,7 +97,6 @@ All user commands use the `/external` namespace:
 | `/external settings` | Show the default harness and effective runtime settings |
 | `/external profiles` | List configured external profiles |
 | `/external profile create` | Create and smoke-test a profile |
-| `/external profile clean-up` | Archive retired pi-flow default profiles |
 | `/external workflows` | List saved workflows |
 | `/external runs` | Interactively browse current-session runs, every workflow child, paged output/diagnostics, and cancellation |
 | `/external runs summary` | Summarize durable run records |
@@ -112,7 +113,7 @@ Profiles live in:
 ~/.pi/agent/subagents/<name>.md
 ```
 
-Names may contain lowercase letters, numbers, and hyphens. A profile must declare `backend: claude`, `backend: codex`, or `backend: agy`, and its name should start with the matching backend name.
+Names may contain lowercase letters, numbers, and hyphens. A profile must declare `backend: claude`, `backend: codex`, `backend: agy`, or (alongside `harness: <a registered pi-* name>`) `backend: pi`, and its name should start with the matching harness name.
 
 Example Claude profile, `~/.pi/agent/subagents/claude-explorer.md`:
 
@@ -139,16 +140,46 @@ backend: agy
 model: gemini-3.7-flash-high
 ```
 
-Profile instructions become the external agent's system instructions. A profile's `description` is also shown as the user-visible reason for its selection, so keep it concise and concrete. External CLIs use their own tools, so a profile's `tools:` field does not control them. Profiles with `backend: pi` or no backend are not available to this extension; they belong to Pi's native subagent system and are never modified by it. `/external profile clean-up` archives only profiles this extension itself shipped and later retired (currently the former `debugger` role) to `~/.pi/agent/subagents/archive/` after confirmation — moved, never deleted.
-
-Profiles created through `/external profile create` are stamped `owner: user`, and clean-up never archives `owner: user` profiles. When writing a profile by hand, add `owner: user` to its frontmatter to protect it from clean-up.
+Profile instructions become the external agent's system instructions. A profile's `description` is also shown as the user-visible reason for its selection, so keep it concise and concrete. External CLIs use their own tools, so a profile's `tools:` field does not control them; a pi profile's `tools:` field does apply, intersected with its permission tier's curated tool table. A `backend: pi` profile is only available to this extension when it also declares `harness: <name>` for a name registered in `harnesses.json` (see below); a bare `backend: pi` profile, or no backend at all, belongs to Pi's native subagent system and is never modified by this extension.
 
 ### Default profiles
 
-On first session start the extension seeds a default roster — five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker — as one storage profile per backend (18 files). The compact agent catalog advertises each role once rather than presenting 18 choices. Seeding happens once: it never overwrites existing files, and profiles you delete or customize afterwards stay that way. Default profiles leave `model` and `thinking` unpinned so they track the CLI's own model and the current Pi thinking level. Roles not in the default roster, such as debugger, can be added with `/external profile create`.
+On first session start the extension seeds a default roster — five code-oriented roles (explorer, planner, implementer, reviewer, qa) plus the generalist worker — as one storage profile per backend (18 files). The compact agent catalog advertises each role once rather than presenting 18 choices. Seeding happens once: it never overwrites existing files, and profiles you delete or customize afterwards stay that way. Default profiles leave `model` and `thinking` unpinned so they track the CLI's own model and the current Pi thinking level. Roles not in the default roster can be added with `/external profile create`.
 
 Project-local profiles are not supported; global profiles are used for both global and project-only package installations.
 
+## Named Pi harness configurations
+
+A named Pi harness runs in-process through Pi's own SDK rather than as a spawned CLI, letting you delegate to any model Pi can already resolve (built-in, self-hosted, or a custom-registered provider) without an external CLI. Register one via `/external profile create` (choose the "declare a new named Pi harness" branch): give it a `pi-<label>` name, a `provider/model` id, and an optional thinking level. Registration is smoke-tested against the real pi runtime before it is saved, exactly like a CLI profile, into:
+
+```text
+~/.pi/agent/pi-flow-external/harnesses.json
+```
+
+```json
+{
+  "version": 1,
+  "harnesses": {
+    "pi-deepseek": { "model": "deepseek/deepseek-chat", "thinking": "high" }
+  }
+}
+```
+
+The moment a harness is registered, all six default roles (explorer, planner, implementer, reviewer, qa, worker) become available on it automatically — no per-role file to write. Delegate to it exactly like any other harness:
+
+```ts
+Agent({
+  description: "Cheap repository review",
+  prompt: "Review this diff read-only.",
+  role: "reviewer",
+  harness: "pi-deepseek",
+});
+```
+
+A custom (non-canonical) role still needs its own profile file per harness, the same as for the three CLI backends: `~/.pi/agent/subagents/pi-deepseek-security-reviewer.md` with `backend: pi` and `harness: pi-deepseek`. That file's body/permission/tools may be customized; its `model`/`thinking` are not — they always come from the harness's registered config, and a file that tries to override them to a different value is rejected rather than silently honored.
+
+**v1 scope, by design:** a pi child's entire tool surface is the SDK's own builtins (`read`/`bash`/`edit`/`write`, plus `grep`/`find`/`ls` at `readonly`/`edit` tiers) — no project/user extensions, skills, prompt templates, or themes load into it. This bounds which tool *names* exist; it does not make `bash` at `danger` tier any less exposed than on an external CLI. Retry is disabled per pi child (in-memory, never touching your real Pi settings) so a transient provider error fails immediately rather than silently retrying. Pi children cannot resume a prior conversation and have no enforced budget cap. Expanding this capability set (trusted extensions/MCP/skills, a shared custom-role format, resumable sessions, real budget controls) is tracked in [issue #43](https://github.com/tranhoangnguyen03/pi-flow-external/issues/43).
+
 ## Agent usage
 
 A direct tool call requires `description`, `prompt`, and either `role` or legacy exact-profile `subagent_type`. With `role`, `harness` is optional and defaults to the global `defaultHarness` setting:
@@ -374,8 +405,12 @@ npm run e2e -- --backend agy
 npm run e2e -- --backend claude --workflow
 npm run e2e -- --backend codex --workflow
 npm run e2e -- --backend agy --workflow
+npm run e2e -- --backend pi --harness pi-deepseek
+npm run e2e -- --backend pi --harness pi-deepseek --workflow
 ```
 
+The `pi` backend requires a harness you have already registered yourself in your real `harnesses.json` with real credentials configured; the script never registers or pays for one on your behalf.
+
 See [`docs/field-testing.md`](docs/field-testing.md) for provider checks and [`docs/releasing.md`](docs/releasing.md) for the release process.
 
 Run directly from a checkout with:

package/docs/field-testing.md

@@ -39,6 +39,16 @@ Defaults:
 
 Override with `--model`, `--thinking`, `--root-model`, or `--root-thinking`. Use `--keep` only when evidence inspection is necessary; it preserves sensitive output and the temporary profile path printed by the runner.
 
+### Named Pi harness receipt
+
+Run only when the pi runtime contract (§7 of the design), harness registry, or canonical role synthesis changes, and only if you have already registered a real `pi-*` harness in your own `harnesses.json` with real credentials configured:
+
+```bash
+npm run e2e -- --backend pi --harness pi-deepseek
+```
+
+This lane never registers a harness or writes a temporary profile — canonical synthesis already provides the `worker` role for any registered harness — it only delegates to the harness you name and requires the same one complete `done` receipt.
+
 ## Supervised workflow receipt
 
 When workflow runtime, scheduling, supervision, or tool integration changes, run the affected backend; run all three before release:
@@ -47,6 +57,7 @@ When workflow runtime, scheduling, supervision, or tool integration changes, run
 npm run e2e -- --backend claude --workflow
 npm run e2e -- --backend codex --workflow
 npm run e2e -- --backend agy --workflow
+npm run e2e -- --backend pi --harness pi-deepseek --workflow
 ```
 
 Each command declares `meta.apiVersion: 1`, starts a two-child workflow with `background: true`, waits for the selected workflow through `external_runs`, inspects its summary/output, requires two complete child receipts, and verifies the read-only fixture stayed clean. Forced multi-page cursor behavior remains covered by deterministic offline tests; this check exercises real workflow child handling without duplicating those semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.0.0-external.0",
+  "version": "2.1.0-external.0",
   "description": "External Claude Code, Codex CLI, and Antigravity delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/model.ts

@@ -20,7 +20,32 @@ export function resolveProfileModel(profile: SubagentProfile, ctx: ExtensionCont
   if (!usesPiBackend(profile)) {
     return undefined;
   }
-  return profile.model ? findProfileModel(profile, ctx.modelRegistry) : ctx.model;
+  // A legitimate pi profile always pins a model (either declared directly or
+  // inherited from its registered harness at resolution time), so there is no
+  // "fall back to the parent's own model" case here: an admitted pi profile
+  // with no resolvable model is a real error, surfaced by describeMissingModel.
+  return profile.model ? findProfileModel(profile, ctx.modelRegistry) : undefined;
+}
+
+/**
+ * Distinguish "profile pins no parseable model string" from "profile pins a
+ * parseable model that isn't in the registry" so callers can surface the two
+ * distinct failures from design §7.1 instead of one generic message.
+ */
+export function describeMissingModel(profile: SubagentProfile, modelRegistry: ModelRegistry): string {
+  if (!profile.model) {
+    return "No model is selected";
+  }
+  const separator = profile.model.indexOf("/");
+  if (separator === -1) {
+    return `Profile "${profile.name}" pins no resolvable model (expected "<provider>/<id>", got ${JSON.stringify(profile.model)}).`;
+  }
+  const provider = profile.model.slice(0, separator);
+  const id = profile.model.slice(separator + 1);
+  if (modelRegistry.find(provider, id)) {
+    return "No model is selected";
+  }
+  return `Profile "${profile.name}" pins model "${profile.model}", which was not found in the registry.`;
 }
 
 export function filterProfilesForModelRegistry(

package/src/core/permissions.ts

@@ -1,18 +1,33 @@
 import type { PermissionTier, SubagentBackend, SubagentProfile } from "../types.ts";
 
+/**
+ * Single source of truth for which pi-child SDK builtin tools are active at
+ * each permission tier (design §6's curated tier table). Both the runtime
+ * (src/core/spawn.ts, which derives its actual excludeTools/tools allow-list
+ * from this) and this module's disclosure caveat read from here, so the
+ * caveat text can never drift out of sync with what actually executes.
+ */
+export const PI_TIER_ACTIVE_TOOLS: Readonly<Record<PermissionTier, readonly string[]>> = {
+  readonly: ["read", "grep", "find", "ls"],
+  edit: ["read", "grep", "find", "ls", "edit", "write"],
+  danger: ["read", "bash", "edit", "write"],
+};
+
 export interface PermissionResolution {
   tier: PermissionTier;
   /** True when the backend enforces the tier with a native mechanism. */
   enforced: boolean;
   /** Short human-readable caveat shown in disclosure labels. */
   caveat: string | undefined;
+  /** Backend this resolution was computed for; lets permissionLabel branch on it. */
+  backend?: SubagentBackend;
 }
 
 /**
  * Known execution-oriented roles that require command/Bash execution
  * (running tests, build tools, git inspection, etc.).
  */
-export const EXECUTION_ROLES: readonly string[] = ["implementer", "debugger", "qa", "worker"];
+export const EXECUTION_ROLES: readonly string[] = ["implementer", "qa", "worker"];
 
 /** Minimal profile shape needed to reason about permission tiers. */
 export type PermissionProfileRef = Pick<SubagentProfile, "name" | "backend" | "description" | "permission">;
@@ -29,7 +44,7 @@ export function isExecutionProfile(profile?: PermissionProfileRef): boolean {
  *
  * Pragmatic execution principle: do not get in the way of external agents
  * doing good work. Claude in headless mode auto-denies all Bash commands at
- * `edit` (acceptEdits); execution profiles (such as implementer, debugger, qa,
+ * `edit` (acceptEdits); execution profiles (such as implementer, qa,
  * worker) require shell access to inspect repositories, run tests, and validate
  * fixes. An override to `edit` on these lanes would handcuff the model into
  * headless permission denials. We elevate to `danger` so the agent has the
@@ -49,7 +64,11 @@ export function resolveEffectivePermissionTier(
     // by the profile body, not a harness boundary.
     return "danger";
   }
-  if (profile?.backend === "claude" && isExecutionProfile(profile) && baseTier === "edit") {
+  if ((profile?.backend === "claude" || profile?.backend === "pi") && isExecutionProfile(profile) && baseTier === "edit") {
+    // Same floor as claude, for the same reason: §6's curated pi tool table
+    // strips `bash` at `edit` tier, so an execution-lane pi profile (implementer,
+    // qa, worker) requested at `edit` would otherwise lose shell
+    // access entirely. Elevate rather than silently handcuff the agent.
     return "danger";
   }
   return baseTier;
@@ -65,6 +84,7 @@ export function resolvePermission(tier: PermissionTier, backend: SubagentBackend
       return {
         tier,
         enforced: true,
+        backend,
         // plan/acceptEdits auto-deny Bash headlessly; denials are surfaced.
         caveat: tier === "danger" ? undefined : "Bash auto-denied headlessly",
       };
@@ -72,6 +92,7 @@ export function resolvePermission(tier: PermissionTier, backend: SubagentBackend
       return {
         tier,
         enforced: true,
+        backend,
         // --sandbox governs model-generated shell commands, not MCP/plugins/hooks.
         caveat: tier === "danger" ? undefined : "shell commands only",
       };
@@ -84,10 +105,27 @@ export function resolvePermission(tier: PermissionTier, backend: SubagentBackend
       return {
         tier,
         enforced: tier === "danger",
+        backend,
         caveat: tier === "danger" ? undefined : "runs unsandboxed; tier advisory only",
       };
+    case "pi":
+      // A curated builtins-only tool surface bounds which tool *names* exist
+      // (see spawn.ts's pi branch); it is a real, truthful tool-level
+      // restriction and not an OS sandbox. It never makes `bash` at `danger`
+      // tier meaningfully less exposed than any other backend's `danger` tier.
+      // The caveat names exactly the tools active *at this tier* (from the
+      // same PI_TIER_ACTIVE_TOOLS table spawn.ts's runtime derives its actual
+      // allow-list from) — never the full builtin universe regardless of
+      // tier, which would misrepresent readonly/edit as having bash/write
+      // available when the tier table excludes them.
+      return {
+        tier,
+        enforced: true,
+        backend,
+        caveat: tier === "danger" ? undefined : `${PI_TIER_ACTIVE_TOOLS[tier].join("/")} tools only; no project extensions`,
+      };
     default:
-      return { tier, enforced: false, caveat: "advisory, not enforced" };
+      return { tier, enforced: false, backend, caveat: "advisory, not enforced" };
   }
 }
 
@@ -118,7 +156,25 @@ export function buildPermissionArgs(
 
 /** Disclosure label used in delegation cards and receipts. */
 export function permissionLabel(resolution: PermissionResolution): string {
-  const { tier, enforced, caveat } = resolution;
+  const { tier, enforced, caveat, backend } = resolution;
+  if (backend === "pi") {
+    // A pi child is an in-process SDK session, not an external CLI process:
+    // never describe it as "external CLI" (design §9, "Delegation transparency
+    // invariants" in AGENTS.md). "host access" discloses the real boundary —
+    // the curated tool table restricts which tool *names* exist, not what an
+    // admitted bash tool can do.
+    if (tier === "danger") {
+      return "Pi SDK child · host access · curated tools";
+    }
+    const parts = [`Pi SDK child · ${tier} · curated tools`];
+    if (!enforced) {
+      parts.push("advisory, not enforced");
+    }
+    if (caveat && caveat !== "advisory, not enforced") {
+      parts.push(caveat);
+    }
+    return parts.join(" · ");
+  }
   if (tier === "danger") {
     return "unsandboxed external CLI";
   }