@hheei/pi-subagents 0.1.2 → 0.2.3

package/README.md

@@ -1,42 +1,54 @@
 # @hheei/pi-subagents
 
 Run several independent Pi child sessions from one Pi session, each with its own Pi session
-file, its own RPC runtime, and its own durable identity.
+file, its own runtime, and its own durable identity.
 
 The package is a single concrete extension with one `pi.extensions` entry
 (`dist/extension.js`). The same entry runs on both sides: the parent branch registers the
 model-facing tools, commands, and widget; the child branch registers only the reporting
 bridge and session-leave reporting.
 
-Current behavior is defined by [`docs/pi-subagents/spec.md`](../../docs/pi-subagents/spec.md).
-[`docs/pi-subagents/PLAN.md`](../../docs/pi-subagents/PLAN.md) and
-[`docs/pi-subagents/PLAN-delivery-presentation.md`](../../docs/pi-subagents/PLAN-delivery-presentation.md)
-are design sources, not the live contract. Remaining pause-handshake work is tracked in
-[`docs/pi-subagents/tickets.md`](../../docs/pi-subagents/tickets.md) SUB-08.
-
 ## Parent tools
 
+The extension registers no global keyboard shortcuts. Use `/subagents` to manage
+children and `/subagents stop [id]` to stop one without conflicting with other extensions.
+
 | Tool | Purpose |
 | --- | --- |
-| `spawn_subagent({ task, agent, cwd? })` | Start one background RPC child and return when the runtime is ready. Do not poll `get`/`list` for the child's work; reports arrive as `pi-subagent-report` messages. |
-| `send_subagent({ id, message, mode? })` | Send `steer`, `follow_up`, or `auto` input to a specific child. Do not poll afterwards. |
-| `get_subagent({ id })` | Inspect one child: state, mode, session, summary, usage, runtime freshness, and inherited model/thinking. Use this for identity or state, not to wait. |
-| `list_subagents({})` | List children owned by this parent session. Use this for ids or current state, not to wait. |
-| `stop_subagent({ id })` | Persist a stopped intent, then end the runtime. |
-
-There is no batch-spawn tool: parallel children come from Pi's own parallel tool calls.
-`agent` is required; this package ships no built-in default agent, so an unresolved or
-missing agent name fails before any process starts.
-
-The child branch registers exactly one tool, `contact_parent({ reason, message })`, with
-reasons `progress_update`, `important_finding`, `need_decision`, and `blocked`. Calling it
-wakes the parent. If a child ends a turn without reporting, it may receive a follow-up
-nudge to call `contact_parent`; the child session is never auto-exited. Delay defaults to
-5s (`PI_SUBAGENTS_NUDGE_DELAY_MS`); set `PI_SUBAGENTS_NUDGE_DISABLE=1` to turn it off.
-
-`get_subagent` / `list_subagents` include `interactive`, `freshness`, `updatedAt`, and the
-resolved `model` / `thinking` with whether each came from the agent or the parent.
-Reports delivered to the parent are titled with the agent display name and child id.
+| `subagent_enable({})` | Enable interactive agent tools (`spawn_agent`, `send_agent`, `get_agent`, `stop_agent`) on demand. Deactivated by default in new sessions to save tokens; appends available interactive agents if any are defined, and enabled tools become available on the next model request. |
+| `spawn_agent({ task, agent, cwd?, title? })` | Start one child and return when its bridge is ready and the initial task was delivered. Runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing subagents** via `send_agent` for related/follow-up work to maintain context and maximize prompt cache and memory efficiency. `title` (<= 60 chars) names the child's Pi session, shown as `🤖 <title>`. Requires `subagent_enable`. Do not poll `get`/`list` for completion; reports arrive automatically as `subagent-report` messages. Do not pause or freeze other subagents before spawning. |
+| `send_agent({ id, message, mode? })` | Send `steer`, `follow_up`, or `auto` input to a specific child. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle or completed (`done`/`blocked`) children resume their existing session automatically with historical context intact, maximizing cache and memory efficiency. Do not wait for or ask workers to 'freeze': idle subagents are completely dormant and touch nothing. Requires `subagent_enable`. |
+| `get_agent({ id })` | Inspect one child: state (`running` / `done` / `blocked`), presentation (`panel`/`background`), session, summary, usage, runtime freshness, and model/thinking. Requires `subagent_enable`. |
+| `list_agents({})` | List available interactive agent definitions and running subagents owned by this parent session. |
+| `stop_agent({ id })` | Persist a stopped intent, then end the runtime: a background child is killed, a panel child has its panel closed and verified gone. Requires `subagent_enable`. |
+
+### Unified Task Management
+
+Subagent execution tasks automatically register with ext-core's `TaskRegistry`. Background bash jobs and subagents are uniformly tracked and waited upon using `wait_jobs`, eliminating fragmented or redundant task tools.
+
+## Child execution and reporting
+
+Subagents communicate with the parent over a dedicated Unix domain socket bridge:
+
+- **Completion by Direct Output**: Subagents do **not** need to call any reporting tool upon successful completion. The subagent simply outputs its final answer as normal assistant text.
+- **Settlement Debounce**: When a subagent finishes a turn and remains idle for 5 seconds (to prevent false idles), the harness automatically captures the trailing assistant text and delivers it to the parent conversation dialog as a completed `subagent-report`.
+- **Blockers & Decisions**: The child registers `contact_parent({ message, reason? })` strictly for reporting when it is blocked or urgently requires a parent decision midway (`reason` defaults to `'blocked'`). Blocked reports wake the parent immediately.
+- **Automatic Retry**: If a subagent encounters a transient error, the harness allows one automatic retry before marking the task failed or delivering a blocked notification.
+- **Panel Failure Auto-Close**: When a subagent running in a panel encounters a fatal error or reports a blocker, the manager starts a 15-second countdown after notifying the parent, automatically closing the panel tab to avoid workspace clutter unless new instructions are dispatched.
+- **Session Reference (`forkFrom`)**: `spawn_agent` can reference past conversation via `forkFrom: 'parent'` or a subagent id like `agent-1` (cannot be `'current'`). Instead of injecting the entire transcript into the subagent's prompt, the subagent's instructions reference the source session JSONL file path, allowing the model to inspect earlier context on demand using `read` or `grep` without token bloat.
+
+## Three visual states
+
+Subagent lifecycle is streamlined into three visual states in the TUI widget and status line:
+
+- **`running`** (blue/amber): Starting, executing turns, auto-retrying, or waiting out the 5-second settlement debounce.
+- **`done`** (green checkmark `✓`): Succeeded and automatically reported final assistant text back to the parent.
+- **`blocked`** (red/dim `!`): Failed, interrupted, stopped, or explicitly blocked via `contact_parent`.
+
+## Host Integration and Isolation
+
+- **Herdr Workspace Affinity**: When spawning in Herdr, tabs are explicitly created in the parent process's current workspace (`--workspace <WORKSPACE_ID>`), preventing child tabs from jumping to whichever workspace happens to have user focus.
+- **Hindsight Memory Isolation**: Subagents are completely isolated from the parent's long-term Hindsight memory. `PI_HINDSIGHT_DISABLE=1` is set in the child environment, hindsight tools are excluded via `--exclude-tools`, and any memory recall prompt blocks are stripped to protect memory banks from subagent noise.
 
 ## Agent definitions
 
@@ -48,114 +60,10 @@ Agent Markdown files are discovered in this order, most specific first, by `name
 ~/.pi/agent/agents/*.md
 ```
 
-Frontmatter is parsed with Pi's `parseFrontmatter` and then validated against this
-package's schema. Supported fields: `name`, `display_name`, `description`, `hidden`,
-`model`, `thinking`, `tools`, `exclude_tools`, `extensions`, `skills`, `interactive`.
-`interactive` defaults to `false` and is frozen into the launch snapshot. The Markdown body
-becomes the child's agent instructions.
-
-Validation happens before launch and fails closed:
-
-- unknown fields, and the recognized-but-unimplemented `exclude_extensions`,
-  `preload_skills`, `max_turns`, `max_tokens` fields;
-- `model` that is not an exact `provider/model-id` present in Pi's `ModelRegistry`;
-- invalid `thinking` levels, conflicting `tools`/`exclude_tools`, missing resource paths;
-- any policy that would remove the `contact_parent` bridge.
-
-`model` and `thinking` fall back to the parent session's current values, and the resolved
-result records whether each value came from the agent (`agent`) or the parent (`parent`).
-Models are never chosen by fuzzy match.
-
-## Launch configuration
-
-One builder produces every child process description. It resolves the Pi invocation, the
-full argv, cwd, session placement, model/thinking, tool/extension/skill selection, the
-assembled prompt, and the non-secret bridge environment, then reports `mode` and `stdio`
-separately. Values that contain spaces stay single argv atoms, and no shell is involved.
-
-Session identity is always explicit: a session that has never been flushed is created with
-`--session-id <id> --session-dir <dir>`, and a flushed session is opened by path. No path
-opens an absent file, so a child can never silently acquire a random session id.
-`extensions: false` keeps this package's absolute `-e <entry>` bridge argument while
-disabling discovery, so a child never loses `contact_parent` and never gains a manager.
-
-## Presentation hosts
-
-A HostAdapter only carries a native TUI. It receives the same LaunchSpec the RPC runner
-uses, probes real host capability, and never re-resolves agent, model, or Pi flags.
-
-`/attach-subagent <id>` opens an RPC child as native Pi in Herdr or cmux. With no
-id, `/subagents` or the attach shortcut uses `ctx.ui.select`. An idle child switches
-immediately. A busy child waits for the current turn's `turn_end`, then closes the
-RPC writer. Timeout or cancel keeps the RPC writer and fails visibly. Session files
-that have never flushed refuse attach. There is no model-facing attach tool.
-
-- Default selection is Herdr, then cmux. An explicit unavailable host fails visibly and
-  does not fall back.
-- Probe talks to the live session (`herdr pane current` inside `HERDR_ENV=1`, `cmux ping`
-  plus `capabilities`). A binary on PATH is not enough.
-- Herdr attach splits with `--cwd` / `--env` and runs the quoted command+argv. cmux attach
-  uses `new-split --command`. Neither path invents a second argv.
-- Observation uses host process APIs where they exist. A pane still being open is not
-  evidence that the Pi process is alive. Command timeout is not rollback: the attachment
-  is returned so the caller can inspect it, and nothing is closed automatically.
-- Cleanup closes only the pane or surface this transition created and still owns.
-- After a confirmed TUI process exit (`/quit`, pane close, crash), the same runner restores
-  RPC on session A and waits for input. Crash adds an extra diagnostic. A pane event with a
-  still-live process does not detach.
-- `/new`, `/resume` other, and `/fork` unbind A only after the TUI is confirmed on session
-  B. A returns to RPC; B is a native Pi session, not a subagent, and cannot `contact_parent`
-  as A. `/reload` and `/resume` of A do not detach. This package does not intercept a
-  user opening the same session with native `/resume` outside the managed path.
-- A confirmed user interrupt (Pi `stopReason: aborted`) notifies the parent and stays on
-  the TUI. Nothing is auto-resumed.
-
-## Persistence
-
-Each parent session gets its own registry file under
-`<agent-dir>/pi-subagents/registry/<parentSessionId>.json`, written through ext-core's
-atomic, cross-process-locked JSON root update. Nothing is written to `settings.json`.
-
-A record holds the child id, parent session id, session id/path, cwd, initial task, active
-or stopped intent, the non-secret launch configuration, state and mode, last-known summary
-and usage, and the reconnect metadata (`runtimeIdentity`, `endpoint`, optional `pid`).
-Revisions are monotonic; stale writers and updates aimed at a replaced runtime are
-rejected. Corruption, unsupported versions, parent mismatch, and identity mismatch fail
-closed instead of returning partial state. API keys and controller tokens are never
-persisted.
-
-Spawn order is fixed: resolve, persist intent, then start the runner. If the registry write
-fails, no child process is started, and a session that has already flushed must still prove
-its id on disk before anything opens it.
-
-Parent reload reconnects a surviving runner by `runtimeIdentity` and endpoint. Replacement
-starts only after the old runner PID is confirmed dead (a reused PID is not treated as
-ours). Pending input is marked interrupted and never replayed. A flushed session whose
-file is missing fails closed; a never-flushed child keeps its original session id.
-
-## Observation and commands
-
-An interactive TUI parent shows an above-editor widget of live children (`starting`,
-`running`, `idle`). It is a projection of `list()`:
-no second running set, no border, no file polling. Rows use the agent display name when
-present, mark `last known` when the runner is not connected, and show elapsed time since
-spawn. Headless/RPC parents do not mount it.
-
-`setStatus` shows a compact `running` / `idle` / `tui` / `failed` line, including
-`interrupted` when that diagnostic is set. `/subagents` lists, inspects, attaches, sends,
-or stops through `ctx.ui.select`. `/attach-subagent` and `/stop-subagent` accept an id or
-open the same picker. Shortcuts `ctrl+shift+a` and `ctrl+shift+s` call the same manager
-operations. Spawn/send/get/list/stop results render through ext-core ToolTui so collapsed
-output still keeps the full details.
-
-A TUI child shows one borderless identity line (agent, `contact_parent`, tool count). It
-is not a control surface.
-
-## Notes
-
-- `@hheei/pi-ext-core` is a production dependency, not a separately loaded extension.
-- Child processes are deliberately independent of the parent process lifetime; parent
-  cleanup releases local connections only.
-- This package does not use ext-core's in-process `startSubagent`: that contract cancels the
-  child when the parent shuts down, which is incompatible with surviving, reconnectable
-  children.
+Frontmatter is parsed with Pi's `parseFrontmatter` and validated against this package's schema. Supported fields: `name`, `display_name`, `description`, `hidden`, `model`, `thinking`, `tools`, `exclude_tools`, `extensions`, `skills`, `interactive`.
+
+### Built-in Agents
+
+- **`scout`**: Read-only reconnaissance agent. Disabled by default until the user explicitly configures a model in `~/.pi/agent/agents/scout.md`.
+- **`worker`**: General implementation agent. Configured with `model: inherit` to inherit the parent session's model and thinking level.
+- **`reviewer`**: Code review agent. Configured with `model: inherit` and leverages skill discovery to run review skills.

package/dist/agent-resolver.d.ts

@@ -1,4 +1,11 @@
 import type { ResolvedAgentPolicy, ThinkingLevel } from "./domain.js";
+/** Detects whether codemode is configured with mode: "only" in settings or environment. */
+export declare function detectCodemodeOnly(cwd?: string, homeDirectory?: string): boolean;
+export declare function isCodemodeOnlyMode(options: {
+    cwd?: string;
+    homeDirectory?: string;
+    frontmatterCodemode?: unknown;
+}): boolean;
 export interface ModelRegistryLike {
     /** `ModelRegistry.find` from the Pi extension context: exact provider/id lookup. */
     find(provider: string, modelId: string): unknown | undefined;
@@ -12,6 +19,14 @@ export interface ParentAgentDefaults {
     /** Parent's current thinking level, inherited only when the definition does not name one. */
     readonly thinking: ThinkingLevel;
 }
+/**
+ * One skill Pi has loaded, as the parent sees it. A definition names skills the way Pi lists them,
+ * so the parent's own catalog is the only authority for name → path; nothing here re-scans disk.
+ */
+export interface SkillCatalogEntry {
+    readonly name: string;
+    readonly path: string;
+}
 export interface ResolveAgentOptions {
     readonly name: string;
     readonly cwd: string;
@@ -20,12 +35,17 @@ export interface ResolveAgentOptions {
     /** Absolute path to this package's extension entry, always kept in the child extension selection. */
     readonly bridgeExtensionPath: string;
     readonly homeDirectory?: string;
+    /** Parent's loaded skills, the catalog a definition's skill names resolve against. */
+    readonly skillCatalog?: readonly SkillCatalogEntry[];
+    /** Diagnostics for the caller to surface; a caller that omits this drops them. */
+    readonly onWarning?: (message: string) => void;
 }
 export interface DiscoveredAgent {
     readonly name: string;
     readonly path: string;
     readonly frontmatter: Record<string, unknown>;
     readonly body: string;
+    readonly enabled?: boolean;
 }
 export declare function discoverAgents(cwd: string, homeDirectory?: string): Promise<readonly DiscoveredAgent[]>;
 /**

package/dist/agent-resolver.js

@@ -1,8 +1,11 @@
+import { existsSync, readFileSync } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { CONTACT_PARENT_TOOL_NAME, isRecord, isThinkingLevel } from "./domain.js";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { expandHome, isRecord } from "@hheei/pi-ext-core";
+import { builtinAgents } from "./builtin-agents.js";
+import { CONTACT_PARENT_TOOL_NAME, isThinkingLevel } from "./domain.js";
 /**
  * Agent definition fields this version actually implements. Anything outside this
  * table fails before launch; `DEFERRED_FIELDS` exists only to give those known
@@ -20,7 +23,44 @@ const SUPPORTED_FIELDS = {
     extensions: true,
     skills: true,
     interactive: true,
+    codemode: true,
 };
+/** Detects whether codemode is configured with mode: "only" in settings or environment. */
+export function detectCodemodeOnly(cwd, homeDirectory) {
+    if (process.env.PI_CODEMODE_MODE === "only")
+        return true;
+    try {
+        const agentDir = process.env.PI_CODING_AGENT_DIR !== undefined && process.env.PI_CODING_AGENT_DIR !== ""
+            ? process.env.PI_CODING_AGENT_DIR
+            : homeDirectory !== undefined
+                ? join(homeDirectory, ".pi", "agent")
+                : getAgentDir();
+        const candidates = [
+            join(agentDir, "settings.json"),
+            ...(cwd ? [join(cwd, ".pi", "settings.json")] : []),
+        ];
+        for (const candidate of candidates) {
+            if (existsSync(candidate)) {
+                const content = JSON.parse(readFileSync(candidate, "utf8"));
+                if (isRecord(content) && isRecord(content.codemode) && content.codemode.mode === "only") {
+                    return true;
+                }
+            }
+        }
+    }
+    catch {
+        // Ignore filesystem or JSON parse failures
+    }
+    return false;
+}
+export function isCodemodeOnlyMode(options) {
+    const val = options.frontmatterCodemode;
+    if (val === "only" || val === true)
+        return true;
+    if (val === "on" || val === false || val === "off")
+        return false;
+    return detectCodemodeOnly(options.cwd, options.homeDirectory);
+}
 /** Recognized candidate fields with no execution semantics yet; silently ignoring them is prohibited. */
 const DEFERRED_FIELDS = {
     exclude_extensions: true,
@@ -56,20 +96,20 @@ function stringList(value, field, path) {
 }
 const LOCAL_PATH_PATTERN = /^(?:[A-Za-z]:[\\/]|[~/]|\.{1,2}[\\/])/;
 /** Local selections become absolute paths next to the definition; package specs are left for Pi to resolve. */
-function resolveResourcePaths(value, field, path) {
+function resolveResourcePaths(value, field, path, homeDirectory) {
     return stringList(value, field, path).map((item) => {
         if (!LOCAL_PATH_PATTERN.test(item))
             return item;
-        const trimmed = item.startsWith("~/") ? join(homedir(), item.slice(2)) : item;
+        const trimmed = expandHome(item, homeDirectory);
         return resolve(dirname(path), trimmed);
     });
 }
-async function resourceSelection(value, field, path) {
+async function resourceSelection(value, field, path, homeDirectory) {
     if (value === undefined || value === true)
         return { discovery: true, paths: [] };
     if (value === false)
         return { discovery: false, paths: [] };
-    const paths = resolveResourcePaths(value, field, path);
+    const paths = resolveResourcePaths(value, field, path, homeDirectory);
     for (const selected of paths) {
         if (!isAbsolute(selected))
             continue;
@@ -79,6 +119,45 @@ async function resourceSelection(value, field, path) {
     }
     return { discovery: true, paths };
 }
+/** `skills: all` is the default and `skills: none` the opt-out; a list is a whitelist. */
+const SKILL_ALL = "all";
+const SKILL_NONE = "none";
+/**
+ * Skills are chosen as a whitelist, unlike extensions: a list means "exactly these", because
+ * inheriting every discovered skill is the thing a definition usually wants to narrow. A bare
+ * word is a skill *name* and resolves against the parent's loaded catalog, which also gives the
+ * absolute path the child needs; anything path-shaped stays what it was, and a name the catalog
+ * does not know is dropped with a warning rather than silently matching nothing.
+ */
+async function skillSelection(value, path, homeDirectory, catalog, warn) {
+    if (value === undefined || value === true || value === SKILL_ALL) {
+        return { discovery: true, paths: [] };
+    }
+    if (value === false || value === SKILL_NONE)
+        return { discovery: false, paths: [] };
+    const paths = [];
+    for (const entry of stringList(value, "skills", path)) {
+        if (LOCAL_PATH_PATTERN.test(entry)) {
+            const selected = resolve(dirname(path), expandHome(entry, homeDirectory));
+            const exists = await stat(selected).then(() => true, () => false);
+            if (!exists)
+                throw readableError(path, `skills entry does not exist: ${selected}`);
+            paths.push(selected);
+            continue;
+        }
+        if (entry.includes(":") || entry.includes("/") || entry.includes("\\")) {
+            paths.push(entry);
+            continue;
+        }
+        const match = catalog?.find((skill) => skill.name === entry);
+        if (match === undefined) {
+            warn(`Subagent skill "${entry}" is not among the skills Pi loaded, so ${path} launches without it.`);
+            continue;
+        }
+        paths.push(match.path);
+    }
+    return { discovery: false, paths };
+}
 async function markdownFiles(directory) {
     let entries;
     try {
@@ -96,11 +175,10 @@ async function markdownFiles(directory) {
 }
 /** Most specific scope first; the first definition of a name wins deterministically. */
 function agentDirectories(cwd, homeDirectory) {
-    return [
-        join(cwd, ".pi", "agents"),
-        join(cwd, ".agents", "agents"),
-        join(homeDirectory, ".pi", "agent", "agents"),
-    ];
+    const userAgentDir = process.env.PI_CODING_AGENT_DIR
+        ? join(process.env.PI_CODING_AGENT_DIR, "agents")
+        : join(homeDirectory, ".pi", "agent", "agents");
+    return [join(cwd, ".pi", "agents"), join(cwd, ".agents", "agents"), userAgentDir];
 }
 async function readAgentDefinition(path) {
     const content = await readFile(path, "utf8").catch((error) => {
@@ -118,17 +196,51 @@ async function readAgentDefinition(path) {
 }
 export async function discoverAgents(cwd, homeDirectory = homedir()) {
     const selected = new Map();
+    const builtins = new Map(builtinAgents().map((a) => [a.name, a]));
     for (const directory of agentDirectories(resolve(cwd), resolve(homeDirectory))) {
         for (const path of await markdownFiles(directory)) {
-            const agent = await readAgentDefinition(path);
+            const raw = await readAgentDefinition(path);
+            const builtin = builtins.get(raw.name);
+            const isBuiltin = builtin !== undefined;
+            const isBodyEmpty = raw.body.trim() === "";
+            // If it matches a built-in agent and the user markdown body is empty,
+            // inherit the built-in's body, tools, and description!
+            const frontmatter = isBuiltin && isBodyEmpty ? { ...builtin.frontmatter, ...raw.frontmatter } : raw.frontmatter;
+            const body = isBuiltin && isBodyEmpty ? builtin.body : raw.body;
+            const isCompliant = typeof frontmatter.model === "string" &&
+                frontmatter.model.trim() !== "" &&
+                (frontmatter.model.trim() === "inherit" || frontmatter.model.includes("/"));
+            const agent = {
+                name: raw.name,
+                path: raw.path,
+                frontmatter,
+                body,
+                enabled: isCompliant,
+            };
             if (!selected.has(agent.name))
                 selected.set(agent.name, agent);
         }
     }
+    // Built-ins not overridden on disk:
+    // If a built-in agent explicitly specifies model (e.g. model: inherit like reviewer/worker),
+    // it is compliant and directly available.
+    // If a built-in agent omits model (like scout), it is non-compliant and not loaded
+    // until the user supplements model metadata in user configuration.
+    for (const builtin of builtinAgents()) {
+        if (!selected.has(builtin.name)) {
+            const isCompliant = typeof builtin.frontmatter.model === "string" &&
+                builtin.frontmatter.model.trim() !== "" &&
+                (builtin.frontmatter.model.trim() === "inherit" || builtin.frontmatter.model.includes("/"));
+            selected.set(builtin.name, {
+                ...builtin,
+                enabled: isCompliant,
+            });
+        }
+    }
     return [...selected.values()];
 }
 function resolveModel(value, defaults, registry, path) {
-    if (value === undefined) {
+    if (value === undefined || value === "inherit") {
         if (registry.find(defaults.model.provider, defaults.model.id) === undefined) {
             throw readableError(path, `parent model ${defaults.model.provider}/${defaults.model.id} is unavailable`);
         }
@@ -153,10 +265,14 @@ function resolveModel(value, defaults, registry, path) {
  * before any child process exists.
  */
 export async function resolveAgent(options) {
-    const agents = await discoverAgents(options.cwd, options.homeDirectory);
+    const homeDirectory = resolve(options.homeDirectory ?? homedir());
+    const agents = await discoverAgents(options.cwd, homeDirectory);
     const discovered = agents.find((agent) => agent.name === options.name);
-    if (discovered === undefined)
-        throw new Error(`Unknown agent ${options.name}`);
+    if (discovered === undefined) {
+        const available = agents.map((agent) => agent.name).join(", ");
+        const searched = agentDirectories(resolve(options.cwd), homeDirectory).join(", ");
+        throw new Error(`Unknown agent ${options.name}. Available: [${available || "none"}]. Searched: ${searched}`);
+    }
     const path = discovered.path;
     for (const field of Object.keys(discovered.frontmatter)) {
         if (SUPPORTED_FIELDS[field] === true)
@@ -174,28 +290,44 @@ export async function resolveAgent(options) {
     const body = discovered.body.trim();
     if (body === "")
         throw readableError(path, "Markdown body must not be empty");
-    const tools = stringList(discovered.frontmatter.tools, "tools", path);
+    const codemodeValue = discovered.frontmatter.codemode;
+    if (codemodeValue !== undefined &&
+        codemodeValue !== "only" &&
+        codemodeValue !== "on" &&
+        codemodeValue !== "off" &&
+        typeof codemodeValue !== "boolean") {
+        throw readableError(path, "codemode must be boolean, 'only', 'on', or 'off'");
+    }
+    const codemodeOnly = isCodemodeOnlyMode({
+        cwd: options.cwd,
+        homeDirectory,
+        frontmatterCodemode: codemodeValue,
+    });
+    const rawTools = stringList(discovered.frontmatter.tools, "tools", path);
     const excludeTools = stringList(discovered.frontmatter.exclude_tools, "exclude_tools", path);
     if (excludeTools.includes(CONTACT_PARENT_TOOL_NAME)) {
         throw readableError(path, `exclude_tools cannot disable the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
     }
-    const overlap = tools.find((tool) => excludeTools.includes(tool));
+    const overlap = rawTools.find((tool) => excludeTools.includes(tool));
     if (overlap !== undefined)
         throw readableError(path, `tool ${overlap} is both allowed and excluded`);
-    if (tools.length > 0 && !tools.includes(CONTACT_PARENT_TOOL_NAME)) {
+    if (rawTools.length > 0 && !rawTools.includes(CONTACT_PARENT_TOOL_NAME)) {
         throw readableError(path, `tools must include the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
     }
+    const tools = codemodeOnly && !rawTools.includes("codemode") && !excludeTools.includes("codemode")
+        ? [...rawTools, "codemode"]
+        : rawTools;
     const thinkingValue = discovered.frontmatter.thinking;
     if (thinkingValue !== undefined && !isThinkingLevel(thinkingValue)) {
         throw readableError(path, "thinking is invalid");
     }
-    const extensionSelection = await resourceSelection(discovered.frontmatter.extensions, "extensions", path);
+    const extensionSelection = await resourceSelection(discovered.frontmatter.extensions, "extensions", path, homeDirectory);
     const bridgeExtensionPath = resolve(options.bridgeExtensionPath);
     const extensionPaths = [
         ...extensionSelection.paths.filter((selected) => selected !== bridgeExtensionPath),
         bridgeExtensionPath,
     ];
-    const skills = await resourceSelection(discovered.frontmatter.skills, "skills", path);
+    const skills = await skillSelection(discovered.frontmatter.skills, path, homeDirectory, options.skillCatalog, options.onWarning ?? (() => { }));
     const displayName = optionalString(discovered.frontmatter.display_name, "display_name", path);
     const description = optionalString(discovered.frontmatter.description, "description", path);
     const interactiveValue = discovered.frontmatter.interactive;
@@ -218,6 +350,7 @@ export async function resolveAgent(options) {
             source: thinkingValue === undefined ? "parent" : "agent",
         }),
         tools: Object.freeze(tools),
+        codemodeOnly,
         excludeTools: Object.freeze(excludeTools),
         extensions: Object.freeze({
             discovery: extensionSelection.discovery,
@@ -228,5 +361,6 @@ export async function resolveAgent(options) {
             paths: Object.freeze([...skills.paths]),
         }),
         interactive,
+        enabled: discovered.enabled !== false,
     });
 }

package/dist/bridge-client.d.ts

@@ -0,0 +1,55 @@
+import { type ChildIdentity } from "./domain.js";
+import { type ChildInputSource } from "./protocol.js";
+export interface ChildBridgeRequest {
+    readonly operation: string;
+    readonly payload: unknown;
+}
+export interface ChildBridgeClientOptions {
+    /** The parent's bridge socket. */
+    readonly endpoint: string;
+    readonly identity: ChildIdentity;
+    /** Executes a parent request; a thrown error becomes a failure response. */
+    readonly handleRequest: (request: ChildBridgeRequest) => Promise<unknown>;
+    readonly reconnectDelayMs?: number;
+    readonly maxBufferedReports?: number;
+    readonly maxFrameBytes?: number;
+    readonly connectTimeoutMs?: number;
+    readonly reportTimeoutMs?: number;
+    readonly diagnose?: (message: string) => void;
+}
+/**
+ * The child side of the bridge: one long-lived connection to the parent, carrying both directions
+ * of control.
+ *
+ * The child therefore never owns its own lifecycle endpoint: it dials the parent, keeps dialing
+ * while the parent is away, and reconnects with the same identity when the parent comes back (a
+ * parent restart re-listens the same socket path). Reports the parent has not accepted yet are
+ * buffered here, bounded, and flushed in order after a reconnect, so a report is never silently
+ * lost just because the parent was momentarily gone. Pi events are advisory snapshots and are
+ * dropped instead of buffered.
+ */
+export declare class ChildBridgeClient {
+    #private;
+    constructor(options: ChildBridgeClientOptions);
+    get connected(): boolean;
+    /**
+     * Starts the connect loop. It keeps retrying on its own: a panel child outlives the parent
+     * process that started it, so being unable to reach the parent is a state to wait out, not a
+     * failure to give up on. Call `close()` to stop it.
+     */
+    start(): void;
+    /** Sends an advisory frame: Pi events and child lifecycle signals. */
+    sendEvent(event: unknown): void;
+    /**
+     * Tells the parent that input arrived, with its source and nothing else. The parent uses this
+     * to cancel an idle countdown, so the text of a human message stays inside the child.
+     */
+    sendChildInput(source: ChildInputSource): void;
+    /**
+     * Reports to the parent, waiting for its answer. While the parent is unreachable the report is
+     * buffered instead of failed, and delivered after the reconnect.
+     */
+    sendReport(operation: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+    /** Stops reconnecting and fails everything still waiting for the parent. */
+    close(): void;
+}