pi-jar 0.2.7 → 0.2.8

package/README.md

@@ -309,7 +309,7 @@ Providers cache a prompt as an ordered prefix: tools, then the system prompt, th
 - **`jar_shell`** — `start` (optional `name`, `watch` regex, `notify`, task/service `purpose`, `waitMs` up to 30 s), `list`, `peek`, bounded `wait`, `output`, `kill`. Use plain `bash` for finite commands expected to finish in about two minutes; `jar_shell` is for services, watchers and long jobs. `start` with `waitMs` returns the exit code and output tail in one call when the job finishes in time (acknowledged, so no later notification), otherwise the output so far; Esc cancels only the wait. `output` returns only lines new since your last read (with counts of trimmed or skipped lines); `all: true` repeats the trailing window. ANSI-stripped logs have per-job caps and a 4 MiB aggregate budget; surfaced finished jobs compact to a 32 KiB tail. Live jobs retain useful tails and are never killed to reclaim logs. Watch/exit notifications are compact and coalesced; reads acknowledge observed events. Active model responses cannot be interrupted by a completion event: the UI previews status without consuming it, and model delivery waits for a safe boundary. When no useful work remains, use bounded `wait` for the relevant finite jobs rather than waiting for an automatic wake-up. Each running shell gets a footer row and an activity view (`/jar shells`) with `x` kill and `f` follow. All shells stop when the session ends.
 - **`jar_delegate`** — spawns retained, session-scoped subagents up to **Max subagents** in `/jar settings` (2, 4, 6, 8 or 16; default 2). Idle, paused and hibernated agents count toward this pool; over-cap batches are rejected. `/profiles` → **Create Swarm profile** copies the current settings with a pool of 4. `scout` is fresh/read-only, `fork` inherits conversation read-only, and `worktree` forks context into a path-guarded Git worktree. Settled retained agents close their Pi process after 30 seconds of quiet while keeping their private session and workspace; `resume`/`ask` relaunch that same session. Launch returns before startup or the first turn completes, including legacy one-shot `write: true` mode. Turn and stop events carry a summary of at most 400 characters plus changed files; all events pending at one boundary arrive as one `pi-jar.subagent` message, together with the moderator's unread discussion mail. `/roles` warns when the `scout` or `reviewer` role would run on the main model while a cheaper model is available.
 - **`jar_subagent`** — `peek` reports progress, including the workspace path and changed files for recovery records; `steer` redirects a running worker; `resume` relaunches an idle/paused/hibernated agent; `report` returns an agent's latest full report (a synchronous `jar_delegate` result shares a 16k-character report budget across its runs and points here when it truncates). `ask`, `pause` and `stop` return accepted receipts immediately; answers and final handoffs arrive as `pi-jar.subagent` events. `stop` reconciles safe worktree changes; conflicts remain private and can be retried with `stop` after resolving parent drift. `discard` removes an unresolved recovery worktree without applying it. At most four active/recovery worktrees are admitted; resolve or discard one before starting another. Session shutdown reports paths of any preserved worktrees. Controls do not poll the child.
-- **Subagent capabilities** — each task can set `tools` or `inheritTools: true`; known-tool mode filters and child guards remain in force. See [tool capabilities](docs/SUBAGENT-TOOLS.md).
+- **Subagent capabilities** — each task can set `tools` (`name` exact list / `-name` subtract; any active tool, e.g. MCP `mom_search`; worktrees still refuse shells), `inheritTools: true`, and `skills` (same `+`/`-` syntax). `~/.pi/agent/pi-jar-subagents.json` holds user `+`/`-` rules for tools, extensions (`npm:@scope/pkg`, names, paths) and skills; user disallows always win. See [tool capabilities](docs/SUBAGENT-TOOLS.md).
 - **Worktree finalization** — edits do not touch the parent merely because a worker settles or hibernates. On `jar_subagent stop`, pi-jar checks parent drift and reviewability, applies safe changes and adds them to `/diff`; conflicts remain isolated for retry or explicit discard. Failed worktree transcripts are compacted independently of finished history. Process closure is awaited before finalization, and failed multi-file application rolls back rather than leaving a partial result.
 - **`jar_council`** — **exceptional only**, for a persistent super-complex issue with several evidence-backed options after at least two distinct failed approaches. The moderator opens 2–8 options, resumes relevant idle/paused/hibernated fresh-context read-only scouts or spawns new scouts within the pool, and collects one private ballot per voter. A strict majority of invited voters wins; ties, plurality or missing/invalid ballots require user choice. Voting never implements its recommendation. A round has a 10-minute deadline and bounded rationales.
 - **`jar_discuss`** — session-local, parent-owned discussion broker over authenticated local IPC; no shared paper, lock or polling. `ask`/`answer` return stable IDs without echoing your text. `list` reads only relevant unread questions/answers and advances your cursor; `thread` (or `list` with `questionId`) reads one thread; `pending` shows counts without message bodies. `since: "d0"` rereads relevant mail. At most 128 messages, 1600 characters each and 128 KiB are retained; unread/unanswered questions block new posts instead of being silently lost. Messages do not wake idle agents. Unread mail (never your own messages) arrives once, inline, at your next natural turn start, so no `list` call is needed; the moderator's also rides along with subagent events.

package/docs/INTEGRATIONS.md

@@ -62,7 +62,7 @@ Hidden context messages (`pi-jar.plan-context`, `pi-jar.plan-reminder`, `pi-jar.
 | `jar_goal` | `get`, `complete` (with evidence, audit phase only), `block`; active only while a goal runs |
 | `jar_suggest` | one next-prompt suggestion shown as composer ghost text; active only when suggestions are enabled |
 | `jar_shell` | background shells: `start` (`command`, `name`, `watch`, `notify`, `purpose`, `waitMs`), `list`, `peek`, `wait`, `output` (new lines; `all`), `kill` |
-| `jar_delegate` | retained subagents within the configured pool (`tasks: [{task, name?, role?, mode?, tools?, inheritTools?}]`) |
+| `jar_delegate` | retained subagents within the configured pool (`tasks: [{task, name?, role?, mode?, tools?, inheritTools?, skills?}]`) |
 | `jar_subagent` | moderator control: `peek`, `report`, `steer`, `ask`, `pause`, `resume`, `stop`, `discard` |
 | `jar_council` | exceptional scout vote with strict majority; never implements |
 | `jar_discuss` | parent-brokered Q/A between moderator and subagents |

package/docs/SUBAGENT-TOOLS.md

@@ -12,10 +12,11 @@ Subagents use Pi's standard `--tools` allowlist. Each `jar_delegate` task can cu
 ```
 
 - With neither option, existing mode defaults are unchanged: `scout` and `fork` are read-only; `worktree` gets the path-guarded file tools; legacy `direct` retains Pi's default allowlist.
-- `tools` replaces the mode's default tool list. Names must be active in the parent session. Enable the relevant extension and tool in the parent first. Tool names vary by extension; use the exact active name (for example, a configured web/search extension's names).
-- `inheritTools: true` snapshots the parent's currently active tool names, then filters them for mode safety. It does not grant tools registered later. Pi hosts must expose `getActiveTools()` (or the integration must supply an active-name getter); otherwise inheritance/configurable lists fail with an actionable error.
-- `scout` and `fork` accept only known read-only/discovery tools and named web tools; edit/write, shell and arbitrary extension tools are rejected even if explicitly requested.
-- `worktree` accepts known path-guarded file tools and named web tools. Shell and arbitrary extension tools are rejected. `multi_file_edit` is included in defaults only when active in the parent; each effective edit target, default path and recognized alternate path field is validated, including traversal and existing symlink escapes.
+- `tools` entries are `name`/`+name` (allow) or `-name` (subtract). Any allow entry makes an exact list that replaces the mode defaults and is the moderator's deliberate grant: any tool active in the parent is honored, including MCP/extension tools such as `mom_search` or `punakawan_project`. Include the basics you still need (`read`, `jar_todo`, ...). Only `-name` entries subtract from the mode defaults (or inherited tools), e.g. `["-jar_discuss"]`. A scout or fork granted a mutating tool is no longer strictly read-only — grant narrowly.
+- `skills` (per task) uses the same syntax for Pi skills, by name or path: `["mom", "punakawan"]` (or `[]`) is exact, `["-lavish"]` removes from the defaults; omit it to keep the defaults. Children then run `--no-skills --skill <path>...`.
+- `inheritTools: true` snapshots the parent's currently active tool names, then filters them for mode safety plus the trusted extras from `pi-jar-subagents.json`. It does not grant tools registered later. Pi hosts must expose `getActiveTools()` (or the integration must supply an active-name getter); otherwise inheritance/configurable lists fail with an actionable error.
+- Inherited `scout`/`fork` tools are known read-only/discovery tools, named web tools and trusted extras.
+- `worktree` rejects shell tools even when explicitly requested (a shell would escape the path guard). Inherited worktree tools are path-guarded file tools, named web tools and trusted extras. `multi_file_edit` is included in defaults only when active in the parent; each effective edit target, default path and recognized alternate path field is validated, including traversal and existing symlink escapes.
 - Named web capabilities are `web_enable`, `web_search`, `fetch_content`, `get_search_content` and `source_check`. Newly enabled tools must still be in the child's original capability list.
 - These are tool-call restrictions, not an OS sandbox. Extensions execute trusted code; named web tools can access external services, and legacy direct-write mode is not workspace-confined.
 - `jar_delegate`, `jar_subagent`, and `jar_council` are always removed from inherited tools and rejected in explicit lists. A child cannot recursively spawn more subagents.
@@ -23,4 +24,23 @@ Subagents use Pi's standard `--tools` allowlist. Each `jar_delegate` task can cu
 
 Retained scout/fork/worktree children hibernate after 30 seconds idle: their Pi process exits, but the private child session and worktree remain for `jar_subagent resume` or `ask`. Hibernated records count against Max subagents. Unresolved worktree recovery records do not occupy a pool slot, but at most four active/recovery worktrees are admitted. `jar_subagent stop` retries reconciliation; `discard` explicitly removes an unresolved recovery workspace without applying it. On session shutdown pi-jar reports paths for worktrees it preserves on disk, including still-active worktrees that might contain edits.
 
+## `~/.pi/agent/pi-jar-subagents.json`
+
+User-owned and profile-independent; read on every launch. A missing file means no rules; malformed content fails the launch with an error. Each list takes `+entry` (or bare `entry`) to allow and `-entry` to disallow; a disallow wins over an allow, and user disallows always win over the moderator's task requests (which are then rejected with an error).
+
+```json
+{
+  "tools": ["+mom_search", "+mom_get", "-punakawan_connector_call"],
+  "extensions": ["+npm:@gotgenes/pi-anthropic-auth", "-pi-web-access"],
+  "skills": ["+antislop", "-lavish"]
+}
+```
+
+- `tools` — allow: trusted names added to `inheritTools` in every mode. Disallow: removed from defaults/inheritance and rejected in explicit task lists. Recursive delegation tools can never be allowed.
+- `extensions` — entries are Pi package sources (`npm:@scope/name`, `git:host/owner/repo`, URLs), short names (npm package, git repo, a top-level extension file/dir name, or a builtin such as `mcp`), or paths (`~/`, absolute, `./`, or `dir/file` relative to the agent dir). Sources and names resolve to the installed paths from the parent's own Pi resolution (settings filters included); an allowed source that is not installed is passed to Pi as-is (Pi installs it temporarily, slower).
+  - allow: loaded by every child. Default read-only scouts/forks run `--no-extensions` plus pi-jar for fast startup, so a provider extension such as Anthropic OAuth compatibility must be allowed here or those children fail authentication. Children with normal discovery get it added only when it is not already loaded.
+  - disallow: children that would use normal discovery instead get `--no-extensions` plus the parent's enabled extensions (top-level, packages and enabled builtins) minus the disallowed ones. A parent started with `--no-extensions` never gains discovered extensions.
+- `skills` — names or paths. allow: added to children's default skills, even when disabled in the parent. Disallow: never loaded by children; a task asking for one is rejected. When any skill rule (config or task) applies, children get an exact `--no-skills --skill ...` list; otherwise Pi's normal discovery is unchanged.
+- The running pi-jar is always loaded explicitly; another installed pi-jar copy is never loaded twice.
+
 If configurable tools are unavailable on a Pi host, use mode defaults or upgrade to a host exposing its active tool list. Avoid inheriting every tool for convenience; grant the narrowest capability needed for the assignment.

package/extensions/index.ts

@@ -54,7 +54,8 @@ import { ContextSampler, formatPerf, LARGE_SESSION_ENTRIES, processRss, RenderSc
 import { registerChangeReview } from "../src/diff-view.ts";
 import { registerShells, ShellManager, type ShellEvent, type ShellJob } from "../src/shells.ts";
 import { registerShellNotifications } from "../src/shell-notifications.ts";
-import { CHILD_TOOLS_ENV, childToolAllowlist, RECURSIVE_TOOLS, worktreeToolViolation } from "../src/subagent-tools.ts";
+import { loadResourceCatalog } from "../src/subagent-resources.ts";
+import { CHILD_TOOLS_ENV, childToolAllowlist, loadSubagentConfig, RECURSIVE_TOOLS, worktreeToolViolation } from "../src/subagent-tools.ts";
 import { hopefulWelcomeMessage, welcomeHit, welcomeLines, type WelcomeAction } from "../src/welcome.ts";
 
 const WELCOME_KEY = "pi-jar.welcome";
@@ -351,6 +352,8 @@ export default function piJar(pi: ExtensionAPI): void {
     discussionRetire: (key) => discussion?.retire(key),
     discussionUnread: (key) => discussion?.unreadFor(key) ?? 0,
     discussionDigest: () => discussion?.digest(),
+    getSubagentConfig: () => loadSubagentConfig(getAgentDir()),
+    loadResources: (cwd) => loadResourceCatalog(cwd, getAgentDir()),
     getMaxSubagents: () => visualSettings.maxSubagents, onController: (controller) => { delegateController = controller; } });
   if (!delegatedChild) registerCouncil(pi, () => delegateController, () => visualSettings.maxSubagents);
   const planMode = new PlanMode(pi, () => todos, modelRoles, updateTaskWidget);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jar",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "A warm, role-aware Pi terminal workspace with switchable profiles, animated UI, plan and goal workflows, tasks, change review, model roles, background shells and subagents.",
   "type": "module",
   "license": "MIT",

package/src/delegate.ts

@@ -1,6 +1,7 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import { signalProcessTree } from "./async-process.ts";
-import { CHILD_TOOLS_ENV, RECURSIVE_TOOLS, WEB_TOOLS } from "./subagent-tools.ts";
+import { CHILD_TOOLS_ENV, EMPTY_SUBAGENT_CONFIG, parseRules, RECURSIVE_TOOLS, SHELL_TOOLS, SUBAGENT_CONFIG_FILE, WEB_TOOLS, type RuleList, type SubagentConfig } from "./subagent-tools.ts";
+import { planExtensions, planSkills, type ExtensionPlan, type ResourceCatalog } from "./subagent-resources.ts";
 import { existsSync, mkdtempSync, realpathSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -37,8 +38,9 @@ export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "jar_todo", "jar_d
 export const WORKTREE_TOOLS = ["read", "edit", "write", "multi_file_edit", "grep", "find", "ls", "jar_todo", "jar_discuss"] as const;
 const READ_ONLY_SAFE_TOOLS = new Set<string>([...READ_ONLY_TOOLS, ...WEB_TOOLS, "ffgrep", "fffind", "lsp_diagnostics", "obs_recall"]);
 const WORKTREE_SAFE_TOOLS = new Set<string>([...WORKTREE_TOOLS, ...WEB_TOOLS]);
-const allowedInMode = (mode: DelegateExecutionMode, name: string) => !RECURSIVE_TOOLS.has(name)
-  && (mode === "direct" || (mode === "worktree" ? WORKTREE_SAFE_TOOLS.has(name) : READ_ONLY_SAFE_TOOLS.has(name)));
+/** Inheritance filter: mode-safe tools plus the user's trusted extras from pi-jar-subagents.json. */
+const allowedInMode = (mode: DelegateExecutionMode, name: string, trusted: ReadonlySet<string> = new Set()) => !RECURSIVE_TOOLS.has(name)
+  && (mode === "direct" || trusted.has(name) || (mode === "worktree" ? WORKTREE_SAFE_TOOLS.has(name) : READ_ONLY_SAFE_TOOLS.has(name)));
 export type DelegateMode = "scout" | "fork" | "worktree";
 type DelegateExecutionMode = DelegateMode | "direct";
 const MAX_OUTPUT_CHARS = 12_000;
@@ -169,24 +171,52 @@ export interface DelegateSessionOptions {
   tools?: readonly string[];
 }
 
+/** The running pi-jar entry point; children always load this copy explicitly. */
+export const OWN_EXTENSION = fileURLToPath(new URL("../extensions/index.ts", import.meta.url));
+
+/** Extension and skill choices for one child, planned from pi-jar-subagents.json and the task. */
+export interface ChildResources {
+  extensions?: ExtensionPlan;
+  /** Exact skill paths (`--no-skills --skill ...`); undefined keeps Pi's normal skill discovery. */
+  skills?: readonly string[];
+}
+
 /** CLI arguments for one subagent: an ephemeral one-shot, a private resumable session, or a real Pi session fork. */
 export function delegateArgs(model: string | undefined, thinking: string | undefined, write: boolean, argv = process.argv,
-  session?: DelegateSessionOptions, toolOverride?: readonly string[]): string[] {
+  session?: DelegateSessionOptions, toolOverride?: readonly string[], resources: ChildResources = {}): string[] {
   const sessionArgs = !session ? ["--no-session"]
     : session.resume ? ["--session", session.resume, "--session-dir", session.sessionDir]
     : session.source ? ["--fork", session.source, "--session-dir", session.sessionDir]
     : ["--session-dir", session.sessionDir];
   const extensions = extensionFlags(argv);
   const tools = session?.tools ?? toolOverride ?? (!write ? READ_ONLY_TOOLS : undefined);
-  const ownExtension = fileURLToPath(new URL("../extensions/index.ts", import.meta.url));
+  const ownExtension = OWN_EXTENSION;
+  const plan = resources.extensions;
+  const load = (path: string) => { if (!extensions.includes(path)) extensions.push("--extension", path); };
+  const parentDiscovers = !extensions.some(flag => flag === "-ne" || flag === "--no-extensions");
   // Default read-only children need only core file tools and pi-jar. Avoid importing every
   // personal extension (and opening unused MCP/provider connections) for each scout.
   // Explicit extension flags and optional inherited tools retain the parent's full setup.
   const lean = !write && extensions.length === 0 && tools?.every(tool => (READ_ONLY_TOOLS as readonly string[]).includes(tool));
-  if (lean) extensions.push("--no-extensions", "--extension", ownExtension);
-  // Worktree cwd/session forks (resumed ones too) do not inherit project extension discovery from the parent.
-  else if (session?.source && !extensions.includes(ownExtension)) extensions.push("--extension", ownExtension);
+  if (lean) {
+    extensions.push("--no-extensions", "--extension", ownExtension);
+    // User-allowed essentials (e.g. a provider auth extension) that lean children still need.
+    for (const path of plan?.lean ?? []) load(path);
+  } else if (plan?.explicit && parentDiscovers) {
+    // Something is disallowed: replace discovery with the parent's resolved list minus the disallowed entries.
+    extensions.push("--no-extensions");
+    load(ownExtension);
+    for (const path of plan.explicit) load(path);
+  } else {
+    // Worktree cwd/session forks (resumed ones too) do not inherit project extension discovery from the parent.
+    if (session?.source) load(ownExtension);
+    for (const path of plan?.add ?? []) load(path);
+  }
   const args = ["--mode", "rpc", ...sessionArgs, ...extensions];
+  if (resources.skills) {
+    args.push("--no-skills");
+    for (const path of resources.skills) args.push("--skill", path);
+  }
   if (model) args.push("--model", model);
   if (thinking) args.push("--thinking", thinking);
   if (tools) args.push("--tools", tools.join(","));
@@ -1186,8 +1216,10 @@ const Parameters = Type.Object({
     role: Type.Optional(Type.String({ description: "pi-jar role override; defaults by mode (scout→scout, fork→reviewer, worktree→worker), then role fallbacks/current model." })),
     mode: Type.Optional(DelegateModeSchema),
     tools: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 80 }), { minItems: 1, maxItems: 64, uniqueItems: true,
-      description: "Explicit child tool allowlist; grant narrowly. scout/fork stay read-only; worktree accepts only path-guarded file tools; web/browser tools only when active here." })),
-    inheritTools: Type.Optional(Type.Boolean({ description: "Inherit your active tools, filtered by mode safety; recursive delegation tools are always removed." }))
+      description: "Child tools. `name`/`+name` entries form an exact list (replaces mode defaults; include read etc.); any tool active here is honored, e.g. MCP mom_search; mutating tools bypass scout/fork read-only. Only `-name` entries subtract from the defaults (or inherited tools). User-disallowed tools and worktree shells are rejected." })),
+    inheritTools: Type.Optional(Type.Boolean({ description: "Inherit your active tools, filtered by mode safety plus user-trusted extras; recursive delegation tools are always removed." })),
+    skills: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 300 }), { maxItems: 64, uniqueItems: true,
+      description: "Skills the child may load, by name or path. `name`/`+name` entries (or []) form an exact list; only `-name` entries remove from the defaults. Omit to keep defaults. User-disallowed skills are rejected." }))
   }), { minItems: 1, maxItems: 16 }),
   mode: Type.Optional(DelegateModeSchema),
   write: Type.Optional(Type.Boolean({ description: "Deprecated: true = legacy shared-workspace editing; prefer mode=\"worktree\"." }))
@@ -1219,6 +1251,10 @@ export interface DelegateController {
 export interface DelegateOptions {
   /** Snapshot names of tools active in the parent session. */
   getActiveToolNames?: () => readonly string[];
+  /** Tool/extension/skill allow (+) and disallow (-) rules (pi-jar-subagents.json); read on every launch, may throw on bad config. */
+  getSubagentConfig?: () => SubagentConfig;
+  /** The parent's resolved extensions and skills; needed only when extension/skill rules apply. */
+  loadResources?: (cwd: string) => Promise<ResourceCatalog>;
   /** Allowed sizes: 2, 4, 6, 8, 16; defaults to MAX_DELEGATES. Read on every launch. */
   getMaxSubagents?: () => number;
   /** Shares the delegate lifecycle and capacity with scout orchestration. */
@@ -1472,32 +1508,77 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         } catch { return undefined; }
       };
       const activeNames = parentToolNames();
+      let config: SubagentConfig;
+      try { config = options.getSubagentConfig?.() ?? EMPTY_SUBAGENT_CONFIG; }
+      catch (error) {
+        return { content: [{ type: "text", text: `Cannot read subagent config: ${(error as Error).message}` }], details: { runs: [], write: false }, isError: true };
+      }
+      const trusted = new Set(config.tools.allow);
+      const disallowed = new Set(config.tools.deny);
       const defaultWorktreeTools = WORKTREE_TOOLS.filter(name => name !== "multi_file_edit" || activeNames?.includes(name));
+      const toolPlans: Array<readonly string[] | undefined> = [];
+      const skillRules: Array<RuleList | undefined> = [];
       for (const [index, item] of requested.entries()) {
         const mode = item.mode ?? params.mode ?? (params.write === true ? "direct" : "scout");
-        const selected = item.tools ?? (item.inheritTools && activeNames ? activeNames.filter(name =>
-          allowedInMode(mode, name)) : undefined);
+        let rules: RuleList | undefined;
+        try {
+          rules = item.tools ? parseRules(item.tools, `Task ${index + 1}: tools`) : undefined;
+          skillRules.push(item.skills ? parseRules(item.skills, `Task ${index + 1}: skills`) : undefined);
+        } catch (error) {
+          return { content: [{ type: "text", text: (error as Error).message }], details: { runs: [], write: false }, isError: true };
+        }
         if ((item.inheritTools || item.tools) && !activeNames) {
           return { content: [{ type: "text", text: `Task ${index + 1}: this Pi host does not expose active tool names; configurable tools cannot be validated. Use default tools or a host with getActiveTools().` }], details: { runs: [], write: false }, isError: true };
         }
-        if (item.inheritTools && !selected?.length) {
-          return { content: [{ type: "text", text: `Task ${index + 1}: no active tools remain after applying ${mode} safety filters. Choose explicit safe tools or use the mode defaults.` }], details: { runs: [], write: false }, isError: true };
+        const inherited = item.inheritTools && activeNames ? activeNames.filter(name => allowedInMode(mode, name, trusted) && !disallowed.has(name)) : undefined;
+        const defaults = inherited ?? (mode === "worktree" ? defaultWorktreeTools : mode === "direct" ? undefined : [...READ_ONLY_TOOLS]);
+        const explicit = rules?.allow.length ? rules.allow : undefined;
+        let selected: readonly string[] | undefined;
+        if (explicit) selected = explicit;
+        else if (rules) {
+          if (!defaults) return { content: [{ type: "text", text: `Task ${index + 1}: direct mode has no default tool list to subtract from; list the tools to grant.` }], details: { runs: [], write: false }, isError: true };
+          selected = defaults.filter(name => !rules!.deny.includes(name));
+        } else selected = inherited ?? (defaults?.some(name => disallowed.has(name)) ? defaults.filter(name => !disallowed.has(name)) : undefined);
+        if ((item.inheritTools || rules) && !selected?.length) {
+          return { content: [{ type: "text", text: `Task ${index + 1}: no tools remain after applying ${mode} safety filters and disallow rules. Choose explicit tools or use the mode defaults.` }], details: { runs: [], write: false }, isError: true };
         }
         if (selected) {
-          if (activeNames) {
-            const missing = selected.filter(name => !activeNames.includes(name));
+          const blocked = selected.filter(name => disallowed.has(name));
+          if (blocked.length) return { content: [{ type: "text", text: `Task ${index + 1}: tools disallowed by ${SUBAGENT_CONFIG_FILE}: ${blocked.join(", ")}.` }], details: { runs: [], write: false }, isError: true };
+          if (explicit && activeNames) {
+            const missing = explicit.filter(name => !activeNames.includes(name));
             if (missing.length) return { content: [{ type: "text", text: `Task ${index + 1}: tools are not currently active in the parent: ${missing.join(", ")}. Enable their extensions/tools first.` }], details: { runs: [], write: false }, isError: true };
-          } else if (item.inheritTools) {
-            return { content: [{ type: "text", text: `Task ${index + 1}: cannot resolve inherited tools from this Pi host.` }], details: { runs: [], write: false }, isError: true };
           }
           const recursive = selected.filter(name => RECURSIVE_TOOLS.has(name));
           if (recursive.length) return { content: [{ type: "text", text: `Task ${index + 1}: recursive delegation tools are never available to subagents: ${recursive.join(", ")}.` }], details: { runs: [], write: false }, isError: true };
-          if ((mode === "scout" || mode === "fork") && selected.some(name => !READ_ONLY_SAFE_TOOLS.has(name))) {
-            return { content: [{ type: "text", text: `Task ${index + 1}: ${mode} is read-only; remove edit/write/shell tools or use mode="worktree" for sandboxed code changes.` }], details: { runs: [], write: false }, isError: true };
-          }
+          // Explicit `tools` are the moderator's deliberate grant: any active non-recursive tool is honored.
+          // Only the worktree sandbox keeps its hard boundary, since a shell would escape the path guard.
           if (mode === "worktree") {
-            const unsafe = selected.filter(name => !WORKTREE_SAFE_TOOLS.has(name));
-            if (unsafe.length) return { content: [{ type: "text", text: `Task ${index + 1}: worktree cannot safely use tools outside its path-guarded allowlist: ${unsafe.join(", ")}. Arbitrary extension tools remain disabled unless the worktree boundary validates them.` }], details: { runs: [], write: false }, isError: true };
+            const unsafe = selected.filter(name => SHELL_TOOLS.has(name));
+            if (unsafe.length) return { content: [{ type: "text", text: `Task ${index + 1}: worktree subagents cannot run shell tools (${unsafe.join(", ")}); edits stay inside path-guarded file tools.` }], details: { runs: [], write: false }, isError: true };
+          }
+        }
+        toolPlans.push(selected);
+      }
+      // Extension/skill rules need the parent's resolved resources; plain launches skip that work.
+      let extensionPlan: ExtensionPlan | undefined;
+      const skillPlans: Array<readonly string[] | undefined> = requested.map(() => undefined);
+      const ruled = (rules: RuleList) => rules.allow.length > 0 || rules.deny.length > 0;
+      if (ruled(config.extensions) || ruled(config.skills) || skillRules.some(Boolean)) {
+        if (!options.loadResources) {
+          return { content: [{ type: "text", text: "This Pi host cannot resolve extensions/skills for subagents; remove extension/skill rules." }], details: { runs: [], write: false }, isError: true };
+        }
+        let catalog: ResourceCatalog;
+        try {
+          catalog = await options.loadResources(ctx.cwd);
+          if (ruled(config.extensions)) extensionPlan = planExtensions(config.extensions, catalog, OWN_EXTENSION);
+        } catch (error) {
+          return { content: [{ type: "text", text: `Cannot plan subagent extensions: ${(error as Error).message}` }], details: { runs: [], write: false }, isError: true };
+        }
+        for (const [index, rules] of skillRules.entries()) {
+          try { skillPlans[index] = planSkills(config.skills, rules, catalog, SUBAGENT_CONFIG_FILE); }
+          catch (error) {
+            return { content: [{ type: "text", text: `Task ${index + 1}: ${(error as Error).message}` }], details: { runs: [], write: false }, isError: true };
           }
         }
       }
@@ -1519,8 +1600,7 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
       const toolsByRun = new Map<number, readonly string[] | undefined>();
       const runs: DelegateRun[] = requested.map((item, index) => {
         const mode: DelegateExecutionMode = item.mode ?? defaultMode;
-        toolsByRun.set(index + 1, item.tools ?? (item.inheritTools && activeNames ? activeNames.filter(name =>
-          allowedInMode(mode, name)) : mode === "worktree" ? defaultWorktreeTools : undefined));
+        toolsByRun.set(index + 1, toolPlans[index] ?? (mode === "worktree" ? defaultWorktreeTools : undefined));
         const role = cleanText(item.role ?? roleForMode(mode), 32) || roleForMode(mode);
         const candidates = [...roleCandidates(role), ...roleCandidates("default")];
         const selected = candidates.find((candidate) => available.has(candidate.provider + "/" + candidate.model));
@@ -1684,7 +1764,8 @@ export function registerDelegate(pi: ExtensionAPI, roles: ModelRoleManager, regi
         // Read at every spawn, so a relaunch after hibernation reaches the current discussion broker.
         hooks.env = () => ({ ...env, ...discussionEnv(key, run.name) });
         const argsFor = (resume?: string) => delegateArgs(run.model, thinkingByRun.get(run.index), write, process.argv,
-          session && resume ? { ...session, resume } : session, run.mode === "scout" ? toolsByRun.get(run.index) : undefined);
+          session && resume ? { ...session, resume } : session, run.mode === "scout" ? toolsByRun.get(run.index) : undefined,
+          { ...(extensionPlan ? { extensions: extensionPlan } : {}), ...(skillPlans[run.index - 1] ? { skills: skillPlans[run.index - 1] } : {}) });
         if (session) {
           const own = session.sessionDir;
           // Only ever continue this child's own private session, never a file it reports elsewhere.

package/src/subagent-resources.ts

@@ -0,0 +1,152 @@
+import { readFileSync } from "node:fs";
+import { basename, dirname, extname, isAbsolute, resolve, sep } from "node:path";
+import type { RuleList } from "./subagent-tools.ts";
+
+/** One extension or skill the parent's Pi configuration resolves, enabled or filtered out. */
+export interface CatalogResource { path: string; enabled: boolean; source: string; packageRoot?: string }
+export interface ResourceCatalog { extensions: readonly CatalogResource[]; skills: readonly CatalogResource[] }
+
+/** Pi's built-in extensions; resolved as `builtin:<name>` so an explicit child list keeps the enabled ones. */
+export const BUILTIN_EXTENSIONS = ["llama.cpp", "codemode", "tool-search", "mcp"] as const;
+
+/** The parent's resources exactly as Pi resolves them (settings filters, packages, top-level dirs); never installs. */
+export async function loadResourceCatalog(cwd: string, agentDir: string): Promise<ResourceCatalog> {
+  const { DefaultPackageManager, SettingsManager } = await import("@earendil-works/pi-coding-agent");
+  const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager: SettingsManager.create(cwd, agentDir),
+    builtinExtensions: [...BUILTIN_EXTENSIONS] });
+  const resolved = await manager.resolve(async () => "skip");
+  const map = (item: { path: string; enabled: boolean; metadata: { source: string; packageRoot?: string } }): CatalogResource =>
+    ({ path: item.path, enabled: item.enabled, source: item.metadata.source, ...(item.metadata.packageRoot ? { packageRoot: item.metadata.packageRoot } : {}) });
+  return { extensions: resolved.extensions.map(map), skills: resolved.skills.map(map) };
+}
+
+/** `npm:@a/b@1` → `npm:@a/b`; git/URL forms → `git:host/path` without ref or `.git`; others unchanged. */
+export function normalizeSource(spec: string): string {
+  const value = spec.trim();
+  if (value.startsWith("npm:")) {
+    const name = value.slice(4);
+    const at = name.indexOf("@", 1);
+    return "npm:" + (at > 0 ? name.slice(0, at) : name);
+  }
+  let git: string;
+  if (value.startsWith("git:")) git = value.slice(4);
+  else if (/^https?:\/\//.test(value)) git = value.replace(/^https?:\/\//, "");
+  else if (/^git@[^:]+:/.test(value)) git = value.slice(4).replace(":", "/");
+  else return value;
+  return "git:" + git.replace(/@[^/]*$/, "").replace(/\.git$/, "").replace(/\/+$/, "");
+}
+
+const stem = (path: string) => basename(path, extname(path));
+/** Short name: npm package, git repo, builtin name, or a top-level file/directory name. */
+export function extensionName(resource: CatalogResource): string {
+  if (resource.path.startsWith("builtin:")) return resource.path.slice(8);
+  const source = normalizeSource(resource.source);
+  if (source.startsWith("npm:")) return source.slice(4);
+  if (source.startsWith("git:")) return source.slice(source.lastIndexOf("/") + 1);
+  const file = stem(resource.path);
+  return file === "index" ? basename(dirname(resource.path)) : file;
+}
+/** Agent Skills names match their directory; standalone Markdown skills use the file name. */
+export function skillName(resource: CatalogResource): string {
+  return basename(resource.path) === "SKILL.md" ? basename(dirname(resource.path)) : stem(resource.path);
+}
+
+const isPathSpec = (spec: string) => isAbsolute(spec);
+const within = (path: string, root: string) => path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
+
+function extensionMatches(resource: CatalogResource, spec: string): boolean {
+  if (spec === resource.path) return true;
+  if (isPathSpec(spec)) {
+    const target = resolve(spec);
+    return within(resource.path, target) || (!!resource.packageRoot && resolve(resource.packageRoot) === target);
+  }
+  if (spec.includes(":")) return normalizeSource(spec) === normalizeSource(resource.source);
+  return extensionName(resource) === spec;
+}
+function skillMatches(resource: CatalogResource, spec: string): boolean {
+  if (spec === resource.path) return true;
+  if (isPathSpec(spec)) return within(resource.path, resolve(spec));
+  return skillName(resource) === spec;
+}
+
+const packageNames = new Map<string, string | undefined>();
+const packageName = (root: string): string | undefined => {
+  if (!packageNames.has(root)) {
+    let name: string | undefined;
+    try { name = (JSON.parse(readFileSync(resolve(root, "package.json"), "utf8")) as { name?: unknown }).name as string | undefined; }
+    catch { name = undefined; } // a package root without a readable manifest simply is not pi-jar
+    packageNames.set(root, typeof name === "string" ? name : undefined);
+  }
+  return packageNames.get(root);
+};
+/** Children always load the running pi-jar explicitly; never a second (possibly older) pi-jar copy. */
+const isPiJar = (resource: CatalogResource, ownExtension: string) => resource.path === ownExtension
+  || (!!resource.packageRoot && packageName(resource.packageRoot) === "pi-jar");
+
+const unique = (paths: Iterable<string>) => [...new Set(paths)];
+
+export interface ExtensionPlan {
+  /** Loaded by lean (`--no-extensions`) children besides pi-jar. */
+  lean: string[];
+  /** Added with `--extension` to children that keep normal discovery. */
+  add: string[];
+  /** Set when something is disallowed: the complete list for `--no-extensions` children (pi-jar excluded). */
+  explicit?: string[];
+}
+
+/** Applies `+`/`-` extension rules to the parent's resolved extensions. Unknown allowed specs pass through to Pi. */
+export function planExtensions(rules: RuleList, catalog: ResourceCatalog, ownExtension: string): ExtensionPlan {
+  const denied = (resource: CatalogResource) => rules.deny.some(spec => extensionMatches(resource, spec));
+  const allowed: string[] = [];
+  const added: string[] = [];
+  for (const spec of rules.allow) {
+    const matched = catalog.extensions.filter(resource => extensionMatches(resource, spec) && !isPiJar(resource, ownExtension) && !denied(resource));
+    if (!matched.length) {
+      if (!rules.deny.some(deny => deny === spec)) { allowed.push(spec); added.push(spec); }
+      continue;
+    }
+    const enabled = matched.filter(resource => resource.enabled);
+    allowed.push(...(enabled.length ? enabled : matched).map(resource => resource.path));
+    if (!enabled.length) added.push(...matched.map(resource => resource.path));
+  }
+  const plan: ExtensionPlan = { lean: unique(allowed), add: unique(added) };
+  if (rules.deny.length) {
+    plan.explicit = unique([...catalog.extensions.filter(resource => resource.enabled && !denied(resource) && !isPiJar(resource, ownExtension))
+      .map(resource => resource.path), ...allowed]);
+  }
+  return plan;
+}
+
+/**
+ * Child skill paths for `--no-skills --skill ...`, or undefined to keep Pi's normal discovery.
+ * Defaults are the parent's enabled skills plus config allows minus config denies. A task list with any
+ * allowed entry (or an empty list) is exact; a list of only `-` entries subtracts from the defaults.
+ * Config denies always win: a task that explicitly asks for one is rejected.
+ */
+export function planSkills(config: RuleList, task: RuleList | undefined, catalog: ResourceCatalog, configLabel: string): string[] | undefined {
+  if (!config.allow.length && !config.deny.length && !task) return undefined;
+  const find = (spec: string, label: string): string[] => {
+    const resources = catalog.skills.filter(resource => skillMatches(resource, spec));
+    // A name picks one skill (enabled copy first), like Pi's own first-wins collision rule; a directory path keeps all.
+    const matched = (isPathSpec(spec) ? resources : resources.filter(resource => resource.enabled).concat(resources).slice(0, 1))
+      .map(resource => resource.path);
+    if (matched.length) return matched;
+    if (isPathSpec(spec)) return [spec];
+    throw new Error(`${label}: unknown skill "${spec}"`);
+  };
+  const configDenied = (path: string) => config.deny.some(spec => {
+    const resource = catalog.skills.find(item => item.path === path) ?? { path, enabled: true, source: "explicit" };
+    return skillMatches(resource, spec);
+  });
+  const defaults = unique([...catalog.skills.filter(resource => resource.enabled).map(resource => resource.path),
+    ...config.allow.flatMap(spec => find(spec, configLabel))]).filter(path => !configDenied(path));
+  if (!task) return defaults;
+  const subtract = new Set(task.deny.flatMap(spec => find(spec, "skills")));
+  if (task.allow.length || !task.deny.length) {
+    const requested = unique(task.allow.flatMap(spec => find(spec, "skills")));
+    const blocked = requested.filter(configDenied);
+    if (blocked.length) throw new Error(`skills disallowed by ${configLabel}: ${blocked.map(path => skillName({ path, enabled: true, source: "" })).join(", ")}`);
+    return requested.filter(path => !subtract.has(path));
+  }
+  return defaults.filter(path => !subtract.has(path));
+}

package/src/subagent-tools.ts

@@ -1,12 +1,78 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
 import { workspacePathAllowed } from "./delegate-worktree.ts";
 
 export const CHILD_TOOLS_ENV = "PI_JAR_CHILD_TOOLS";
 export const WEB_TOOLS = ["web_enable", "web_search", "fetch_content", "get_search_content", "source_check"] as const;
 export const RECURSIVE_TOOLS = new Set(["jar_delegate", "jar_subagent", "jar_council"]);
+export const SHELL_TOOLS = new Set(["bash", "powershell", "jar_shell"]);
+
+/** User-owned, profile-independent subagent capabilities in the agent directory. */
+export const SUBAGENT_CONFIG_FILE = "pi-jar-subagents.json";
+/** `+name` (or bare `name`) allows, `-name` disallows. */
+export interface RuleList { allow: readonly string[]; deny: readonly string[] }
+export interface SubagentConfig {
+  /** allow: trusted for `inheritTools` in every mode (e.g. mom_search); deny: never granted to any subagent. */
+  tools: RuleList;
+  /** allow: always loaded by children (npm:/git:/URL sources, paths, or names); deny: never loaded by children. */
+  extensions: RuleList;
+  /** allow: added to children's default skills (even if disabled in the parent); deny: never loaded by children. */
+  skills: RuleList;
+}
+export const EMPTY_RULES: RuleList = { allow: [], deny: [] };
+export const EMPTY_SUBAGENT_CONFIG: SubagentConfig = { tools: EMPTY_RULES, extensions: EMPTY_RULES, skills: EMPTY_RULES };
+
+/** Splits `+x`/`x`/`-x` entries; throws `${label}: ...` on empty or non-string entries. */
+export function parseRules(value: unknown, label: string, map: (entry: string) => string = entry => entry): RuleList {
+  if (value === undefined) return EMPTY_RULES;
+  if (!Array.isArray(value) || value.length > 64 || value.some(item => typeof item !== "string"))
+    throw new Error(`${label} must be an array of at most 64 strings`);
+  const allow = new Set<string>();
+  const deny = new Set<string>();
+  for (const raw of value as string[]) {
+    const text = raw.trim();
+    const negative = text.startsWith("-");
+    const entry = (negative || text.startsWith("+") ? text.slice(1) : text).trim();
+    if (!entry) throw new Error(`${label}: empty entry "${raw}"`);
+    (negative ? deny : allow).add(map(entry));
+  }
+  for (const entry of deny) allow.delete(entry); // disallow wins
+  return { allow: [...allow], deny: [...deny] };
+}
+
+/** `~/x`, absolute, `./x` and `dir/x` are paths (resolved from `directory`); `npm:`/`git:`/URLs and bare names stay as specs. */
+export function expandSpec(spec: string, directory: string, home = homedir()): string {
+  if (spec === "~" || spec.startsWith("~/")) return join(home, spec.slice(1));
+  if (isAbsolute(spec)) return spec;
+  if (spec.includes(":") || !spec.includes("/") && !spec.startsWith(".")) return spec;
+  return resolve(directory, spec);
+}
+
+/** Missing file means no extras; a malformed file is an error, never silently ignored. */
+export function loadSubagentConfig(directory: string, home = homedir()): SubagentConfig {
+  let text: string;
+  try { text = readFileSync(join(directory, SUBAGENT_CONFIG_FILE), "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return EMPTY_SUBAGENT_CONFIG;
+    throw error;
+  }
+  let raw: unknown;
+  try { raw = JSON.parse(text); } catch (error) { throw new Error(`${SUBAGENT_CONFIG_FILE}: invalid JSON: ${(error as Error).message}`); }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error(`${SUBAGENT_CONFIG_FILE}: expected a JSON object`);
+  const value = raw as Record<string, unknown>;
+  const label = (key: string) => `${SUBAGENT_CONFIG_FILE}: "${key}"`;
+  const tools = parseRules(value.tools, label("tools"));
+  const recursive = tools.allow.filter(name => RECURSIVE_TOOLS.has(name));
+  if (recursive.length) throw new Error(`${SUBAGENT_CONFIG_FILE}: recursive delegation tools are never available to subagents: ${recursive.join(", ")}`);
+  const extensions = parseRules(value.extensions, label("extensions"), spec => expandSpec(spec, directory, home));
+  const skills = parseRules(value.skills, label("skills"), spec => expandSpec(spec, directory, home));
+  return { tools, extensions, skills };
+}
 
 /** Multi-file tools must validate each effective target, not just the top-level default path. */
 export function worktreeToolViolation(root: string, cwd: string, name: string, args: unknown): string | undefined {
-  if (["bash", "powershell", "jar_shell"].includes(name)) return "Sandboxed worktree subagents cannot run shell tools.";
+  if (SHELL_TOOLS.has(name)) return "Sandboxed worktree subagents cannot run shell tools.";
   const pathTools = new Set(["read", "edit", "write", "grep", "find", "ls", "multi_file_edit"]);
   if (!pathTools.has(name)) return;
   if (!workspacePathAllowed(root, cwd, ".")) return "Sandboxed worktree subagent working directory is outside its workspace.";