@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/skills/pi-subagents/SKILL.md

@@ -1,76 +1,80 @@
 ---
 name: pi-subagents
-description: "Pi subagent orchestration: delegate to builtin/custom agents; run single, parallel, chain, async/background, forked-context, acceptance, worktree, intercom, status/control, or agent-management workflows. Do not use for Agent Skill maintenance or non-Pi delegation."
+description: "Delegate one complete assignment to a native Pi child; inspect, continue, or stop saved child runs. Use for Pi delegation, not profile administration or non-Pi agents."
 ---
 
-# Pi Subagents
-
-Use this skill to coordinate focused Pi sessions. The original agent owns integration, review synthesis, and final delivery. Helpers with delegation enabled may split their assigned work when it saves time or improves quality. For Agent Skill file maintenance (`SKILL.md`, evals, trigger descriptions), use `agent-skill-engineering` instead.
-
-## Hard constraints
-
-- Prefer `delegate({ agent, task })` for a known profile; it enables run controls automatically. For discovery/history first, call `load_subagent({ advanced: false })`, then `agent_runs({ action: "profiles" })`. `agent_runs` provides list/inspect/history/search/nudge/continue/stop/questions/answer/review without loading the full schema.
-- For parallel groups, chains, detailed overrides, or profile administration, call `load_subagent` if `subagent` is inactive.
-- Discover profiles before execution with `agent_runs({ action: "profiles" })` or `subagent({ action: "list" })` unless already known; the list shows effective role, source, context and model/thinking/fallback defaults, marking unset choices as inherited rather than guessing runtime values.
-- Treat child output as evidence to inspect, not automatic truth. Record parent review with `agent_runs({ action: "review", id, decision: "accepted" | "needs_changes", message? })`; this is parent-only, not sent to the child, and never launches work. Put actionable instructions in continue/nudge.
-- The owned run list is attention-first and paged (default 20, maximum 100), not a history limit. Apply global `agent`/`state`/`text` filters and `sort`, then reuse the returned cursor with the same query; restart paging when it is stale. `history` reads bounded native previews for an owned `id`/child `index`; `search` accepts words or one quoted phrase, not operators or prefixes. Indexed freshness/excerpts never prove completion or delivery. Resume the same saved parent after reload/restart; inspect the original handle for concise results, paths and continuation history; use full:true for the full task/configuration. Live work precedes completed unreviewed rows.
-- `continue` and exited-question revival keep saved launch settings, including override pinning. Explicit `agent` selects the current profile's model, thinking and fallbacks; a separate `model` override wins. Old runs without a saved profile require `agent`. Override `cwd`, `output`, or `acceptance` for a new continuation as needed; live guidance/answers never mutate model or acceptance. A late nudge or inspect never restarts a finished child.
-- `continue`/`answer` with `async: false` waits for the actual continuation result. Important steers release foreground waits so the parent can respond while the child keeps working; completion arrives automatically.
-- Stop acknowledgement is a request, not proof of agent or command exit. Use the separately recorded agent-process outcome and actual native tool results; missing command results mean exit unconfirmed.
-- An observed human-only authentication boundary may report a criterion as `blocked`, with concrete `evidence` and an exact `humanAction`. Acceptance stays incomplete and finalization/verification stops until explicit Continue. Retain completed evidence; do not use this for ordinary errors or fixable work.
-- Keep writes single-threaded unless writers are isolated with `worktree: true`.
-- Use fresh-context reviewers for adversarial review; use forked `oracle` for inherited-decision/drift review. Fresh handoffs must include relevant exact original user instructions and settled decisions, or readable source references, alongside the bounded assignment. Summaries do not replace original requirements; the harness does not automatically forward the owner's transcript.
-- Keep bundled children as leaf agents and launch useful fanout from the parent. Nested helpers require explicit user authorization and an already-enabled profile within its native depth budget; do not infer permission to change nesting settings. Keep the original agent responsible for the complete result; do not repeat approvals for already-authorized work.
-- A reviewer timeout is not sign-off. Foreground reviewer budgets are raised to a safe floor; planner/researcher budgets are raised only from local history. Rerun, resume, or split timed-out work.
-- Subagent execution defaults to async/background. Launch a small bounded fanout as separate single-agent runs so each completion wakes the parent, with at most one writer. Continue useful parent work while children run; if none remains, end the turn and wait for completion instead of polling. Use one `tasks` call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require `worktree: true`; the parent receives one aggregate completion. Check status only when the user asks or the run may be blocked or stale.
-- An incomplete active Pi goal follows the same async workflow: if child evidence gates the next step, end the current turn and continue after automatic completion delivery. Do not advance past missing evidence. Use `async: false` for explicitly chosen foreground execution or a non-interactive one-shot caller that needs the result on stdout.
-- Use `acceptance` for goal-style requests and plan/spec/broad-fix worker handoffs; put criteria, evidence, verify commands, stop rules, and loop cap there instead of burying them only in task prose. Require only checks the child can run in its environment; keep checks that need unavailable services, credentials, devices, or deploys for the parent. Revived runs inherit that contract unless the resume call explicitly overrides `acceptance`.
-- Omit `acceptance` from review-only tasks unless the user explicitly requests a same-session acceptance contract; it adds a finalization turn and does not provide independent review.
-- Independent review stays parent-controlled: never put `review` inside `acceptance`; launch reviewer subagents separately after the worker completes.
-- Do not set `acceptance` on static parallel groups or dynamic fanout aggregate groups; set it on each child task/template that owns a session.
-
-## Agent selection
-
-Use effective agents from `agent_runs({ action: "profiles" })` or `subagent({ action: "list" })`; user/project profiles may replace builtin role behavior. Common roles:
-
-- `scout`: fast codebase recon and handoff context.
-- `context-builder`: stronger context/meta-prompt handoff builder.
-- `researcher`: evidence-driven technical research.
-- `watcher`: observation that needs ongoing interpretation; use ordinary tools for routine waiting and check collection. Define material transitions and a terminal condition.
-- `planner`: concrete implementation plans; should read and plan, not edit.
-- `worker`: single-writer implementation for approved scope.
-- `debugger`: root-cause diagnosis and repair evidence.
-- `fixer`: bounded remediation after findings are already decided.
-- `reviewer`: general implementation review.
-- `reviewer-gpt`: strict maintainability and correctness gate.
-- `reviewer-claude`: independent cross-model assumptions and product-risk review.
-- `reviewer-security`: security and data-safety review for trust boundaries.
-- `reviewer-ponytail`: over-engineering and slop review; uses the `ponytail` skill when installed and never trades away intended behavior.
-- `ui-designer`: rendered UI, layout, accessibility, and visual polish.
-- `writer`: human-facing documentation and polished copy.
-- `oracle`: forked advisory second opinion for direction, drift, and assumptions.
-- `delegate`: lightweight generic child; prefer a specialist or `worker` when the task has a real role.
-
-Profiles are reliable defaults, not override prohibitions. When warranted by the task, use `model: "provider/model:high"`, subject to user instructions and provider authorization; there is no standalone execution `thinking` argument. Explicit overrides pin route and effort: transient transport retries stay on that choice, with no profile fallback. On unavailability, the parent must choose a replacement. Ordinary launches keep profile fallbacks. Pass explicit `context: "fresh"` or `"fork"` only when one policy should override every child in the call. Fork is rejected for actual `anthropic/` primary or fallback candidates. A pinned non-Anthropic override excludes profile fallbacks; an Anthropic override remains ineligible.
-
-## Intercom bridge
-
-`pi-subagents` bundles its intercom extension. Children always get `contact_supervisor` unless an explicit agent `extensions` allowlist omits `pi-intercom`.
-
-- `contact_supervisor({ reason: "need_decision", message })`: steered blocking decision/clarification only when the ephemeral child cannot safely continue and must remain alive for one reply.
-- `contact_supervisor({ reason: "interview_request", message, interview })`: steered blocking structured questions only when the ephemeral child cannot safely continue until it receives multiple answers.
-- `contact_supervisor({ reason: "progress_update", message })`: a non-blocking discovery or change the supervisor needs while working, delivered at the next tool boundary. Skip starts, redundant narration, and routine completion; retain material findings in the final result.
-- Use `agent_runs({ action: "inspect", id })`, then `agent_runs({ action: "nudge", id, message })` for live child guidance, answers, corrections, or blockers. A nudge supplements the child's active task unless it explicitly says to replace it.
-- Blocking supervisor questions are persisted and do not use the ordinary two-minute ask timeout. After reload/reconnect, resume the same saved supervisor session, call `agent_runs({ action: "questions" })`, then `agent_runs({ action: "answer", id, questionId, message })`. A nudge is not a question answer.
-- Questions, answers, launch contracts, and results use persistent Pi session storage, not temporary logs. The live waiter reads the saved answer, or an exited child resumes its saved session with its saved launch configuration and acceptance contract. Identical repeated answers do not duplicate execution; an answer receipt is not run completion. `agent_runs({ action: "stop", id })` also cancels pending questions.
-- Load `load_intercom({})` if intercom is inactive. Use the status-shown `intercom({ action: "ask", delivery: "steer" })` only when the parent must remain alive waiting for a child reply.
-- Do not use intercom/contact_supervisor for routine completion handoffs; return normal child results.
-- If bridge messages do not appear, call `load_subagent({})` if needed, then `subagent({ action: "doctor" })`.
-
-## Detailed recipes
-
-Load `references/full-orchestration-guide.md` only when you need concrete `subagent(...)` call shapes, example workflow recipes, staged fix orchestration, settings, or edge cases. Do not reload it for every routine launch.
-
-## Stop rules
-
-Stop when the delegated work has produced the needed evidence, review/fix loops have no material remaining findings or hit a real blocker/cap, and the parent has verified enough to report accurately.
+# Pi delegation
+
+Use the eager `delegate` and `agent_runs` tools. There is one agent type and no
+profile discovery, loader, role body, chain DSL, or nested delegation.
+
+## Assignment
+
+```js
+delegate({
+  prompt: "Complete assignment with constraints and expected output",
+  name: "short-name",
+});
+```
+
+Supply the complete prompt: relevant original requirements, settled decisions or
+readable references, scope and files, authority and non-goals, verification venue,
+expected result, and stop boundary. Do not rely on a hidden profile to add them.
+
+Fresh context is default; `context:"fork"` preserves the native conversation,
+including prior tool results. A forked child still cannot delegate. Optional
+`cwd` and `model` are explicit launch overrides; do not change global auth/model
+settings to implement an override.
+`model:"provider/model:thinking"` uses Pi's native suffix resolver when the host
+exports it; a literal model ID wins before suffix parsing. Without that host API,
+use a literal ID with inherited thinking or upgrade Pi. Never retry another model
+silently.
+
+Every launch, continuation and guidance call returns a receipt; no tool waits for
+child completion. Continue useful independent work; when child evidence gates the
+next step, end the turn and let the completion notice resume you rather than
+polling `inspect`. A launch receipt is not completion. Review actual outputs and
+validation evidence before accepting the result.
+
+Keep the main session running for completion delivery. A one-shot print
+invocation exits after its final turn and stops any remaining children.
+
+## Controls
+
+- `agent_runs({action:"list"})` discovers this native main's saved runs.
+- `inspect` reads a run by ID; follow returned offsets for complete output.
+- `continue` takes a complete follow-up `prompt` and keeps the saved child chat.
+  Active work receives guidance; completed work gets an immutable successor.
+- `stop` requests termination. Inspect actual process evidence; request acceptance
+  does not prove actor or command exit.
+
+Use IDs returned by the tools. Runs belong to their native main session, not a
+cwd, project, name, or forked copy of its transcript. Resume the same main for
+ownership. Do not delete ambiguous launch state to force another attempt.
+
+Escape aborts the parent's reply, not already-launched children; `stop` ends one
+run. Children terminate when their parent exits. Resume the same parent and explicitly
+continue a saved child conversation; the child inspects the interrupted work
+rather than automatically replaying tool calls. Ordinary `/reload` is not exit.
+Under a fork launcher that provides `ctx.managedHost`, `pi restart` or `/restart`
+is not exit either: children keep running and report to the ready replacement.
+That needs one full CLI relaunch after upgrading; a worker under an older loaded
+launcher still stops children when it exits.
+
+## Coordination and delivery
+
+All pairs inside a main/children group can use `intercom` list/send/last. Across
+groups, mains alone can communicate. Children cannot see or address foreign
+groups, and cannot spawn children. `last` reads original completed assistant text
+without waking a peer; it is not a completion notification or replacement for
+run inspection.
+
+Keep writers isolated and integration parent-owned. Prefer bounded independent
+review with a fresh complete brief. Retain native SDK/journal/process boundary
+proof; a child-reported pass is evidence to inspect, not automatic sign-off.
+
+Normal child completion returns through the run, not a redundant intercom
+message. Use direct `send` for guidance, corrections, or blockers that affect live
+work. Ordinary `ask` is bounded request/reply, not durable supervisor revival.
+The [pi-intercom skill](../pi-intercom/SKILL.md) covers messaging operations.
+See [tools and lifecycle](../../docs/reference.md) for the owning contracts.

package/src/agent/contracts.ts

@@ -0,0 +1,118 @@
+import type { Static } from "typebox";
+import { Type } from "./typebox.ts";
+
+export const thinkingSchema = Type.Union([
+  Type.Literal("off"),
+  Type.Literal("minimal"),
+  Type.Literal("low"),
+  Type.Literal("medium"),
+  Type.Literal("high"),
+  Type.Literal("xhigh"),
+  Type.Literal("max"),
+]);
+export const launchSchema = Type.Object({
+  version: Type.Literal(1),
+  id: Type.String(),
+  rootId: Type.String(),
+  predecessor: Type.Optional(Type.String()),
+  owner: Type.String(),
+  cwd: Type.String(),
+  agentDir: Type.String(),
+  sdk: Type.String(),
+  entry: Type.String(),
+  sessionFile: Type.String(),
+  sessionId: Type.String(),
+  prompt: Type.String(),
+  context: Type.Union([Type.Literal("fresh"), Type.Literal("fork")]),
+  provider: Type.String(),
+  model: Type.String(),
+  thinking: thinkingSchema,
+  trusted: Type.Boolean(),
+  name: Type.Optional(Type.String()),
+  createdAt: Type.Number(),
+});
+export type Launch = Static<typeof launchSchema>;
+export const processSchema = Type.Object({
+  pid: Type.Integer({ minimum: 1 }),
+  identity: Type.String(),
+  token: Type.String(),
+  clock: Type.Optional(
+    Type.Object({
+      boot: Type.String(),
+      namespace: Type.String(),
+      at: Type.String({ pattern: "^[1-9][0-9]*$", maxLength: 20 }),
+    }),
+  ),
+});
+export type ProcessIdentity = Static<typeof processSchema>;
+export const attachmentSchema = Type.Object({
+  ...Type.Pick(processSchema, ["pid", "identity", "clock"]).properties,
+  generation: Type.String(),
+  attached: Type.Boolean(),
+});
+export type Attachment = Static<typeof attachmentSchema>;
+export const usageSchema = Type.Object({
+  input: Type.Number({ minimum: 0 }),
+  output: Type.Number({ minimum: 0 }),
+  cacheRead: Type.Number({ minimum: 0 }),
+  cacheWrite: Type.Number({ minimum: 0 }),
+  totalTokens: Type.Number({ minimum: 0 }),
+  reasoning: Type.Optional(Type.Number({ minimum: 0 })),
+  cacheWrite1h: Type.Optional(Type.Number({ minimum: 0 })),
+  cost: Type.Object({
+    input: Type.Number({ minimum: 0 }),
+    output: Type.Number({ minimum: 0 }),
+    cacheRead: Type.Number({ minimum: 0 }),
+    cacheWrite: Type.Number({ minimum: 0 }),
+    total: Type.Number({ minimum: 0 }),
+  }),
+});
+export const contributionsSchema = Type.Array(
+  Type.Object({
+    id: Type.String({ minLength: 1 }),
+    provider: Type.String(),
+    model: Type.String(),
+    usage: usageSchema,
+  }),
+);
+export type Contribution = Static<typeof contributionsSchema>[number];
+export const resultSchema = Type.Object({
+  id: Type.String(),
+  owner: Type.String(),
+  status: Type.Union([Type.Literal("completed"), Type.Literal("failed"), Type.Literal("stopped")]),
+  endedAt: Type.Number(),
+  terminalEntryId: Type.Optional(Type.String()),
+  error: Type.Optional(Type.String()),
+  contributions: Type.Optional(contributionsSchema),
+  accountingError: Type.Optional(Type.String()),
+  accountingPending: Type.Optional(
+    Type.Object({
+      terminalCandidate: Type.String(),
+      baseline: Type.Array(Type.String()),
+    }),
+  ),
+});
+export type Result = Static<typeof resultSchema>;
+export const commandSchema = Type.Object({
+  id: Type.String(),
+  runId: Type.String(),
+  action: Type.Union([Type.Literal("run"), Type.Literal("steer"), Type.Literal("stop")]),
+  prompt: Type.Optional(Type.String()),
+  actorToken: Type.Optional(Type.String()),
+  createdAt: Type.Number(),
+});
+export type Command = Static<typeof commandSchema>;
+export const successorSchema = Type.Object({ id: Type.String() });
+export const exitSchema = Type.Object({
+  pid: Type.Integer(),
+  code: Type.Union([Type.Integer(), Type.Null()]),
+  signal: Type.Union([Type.String(), Type.Null()]),
+  at: Type.Number(),
+});
+export const admissionSchema = Type.Object({
+  id: Type.String(),
+  action: Type.String(),
+  runId: Type.Optional(Type.String()),
+  state: Type.Optional(Type.Union([Type.Literal("accepted"), Type.Literal("stale")])),
+  at: Type.Number(),
+});

package/src/agent/cwd.ts

@@ -0,0 +1,69 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { write } from "./storage.ts";
+
+type Request = {
+  sessionManager: ExtensionContext["sessionManager"];
+  path?: string;
+  result?: { cwd?: string; error?: string };
+};
+export function localCwdOwner(source: { source: string; path: string }): boolean {
+  return /(?:^|[/\\:@])(?:pi-)?change-working-dir(?:[/\\@:.>]|$)/.test(
+    `${source.source}/${source.path}`,
+  );
+}
+function hasOwner(pi: ExtensionAPI): boolean {
+  return (
+    pi.getAllTools().some((tool) => tool.name === "change_dir" || localCwdOwner(tool.sourceInfo)) ||
+    pi
+      .getCommands()
+      .some(
+        (command) =>
+          command.source === "extension" &&
+          (/^cwd(?::\d+)?$/.test(command.name) || localCwdOwner(command.sourceInfo)),
+      )
+  );
+}
+function reply(request: Request): string | undefined {
+  if (request.result?.error !== undefined && request.result.error !== "") {
+    throw new Error(request.result.error);
+  }
+  if (request.result && (request.result.cwd === undefined || request.result.cwd === "")) {
+    throw new Error("Directory owner returned no execution directory.");
+  }
+  return request.result?.cwd;
+}
+export function executionCwd(pi: ExtensionAPI, ctx: ExtensionContext): string {
+  const request: Request = { sessionManager: ctx.sessionManager };
+  pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
+  const cwd = reply(request);
+  if (cwd === undefined && hasOwner(pi)) {
+    throw new Error("Loaded directory owner did not resolve cwd; update pi-change-working-dir.");
+  }
+  return cwd ?? ctx.cwd;
+}
+export function initializeCwd(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  cwd: string,
+  directory: string,
+): void {
+  // A saved continuation restores its owner's latest selection, not its frozen launch directory.
+  const current = executionCwd(pi, ctx);
+  const marker = path.join(directory, "cwd-initialized.json");
+  if (fs.existsSync(marker)) {
+    return;
+  }
+  if (hasOwner(pi) || fs.realpathSync(current) !== fs.realpathSync(ctx.cwd)) {
+    const request: Request = { sessionManager: ctx.sessionManager, path: cwd };
+    pi.events.emit("pi-change-working-dir:set-execution-cwd", request);
+    const selected = reply(request);
+    if (selected === undefined || fs.realpathSync(selected) !== fs.realpathSync(cwd)) {
+      throw new Error("Directory owner did not initialize the requested child cwd.");
+    }
+  } else if (fs.realpathSync(ctx.cwd) !== fs.realpathSync(cwd)) {
+    throw new Error("Native child directory does not match launch cwd.");
+  }
+  write(marker, { cwd }, true);
+}

package/src/agent/host.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findPackageJSON } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type * as SDK from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { readIntercomLineage } from "../pi-intercom/identity.ts";
+
+export { errorMessage as errorText } from "../shared/unknown.ts";
+
+// The native resolver is optional until official Pi exports it at the package root.
+type HostSDK = typeof SDK & {
+  resolveModelReference?: (
+    request: { text: string; provider: string; thinkingSuffix: "strict"; fuzzy: false },
+    models: readonly Model<Api>[],
+    usable: (provider: string) => boolean,
+  ) =>
+    | { status: "resolved"; model: Model<Api>; thinkingLevel?: ThinkingLevel }
+    | { status: "ambiguous" | "not-found" };
+};
+
+function isPackage(root: string): boolean {
+  const file = path.join(root, "package.json");
+  if (!fs.existsSync(file)) {
+    return false;
+  }
+  const value: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "name" in value &&
+    value.name === "@earendil-works/pi-coding-agent"
+  );
+}
+function launcherPackage(): string | undefined {
+  const entry = process.argv.at(1);
+  if (entry === undefined) {
+    return;
+  }
+  let directory = path.dirname(fs.realpathSync(entry));
+  while (directory !== path.dirname(directory)) {
+    if (isPackage(directory)) {
+      return directory;
+    }
+    directory = path.dirname(directory);
+  }
+  return undefined;
+}
+export function packageRoot(): string {
+  const configured = process.env.PI_PACKAGE_DIR;
+  if (configured !== undefined && configured.length > 0) {
+    if (!isPackage(configured)) {
+      throw new Error("PI_PACKAGE_DIR is not a Pi SDK.");
+    }
+    return configured;
+  }
+  const launcher = launcherPackage();
+  if (launcher !== undefined) {
+    return launcher;
+  }
+  const manifest = findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url);
+  if (manifest === undefined) {
+    throw new Error("Cannot locate the native Pi SDK.");
+  }
+  return path.dirname(manifest);
+}
+export async function loadSDK(root: string): Promise<HostSDK> {
+  // Selected host SDK, not a second package-local runtime hidden behind Jiti aliases.
+  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  const sdk: HostSDK = await import(pathToFileURL(path.join(root, "dist/index.js")).href);
+  return sdk;
+}
+export function runtimeEntry(): string {
+  return fileURLToPath(
+    new URL(import.meta.url.endsWith(".ts") ? "../index.ts" : "../index.js", import.meta.url),
+  );
+}
+export function isChild(): boolean {
+  return readIntercomLineage() !== undefined;
+}