ytdb-slate 0.3.0 → 0.4.0

package/README.md

@@ -70,6 +70,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `orchestratorModeDefault` | boolean | `false` | Start fresh interactive sessions with orchestrator mode ON. |
 | `episodeModel` | string | newest available Anthropic Sonnet, else the worker's own model | Model (`provider/id`) used to compress a finished action into an episode. |
 | `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Tools available to worker threads (an empty list also falls back to the default). |
+| `workerExtensions` | string[] | `[]` | Regex patterns (matched **unanchored**) selecting which of the host session's already-loaded extensions also load into every worker thread; each matched extension's tools are added **on top of** `workerTools`. Empty (default) means workers load no extensions. The orchestrator keeps its restricted tool set but its doctrine is told what was whitelisted. Invalid patterns are dropped with a warning at session start. |
 | `maxConcurrent` | number | `4` | Maximum number of worker actions running concurrently (must be ≥ 1 — unenforced: a value of 0 or less silently hangs all dispatches). Excess dispatches wait in a queue; actions on the same thread always run in dispatch order. Default rationale: shipped `docs/design-principles.md` §5 (repo-local note). |
 | `contextBudget` | number \| object | `256000` (Anthropic models: `400000`) | Absolute orchestrator context budget (tokens) at which Slate auto-pauses and prepares a fresh-session handoff — semantics, defaults, per-model overrides, and rationale in [`docs/context-budget.md`](docs/context-budget.md). |
 | `orchestratorPromptDocs` | string[] | `[]` | Project markdown files (paths relative to the project root) whose **contents** are appended to the orchestrator system prompt. |
@@ -98,6 +99,27 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
 
 > **Silent skip:** the project-file keys fail silently — no error is shown. For the content-injected keys (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`) a missing, unreadable, or empty file is skipped and nothing is injected. For `reviewPerspectivesPath` the pointer is omitted only when the file is missing — the file is not read at injection time, so an unreadable or empty file is still cited. Verify your paths after copying the example.
 
+**Worker extensions (`workerExtensions`).** By default worker threads load no extensions. This key is a list of regex patterns that select extensions the **host session has already loaded** and load them into every worker too. Each pattern is matched **unanchored** (unlike `contextBudget.overrides`, which is anchored) against a load unit's recorded source spec (e.g. `npm:pi-web-search@1.3.1`), its load-unit path, or the entry path of any tool that unit contributes, so a bare package name matches:
+
+```json
+{
+  "workerExtensions": ["pi-smart-fetch", "pi-web-search"]
+}
+```
+
+Every worker then gets the fetch and web-search tools **on top of** `workerTools` (and on top of the per-dispatch `tools` argument of the `thread` tool — those two govern the built-in tools only). The orchestrator itself does **not** gain these tools — orchestrator mode keeps its restricted set — but its doctrine gains a rule naming each whitelisted extension and its tools, so it knows what it can delegate. pi's discovery, project-trust gating, and dedup remain the only ingress: a worker can never load an extension the host is not running, an extension that registers no tools cannot be whitelisted, and a host started with extensions disabled offers nothing to whitelist.
+
+**What to know before whitelisting** — it reaches past Slate's isolation, so it is an operator decision:
+
+- **Delegation is unbounded.** Slate guarantees only that no worker obtains Slate's own `thread`/`threads`/`episode` tools. A whitelisted extension that ships its own sub-agent or delegation tool under any other name gives workers delegation Slate can neither detect, bound, nor account for.
+- **Credential and filesystem reach.** Inside a worker the extension has the same filesystem and credential access it has in the host; Slate's read-only settings snapshot blocks pi-settings writes and nothing else.
+- **Unsynced model-scoped tools.** Worker sessions never fire the session-start event, so an extension whose tool set is model-scoped stays unsynced and may offer a tool the worker's model cannot serve (e.g. pi-web-search's `url_context` on a non-Google worker model) — the call simply fails and the episode records it.
+- **Abort.** A third-party extension may ignore the abort signal, so its network activity can outlive an abort or a context-budget pause.
+- **Cost.** Provider-native tool billing can escape Slate's worker cost accounting.
+- **Pathological patterns.** The patterns are regexes from your own trusted config — the same file that already steers models, prompts, and tool lists — matched with no time bound while the extension set is resolved once per session. A pattern with catastrophic backtracking can stall that resolution; treat it as a footgun to avoid, not a privilege boundary.
+
+The load-time recursion guard behind this — and the risks it does and does not cover — is in [`docs/design-principles.md`](docs/design-principles.md).
+
 ## Trust
 
 Slate reads project configuration (`.pi/slate.json`) and injects project files (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`, `reviewPerspectivesPath`) **only in trusted projects**. In untrusted projects Slate runs with built-in defaults and injects nothing from the working tree.

package/docs/design-principles.md

@@ -125,8 +125,11 @@ or two problems for the others:
   not blind retry.
 - **P6 — Make desired behavior the natural behavior.** In orchestrator
   mode, tactical tools are removed, so delegation is the only way to act.
-- **P7 — Guard against over-decomposition.** Workers cannot spawn threads
-  (depth-1); recursion is structurally impossible.
+- **P7 — Guard against over-decomposition.** Workers never receive
+  Slate's dispatch tools (`thread`/`threads`/`episode`), so no worker can
+  spawn a Slate thread — Slate's own recursion stays depth-1. That is a
+  narrow load-time invariant, not a general delegation bound (see the
+  recursion-guard note in §5).
 - **P8 — Per-episode feedback beats blind N-step execution.** Bounded
   actions return before the next decision, so course correction is always
   possible.
@@ -146,7 +149,7 @@ or two problems for the others:
 | P4 context by reference | `tools.ts` `context` parameter injects prior episodes by id |
 | P5 adaptive decomposition | doctrine rule 6 in `mode.ts`; no plan structure imposed anywhere |
 | P6 natural behavior | `mode.ts` `ORCHESTRATOR_TOOLS` restriction (read-only + slate tools) |
-| P7 over-decomposition guard | `worker.ts` recursion guard — workers load no extensions, so the `thread` tool never exists for them |
+| P7 over-decomposition guard | `worker.ts` recursion guard — load-scoped barriers keep Slate's `thread`/`threads`/`episode` tools out of every worker (recursion-guard note below) |
 | P8 per-episode feedback | `threads.ts` synchronous dispatch; episode returned to orchestrator |
 | P9 parallelism | `threads.ts` `maxConcurrent` queueing; doctrine rule 2 in `mode.ts` |
 | P10 context as RAM | `handoff.ts` context-budget auto-pause + fresh-session handoff |
@@ -164,6 +167,97 @@ while staying safe on common consumer API tiers; wider fan-outs only
 pay tail latency, and projects with higher-tier keys raise the cap in
 `slate.json`.
 
+Repo-local note (not from the report): the P7 guard was originally
+absolute — workers loaded no extensions, so Slate's `thread` tool simply
+never existed for them. The optional `workerExtensions` key (`slate.json`,
+trusted projects only — see the README config reference) relaxes that: it
+whitelists extensions the host session has ALREADY loaded and loads them
+into every worker. The guard therefore no longer rests on "workers load
+nothing" but on a narrower, more precise invariant: no worker can ever
+obtain SLATE's dispatch tools (`thread`/`threads`/`episode`).
+
+Three load-scoped barriers buy that invariant, all applied per LOAD UNIT
+— the owning package directory when the extension is package-originated
+and the package's declared entries provably match what the host loaded
+(BG20, below), otherwise the extension's own entry file:
+
+1. Only whitelisted units load, through pi's resource loader in allowlist
+   mode; a worker's extension set is exactly the allowlist and no
+   non-whitelisted module is ever imported (load errors surface as
+   warnings). Candidates are only what the host session already loaded,
+   enumerated from its tool registry — so an extension registering no
+   tools is invisible, and a host started with extensions disabled yields
+   an empty candidate set.
+2. Any unit that contains Slate's own package root is dropped whatever the
+   patterns say.
+3. Any unit whose tools collide with Slate's `thread`/`threads`/`episode`
+   or with pi's built-ins (`read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`)
+   is dropped WHOLE — pi's registry lets an extension tool overwrite a
+   same-named built-in, so a partial load could shadow the very tools the
+   guard protects.
+
+Exclusion has to happen at load time, at unit granularity, rather than by
+loading everything and filtering the tool list afterwards: a
+worker-loaded extension is not tools-only. Its event handlers, tools, and
+flags all go live on load, so once a unit has loaded its side effects have
+already run and dropping its tools afterwards would leave its handlers and
+flags active. Dropping the whole unit before it loads is the only clean
+cut — which is also why barrier 3 rejects a colliding unit entirely
+instead of suppressing just the offending tool. (A package directory is
+handed to pi whole — letting pi's own manifest resolution expand it, so
+no-tool companion entries load alongside the tool-bearing ones — only when
+the manifest's declared entries are ALL literal relative paths AND the
+host loaded every one of them. A glob or override-form entry, or a host
+running only a filtered subset, fails that equivalence check and drops the
+unit to exactly the entry files the host loaded; that fallback loses the
+package's no-tool companion entries, since an entry that registered no
+tool cannot be shown to be running.)
+
+That collision barrier is best-effort and load-time only: it runs before a
+unit loads, against its tools as the HOST registry reports them, and once
+more after the load, against the tools the units actually registered — a
+post-load collision fails the dispatch CLOSED rather than opening the
+worker. Neither pass can see a tool an extension registers only LATER, on
+the worker's first turn (a `before_agent_start` handler, say). Slate's own
+dispatch tools do not depend on that scan: `createAgentSession` is given
+an `excludeTools` denylist of `thread`/`threads`/`episode` that pi applies
+AFTER the tool allowlist and re-applies on every tool-registry refresh, so
+they can never be active in a worker no matter when or by whom they are
+registered — a deferred registration included. A deferred registration
+that shadows a pi BUILT-IN (`read`, `bash`, …) has no such gap-closer —
+the worker needs the real built-in — so it stays outside Slate's control,
+exactly as available to any extension the host session runs. The guard
+bounds Slate's dispatch tools, not every tool an extension might register
+at runtime.
+
+The orchestrator does NOT get the whitelisted tools; orchestrator mode
+keeps its restricted set. Instead its doctrine gains a rule listing each
+whitelisted extension with its tool names and descriptions, so it knows
+what it can delegate. That doctrine rule and the worker allowlists come
+from a single memoized resolution per session, so the two cannot drift.
+
+The invariant bought is exactly that: no worker gets Slate's dispatch
+tools. It is NOT a general recursion or delegation bound, and the accepted
+risks that follow are the operator's to weigh:
+
+- A whitelisted extension that registers its OWN sub-agent or delegation
+  tool under any other name gives workers unbounded delegation that Slate
+  can neither detect nor bound, outside Slate's episode and cost
+  accounting. Whitelisting such an extension is a deliberate operator
+  decision.
+- Inside a worker a whitelisted extension has the same filesystem and
+  credential reach it has in the host; Slate's read-only settings snapshot
+  blocks pi-settings writes and nothing else.
+- Worker sessions never fire the session-start event, so an extension
+  whose model-scoped tool manager depends on it stays unsynced and may
+  offer a tool the worker's model cannot serve — the call simply fails and
+  the episode records it.
+- Third-party extensions may ignore the abort signal, so their network
+  activity can outlive an abort or a context-budget pause.
+- Host and worker copies of the same extension share module-level state
+  through pi's process-global module cache.
+- Provider-native tool billing may escape Slate's worker cost accounting.
+
 ## 6. Runtime knowledge: what the orchestrator knows, and when
 
 The orchestrator's knowledge of these principles is two-tier, following

package/extension/failover.ts

@@ -27,18 +27,11 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { withGlobalModelDefaultRestored } from "./model-default.ts";
+import { sanitizeForNotify } from "./notify.ts";
 import type { SlateConfig } from "./state.ts";
 
 type RegistryModel = NonNullable<ReturnType<ExtensionContext["modelRegistry"]["find"]>>;
 
-// Error messages reach ctx.ui.notify, and pi-tui renders control/ANSI codes
-// verbatim — strip control characters and cap length before display (same
-// pattern as handoff.ts's sanitizeForNotify).
-function sanitizeForNotify(s: string, max = 120): string {
-	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
-	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
-}
-
 // Console-first reporting, for FAILURES ONLY: the console line is
 // unconditional, so a failover that could not happen still surfaces in
 // headless runs and at teardown — the has-UI branch is exactly the one that

package/extension/handoff.ts

@@ -42,6 +42,7 @@ import {
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { withGlobalModelDefaultRestored } from "./model-default.ts";
+import { sanitizeForNotify } from "./notify.ts";
 import {
 	orchestratorCostUsd,
 	type ContextBudgetObject,
@@ -94,15 +95,6 @@ function pendingFile(cwd: string): string {
 	return join(cwd, CONFIG_DIR_NAME, "slate", "pending-handoff.json");
 }
 
-// Strings from the pending file (and error messages derived from them) reach
-// ctx.ui.notify, and pi-tui renders control/ANSI codes verbatim — a seeded
-// pending file could inject terminal escapes. Strip control characters and
-// cap the length before display.
-function sanitizeForNotify(s: string, max = 120): string {
-	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
-	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
-}
-
 // Console-first reporting for the model-adoption block below, and for FAILURES
 // ONLY: the console line is unconditional, so the failure surfaces in headless
 // runs and at teardown too — the has-UI branch is exactly the one that vanishes

package/extension/index.ts

@@ -20,7 +20,8 @@
  * Optional config at <config dir>/slate.json (config dir = CONFIG_DIR_NAME,
  * ".pi" by default), honored ONLY when the project is trusted — untrusted
  * projects run on built-in defaults with no project file injection:
- *   { "episodeModel": "provider/id", "workerTools": [...], "maxConcurrent": 4,
+ *   { "episodeModel": "provider/id", "workerTools": [...],
+ *     "workerExtensions": ["regex", ...], "maxConcurrent": 4,
  *     "contextBudget": 256000, "orchestratorModeDefault": true,
  *     "orchestratorPromptDocs": ["docs/orchestrator-guidelines.md"],
  *     "workerPromptDocs": ["docs/thread-guidelines.md"],
@@ -46,6 +47,12 @@ import { registerSlateMode } from "./mode.ts";
 import { SlateStore, type SlateConfig } from "./state.ts";
 import { ThreadManager } from "./threads.ts";
 import { registerSlateTools } from "./tools.ts";
+import {
+	createWorkerExtensionResolver,
+	EMPTY_WORKER_EXTENSION_SET,
+	sanitizeWorkerExtensions,
+	type WorkerExtensionSet,
+} from "./worker-extensions.ts";
 
 function loadConfig(cwd: string): SlateConfig {
 	const file = join(cwd, CONFIG_DIR_NAME, "slate.json");
@@ -68,7 +75,16 @@ function loadConfig(cwd: string): SlateConfig {
 
 export default function (pi: ExtensionAPI) {
 	const store = new SlateStore(pi);
-	let manager = new ThreadManager(store, {});
+	// One worker-extension resolver per session (AD41), reassigned every
+	// session_start below. The DOCTRINE consumer (registerSlateMode) reads it
+	// through the live `() => resolveWorkerExtensionSet()` indirection because it
+	// always belongs to the CURRENT session. ThreadManager instead binds the
+	// resolver instance BY VALUE at construction (CN20): a manager orphaned by a
+	// session swap must keep resolving against ITS OWN session's frozen set, not a
+	// later session's — the live indirection would leak the newer set into the
+	// stale manager. Starts as the empty set (feature off) until session_start.
+	let resolveWorkerExtensionSet: () => WorkerExtensionSet = () => EMPTY_WORKER_EXTENSION_SET;
+	let manager = new ThreadManager(store, {}, resolveWorkerExtensionSet);
 
 	registerSlateTools(pi, store, () => manager);
 
@@ -78,15 +94,24 @@ export default function (pi: ExtensionAPI) {
 		// it is honored only for trusted projects; untrusted → built-in defaults.
 		const config = ctx.isProjectTrusted() ? loadConfig(ctx.cwd) : {};
 		const warn = (msg: string) => (ctx.hasUI ? ctx.ui.notify(msg, "warning") : console.warn(msg));
-		// modelFailover and contextBudget are validated eagerly: a malformed
-		// value would otherwise fail silently mid-dispatch / exactly when the
-		// auto-pause was supposed to save the orchestrator's context.
+		// modelFailover, contextBudget and workerExtensions are validated eagerly:
+		// a malformed value would otherwise fail silently mid-dispatch / exactly
+		// when the auto-pause was supposed to save the orchestrator's context.
 		config.modelFailover = sanitizeModelFailover(config.modelFailover, warn);
 		config.contextBudget = sanitizeContextBudget(config.contextBudget, warn);
+		config.workerExtensions = sanitizeWorkerExtensions(config.workerExtensions, warn);
 		if (config.contextBudget !== undefined && config.pauseThresholdPercent !== undefined) {
 			warn("slate: contextBudget is set — the deprecated pauseThresholdPercent is ignored");
 		}
-		manager = new ThreadManager(store, config);
+		// Fresh resolver AFTER sanitization (reads the cleaned patterns) and per
+		// session_start (a restart re-resolves). Same warn as the sanitizers so a
+		// withheld colliding unit surfaces the same way. First use is later, in a
+		// worker open or a doctrine build — after session_start finishes, so tools
+		// registered during session_start are captured (AD41).
+		resolveWorkerExtensionSet = createWorkerExtensionResolver(pi, () => config.workerExtensions ?? [], warn);
+		// Bound BY VALUE (CN20): this manager keeps this session's resolver even if a
+		// later session_start replaces the module variable above.
+		manager = new ThreadManager(store, config, resolveWorkerExtensionSet);
 		store.restore(ctx);
 	});
 
@@ -104,5 +129,5 @@ export default function (pi: ExtensionAPI) {
 	// order-critical relative to the handlers above (different trigger events).
 	registerOrchestratorFailover(pi, () => manager.getConfig());
 
-	registerSlateMode(pi, store, handoff, () => manager.getConfig());
+	registerSlateMode(pi, store, handoff, () => manager.getConfig(), () => resolveWorkerExtensionSet());
 }

package/extension/mode.ts

@@ -27,6 +27,7 @@ import {
 } from "./paths.ts";
 import { loadPromptDocs } from "./prompt-docs.ts";
 import { orchestratorCostUsd, type SlateConfig, type SlateStore } from "./state.ts";
+import type { WorkerExtensionSet, WorkerExtensionUnit } from "./worker-extensions.ts";
 
 const ORCHESTRATOR_TOOLS = ["read", "grep", "find", "ls", "thread", "threads", "episode"];
 
@@ -40,7 +41,68 @@ const ORCHESTRATOR_TOOLS = ["read", "grep", "find", "ls", "thread", "threads", "
  * the file exists (cwd-resolved) — missing files are skipped silently like
  * every other project doc.
  */
-function buildDoctrine(cwd: string, config: SlateConfig, trusted: boolean): string {
+// A source spec that names WHICH extension (e.g. "npm:foo") is worth showing;
+// the generic scope-ish sources are not, so rule 11 falls back to the unit path.
+const UNINFORMATIVE_SOURCES = new Set(["", "auto", "local", "cli", "project", "user", "temporary", "builtin", "sdk"]);
+
+function unitLabel(unit: WorkerExtensionUnit): string {
+	return UNINFORMATIVE_SOURCES.has(unit.source) ? unit.path : unit.source;
+}
+
+// Per-field caps for the doctrine interpolations (WB21): a tool name is an
+// identifier, a unit label is a package spec or path, a description is a
+// sentence. Caps keep a pathological 2000-char value from bloating every turn.
+const DOCTRINE_NAME_MAX = 64;
+const DOCTRINE_LABEL_MAX = 128;
+const DOCTRINE_DESC_MAX = 140;
+
+// ONE sanitizer for every extension-supplied string interpolated into the
+// orchestrator doctrine — tool names, unit labels and descriptions (WB20/WB21/
+// WB22). The doctrine is a numbered, indented plain-text block inside the
+// system prompt, so a raw value must not be able to: (WB20) inject a newline
+// that forges a new numbered directive; (WB21) run on for thousands of
+// characters; or (WB22) carry backticks/markdown that break the block's
+// structure or read as an instruction. Control characters and newlines collapse
+// to spaces, backticks and markdown structural markers are dropped, remaining
+// whitespace is collapsed, and the result is capped with an ellipsis.
+function sanitizeForDoctrine(value: string, max: number): string {
+	const cleaned = value
+		.replace(/[\u0000-\u001f\u007f\u009b]/g, " ") // control chars + newlines → space (WB20)
+		.replace(/[`*_~#>|]/g, " ") // code fences / markdown structure → space (WB22)
+		.replace(/\s+/g, " ")
+		.trim();
+	return cleaned.length > max ? `${cleaned.slice(0, max - 1)}\u2026` : cleaned;
+}
+
+/**
+ * Rule 11 (worker-extension awareness): appended ONLY when workers load extra
+ * pi extensions. With no units it returns "" so the doctrine is byte-identical
+ * to the pre-feature output (feature-off is unchanged). Phrased to match the
+ * imperative register of rules 1–10 (WS20/WS21/WS22): it LEADS with the action
+ * (delegate to a thread), states the constraint in the doctrine's own "cannot"
+ * voice, and CLOSES with an instruction. The extension/tool listing in the
+ * middle is data and renders verbatim.
+ */
+function buildWorkerExtensionsRule(extensions: WorkerExtensionSet): string {
+	if (extensions.units.length === 0) return "";
+	const lines = [
+		"11. Delegate any action that needs one of these worker-loaded pi extensions to a",
+		"   thread; you cannot call their tools yourself:",
+	];
+	for (const unit of extensions.units) {
+		lines.push(`   - ${sanitizeForDoctrine(unitLabel(unit), DOCTRINE_LABEL_MAX)}`);
+		for (const tool of unit.tools) {
+			lines.push(`     ${sanitizeForDoctrine(tool.name, DOCTRINE_NAME_MAX)}: ${sanitizeForDoctrine(tool.description, DOCTRINE_DESC_MAX)}`);
+		}
+	}
+	lines.push(
+		"   Assume every worker already has them — you need not pass them in a thread's",
+		"   `tools` allowlist.",
+	);
+	return `\n${lines.join("\n")}`;
+}
+
+function buildDoctrine(cwd: string, config: SlateConfig, trusted: boolean, extensions: WorkerExtensionSet): string {
 	// Rule 8 tail: with draft-PR publishing enabled, the umbrella draft PR is
 	// one of the gates; otherwise durable records live in the workflow log.
 	const rule8Tail =
@@ -92,7 +154,7 @@ threads execute. Rules:
    Read that file only when you must reason about slate itself (explaining
    it, changing the extension, or an unusual routing/compaction decision) —
    never for routine dispatching. Skip the read if it is already in your
-   context.`;
+   context.${buildWorkerExtensionsRule(extensions)}`;
 }
 
 /**
@@ -130,6 +192,7 @@ export function registerSlateMode(
 	store: SlateStore,
 	hooks: SlateHandoffHooks,
 	getConfig: () => SlateConfig,
+	getExtensions: () => WorkerExtensionSet,
 ): void {
 	let savedTools: string[] | undefined;
 	let uiCtx: ExtensionContext | undefined;
@@ -229,7 +292,7 @@ export function registerSlateMode(
 		// addendum goes LAST so the pause directive is the final word in the
 		// prompt, undiluted by the role guidelines.
 		const parts = [
-			buildDoctrine(ctx.cwd, config, trusted),
+			buildDoctrine(ctx.cwd, config, trusted, getExtensions()),
 			...loadDoctrineExtra(ctx.cwd, config, trusted).map((d) => `\n\n${d}`),
 			...docs.map((d) => `\n\n${d}`),
 		];

package/extension/model-default.ts

@@ -163,8 +163,12 @@ function stripControlChars(s: string): string {
 	return s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
 }
 
-// Per-FRAGMENT sanitizer for text spliced into a message — same pattern and
-// same 120-char default as failover.ts / handoff.ts's sanitizeForNotify.
+// Per-FRAGMENT sanitizer for text spliced into a message: the same logic as the
+// shared helper in notify.ts (control-char strip + 120-char cap), kept LOCAL on
+// purpose. This module also needs the bare stripControlChars primitive above for
+// truncateForReport's word-boundary report cap, which notify.ts does not
+// provide; keeping the fragment cap here lets both caps share that one strip
+// primitive rather than importing one function and re-deriving its dependency.
 function sanitizeForNotify(s: string, max = 120): string {
 	const clean = stripControlChars(s);
 	return clean.length > max ? `${clean.slice(0, max)}…` : clean;

package/extension/notify.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared notify-string sanitizer (CQ20).
+ *
+ * Strings that reach ctx.ui.notify / the console can carry user- or
+ * extension-supplied content: config values, regex patterns, extension load
+ * paths, loader error messages, pending-handoff fields. pi-tui renders
+ * control/ANSI codes verbatim, so a raw value could inject terminal escapes —
+ * strip control characters and cap the length before display.
+ *
+ * Imported by failover.ts, handoff.ts, worker.ts and worker-extensions.ts, which
+ * previously each carried a verbatim copy. model-default.ts deliberately does
+ * NOT import this: it also needs the bare control-char strip as a standalone
+ * primitive (for its word-boundary report truncation, which this helper does
+ * not do), so it keeps that primitive and its own fragment cap together locally
+ * — see the note there.
+ */
+export function sanitizeForNotify(s: string, max = 120): string {
+	const clean = s.replace(/[\u0000-\u001f\u007f\u009b]/g, "");
+	return clean.length > max ? `${clean.slice(0, max)}…` : clean;
+}

package/extension/state.ts

@@ -56,6 +56,7 @@ export interface ContextBudgetObject {
 export interface SlateConfig {
 	episodeModel?: string; // "provider/id" for the episode compressor (D5)
 	workerTools?: string[];
+	workerExtensions?: string[]; // regex patterns selecting which of the HOST session's pi extensions worker threads may load (default [] = none); see worker-extensions.ts
 	maxConcurrent?: number; // global cap on concurrently running worker actions (default 4; must be ≥ 1 — unenforced, ≤ 0 silently hangs all dispatches; rationale: docs/design-principles.md §5 repo-local note)
 	pauseThresholdPercent?: number; // DEPRECATED: legacy percent-based auto-pause (default 40); applies only when set AND contextBudget is absent or entirely invalid (invalid sanitizes to absent — a partially invalid object stays budget mode)
 	contextBudget?: number | ContextBudgetObject; // absolute orchestrator token budget; bare number = { tokens: N }; {} opts into built-in defaults (256k, 400k for anthropic/*) — see handoff.ts

package/extension/threads.ts

@@ -16,6 +16,7 @@ import { compressEpisode } from "./episodes.ts";
 import { isAuthFailure, isFailoverCandidate, resolveMappedModel } from "./failover.ts";
 import type { EpisodeRecord, SlateConfig, SlateStore, ThreadRecord } from "./state.ts";
 import { openWorkerSession, type WorkerSession } from "./worker.ts";
+import { EMPTY_WORKER_EXTENSION_SET, type WorkerExtensionSet } from "./worker-extensions.ts";
 
 export interface DispatchOptions {
 	threadId?: string;
@@ -113,6 +114,12 @@ export class ThreadManager {
 	constructor(
 		private store: SlateStore,
 		private config: SlateConfig,
+		// This session's frozen worker-extension resolver (AD41), bound BY VALUE at
+		// construction (CN20) so a manager orphaned by a session swap keeps its own
+		// session's set instead of resolving against a later one's. Read lazily per
+		// new worker. Defaults to the empty-set function so existing construction
+		// sites and test harnesses keep working with the feature off.
+		private resolveExtensions: () => WorkerExtensionSet = () => EMPTY_WORKER_EXTENSION_SET,
 	) {
 		this.semaphore = new Semaphore(config.maxConcurrent ?? 4); // default rationale: docs/design-principles.md §5 repo-local note
 	}
@@ -272,12 +279,17 @@ export class ThreadManager {
 
 			session = this.live.get(thread.id);
 			if (!session) {
+				// A NEW session gets the CURRENT frozen worker-extension set. A LIVE
+				// cached session (reused when present) keeps whatever set it was opened
+				// with — which is precisely why the resolution is frozen per session
+				// (AD41): every worker in this session then shares one extension set.
 				session = await openWorkerSession({
 					ctx,
 					sessionFile: thread.sessionFile || undefined,
 					model: thread.model,
 					tools: opts.tools ?? this.config.workerTools,
 					promptDocs: this.config.workerPromptDocs,
+					extensionPaths: this.resolveExtensions().paths,
 				});
 				this.live.set(thread.id, session);
 				// A freshly opened session starts on its configured model — drop any

package/extension/worker-extensions.ts

@@ -0,0 +1,392 @@
+/**
+ * Worker extensions: resolving which of the HOST session's pi extensions a
+ * worker thread is allowed to load.
+ *
+ * Workers normally load NO extensions (worker.ts, depth-1 recursion guard D7).
+ * This module lets a trusted project opt SPECIFIC host extensions back in, by
+ * regex, via the `workerExtensions` config. It NEVER loads anything itself —
+ * it only resolves a SET of extension load units (file paths or package
+ * directories) and the tool names they contribute, which part 2 hands to a
+ * worker's DefaultResourceLoader/tools allowlist. The resolution is what makes
+ * the feature safe; the load semantics stay pi's own.
+ *
+ * The mechanism, and the findings it answers:
+ *
+ *  - CANDIDATES come from pi.getAllTools(), keyed by each tool's sourceInfo.
+ *    Only tools that are (a) NOT built-in/sdk and (b) carry a real, absolute,
+ *    on-disk entry path survive (AD25) — otherwise a broad pattern such as
+ *    ".*" would re-advertise pi's own built-ins (read/bash/…) as delegatable
+ *    "extension" tools. The sourceInfo shape is treated defensively with a
+ *    loose cast, the way state.ts tolerates malformed session entries.
+ *
+ *  - LOAD UNITS (RG1): a package-origin tool whose baseDir holds a parseable
+ *    package.json with a `pi.extensions` array becomes a DIRECTORY unit at that
+ *    baseDir — pi's own package-manifest resolution then expands the entry set
+ *    (globs, override forms and all), so this module implements no manifest
+ *    logic. Everything else becomes a FILE unit at the tool's own entry path.
+ *    We NEVER walk parent directories looking for a manifest: in this very repo
+ *    an auto-discovered project extension would walk up to the repo's own
+ *    package.json and pull slate itself back into a worker.
+ *
+ *  - BARRIERS drop whole units before any pattern is consulted, so a broad
+ *    pattern can never punch through them:
+ *      · Self-exclusion (AD24): slate's own package root is computed ONCE from
+ *        THIS module's own location, never by asking who registered the
+ *        `thread` tool — registration is first-wins, so with two slate copies
+ *        loaded that lookup can resolve to a copy other than the one running.
+ *      · Name collision (AD44/RG2): a unit that registers a tool named like a
+ *        slate tool or a pi built-in is withheld — pi's final tool registry
+ *        lets an extension-registered tool OVERWRITE a same-named built-in, so
+ *        a colliding unit could silently replace a worker's own `read`.
+ *
+ *  - MATCHING is unanchored `regex.test` against a unit's source spec, its
+ *    path, or any of its tools' entry paths — any pattern hit selects the unit.
+ *
+ *  - FREEZE AT FIRST USE (AD41): createWorkerExtensionResolver memoizes the
+ *    first resolution forever. The orchestrator doctrine is rebuilt every turn
+ *    while a live worker keeps the tool set it was opened with, and a live
+ *    session's tool allowlist cannot be widened afterwards — freezing makes the
+ *    doctrine and every worker opened in that session provably the same set.
+ *    First use happens AFTER the host's session_start, so extensions that
+ *    register tools during session_start are still captured; a fresh resolver
+ *    is created per session_start, so a restart re-resolves.
+ *
+ * Warnings (a withheld colliding unit) go through an injected `warn` callback,
+ * never console.log — the same reporting discipline as failover.ts.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { sanitizeForNotify } from "./notify.ts";
+
+export interface WorkerExtensionTool {
+	name: string;
+	description: string;
+}
+
+export interface WorkerExtensionUnit {
+	path: string; // absolute path of the load unit (a file, or a package directory when isDirectory)
+	source: string; // recorded source spec of the unit's first tool (sourceInfo.source)
+	isDirectory: boolean; // true = package-directory unit (RG1); false = single extension file
+	tools: WorkerExtensionTool[];
+}
+
+export interface WorkerExtensionSet {
+	units: WorkerExtensionUnit[]; // selected units, sorted by path
+	paths: string[]; // selected unit paths, unit order
+	toolNames: string[]; // de-duplicated tool names of the selected units, unit order
+}
+
+/**
+ * The empty result — the off-by-default state. Shared so every consumer's
+ * feature-off path (index.ts's initial resolver, ThreadManager's default,
+ * the fast paths below) allocates nothing meaningful. DEEP-FROZEN (CQ22) so a
+ * stray `.push`/reassignment from any one consumer cannot corrupt the object
+ * every other feature-off consumer reads.
+ */
+export const EMPTY_WORKER_EXTENSION_SET: WorkerExtensionSet = Object.freeze({
+	units: Object.freeze([]),
+	paths: Object.freeze([]),
+	toolNames: Object.freeze([]),
+}) as unknown as WorkerExtensionSet;
+
+/** Slate's own model-facing tools — a unit registering any of these is withheld (AD44/RG2). */
+export const SLATE_TOOL_NAMES = ["thread", "threads", "episode"];
+
+/** pi's built-in tools — a unit registering any of these would overwrite a worker's own (AD44/RG2). */
+export const PI_BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+/** Union of the two lists above, as a set, for the collision barrier. */
+const COLLISION_NAMES = new Set([...SLATE_TOOL_NAMES, ...PI_BUILTIN_TOOL_NAMES]);
+
+/**
+ * Slate's own package root, computed ONCE from this module's location (AD24):
+ * fileURLToPath(import.meta.url) → .../extension/worker-extensions.ts, its
+ * directory → .../extension, its parent → the package root. Never derived by
+ * looking up who registered the `thread` tool (first-wins registration can
+ * resolve to a different slate copy than the one executing).
+ */
+const SLATE_PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Separator-aware containment: true iff `child` is `parent` or lies under it.
+ * The trailing separator is what keeps "/a/bc" from counting as inside "/a/b".
+ */
+function pathContains(parent: string, child: string): boolean {
+	if (parent === child) return true;
+	const prefix = parent.endsWith(sep) ? parent : parent + sep;
+	return child.startsWith(prefix);
+}
+
+/** Loose views of the getAllTools() shape — tolerated defensively (state.ts pattern). */
+interface LooseSourceInfo {
+	path?: unknown;
+	source?: unknown;
+	origin?: unknown;
+	baseDir?: unknown;
+}
+interface LooseTool {
+	name?: unknown;
+	description?: unknown;
+	sourceInfo?: LooseSourceInfo;
+}
+
+/** A surviving candidate tool with its resolved on-disk entry path and unit membership. */
+interface Candidate {
+	name: string;
+	description: string;
+	source: string;
+	path: string; // the tool's own sourceInfo.path (absolute, exists on disk)
+	baseDir?: string; // package directory when this tool qualifies for a directory unit (RG1)
+}
+
+/** Working unit accumulated during grouping; toolPaths is kept for matching only. */
+interface WorkingUnit {
+	path: string;
+	source: string;
+	isDirectory: boolean;
+	tools: WorkerExtensionTool[];
+	toolPaths: string[];
+}
+
+/** The `pi.extensions` array from a package.json, or undefined when absent/invalid/not a manifest. */
+type ManifestEntries = string[] | undefined;
+
+/**
+ * Read and parse <baseDir>/package.json, returning its `pi.extensions` array.
+ * CACHED per directory for the whole resolution (CQ21 — the manifest was
+ * previously re-read and re-parsed once per candidate tool). undefined when the
+ * file is missing, unreadable, invalid JSON, or lacks a `pi.extensions` array.
+ */
+function readPackageExtensions(baseDir: string, cache: Map<string, ManifestEntries>): ManifestEntries {
+	if (cache.has(baseDir)) return cache.get(baseDir);
+	let entries: ManifestEntries;
+	const manifest = join(baseDir, "package.json");
+	if (existsSync(manifest)) {
+		try {
+			const parsed = JSON.parse(readFileSync(manifest, "utf8")) as { pi?: { extensions?: unknown } } | null;
+			const ext = parsed?.pi?.extensions;
+			if (Array.isArray(ext)) entries = ext as string[];
+		} catch {
+			/* unreadable/invalid manifest → undefined (fall back to file units) */
+		}
+	}
+	cache.set(baseDir, entries);
+	return entries;
+}
+
+/**
+ * RG1: is `info` a package-origin tool whose baseDir carries a valid extension
+ * manifest? Returns that baseDir (a directory-unit CANDIDATE) or undefined (a
+ * file unit). Whether the directory form is actually USED is decided later by
+ * the BG20 equivalence check, once all candidates are known. Anything short of
+ * a package origin with a `pi.extensions` manifest — wrong origin, no baseDir,
+ * missing/unreadable/invalid manifest — is a file unit. Parents are never
+ * consulted.
+ */
+function packageBaseDir(info: LooseSourceInfo, cache: Map<string, ManifestEntries>): string | undefined {
+	if (info.origin !== "package") return undefined;
+	const baseDir = info.baseDir;
+	if (typeof baseDir !== "string" || baseDir === "") return undefined;
+	return readPackageExtensions(baseDir, cache) !== undefined ? baseDir : undefined;
+}
+
+/**
+ * BG20: a manifest entry is safe to hand to pi via the DIRECTORY form only if it
+ * is a plain literal relative path — no glob metacharacters and none of the
+ * !/+/- override prefixes pi's manifest matcher understands. A glob can expand
+ * differently in the worker than it did in the host, and an override prefix
+ * changes which declared entries load; either way the directory form risks
+ * loading a SUPERSET of what the host runs, so such a unit falls back to
+ * explicit file units.
+ */
+function isLiteralManifestEntry(entry: string): boolean {
+	if (entry === "" || /^[!+\-]/.test(entry)) return false;
+	return !/[*?[\]{}()!]/.test(entry);
+}
+
+/**
+ * Validate the raw `workerExtensions` config value into a list of regex source
+ * strings. undefined → [] (feature off, silently). A non-array warns and
+ * yields []. Per element: non-strings, empty strings, and patterns that fail
+ * `new RegExp` are dropped with a warning; the rest are kept in order.
+ */
+export function sanitizeWorkerExtensions(value: unknown, warn: (msg: string) => void): string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value)) {
+		warn("slate: workerExtensions must be an array of regex strings — ignoring");
+		return [];
+	}
+	const patterns: string[] = [];
+	for (const entry of value) {
+		if (typeof entry !== "string" || entry === "") {
+			warn(`slate: ignoring workerExtensions entry ${sanitizeForNotify(JSON.stringify(entry))} — expected a non-empty regex string`);
+			continue;
+		}
+		try {
+			new RegExp(entry);
+		} catch {
+			warn(`slate: ignoring workerExtensions pattern ${sanitizeForNotify(JSON.stringify(entry))} — not a valid regular expression`);
+			continue;
+		}
+		patterns.push(entry);
+	}
+	return patterns;
+}
+
+/**
+ * Resolve the set of worker-loadable extension units for `patterns`.
+ *
+ * An empty pattern list returns an empty set WITHOUT walking the registry —
+ * the fast path, since the feature is off by default. `warn` receives the
+ * collision-barrier notices (AD44/RG2); it defaults to a no-op so a bare
+ * `resolveWorkerExtensions(pi, patterns)` still type-checks and runs.
+ */
+export function resolveWorkerExtensions(
+	pi: ExtensionAPI,
+	patterns: string[],
+	warn: (msg: string) => void = () => {},
+): WorkerExtensionSet {
+	if (patterns.length === 0) return EMPTY_WORKER_EXTENSION_SET;
+
+	// One manifest read per package directory for this whole resolution (CQ21).
+	const manifestCache = new Map<string, ManifestEntries>();
+
+	// 1. CANDIDATES (AD25): extension-owned tools with a real on-disk entry path.
+	const candidates: Candidate[] = [];
+	for (const raw of pi.getAllTools()) {
+		const tool = raw as unknown as LooseTool;
+		const info = tool.sourceInfo;
+		if (!info) continue;
+		const source = typeof info.source === "string" ? info.source : "";
+		if (source === "builtin" || source === "sdk") continue;
+		const path = typeof info.path === "string" ? info.path : "";
+		if (path === "" || !isAbsolute(path) || !existsSync(path)) continue;
+		const name = typeof tool.name === "string" ? tool.name : "";
+		if (name === "") continue;
+		const description = typeof tool.description === "string" ? tool.description : "";
+		candidates.push({ name, description, source, path, baseDir: packageBaseDir(info, manifestCache) });
+	}
+	if (candidates.length === 0) return EMPTY_WORKER_EXTENSION_SET;
+
+	// 2. DIRECTORY UNITS (RG1 + BG20): a package baseDir becomes a directory unit
+	// — handed to pi WHOLE so pi's own manifest resolution expands the entries —
+	// ONLY when that is provably equivalent to what the host loaded: every manifest
+	// entry is a literal relative path AND every one of them is an entry the host
+	// actually loaded (a tool we saw). Otherwise the host may be running a filtered
+	// subset (a settings package entry can carry its own extensions filter) or a
+	// glob could expand differently in the worker, so the unit falls back to file
+	// units below. TRADE-OFF: the fallback drops a package's no-tool companion
+	// entries — correct, because an entry that registered no tool is one we cannot
+	// prove the host is running.
+	const dirUnits: string[] = [];
+	const seenDirs = new Set<string>();
+	for (const c of candidates) {
+		if (!c.baseDir || seenDirs.has(c.baseDir)) continue;
+		seenDirs.add(c.baseDir);
+		const baseDir = c.baseDir;
+		const entries = readPackageExtensions(baseDir, manifestCache);
+		if (!entries || entries.length === 0) continue;
+		const loadedEntryPaths = new Set(candidates.filter((o) => pathContains(baseDir, o.path)).map((o) => resolve(o.path)));
+		const equivalent = entries.every(
+			(e) => typeof e === "string" && isLiteralManifestEntry(e) && loadedEntryPaths.has(resolve(baseDir, e)),
+		);
+		if (equivalent) dirUnits.push(baseDir);
+	}
+
+	// 3. GROUP candidates into units. A candidate whose entry path lies inside a
+	// validated directory unit joins it (most specific wins); everything else
+	// (including candidates whose package failed the BG20 check) becomes a file
+	// unit keyed by its own path.
+	const working = new Map<string, WorkingUnit>();
+	for (const c of candidates) {
+		let unitPath: string | undefined;
+		for (const d of dirUnits) {
+			if (pathContains(d, c.path) && (unitPath === undefined || d.length > unitPath.length)) unitPath = d;
+		}
+		const isDirectory = unitPath !== undefined;
+		const key = unitPath ?? c.path;
+		let unit = working.get(key);
+		if (!unit) {
+			// unit.source is the source spec of the unit's FIRST tool.
+			unit = { path: key, source: c.source, isDirectory, tools: [], toolPaths: [] };
+			working.set(key, unit);
+		}
+		unit.tools.push({ name: c.name, description: c.description });
+		unit.toolPaths.push(c.path);
+	}
+
+	// Deterministic order (needed for stable doctrine/allowlist output).
+	const units = [...working.values()].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+	// 4. BARRIERS — applied to EVERY unit before matching, regardless of patterns.
+	const surviving: WorkingUnit[] = [];
+	for (const unit of units) {
+		// (a) Self-exclusion (AD24): drop when the unit equals slate's root, sits
+		// inside it, or contains it.
+		if (pathContains(SLATE_PACKAGE_ROOT, unit.path) || pathContains(unit.path, SLATE_PACKAGE_ROOT)) continue;
+		// (b) Name collision (AD44/RG2): checked across the WHOLE unit, not just a
+		// matched tool — any collision withholds the unit and warns.
+		const collisions = unit.tools.map((t) => t.name).filter((n) => COLLISION_NAMES.has(n));
+		if (collisions.length > 0) {
+			warn(
+				`slate: worker extension ${sanitizeForNotify(unit.path)} withheld from workers — it registers ` +
+					`${collisions.map((n) => `"${n}"`).join(", ")}, which would overwrite a slate or pi built-in tool`,
+			);
+			continue;
+		}
+		surviving.push(unit);
+	}
+
+	// 5. MATCH: compile each pattern once; a unit is selected on ANY hit against
+	// its source spec, its path, or any of its tools' entry paths. Patterns are
+	// pre-validated by sanitizeWorkerExtensions; a stray invalid one is dropped.
+	const regexes: RegExp[] = [];
+	for (const p of patterns) {
+		try {
+			regexes.push(new RegExp(p));
+		} catch {
+			/* pre-validated upstream; tolerate a raw invalid pattern */
+		}
+	}
+	const selected = surviving.filter((unit) =>
+		regexes.some((re) => re.test(unit.source) || re.test(unit.path) || unit.toolPaths.some((tp) => re.test(tp))),
+	);
+
+	// 6. RESULT: de-duplicate tool names across selected units, in unit order.
+	const seen = new Set<string>();
+	const toolNames: string[] = [];
+	for (const unit of selected) {
+		for (const t of unit.tools) {
+			if (seen.has(t.name)) continue;
+			seen.add(t.name);
+			toolNames.push(t.name);
+		}
+	}
+	return {
+		units: selected.map((u) => ({ path: u.path, source: u.source, isDirectory: u.isDirectory, tools: u.tools })),
+		paths: selected.map((u) => u.path),
+		toolNames,
+	};
+}
+
+/**
+ * Wrap resolveWorkerExtensions so it runs at most ONCE per session (AD41): the
+ * first call resolves and caches; every later call returns that same frozen
+ * set. `getPatterns` is read lazily at first use — after session_start, so
+ * tools registered during session_start are captured. A new resolver is
+ * created per session_start, so a restart re-resolves from scratch.
+ */
+export function createWorkerExtensionResolver(
+	pi: ExtensionAPI,
+	getPatterns: () => string[],
+	warn: (msg: string) => void = () => {},
+): () => WorkerExtensionSet {
+	let cached: WorkerExtensionSet | undefined;
+	return () => {
+		if (cached === undefined) cached = resolveWorkerExtensions(pi, getPatterns(), warn);
+		return cached;
+	};
+}

package/extension/worker.ts

@@ -1,11 +1,29 @@
 /**
  * Worker sessions: in-process pi SDK AgentSessions with the recursion guard.
  *
- * A worker loads NO extensions, skills, prompt templates, or themes
- * (DefaultResourceLoader no* options) — so a worker can never see slate tools
- * (ExecPlan D7, depth-1 guard) — and inherits the HOST session's project-trust
- * state via an explicit SettingsManager, so untrusted projects get neither
- * project-local settings nor the project SYSTEM.md override in workers.
+ * A worker loads NO skills, prompt templates, or themes (DefaultResourceLoader
+ * no* options), and by default NO extensions either — so a worker can never see
+ * slate tools (ExecPlan D7, depth-1 guard). It inherits the HOST session's
+ * project-trust state via an explicit SettingsManager, so untrusted projects get
+ * neither project-local settings nor the project SYSTEM.md override in workers.
+ *
+ * When the host resolved a `workerExtensions` whitelist (worker-extensions.ts),
+ * the loader runs in ALLOWLIST mode: noExtensions STAYS true — so auto-discovery
+ * (slate itself included) never runs — while additionalExtensionPaths adds back
+ * EXACTLY the resolved units and nothing else. The depth-1 guard is STRUCTURAL
+ * (SE20): createAgentSession is given an excludeTools denylist of slate's
+ * dispatch tools (thread/threads/episode), and the SDK re-applies that denylist
+ * on every tool-registry refresh, so no worker can call them no matter when or
+ * by whom they are registered — even a deferred before_agent_start registration.
+ * The resolver's load-scoped barriers plus a best-effort post-load scan (RG2
+ * below) additionally reject a unit that shadows a pi BUILT-IN at load time; a
+ * deferred built-in shadow cannot be prevented from slate's side, exactly as it
+ * cannot be for any extension in the host session.
+ * Load units are ABSOLUTE paths (package directories or entry files), NEVER npm/
+ * git specs (AD20): a spec resolves at temporary scope against a separate install
+ * root, which would not reuse the host's installed copy and would attempt a
+ * network install.
+ *
  * Worker conversations persist under
  * <config dir>/slate/threads/*.jsonl (CONFIG_DIR_NAME, ".pi" by default)
  * and are reopened via SessionManager.open.
@@ -22,7 +40,9 @@ import {
 	SettingsManager,
 	type ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { sanitizeForNotify } from "./notify.ts";
 import { loadPromptDocs } from "./prompt-docs.ts";
+import { PI_BUILTIN_TOOL_NAMES, SLATE_TOOL_NAMES } from "./worker-extensions.ts";
 
 export type WorkerSession = Awaited<ReturnType<typeof createAgentSession>>["session"];
 
@@ -58,6 +78,7 @@ export async function openWorkerSession(opts: {
 	model?: string; // "provider/id"
 	tools?: string[];
 	promptDocs?: string[]; // role-guideline doc paths, cwd-relative (default none)
+	extensionPaths?: string[]; // absolute worker-extension load units (package dirs or entry files); default none
 }): Promise<WorkerSession> {
 	const { ctx } = opts;
 	const dir = threadsDir(ctx.cwd);
@@ -110,11 +131,24 @@ export async function openWorkerSession(opts: {
 	// joins appendSystemPrompt entries with "\n\n". Trust gate: project files
 	// are never injected into worker prompts for untrusted projects.
 	const promptDocs = ctx.isProjectTrusted() ? loadPromptDocs(ctx.cwd, opts.promptDocs ?? []) : [];
+	// Absolute load units resolved by the host (worker-extensions.ts); empty =
+	// feature off, the historical no-extensions worker. Defense in depth (CQ23):
+	// re-gate on project trust here even though the config that produced these
+	// paths is itself only loaded for trusted projects (index.ts) — an untrusted
+	// project must never load extensions into a worker, whatever a future caller
+	// passes.
+	const extensionPaths = ctx.isProjectTrusted() ? (opts.extensionPaths ?? []) : [];
 	const loader = new DefaultResourceLoader({
 		cwd: ctx.cwd,
 		agentDir,
 		settingsManager,
-		noExtensions: true, // recursion guard (D7)
+		// Recursion guard (D7): auto-discovery stays OFF. additionalExtensionPaths
+		// runs the loader in allowlist mode — noExtensions keeps every
+		// auto-discovered extension out (slate included) while these absolute units
+		// are the only ones added back (AD20 — see the module header on why paths,
+		// never specs). undefined when empty so the default worker is untouched.
+		noExtensions: true,
+		additionalExtensionPaths: extensionPaths.length > 0 ? extensionPaths : undefined,
 		noSkills: true,
 		noPromptTemplates: true,
 		noThemes: true,
@@ -122,6 +156,56 @@ export async function openWorkerSession(opts: {
 	});
 	await loader.reload();
 
+	// Extension tool names actually registered by the whitelisted units — needed
+	// both for the collision re-check and for the tools allowlist below. Stays
+	// empty (and this whole block is skipped) unless a whitelist was resolved.
+	const extensionToolNames: string[] = [];
+	if (extensionPaths.length > 0) {
+		const warn = (msg: string) => (ctx.hasUI ? ctx.ui.notify(msg, "warning") : console.warn(msg));
+		const loaded = loader.getExtensions();
+		// A whitelisted extension that failed to load must not vanish silently —
+		// surface every loader error naming the path. Paths and messages are
+		// extension-supplied and flow to the UI, the console and the persisted
+		// episode, so sanitize them (SE22) like every other displayed string.
+		for (const err of loaded.errors ?? []) {
+			warn(`slate: worker extension failed to load — ${sanitizeForNotify(String(err.path))}: ${sanitizeForNotify(String(err.error))}`);
+		}
+		// Collect the tool names each loaded extension actually registered. Loose
+		// cast + Map guard: tolerate a malformed extensions/tools shape (state.ts
+		// pattern).
+		const collisions: string[] = [];
+		for (const ext of loaded.extensions ?? []) {
+			const e = ext as unknown as { path?: unknown; tools?: unknown };
+			if (!(e.tools instanceof Map)) continue;
+			for (const name of e.tools.keys()) {
+				if (typeof name !== "string" || name === "") continue;
+				extensionToolNames.push(name);
+				// LOAD-TIME collision scan (RG2), BEST-EFFORT: it sees only what the
+				// extensions registered DURING loader.reload(). A deferred registration
+				// (e.g. from a before_agent_start handler on the worker's first prompt)
+				// is invisible here — and is equally available to any extension the host
+				// session runs, so it is outside slate's control. slate's OWN invariant
+				// does NOT rely on this scan: thread/threads/episode are denied
+				// structurally by the excludeTools denylist on createAgentSession below
+				// (re-applied on every tool-registry refresh), so no worker can call them
+				// whenever they are registered. For a pi BUILT-IN there is no such
+				// gap-closer (the worker needs the real built-in), so this scan catches a
+				// LOAD-TIME shadow and fails the dispatch closed; a deferred shadow cannot
+				// be prevented.
+				if (SLATE_TOOL_NAMES.includes(name) || PI_BUILTIN_TOOL_NAMES.includes(name)) {
+					const path = typeof e.path === "string" ? e.path : "extension";
+					collisions.push(`${sanitizeForNotify(path)} → "${sanitizeForNotify(name)}"`);
+				}
+			}
+		}
+		if (collisions.length > 0) {
+			// Thrown BEFORE createAgentSession below, so no worker session is leaked.
+			throw new Error(
+				`slate: refusing to open worker — whitelisted extension(s) register tool(s) that would overwrite a slate or pi built-in tool: ${collisions.join(", ")}`,
+			);
+		}
+	}
+
 	const model = opts.model ? resolveModel(ctx, opts.model) : ctx.model;
 
 	const sessionManager = opts.sessionFile
@@ -148,7 +232,21 @@ export async function openWorkerSession(opts: {
 		// the SDK re-clamp against the CURRENT model instead. "medium" mirrors
 		// the SDK's DEFAULT_THINKING_LEVEL (not exported).
 		thinkingLevel: settingsManager.getDefaultThinkingLevel() ?? "medium",
-		tools: opts.tools && opts.tools.length > 0 ? opts.tools : DEFAULT_WORKER_TOOLS,
+		// workerTools / the per-dispatch `tools` argument govern the BUILT-IN tools
+		// only; pi's allowlist gates extension tools too, so the whitelisted
+		// extensions' registered tool names are unioned in (de-duplicated) — without
+		// this the extensions would load but stay inert (present in the registry,
+		// absent from the active set). A colliding built-in name was rejected above.
+		tools: [
+			...new Set([...(opts.tools && opts.tools.length > 0 ? opts.tools : DEFAULT_WORKER_TOOLS), ...extensionToolNames]),
+		],
+		// STRUCTURAL depth-1 guard (SE20): slate's dispatch tools are denied to EVERY
+		// worker session. excludeTools applies AFTER the allowlist and the SDK
+		// re-applies it on every tool-registry refresh, so a tool named
+		// thread/threads/episode is filtered out no matter when it is registered
+		// (including a deferred before_agent_start registration) — a worker can never
+		// re-enter the orchestrator's dispatch surface (D7).
+		excludeTools: SLATE_TOOL_NAMES,
 		resourceLoader: loader,
 		sessionManager,
 		settingsManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytdb-slate",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Slate: thread-weaving orchestration for the pi coding agent — bounded worker actions, compressed episodes, mandatory research/design/adversarial/track review workflow, configurable model failover, and orchestrator context-budget handoff.",
   "license": "Apache-2.0",
   "repository": {