pi-better-subagents 0.27.2 → 0.28.1

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.
@@ -1,7 +1,8 @@
1
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
1
+ import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
2
  import { parse } from "shell-quote";
3
3
  import { STEER_FILE_ENV } from "./child-steer.ts";
4
4
  import { supportsPromptSections } from "./shared-execution-policy.ts";
5
+ import { restrictContextFilesToWorktree } from "./shared-worktree-context.ts";
5
6
 
6
7
  export const WORKER_HANDOFF = "Worker ownership: complete your assigned implementation or diagnosis, run focused checks, push only when authorized, write the requested result, then return. Pending CI is a handoff, not a failed implementation or a CI pass. The coordinator owns CI/PR monitoring, review scheduling, readiness, enqueueing and merge. Do not start external delivery watchers or background monitoring. Short status reads and failed-log retrieval for diagnosis are allowed. Legitimate local tests and builds may run to completion within their command limits. Use Bash for short diagnostic commands and focused checks needed to implement the change. When supervised background tools are available, retain ownership of assigned validation: launch a known long command with bg_task_spawn or repeated observation with bg_task_watch, continue independent work, then call wait_for_operations to park when no independent work remains. On continuation, inspect the operation's terminal evidence and acknowledge its interpretation before continuing the assignment. Parking is a saved-conversation dependency, not a request for the parent model to relay commands or results. An explicit restricted tool loadout may omit background support; return the exact command, cwd, required environment variable names (never secret values), current evidence and remaining validation to the coordinator. Do not emulate background execution with polling, sleep loops, nohup or shell detachment. Established command-only operations and external delivery monitoring belong to the coordinator's background tools.";
7
8
  export const WORKER_HANDOFF_SECTION = "worker_handoff";
@@ -133,6 +134,11 @@ export function workerMonitoringRefusal(toolName: string, input: unknown): strin
133
134
  }
134
135
 
135
136
  export default function childOwnership(pi: Pick<ExtensionAPI, "on">, env: NodeJS.ProcessEnv = process.env): void {
137
+ // The child keeps the parent's cwd, so a linked worktree is its project root:
138
+ // send that worktree's context file, not the main checkout's ancestor files.
139
+ pi.on("before_agent_start", (event) => {
140
+ restrictContextFilesToWorktree(event.systemPromptOptions, getAgentDir());
141
+ });
136
142
  // This marker is supplied by the parent on every child launch, including clean/unsandboxed runs.
137
143
  if (!env[STEER_FILE_ENV]) return;
138
144
  // A section on hosts that render them; appended text on hosts that do not.
package/config.ts CHANGED
@@ -6,15 +6,17 @@
6
6
  *
7
7
  * `defaultModel: null` / absent → inherit the foreground model.
8
8
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
9
+ * `defaultSkills` absent → the child discovers the user-level skills catalog.
9
10
  */
10
11
 
11
12
  import { existsSync, readFileSync, statSync } from "node:fs";
12
13
  import { fileURLToPath } from "node:url";
13
- import { dirname, join } from "node:path";
14
+ import { dirname, isAbsolute, join } from "node:path";
14
15
  import { homedir } from "node:os";
15
16
  import { SELF_SPEC } from "./extensions.ts";
16
17
  import { installedPackage } from "./child-dependencies.mjs";
17
18
  import { isDelegationMode, type DelegationMode } from "./delegation.ts";
19
+ import { normalizeSkillExposure } from "./skills.ts";
18
20
  import type { TimingSettings } from "./timing.ts";
19
21
  import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
20
22
 
@@ -23,6 +25,12 @@ export interface SubagentConfig extends TimingSettings {
23
25
  delegationMode?: DelegationMode | null;
24
26
  defaultModel?: string | null;
25
27
  defaultTools?: string | null;
28
+ /**
29
+ * Skill exposure when neither the launch nor a catalog role/agent chooses
30
+ * one: absent/null keeps discovery, `[]` loads no skills, and absolute
31
+ * paths load exactly those skills. See `skills.ts`.
32
+ */
33
+ defaultSkills?: string[] | null;
26
34
  /** Default concurrency cap; /subagents cap overrides it for the current session. */
27
35
  maxConcurrent?: number | null;
28
36
  /**
@@ -183,10 +191,34 @@ export function writeDelegationMode(mode: DelegationMode, path = configPath()):
183
191
  }
184
192
 
185
193
  /** Save human-facing defaults together, preserving unrelated configuration. */
186
- export function writeSubagentSettings(settings: { delegationMode: DelegationMode; maxConcurrent: number }, path = configPath()): void {
194
+ export function writeSubagentSettings(
195
+ settings: {
196
+ delegationMode: DelegationMode;
197
+ maxConcurrent: number;
198
+ /** Omit to preserve the saved value; `null` explicitly records discovery. */
199
+ defaultSkills?: string[] | null;
200
+ },
201
+ path = configPath(),
202
+ ): void {
187
203
  if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
188
204
  if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
189
- writeConfigSettings(settings, path);
205
+ const next: { delegationMode: DelegationMode; maxConcurrent: number; defaultSkills?: string[] | null } = {
206
+ delegationMode: settings.delegationMode,
207
+ maxConcurrent: settings.maxConcurrent,
208
+ };
209
+ if (Object.hasOwn(settings, "defaultSkills")) {
210
+ if (settings.defaultSkills === null) {
211
+ next.defaultSkills = null;
212
+ } else {
213
+ const skills = normalizeSkillExposure(settings.defaultSkills, "defaultSkills");
214
+ if (skills === undefined) throw new Error("defaultSkills must be an array of paths or null for discovery.");
215
+ if (skills.some((entry) => !isAbsolute(entry))) {
216
+ throw new Error("defaultSkills paths must be absolute so every child resolves the same files.");
217
+ }
218
+ next.defaultSkills = skills;
219
+ }
220
+ }
221
+ writeConfigSettings(next, path);
190
222
  }
191
223
 
192
224
  function writeConfigSettings(settings: Partial<SubagentConfig>, path: string): void {
package/continuation.ts CHANGED
@@ -210,6 +210,9 @@ export function buildLaunchRecipe(input: Omit<LaunchRecipe, "version">): LaunchR
210
210
  const recipe: LaunchRecipe = { version: 1, ...input };
211
211
  if (input.excludeTools === "") delete recipe.excludeTools;
212
212
  if (input.sandboxDir === "") delete recipe.sandboxDir;
213
+ // Absent means discovery. Never write an explicit undefined key, so a recipe
214
+ // that inherited skills reads back exactly like one written before #664.
215
+ if (input.skills === undefined) delete recipe.skills;
213
216
  return recipe;
214
217
  }
215
218
 
@@ -6,11 +6,11 @@ Commands, the read-only discovery tool, and the Codex importer for `pi-agent/v1`
6
6
 
7
7
  `/agents` is one Pi command. Dialogs use `ctx.ui.select`, `confirm`, `input`, and `editor`. `ctx.hasUI` is false in print and JSON mode. When a choice or confirmation is required there, the command returns `clarification-needed` and writes nothing.
8
8
 
9
- In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view opens **Settings**, with Model, Effort, launch resolution, and diagnostics. **Instructions** contains the complete effective prompt (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. **Files** shows definition and saved-config sources plus current session edits. Tab and Shift+Tab cycle between these pages; `p` opens Instructions. Up/Down selects settings or scrolls the current page. Left or Escape returns to Settings, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result; bare `/agents` still returns help outside the custom TUI.
9
+ In an interactive TUI, `/agents`, `/agents list`, and `/agents show` open a focused catalog view instead of leaving the listing in a persistent widget. Rows align name, effective model, source, and launch state; narrow terminals retain name and model. The model is the resolved actual model when available, otherwise the requested or inherited preference, or `not resolved`. Type to filter by id, name, description, or base role; use Up/Down and Enter to inspect. The detail view opens **Settings**, with Model, Effort, Skills, launch resolution, and diagnostics. **Instructions** contains the complete effective prompt (role plus agent in add mode, agent text in replace mode); this is not the task-specific launch prompt. **Files** shows definition and saved-config sources plus current session edits. Tab and Shift+Tab cycle between these pages; `p` opens Instructions. Up/Down selects settings or scrolls the current page. Left or Escape returns to Settings, then list, clears the filter, then closes. `/agents show <id>` opens that definition directly. Print/JSON callers still receive the complete text and structured result; bare `/agents` still returns help outside the custom TUI.
10
10
 
11
11
  ### Model and effort edits
12
12
 
13
- When lifecycle supplies `sessionSettings`, press `e` in detail to edit Model or Effort. Up/Down selects the setting and Enter opens its choices. Model choices follow the session's model scope (`ctx.scopedModels`, the same resolved set `/scoped-models` shows), with a header row naming the source, and type filters the names. A saved value outside the scope stays on the definition and in the detail view but is not offered by the picker; the header says so instead. An empty scope means no restriction in Pi, so the picker falls back to the foreground registry's available models, keeping a current preference that is no longer available labelled `saved`. Effort choices use the existing catalog effort levels. Escape cancels an unselected choice. Only these two fields are editable; instructions, base role, tier, and execution controls are unchanged.
13
+ When lifecycle supplies `sessionSettings`, press `e` in detail to edit Model or Effort. Up/Down selects the setting and Enter opens its choices. Model choices follow the session's model scope (`ctx.scopedModels`, the same resolved set `/scoped-models` shows), with a header row naming the source, and type filters the names. A saved value outside the scope stays on the definition and in the detail view but is not offered by the picker; the header says so instead. An empty scope means no restriction in Pi, so the picker falls back to the foreground registry's available models, keeping a current preference that is no longer available labelled `saved`. Effort choices use the existing catalog effort levels. Escape cancels an unselected choice. Only Model, Effort, and Skills are editable; instructions, base role, tier, and execution controls are unchanged. Skills are documented below because they save to the definition rather than to the session.
14
14
 
15
15
  The scope affects only the picker. Launch and runtime model resolution keep reading the catalog/session preference as before, and the package imposes no global model restriction.
16
16
 
@@ -31,12 +31,55 @@ The dedicated config has this shape:
31
31
 
32
32
  Saved fields override definition defaults one field at a time; branch edits override saved fields. A record with `bundled: true` takes model/effort defaults from the current bundled definition before applying any explicit fields in that record. Trusted project config wins over user config. User config does not override a project-owned Markdown definition. The detail view labels saved fields as `user config` or `project config`.
33
33
 
34
+ ### Skill exposure edits
35
+
36
+ The **Skills** row shows the effective mode and where it comes from: `override`
37
+ (the named agent's own `overrides.skills`), `role default` / `inherited`
38
+ (the base role's `defaults.skills`), `global` (the subagent config's
39
+ `defaultSkills`), or `discovery`. An explicit `skills: null` on an agent is shown
40
+ as `inherit (role list suppressed)` and the origin names the fall-through, for
41
+ example `override → global`.
42
+
43
+ Enter on Skills offers three choices:
44
+
45
+ - **Inherit** deletes the definition's own key. A named agent then uses its base
46
+ role's list; a role falls through to the global default and then discovery.
47
+ Removing an override therefore restores inheritance instead of storing a null.
48
+ - **No skill catalog** writes `skills: []`, which becomes `--no-skills`.
49
+ - **Selected skills…** opens the shared searchable checkbox picker with skill
50
+ names and descriptions. Space toggles a skill, Enter applies, and Escape
51
+ cancels. Filtering preserves checked items. Saved paths missing from discovery
52
+ remain available as unavailable rows. Add skill path accepts an absolute
53
+ `SKILL.md` or skill-directory path, including commas and spaces. Failed saves
54
+ keep the draft for retry. Applying zero checked explicitly selects No skill
55
+ catalog (`[]`); it never means discovery. Definitions require absolute paths
56
+ because a catalog file has no workspace of its own.
57
+
58
+ Unlike model and effort, the skill value is not a `settings.json` preference: it
59
+ is a launch value the definition carries. Selecting a choice rewrites that
60
+ definition through the catalog's existing save path, keeping the prompt,
61
+ description, restrictions, and sibling preferences unchanged. A personal or
62
+ trusted project definition is updated in place. A bundled definition is
63
+ immutable, so the same save creates or updates a personal whole-definition
64
+ override with the bundled content unchanged except for `skills`; the message
65
+ says `Personal definition saved` and names the path. The **Instructions** tab's
66
+ Reset to bundled archives that personal definition. The **Settings** reset only
67
+ follows bundled model and effort, so it does not remove a skill value stored in a
68
+ personal definition.
69
+
70
+ Inspection and the launch path share the resolution: an inherited role list, an
71
+ agent override including `[]`, the global `defaultSkills` value, and discovery
72
+ stay distinct. Launch-level `skills` still wins over all of them. `/subagents`
73
+ owns the global default and any current-session choice above this row; the
74
+ catalog view reports the definition layer and that saved default, not the other
75
+ surface's session choice.
76
+
34
77
  Both Settings and Instructions offer **Reset to bundled**, with independent effects:
35
78
 
36
79
  - **Settings:** follows the current bundled model and effort, clears that id's current-session choices, and leaves its Markdown prompt unchanged. A user definition records `{ "bundled": true }` instead of copied default values; the UI shows `bundled`, and later bundle updates apply automatically. An explicit model/effort choice can override one field while the other keeps following the bundle. Project-owned definitions and active project config are excluded.
37
80
  - **Instructions:** archives a user Markdown override in a hidden `.backup` file beside the original and reveals the bundled role prompt. Its model/effort choices move to the config where needed, and session choices remain unchanged. An already-bundled prompt needs no change. Project definitions are excluded.
38
81
 
39
- Click the action once, or select it in Settings and press Enter. In Instructions, Enter activates the reset when scrolled to the top. The action requires a valid bundled fallback and refuses stale selections, duplicates, and symlink redirects. Other definitions stay unchanged. Saving remains **Ctrl+S** only; there is no Save button or selectable save row. Existing overrides remain intact until explicitly reset.
82
+ Click the action once, or select it in Settings and press Enter. In Instructions, Enter activates the reset when scrolled to the top. The action requires a valid bundled fallback and refuses stale selections, duplicates, and symlink redirects. Other definitions stay unchanged. Saving model and effort remains **Ctrl+S** only; there is no Save button or selectable save row. Skill choices save when selected and have no save row of their own. Existing overrides remain intact until explicitly reset.
40
83
 
41
84
  New launches and `agents_catalog` discovery use the same session overlay. Explicit per-run model/effort choices still win, a batch retains one immutable snapshot, and active/completed runs do not change. Role effort remains an inherited default with the existing nearest-supported adjustment; named-agent effort remains explicit and blocks when unsupported. The lifecycle wiring required to enable this surface is in [agent-catalog-lifecycle.md](./agent-catalog-lifecycle.md#session-settings-integration).
42
85
 
@@ -58,7 +101,7 @@ Create and import ask for a missing role, name, or path only when `hasUI` is tru
58
101
 
59
102
  `launchable` stays `unknown` until lifecycle injects a `LaunchEnricher` from the model resolver. That enricher supplies availability, requested and actual model, requested and actual effort, and its launch decision. If the catalog already blocks the id, enrichment cannot flip it to launchable. This module does not call the model registry and does not implement fallback.
60
103
 
61
- Effective capabilities stay the existing spawn controls: tool selection, extension loading, skills setup, sandbox and workspace, and nested delegation. `grantedByCatalog` is false. No tool preset or permission is added. A prompt that says read-only is not enforcement.
104
+ Effective capabilities stay the existing spawn controls: tool selection, extension loading, sandbox and workspace, and nested delegation. `grantedByCatalog` is false. No tool preset or permission is added. Skill exposure is the exception the launcher reproduces from a definition (`skills`, shown as `skills: value=… mode=…`), and it only narrows which skills the child can see. A prompt that says read-only is not enforcement.
62
105
 
63
106
  ## Codex import
64
107
 
@@ -63,9 +63,18 @@ People type and read a role by its short name: `developer` is `role.developer`.
63
63
  | `model` | `provider/model`. No `@effort` suffix. |
64
64
  | `effort` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |
65
65
  | `tier` | Catalog-policy label (`balanced`, `efficient`, `frontier`, or another short label). Not a benchmark claim. |
66
+ | `skills` | Skill exposure for a launch: a list of absolute `SKILL.md` or skill-directory paths, or `[]` for no skills. Absent keeps user-catalog discovery. |
66
67
 
67
68
  A missing key inherits. A present key, including `null`, is an explicit value and does not inherit. Removing an override means deleting the key. Writers must not copy effective inherited values back into `overrides`. Agents must not store a `defaults` object; that mapping is kept only so it is not discarded, and it is not promoted into overrides.
68
69
 
70
+ Model, effort, and tier choose which model runs. `skills` is the one launch value
71
+ here that changes what the child can see: `[]` becomes `--no-skills`, and paths
72
+ become `--no-skills --skill <path>…`. It is reproduced exactly like model and
73
+ effort, and it grants nothing — a list narrows prompt exposure and cannot add a
74
+ tool, an extension, or a permission. See
75
+ [skill exposure](usage.md#skill-exposure) for the launch-level precedence, which
76
+ puts an explicit `skills` option above the catalog.
77
+
69
78
  These preferences do not grant tools, sandbox behavior, extension loading, or nested delegation. Launch keeps the existing subagent controls. A role name or a prompt that says "read-only" is not enforcement.
70
79
 
71
80
  Host execution keys (`sandbox`, `sandbox_mode`, `tools`, `permissions`, `mcp`, `mcpServers`, `extensions`, `network`, `filesystem`, and the other names in `HOST_EXECUTION_CONTROL_KEYS`) are preserved. A required restriction blocks launch until it is removed. `honored: true` in the file is not proof that Pi enforced it. Optional restrictions (`required: false`) are warnings. Cosmetic `metadata` and unknown non-execution fields are preserved and do not block launch.
@@ -82,6 +91,8 @@ Markdown definition precedence is project, then personal, then bundled. The high
82
91
 
83
92
  Model and effort choices saved through `/agents` live separately in the catalog's `settings.json` (`version: 1`, with a `defaults` map keyed by role/agent id). They override only those fields, without shadowing the Markdown prompt. Branch edits win over saved preferences; trusted project preferences win over user preferences. User preferences do not override project-owned definitions. Existing Markdown overrides stay whole definitions until explicitly archived through **Reset to bundled** in Instructions. See [catalog operations](agent-catalog-operations.md#model-and-effort-edits).
84
93
 
94
+ Skill exposure is a definition value, not a `settings.json` preference. `/agents` edits `defaults.skills` or `overrides.skills` through the normal definition save path: user and trusted project definitions are updated in place, and editing a bundled definition writes a personal whole-definition override with the bundled prompt unchanged. See [skill exposure edits](agent-catalog-operations.md#skill-exposure-edits).
95
+
85
96
  | Scope | Path |
86
97
  | --- | --- |
87
98
  | Project | `<cwd>/<CONFIG_DIR_NAME>/agents/roles/*.md` and `.../agents/agents/*.md`. `CONFIG_DIR_NAME` defaults to `.pi`. Pass Pi's export from the host. |
@@ -149,7 +160,7 @@ DEV-39 owns Agentier adaptation, migration, remote model policy, credentials, an
149
160
  | `id` | Stable identity, distinct from `name`, filename, and run id. |
150
161
  | `roleId` | Exactly one live base role. Membership lists are not parents. |
151
162
  | `instructions.mode` + body | `add` appends; `replace` swaps instruction text only. |
152
- | Missing override vs `overrides.<field>` | Absence inherits the current role. Presence, including null, is explicit. Deleting the key removes the override. |
163
+ | Missing override vs `overrides.<field>` | Absence inherits the current role. Presence, including null, is explicit. Deleting the key removes the override. An explicit `skills: null` on an agent suppresses the role's skill list, so the launch falls back to the config default and then discovery. |
153
164
  | Role `defaults` | Live source for the next resolution. Not copied onto the agent at save time. |
154
165
  | `provenance` | Import origin of an independent copy. Not a subscription to the external file. |
155
166
  | `executionRestrictions` | Required restrictions stay visible and blocking until a real host control exists. |
package/docs/usage.md CHANGED
@@ -18,14 +18,24 @@ Set `delegationMode` in the user config described under
18
18
  [Tool scoping](#tool-scoping-allowlist) to `manual`, `adaptive`, or
19
19
  `coordinator` (default `adaptive`). This controls foreground delegation guidance,
20
20
  not child permissions or catalog definitions. `/subagents settings` (or simply
21
- `/subagents`) opens the terminal settings page with mode and concurrent-subagent
22
- cap controls, an Agents shortcut to `/agents`, and Reset to defaults.
23
- The page uses the same selected-row and
24
- active-cell styling as `/sandbox`, with one editable value column.
21
+ `/subagents`) opens the terminal settings page with mode, concurrent-subagent
22
+ cap, and default skill-exposure controls, an Agents shortcut to `/agents`, and
23
+ Reset to defaults. The page uses the same selected-row and active-cell styling
24
+ as `/sandbox`, with one editable value column. Skill exposure cycles between
25
+ Discover automatically and No skill catalog. The Selected skills row opens the
26
+ shared searchable checkbox picker, which lists loaded skills by name and
27
+ description, uses Space to toggle, Enter to apply, and Esc to cancel. Typing
28
+ filters the list without losing checked items. A saved path missing from current
29
+ discovery stays visible as unavailable and survives apply. Zero checked applies
30
+ No skill catalog, never discovery and never an invalid empty Selected skills
31
+ draft. Manual Add skill path remains available inside the picker; a path must be
32
+ absolute and exist. Invalid input stays in the editor with an explanation rather
33
+ than being dropped.
25
34
  Edits automatically persist for this session, including across reloads; Escape
26
35
  closes the page without undoing them.
27
36
  Enter edits the cap as a positive whole number; Escape cancels an unfinished edit.
28
- Ctrl+S saves both settings as defaults. Sandbox permissions remain in `/sandbox`.
37
+ Ctrl+S saves mode, cap, and skill exposure as defaults. Reset to defaults restores
38
+ all three from the saved config. Sandbox permissions remain in `/sandbox`.
29
39
 
30
40
  Command equivalents also work outside the terminal UI:
31
41
 
@@ -41,7 +51,7 @@ below the running count leaves existing work untouched and blocks new admissions
41
51
  until capacity becomes available. Slots already reserved by an in-flight launch
42
52
  remain admitted. Settings apply to this parent Pi process, not
43
53
  all Pi sessions on the machine. Saving preserves unrelated config keys and
44
- clears both session overrides. The command form asks for confirmation when a UI
54
+ clears the mode, cap, and skill session overrides. The command form asks for confirmation when a UI
45
55
  is available. Reset restores saved defaults without changing config.
46
56
 
47
57
  `/reload` retains session overrides; new sessions use config, while resuming or
@@ -96,7 +106,7 @@ thresholds continue to take precedence for subagent health.
96
106
 
97
107
  | Tool | Blocks? | What it does |
98
108
  |------|---------|--------------|
99
- | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
109
+ | `subagent_spawn` | never | Launch a task in a background subagent; returns a run id at once. Params: `prompt`, `name`, `model`, `tools` (allowlist), `exclude_tools`, `skills` ([skill exposure](#skill-exposure)), `sandbox`, `sandbox_dir`, `callback`, `clean`, `cwd`, `git_clone_workspace`, `approve`, `allow_nested`, optional `session_id` or `session_name` (continue a saved conversation), and the [timing](#run-timing-deadline-ceiling-stuck) overrides `deadline_minutes`, `grace_minutes`, `max_minutes`, `stuck_minutes`. |
100
110
  | `subagent_spawn_batch` | never | Launch several independent subagents at once. Each job becomes a normal run. Params: `batchName`, `shared` (options applied to every job), `jobs[]` (each needs `prompt`; optional per-job `session_id` or `session_name` continues a saved conversation), `onCapacity` (`reject` or `launch-available`). |
101
111
  | `subagent_settings` | never | Read-only effective settings and capacity snapshot. No parameters. Returns `delegationMode`, `maxConcurrent`, per-setting `sources` (`session` or `config`), a stable settings `revision`, `runningCount`, `pendingCount`, `occupiedSlots`, and `availableSlots`. The limit is a ceiling, not a target; spawn admission rechecks live capacity. |
102
112
  | `subagent_list` | never | Compact list for the current folder and descendants across foreground sessions (default 10 rows / 1 KiB page). Each row includes `session_id`. Params: `all` (machine-global search), `limit` (default 10, max 100), `cursor`, `max_bytes` (max 4 KiB), `status` (`running`, `completed`, `failed`, `killed`, `exited`, durable `orphaned`, `lost`). Incident counts are compact; no spend/tool histories. Abandoned launch records are reported separately and are never counted as runs. |
@@ -134,7 +144,12 @@ A launch without a session selector starts a new conversation. With a selector,
134
144
  `prompt` is the next user turn; the original task and role are already saved.
135
145
  Each attempt gets a new run id, log, timing record, and capacity slot while the
136
146
  native session id and history stay the same. The launch recipe preserves the
137
- worker's role, tools, model, and workspace, including uncommitted changes.
147
+ worker's role, tools, skill exposure, model, and workspace, including uncommitted
148
+ changes. Repeating a launch-only option is accepted only with the saved value;
149
+ a different `skills` list is refused rather than silently dropped. A continuation
150
+ whose frozen tool loadout can no longer be admitted (for example its trusted
151
+ package is gone) is refused before anything is spawned, instead of reopening the
152
+ saved conversation with different tools.
138
153
 
139
154
  A run stopped with `subagent_stop` (status `killed`) can be continued the same
140
155
  way. Stopping ends that execution, not the saved conversation or its
@@ -510,11 +525,15 @@ chosen in `/sandbox` → Subagents · Tools
510
525
  name is refused. A single extension file with no package manifest is loaded
511
526
  and admitted by itself, never its directory. Known network tool names
512
527
  (`web_fetch`, `web_search`, `firecrawl_scrape`, `firecrawl_extract`, `mcp`, `mcpScript`, `remote_bash`, and any `mcp__*` name) are refused while Network access is Off; this is a name list, not a
513
- network sandbox. A ticked tool whose package can't be found is refused at launch. Ticked tools
514
- join the default tool list; an explicit `tools` list still decides.
515
-
516
- Other tools are disabled in confined children and listed in launch output with
517
- the reason. The launch line shows what was admitted, for example
528
+ network sandbox. A ticked tool whose package can't be found is left out of a
529
+ default loadout and reported with its reason in the launch output; an explicit
530
+ `tools` request for a tool the task boundary cannot provide refuses the launch.
531
+ Ticked tools join the default tool list; an explicit `tools` list still decides.
532
+
533
+ Other tools are disabled in confined children. One that only joined the default
534
+ loadout is omitted from the child and listed in launch output with the reason;
535
+ one the caller named in `tools` refuses the launch with the reason. The launch
536
+ line shows what was admitted, for example
518
537
  `Runtime: isolated · guarded apply_patch · trusted web_fetch (@juicesharp/rpiv-web-tools)`.
519
538
  Provider extensions are trusted runtime code; arbitrary extension tools are not
520
539
  admitted merely because their names were requested. Confined children disable project
@@ -578,6 +597,62 @@ The mandatory task guard is independent of optional guardrails extensions.
578
597
  Adding a package to the tool map does not make its tools safe to execute outside
579
598
  the task boundary.
580
599
 
600
+ ## Skill exposure
601
+
602
+ A child otherwise inherits the whole user-level skills catalog, which dominates
603
+ its system prompt even when the task already names the one `SKILL.md` it needs.
604
+ `skills` bounds that exposure:
605
+
606
+ | `skills` | Child argv | Effect |
607
+ | --- | --- | --- |
608
+ | omitted | (no flag) | discover the user catalog |
609
+ | `[]` | `--no-skills` | no skills at all |
610
+ | `["/abs/SKILL.md", …]` | `--no-skills --skill <path>…` | exactly those skills |
611
+
612
+ Precedence, highest first: the launch option (or the batch job's value, then
613
+ `shared`), a catalog role/agent's `defaults.skills` / `overrides.skills`
614
+ ([catalog](agent-catalog.md#portable-preferences-vs-host-controls)), the current
615
+ session's `/subagents settings` choice, saved `defaultSkills`, then discovery.
616
+ Each level distinguishes "not set" from `[]`, so `[]` disables discovery rather
617
+ than falling through to a wider default. The session choice applies to the next
618
+ launch even before Ctrl+S.
619
+
620
+ `/agents` edits the catalog's own value: the Skills row shows the effective mode
621
+ and whether it comes from the agent override, the base role, the session or
622
+ global default, or discovery, and offers Inherit, No skill catalog, or Selected
623
+ skills. `/subagents` edits the session choice first, then saves it as the global
624
+ `defaultSkills`. Both Selected skills screens use the same checkbox picker. Its
625
+ available entries come from the skills Pi already loaded for the current session
626
+ through `ctx.getSystemPromptOptions().skills`; saved paths that are not in that
627
+ list stay visible as unavailable. If the host reports no loaded skills, the
628
+ picker says so and manual Add skill path remains available. See
629
+ [catalog operations](agent-catalog-operations.md#skill-exposure-edits).
630
+
631
+ Relative paths resolve against the child's workspace. The effective choice is
632
+ frozen in the launch recipe and printed at launch as
633
+ `Skills: none (--no-skills) · source launch`, so a continuation reproduces it.
634
+ A recipe written before this option existed has no `skills` key and keeps
635
+ discovery. There is no `exclude_skills`: Pi cannot drop single entries from a
636
+ discovered catalog without also taking over discovery.
637
+
638
+ Discovery and an empty list are different choices. A continuation may repeat
639
+ only the frozen choice: `skills: []` is refused for a conversation launched with
640
+ discovery, including a recipe written before this option. A conversation that
641
+ froze `[]` accepts an identical `[]` and refuses paths.
642
+
643
+ ### Project context in a linked worktree
644
+
645
+ A child keeps its parent's working directory. When that directory is inside a
646
+ linked Git worktree, the worktree is the project context root: the child receives
647
+ the global `AGENTS.md` from the agent directory and the context files at or below
648
+ the worktree root, not the main checkout's file or any ancestor above it. Ordinary
649
+ repositories keep every ancestor context file. The parent session applies the same
650
+ boundary, so a standalone Subagents install behaves like the bundled one.
651
+
652
+ The boundary follows where Pi selected a file, not what a filename symlink points
653
+ at. It needs a Pi host that rebuilds the prompt from `systemPromptOptions` after
654
+ the `before_agent_start` hook (Pi 1.x); an older host keeps the prompt it loaded.
655
+
581
656
  ## Tool scoping (allowlist)
582
657
 
583
658
  Precedence, highest first: the per-call `tools` param → `config.json`
@@ -606,6 +681,11 @@ The effective config also sets:
606
681
 
607
682
  - `defaultModel` — model for spawns that don't specify one (`null` = inherit the
608
683
  foreground model).
684
+ - `defaultSkills` — skill exposure when neither the launch nor a catalog role or
685
+ agent chooses one. Omit it (or set `null`) for discovery, `[]` for no skills,
686
+ or absolute paths for exactly those skills. `/subagents settings` writes
687
+ `null` when Discover automatically is saved, so it overrides an older path
688
+ list. See [skill exposure](#skill-exposure).
609
689
  - `delegationMode` — foreground policy (`manual`, `adaptive`, or `coordinator`;
610
690
  default `adaptive`). `/subagents mode ...` changes only the current session.
611
691
  `/subagents save` saves mode and cap together as config defaults.