pi-better-subagents 0.27.1 → 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/README.md CHANGED
@@ -15,7 +15,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
15
15
  - Continue a saved conversation with `subagent_spawn({ session_id, prompt })`, or use `session_name` for a unique name in the current folder. Sessions persist by default. Lists show session IDs and search locally; `all:true` searches globally. Batch jobs use the same selectors. See [continuing a saved conversation](docs/usage.md#continuing-a-saved-conversation).
16
16
  - Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
17
17
  - Opt-in OS task sandboxing on macOS and Linux.
18
- - Explicit tool allowlists for child sessions.
18
+ - Explicit tool allowlists for child sessions, and `skills` for prompt exposure: omit it to keep user-catalog discovery, pass `[]` for no skills, or pass absolute `SKILL.md` paths for exactly those. See [skill exposure](docs/usage.md#skill-exposure).
19
19
  - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
20
20
  - Live background-work navigator for active runs.
21
21
  - Harness-owned run timing: every run gets a no-progress wake (10 min), while wall-clock soft deadlines and hard ceilings are opt-in so productive agents are not stopped solely for taking a long time. Configure per spawn with `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`, or globally in `config.json` / `PI_SUBAGENT_*_MINUTES`. See [usage notes](docs/usage.md#run-timing-deadline-ceiling-stuck).
@@ -80,13 +80,23 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
80
80
 
81
81
  The user config sets `delegationMode` to `manual`, `adaptive` (default), or
82
82
  `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
83
- for delegation mode and the concurrent-subagent cap (default 6). Edits apply to
84
- this session and persist across reloads; Ctrl+S saves both as defaults, and
85
- Reset to defaults clears
86
- session overrides. Agents opens the same catalog as `/agents`.
87
- `/subagents mode manual|adaptive|coordinator` and
83
+ for delegation mode, the concurrent-subagent cap (default 6), and the default
84
+ skill exposure. Skill exposure cycles between Discover automatically and No skill
85
+ catalog. The Selected skills row opens the same searchable checkbox picker used
86
+ by `/agents`: it lists loaded skills by name and description, Space toggles one,
87
+ Enter applies, and typing filters without dropping checked items. Saved paths
88
+ missing from discovery stay visible as unavailable and survive apply. Zero
89
+ checked applies No skill catalog, not discovery. Manual Add skill path remains
90
+ available. The page names whether the current value comes from the saved config
91
+ or this session. The session choice controls the next launch before Ctrl+S, and
92
+ edits persist across reloads. Ctrl+S saves mode, cap, and skill exposure as
93
+ defaults, and Reset to defaults clears session overrides, including the skill
94
+ list. Agents opens the same catalog as `/agents`; a definition that inherits
95
+ skill exposure shows whether the live value comes from this session, saved
96
+ config, or discovery, and an invalid draft is marked invalid rather than shown
97
+ as discovery. `/subagents mode manual|adaptive|coordinator` and
88
98
  `/subagents cap <number>` are command equivalents; `/subagents save` persists
89
- both. Lowering the cap blocks new single and batch launches, including launches
99
+ the current settings. Lowering the cap blocks new single and batch launches, including launches
90
100
  still preparing, without stopping running work. Saved configuration changes are
91
101
  picked up on subsequent reads; explicit session overrides still take precedence.
92
102
  Before every model request, including continuations after tool calls,
@@ -112,7 +122,9 @@ Saved defaults live in global `~/.pi/agent/settings.json` under
112
122
  `piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
113
123
  reinstalls and upgrades. The old user config migrates on first use. Global values
114
124
  override the package's `config.json`, which remains a compatibility fallback.
115
- Save existing mode and cap choices with `/subagents save` or Ctrl+S. Put other
125
+ Save existing mode, cap, and skill choices with `/subagents save` or Ctrl+S.
126
+ Discovery is saved as `defaultSkills: null`, which clears a previously saved
127
+ path list. Put other
116
128
  custom config keys in `piBetterHarness.subagents` as well; edits made only inside
117
129
  the installed package can be lost on upgrade.
118
130
 
package/agent-commands.ts CHANGED
@@ -9,7 +9,7 @@
9
9
  import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
10
10
  import { isAbsolute, resolve } from "node:path";
11
11
  import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
12
- import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type OperationView } from "./agent-inspection.ts";
12
+ import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type OperationView, type ReadSkillDefaults } from "./agent-inspection.ts";
13
13
  import { createCatalogComponent } from "./catalog-ui.ts";
14
14
  import type { ScopedModelLike } from "./catalog-editor.ts";
15
15
  import {
@@ -51,6 +51,8 @@ import {
51
51
  } from "./codex-import.ts";
52
52
  import { resolveRoleAssignment } from "./role-assignment.ts";
53
53
  import { saveAgentSessionDefaults, withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
54
+ import { saveSkillExposure } from "./catalog-skill-edits.ts";
55
+ import type { DiscoveredSkill } from "./skill-picker.ts";
54
56
 
55
57
  const MODEL_PATTERN = /^[a-z0-9][a-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._+-]*$/;
56
58
  const TIER_PATTERN = /^[a-z][a-z0-9-]{0,32}$/;
@@ -72,6 +74,12 @@ export interface AgentCommandDeps {
72
74
  now?: () => string;
73
75
  /** Resolution unit injects availability, actual model/effort, and launchability. */
74
76
  enrich?: LaunchEnricher;
77
+ /** Live session/config default skill choice; absent keeps the legacy config read. */
78
+ readSkillDefaults?: ReadSkillDefaults;
79
+ /** Read loaded Pi skill metadata for the checkbox picker. */
80
+ discoverSkills?: (ctx: ExtensionCommandContext) => readonly DiscoveredSkill[];
81
+ /** Snapshot captured for this invocation. */
82
+ discoveredSkills?: readonly DiscoveredSkill[];
75
83
  sessionSettings?: AgentSessionSettings;
76
84
  /** Available foreground registry models, as provider/id. */
77
85
  editableModels?: () => readonly string[];
@@ -153,6 +161,7 @@ export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">,
153
161
  /** Slash commands and settings shortcuts must resolve against the same live context. */
154
162
  export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandContext, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
155
163
  deps.propagateCommandContext?.(ctx);
164
+ const discoveredSkills = deps.discoverSkills?.(ctx) ?? deps.discoveredSkills;
156
165
  return executeAgentsCommand(args, {
157
166
  cwd: ctx.cwd,
158
167
  hasUI: ctx.hasUI,
@@ -160,7 +169,7 @@ export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandC
160
169
  isProjectTrusted: () => ctx.isProjectTrusted(),
161
170
  scopedModels: scopedModelsFromContext(ctx),
162
171
  ui: ctx.ui,
163
- }, deps);
172
+ }, discoveredSkills ? { ...deps, discoveredSkills } : deps);
164
173
  }
165
174
 
166
175
  /**
@@ -231,7 +240,7 @@ export function parseCommandArgs(input: string): ParsedArgs {
231
240
 
232
241
  async function runList(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentCommandDeps): Promise<AgentCommandResult> {
233
242
  if (parsed.positionals.length > 1) return result("error", "list", false, "list does not take extra arguments. Use /agents show <id> to inspect one definition.");
234
- const listed = presentCatalog(readCatalog(loc), deps.enrich);
243
+ const listed = presentCatalog(readCatalog(loc), deps.enrich, deps.readSkillDefaults);
235
244
  return {
236
245
  ...result("ok", "list", false, `Listed from a fresh catalog read. File edits show up on the next list or launch; /agents reload is not required for that.\n${listed.text}`),
237
246
  diagnostics: listed.diagnostics,
@@ -241,7 +250,7 @@ async function runList(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentComm
241
250
 
242
251
  async function runReload(parsed: ParsedArgs, loc: CatalogLocation, deps: AgentCommandDeps): Promise<AgentCommandResult> {
243
252
  if (parsed.positionals.length > 1) return result("error", "reload", false, "reload does not take extra arguments.");
244
- const listed = presentCatalog(withAgentSessionSettings(refreshCatalog(loc), loc.sessionSettings), deps.enrich);
253
+ const listed = presentCatalog(withAgentSessionSettings(refreshCatalog(loc), loc.sessionSettings), deps.enrich, deps.readSkillDefaults);
245
254
  return {
246
255
  ...result("ok", "reload", false, `Reloaded revision ${listed.revision} for inspection. The next launch reads the files again on its own; this command is not a prerequisite.\n${listed.text}`),
247
256
  diagnostics: listed.diagnostics,
@@ -263,7 +272,7 @@ async function runShow(
263
272
  return clarification(command, `${command} needs an id. UI is unavailable, so none was selected. Run /agents list and pass the id. Nothing was written.`);
264
273
  }
265
274
  if (host.mode === "tui" && host.ui.custom) {
266
- const listed = presentCatalog(readCatalog(loc), deps.enrich);
275
+ const listed = presentCatalog(readCatalog(loc), deps.enrich, deps.readSkillDefaults);
267
276
  return { ...result("ok", command, false, listed.text), diagnostics: listed.diagnostics, data: listed };
268
277
  }
269
278
  const ids = listCatalog(readCatalog(loc)).map((entry) => entry.id);
@@ -272,7 +281,7 @@ async function runShow(
272
281
  if (!selected) return clarification(command, "Inspect was dismissed. Nothing was written.");
273
282
  id = selected;
274
283
  }
275
- const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich);
284
+ const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich, deps.readSkillDefaults);
276
285
  return {
277
286
  ok: view.found,
278
287
  status: view.found ? "ok" : "error",
@@ -375,7 +384,7 @@ async function runCreate(
375
384
  if (!saved.ok || !saved.path) {
376
385
  return { ...result("error", "create", false, saved.diagnostics.map((item) => item.message).join("\n") || "Create did not write a file."), diagnostics: saved.diagnostics };
377
386
  }
378
- const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich);
387
+ const view = presentCatalogEntry(readCatalog(loc), id, deps.enrich, deps.readSkillDefaults);
379
388
  return {
380
389
  ok: true,
381
390
  status: "ok",
@@ -525,7 +534,7 @@ async function runImport(
525
534
  if (!saved.ok || !saved.path) {
526
535
  return { ...result("error", "import-codex", false, saved.diagnostics.map((item) => item.message).join("\n") || "Import did not write a file."), diagnostics: [...parsedSource.diagnostics, ...built.diagnostics, ...saved.diagnostics] };
527
536
  }
528
- const view = presentCatalogEntry(readCatalog(loc), built.definition.id, deps.enrich);
537
+ const view = presentCatalogEntry(readCatalog(loc), built.definition.id, deps.enrich, deps.readSkillDefaults);
529
538
  const launchNote = view.catalogLaunchable
530
539
  ? "Catalog validation passed. Definition validity is not launchability."
531
540
  : "The file was saved and is not launchable.";
@@ -745,11 +754,21 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
745
754
  let viewportHeight = 30;
746
755
  await host.ui.custom<void>((tui, theme, _keys, done) =>
747
756
  createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id, deps.sessionSettings ? {
748
- get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich),
757
+ get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich, deps.readSkillDefaults),
749
758
  models: () => deps.editableModels?.() ?? [],
750
759
  scopedModels: () => host.scopedModels ?? [],
751
760
  settings: () => deps.sessionSettings!.snapshot(),
752
761
  change: (id, key, value) => deps.sessionSettings!.change(id, key, value),
762
+ changeSkills(entry, edit) {
763
+ const result = saveSkillExposure({ ...location(host, deps), entry }, edit);
764
+ if (result.ok && result.path) {
765
+ commandResult.wrote = true;
766
+ commandResult.path = result.path;
767
+ commandResult.scope = result.scope;
768
+ }
769
+ return { ok: result.ok, message: result.message };
770
+ },
771
+ discoverSkills: () => deps.discoveredSkills ?? [],
753
772
  save(id) {
754
773
  const loc = location(host, deps);
755
774
  const saved = saveAgentSessionDefaults(loadCatalog(loc), id, deps.sessionSettings!.snapshot(), loc);
@@ -800,7 +819,7 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
800
819
  });
801
820
  if (deps.sessionSettings) {
802
821
  const current = readCatalog(location(host, deps));
803
- const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich) : presentCatalog(current, deps.enrich);
822
+ const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich, deps.readSkillDefaults) : presentCatalog(current, deps.enrich, deps.readSkillDefaults);
804
823
  commandResult.data = refreshed;
805
824
  commandResult.message = refreshed.text;
806
825
  }
@@ -12,17 +12,17 @@ import { formatDiagnostic, shortRoleName, type Diagnostic } from "./catalog-sche
12
12
  import type { CatalogSnapshot } from "./catalog-store.ts";
13
13
  import { loadConfig, normalizeTools, SAFE_DEFAULT_TOOLS, type SubagentConfig } from "./config.ts";
14
14
  import { resolveExtensions } from "./extensions.ts";
15
+ import { configuredSkillExposure } from "./skills.ts";
15
16
  import type { PermissionProfile } from "./permission-policy.ts";
16
17
 
17
18
  export const LEGACY_CAPABILITY_CONTROLS = [
18
19
  "tool selection",
19
20
  "extension loading",
20
- "skills setup",
21
21
  "sandbox and workspace",
22
22
  "nested delegation",
23
23
  ] as const;
24
24
 
25
- export const CAPABILITY_NOTE = "Tool selection, extension loading, skills setup, sandbox and workspace, and nested delegation stay on the existing spawn path. The catalog grants no extra tools or permissions. A role name or instruction that says read-only is not enforcement.";
25
+ export const CAPABILITY_NOTE = "Tool selection, extension loading, sandbox and workspace, and nested delegation stay on the existing spawn path. Skill exposure is the one launch value a definition carries (`defaults.skills` / `overrides.skills`) because the launcher reproduces it exactly; like those controls it grants no extra tools or permissions, it only narrows which skills the child can see. A role name or instruction that says read-only is not enforcement.";
26
26
 
27
27
  /** Existing spawn defaults a catalog launch uses when the caller does not override them. Not grants. */
28
28
  export interface EffectiveLaunchCapabilities {
@@ -75,6 +75,16 @@ export type LaunchEnricher = (input: {
75
75
  snapshotDigest: string;
76
76
  }) => LaunchEnrichment | undefined;
77
77
 
78
+ /** The active default a launch would use when the definition chooses nothing. */
79
+ export interface SkillDefaultsSnapshot {
80
+ /** Explicit session discovery is `undefined`; none is `[]`. */
81
+ value?: readonly string[] | null;
82
+ source: "session" | "config" | "default";
83
+ error?: string;
84
+ }
85
+
86
+ export type ReadSkillDefaults = () => SkillDefaultsSnapshot;
87
+
78
88
  export interface OperationField {
79
89
  value: string | null;
80
90
  source: "agent-override" | "role-default" | "absent";
@@ -133,6 +143,22 @@ export interface OperationView {
133
143
  preferenceSources?: Partial<Record<"model" | "effort", { scope: "user" | "project"; path: string; bundled?: boolean }>>;
134
144
  instructions?: string;
135
145
  fields?: { model: OperationField; effort: OperationField; tier: OperationField };
146
+ /** Skill exposure the definition resolves to; absent is discovery. */
147
+ skills?: {
148
+ value: string[] | null;
149
+ source: OperationField["source"];
150
+ explicit: boolean;
151
+ inherited: boolean;
152
+ /** Global `defaultSkills`; null when the current config sets none. */
153
+ global: string[] | null;
154
+ /** What a launch with no `skills` option would use for this definition. */
155
+ effective: {
156
+ mode: "discovery" | "none" | "explicit" | "error";
157
+ paths: string[];
158
+ source: "agent-override" | "role-default" | "session" | "global" | "discovery";
159
+ error?: string;
160
+ };
161
+ };
136
162
  /** The definition's own default model and effort (role default, or the agent's override or inherited value). Null when neither is set. */
137
163
  defaults: DefinitionDefaults | null;
138
164
  requestedModel: string | null;
@@ -225,8 +251,12 @@ export function describeDefaultLaunchCapabilities(input: {
225
251
  };
226
252
  }
227
253
 
228
- export function presentCatalog(snapshot: CatalogSnapshot, enrich?: LaunchEnricher): OperationList {
229
- const entries = listCatalog(snapshot).map((entry) => presentCatalogEntry(snapshot, entry.id, enrich));
254
+ export function presentCatalog(
255
+ snapshot: CatalogSnapshot,
256
+ enrich?: LaunchEnricher,
257
+ readSkillDefaults?: ReadSkillDefaults,
258
+ ): OperationList {
259
+ const entries = listCatalog(snapshot).map((entry) => presentCatalogEntry(snapshot, entry.id, enrich, readSkillDefaults));
230
260
  const lines = [
231
261
  `Catalog revision ${snapshot.digest}.`,
232
262
  "Definition validity is not launchability. Model availability is decided only by the injected resolver.",
@@ -239,7 +269,12 @@ export function presentCatalog(snapshot: CatalogSnapshot, enrich?: LaunchEnriche
239
269
  return { revision: snapshot.digest, entries, diagnostics: [...snapshot.diagnostics], text: lines.join("\n") };
240
270
  }
241
271
 
242
- export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enrich?: LaunchEnricher): OperationView {
272
+ export function presentCatalogEntry(
273
+ snapshot: CatalogSnapshot,
274
+ id: string,
275
+ enrich?: LaunchEnricher,
276
+ readSkillDefaults?: ReadSkillDefaults,
277
+ ): OperationView {
243
278
  const inspection = inspectCatalog(snapshot, id);
244
279
  const entry = snapshot.roles.get(id) ?? snapshot.agents.get(id) ?? snapshot.blocked.find((item) => item.id === id);
245
280
  const definitionValid = Boolean(entry?.structurallyValid && entry.definition);
@@ -309,6 +344,9 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
309
344
  const metadata = entry?.definition && "metadata" in entry.definition ? entry.definition.metadata : undefined;
310
345
  const codex = metadata && typeof metadata === "object" ? (metadata as { codex?: { model?: unknown } }).codex : undefined;
311
346
  const codexProvenanceModel = typeof codex?.model === "string" ? codex.model : null;
347
+ const skillDefaults = readSkillDefaults?.() ?? configuredSkillDefaults();
348
+ const globalSkills = skillDefaults.value === undefined || skillDefaults.value === null
349
+ ? null : [...skillDefaults.value];
312
350
  const view: OperationView = {
313
351
  id,
314
352
  found: inspection.found,
@@ -340,6 +378,14 @@ export function presentCatalogEntry(snapshot: CatalogSnapshot, id: string, enric
340
378
  })),
341
379
  instructions: inspection.instructions,
342
380
  fields,
381
+ skills: inspection.skills ? {
382
+ value: inspection.skills.value ? [...inspection.skills.value] : null,
383
+ source: inspection.skills.source,
384
+ explicit: inspection.skills.explicit,
385
+ inherited: inspection.skills.source === "role-default",
386
+ global: globalSkills,
387
+ effective: effectiveSkillExposure(inspection.skills, skillDefaults),
388
+ } : undefined,
343
389
  defaults: definitionDefaults(fields),
344
390
  requestedModel: enrichment?.requestedModel ?? fields?.model.value ?? null,
345
391
  requestedEffort: enrichment?.requestedEffort ?? (fields?.effort.value ?? null),
@@ -412,6 +458,13 @@ export function renderOperationView(view: OperationView): string {
412
458
  lines.push(`${key}: value=${JSON.stringify(fieldValue.value)} source=${fieldValue.source} explicit=${yesNo(fieldValue.explicit)} inherited=${yesNo(fieldValue.inherited)}`);
413
459
  }
414
460
  }
461
+ lines.push(view.skills
462
+ ? `skills: value=${JSON.stringify(view.skills.value)} mode=${skillMode(view.skills.value)} source=${view.skills.source} explicit=${yesNo(view.skills.explicit)} inherited=${yesNo(view.skills.inherited)}`
463
+ : "skills: mode=discovery source=default");
464
+ if (view.skills) {
465
+ lines.push(`skills effective: mode=${view.skills.effective.mode} source=${view.skills.effective.source} paths=${JSON.stringify(view.skills.effective.paths)}${view.skills.effective.error ? ` error=${JSON.stringify(view.skills.effective.error)}` : ""}`);
466
+ lines.push(`skills default: ${view.skills.global === null ? "not set" : JSON.stringify(view.skills.global)}`);
467
+ }
415
468
  lines.push(`requested model: ${JSON.stringify(view.requestedModel)}`);
416
469
  lines.push(`actual model: ${JSON.stringify(view.actualModel)}`);
417
470
  lines.push(`requested effort: ${JSON.stringify(view.requestedEffort)}`);
@@ -457,6 +510,64 @@ function field(value: { value: string | null; source: OperationField["source"];
457
510
  };
458
511
  }
459
512
 
513
+ /** The child's observable skill modes: discovery, none, or exactly these paths. */
514
+ function skillMode(value: string[] | null): "discovery" | "none" | "explicit" {
515
+ if (value === null) return "discovery";
516
+ return value.length === 0 ? "none" : "explicit";
517
+ }
518
+
519
+ /** Saved global `defaultSkills`; a malformed or unreadable config stays visible as an error. */
520
+ function configuredSkillDefaults(): SkillDefaultsSnapshot {
521
+ try {
522
+ const exposure = configuredSkillExposure(loadConfig().defaultSkills);
523
+ return {
524
+ value: exposure.mode === "inherit" ? null : exposure.paths,
525
+ source: exposure.source,
526
+ };
527
+ } catch (error) {
528
+ return {
529
+ source: "config",
530
+ error: error instanceof Error ? error.message : String(error),
531
+ };
532
+ }
533
+ }
534
+
535
+ /** Where the active default resolves: session choice, saved global config, or discovery. */
536
+ function defaultSkillSource(defaults: SkillDefaultsSnapshot): NonNullable<OperationView["skills"]>["effective"]["source"] {
537
+ if (defaults.source === "session") return "session";
538
+ if (defaults.source === "config" && (defaults.error || (defaults.value !== undefined && defaults.value !== null))) return "global";
539
+ return "discovery";
540
+ }
541
+
542
+ /**
543
+ * The exposure a launch with no `skills` option would resolve for this
544
+ * definition. A definition's own list wins; otherwise an explicit null or an
545
+ * absent key falls to the active default and then discovery. A session choice
546
+ * that means discovery stays a session source, not a false discovery fallback.
547
+ */
548
+ function effectiveSkillExposure(
549
+ field: { value: readonly string[] | null; source: OperationField["source"] },
550
+ defaults: SkillDefaultsSnapshot,
551
+ ): NonNullable<OperationView["skills"]>["effective"] {
552
+ if (field.value !== null) {
553
+ const paths = [...field.value];
554
+ return {
555
+ mode: paths.length === 0 ? "none" : "explicit",
556
+ paths,
557
+ source: field.source === "agent-override" ? "agent-override" : "role-default",
558
+ };
559
+ }
560
+ const source = defaultSkillSource(defaults);
561
+ if (defaults.error) {
562
+ return { mode: "error", paths: [], source, error: defaults.error };
563
+ }
564
+ if (defaults.value === undefined || defaults.value === null) {
565
+ return { mode: "discovery", paths: [], source };
566
+ }
567
+ const paths = [...defaults.value];
568
+ return { mode: paths.length === 0 ? "none" : "explicit", paths, source };
569
+ }
570
+
460
571
  function yesNo(value: boolean): "yes" | "no" {
461
572
  return value ? "yes" : "no";
462
573
  }
@@ -3,7 +3,7 @@
3
3
  * Creation, import, and reload stay on `/agents`, where confirmation can be
4
4
  * collected. This module does not write files.
5
5
  */
6
- import { presentCatalog, presentCatalogEntry, type LaunchEnricher } from "./agent-inspection.ts";
6
+ import { presentCatalog, presentCatalogEntry, type LaunchEnricher, type ReadSkillDefaults } from "./agent-inspection.ts";
7
7
  import { canonicalCatalogId } from "./catalog-schema.ts";
8
8
  import { defaultUserRoot, loadCatalog } from "./catalog-store.ts";
9
9
  import { withAgentSessionSettings, type AgentSessionOverrides, type AgentSessionSettings } from "./agent-session-settings.ts";
@@ -28,6 +28,8 @@ export interface DiscoveryDeps {
28
28
  bundledRoot?: string;
29
29
  projectConfigDirName?: string;
30
30
  enrich?: LaunchEnricher;
31
+ /** Live session/config default skill choice; absent keeps the legacy config read. */
32
+ readSkillDefaults?: ReadSkillDefaults;
31
33
  sessionSettings?: AgentSessionSettings;
32
34
  resolveHost?: (ctx: { cwd: string; isProjectTrusted(): boolean }) => DiscoveryHost;
33
35
  }
@@ -72,14 +74,14 @@ export function agentsCatalogTool(Type: TypeModule, deps: DiscoveryDeps = {}) {
72
74
  const host = resolveHost(ctx, deps);
73
75
  const snapshot = withAgentSessionSettings(loadCatalog(host), host.sessionSettings ?? deps.sessionSettings?.snapshot());
74
76
  if (action === "list") {
75
- const listed = presentCatalog(snapshot, deps.enrich);
77
+ const listed = presentCatalog(snapshot, deps.enrich, deps.readSkillDefaults);
76
78
  return {
77
79
  content: [{ type: "text" as const, text: listed.text }],
78
80
  details: { action, wrote: false, revision: listed.revision, entries: listed.entries, diagnostics: listed.diagnostics },
79
81
  };
80
82
  }
81
83
  if (!params.id?.trim()) return toolError("inspect needs a role name or agent id. Call agents_catalog with action list to see them. Nothing was written.");
82
- const view = presentCatalogEntry(snapshot, canonicalCatalogId(params.id), deps.enrich);
84
+ const view = presentCatalogEntry(snapshot, canonicalCatalogId(params.id), deps.enrich, deps.readSkillDefaults);
83
85
  return {
84
86
  content: [{ type: "text" as const, text: view.text }],
85
87
  details: { action, wrote: false, view },
package/batch.mjs CHANGED
@@ -11,6 +11,7 @@ import { BUILTIN_TOOLS } from "./extensions.mjs";
11
11
  import { SAFE_CLEAN_TOOLS } from "./config.ts";
12
12
  import { assertThinkingLevel } from "./thinking.ts";
13
13
  import { assertTimingParams } from "./timing.ts";
14
+ import { normalizeSkillExposure } from "./skills.ts";
14
15
 
15
16
  const VALID_CAPACITY_MODES = new Set(["reject", "launch-available"]);
16
17
 
@@ -84,6 +85,8 @@ export function mergeJobOptions(shared, job) {
84
85
  thinking: job.thinking ?? shared?.thinking,
85
86
  tools: job.tools ?? shared?.tools,
86
87
  exclude_tools: job.exclude_tools ?? shared?.exclude_tools,
88
+ // `[]` is a real choice ("no skills"), so only a missing value inherits.
89
+ skills: job.skills ?? shared?.skills,
87
90
  clean: job.clean ?? shared?.clean,
88
91
  sandbox: job.sandbox ?? shared?.sandbox,
89
92
  sandbox_dir: job.sandbox_dir ?? shared?.sandbox_dir,
@@ -171,6 +174,9 @@ export function validateBatchPlan({ shared, jobs, onCapacity, config }) {
171
174
  const merged = mergeJobOptions(shared, job);
172
175
  assertThinkingLevel(merged.thinking, `job ${i + 1} thinking`);
173
176
  assertTimingParams(merged, `job ${i + 1} `);
177
+ // Validate every job's skill exposure before any job launches, so a bad
178
+ // path list cannot leave a half-launched batch behind.
179
+ normalizeSkillExposure(merged.skills, `job ${i + 1} (${merged.name ?? i + 1}) skills`);
174
180
  if (merged.clean === true) {
175
181
  // Validate the effective tool allowlist, which resolves in this order:
176
182
  // per-job tools → shared tools → config.defaultTools → clean-safe built-ins.
@@ -45,6 +45,11 @@ export interface EffectiveDefinition {
45
45
  model: FieldValue<string>;
46
46
  effort: FieldValue<ThinkingLevel>;
47
47
  tier: FieldValue<string>;
48
+ /**
49
+ * Skill exposure for a launch of this definition. Absent means the child
50
+ * discovers the user catalog; `[]` means no skills; paths mean exactly those.
51
+ */
52
+ skills: FieldValue<readonly string[]>;
48
53
  launchable: boolean;
49
54
  diagnostics: readonly Diagnostic[];
50
55
  source?: DefinitionOrigin;
@@ -101,6 +106,7 @@ export interface CatalogInspection {
101
106
  effort: FieldValue<ThinkingLevel>;
102
107
  tier: FieldValue<string>;
103
108
  };
109
+ skills?: FieldValue<readonly string[]>;
104
110
  validation: readonly Diagnostic[];
105
111
  launchable: boolean;
106
112
  restrictions: readonly ExecutionRestriction[];
@@ -203,6 +209,7 @@ export function inspectCatalog(snapshot: CatalogSnapshot, id: string): CatalogIn
203
209
  instructionMode: effective?.instructionMode,
204
210
  instructions: effective?.instructions,
205
211
  fields: effective ? { model: effective.model, effort: effective.effort, tier: effective.tier } : undefined,
212
+ skills: effective?.skills,
206
213
  validation: resolved.diagnostics,
207
214
  launchable: resolved.launchable,
208
215
  restrictions: effective?.restrictions ?? entry.definition?.executionRestrictions ?? [],
@@ -250,6 +257,7 @@ function resolveRole(snapshot: CatalogSnapshot, roleId: string): Resolution {
250
257
  model: fieldFromRole(preferences.model),
251
258
  effort: fieldFromRole(preferences.effort),
252
259
  tier: fieldFromRole(preferences.tier),
260
+ skills: fieldFromRole(preferences.skills),
253
261
  launchable,
254
262
  diagnostics,
255
263
  source: originOf(entry),
@@ -350,6 +358,7 @@ function baseEffective(
350
358
  model: inheritance ? inheritField(overrides, defaults, "model") : absentField(),
351
359
  effort: inheritance ? inheritField(overrides, defaults, "effort") : absentField(),
352
360
  tier: inheritance ? inheritField(overrides, defaults, "tier") : absentField(),
361
+ skills: inheritance ? inheritSkillPaths(overrides.skills, defaults.skills) : absentField(),
353
362
  launchable: inheritance?.launchable ?? false,
354
363
  diagnostics,
355
364
  source: originOf(entry),
@@ -392,6 +401,24 @@ function inheritField<K extends PreferenceKey>(
392
401
  return absentField();
393
402
  }
394
403
 
404
+ /**
405
+ * Skill exposure inherits exactly like a preference: an agent override wins —
406
+ * including an explicit null, which suppresses the role's list — and otherwise
407
+ * the role default applies. `[]` is a real value ("no skills"), not absence.
408
+ */
409
+ function inheritSkillPaths(
410
+ override: readonly string[] | null | undefined,
411
+ roleDefault: readonly string[] | null | undefined,
412
+ ): FieldValue<readonly string[]> {
413
+ if (override !== undefined) {
414
+ return { value: override === null ? null : [...override], source: "agent-override", explicit: true };
415
+ }
416
+ if (roleDefault !== undefined && roleDefault !== null) {
417
+ return { value: [...roleDefault], source: "role-default", explicit: false };
418
+ }
419
+ return absentField();
420
+ }
421
+
395
422
  function fieldFromRole<T>(value: T | null | undefined): FieldValue<T> {
396
423
  if (value === undefined || value === null) return absentField();
397
424
  return { value, source: "role-default", explicit: false };
@@ -448,6 +475,7 @@ function blockedEntry(snapshot: CatalogSnapshot, entry: CatalogEntry, diagnostic
448
475
  model: absentField(),
449
476
  effort: absentField(),
450
477
  tier: absentField(),
478
+ skills: absentField(),
451
479
  launchable: false,
452
480
  diagnostics: withSummary,
453
481
  source: originOf(entry),
@@ -85,6 +85,8 @@ export interface CatalogRunRecord {
85
85
  model: { value: string | null; source: string; explicit: boolean };
86
86
  effort: { value: string | null; source: string; explicit: boolean };
87
87
  tier: { value: string | null; source: string; explicit: boolean };
88
+ /** Absent exposure is discovery; [] is none; paths are exactly those skills. */
89
+ skills: { value: string[] | null; source: string; explicit: boolean };
88
90
  };
89
91
  modelSelection: ModelSelection;
90
92
  effortSelection: EffortSelection;
@@ -379,6 +381,7 @@ export async function prepareCatalogJob(snapshot: CatalogSnapshot, job: CatalogJ
379
381
  model: field(resolved.effective.model),
380
382
  effort: field(resolved.effective.effort),
381
383
  tier: field(resolved.effective.tier),
384
+ skills: skillField(resolved.effective.skills),
382
385
  },
383
386
  modelSelection: decision.modelSelection,
384
387
  effortSelection: decision.effortSelection,
@@ -654,6 +657,11 @@ function field(value: { value: string | null; source: string; explicit: boolean
654
657
  return { value: value.value, source: value.source, explicit: value.explicit };
655
658
  }
656
659
 
660
+ /** The catalog's skill exposure, frozen on the run record like model and effort. */
661
+ function skillField(value: EffectiveDefinition["skills"]): CatalogRunRecord["effective"]["skills"] {
662
+ return { value: value.value ? [...value.value] : null, source: value.source, explicit: value.explicit };
663
+ }
664
+
657
665
  function origin(value: EffectiveDefinition["source"]): CatalogRunRecord["source"] {
658
666
  if (!value) return undefined;
659
667
  return { scope: value.scope, path: value.path, contentDigest: value.contentDigest, id: value.id };