@cr1ms0n/pi-subagent 0.8.1

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cr1ms0n/pi-subagent",
+  "version": "0.8.1",
+  "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
+  "type": "module",
+  "license": "MIT",
+  "author": "Luke Parke",
+  "contributors": [
+    "Luke Parke (upstream author)",
+    "cr1ms0n (fork maintainer)"
+  ],
+  "homepage": "https://www.npmjs.com/package/@cr1ms0n/pi-subagent",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "subagent",
+    "agents",
+    "coding-agent",
+    "extension",
+    "community-fork"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./sdk": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "skills",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/subagent.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}

package/skills/subagent/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: subagent
+description: Delegate work to isolated child agents with the subagent tool — model and thinking policy, explore/review/general profiles, parallel fanout with synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and backend tradeoffs (pi/codex/claude). Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
+---
+
+# Subagent
+
+Delegate research, parallel exploration, and clean-context implementation to child
+agents. Prefer `subagent` over long in-thread digressions when the work benefits
+from isolation, parallelism, or a fresh context.
+
+## When to use
+
+- Map a codebase area without bloating the parent context (`profile: "explore"`).
+- Review a diff read-only (`profile: "review"`).
+- Implement behind a worktree and land via apply (`profile: "general"`, `isolation: "worktree"`).
+- Fan out independent questions, optionally with `synthesis` to fold results.
+- Background long work (`async: true`) and collect later with `wait` / `subagent_wait`.
+
+## Core calls
+
+```ts
+// Examples use placeholders only. Replace these with the exact model selected
+// from the current modelPolicy route; they do not configure a real model.
+const routeModel = "<exact model from current modelPolicy route>";
+
+// Single foreground task (default profile: general)
+{ task: "Find call sites of parseConfig", description: "Map parseConfig", model: routeModel }
+
+// Parallel read-only explorers (default profile for tasks[]: explore)
+{
+  tasks: [
+    { task: "Map auth middleware", description: "Auth flow", model: routeModel },
+    { task: "List env vars in server/", description: "Env inventory", model: routeModel }
+  ],
+  synthesis: "Merge into one prioritized brief"
+}
+
+// Background — notified on completion; wait/status still work
+{ task: "Audit dependency licenses", model: routeModel, async: true }
+{ action: "status", id: "abc123" }
+{ action: "wait", id: "abc123" }           // interruptible; does not cancel
+{ action: "cancel", id: "abc123" }
+// Same wait semantics as a dedicated tool:
+// subagent_wait { id: "abc123", timeout_ms?: number }
+
+// Worktree loop
+{ task: "Implement feature A", model: routeModel, profile: "general", isolation: "worktree" }
+{ action: "diff", id: "abc123", index: 1 }
+{ action: "apply", id: "abc123", index: 1 }
+{ action: "discard", id: "abc123", index: 1 }
+
+// Dry-run validation + resolved plan (no spawn)
+// plan is a dry-run, but every task still needs the policy-routed model.
+{ action: "plan", tasks: [{ task: "…", model: routeModel, isolation: "worktree" }] }
+```
+
+## Profiles
+
+| Profile   | Tools                  | Writes                                      |
+| --------- | ---------------------- | ------------------------------------------- |
+| `explore` | read/search/ls (+safe) | no                                          |
+| `review`  | same as explore        | no                                          |
+| `general` | inherited active tools | yes if tools include bash/edit/write        |
+
+Parallel write-capable tasks sharing one checkout are rejected unless each uses
+`isolation: "worktree"`, a distinct `cwd`, or `allow_shared_writes: true`.
+
+## Backends
+
+`backend: "pi" | "codex" | "claude"` (default `pi`). Unsupported combinations are
+**refused**, not silently degraded:
+
+|                          | pi             | codex                  | claude         |
+| ------------------------ | -------------- | ---------------------- | -------------- |
+| `max_cost`               | yes            | refused (tokens only)  | yes            |
+| read-only profile        | tool allowlist | OS sandbox             | tool allowlist |
+| steering / grace wrap-up | yes            | no                     | no             |
+| `context: "fork"`        | yes            | refused                | yes            |
+| `thinking`               | yes            | no                     | no             |
+| `output_schema`          | yes            | yes                    | yes            |
+
+## Budgets and safety
+
+- Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
+- `output_schema` asks the child for a fenced `json:result` block (one repair round).
+- `context: "fork"` continues from a fork of the parent session (pi/claude).
+- Do not poll `status` in a tight loop — use `wait` / `subagent_wait`, or let the
+  completion notification arrive for `async: true` runs.
+- Point the user at `/subagents` for the live inspector and `/subagent-cost` for
+  the root / subagent / combined ledger.
+
+## Model policy
+
+Every new task must pass a `model` that exactly matches the current
+`modelPolicy` mapping in `~/.pi/subagent.json`; agent frontmatter,
+`taskDefaults.model`, and parent-session model inheritance are ignored. An
+agent route replaces the default route, and configured fallback order is
+immutable. Omit `fallback_models` to use the route; if supplied, it must match
+exactly. Management actions do not require model. The extension re-reads this
+policy on each dispatch and injects it into the parent prompt. If the policy is
+missing or invalid, management remains available but new spawns and synthesis
+are rejected.

package/src/agents.ts

@@ -0,0 +1,285 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { TaskProfile } from "./types.js";
+import type { ThinkingLevel } from "./config.js";
+import { isPlausibleSchema } from "./structured.js";
+
+/**
+ * Named agent files: reusable subagent personas discovered from the same
+ * conventional locations the ecosystem uses for skills.
+ *
+ * Discovery roots (highest precedence first — same name in a higher root wins):
+ *   1. <cwd>/.pi/agents/<name>.md            project (authoritative)
+ *   2. <cwd>/.agents/agents/<name>.md        shared cross-tool workspace
+ *   3. $PI_CODING_AGENT_DIR/agents/<name>.md global (default ~/.pi/agent/agents/)
+ *
+ * Format: YAML frontmatter + markdown body. The body becomes the child's
+ * appended system prompt. Frontmatter fields use the same snake_case names as
+ * the tool parameters they default.
+ *
+ * Model routing is intentionally excluded from agent files. Agent frontmatter
+ * may still contain legacy model/fallback fields for compatibility, but the
+ * model policy is the only source used for new spawns.
+ */
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+const PROFILES = ["explore", "review", "general"] as const;
+
+export interface AgentDefinition {
+  /** Agent CLI backend this persona runs on (pi | codex | claude). */
+  backend?: "pi" | "codex" | "claude";
+  /** Agent name (the file name without extension). */
+  name: string;
+  /** One-line routing description shown to the orchestrating model. */
+  description: string;
+  /** Markdown body — appended to the child's system prompt. */
+  systemPrompt?: string;
+  /** File the definition was loaded from. */
+  source: string;
+  /** Which discovery root supplied it. */
+  scope: "project" | "shared" | "global";
+  model?: string;
+  thinking?: ThinkingLevel;
+  profile?: TaskProfile;
+  tools?: string[];
+  maxTurns?: number;
+  maxCost?: number;
+  timeoutMs?: number;
+  graceTurns?: number;
+  fallbackModels?: string[];
+  maxRetries?: number;
+  isolation?: "shared" | "worktree";
+  /** JSON Schema the persona's final result must satisfy (inline JSON or @file.json). */
+  outputSchema?: Record<string, unknown>;
+  /**
+   * Which agents this persona may spawn as children.
+   * `false` disables nesting; `"*"` unrestricted; string[] is an allowlist.
+   * Absent means unrestricted (same as `"*"`).
+   */
+  spawns?: false | "*" | string[];
+}
+
+/** Agent names are file-name-safe identifiers; anything else is skipped. */
+
+const MAX_AGENT_FILE_BYTES = 64 * 1024;
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function agentDir(): string {
+  const envDir = process.env.PI_CODING_AGENT_DIR?.trim();
+  if (envDir) {
+    return envDir.startsWith("~") ? path.join(os.homedir(), envDir.slice(1)) : envDir;
+  }
+  return path.join(os.homedir(), ".pi", "agent");
+}
+
+export function discoveryRoots(cwd: string): Array<{ dir: string; scope: AgentDefinition["scope"] }> {
+  return [
+    { dir: path.join(cwd, ".pi", "agents"), scope: "project" },
+    { dir: path.join(cwd, ".agents", "agents"), scope: "shared" },
+    { dir: path.join(agentDir(), "agents"), scope: "global" },
+  ];
+}
+
+// ── Frontmatter parsing (flat YAML subset; no dependency) ───────────────────
+
+function stripQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length >= 2 && ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+/** `[a, b]` or `a, b` → string array. */
+function parseList(value: string): string[] {
+  const inner = value.trim().startsWith("[") && value.trim().endsWith("]")
+    ? value.trim().slice(1, -1)
+    : value;
+  return inner.split(",").map((item) => stripQuotes(item)).filter(Boolean);
+}
+
+function parseNumber(value: string): number | undefined {
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+/** Frontmatter `spawns:` — false | * | list. Invalid forms degrade to unrestricted (absent). */
+function parseSpawns(value: string): AgentDefinition["spawns"] | undefined {
+  const trimmed = stripQuotes(value.trim());
+  if (!trimmed) return undefined;
+  const lower = trimmed.toLowerCase();
+  if (lower === "false" || lower === "off" || lower === "none") return false;
+  if (trimmed === "*" || lower === "true" || lower === "any") return "*";
+  const list = parseList(trimmed).map((item) => item.toLowerCase()).filter((item) => NAME_PATTERN.test(item));
+  // Non-empty list only; garbage becomes unrestricted (same as absent frontmatter).
+  return list.length > 0 ? list : undefined;
+}
+
+/**
+ * Shared 64KB / regular-file / readable guard for `@path` references.
+ * Symlinks and oversized/missing files return undefined (callers degrade open).
+ */
+function readGuardedRelativeFile(agentFile: string, relativePath: string): string | undefined {
+  if (!relativePath || relativePath.includes("\0")) return undefined;
+  const file = path.resolve(path.dirname(agentFile), relativePath);
+  try {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.size > MAX_AGENT_FILE_BYTES) return undefined;
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** `output_schema` value: inline single-line JSON, or `@relative/path.json`. */
+function parseSchemaValue(value: string, agentFile: string): Record<string, unknown> | undefined {
+  let text = value.trim();
+  if (text.startsWith("@")) {
+    const loaded = readGuardedRelativeFile(agentFile, text.slice(1));
+    if (loaded === undefined) return undefined;
+    text = loaded;
+  }
+  try {
+    const parsed = JSON.parse(text);
+    return isPlausibleSchema(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Expand one-level `@include relative/path.md` body lines; missing/bad refs stay verbatim. */
+function expandIncludes(body: string, agentFile: string): string {
+  const lines = body.split(/\r?\n/);
+  let changed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const match = /^\s*@include\s+(\S+)\s*$/.exec(lines[i]!);
+    if (!match) continue;
+    const loaded = readGuardedRelativeFile(agentFile, match[1]!);
+    if (loaded === undefined) continue;
+    lines[i] = loaded.replace(/\r?\n$/, "");
+    changed = true;
+  }
+  return changed ? lines.join("\n") : body;
+}
+
+export function parseAgentFile(name: string, raw: string, source: string, scope: AgentDefinition["scope"]): AgentDefinition | undefined {
+  let frontmatter: Record<string, string> = {};
+  let body = raw;
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+  if (match) {
+    body = raw.slice(match[0].length);
+    for (const line of match[1]!.split(/\r?\n/)) {
+      const separator = line.indexOf(":");
+      if (separator <= 0 || /^\s*#/.test(line)) continue;
+      const key = line.slice(0, separator).trim();
+      const value = line.slice(separator + 1).trim();
+      if (key && value) frontmatter[key] = value;
+    }
+  }
+
+  const thinking = frontmatter.thinking && (THINKING_LEVELS as readonly string[]).includes(frontmatter.thinking)
+    ? (frontmatter.thinking as ThinkingLevel)
+    : undefined;
+  const profile = frontmatter.profile && (PROFILES as readonly string[]).includes(frontmatter.profile)
+    ? (frontmatter.profile as TaskProfile)
+    : undefined;
+  const isolation = frontmatter.isolation === "worktree" ? "worktree" as const
+    : frontmatter.isolation === "shared" ? "shared" as const
+    : undefined;
+  const spawns = frontmatter.spawns !== undefined ? parseSpawns(frontmatter.spawns) : undefined;
+  const backend = frontmatter.backend === "codex" ? "codex" as const
+    : frontmatter.backend === "claude" ? "claude" as const
+    : frontmatter.backend === "pi" ? "pi" as const
+    : undefined;
+
+  const expanded = expandIncludes(body, source);
+  const systemPrompt = expanded.trim() || undefined;
+  const definition: AgentDefinition = {
+    name,
+    description: stripQuotes(frontmatter.description ?? "").slice(0, 200) || name,
+    systemPrompt,
+    source,
+    scope,
+    model: frontmatter.model ? stripQuotes(frontmatter.model) : undefined,
+    thinking,
+    profile,
+    tools: frontmatter.tools ? parseList(frontmatter.tools) : undefined,
+    maxTurns: frontmatter.max_turns ? parseNumber(frontmatter.max_turns) : undefined,
+    maxCost: frontmatter.max_cost ? parseNumber(frontmatter.max_cost) : undefined,
+    timeoutMs: frontmatter.timeout_ms ? parseNumber(frontmatter.timeout_ms) : undefined,
+    graceTurns: frontmatter.grace_turns ? parseNumber(frontmatter.grace_turns) : undefined,
+    fallbackModels: frontmatter.fallback_models ? parseList(frontmatter.fallback_models) : undefined,
+    maxRetries: frontmatter.max_retries ? parseNumber(frontmatter.max_retries) : undefined,
+    isolation,
+    backend,
+    outputSchema: frontmatter.output_schema ? parseSchemaValue(frontmatter.output_schema, source) : undefined,
+    spawns,
+  };
+  return definition;
+}
+
+// ── Discovery ────────────────────────────────────────────────────────────────
+
+/**
+ * Discover agent definitions across the conventional roots. Synchronous by
+ * design: it runs at session start and on tool execute, reads a handful of
+ * small files, and failure of any root is silent (missing dirs are normal).
+ * Symlinked agent files are skipped (matching skill-loading conservatism).
+ */
+export function discoverAgents(cwd: string): Map<string, AgentDefinition> {
+  const catalog = new Map<string, AgentDefinition>();
+  // Iterate lowest precedence first so higher roots overwrite.
+  for (const root of [...discoveryRoots(cwd)].reverse()) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(root.dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith(".md")) continue;
+      const name = entry.name.slice(0, -3);
+      if (!NAME_PATTERN.test(name)) continue;
+      const file = path.join(root.dir, entry.name);
+      try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.size > MAX_AGENT_FILE_BYTES) continue;
+        const raw = fs.readFileSync(file, "utf8");
+        const definition = parseAgentFile(name.toLowerCase(), raw, file, root.scope);
+        if (definition) catalog.set(definition.name, definition);
+      } catch {
+        /* unreadable file: skip */
+      }
+    }
+  }
+  return catalog;
+}
+
+/** Case-insensitive lookup with a helpful error listing available names. */
+export function resolveAgent(
+  catalog: Map<string, AgentDefinition>,
+  name: string,
+): { agent?: AgentDefinition; error?: string } {
+  const agent = catalog.get(name.toLowerCase());
+  if (agent) return { agent };
+  const available = [...catalog.keys()].sort();
+  return {
+    error: available.length
+      ? `Unknown agent "${name}". Available agents: ${available.join(", ")}`
+      : `Unknown agent "${name}". No agent files found (define them in .pi/agents/<name>.md).`,
+  };
+}
+
+/** One line per agent for the tool guidelines / status output. */
+export function describeCatalog(catalog: Map<string, AgentDefinition>): string[] {
+  return [...catalog.values()]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((agent) => {
+      const traits = [
+        agent.profile,
+        agent.isolation === "worktree" ? "worktree" : "",
+      ].filter(Boolean).join(", ");
+      return `${agent.name}: ${agent.description}${traits ? ` (${traits})` : ""}`;
+    });
+}

package/src/backend.ts

@@ -0,0 +1,146 @@
+/**
+ * Backend adapter seam.
+ *
+ * `ChildRunner` owns everything that is *not* agent-specific: semaphore and
+ * global slot acquisition, worktree-prepared cwd, timeouts, budget wrap-up,
+ * the stall watchdog, group-kill/PID-identity safety, structured-output
+ * validation and repair, checkpointing and persistence.
+ *
+ * Only four things actually vary per agent CLI, and they live here:
+ *
+ *  1. `buildInvocation` — how to turn a TaskSpec into command + argv (+ any
+ *     temp files that must be cleaned up afterwards).
+ *  2. `createParser`    — how to turn that process's stdout into our
+ *     normalized `ProtocolUpdate` stream and a final `TaskResult`.
+ *  3. `steerCommand` / `stopCommand` — what to write on stdin to inject a
+ *     message or ask for a graceful stop (undefined = unsupported).
+ *  4. `capabilities`    — which features the backend can actually honor, so
+ *     unsupported requests are *refused* rather than silently ignored.
+ *
+ * Capability honesty is the important part. A backend that cannot report
+ * per-turn cost cannot enforce `max_cost`; pretending otherwise would let a
+ * runaway child spend without a ceiling. Policy validation rejects such
+ * combinations up front (see `assertCapabilities`).
+ */
+
+import type { ProtocolUpdate } from "./protocol.js";
+import type { TaskResult, TaskSpec } from "./types.js";
+
+/** Normalized event-stream parser contract, implemented per backend. */
+export interface BackendParser {
+  /** Consume a stdout chunk, yielding zero or more normalized updates. */
+  feed(data: Buffer | string): ProtocolUpdate[];
+  /** Flush any buffered partial line at stream end. */
+  flush(): ProtocolUpdate[];
+  /** Build the terminal TaskResult from exit status. */
+  finalize(exitCode: number | null, signal?: NodeJS.Signals, stderr?: string): TaskResult;
+  /** Transcript for checkpointing, if the backend can produce one. */
+  getTranscript(): string | undefined;
+  /** Text of the in-flight assistant message. */
+  getLiveText(): string;
+  /** Completed messages so far. */
+  getMessages(): import("@earendil-works/pi-ai").Message[];
+}
+
+export interface BackendInvocation {
+  command: string;
+  args: string[];
+  /** Extra env for the child, merged over the inherited environment. */
+  env?: Record<string, string>;
+  /** Directories to remove once the child exits (temp prompt files, etc.). */
+  cleanupDirs?: string[];
+}
+
+/**
+ * What a backend can actually do. Anything false is refused at validation
+ * time with an explanatory error rather than silently degraded.
+ */
+export interface BackendCapabilities {
+  /** Mid-run steering via a stdin command channel. */
+  steer: boolean;
+  /** Graceful budget wrap-up (needs steering to ask for a summary). */
+  gracefulWrapUp: boolean;
+  /** Per-turn provider usage/cost reporting — required for max_cost. */
+  costReporting: boolean;
+  /** Resuming a previous child session. */
+  resume: boolean;
+  /** Forking a session (context:'fork' / fork_resume). */
+  fork: boolean;
+  /** Restricting the child's tool set (profiles: explore/review). */
+  toolRestriction: boolean;
+  /** Reasoning-effort control. */
+  thinking: boolean;
+  /** Structured output via an appended schema contract. */
+  outputSchema: boolean;
+}
+
+export interface BackendAdapter {
+  readonly name: BackendName;
+  readonly capabilities: BackendCapabilities;
+  /**
+   * Build the child invocation. May write temp files; return their parent
+   * directories in `cleanupDirs` so the runner removes them on exit.
+   */
+  buildInvocation(spec: TaskSpec, context: BackendLaunchContext): Promise<BackendInvocation>;
+  createParser(): BackendParser;
+  /** stdin payload that injects a message mid-run, or undefined if unsupported. */
+  steerCommand?(message: string): unknown;
+  /** stdin payload requesting a graceful stop, or undefined if unsupported. */
+  stopCommand?(): unknown;
+  /** stdin payload answering an interactive UI request (headless auto-cancel). */
+  uiCancelCommand?(id: string): unknown;
+  /** stdin payload asking for session state (used to learn the session id). */
+  stateCommand?(): unknown;
+}
+
+export interface BackendLaunchContext {
+  /** Directory child sessions are written to. */
+  sessionDir: string;
+  /** Resolves the pi command/argv (pi backend only). */
+  getPiCommand: (args: string[]) => { command: string; args: string[] };
+}
+
+export type BackendName = "pi" | "codex" | "claude";
+
+export const BACKEND_NAMES: readonly BackendName[] = ["pi", "codex", "claude"];
+
+/**
+ * Reject requests a backend cannot honor. Returns a list of human-readable
+ * problems; empty means the spec is satisfiable.
+ *
+ * This is deliberately strict: silently dropping `max_cost` or a read-only
+ * profile would turn a safety feature into a no-op.
+ */
+export function checkCapabilities(
+  spec: Partial<
+    Pick<
+      TaskSpec,
+      "maxCost" | "resume" | "forkResume" | "contextFork" | "tools" | "thinking" | "outputSchema" | "profile" | "canWrite"
+    >
+  >,
+  capabilities: BackendCapabilities,
+  backend: BackendName,
+): string[] {
+  const problems: string[] = [];
+  if (spec.maxCost !== undefined && !capabilities.costReporting) {
+    problems.push(
+      `backend '${backend}' does not report per-turn cost, so max_cost cannot be enforced; drop max_cost or use max_turns/timeout_ms instead`,
+    );
+  }
+  if (spec.resume && !capabilities.resume) {
+    problems.push(`backend '${backend}' cannot resume child sessions; drop resume`);
+  }
+  if ((spec.forkResume || spec.contextFork) && !capabilities.fork) {
+    problems.push(`backend '${backend}' cannot fork sessions; drop fork_resume / context:'fork'`);
+  }
+  // A read-only profile that cannot be enforced is a write-safety hole.
+  if (spec.tools !== undefined && !capabilities.toolRestriction) {
+    problems.push(
+      `backend '${backend}' cannot restrict the child's tools, so profile '${spec.profile ?? "explore"}' cannot be enforced; use profile:'general' with an explicitly writable backend, or the pi backend`,
+    );
+  }
+  if (spec.outputSchema && !capabilities.outputSchema) {
+    problems.push(`backend '${backend}' does not support output_schema; drop it`);
+  }
+  return problems;
+}