@tranhoangnguyen0310/pi-flow-external 5.4.0-external.0 → 5.5.0-external.0

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [5.5.0-external.0] - 2026-10-24
+
+### Added
+- Read-only harness capability discovery through `external_help({ topic: "capabilities", harness? })` (#79, #95). Omit `harness` for a compact summary or select a built-in CLI or registered `pi-*` harness for details about permissions, structured child answers, resume, budgets, cost reporting, retries, context sharing, and Pi resources.
+- Capability records distinguish configured/enabled state from `readiness: "not_probed"`, and Flow's structured run receipts from support for schema-constrained child answers. Discovery launches no processes, reads no credentials, calls no providers, and writes no files.
+
+### Changed
+- Permission help is generated from shared per-tier facts, including each Pi tier's exact tools. Budget-support disclosures use shared backend metadata. Existing execution permissions and budget enforcement are unchanged.
+
+### Fixed
+- Capability discovery respects valid OpenCode role overrides instead of marking the whole harness invalid when a binding supplies a compatible model or effort setting.
+- Claude permission help uses the current effective UID and correctly reports `--permission-mode auto` under root.
+- Active in-process Pi child rows show `Pi SDK child · host access` instead of `external host access`.
+
+### Release
+- Publishes the capability changes merged in #95 under a fresh version. That merge retained the already-published `5.4.1-external.0`, so its release workflow reused the existing tag and skipped publishing; this release includes those changes without rewriting any published version or tag.
+
+## [5.4.1-external.0] - 2026-10-23
+
+### Fixed
+- Bounded-repair now rejects non-Codex harnesses before starting any editor. Supporting edit and readonly permissions alone does not provide the shell access and structured output required by QA.
+- Repair guidance now states the Codex-only limit and requires checks compatible with its read-only sandbox. Regression tests cover rejection before edits and default/explicit Codex execution.
+
 ## [5.4.0-external.0] - 2026-10-23
 
 ### Added

package/README.md

@@ -229,5 +229,5 @@ The direct delegation tool `Agent` is now `external_delegate`, with no alias. Up
 - **[Workflows](docs/workflows.md):** `external_workflow`, plain-language plans, live phases, error handling (`ChildRunError`), and replay cache.
 - **[Orchestration Playbook](docs/orchestration-playbook.md):** When to choose patterns, how to invoke the bundled skill, and tested example recipes.
 - **[Workflow Tool Rename](docs/migration-workflow-to-external-workflow.md):** `workflow` → `external_workflow`, with no alias.
-- **[Public Contract](docs/public-contract.md):** Contract envelope definitions (`external_delegate`, `external_workflow`, `external_runs`, `external_help`), `external_help({ topic: "contracts", tool? })` discovery, and explicit context-handoff guidance for Pi codemode consumers.
+- **[Public Contract](docs/public-contract.md):** Contract envelope definitions (`external_delegate`, `external_workflow`, `external_runs`, `external_help`), `external_help({ topic: "contracts" | "capabilities" })` discovery, and explicit context-handoff guidance for Pi codemode consumers.
 - **[Troubleshooting](docs/troubleshooting.md):** Common errors, authentication checks, and `pi-cc-extensions` renderer compatibility.

package/docs/orchestration-playbook.md

@@ -44,7 +44,9 @@ Example for parallel-sweep.js:
 
 Before launch the parent should explain the split, selected harnesses, permissions, which checks run in parallel, and what evidence will come back. Foreground is the default when the result is needed next.
 
-The example pins Codex because it supports the explicit readonly tier (and edit for the repair recipe); **it does not automatically switch backends**. Set harness to a verified available backend that enforces the required tier. Antigravity supports only danger, so these restricted examples do not work on it.
+The example pins Codex because it supports the explicit readonly tier; **it does not automatically switch backends**. For the read-only recipes, set harness to a verified available backend that enforces the required tier. Antigravity supports only danger, so these restricted examples do not work on it.
+
+**Bounded repair is Codex-only.** It rejects other harnesses before any editor starts. Supporting edit and readonly tiers is not enough: QA must also have shell access and structured output. OpenCode rejects the required schema, while Claude, Muse, and named Pi harnesses cannot shell-run tests at readonly. Before launch, confirm Codex is available and the checks can run in its read-only sandbox; checks that need workspace writes or network access may fail. Do not silently raise permissions to run them.
 
 ## What good behavior looks like
 

package/docs/public-contract.md

@@ -25,7 +25,7 @@ Every result carries:
 | `external_delegate` | `delegate` | `{run}` | `{run}`, or `{run: null}` before registration |
 | `external_workflow` | `run` | `{run}` | `{run}`, or `{run: null}` before registration |
 | `external_runs` | the requested action | the action's payload (below) | `null` |
-| `external_help` | `help` | `{topic, harness?, tool?, text}` or `{topic: "contracts", index \| tool, contract}` | `null` |
+| `external_help` | `help` | `{topic, harness?, tool?, text}`, `{topic: "contracts", index \| tool, contract}`, or `{topic: "capabilities", harness?, harnesses}` | `null` |
 
 A failure that has a run keeps that run's evidence. Read-only supervision and help never return partial data on failure.
 
@@ -117,9 +117,12 @@ A host redaction hook that replaces content drops structured content unless it e
 
 Pi generates TypeScript input and discriminated output declarations from the registered schemas through native `searchTools` and `describeTool`. For `external_delegate`, each `anyOf` selector branch (`role` vs `subagent_type`) repeats the shared property definitions and required fields so `describeTool("external_delegate")` renders both branches; JSON Schema `not` exclusions (`role` + `subagent_type` and `subagent_type` + `harness`) are enforced by `validateToolArguments` even though Pi's TypeScript renderer omits `not`.
 
-For Flow-specific semantics, raw JSON schemas, validated example payloads, and workflow helper signatures, call `external_help`:
+For Flow-specific semantics, raw JSON schemas, validated example payloads, workflow helper signatures, and per-harness capabilities, call `external_help`:
 - `external_help({ topic: "contracts" })` returns a compact index (≤ 1.5 KiB) listing `external_delegate`, `external_workflow`, `external_runs`, and `external_help`, whether each is registered (`false` for `external_workflow` when disabled), core contract rules, and a pointer to `describeTool`.
 - `external_help({ topic: "contracts", tool: "external_delegate" })` (or `"external_workflow"`, `"external_runs"`, `"external_help"`) returns `{ tool, contractVersion, registered, actions, purpose, input, output, semantics, examples, helpers? }`, where `input` and `output` come directly from the executable tool definitions and `helpers` on `external_workflow` exposes `WORKFLOW_HELPERS` (`functions`, `globals`, `agentOptions`).
+- `external_help({ topic: "capabilities", harness? })` returns `{ topic: "capabilities", harness?, harnesses: CapabilityRecord[] }` without spawning processes, reading credentials, calling providers, or writing files. Omitting `harness` renders a compact one-line-per-harness summary in `content` (`enabled`, supported `tiers`, `workflowChildSchema`, `resume`, `budget`, `cost`) across all selectable harnesses (or the six built-in harnesses with `configuration.state: "invalid"` and `diagnostics` when settings are blocked, without guessing registered `pi-*` names). Passing `harness` renders the full capability record for that harness: `configuration` (`built_in | registered | invalid`, `enabled`, `diagnostics?`, `model?`, `thinking?`, `preset?`), `readiness: "not_probed"` (configuration does not prove installation or authentication; use `/external config harness test` or `/external doctor`), `workflowChildSchema` (schema-constrained workflow `agent({ schema })` task output, distinct from Flow's operational `PublicRun` receipts which every harness returns), `resume`, `budget` (`"enforced" | "not_enforced"`), `cost` (`"native" | "estimated" | "partial" | "unknown"`), `retries`, `nestedAgentDetection`, `permissions` (`default`, per-tier `supported`/`enforced`/`caveat?`/`tools?`, and backend `caveats`), `context` (`modes`, `maxBytes`, `resumeConflict`), and `resources` (for `pi-*` harnesses, reflecting `preset` and `ctx.isProjectTrusted()`).
+
+Capability configuration describes the harness and its defaults, not every role binding. Role-specific model and effort overrides are validated after resolution; a binding error does not disable the entire harness.
 
 ## Explicit context handoff
 

package/package.json

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

package/skills/pi-flow-orchestration/SKILL.md

@@ -34,9 +34,9 @@ Read [pattern-selection.md](references/pattern-selection.md) for failure modes a
 - [parallel-sweep.js](recipes/parallel-sweep.js) — independent scopes, partial failures kept.
 - [branch-and-converge.js](recipes/branch-and-converge.js) — parallel discovery with explicit evidence handoff into a final synthesis.
 - [adversarial-review.js](recipes/adversarial-review.js) — draft and independent critique (not a self-review).
-- [bounded-repair.js](recipes/bounded-repair.js) — authorized edits, structured checks, limited iterations.
+- [bounded-repair.js](recipes/bounded-repair.js) — Codex-only authorized edits, structured checks, limited iterations. Other harnesses are rejected before any child starts.
 
-These are adaptable **examples**, not new runtime functions. Copy a recipe into a trusted saved workflow root or pass its text as the script to external_workflow, and pass JSON inputs through the tool's args. A scriptPath must be inside an allowed workflow root; a package skill directory is not automatically such a root. Recipes assume Codex as a restricted-permission demonstration backend, not an automatic fallback. Set harness inputs to an available backend that enforces the required tier.
+These are adaptable **examples**, not new runtime functions. Copy a recipe into a trusted saved workflow root or pass its text as the script to external_workflow, and pass JSON inputs through the tool's args. A scriptPath must be inside an allowed workflow root; a package skill directory is not automatically such a root. Recipes assume Codex as a restricted-permission demonstration backend, not an automatic fallback. For the read-only recipes, set harness inputs to an available backend that enforces the required tier. Bounded repair requires Codex: QA needs both shell access at readonly and structured output. Before launch, confirm Codex is available and the specified checks can run in its read-only sandbox; checks that need workspace writes or network access may fail.
 
 ## Flow rules that prevent common failures
 

package/skills/pi-flow-orchestration/recipes/bounded-repair.js

@@ -18,7 +18,11 @@ if (typeof input.checks !== "string" || !input.checks.trim()) throw new Error("a
 if (!Number.isInteger(input.maxAttempts) || input.maxAttempts < 1 || input.maxAttempts > 3) {
   throw new Error("args.maxAttempts must be an authorized number in 1-3");
 }
-const harness = input.harness || "codex"; // Must enforce both edit and readonly.
+// shortcut: Codex-only QA; expand after verifying shell access and structured output at readonly.
+const harness = input.harness === undefined ? "codex" : input.harness;
+if (harness !== "codex") {
+  throw new Error('bounded-repair requires harness "codex" for shell checks and structured QA; no agents started');
+}
 const attempts = [];
 let feedback = "";
 for (let attempt = 1; attempt <= input.maxAttempts; attempt++) {

package/skills/pi-flow-orchestration/references/runtime-rules.md

@@ -19,7 +19,7 @@ Use the installed version's external_help({topic:"workflow"}) and external_help(
 - Claude readonly and edit have native tool restrictions, not kernel isolation; headless shell is denied at those tiers. Codex supports read-only and workspace-write OS sandboxes. Do not promise the same security guarantee across backends.
 - For inspection-only work, prefer a harness that can enforce readonly. A prompt saying "don't edit" alone is insufficient.
 - Do not execute parallel edits in the same working tree unless the parent has verified disjoint ownership and no shared-file changes. No built-in worktree isolation or merge arbitration exists in Flow.
-- A repair recipe needs the user to authorize edits and the expected fix/test cycle. Do not auto-retry failed children or expand permission without authorization.
+- A repair recipe needs the user to authorize edits and the expected fix/test cycle. The bundled bounded-repair recipe accepts only Codex and rejects other harnesses before starting children: QA requires shell access at readonly plus structured output, not just support for the permission tiers. Confirm the checks can run in Codex's read-only sandbox before editing. Do not auto-retry failed children or expand permission without authorization.
 
 ## Context and handoff
 

package/src/contract/help.ts

@@ -1,5 +1,6 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static, type TSchema } from "typebox";
+import { buildCapabilityRecord } from "../core/capabilities.ts";
 import { EXTERNAL_DELEGATE_TOOL, EXTERNAL_WORKFLOW_TOOL } from "../tool-names.ts";
 import { USAGE_ONE_AGENT, usageWorkflowScript } from "../prompts.ts";
 import { workflowToolParameters } from "../workflow/source.ts";
@@ -9,7 +10,7 @@ import { EXTERNAL_RUNS_ACTION_SPECS, EXTERNAL_RUNS_EXAMPLES, externalRunsOutputS
 import { formatWorkflowHelpersLine, HANDLED_CHILD_FAILURES, WORKFLOW_HELPERS, workflowOutputSchema } from "./workflow.ts";
 
 export const EXTERNAL_HELP_TOOL = "external_help" as const;
-export const EXTERNAL_HELP_TOPICS = ["usage", "roles", "permissions", "workflow", "contracts"] as const;
+export const EXTERNAL_HELP_TOPICS = ["usage", "roles", "permissions", "workflow", "contracts", "capabilities"] as const;
 export const PUBLIC_TOOL_NAMES = [
   EXTERNAL_DELEGATE_TOOL,
   EXTERNAL_WORKFLOW_TOOL,
@@ -25,11 +26,11 @@ export const CONTRACT_INDEX_MAX_BYTES = 1536;
 export const externalHelpParameters = Type.Object({
   topic: StringEnum(EXTERNAL_HELP_TOPICS, {
     description:
-      "Help topic: usage playbook, role descriptions/configured profile availability, harness permissions, workflow syntax and saved workflows, or public tool contracts.",
+      "Help topic: usage playbook, role descriptions/configured profile availability, harness permissions, workflow syntax and saved workflows, public tool contracts, or per-harness capabilities.",
   }),
   harness: Type.Optional(Type.String({
     description:
-      "Optional harness filter for roles or permissions: agy, claude, codex, grok, muse, opencode, or a registered pi-* harness. usage, workflow, and contracts describe every harness.",
+      "Optional harness filter for roles, permissions, or capabilities: agy, claude, codex, grok, muse, opencode, or a registered pi-* harness. Omit on capabilities for the compact index. usage, workflow, and contracts describe every harness.",
   })),
   tool: Type.Optional(Type.String({
     description:
@@ -112,10 +113,81 @@ const contractsTopicDataSchema = Type.Union([
   }),
 ]);
 
+export const permissionTierCapabilitySchema = Type.Object({
+  supported: Type.Boolean(),
+  enforced: Type.Boolean(),
+  caveat: Type.Optional(Type.String()),
+  tools: Type.Optional(Type.Array(Type.String())),
+});
+
+export const capabilityRecordSchema = Type.Object({
+  harness: Type.String(),
+  backend: strings("agy", "claude", "codex", "grok", "muse", "opencode", "pi"),
+  boundary: strings("external_cli", "pi_sdk"),
+  configuration: Type.Object({
+    state: strings("built_in", "registered", "invalid"),
+    enabled: Type.Boolean(),
+    diagnostics: Type.Optional(Type.Array(Type.String())),
+    model: Type.Optional(Type.String()),
+    thinking: Type.Optional(Type.String()),
+    preset: Type.Optional(strings("minimal", "skills")),
+  }),
+  readiness: Type.Literal("not_probed"),
+  workflowChildSchema: Type.Object({
+    support: strings("supported", "unsupported"),
+    mechanism: strings("cli_flag", "schema_file", "injected_tool", "none"),
+  }),
+  resume: Type.Object({
+    support: strings("supported", "unsupported"),
+    mechanism: Type.Optional(Type.String()),
+    conditions: Type.Array(Type.String()),
+  }),
+  budget: strings("enforced", "not_enforced"),
+  cost: Type.Object({
+    kind: strings("native", "estimated", "partial", "unknown"),
+    conditions: Type.Array(Type.String()),
+  }),
+  retries: Type.Object({
+    extension: strings("none", "once_on_infrastructure"),
+    native: strings("none", "internal", "unknown"),
+  }),
+  nestedAgentDetection: Type.Boolean(),
+  permissions: Type.Object({
+    default: strings("readonly", "edit", "danger"),
+    tiers: Type.Object({
+      readonly: permissionTierCapabilitySchema,
+      edit: permissionTierCapabilitySchema,
+      danger: permissionTierCapabilitySchema,
+    }),
+    caveats: Type.Array(Type.String()),
+  }),
+  context: Type.Object({
+    modes: Type.Tuple([Type.Literal("none"), Type.Literal("recent"), Type.Literal("full")]),
+    maxBytes: Type.Integer({ minimum: 1 }),
+    resumeConflict: Type.Literal(true),
+  }),
+  resources: Type.Optional(
+    Type.Object({
+      skills: strings("none", "user", "user_and_project"),
+      extensions: Type.Literal("none"),
+      promptTemplates: Type.Literal("none"),
+      themes: Type.Literal("none"),
+    }),
+  ),
+});
+
+export type CapabilityRecordSchema = Static<typeof capabilityRecordSchema>;
+
+const capabilitiesTopicDataSchema = Type.Object({
+  topic: Type.Literal("capabilities"),
+  harness: Type.Optional(Type.String()),
+  harnesses: Type.Array(capabilityRecordSchema),
+});
+
 export const externalHelpOutputSchema = contractEnvelope(
   EXTERNAL_HELP_TOOL,
   Type.Literal("help"),
-  Type.Union([proseTopicDataSchema, contractsTopicDataSchema]),
+  Type.Union([proseTopicDataSchema, contractsTopicDataSchema, capabilitiesTopicDataSchema]),
   Type.Null(),
 );
 
@@ -372,14 +444,15 @@ export const PUBLIC_TOOLS: Record<PublicToolName, PublicToolSpec> = {
     tool: EXTERNAL_HELP_TOOL,
     contractVersion: 1,
     actions: ["help"],
-    purpose: "Read-only help for usage, roles, permissions, workflows, and contracts.",
+    purpose: "Read-only help for usage, roles, permissions, workflows, contracts, and capabilities.",
     input: externalHelpParameters,
     output: externalHelpOutputSchema,
     semantics: [
       "Read-only discovery: spawns no CLIs, reads no credentials, calls no providers, and writes no files.",
       "Blank/whitespace harness and tool placeholders normalize to omitted (#62).",
-      "Unknown harness on roles/permissions or unknown tool on contracts returns ok:false with code 'selection_invalid' and data:null.",
-      "Prose topics (usage, roles, permissions, workflow) return data:{topic, harness?, text}; contracts returns data:{topic:'contracts', index} or data:{topic:'contracts', tool, contract}.",
+      "Unknown harness on roles/permissions/capabilities or unknown tool on contracts returns ok:false with code 'selection_invalid' and data:null.",
+      "Prose topics (usage, roles, permissions, workflow) return data:{topic, harness?, text}; contracts returns data:{topic:'contracts', index} or data:{topic:'contracts', tool, contract}; capabilities returns data:{topic:'capabilities', harness?, harnesses}.",
+      "Capability readiness is always 'not_probed' (configuration does not prove installation or authentication); every harness returns PublicRun receipts while workflowChildSchema describes workflow agent({ schema }) support.",
     ],
     examples: [
       {
@@ -411,6 +484,30 @@ export const PUBLIC_TOOLS: Record<PublicToolName, PublicToolSpec> = {
           warnings: [],
         },
       },
+      {
+        label: "capabilities_detail",
+        input: { topic: "capabilities", harness: "claude" },
+        output: {
+          contractVersion: 1,
+          tool: EXTERNAL_HELP_TOOL,
+          action: "help",
+          observedAt: EXAMPLE_OBSERVED_AT,
+          ok: true,
+          data: {
+            topic: "capabilities",
+            harness: "claude",
+            harnesses: [
+              buildCapabilityRecord({
+                harness: "claude",
+                backend: "claude",
+                configuration: { state: "built_in", enabled: true },
+                options: { effectiveUid: 501, platform: "linux", defaultPermission: "danger" },
+              }),
+            ],
+          },
+          warnings: [],
+        },
+      },
       {
         label: "unknown_tool_selector",
         input: { topic: "contracts", tool: "unknown_tool" },

package/src/core/capabilities.ts

@@ -0,0 +1,615 @@
+import { effectivePiResourcePreset } from "../harnesses.ts";
+import { loadExternalCatalog } from "../profiles.ts";
+import { loadExternalSettings } from "../settings.ts";
+import {
+  EXTERNAL_HARNESSES,
+  type ExternalHarness,
+  type PermissionTier,
+  type PiResourcePreset,
+  type SubagentBackend,
+} from "../types.ts";
+import { ExpectedFlowError } from "./errors.ts";
+import { PARENT_CONTEXT_MAX_BYTES } from "./parent-context.ts";
+import {
+  buildPermissionArgs,
+  PI_TIER_ACTIVE_TOOLS,
+  resolvePermission,
+  unsupportedPermissionReason,
+} from "./permissions.ts";
+
+export interface BackendCapabilityDescriptor {
+  boundary: "external_cli" | "pi_sdk";
+  workflowChildSchema: {
+    support: "supported" | "unsupported";
+    mechanism: "cli_flag" | "schema_file" | "injected_tool" | "none";
+  };
+  resume: {
+    support: "supported" | "unsupported";
+    mechanism?: string;
+    conditions: readonly string[];
+  };
+  budget: "enforced" | "not_enforced";
+  cost: {
+    kind: "native" | "estimated" | "partial" | "unknown";
+    conditions: readonly string[];
+  };
+  retries: {
+    extension: "none" | "once_on_infrastructure";
+    native: "none" | "internal" | "unknown";
+  };
+  nestedAgentDetection: boolean;
+  /** Backend-level permission caveats that no per-tier helper computes. */
+  permissionCaveats: readonly string[];
+}
+
+export const PERMISSION_TIERS: readonly PermissionTier[] = ["readonly", "edit", "danger"];
+
+/**
+ * Single metadata source for backend capability facts that no existing helper
+ * computes. Per-tier support/enforcement/caveats and Pi tool lists are derived
+ * from `src/core/permissions.ts`, and the context byte ceiling is imported from
+ * `src/core/parent-context.ts`. Conformance tests in `test/capabilities.test.ts`
+ * verify every field here against the actual adapter implementations.
+ */
+export const BACKEND_CAPABILITIES: Readonly<Record<SubagentBackend, BackendCapabilityDescriptor>> = {
+  claude: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "supported", mechanism: "cli_flag" },
+    resume: {
+      support: "supported",
+      mechanism: "--resume",
+      conditions: [
+        "Requires a completed claude run record with a sessionId.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "enforced",
+    cost: {
+      kind: "native",
+      conditions: [
+        "Reported natively by Claude Code (total_cost_usd or modelUsage costUSD); costKnown is false when absent.",
+      ],
+    },
+    retries: { extension: "none", native: "unknown" },
+    nestedAgentDetection: true,
+    permissionCaveats: [
+      "danger uses --dangerously-skip-permissions (--permission-mode auto under effective UID 0).",
+      "The requested tier is used as-is; role names do not raise it.",
+    ],
+  },
+  codex: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "supported", mechanism: "schema_file" },
+    resume: {
+      support: "supported",
+      mechanism: "exec resume",
+      conditions: [
+        "Requires a completed codex run record with a sessionId.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "estimated",
+      conditions: [
+        "Estimated from local price table for mapped models (gpt-5.5, gpt-5.4, gpt-5.4-mini) with costEstimated: true; costKnown is false when the model is unmapped.",
+      ],
+    },
+    retries: { extension: "none", native: "unknown" },
+    nestedAgentDetection: true,
+    permissionCaveats: [
+      "Sandbox flags govern model-generated shell commands, not MCP, plugins, or hooks.",
+    ],
+  },
+  agy: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "supported", mechanism: "cli_flag" },
+    resume: {
+      support: "supported",
+      mechanism: "--conversation",
+      conditions: [
+        "Requires a completed agy run record with a sessionId.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "unknown",
+      conditions: [
+        "Antigravity reports token counts only; costKnown is always false.",
+      ],
+    },
+    retries: { extension: "once_on_infrastructure", native: "unknown" },
+    nestedAgentDetection: true,
+    permissionCaveats: [
+      "Autonomous only: every accepted run uses --dangerously-skip-permissions and is unsandboxed.",
+      "readonly and edit are rejected instead of being broadened to danger.",
+    ],
+  },
+  grok: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "supported", mechanism: "cli_flag" },
+    resume: {
+      support: "supported",
+      mechanism: "--resume",
+      conditions: [
+        "Requires a completed grok run record with a sessionId.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "native",
+      conditions: [
+        "Reported natively by Grok CLI (total_cost_usd or modelUsage costUSD); costKnown is false when absent.",
+      ],
+    },
+    retries: { extension: "none", native: "unknown" },
+    nestedAgentDetection: true,
+    permissionCaveats: [
+      "Enforced by a kernel sandbox alongside --permission-mode bypassPermissions, but readonly network blocking is Linux-only.",
+    ],
+  },
+  muse: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "supported", mechanism: "schema_file" },
+    resume: {
+      support: "supported",
+      mechanism: "--session-id",
+      conditions: [
+        "Requires a completed muse run record with a sessionId.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "unknown",
+      conditions: [
+        "Muse has not been observed to report token usage or cost; costKnown is always false.",
+      ],
+    },
+    retries: { extension: "none", native: "internal" },
+    nestedAgentDetection: false,
+    permissionCaveats: [
+      "danger (--yolo) disables approval and the sandbox and additionally trusts this workspace (loads its skills/rules) for this run — a broader grant than an unsandboxed run alone.",
+      "Native provider retries (up to 10 attempts) are disclosed via activity narration, not performed by this extension.",
+    ],
+  },
+  opencode: {
+    boundary: "external_cli",
+    workflowChildSchema: { support: "unsupported", mechanism: "none" },
+    resume: {
+      support: "supported",
+      mechanism: "--session",
+      conditions: [
+        "Requires a completed opencode run record with a sessionId.",
+        "Refused at readonly/edit when the saved session carries its own permission rules.",
+        "Refused at danger when the session was last run by an injected restricted agent.",
+        "Cannot be combined with context sharing (recent/full).",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "partial",
+      conditions: [
+        "Summed from exported turn assistant messages; costKnown is false when any message lacks usage/cost or ran subagent.",
+      ],
+    },
+    retries: { extension: "none", native: "internal" },
+    nestedAgentDetection: true,
+    permissionCaveats: [
+      "Every run is opencode run --standalone, a private server this run owns, never the shared background service.",
+      "readonly and edit run under a per-run agent injected through OPENCODE_CONFIG_CONTENT and selected with --agent on every run, resumes included; shell, subagent, web, MCP, and plugin tools are hidden, and edits outside the workspace are denied.",
+      "Resuming a session with its own permission rules at readonly/edit, or a restricted session at danger, is refused.",
+      "These are OpenCode application rules, not an OS sandbox, and project or user plugins and MCP servers still load and run their code.",
+      "Existing OPENCODE_CONFIG_CONTENT in the environment blocks restricted (readonly/edit) launches.",
+      "danger uses --auto, which approves every permission ask except explicit denies.",
+      "OpenCode retries transient provider errors itself (up to 10 retries); this extension does not retry.",
+    ],
+  },
+  pi: {
+    boundary: "pi_sdk",
+    workflowChildSchema: { support: "supported", mechanism: "injected_tool" },
+    resume: {
+      support: "unsupported",
+      conditions: [
+        "Pi children use an in-memory session and store no resumable sessionId.",
+      ],
+    },
+    budget: "not_enforced",
+    cost: {
+      kind: "native",
+      conditions: [
+        "Reported from Pi SDK session usage stats.",
+      ],
+    },
+    retries: { extension: "none", native: "none" },
+    nestedAgentDetection: false,
+    permissionCaveats: [
+      "Run in-process via the Pi SDK, not as a CLI.",
+      "That curated built-in tool list is not an OS sandbox; danger-tier bash has host access.",
+      "Each registration selects preset minimal (the default when the field is absent; skills stay unloaded) or skills (installed skills load; project skills load only when the project is trusted). Extensions, prompt templates, and themes stay unloaded.",
+      "Retry is disabled per child regardless of Pi's own settings.",
+    ],
+  },
+};
+
+export interface PermissionTierCapability {
+  supported: boolean;
+  enforced: boolean;
+  caveat?: string;
+  tools?: string[];
+}
+
+export interface CapabilityConfiguration {
+  state: "built_in" | "registered" | "invalid";
+  enabled: boolean;
+  diagnostics?: string[];
+  model?: string;
+  thinking?: string;
+  preset?: PiResourcePreset;
+}
+
+export interface PiCapabilityResources {
+  skills: "none" | "user" | "user_and_project";
+  extensions: "none";
+  promptTemplates: "none";
+  themes: "none";
+}
+
+export interface CapabilityRecord {
+  harness: string;
+  backend: SubagentBackend;
+  boundary: "external_cli" | "pi_sdk";
+  configuration: CapabilityConfiguration;
+  readiness: "not_probed";
+  workflowChildSchema: {
+    support: "supported" | "unsupported";
+    mechanism: "cli_flag" | "schema_file" | "injected_tool" | "none";
+  };
+  resume: {
+    support: "supported" | "unsupported";
+    mechanism?: string;
+    conditions: string[];
+  };
+  budget: "enforced" | "not_enforced";
+  cost: {
+    kind: "native" | "estimated" | "partial" | "unknown";
+    conditions: string[];
+  };
+  retries: {
+    extension: "none" | "once_on_infrastructure";
+    native: "none" | "internal" | "unknown";
+  };
+  nestedAgentDetection: boolean;
+  permissions: {
+    default: PermissionTier;
+    tiers: Record<PermissionTier, PermissionTierCapability>;
+    caveats: string[];
+  };
+  context: {
+    modes: ["none", "recent", "full"];
+    maxBytes: number;
+    resumeConflict: true;
+  };
+  resources?: PiCapabilityResources;
+}
+
+export interface CapabilityEnvironmentOptions {
+  effectiveUid?: number;
+  platform?: NodeJS.Platform;
+  projectTrusted?: boolean;
+  defaultPermission?: PermissionTier;
+}
+
+export function buildPermissionTierCapabilities(
+  backend: SubagentBackend,
+  options: Pick<CapabilityEnvironmentOptions, "effectiveUid" | "platform"> = {},
+): Record<PermissionTier, PermissionTierCapability> {
+  const effectiveUid = options.effectiveUid ?? process.geteuid?.();
+  const platform = options.platform ?? process.platform;
+  const buildTier = (tier: PermissionTier): PermissionTierCapability => {
+    const unsupported = unsupportedPermissionReason(tier, backend);
+    const resolved = resolvePermission(tier, backend);
+    let caveat = resolved.caveat;
+    if (backend === "claude" && tier === "danger" && effectiveUid === 0) {
+      caveat = "uses --permission-mode auto under effective UID 0";
+    } else if (backend === "grok" && tier === "readonly" && platform !== "linux") {
+      caveat = `${resolved.caveat} (inactive on ${platform})`;
+    }
+    const tools = backend === "pi" ? [...PI_TIER_ACTIVE_TOOLS[tier]] : undefined;
+    return {
+      supported: unsupported === undefined,
+      enforced: resolved.enforced,
+      ...(caveat ? { caveat } : {}),
+      ...(tools ? { tools } : {}),
+    };
+  };
+  return {
+    readonly: buildTier("readonly"),
+    edit: buildTier("edit"),
+    danger: buildTier("danger"),
+  };
+}
+
+export function buildPiCapabilityResources(
+  preset: PiResourcePreset | undefined,
+  projectTrusted = false,
+): PiCapabilityResources {
+  const effectivePreset = effectivePiResourcePreset(preset);
+  return {
+    skills: effectivePreset === "minimal" ? "none" : projectTrusted ? "user_and_project" : "user",
+    extensions: "none",
+    promptTemplates: "none",
+    themes: "none",
+  };
+}
+
+function harnessLevelDiagnostics(
+  harness: string,
+  catalogDiagnostics: readonly string[],
+): string[] {
+  const problems: string[] = [];
+  for (const diag of catalogDiagnostics) {
+    if (diag.startsWith("Invalid override directory ") && diag.endsWith(`/${harness}`)) {
+      problems.push(diag);
+    }
+  }
+  return problems;
+}
+
+export function buildCapabilityRecord(params: {
+  harness: string;
+  backend: SubagentBackend;
+  configuration: CapabilityConfiguration;
+  options?: CapabilityEnvironmentOptions;
+}): CapabilityRecord {
+  const { harness, backend, configuration, options = {} } = params;
+  const descriptor = BACKEND_CAPABILITIES[backend];
+  const defaultPermission = options.defaultPermission ?? "danger";
+  const resources =
+    backend === "pi"
+      ? buildPiCapabilityResources(configuration.preset, options.projectTrusted === true)
+      : undefined;
+  return {
+    harness,
+    backend,
+    boundary: descriptor.boundary,
+    configuration,
+    readiness: "not_probed",
+    workflowChildSchema: { ...descriptor.workflowChildSchema },
+    resume: {
+      support: descriptor.resume.support,
+      ...(descriptor.resume.mechanism ? { mechanism: descriptor.resume.mechanism } : {}),
+      conditions: [...descriptor.resume.conditions],
+    },
+    budget: descriptor.budget,
+    cost: {
+      kind: descriptor.cost.kind,
+      conditions: [...descriptor.cost.conditions],
+    },
+    retries: { ...descriptor.retries },
+    nestedAgentDetection: descriptor.nestedAgentDetection,
+    permissions: {
+      default: defaultPermission,
+      tiers: buildPermissionTierCapabilities(backend, options),
+      caveats: [...descriptor.permissionCaveats],
+    },
+    context: {
+      modes: ["none", "recent", "full"],
+      maxBytes: PARENT_CONTEXT_MAX_BYTES,
+      resumeConflict: true,
+    },
+    ...(resources ? { resources } : {}),
+  };
+}
+
+export interface BuildCapabilitiesOptions extends CapabilityEnvironmentOptions {
+  agentDir: string;
+  harness?: string;
+}
+
+export function buildCapabilityRecords(options: BuildCapabilitiesOptions): CapabilityRecord[] {
+  const loadedSettings = loadExternalSettings(options.agentDir);
+  const catalog = loadExternalCatalog(options.agentDir);
+  const defaultPermission = options.defaultPermission ?? loadedSettings.settings.defaultPermission;
+  const envOptions: CapabilityEnvironmentOptions = {
+    effectiveUid: options.effectiveUid,
+    platform: options.platform,
+    projectTrusted: options.projectTrusted,
+    defaultPermission,
+  };
+
+  // When the catalog is blocked, registered pi-* names may be unreadable or
+  // untrustworthy, so none are guessed. Only built-in harnesses are selectable.
+  const configuredPiHarnesses = catalog.blocked ? new Set<string>() : new Set(catalog.harnessConfigs.keys());
+  if (options.harness !== undefined) {
+    if (
+      !(EXTERNAL_HARNESSES as readonly string[]).includes(options.harness) &&
+      !configuredPiHarnesses.has(options.harness)
+    ) {
+      const configured = [...EXTERNAL_HARNESSES, ...configuredPiHarnesses].sort();
+      throw new ExpectedFlowError(
+        "selection_invalid",
+        `Unknown harness "${options.harness}". Configured harnesses: ${configured.join(", ") || "none"}.`,
+      );
+    }
+  }
+
+  const targetHarnesses = options.harness
+    ? [options.harness]
+    : [...EXTERNAL_HARNESSES, ...[...configuredPiHarnesses].sort()];
+
+  return targetHarnesses.map((harness) => {
+    const isBuiltIn = (EXTERNAL_HARNESSES as readonly string[]).includes(harness);
+    const backend: SubagentBackend = isBuiltIn ? (harness as ExternalHarness) : "pi";
+    if (catalog.blocked) {
+      const diagnostic = catalog.diagnostics.join(" ").trim() || "Configuration is invalid.";
+      return buildCapabilityRecord({
+        harness,
+        backend,
+        configuration: {
+          state: "invalid",
+          enabled: false,
+          diagnostics: [diagnostic],
+        },
+        options: envOptions,
+      });
+    }
+
+    const hSettings = loadedSettings.settings.harnessSettings?.[harness];
+    // Binding overrides can repair defaults; the catalog validates each resolved binding.
+    const problems = harnessLevelDiagnostics(harness, catalog.diagnostics);
+    if (isBuiltIn) {
+      const model = hSettings?.model && hSettings.model !== "native" ? hSettings.model : undefined;
+      const thinking = hSettings?.thinking;
+      const configuration: CapabilityConfiguration = problems.length
+        ? {
+            state: "invalid",
+            enabled: false,
+            diagnostics: [problems.join(" ")],
+            ...(model ? { model } : {}),
+            ...(thinking ? { thinking } : {}),
+          }
+        : {
+            state: "built_in",
+            enabled: !catalog.disabledHarnesses.has(harness),
+            ...(model ? { model } : {}),
+            ...(thinking ? { thinking } : {}),
+          };
+      return buildCapabilityRecord({ harness, backend, configuration, options: envOptions });
+    }
+
+    const piConfig = catalog.harnessConfigs.get(harness)!;
+    const preset = effectivePiResourcePreset(piConfig.preset);
+    const thinking = hSettings?.thinking ?? piConfig.thinking;
+    const configuration: CapabilityConfiguration = problems.length
+      ? {
+          state: "invalid",
+          enabled: false,
+          diagnostics: [problems.join(" ")],
+          model: piConfig.model,
+          thinking,
+          preset,
+        }
+      : {
+          state: "registered",
+          enabled: !catalog.disabledHarnesses.has(harness),
+          model: piConfig.model,
+          thinking,
+          preset,
+        };
+    return buildCapabilityRecord({ harness, backend, configuration, options: envOptions });
+  });
+}
+
+export function formatCapabilitiesIndex(records: readonly CapabilityRecord[]): string {
+  const invalidDiag = records.find((r) => r.configuration.state === "invalid" && r.configuration.diagnostics?.length)
+    ?.configuration.diagnostics?.join(" ");
+  const rows = records.map((record) => {
+    const cfg = record.configuration;
+    const stateLabel =
+      cfg.state === "invalid"
+        ? "invalid (disabled)"
+        : `${cfg.state} (${cfg.enabled ? "enabled" : "disabled"})${cfg.model ? `, model=${cfg.model}` : ""}${cfg.preset ? `, preset=${cfg.preset}` : ""}`;
+    const supportedTiers = PERMISSION_TIERS.filter((t) => record.permissions.tiers[t].supported).join("/");
+    const schemaLabel =
+      record.workflowChildSchema.support === "supported"
+        ? `supported(${record.workflowChildSchema.mechanism})`
+        : "unsupported";
+    const resumeLabel =
+      record.resume.support === "supported"
+        ? `supported(${record.resume.mechanism})`
+        : "unsupported";
+    return `- ${record.harness} [${record.boundary}, ${stateLabel}]: tiers=${supportedTiers} · childSchema=${schemaLabel} · resume=${resumeLabel} · budget=${record.budget} · cost=${record.cost.kind}`;
+  });
+  return [
+    "Harness capabilities (readiness: not_probed; every harness returns structured PublicRun receipts; pass harness:\"<name>\" for full details):",
+    ...(invalidDiag ? [`Configuration diagnostics: ${invalidDiag}`] : []),
+    ...rows,
+    "",
+    "Readiness is not_probed (configuration is not authentication). Run /external config harness test <pi-harness> or /external doctor to check readiness.",
+  ].join("\n");
+}
+
+export function formatCapabilityDetail(record: CapabilityRecord): string {
+  const cfg = record.configuration;
+  const cfgParts = [
+    `state=${cfg.state}`,
+    `enabled=${cfg.enabled}`,
+    ...(cfg.model ? [`model=${cfg.model}`] : []),
+    ...(cfg.thinking ? [`thinking=${cfg.thinking}`] : []),
+    ...(cfg.preset ? [`preset=${cfg.preset}`] : []),
+  ];
+  const tierLines = PERMISSION_TIERS.map((tier) => {
+    const t = record.permissions.tiers[tier];
+    const status = !t.supported ? "unsupported" : t.enforced ? "supported (enforced)" : "supported (advisory)";
+    const tools = t.tools ? ` · tools: ${t.tools.join("/")}` : "";
+    const caveat = t.caveat ? ` · ${t.caveat}` : "";
+    return `- ${tier}: ${status}${tools}${caveat}`;
+  });
+  return [
+    `${record.harness} (backend: ${record.backend}, boundary: ${record.boundary})`,
+    `Configuration: ${cfgParts.join(", ")}`,
+    ...(cfg.diagnostics?.length ? [`Diagnostics: ${cfg.diagnostics.join("; ")}`] : []),
+    `Readiness: ${record.readiness} (configuration does not prove CLI installation or authentication; use /external config harness test or /external doctor).`,
+    "Operational receipts: PublicRun structuredContent supported on external_delegate, external_workflow, and external_runs.",
+    `Workflow child schema (agent({ schema })): ${record.workflowChildSchema.support} (mechanism: ${record.workflowChildSchema.mechanism}).`,
+    `Resume: ${record.resume.support}${record.resume.mechanism ? ` (${record.resume.mechanism})` : ""}. ${record.resume.conditions.join(" ")}`,
+    `Budget enforcement: ${record.budget}${record.budget === "enforced" ? " (enforced mid-run via --max-budget-usd when > 0)." : " (recorded in receipt with budgetEnforceable: false when set; not enforced mid-run)."}`,
+    `Cost reporting: ${record.cost.kind}. ${record.cost.conditions.join(" ")}`,
+    `Retries: extension=${record.retries.extension}, native=${record.retries.native}.`,
+    `Nested-agent activity detection: ${record.nestedAgentDetection ? "supported" : "disabled"}.`,
+    `Permissions (default: ${record.permissions.default}):`,
+    ...tierLines,
+    "Permission caveats:",
+    ...record.permissions.caveats.map((c) => `- ${c}`),
+    `Context: modes=${record.context.modes.join(", ")}, maxBytes=${record.context.maxBytes}, resumeConflict=${record.context.resumeConflict}.`,
+    ...(record.resources
+      ? [
+          `Resources (Pi SDK child): skills=${record.resources.skills}, extensions=${record.resources.extensions}, promptTemplates=${record.resources.promptTemplates}, themes=${record.resources.themes}.`,
+        ]
+      : []),
+  ].join("\n");
+}
+
+export function formatBackendPermissionHelp(
+  backend: SubagentBackend,
+  options: Pick<CapabilityEnvironmentOptions, "effectiveUid" | "platform"> = {},
+): string {
+  const descriptor = BACKEND_CAPABILITIES[backend];
+  const effectiveUid = options.effectiveUid ?? process.geteuid?.();
+  const tiers = buildPermissionTierCapabilities(backend, { ...options, effectiveUid });
+  if (backend === "pi") {
+    const tierTools = PERMISSION_TIERS.map((tier) => `${tier} (${tiers[tier].tools!.join("/")})`).join(", ");
+    return `pi-* (named Pi harness configs): Tiers gate a curated built-in tool list per tier: ${tierTools}. ${descriptor.permissionCaveats.join(" ")}`;
+  }
+  const tierSummaries = PERMISSION_TIERS.map((tier) => {
+    const info = tiers[tier];
+    if (!info.supported) {
+      return `${tier} is unsupported (${info.caveat ?? "rejected before launch"})`;
+    }
+    const args = buildPermissionArgs(tier, backend, { effectiveUid });
+    const flagPart = args.length ? `uses ${args.join(" ")}` : "is enforced";
+    const caveatPart = info.caveat ? ` (${info.caveat})` : "";
+    return `${tier} ${flagPart}${caveatPart}`;
+  });
+  return `${backend}: ${tierSummaries.join(", ")}. ${descriptor.permissionCaveats.join(" ")}`;
+}
+
+export function formatPermissionHelp(
+  harness: string | undefined,
+  configuredPiHarnesses: ReadonlySet<string>,
+  options: Pick<CapabilityEnvironmentOptions, "effectiveUid" | "platform"> = {},
+): string {
+  const resolveBackend = (name: string): SubagentBackend =>
+    (EXTERNAL_HARNESSES as readonly string[]).includes(name) ? (name as ExternalHarness) : "pi";
+  const backends: SubagentBackend[] = harness
+    ? [resolveBackend(harness)]
+    : [...EXTERNAL_HARNESSES, ...(configuredPiHarnesses.size ? (["pi"] as const) : [])];
+  return [
+    "External CLIs and pi-* harnesses run with host access; use them only in trusted repositories. Permission is the call's explicit tier, otherwise the global defaultPermission (danger unless changed). A role describes intent and does not change that tier. Antigravity rejects readonly and edit.",
+    ...backends.map((backend) => formatBackendPermissionHelp(backend, options)),
+    "Failed or aborted runs are not silently retried. Only agy may retry once for an infrastructure-classified auth, eligibility, or network failure, and the receipt discloses it.",
+  ].join("\n\n");
+}

package/src/core/parent-context.ts

@@ -2,6 +2,8 @@ import { ExpectedFlowError } from "./errors.ts";
 import { buildSessionContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 
+export const PARENT_CONTEXT_MAX_BYTES = 1024 * 1024;
+
 export const parentContextSchema = Type.Union([
   Type.Object({ mode: Type.Literal("none") }, { additionalProperties: false }),
   Type.Object({ mode: Type.Literal("recent"), turns: Type.Integer({ minimum: 1 }) }, { additionalProperties: false }),
@@ -104,7 +106,7 @@ export function prepareParentContext(
   const text = JSON.stringify(transcript);
   const bytes = Buffer.byteLength(text, "utf8");
   // ponytail: fixed transport ceiling, backend-specific token budgeting if needed.
-  if (bytes > 1024 * 1024) throw new ExpectedFlowError("context_invalid", "Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
+  if (bytes > PARENT_CONTEXT_MAX_BYTES) throw new ExpectedFlowError("context_invalid", "Parent context is too large (over 1 MiB); share fewer turns or provide a text briefing. Nothing was truncated.");
   const receipt: ParentContextReceipt = { mode: context.mode, ...(context.mode === "recent" ? { requestedTurns: context.turns } : {}), sharedTurns, messages: transcript.length, bytes, compacted };
   return {
     context: receipt,

package/src/core/spawn.ts

@@ -38,6 +38,7 @@ import type {
 } from "../types.ts";
 import { selectorHarness } from "../profiles.ts";
 import { PI_TIER_ACTIVE_TOOLS, resolvePermission, resolveEffectivePermissionTier, unsupportedPermissionReason } from "./permissions.ts";
+import { BACKEND_CAPABILITIES } from "./capabilities.ts";
 import { resolveResume } from "./resume.ts";
 import { formatParentContext, type ParentContextReceipt } from "./parent-context.ts";
 import { createRunRecord, type RunRecord } from "./run-record.ts";
@@ -259,7 +260,7 @@ function resolvedRunReceipt(input: {
     },
     ...(input.maxBudgetUsd !== undefined ? { maxBudgetUsd: input.maxBudgetUsd } : {}),
     // Budgets are enforced mid-run only where the backend supports a native cap (claude).
-    ...(input.maxBudgetUsd !== undefined && input.backend !== "claude" ? { budgetEnforceable: false as const } : {}),
+    ...(input.maxBudgetUsd !== undefined && BACKEND_CAPABILITIES[input.backend].budget !== "enforced" ? { budgetEnforceable: false as const } : {}),
   };
 }
 
@@ -430,7 +431,7 @@ export async function spawnSubagent(params: SpawnSubagentParams): Promise<AgentT
       permissionEffective: permission,
       timeoutMs: params.timeoutMs,
       maxBudgetUsd: params.maxBudgetUsd ?? null,
-      budgetEnforced: (params.maxBudgetUsd ?? 0) > 0 && params.profile.backend === "claude",
+      budgetEnforced: (params.maxBudgetUsd ?? 0) > 0 && BACKEND_CAPABILITIES[params.profile.backend].budget === "enforced",
       resumeRunId: params.resumeRunId ?? null,
     },
   });

package/src/core/subagent-render.ts

@@ -1,6 +1,7 @@
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Text, TruncatedText, type Component } from "@earendil-works/pi-tui";
 import { getBackendAgentLabel } from "./display.ts";
+import { BACKEND_CAPABILITIES } from "./capabilities.ts";
 import { formatParentContext, type ParentContextReceipt } from "./parent-context.ts";
 import { SPINNER_FRAMES } from "./spinner.ts";
 import type { PermissionTier, SubagentAssistantOutput, SubagentBackend, SubagentRunStatus, SubagentUsage } from "../types.ts";
@@ -173,7 +174,7 @@ function richTitle(node: RenderableSubagentNode): string {
 function formatRuntimeAndUsage(node: RenderableSubagentNode, now: number, showAccess = true): string {
   const parts: string[] = [];
   if (showAccess && isActiveSubagentStatus(node.status)) {
-    parts.push("external host access");
+    parts.push(node.backend === "pi" ? "Pi SDK child · host access" : "external host access");
   }
   if (node.context) {
     const shared = node.context;
@@ -187,7 +188,7 @@ function formatRuntimeAndUsage(node: RenderableSubagentNode, now: number, showAc
   if (node.permissionDenials && node.permissionDenials > 0) {
     parts.push(`${node.permissionDenials} permission denials`);
   }
-  if (node.maxBudgetUsd !== undefined && node.backend && node.backend !== "claude") {
+  if (node.maxBudgetUsd !== undefined && node.backend && BACKEND_CAPABILITIES[node.backend].budget !== "enforced") {
     parts.push("budget unenforceable");
   }
   const startedAt = node.startedAt;

package/src/external-help.ts

@@ -19,6 +19,12 @@ import {
 } from "./contract/help.ts";
 import { formatExternalRunsActionGuidance } from "./contract/runs.ts";
 import { formatWorkflowHelpersLine } from "./contract/workflow.ts";
+import {
+  buildCapabilityRecords,
+  formatCapabilitiesIndex,
+  formatCapabilityDetail,
+  formatPermissionHelp,
+} from "./core/capabilities.ts";
 import { ExpectedFlowError, type FlowErrorCode } from "./core/errors.ts";
 import { disabledHarnessMessage, loadExternalCatalog } from "./profiles.ts";
 import {
@@ -28,7 +34,7 @@ import {
   formatUsagePlaybook,
 } from "./prompts.ts";
 import { listSavedWorkflows } from "./workflow/registry.ts";
-import { EXTERNAL_HARNESSES, type ExternalHarness } from "./types.ts";
+import { EXTERNAL_HARNESSES } from "./types.ts";
 
 export { externalHelpParameters, type ExternalHelpParams } from "./contract/help.ts";
 
@@ -49,37 +55,6 @@ function isProjectTrusted(ctx: ExtensionContext): boolean {
   }
 }
 
-const PERMISSION_HELP_BY_BACKEND: Record<ExternalHarness | "pi", string> = {
-  agy: "agy: autonomous only. Every accepted run uses --dangerously-skip-permissions and is unsandboxed. readonly and edit are rejected instead of being broadened to that mode.",
-  claude: "claude: readonly uses --permission-mode plan, edit uses --permission-mode acceptEdits, and danger uses --dangerously-skip-permissions (--permission-mode auto under effective UID 0). Headless readonly/edit deny Bash. The requested tier is used as-is; role names do not raise it.",
-  codex: "codex: readonly, edit, and danger map to read-only, workspace-write, and danger-full-access sandboxes. This governs model-generated shell commands, not MCP/plugins/hooks.",
-  grok: "grok: readonly uses --sandbox read-only, edit uses --sandbox workspace, and danger uses --sandbox off, always alongside --permission-mode bypassPermissions. Enforced by a kernel sandbox, but network blocking is Linux-only; edit limits writes to the workspace.",
-  muse: "muse: readonly uses --disable-approval --disable-write --disable-shell (approval, non-shell writes, and shell execution all disabled), edit uses --disable-approval alone (the sandbox stays enabled by default; writes and shell remain available within it), and danger uses --yolo, which disables approval and the sandbox and additionally trusts this workspace (loads its skills/rules) for this run — a broader grant than an unsandboxed run alone. Native provider retries (up to 10 attempts) are disclosed via activity narration, not performed by this extension.",
-  opencode: "opencode (OpenCode 2): every run is `opencode run --standalone`, a private server this run owns, never the shared background service. readonly and edit run under a per-run agent injected through OPENCODE_CONFIG_CONTENT and selected with --agent on every run, resumes included, whose permission rules deny every tool except read/grep/glob (readonly) or those plus edit/write/patch (edit); shell, subagent, web, MCP, and plugin tools are hidden, and edits outside the workspace are denied. Resuming a session with its own permission rules at readonly/edit, or a restricted session at danger, is refused. These are OpenCode application rules, not an OS sandbox, and project or user plugins and MCP servers still load and run their code. danger uses --auto, which approves every permission ask except explicit denies. OpenCode retries transient provider errors itself (up to 10 retries); this extension does not retry.",
-  pi: "pi-* (named Pi harness configs): run in-process, not as a CLI. Tiers gate a curated built-in tool list (read/bash/edit/write/grep/find/ls). That list is not an OS sandbox; danger-tier bash has host access. Each registration selects preset minimal (the default when the field is absent; skills stay unloaded) or skills (installed skills load; project skills load only when the project is trusted). Extensions, prompt templates, and themes stay unloaded. Retry is disabled per child regardless of Pi's own settings.",
-};
-
-/** Resolve a requested, already-validated harness name to its permission-semantics backend. */
-function permissionHelpBackend(harness: string, configuredPiHarnesses: ReadonlySet<string>): ExternalHarness | "pi" {
-  if ((EXTERNAL_HARNESSES as readonly string[]).includes(harness)) return harness as ExternalHarness;
-  // Callers only reach here after validateHarnessFilter, so any name that is
-  // not one of the external harnesses is guaranteed to be a registered
-  // pi-* harness at this point — never an unrecognized string silently
-  // treated as "pi".
-  return "pi";
-}
-
-function permissionHelp(harness: string | undefined, configuredPiHarnesses: ReadonlySet<string>): string {
-  const backends: (ExternalHarness | "pi")[] = harness
-    ? [permissionHelpBackend(harness, configuredPiHarnesses)]
-    : [...EXTERNAL_HARNESSES, ...(configuredPiHarnesses.size ? (["pi"] as const) : [])];
-  return [
-    "External CLIs and pi-* harnesses run with host access; use them only in trusted repositories. Permission is the call's explicit tier, otherwise the global defaultPermission (danger unless changed). A role describes intent and does not change that tier. Antigravity rejects readonly and edit.",
-    ...backends.map((name) => PERMISSION_HELP_BY_BACKEND[name]),
-    "Failed or aborted runs are not silently retried. Only agy may retry once for an infrastructure-classified auth, eligibility, or network failure, and the receipt discloses it.",
-  ].join("\n\n");
-}
-
 /**
  * Reject an unknown harness filter up front, listing the live configured
  * set, rather than letting it silently fall through to "pi" (permissions)
@@ -151,7 +126,7 @@ export function createExternalHelpTool(
   return defineTool({
     name: EXTERNAL_HELP_TOOL,
     label: "External Help",
-    description: "Read-only help on demand: usage playbook, role details, permission behavior, workflow usage (including background runs, external_runs supervision syntax, and replay) or saved-workflow discovery, and public tool contracts.",
+    description: "Read-only help on demand: usage playbook, role details, permission behavior, workflow usage (including background runs, external_runs supervision syntax, and replay) or saved-workflow discovery, public tool contracts, and per-harness capabilities.",
     promptSnippet: EXTERNAL_HELP_PROMPT_SNIPPET,
     parameters: externalHelpParameters,
     outputSchema: externalHelpOutputSchema,
@@ -183,6 +158,20 @@ export function createExternalHelpTool(
           };
         }
 
+        if (params.topic === "capabilities") {
+          const harnesses = buildCapabilityRecords({
+            agentDir: getAgentDir(),
+            harness,
+            projectTrusted: isProjectTrusted(ctx),
+          });
+          const text = harness ? formatCapabilityDetail(harnesses[0]!) : formatCapabilitiesIndex(harnesses);
+          return {
+            content: [{ type: "text" as const, text }],
+            details: { topic: "capabilities" as const, ...(harness ? { harness } : {}) },
+            data: { topic: "capabilities" as const, ...(harness ? { harness } : {}), harnesses },
+          };
+        }
+
         let text: string;
         const catalog = loadExternalCatalog(getAgentDir());
         const harnessConfigs = catalog.harnessConfigs;
@@ -199,7 +188,7 @@ export function createExternalHelpTool(
             : harness && catalog.disabledHarnesses.has(harness) ? disabledHarnessMessage(harness)
             : formatExternalRoleHelp(catalog.profiles, options.getDefaultHarness(ctx), harness);
         } else if (params.topic === "permissions") {
-          text = permissionHelp(harness, configuredPiHarnesses);
+          text = formatPermissionHelp(harness, configuredPiHarnesses);
         } else {
           const wfText = workflowHelp(options.workflowEnabled, listSavedWorkflows({
             agentDir: getAgentDir(),

package/src/prompts.ts

@@ -10,7 +10,7 @@ export const WORKFLOW_PROMPT_SNIPPET =
   "Run requested multi-agent orchestration with external roles; when useful read the bundled pi-flow-orchestration skill to select the smallest fitting pattern. Use external_help for exact syntax and saved workflows.";
 
 export const EXTERNAL_HELP_PROMPT_SNIPPET =
-  "Show the delegation playbook, role details, permission behavior, workflow guidance, or public contracts on demand.";
+  "Show the delegation playbook, role details, permission behavior, workflow guidance, public contracts, or harness capabilities on demand.";
 
 export const EXTERNAL_RUNS_PROMPT_SNIPPET =
   "Supervise session-owned external runs (supply only fields for the chosen action): list (optional workflowRunId, limit, cursor, workflowCursor), inspect (runIds: 1 ID with any view, or 2-20 IDs for summary batch), wait (runIds 1-100, optional mode/limitBytes), or cancel (runIds: 1 ID, optional reason). view: final returns only a verified terminal answer, empty until one exists.";
@@ -105,7 +105,7 @@ Choose a fresh child or resume on purpose. Omit context for independent work. co
 
 Default to foreground (blocking) when you need the result next, including parallel workflows. When you have independent local work (read, edit, bash) that does not touch files the delegated run may change, or the user asks for background execution, pass background:true, do that other work first, and only call external_runs wait once you actually need the result; never background then immediately wait. Ending a turn does not stop a background run: if the user asks to leave it running, switch tasks, or check back later, report the runId and end your turn or work on the other task without waiting. Otherwise retain the runId and collect it in this turn after your independent work finishes. Foreground has a live card; a background receipt is not a live monitor, though UI sessions show active background runs in the status bar and wake the session with a follow-up message when an uncollected background run settles across turns. Use external_runs wait only when needed; check each run's outcome and pending IDs. Read inline successful output or inspect view final; inspect failures with diagnostics. Interrupting foreground cancels that call; interrupting wait only stops waiting. Explicit cancel stops background work. Keep the owning session open: orderly shutdown requests cancellation; restart does not adopt work. Prefer one external_workflow with parallel() for coordinated parallel tasks; all children share maxConcurrentSubagents. Sequential awaits stay serial. Report milestones. Retry a failed run, or switch its model or harness, only when the user authorized that step. agy alone may make one disclosed infrastructure retry. Nested agents may start in another workspace.
 
-Catalog availability reflects enabled harnesses and built-in/authored roles, not CLI installation or authentication. Disabled harnesses reject calls without fallback; manage them through /external config. Harness and role lifecycle commands live under /external config harness and /external config role. Role selection never falls back. external_help topic usage is the playbook; roles, permissions, workflow, and contracts are the references.`;
+Catalog availability reflects enabled harnesses and built-in/authored roles, not CLI installation or authentication. Disabled harnesses reject calls without fallback; manage them through /external config. Harness and role lifecycle commands live under /external config harness and /external config role. Role selection never falls back. external_help topic usage is the playbook; roles, permissions, workflow, contracts, and capabilities are the references.`;
 }
 
 export interface UsageAgentExample {
@@ -210,7 +210,7 @@ export function formatUsagePlaybook(): string {
 
 A named pi-* harness runs in-process on the SDK's built-in tools. Preset minimal leaves skills unloaded. Preset skills loads installed skills, and project skills only when the project is trusted. Those presets select skill loading. They are not this extension's tools and they are not web search. Resume does not continue a pi-* child, and a budget there is recorded without enforcement.
 
-Tell each child the objective, the context it needs, what it may change, the deliverable, and how you will verify it. Use absolute paths. Say read-only or edit in the prompt. Omit permission to keep defaultPermission (danger unless changed), including a reviewer that may use a shell and still must not edit. Pass permission only to confine the call below that default. A danger tier stays inside the authorization the user already gave. Antigravity accepts only danger. Topic permissions is the harness-boundary reference. Topic roles lists descriptions. Topic workflow is the syntax and saved-workflow reference. Topic contracts is the public schema and error-code reference (pass tool for one tool's schemas and examples).
+Tell each child the objective, the context it needs, what it may change, the deliverable, and how you will verify it. Use absolute paths. Say read-only or edit in the prompt. Omit permission to keep defaultPermission (danger unless changed), including a reviewer that may use a shell and still must not edit. Pass permission only to confine the call below that default. A danger tier stays inside the authorization the user already gave. Antigravity accepts only danger. Topic permissions is the harness-boundary reference. Topic roles lists descriptions. Topic workflow is the syntax and saved-workflow reference. Topic contracts is the public schema and error-code reference (pass tool for one tool's schemas and examples). Topic capabilities is the per-harness feature, permission, and resource reference (pass harness for one harness's full record; readiness is not_probed).
 
 Choose fresh context or resume deliberately. Omit context, or pass {"mode":"none"}, for independent work such as a review. {"mode":"recent","turns":N} and {"mode":"full"} share parent conversation and cannot be combined with resume. resume continues one prior CLI run that recorded a session id, on the same backend: ${EXTERNAL_HARNESSES.join(", ")}. A named pi-* harness has no persisted session, so resume does not continue it. Prefer resume for the same task and a new child when you want an independent judgment.