@hheei/pi-subagents 0.2.3 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ 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
+model-facing tools, commands, compact footer status, and info entries; the child branch registers only the reporting
 bridge and session-leave reporting.
 
 ## Parent tools
@@ -15,16 +15,20 @@ children and `/subagents stop [id]` to stop one without conflicting with other e
 
 | Tool | Purpose |
 | --- | --- |
-| `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`. |
+| `agent_spawn({ task, agent, cwd?, title? })` | Spawn an independent background subagent task. 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 `agent_send` for related/follow-up work to maintain context and maximize prompt cache and memory efficiency. Tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. Do not poll for completion; results return automatically. |
+| `agent_send({ 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, blocked, done, or errored children resume their existing session automatically with historical context intact. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agent_get({ id, keys? })` | Inspect one subagent by id. `keys` is a comma-separated selection of `status` (default), `progress` (default), and `diagnostic`; unknown keys fail. The view never returns the child's task parameters or terminal result, which arrive automatically as reports. From the second successful inspection of the same child in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agent_stop({ id })` | Stop one subagent's runtime by id. The child keeps its session, so a later `agent_send` can resume it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 
 ### 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.
+`agent_spawn` returns JSON `{ id, path }` on success. `path` is the absolute child session file path
+assigned by Pi; its first write may still be pending. `agent_get` exposes the same `progress.path`.
+`agent_send` and `agent_stop` return one confirmation
+sentence. Failures return only their reason. Operation results omit session IDs, presentation, and
+state snapshots; use `agent_get` for runtime inspection.
+
+Subagent execution tasks register with ext-core's `TaskRegistry` when pi-ext-tools provides it, alongside background Bash jobs. Child reports arrive automatically; do not poll status to detect completion. Bash uses separate `bg_bash_*` tools. Deferred subagent tools are loaded via `tool_search`; activation supplies `subagent_guidance`. Both get tools return the same `status`, `progress`, and optional `diagnostic` envelope. Diagnostics describe blockers, failed turns, or uncertain runtime state.
 
 ## Child execution and reporting
 
@@ -35,20 +39,18 @@ Subagents communicate with the parent over a dedicated Unix domain socket bridge
 - **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.
+## Compact status and reports
 
-## Three visual states
+Running children use the native Pi status line: `🤖 󰪠#21 #22 #23`. With pi-status installed, this appears at the bottom right before the existing TODO segment, separated by ` ‧ `. Display shorthand `#21` refers to tool ID `agent-21`. No running children means no agent segment; no multi-line parent widget is mounted.
 
-Subagent lifecycle is streamlined into three visual states in the TUI widget and status line:
+Confirmed done, error, and blocked reports appear once as `subagent-info` transcript entries. Collapsed entries show the outcome, child ID, and agent name; expand to read the complete report. They survive resume and do not enter model context. The original automatic `subagent-report` still reaches the model, with its duplicate transcript display hidden. Transient errors remain subject to settlement and retry checks before reporting.
 
-- **`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`.
+Use `/subagents` for complete status and management. `agent_send` can resume a done, blocked, errored, or stopped child with its session context intact; retrying does not guarantee the underlying failure is resolved.
 
 ## 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.
+- **Hindsight Memory Isolation**: `PI_HINDSIGHT_DISABLE=1` is set in the child environment and memory auto-registration/recall/writeback are disabled. The child bridge blocks all `mcp__hindsight__*` calls (including nested codemode calls and future server tools), even if that server is configured in a file. Memory recall prompt blocks are stripped. This boundary applies to the reserved `hindsight` server name, not arbitrary external servers registered under other names.
 
 ## Agent definitions
 
@@ -56,11 +58,24 @@ Agent Markdown files are discovered in this order, most specific first, by `name
 
 ```text
 <cwd>/.pi/agents/*.md
-<cwd>/.agents/agents/*.md
+<cwd>/.pi/agents/*.md
 ~/.pi/agent/agents/*.md
 ```
 
-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`.
+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`, `mcp`, `codemode`.
+
+### Unified Resource Selection (Pi Semantics)
+
+`tools`, `skills`, and `mcp` follow Pi's unified selection semantics:
+
+- **`boolean` toggle**:
+  - `true` (or omitted): Full inheritance from host defaults.
+  - `false`: Completely disabled (passes `--no-mcp`, `--no-skills`, `--no-tools` respectively; `--no-mcp` physically shuts down the MCP subsystem so no server processes or network connections start).
+  - MCP selection (`mcp: [server1]`) acts at the tool exposure and execution boundary via `--tools` / `--exclude-tools` patterns and child-bridge tool call gating. Non-whitelisted or excluded server tools cannot be viewed or called.
+- **Exact list (Whitelist / Replace)**:
+  - `[item1, item2]`: Activates only the named entries.
+- **Incremental modifiers (`+` / `-`)**:
+  - `["+itemA", "-itemB"]`: Adds or excludes entries relative to base defaults. Exact names and modifiers cannot be mixed.
 
 ### Built-in Agents
 

package/dist/agent-resolver.d.ts

@@ -47,6 +47,15 @@ export interface DiscoveredAgent {
     readonly body: string;
     readonly enabled?: boolean;
 }
+export type PiSelectionType = "all" | "none" | "whitelist" | "modifier";
+export interface ParsedPiSelection {
+    readonly type: PiSelectionType;
+    readonly names?: readonly string[];
+    readonly modifiers?: readonly string[];
+    readonly add?: readonly string[];
+    readonly remove?: readonly string[];
+}
+export declare function parsePiSelection(value: unknown, field: string, path: string): ParsedPiSelection;
 export declare function discoverAgents(cwd: string, homeDirectory?: string): Promise<readonly DiscoveredAgent[]>;
 /**
  * Resolves one agent definition into an immutable, non-secret policy snapshot.

package/dist/agent-resolver.js

@@ -22,8 +22,8 @@ const SUPPORTED_FIELDS = {
     exclude_tools: true,
     extensions: true,
     skills: true,
-    interactive: true,
     codemode: true,
+    mcp: true,
 };
 /** Detects whether codemode is configured with mode: "only" in settings or environment. */
 export function detectCodemodeOnly(cwd, homeDirectory) {
@@ -35,18 +35,27 @@ export function detectCodemodeOnly(cwd, homeDirectory) {
             : 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;
+        // Project settings (.pi/settings.json in cwd) take precedence over user settings (.pi/agent/settings.json)
+        if (cwd) {
+            const projectSettings = join(cwd, ".pi", "settings.json");
+            if (existsSync(projectSettings)) {
+                const content = JSON.parse(readFileSync(projectSettings, "utf8"));
+                if (isRecord(content) &&
+                    isRecord(content.codemode) &&
+                    typeof content.codemode.mode === "string") {
+                    return content.codemode.mode === "only";
                 }
             }
         }
+        const userSettings = join(agentDir, "settings.json");
+        if (existsSync(userSettings)) {
+            const content = JSON.parse(readFileSync(userSettings, "utf8"));
+            if (isRecord(content) &&
+                isRecord(content.codemode) &&
+                typeof content.codemode.mode === "string") {
+                return content.codemode.mode === "only";
+            }
+        }
     }
     catch {
         // Ignore filesystem or JSON parse failures
@@ -104,6 +113,161 @@ function resolveResourcePaths(value, field, path, homeDirectory) {
         return resolve(dirname(path), trimmed);
     });
 }
+const DEFAULT_PI_TOOLS = ["read", "bash", "edit", "write"];
+function isModifier(entry) {
+    return entry.startsWith("+") || entry.startsWith("-");
+}
+export function parsePiSelection(value, field, path) {
+    if (value === undefined || value === true || value === "all") {
+        return { type: "all" };
+    }
+    if (value === false || value === "none") {
+        return { type: "none" };
+    }
+    const raw = typeof value === "string" ? value.split(",") : value;
+    if (!Array.isArray(raw)) {
+        throw readableError(path, `${field} must be a boolean, string, or string array`);
+    }
+    const entries = raw.map((item) => requiredString(item, field, path));
+    if (entries.length === 0) {
+        return { type: "none" };
+    }
+    const modifiers = entries.filter(isModifier);
+    if (modifiers.length > 0) {
+        if (modifiers.length < entries.length) {
+            throw readableError(path, `cannot mix exact names with +name or -name entries in ${field}`);
+        }
+        const add = [];
+        const remove = [];
+        for (const entry of modifiers) {
+            if (entry.includes("*")) {
+                throw readableError(path, `+name and -name entries take exact names, not patterns: ${entry}`);
+            }
+            const name = entry.slice(1).trim();
+            if (name === "") {
+                throw readableError(path, `${field} entry has empty modifier name`);
+            }
+            if (entry.startsWith("+")) {
+                if (!add.includes(name))
+                    add.push(name);
+            }
+            else {
+                if (!remove.includes(name))
+                    remove.push(name);
+            }
+        }
+        return {
+            type: "modifier",
+            modifiers: Object.freeze(entries),
+            add: Object.freeze(add),
+            remove: Object.freeze(remove),
+        };
+    }
+    if (new Set(entries).size !== entries.length) {
+        throw readableError(path, `${field} selects the same entry twice`);
+    }
+    return { type: "whitelist", names: Object.freeze(entries) };
+}
+function applyModifiers(base, modifiers) {
+    const result = [...base];
+    for (const entry of modifiers) {
+        const name = entry.slice(1).trim();
+        if (entry.startsWith("+")) {
+            if (!result.includes(name))
+                result.push(name);
+        }
+        else if (entry.startsWith("-")) {
+            const idx = result.indexOf(name);
+            if (idx !== -1)
+                result.splice(idx, 1);
+        }
+    }
+    return result;
+}
+function mergeDiscoveredFrontmatter(builtinFm, userFm, path, inheritBaseDefaults) {
+    const merged = inheritBaseDefaults
+        ? { ...builtinFm, ...userFm }
+        : { ...userFm };
+    if (userFm.tools !== undefined) {
+        const parsedUser = parsePiSelection(userFm.tools, "tools", path);
+        if (parsedUser.type === "modifier") {
+            const baseTools = stringList(builtinFm.tools, "tools", path);
+            const evaluatedTools = applyModifiers(baseTools, parsedUser.modifiers ?? []);
+            merged.tools = evaluatedTools;
+            const existing = Array.isArray(merged.exclude_tools)
+                ? merged.exclude_tools
+                : typeof merged.exclude_tools === "string"
+                    ? [merged.exclude_tools]
+                    : [];
+            const currentExcludes = existing.filter((e) => !evaluatedTools.includes(e));
+            const finalRemovals = (parsedUser.remove ?? []).filter((r) => !evaluatedTools.includes(r));
+            merged.exclude_tools = Array.from(new Set([...currentExcludes, ...finalRemovals]));
+        }
+    }
+    if (userFm.skills !== undefined) {
+        const parsedUser = parsePiSelection(userFm.skills, "skills", path);
+        if (parsedUser.type === "modifier") {
+            if (Array.isArray(builtinFm.skills)) {
+                const baseSkills = stringList(builtinFm.skills, "skills", path);
+                merged.skills = applyModifiers(baseSkills, parsedUser.modifiers ?? []);
+            }
+            else {
+                merged.skills = userFm.skills;
+            }
+        }
+    }
+    if (userFm.mcp !== undefined) {
+        const parsedUser = parsePiSelection(userFm.mcp, "mcp", path);
+        if (parsedUser.type === "modifier") {
+            if (Array.isArray(builtinFm.mcp)) {
+                const baseMcp = stringList(builtinFm.mcp, "mcp", path);
+                merged.mcp = applyModifiers(baseMcp, parsedUser.modifiers ?? []);
+            }
+            else if (builtinFm.mcp === false) {
+                const evaluated = applyModifiers([], parsedUser.modifiers ?? []);
+                merged.mcp = evaluated.length > 0 ? evaluated : false;
+            }
+            else {
+                merged.mcp = userFm.mcp;
+            }
+        }
+    }
+    return merged;
+}
+function mcpSelection(value, path) {
+    const parsed = parsePiSelection(value, "mcp", path);
+    if (parsed.type === "none") {
+        return Object.freeze({ enabled: false });
+    }
+    if (parsed.type === "all") {
+        return Object.freeze({ enabled: true });
+    }
+    if (parsed.type === "whitelist") {
+        const servers = parsed.names;
+        return Object.freeze({
+            enabled: true,
+            ...(servers !== undefined ? { servers } : {}),
+        });
+    }
+    const excluded = [];
+    for (const entry of parsed.modifiers ?? []) {
+        const name = entry.slice(1).trim();
+        if (entry.startsWith("-")) {
+            if (!excluded.includes(name))
+                excluded.push(name);
+        }
+        else if (entry.startsWith("+")) {
+            const idx = excluded.indexOf(name);
+            if (idx !== -1)
+                excluded.splice(idx, 1);
+        }
+    }
+    const result = {
+        enabled: true,
+        ...(excluded.length > 0 ? { excluded } : {}),
+    };
+    return Object.freeze(result);
+}
 async function resourceSelection(value, field, path, homeDirectory) {
     if (value === undefined || value === true)
         return { discovery: true, paths: [] };
@@ -119,9 +283,6 @@ async function resourceSelection(value, field, path, homeDirectory) {
     }
     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
@@ -129,32 +290,59 @@ const SKILL_NONE = "none";
  * 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) {
+async function skillSelection(value, path, homeDirectory, catalog) {
+    const parsed = parsePiSelection(value, "skills", path);
+    if (parsed.type === "all") {
         return { discovery: true, paths: [] };
     }
-    if (value === false || value === SKILL_NONE)
+    if (parsed.type === "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 (parsed.type === "whitelist") {
+        const paths = [];
+        for (const entry of parsed.names ?? []) {
+            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) {
+                // Pass uncatalogued skill name down to Pi CLI so Pi validates it and reports in the subagent panel
+                paths.push(entry);
+                continue;
+            }
+            paths.push(match.path);
         }
-        if (entry.includes(":") || entry.includes("/") || entry.includes("\\")) {
-            paths.push(entry);
-            continue;
+        return { discovery: false, paths };
+    }
+    if (catalog === undefined || catalog.length === 0) {
+        const paths = [];
+        for (const entry of parsed.modifiers ?? []) {
+            if (entry.startsWith("+")) {
+                paths.push(entry.slice(1).trim());
+            }
         }
-        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;
+        return { discovery: false, paths };
+    }
+    const baseSkillNames = catalog.map((skill) => skill.name);
+    const activeSkillNames = applyModifiers(baseSkillNames, parsed.modifiers ?? []);
+    const paths = [];
+    for (const name of activeSkillNames) {
+        const match = catalog.find((skill) => skill.name === name);
+        if (match !== undefined) {
+            paths.push(match.path);
+        }
+        else {
+            paths.push(name);
         }
-        paths.push(match.path);
     }
     return { discovery: false, paths };
 }
@@ -175,9 +363,11 @@ async function markdownFiles(directory) {
 }
 /** Most specific scope first; the first definition of a name wins deterministically. */
 function agentDirectories(cwd, homeDirectory) {
-    const userAgentDir = process.env.PI_CODING_AGENT_DIR
-        ? join(process.env.PI_CODING_AGENT_DIR, "agents")
-        : join(homeDirectory, ".pi", "agent", "agents");
+    const userAgentDir = homeDirectory === homedir()
+        ? join(getAgentDir(), "agents")
+        : 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) {
@@ -200,13 +390,25 @@ export async function discoverAgents(cwd, homeDirectory = homedir()) {
     for (const directory of agentDirectories(resolve(cwd), resolve(homeDirectory))) {
         for (const path of await markdownFiles(directory)) {
             const raw = await readAgentDefinition(path);
+            if (selected.has(raw.name))
+                continue;
             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;
+            let frontmatter;
+            let body;
+            if (isBuiltin && isBodyEmpty) {
+                frontmatter = mergeDiscoveredFrontmatter(builtin.frontmatter, raw.frontmatter, path, true);
+                body = builtin.body;
+            }
+            else if (isBuiltin && !isBodyEmpty) {
+                frontmatter = mergeDiscoveredFrontmatter(builtin.frontmatter, raw.frontmatter, path, false);
+                body = raw.body;
+            }
+            else {
+                frontmatter = raw.frontmatter;
+                body = raw.body;
+            }
             const isCompliant = typeof frontmatter.model === "string" &&
                 frontmatter.model.trim() !== "" &&
                 (frontmatter.model.trim() === "inherit" || frontmatter.model.includes("/"));
@@ -303,18 +505,47 @@ export async function resolveAgent(options) {
         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)) {
+    const excludeToolsRaw = stringList(discovered.frontmatter.exclude_tools, "exclude_tools", path);
+    if (excludeToolsRaw.includes(CONTACT_PARENT_TOOL_NAME)) {
         throw readableError(path, `exclude_tools cannot disable the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
     }
+    const parsedTools = parsePiSelection(discovered.frontmatter.tools, "tools", path);
+    let rawTools;
+    const excludeTools = [...excludeToolsRaw];
+    if (parsedTools.type === "none") {
+        rawTools = [CONTACT_PARENT_TOOL_NAME];
+    }
+    else if (parsedTools.type === "whitelist") {
+        rawTools = [...(parsedTools.names ?? [])];
+    }
+    else if (parsedTools.type === "modifier") {
+        const baseTools = [...DEFAULT_PI_TOOLS, CONTACT_PARENT_TOOL_NAME];
+        if (parsedTools.remove?.includes(CONTACT_PARENT_TOOL_NAME)) {
+            throw readableError(path, `tools modifier cannot remove the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
+        }
+        rawTools = applyModifiers(baseTools, parsedTools.modifiers ?? []);
+        const finalExclusions = (parsedTools.remove ?? []).filter((r) => !rawTools.includes(r));
+        for (const r of finalExclusions) {
+            if (!excludeTools.includes(r))
+                excludeTools.push(r);
+        }
+    }
+    else {
+        rawTools = [];
+    }
     const overlap = rawTools.find((tool) => excludeTools.includes(tool));
     if (overlap !== undefined)
         throw readableError(path, `tool ${overlap} is both allowed and excluded`);
     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")
+    if (excludeTools.length > 0) {
+        rawTools = rawTools.filter((t) => !excludeTools.includes(t));
+    }
+    const tools = rawTools.length > 0 &&
+        codemodeOnly &&
+        !rawTools.includes("codemode") &&
+        !excludeTools.includes("codemode")
         ? [...rawTools, "codemode"]
         : rawTools;
     const thinkingValue = discovered.frontmatter.thinking;
@@ -327,14 +558,10 @@ export async function resolveAgent(options) {
         ...extensionSelection.paths.filter((selected) => selected !== bridgeExtensionPath),
         bridgeExtensionPath,
     ];
-    const skills = await skillSelection(discovered.frontmatter.skills, path, homeDirectory, options.skillCatalog, options.onWarning ?? (() => { }));
+    const skills = await skillSelection(discovered.frontmatter.skills, path, homeDirectory, options.skillCatalog);
+    const mcp = mcpSelection(discovered.frontmatter.mcp, path);
     const displayName = optionalString(discovered.frontmatter.display_name, "display_name", path);
     const description = optionalString(discovered.frontmatter.description, "description", path);
-    const interactiveValue = discovered.frontmatter.interactive;
-    if (interactiveValue !== undefined && typeof interactiveValue !== "boolean") {
-        throw readableError(path, "interactive must be boolean");
-    }
-    const interactive = interactiveValue === true;
     return Object.freeze({
         agent: Object.freeze({
             name,
@@ -360,7 +587,7 @@ export async function resolveAgent(options) {
             discovery: skills.discovery,
             paths: Object.freeze([...skills.paths]),
         }),
-        interactive,
+        mcp,
         enabled: discovered.enabled !== false,
     });
 }

package/dist/bridge-client.d.ts

@@ -10,6 +10,11 @@ export interface ChildBridgeClientOptions {
     readonly identity: ChildIdentity;
     /** Executes a parent request; a thrown error becomes a failure response. */
     readonly handleRequest: (request: ChildBridgeRequest) => Promise<unknown>;
+    /**
+     * Called after every successful handshake, including the first. A reconnecting child uses it to
+     * resend whatever state the parent needs to stay synchronized.
+     */
+    readonly onConnect?: () => void;
     readonly reconnectDelayMs?: number;
     readonly maxBufferedReports?: number;
     readonly maxFrameBytes?: number;

package/dist/bridge-client.js

@@ -274,6 +274,12 @@ export class ChildBridgeClient {
         this.#connected = true;
         socket.on("close", () => this.#teardown(socket));
         socket.on("error", () => this.#teardown(socket));
+        try {
+            this.#options.onConnect?.();
+        }
+        catch (error) {
+            this.#diagnose(`onConnect handler failed: ${errorMessage(error)}`);
+        }
         void this.#flush();
         return true;
     }