1 +#
ultra Sub-agent Extension Loading — Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Let ultra sub-agents reach extension-provided tools (e.g. `web_search`) via a single `ultra.subagentExtensions` setting, keeping the tool allowlist as the only gate and making `workflow` recursion impossible.
7 +**Architecture:** Flip only `noExtensions` on the sub-agent resource loader (other isolation flags stay on, so no skill/prompt/theme/context bloat). The existing `[...step.tools, structured_output]` allowlist stays authoritative over which tools are active; `workflow` is defensively stripped from every sub-agent allowlist. A new `none|all` setting (default `all`) drives the flip. The web `research` workflow that consumes this is **deferred** (spec Part B) and out of scope here.
9 +**Tech Stack:** TypeScript, Pi coding-agent SDK (`@earendil-works/pi-coding-agent`), TypeBox, vitest, biome, dprint, markdownlint.
11 +##
Global Constraints 13 +- **Default `subagentExtensions` is `"all"`**; `"none"` is the opt-out. The setting union is exactly `"none" | "all"`.
14 +- **Only `noExtensions` flips.** `noSkills`, `noPromptTemplates`, `noThemes`, `noContextFiles` stay `true` in both modes.
15 +- **The tool allowlist is the gate.** `workflow` (ultra's own model-tool) is stripped from every sub-agent allowlist so a loaded ultra can't be re-entered.
16 +- **Factory-level default is isolation:** when `makeSessionFactory` gets no `loadExtensions` dep, it behaves as today (`noExtensions: true`). The product default (`"all"`) is applied at `index.ts`. These are intentionally different layers.
17 +- **Commits are gated on the user.** The user's standing instruction is "commit only when asked." Each "Commit" step means _stage the change and surface the proposed commit_; only run `git commit` when the user approves. Commit message trailer (verbatim): `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`. Current branch is `trunk` (default) — branch first before any real commit.
18 +- **Verify green with** `mise run ci` (lint + test + check). No `build` task. Biome binary: `/home/me/.local/share/mise/installs/biome/2.4.15/biome`.
19 +- **No fs writes from extension _runtime_ code** (it crashes pi). Test-file writes are fine.
20 +- If `.claude/settings.local.json` exists, move it to scratchpad before the final `mise run ci` (biome has no vcs block locally and false-positives on that gitignored file), then restore.
24 +###
Task 1: Spike — confirm the allowlist gates extension tools and auth carries (GATE) 26 +This is an **investigative gate**, not a TDD task. It uses a throwaway one-line hack to prove the mechanism before any real code. If it fails, stop and revisit the spec.
30 +- Temporarily modify: `extensions/ultra/drivers.ts:62` (revert at the end)
31 +- Scratch: `<scratchpad>/spike-web.json`
33 +- [ ] **Step 1: Temporarily force extensions on**
35 +In `extensions/ultra/drivers.ts`, change line 62 from `noExtensions: true,` to `noExtensions: false,`. (Leave the other `no*` flags `true`.) This is a throwaway hack reverted in Step 5.
37 +- [ ] **Step 2: Write the spike workflow spec**
39 +Write `<scratchpad>/spike-web.json`:
49 + "prompt":
"You have a tool allowlist. Try to call web_search with the query 'anthropic claude' AND try to call web_fetch on https://example.com . Then answer in ONE line exactly: 'search=<ok|unavailable|error> fetch=<ok|unavailable|error>'. 'unavailable' means the tool was not in your toolset.",
50 + "tools": [
"web_search"]
57 +- [ ] **Step 3: Run headless and observe**
59 +Run (the prompt forces the model to call the `workflow` tool with the inline spec):
62 +pi -p --mode json
"Call the workflow tool with this exact spec argument (no name, use the inline spec): $(cat <scratchpad>/spike-web.json)" 65 +Expected (the two assumptions): the probe agent reports **`search=ok`** (web_search ran AND returned results → auth/activation carried into the isolated sub-agent) and **`fetch=unavailable`** (web_fetch was NOT allowlisted → the allowlist gates _extension_ tools, not just core ones).
67 +- [ ] **Step 4: Record the result**
69 +Note in your working notes: did `search=ok`? did `fetch=unavailable`? These are the two kill criteria below.
71 +- [ ] **Step 5: Revert the hack**
73 +Restore `extensions/ultra/drivers.ts:62` to `noExtensions: true,`. Confirm `git diff extensions/ultra/drivers.ts` is empty.
75 +**Kill / adjust criteria (do NOT proceed past this task if either fails):**
77 +- If `fetch` is **`ok`** (a non-allowlisted extension tool was callable) → the allowlist does _not_ gate extension tools. Default `"all"` is unsafe. STOP, report, redesign.
78 +- If `search` is **`unavailable`/`error`** (auth didn't carry / extension didn't activate) → real web tools aren't reachable this way. STOP, report; the deferred Part B falls back to codebase-research.
79 +- If both pass → proceed to Task 2.
83 +###
Task 2: Add the `subagentExtensions` setting 87 +- Modify: `extensions/ultra/settings.ts`
88 +- Test: `extensions/ultra/__tests__/settings.test.ts`
92 +- Produces: `UltraSettings.subagentExtensions: "none" | "all"`; `ULTRA_DEFAULTS.subagentExtensions === "all"`. Consumed by Task 5 (`index.ts`).
94 +- [ ] **Step 1: Write the failing tests**
96 +Add to `extensions/ultra/__tests__/settings.test.ts`:
99 +describe(
"subagentExtensions setting", ()
=> {
100 + it(
"defaults to \"all\"", ()
=> {
101 + expect(ULTRA_DEFAULTS.subagentExtensions).
toBe(
"all");
104 + it(
"pickUltra keeps only the none|all union", ()
=> {
105 + expect(
pickUltra({ ultra: { subagentExtensions:
"none" } })).
toEqual({
106 + subagentExtensions:
"none",
108 + expect(
pickUltra({ ultra: { subagentExtensions:
"all" } })).
toEqual({
109 + subagentExtensions:
"all",
112 + expect(
pickUltra({ ultra: { subagentExtensions:
"lots" } })).
toEqual({});
115 + it(
"mergeUltraSettings folds it; later wins, bad ignored", ()
=> {
117 + mergeUltraSettings({ subagentExtensions:
"none" }).subagentExtensions,
120 + mergeUltraSettings(
121 + { subagentExtensions:
"none" },
122 + { subagentExtensions:
"all" },
123 + ).subagentExtensions,
126 + mergeUltraSettings({
127 + subagentExtensions:
"bogus" as never,
128 + }).subagentExtensions,
134 +Also **update existing exact-shape assertions** so the new 5th field doesn't break them:
136 +- The `ULTRA_DEFAULTS` `toEqual({...})` test (around line 31) — add `subagentExtensions: "all",`.
137 +- Any `mergeUltraSettings(...)` test that asserts a full literal object (around line 78-84) — add `subagentExtensions: "all",`.
138 +- Any `loadUltraSettings(...)` test asserting a full literal object (around line 138-143) — add `subagentExtensions: "all",`. (Tests that assert `toEqual(ULTRA_DEFAULTS)` need no change — they reference the constant.)
140 +- [ ] **Step 2: Run to verify failure**
142 +Run: `npx vitest run extensions/ultra/__tests__/settings.test.ts`
143 +Expected: FAIL (`subagentExtensions` undefined / property missing).
145 +- [ ] **Step 3: Implement**
147 +In `extensions/ultra/settings.ts`:
149 +Add to the `UltraSettings` interface (after `defaultTimeoutMs`):
155 +subagentExtensions:
"none" | "all";
158 +Add to `ULTRA_DEFAULTS`:
161 +subagentExtensions:
"all",
164 +Add to `pickUltra` (before `return out;`):
167 +if (ultra.subagentExtensions
=== "none" || ultra.subagentExtensions
=== "all") {
168 + out.subagentExtensions
= ultra.subagentExtensions;
172 +Add to the `mergeUltraSettings` reducer object:
176 + p.subagentExtensions
=== "none" || p.subagentExtensions
=== "all" 177 + ? p.subagentExtensions
178 + : into.subagentExtensions,
181 +- [ ] **Step 4: Run to verify pass**
183 +Run: `npx vitest run extensions/ultra/__tests__/settings.test.ts`
186 +- [ ] **Step 5: Commit** (staged; run `git commit` only on user approval)
189 +git add extensions/ultra/settings.ts extensions/ultra/__tests__/settings.test.ts
195 +###
Task 3: Thread `loadExtensions` into the session factory 199 +- Modify: `extensions/ultra/drivers.ts`
200 +- Test: `extensions/ultra/__tests__/drivers.test.ts`
204 +- Consumes: nothing new.
205 +- Produces: `SessionFactoryDeps.loadExtensions?: boolean`. The factory sets `noExtensions: !loadExtensions` (omitted dep ⇒ `noExtensions: true`). Consumed by Task 5.
207 +- [ ] **Step 1: Write the failing test**
209 +Add to `extensions/ultra/__tests__/drivers.test.ts` (mirror the existing `makeSessionFactory` test's `FakeLoader` + `createAgentSession` fakes; capture the loader opts):
212 +it(
"loadExtensions:true flips noExtensions to false; other isolation flags stay true",
async ()
=> {
213 + let loaderOpts
: Record<
string,
unknown>
= {};
215 + constructor(opts
: Record<
string,
unknown>) {
220 + const fakeSession
= { id:
"s" };
221 + const createAgentSession
= vi.
fn(
async ()
=> ({ session: fakeSession }));
223 + const factory
= makeSessionFactory({
224 + createAgentSession,
225 + DefaultResourceLoader: FakeLoader
as any,
226 + getAgentDir: ()
=> "/agent",
229 + loadExtensions:
true,
233 + tools: [
"web_search",
"structured_output"],
235 + sessionManager: {},
238 + expect(loaderOpts.noExtensions).
toBe(
false);
240 + expect(loaderOpts.noSkills).
toBe(
true);
241 + expect(loaderOpts.noPromptTemplates).
toBe(
true);
242 + expect(loaderOpts.noThemes).
toBe(
true);
243 + expect(loaderOpts.noContextFiles).
toBe(
true);
247 +(The existing test that asserts `noExtensions: true` with no `loadExtensions` dep stays valid — `!undefined === true`.)
249 +- [ ] **Step 2: Run to verify failure**
251 +Run: `npx vitest run extensions/ultra/__tests__/drivers.test.ts`
252 +Expected: FAIL (`loaderOpts.noExtensions` is `true`, not `false`).
254 +- [ ] **Step 3: Implement**
256 +In `extensions/ultra/drivers.ts`, add to `SessionFactoryDeps`:
261 +loadExtensions
?: boolean;
264 +Change the resource-loader construction:
267 +noExtensions:
!deps.loadExtensions,
270 +- [ ] **Step 4: Run to verify pass**
272 +Run: `npx vitest run extensions/ultra/__tests__/drivers.test.ts`
273 +Expected: PASS (both the new test and the existing `noExtensions: true` test).
275 +- [ ] **Step 5: Commit** (staged; gated)
278 +git add extensions/ultra/drivers.ts extensions/ultra/__tests__/drivers.test.ts
284 +###
Task 4: Strip `workflow` from sub-agent allowlists (recursion defense) 288 +- Modify: `extensions/ultra/runner.ts`
289 +- Test: `extensions/ultra/__tests__/runner.test.ts`
293 +- Produces: `ULTRA_OWN_TOOL_NAMES` (exported const). The tools passed to `sessionFactory` become `[...step.tools without any ULTRA_OWN_TOOL_NAMES, STRUCTURED_OUTPUT_TOOL_NAME]`.
295 +- [ ] **Step 1: Write the failing test**
297 +Add to `extensions/ultra/__tests__/runner.test.ts` (in the tool-using `sessionFactory` describe block; reuse the existing `harness`):
300 +it(
"strips ultra's own `workflow` tool from the sub-agent allowlist (no recursion)",
async ()
=> {
301 + const harness
= makeFactoryHarness();
302 + const drivers
= makeDrivers({ sessionFactory: harness.factory });
303 + const runner
= makeStepRunner(drivers, ctxLike, baseOpts);
307 + tools: [
"read",
"workflow"],
314 + expect(harness.captured.args?.tools).
toEqual([
316 + STRUCTURED_OUTPUT_TOOL_NAME,
318 + expect(harness.captured.args?.tools).not.
toContain(
"workflow");
322 +(Use the same harness/`makeDrivers`/`ctxLike`/`baseOpts` helpers the existing tool-using tests use — match their exact names from the top of the file.)
324 +- [ ] **Step 2: Run to verify failure**
326 +Run: `npx vitest run extensions/ultra/__tests__/runner.test.ts`
327 +Expected: FAIL (`args.tools` is `["read","workflow",structured_output]`).
329 +- [ ] **Step 3: Implement**
331 +In `extensions/ultra/runner.ts`, near `STRUCTURED_OUTPUT_TOOL_NAME`:
337 +export const ULTRA_OWN_TOOL_NAMES
= [
"workflow"]
as const;
339 +function sanitizeSubagentTools(tools
: string[]
| undefined)
: string[] {
340 + const own
= ULTRA_OWN_TOOL_NAMES
as readonly string[];
341 + return (tools
?? []).
filter((t)
=> !own.
includes(t));
345 +Change the `tools:` line in the `sessionFactory` call (the `[...(step.tools ?? []), STRUCTURED_OUTPUT_TOOL_NAME]` line):
348 +tools: [
...sanitizeSubagentTools(step.tools), STRUCTURED_OUTPUT_TOOL_NAME],
351 +- [ ] **Step 4: Run to verify pass**
353 +Run: `npx vitest run extensions/ultra/__tests__/runner.test.ts`
354 +Expected: PASS (new test green; existing tools assertions unaffected — they list no `workflow`).
356 +- [ ] **Step 5: Commit** (staged; gated)
359 +git add extensions/ultra/runner.ts extensions/ultra/__tests__/runner.test.ts
365 +###
Task 5: Wire the setting through `index.ts` + document, then full CI 369 +- Modify: `extensions/ultra/index.ts` (the `buildStepRunner` → `makeSessionFactory` call, ~line 92)
370 +- Modify: `extensions/ultra/README.md` (Settings section)
374 +- Consumes: `cfg.subagentExtensions` (Task 2), `SessionFactoryDeps.loadExtensions` (Task 3).
376 +- [ ] **Step 1: Wire it**
378 +In `extensions/ultra/index.ts`, in the `makeSessionFactory({ ... })` call inside `buildStepRunner`, add the dep (alongside `cwd`, `modelRegistry`):
381 +loadExtensions: cfg.subagentExtensions
=== "all",
384 +(No unit test: `index.ts` is thin SDK glue — its own module comment notes the harness asserts registration only. The behaviour is covered by Tasks 2–4 + the Task 1 spike.)
386 +- [ ] **Step 2: Document the setting + portability contract**
388 +In `extensions/ultra/README.md` Settings section, add a short paragraph:
391 +`ultra.subagentExtensions` (`"all"` | `"none"`, default `"all"`) controls whether
392 +workflow sub-agents load the host's extensions. With `"all"`, a step can grant any
393 +tool an installed extension provides (e.g. `web_search`); with `"none"`, sub-agents
394 +are isolated to the core tools (`bash`, `find`, `grep`, `ls`, `read`, `ripgrep`).
395 +Either way the step's `tools` allowlist is the only gate on what's active, and
396 +ultra's own `workflow` tool is never grantable to a sub-agent. Workflows should
397 +name **tools**, never extensions — a workflow that lists a tool no installed
398 +extension provides simply runs without it.
401 +- [ ] **Step 3: Full CI green**
403 +If present, move the gitignored local settings aside first:
406 +[ -f .claude/settings.local.json
] && mv .claude/settings.local.json
<scratchpad
>/settings.local.json.bak
|| true
410 +Expected: lint 0 errors, all tests pass (settings/drivers/runner additions included), checks OK. Restore the file afterward if moved.
412 +- [ ] **Step 4: Commit** (staged; gated)
415 +git add extensions/ultra/index.ts extensions/ultra/README.md
423 +**Spec coverage (Part A):**
425 +- Setting `none|all` default `all` → Task 2. ✓
426 +- Only `noExtensions` flips, other isolation flags stay → Task 3 (asserted). ✓
427 +- Tool allowlist is the gate → unchanged behaviour, proven by Task 1 spike. ✓
428 +- `workflow` recursion defense → Task 4. ✓
429 +- Wiring + docs → Task 5. ✓
430 +- Spike with kill criteria → Task 1. ✓
431 +- Part B (`research` workflow) → explicitly deferred, no task. ✓
433 +**Placeholder scan:** No TBD/TODO; every code + test step shows concrete code. The only "around line N" references are for locating _existing_ assertions to update (exact code given). ✓
435 +**Type consistency:** `subagentExtensions: "none" | "all"` used identically in settings type, defaults, pick, merge, and the `index.ts` `=== "all"` check. `loadExtensions?: boolean` consistent between Task 3 (def) and Task 5 (use). `ULTRA_OWN_TOOL_NAMES` / `sanitizeSubagentTools` consistent within Task 4. ✓