pi-better-subagents 0.27.2 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/index.ts CHANGED
@@ -67,7 +67,7 @@ import {
67
67
  announceExecutionAdapter, observeSandboxPermissions, resolveCommandSettings, resolveSubagentPermissions,
68
68
  } from "./permission-policy.ts";
69
69
  import { resolveSubagentWorkspace } from "./git-workspace.ts";
70
- import { dirname, join } from "node:path";
70
+ import { dirname, isAbsolute, join } from "node:path";
71
71
  import {
72
72
  baseDir,
73
73
  taskWorkspaceDir,
@@ -164,6 +164,16 @@ import {
164
164
  } from "./continuation.ts";
165
165
  import { createHash } from "node:crypto";
166
166
  import { assertThinkingLevel, parseModelThinking, type ThinkingLevel } from "./thinking.ts";
167
+ import {
168
+ absolutizeSkillPaths,
169
+ configuredSkillExposure,
170
+ describeSkillExposure,
171
+ normalizeSkillExposure,
172
+ resolveSkillExposure,
173
+ skillLaunchArgs,
174
+ type SkillExposureMode,
175
+ } from "./skills.ts";
176
+ import type { DiscoveredSkill } from "./skill-picker.ts";
167
177
  import { createAgentOperations } from "./agent-operations.ts";
168
178
  import { createAgentSessionSettings } from "./agent-session-settings.ts";
169
179
  import {
@@ -209,6 +219,7 @@ import {
209
219
  type WorkerOperationsHost,
210
220
  } from "./worker-waits.ts";
211
221
  import { defaultUserRoot, type CatalogSnapshot } from "./catalog-store.ts";
222
+ import { restrictContextFilesToWorktree } from "./shared-worktree-context.ts";
212
223
 
213
224
  const SUBAGENT_MODE_ACTIONS: readonly AutocompleteItem[] = [
214
225
  { value: "settings", label: "settings", description: "Open delegation mode and concurrency settings" },
@@ -1827,6 +1838,31 @@ function sameLaunchTools(left: unknown, right: string): boolean {
1827
1838
  return typeof left === "string" && normalizeTools(left) === normalizeTools(right);
1828
1839
  }
1829
1840
 
1841
+ /**
1842
+ * A continuation may repeat its launch's skill exposure, and only that. The
1843
+ * saved paths are absolute (frozen at launch), so a caller repeating relative
1844
+ * paths is compared against the recipe's own workspace.
1845
+ *
1846
+ * Discovery and `[]` are different choices and must never compare equal: a
1847
+ * recipe with no `skills` key means "the child discovers the user catalog", and
1848
+ * an explicit `[]` means "load no skills at all". Treating an absent key as an
1849
+ * empty list would accept a continuation that silently disables discovery for a
1850
+ * conversation that was launched with it.
1851
+ */
1852
+ function sameLaunchSkills(value: unknown, recipe: ContinuationPlan["recipe"]): boolean {
1853
+ let requested: string[] | undefined;
1854
+ try {
1855
+ requested = normalizeSkillExposure(value, "skills");
1856
+ } catch {
1857
+ return false;
1858
+ }
1859
+ if (requested === undefined) return false;
1860
+ const saved = recipe.skills;
1861
+ if (saved === undefined) return false;
1862
+ const resolved = requested.length === 0 ? [] : absolutizeSkillPaths(requested, recipe.cwd);
1863
+ return resolved.length === saved.length && resolved.every((path, index) => path === saved[index]);
1864
+ }
1865
+
1830
1866
  function sameLaunchRoles(left: unknown, right: string | readonly string[] | undefined): boolean {
1831
1867
  if (typeof left === "string") return left === right;
1832
1868
  if (Array.isArray(left) && Array.isArray(right)) {
@@ -1851,6 +1887,7 @@ function continuationLaunchConflicts(
1851
1887
  check("alias", (value) => value === recipe.alias);
1852
1888
  check("tools", (value) => sameLaunchTools(value, recipe.tools));
1853
1889
  check("exclude_tools", (value) => typeof value === "string" && normalizeTools(value) === normalizeTools(recipe.excludeTools ?? ""));
1890
+ check("skills", (value) => sameLaunchSkills(value, recipe));
1854
1891
  check("clean", (value) => value === recipe.clean);
1855
1892
  check("sandbox", (value) => value === recipe.sandbox);
1856
1893
  check("sandbox_dir", (value) => sameLaunchPath(value, recipe.sandboxDir));
@@ -1942,12 +1979,86 @@ function catalogRoleSchema(purpose: string) {
1942
1979
  ], { description: `${one} ${many}` }));
1943
1980
  }
1944
1981
 
1982
+ /** Loaded Pi skill metadata from the current prompt resources. No model call, no directory scan. */
1983
+ function discoveredSkillsFromContext(ctx: { getSystemPromptOptions?: () => { skills?: readonly unknown[] } }): DiscoveredSkill[] {
1984
+ try {
1985
+ const loaded = ctx.getSystemPromptOptions?.().skills ?? [];
1986
+ const skills: DiscoveredSkill[] = [];
1987
+ for (const raw of loaded) {
1988
+ if (!raw || typeof raw !== "object") continue;
1989
+ const skill = raw as {
1990
+ name?: unknown; description?: unknown; filePath?: unknown; baseDir?: unknown;
1991
+ sourceInfo?: { source?: unknown };
1992
+ };
1993
+ if (typeof skill.name !== "string" || !skill.name || typeof skill.filePath !== "string" || !skill.filePath) continue;
1994
+ skills.push({
1995
+ name: skill.name,
1996
+ description: typeof skill.description === "string" ? skill.description : "",
1997
+ path: skill.filePath,
1998
+ ...(typeof skill.baseDir === "string" ? { baseDir: skill.baseDir } : {}),
1999
+ ...(typeof skill.sourceInfo?.source === "string" ? { source: skill.sourceInfo.source } : {}),
2000
+ });
2001
+ }
2002
+ return skills;
2003
+ } catch {
2004
+ return [];
2005
+ }
2006
+ }
2007
+
1945
2008
  export default function (pi: ExtensionAPI) {
2009
+ // A standalone Subagents install has no Harness extension, so the parent
2010
+ // session applies the same linked-worktree project boundary as its children.
2011
+ pi.on("before_agent_start", (event) => {
2012
+ restrictContextFilesToWorktree(event.systemPromptOptions, PiCodingAgent.getAgentDir());
2013
+ });
1946
2014
  initializeNavigatorPanels(pi);
1947
2015
  const agentSessionSettings = createAgentSessionSettings(pi);
1948
2016
  let catalogModelRegistry: ExtensionContext["modelRegistry"] | undefined;
1949
2017
  let delegationOverride: DelegationMode | undefined;
1950
2018
  let capOverride: number | undefined;
2019
+ interface SkillSelection { mode: SkillExposureMode; paths: string[] }
2020
+ let skillsOverride: SkillSelection | undefined;
2021
+ const savedSkills = (): SkillSelection & { source: "config" | "default"; error?: string } => {
2022
+ try {
2023
+ return configuredSkillExposure(loadConfig().defaultSkills);
2024
+ } catch (error) {
2025
+ return {
2026
+ mode: "inherit", paths: [], source: "config",
2027
+ error: error instanceof Error ? error.message : String(error),
2028
+ };
2029
+ }
2030
+ };
2031
+ const activeSkills = (): SkillSelection & { source: "session" | "config" | "default"; error?: string } => {
2032
+ if (skillsOverride) return { ...skillsOverride, source: "session" };
2033
+ return savedSkills();
2034
+ };
2035
+ /** The same active default a launch sees, shaped for catalog inspection. */
2036
+ const readSkillDefaults = () => {
2037
+ const skills = activeSkills();
2038
+ const value = skills.mode === "inherit" ? undefined : [...skills.paths];
2039
+ const error = skills.error ?? (skills.mode === "explicit" && skills.paths.length === 0
2040
+ ? "Selected skills has no paths. Add at least one skill path or choose No skill catalog."
2041
+ : undefined);
2042
+ return { value, source: skills.source, ...(error ? { error } : {}) };
2043
+ };
2044
+ const changeSkills = (mode: SkillExposureMode, paths: readonly string[]): void => {
2045
+ if (mode !== "explicit" && paths.length > 0) throw new Error("Only Selected skills carries a path list.");
2046
+ if (mode === "explicit" && paths.some((path) => !isAbsolute(path))) {
2047
+ throw new Error("Enter absolute skill paths so every child resolves the same files.");
2048
+ }
2049
+ const next = { mode, paths: [...paths] };
2050
+ skillsOverride = next;
2051
+ pi.appendEntry("pi-better-subagents-skills", { version: 1, ...next });
2052
+ };
2053
+ /** The current-session choice, with `{}` preserving explicit discovery. */
2054
+ const sessionSkillChoice = (): { value?: unknown } | undefined => {
2055
+ if (!skillsOverride) return undefined;
2056
+ if (skillsOverride.mode === "explicit" && skillsOverride.paths.length === 0) {
2057
+ throw new Error("Selected skills has no paths. Add at least one skill path or choose No skill catalog before launching.");
2058
+ }
2059
+ if (skillsOverride.mode === "inherit") return {};
2060
+ return { value: skillsOverride.mode === "none" ? [] : [...skillsOverride.paths] };
2061
+ };
1951
2062
  const activeConcurrencyCap = (): number => capOverride ?? normalizeConcurrencyCap(loadConfig().maxConcurrent);
1952
2063
  const changeCap = (cap: number): void => {
1953
2064
  if (!isConcurrencyCap(cap)) throw new Error("Concurrent subagents must be a positive whole number.");
@@ -1961,8 +2072,10 @@ export default function (pi: ExtensionAPI) {
1961
2072
  const resetSettings = (): void => {
1962
2073
  capOverride = undefined;
1963
2074
  delegationOverride = undefined;
2075
+ skillsOverride = undefined;
1964
2076
  pi.appendEntry("pi-better-subagents-cap", { version: 1, maxConcurrent: null });
1965
2077
  pi.appendEntry("pi-better-subagents-delegation", { version: 1, mode: null });
2078
+ pi.appendEntry("pi-better-subagents-skills", { version: 1, mode: null });
1966
2079
  };
1967
2080
  const activeDelegationMode = (): DelegationMode => delegationOverride ?? normalizeDelegationMode(loadConfig().delegationMode);
1968
2081
  const countRunning = () =>
@@ -1996,7 +2109,30 @@ export default function (pi: ExtensionAPI) {
1996
2109
  }, countRunning(), getSharedCapacityGate(countRunning).pending);
1997
2110
  const saveSettings = (): { ok: boolean; message: string } => {
1998
2111
  try {
1999
- writeSubagentSettings({ delegationMode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap() });
2112
+ const skills = activeSkills();
2113
+ if (!skillsOverride && skills.error) {
2114
+ return {
2115
+ ok: false,
2116
+ message: `Cannot save subagent defaults: the saved defaultSkills value is invalid (${skills.error}). ` +
2117
+ `Choose a skill mode in this session to replace it, or fix the saved config first.`,
2118
+ };
2119
+ }
2120
+ if (skills.mode === "explicit" && skills.paths.length === 0) {
2121
+ return { ok: false, message: "Add at least one skill path, or choose No skill catalog to load none." };
2122
+ }
2123
+ // Saving mode and cap must not write a skill key into a config that
2124
+ // never had one. Discovery only replaces a saved choice when a saved
2125
+ // skill value already exists.
2126
+ const savedSkillValue = loadConfig().defaultSkills;
2127
+ const hasSavedSkillChoice = savedSkillValue !== undefined && savedSkillValue !== null;
2128
+ writeSubagentSettings({
2129
+ delegationMode: activeDelegationMode(),
2130
+ maxConcurrent: activeConcurrencyCap(),
2131
+ ...(skills.mode === "inherit" && !hasSavedSkillChoice ? {} : {
2132
+ // null is an explicit discovery choice; it must override a saved path list.
2133
+ defaultSkills: skills.mode === "inherit" ? null : [...skills.paths],
2134
+ }),
2135
+ });
2000
2136
  resetSettings();
2001
2137
  return { ok: true, message: "Subagent defaults saved." };
2002
2138
  } catch (error) {
@@ -2025,6 +2161,7 @@ export default function (pi: ExtensionAPI) {
2025
2161
  const restoreDelegationMode = (ctx: ExtensionContext): void => {
2026
2162
  delegationOverride = undefined;
2027
2163
  capOverride = undefined;
2164
+ skillsOverride = undefined;
2028
2165
  const branch = ctx.sessionManager?.getBranch?.();
2029
2166
  if (!Array.isArray(branch)) return;
2030
2167
  for (const entry of branch) {
@@ -2035,6 +2172,19 @@ export default function (pi: ExtensionAPI) {
2035
2172
  else if (isConcurrencyCap(data.maxConcurrent)) capOverride = data.maxConcurrent;
2036
2173
  }
2037
2174
  }
2175
+ if (entry.type === "custom" && entry.customType === "pi-better-subagents-skills") {
2176
+ const data = entry.data as { version?: unknown; mode?: unknown; paths?: unknown } | null;
2177
+ if (data?.version !== 1) continue;
2178
+ if (data.mode === null) {
2179
+ skillsOverride = undefined;
2180
+ } else if ((data.mode === "inherit" || data.mode === "none") && Array.isArray(data.paths) && data.paths.length === 0) {
2181
+ skillsOverride = { mode: data.mode, paths: [] };
2182
+ } else if (data.mode === "explicit" && Array.isArray(data.paths)
2183
+ && data.paths.every((path): path is string => typeof path === "string" && isAbsolute(path))) {
2184
+ skillsOverride = { mode: "explicit", paths: [...data.paths] };
2185
+ }
2186
+ continue;
2187
+ }
2038
2188
  if (entry.type !== "custom" || entry.customType !== "pi-better-subagents-delegation") continue;
2039
2189
  const data = entry.data as { version?: unknown; mode?: unknown } | null;
2040
2190
  if (data?.version !== 1) continue;
@@ -2141,6 +2291,8 @@ export default function (pi: ExtensionAPI) {
2141
2291
  type SpawnParams = {
2142
2292
  prompt: string; name?: string; model?: string; thinking?: ThinkingLevel; tools?: string;
2143
2293
  exclude_tools?: string; clean?: boolean; sandbox?: boolean;
2294
+ /** Skill exposure for this launch; omit to inherit catalog/config/discovery. */
2295
+ skills?: readonly string[];
2144
2296
  sandbox_dir?: string; callback?: boolean; cwd?: string;
2145
2297
  git_clone_workspace?: boolean; approve?: boolean; allow_nested?: boolean;
2146
2298
  agent?: string; role?: string | readonly string[]; alias?: string;
@@ -2207,6 +2359,11 @@ export default function (pi: ExtensionAPI) {
2207
2359
  modelNote?: string;
2208
2360
  }> {
2209
2361
  assertThinkingLevel(p.thinking);
2362
+ // Skill exposure is a caller choice, not a launch: validate its shape
2363
+ // before any attempt directory or capacity effect exists. A continuation
2364
+ // validates too, so a malformed repeat is a shape error rather than being
2365
+ // reported as a recipe conflict.
2366
+ normalizeSkillExposure(p.skills, "skills");
2210
2367
  // A conversation parked on an observed wait resumes through the
2211
2368
  // coordinator's claim. An ordinary manual continuation would leave that
2212
2369
  // automatic resume armed for the same assignment, so it is refused until
@@ -2322,6 +2479,28 @@ export default function (pi: ExtensionAPI) {
2322
2479
  const cwd = workspace.cwd;
2323
2480
  const requestedSandboxDir = workspace.requestedSandboxDir;
2324
2481
 
2482
+ // Skill exposure is decided once per attempt. A continuation replays the
2483
+ // frozen recipe (including its absence, which keeps discovery); a fresh
2484
+ // launch resolves launch option → catalog role/agent → this session's
2485
+ // default → saved config default → discovery. Relative paths belong to
2486
+ // the workspace the child runs in.
2487
+ const sessionSkills = resume ? undefined : sessionSkillChoice();
2488
+ if (!resume && !sessionSkills) {
2489
+ const saved = savedSkills();
2490
+ if (saved.error) {
2491
+ throw new Error(`Cannot read config defaultSkills: ${saved.error}`);
2492
+ }
2493
+ }
2494
+ const skills = resolveSkillExposure(resume
2495
+ ? { saved: { paths: resume.recipe.skills }, cwd }
2496
+ : {
2497
+ requested: p.skills,
2498
+ catalog: p.catalog?.effective?.skills?.value,
2499
+ session: sessionSkills,
2500
+ configured: cfg.defaultSkills,
2501
+ cwd,
2502
+ });
2503
+
2325
2504
  if (requestedSandboxDir) mkdirSync(requestedSandboxDir, { recursive: true });
2326
2505
  writeFileSync(promptPathFor(id), p.prompt);
2327
2506
 
@@ -2485,6 +2664,7 @@ export default function (pi: ExtensionAPI) {
2485
2664
  ...commandExtArgs,
2486
2665
  ...(model ? ["--model", model] : []),
2487
2666
  ...(thinking ? ["--thinking", thinking] : []),
2667
+ ...skillLaunchArgs(skills),
2488
2668
  ...(allow && !sandboxEnabled ? ["--tools", allow] : []),
2489
2669
  ...(excludes.size ? ["--exclude-tools", [...excludes].join(",")] : []),
2490
2670
  ...(sandboxEnabled ? ["--no-builtin-tools", "--no-approve"] : approve ? ["--approve"] : []),
@@ -2644,6 +2824,7 @@ export default function (pi: ExtensionAPI) {
2644
2824
  effort: thinking,
2645
2825
  tools: allow,
2646
2826
  excludeTools: requestedExcludes.size ? [...requestedExcludes].join(",") : undefined,
2827
+ skills: skills.mode === "inherit" ? undefined : [...skills.paths],
2647
2828
  clean,
2648
2829
  allowNested,
2649
2830
  approve,
@@ -2665,6 +2846,8 @@ export default function (pi: ExtensionAPI) {
2665
2846
  id, name: launchName, status: "running",
2666
2847
  pid: spawned.pid, spawnPid: process.pid, spawnPidStartTime: parentStartToken(), model,
2667
2848
  effort: thinking, cwd,
2849
+ ...(skills.mode === "inherit" ? {} : { skills: [...skills.paths] }),
2850
+ skillsSource: skills.source,
2668
2851
  ...identity,
2669
2852
  promptPreview: p.prompt.slice(0, 200),
2670
2853
  startedAt, logPath: logPathFor(id), sessionId,
@@ -2769,7 +2952,9 @@ export default function (pi: ExtensionAPI) {
2769
2952
  `Add a toolExtensions entry in config.json.\n`
2770
2953
  : "");
2771
2954
  const modelNote = catalogDefaultNote(resume ? undefined : p.catalog, model, thinking);
2772
- return { id, meta, spawned, runtime: runtime + (meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""), warn, sandboxDir, modelNote };
2955
+ // The resolved skill exposure rides with the runtime summary, which every
2956
+ // launch and continuation message already prints.
2957
+ return { id, meta, spawned, runtime: `${runtime}${describeSkillExposure(skills)}\n${meta.timing ? `${formatTimingLimits(meta.timing, startedAt)}\n` : ""}`, warn, sandboxDir, modelNote };
2773
2958
  } catch (error) {
2774
2959
  // A launch that never committed metadata is not a run: drop
2775
2960
  // everything the attempt created so the registry keeps no
@@ -3040,13 +3225,13 @@ export default function (pi: ExtensionAPI) {
3040
3225
  "After subagent_spawn, do NOT call subagent_output or subagent_result in a loop to wait for the result, and do NOT sleep. The run completes on its own and reports back on the next turn.",
3041
3226
  "Call subagent_result after a completion or attention callback, or when the user explicitly asks for the result. Use subagent_output only when the user explicitly asks how a run is progressing; never use either tool to poll.",
3042
3227
  ...SUBAGENT_ORCHESTRATION_GUIDELINES,
3043
- "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
3228
+ "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. When the task already names its SKILL.md by path, pass skills with those absolute paths (or [] for none) so the child does not advertise the whole skills catalog. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
3044
3229
  ...CATALOG_GUIDELINES,
3045
3230
  "Subagent sandboxing defaults to off. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Set sandbox:true to request kernel confinement, including without published settings. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
3046
3231
  "Every launch automatically joins one shared harness-owned watcher, including batch launches; it stops when the last active run ends. Do not start a separate heartbeat or background watcher for subagents. No progress for stuck_minutes (default 10) wakes you once without stopping the run. Elapsed-time limits are opt-in: deadline_minutes steers the child to wrap up and later stops it after grace_minutes, while max_minutes stops it without grace. Do not set elapsed-time limits merely because a task may take a while; use them only when the work needs a real wall-clock bound.",
3047
3232
  "Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
3048
3233
  "Saved conversations persist automatically. To continue a completed or stopped worker in its own history, call subagent_spawn with session_id (the native session id reported for the saved conversation) and the new feedback as prompt. Omit session_id for a brand-new conversation.",
3049
- "On a continuation, pass prompt, session_id, and only optional model, thinking, callback, or timing overrides. Launch-only options (name, agent, role, alias, tools, exclude_tools, clean, sandbox, sandbox_dir, cwd, git_clone_workspace, approve, allow_nested) keep the saved recipe; repeat them only with the same value, otherwise the launch is refused.",
3234
+ "On a continuation, pass prompt, session_id, and only optional model, thinking, callback, or timing overrides. Launch-only options (name, agent, role, alias, tools, exclude_tools, skills, clean, sandbox, sandbox_dir, cwd, git_clone_workspace, approve, allow_nested) keep the saved recipe; repeat them only with the same value, otherwise the launch is refused.",
3050
3235
  "Do not restate the original task or role when continuing: they already live in the saved conversation. A running or orphaned latest attempt blocks continuation until it stops, and missing saved history is refused rather than recreated.",
3051
3236
  ],
3052
3237
  parameters: Type.Object({
@@ -3061,6 +3246,7 @@ export default function (pi: ExtensionAPI) {
3061
3246
  thinking: Type.Optional(Type.String({ description: "Reasoning effort for the child: off, minimal, low, medium, high, xhigh, or max. Omit to use the agent or role default; without one, the Pi/model default." })),
3062
3247
  tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
3063
3248
  exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
3249
+ skills: Type.Optional(Type.Array(Type.String(), { description: "Skill exposure for the child. Omit to inherit the catalog role/agent choice, then config defaultSkills, then user-catalog discovery. [] loads no skills (--no-skills). Absolute paths load exactly those skills (--no-skills --skill <path>), which is how a task that names one SKILL.md by path avoids advertising the whole catalog. Relative paths resolve against the child workspace." })),
3064
3250
  clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
3065
3251
  sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox. Defaults to off without published settings. True requests kernel confinement; false cannot bypass an enabled human profile." })),
3066
3252
  sandbox_dir: Type.Optional(Type.String({ description: "Confine writes to (and run the child in) this directory instead of the working dir. Created if missing." })),
@@ -3229,6 +3415,7 @@ export default function (pi: ExtensionAPI) {
3229
3415
  thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
3230
3416
  tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
3231
3417
  exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
3418
+ skills: Type.Optional(Type.Array(Type.String(), { description: "Skill exposure applied to every job. Per-job skills override this. [] loads no skills; absolute paths load exactly those skills; omit to inherit discovery." })),
3232
3419
  sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile. Defaults to off without published settings; true requests kernel confinement." })),
3233
3420
  sandbox_dir: Type.Optional(Type.String({ description: "Writable root for every job." })),
3234
3421
  callback: Type.Optional(Type.Boolean({ description: "Default TRUE: post result back on completion." })),
@@ -3251,6 +3438,7 @@ export default function (pi: ExtensionAPI) {
3251
3438
  thinking: Type.Optional(Type.String()),
3252
3439
  tools: Type.Optional(Type.String()),
3253
3440
  exclude_tools: Type.Optional(Type.String()),
3441
+ skills: Type.Optional(Type.Array(Type.String())),
3254
3442
  sandbox: Type.Optional(Type.Boolean()),
3255
3443
  sandbox_dir: Type.Optional(Type.String()),
3256
3444
  callback: Type.Optional(Type.Boolean()),
@@ -3502,6 +3690,8 @@ export default function (pi: ExtensionAPI) {
3502
3690
  const agentOperations = createAgentOperations({
3503
3691
  projectConfigDirName,
3504
3692
  sessionSettings: agentSessionSettings,
3693
+ readSkillDefaults,
3694
+ discoverSkills: (commandCtx) => discoveredSkillsFromContext(commandCtx),
3505
3695
  editableModels: () => catalogModelRegistry?.getAvailable().map((model) => `${model.provider}/${model.id}`) ?? [],
3506
3696
  propagateCommandContext(commandCtx) {
3507
3697
  noteCatalogHost(catalogHostFrom(commandCtx));
@@ -3532,21 +3722,28 @@ export default function (pi: ExtensionAPI) {
3532
3722
  const next = await ctx.ui.custom<"agents" | undefined>((tui, theme, _kb, done) => createSubagentSettingsPage(theme, {
3533
3723
  get: () => {
3534
3724
  const settings = effectiveSettings();
3725
+ const skills = activeSkills();
3535
3726
  return {
3536
3727
  mode: settings.delegationMode, maxConcurrent: settings.maxConcurrent,
3537
3728
  modeSource: settings.sources.delegationMode,
3538
3729
  capSource: settings.sources.maxConcurrent,
3539
3730
  defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
3540
3731
  defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
3732
+ skillsMode: skills.mode, skillsPaths: skills.paths, skillsSource: skills.source,
3733
+ skillsError: skills.error,
3541
3734
  };
3542
3735
  },
3543
- changeMode, changeCap, save: saveSettings, reset: resetSettings,
3736
+ changeMode, changeCap, changeSkills, save: saveSettings, reset: resetSettings,
3737
+ discoverSkills: () => discoveredSkillsFromContext(ctx),
3544
3738
  // Close this page first; the catalog opens after ui.custom resolves.
3545
3739
  openAgents: () => done("agents"),
3546
3740
  }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done(undefined)));
3547
3741
  if (next === "agents") await agentOperations.openCatalog(ctx);
3548
3742
  } else {
3549
- ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}. Concurrent subagents: ${activeConcurrencyCap()}. Use /subagents mode <mode> or /subagents cap <number>; /subagents save persists both.`, "info");
3743
+ const skills = activeSkills();
3744
+ const skillChoice = skills.mode === "inherit" ? "discovery"
3745
+ : skills.mode === "none" ? "no skills" : `${skills.paths.length} selected skills`;
3746
+ ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}. Concurrent subagents: ${activeConcurrencyCap()}. Skills: ${skillChoice}. Use /subagents mode <mode>, cap <number>, or settings; /subagents save persists them.`, "info");
3550
3747
  }
3551
3748
  };
3552
3749
  const contribution = { id: "subagents", label: "Subagents", command: "/subagents settings", open: openSettings };
@@ -3571,7 +3768,14 @@ export default function (pi: ExtensionAPI) {
3571
3768
  }
3572
3769
  const requested = tokens[1];
3573
3770
  if (tokens.length === 1 && tokens[0] === "save") {
3574
- if (ctx.hasUI && !(await ctx.ui.confirm("Save subagent defaults?", `Future sessions will start in ${activeDelegationMode()} with a cap of ${activeConcurrencyCap()}.`))) {
3771
+ const skills = activeSkills();
3772
+ if (skills.mode === "explicit" && skills.paths.length === 0) {
3773
+ ctx.ui.notify("Add at least one skill path, or choose No skill catalog to load none.", "warning");
3774
+ return;
3775
+ }
3776
+ const skillChoice = skills.mode === "inherit" ? "skill discovery"
3777
+ : skills.mode === "none" ? "no skills" : `${skills.paths.length} selected skills`;
3778
+ if (ctx.hasUI && !(await ctx.ui.confirm("Save subagent defaults?", `Future sessions will start in ${activeDelegationMode()} with a cap of ${activeConcurrencyCap()} and ${skillChoice}.`))) {
3575
3779
  ctx.ui.notify("Subagent defaults unchanged.", "info");
3576
3780
  return;
3577
3781
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-subagents",
3
- "version": "0.27.2",
3
+ "version": "0.28.0",
4
4
  "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
5
5
  "license": "MIT",
6
6
  "type": "module",
package/registry.ts CHANGED
@@ -13,6 +13,7 @@
13
13
  */
14
14
 
15
15
  import type { RunTiming } from "./timing.ts";
16
+ import type { SkillExposureSource } from "./skills.ts";
16
17
  import { execFileSync } from "node:child_process";
17
18
  import { createHash, randomBytes } from "node:crypto";
18
19
  import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
@@ -109,6 +110,12 @@ export interface LaunchRecipe {
109
110
  /** Effective tool allowlist (already adjusted for confinement). */
110
111
  tools: string;
111
112
  excludeTools?: string;
113
+ /**
114
+ * Effective skill exposure: absent means discovery of the user catalog,
115
+ * `[]` means none, and paths mean exactly those skills. Recipes written
116
+ * before skill controls existed have no key and keep discovery.
117
+ */
118
+ skills?: string[];
112
119
  clean: boolean;
113
120
  allowNested: boolean;
114
121
  approve: boolean;
@@ -191,6 +198,10 @@ export interface RunMeta {
191
198
  model?: string;
192
199
  /** Reasoning effort passed to the child via Pi's --thinking option. */
193
200
  effort?: string;
201
+ /** Effective skill exposure when it is not discovery; absent means discovery. */
202
+ skills?: string[];
203
+ /** Which layer chose that exposure: launch, catalog, config, default, or a replayed recipe. */
204
+ skillsSource?: SkillExposureSource;
194
205
  cwd: string;
195
206
  /** First ~200 chars of the task prompt, for listings. */
196
207
  promptPreview: string;