pi-crew 0.9.54 → 0.9.55

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
 
+## [0.9.55] — HOTFIX: ship src/ (child workers load src/prompt/prompt-runtime.ts by path) (2026-07-29)
+
+**Fixes the delegation / team-run regression** that affected 0.9.52–0.9.54. The extension loaded fine (0.9.54), but delegation/team-run failed with "pi-crew run failed" — the child worker `pi` process could not find its extension.
+
+### Root cause (third consequence of PKG-2)
+pi-crew spawns a child `pi` worker per agent task and passes it `--extension <packageRoot>/src/prompt/prompt-runtime.ts` (pi-args.ts `PROMPT_RUNTIME_EXTENSION_PATH`). The child loads that file BY PATH as its extension. PKG-2 (Sprint 6) removed `src/` from the npm tarball to slim it, so the file did not exist in published installs → child failed → "pi-crew run failed".
+
+This was masked in 0.9.52/0.9.53 by the load failure (extension never loaded, so delegation was never reached). 0.9.54 fixed the load, surfacing this. (Not Windows-specific — my Linux repro passed only because the dev checkout has `src/`; published installs do not.)
+
+`prompt-runtime.ts` also imports 3 more src/ files (crew-broker-child, internal-error, safe-paths), so shipping just it is insufficient.
+
+### Fix
+- **Ship `src/` again** — add `"src/"` to package.json `files`. Reverts the PKG-2 src/ removal. The child worker can now find prompt-runtime.ts. Tarball stays lean (2.4MB compressed / 8.9MB unpacked).
+- **prepack hook** (`scripts/clean-strip-types.mjs`): strips the ~290 strip-types `.js` companion files (dev-only cache, gitignored) from `src/` before every pack/publish, keeping the tarball clean regardless of local dev state.
+- esbuild stays in `dependencies` (0.9.54 fix retained).
+
+### Regression guards (CI Test step)
+- `test/unit/package-ships-src.test.ts` — **new**. Asserts `files` includes `src/` and the path-loaded files exist. Would have caught the PKG-2 regression.
+- `test/unit/bundle-deps-consistency.test.ts` (0.9.54) — bundle external imports declared as runtime deps (caught the esbuild-devDep bug).
+- `test/unit/extension-entry-load.test.ts` (0.9.53) — index.ts has no static src/ imports.
+
+### Note on PKG-2 / 0.9.52–0.9.54
+PKG-2's tarball-slimming caused THREE bugs (load failure, esbuild-devDep mask, delegation failure). 0.9.52–0.9.54 are deprecated. `latest` → 0.9.55.
+
 ## [0.9.54] — HOTFIX (real root cause): esbuild runtime dep mis-declared as devDependency (2026-07-29)
 
 **Fixes the TRUE root cause** of the extension-load regression that affected 0.9.52 AND 0.9.53. Both are deprecated; `latest` now points here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.54",
+  "version": "0.9.55",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -31,6 +31,7 @@
   "files": [
     "*.ts",
     "*.mjs",
+    "src/",
     "dist/index.mjs",
     "dist/build-meta.json",
     "agents/",
@@ -39,6 +40,7 @@
     "skills/**",
     "themes/",
     "assets/crew-vibes.ttf",
+    "scripts/clean-strip-types.mjs",
     "scripts/postinstall.mjs",
     "scripts/install-crew-vibes-font.mjs",
     "scripts/build-crew-vibes-font.py",
@@ -93,7 +95,8 @@
     "bench:capture": "node scripts/run-bench.mjs && node -e \"require('node:fs').copyFileSync('test/bench/results.json','test/bench/baseline.json')\"",
     "profile:startup": "node scripts/profile-startup.mjs",
     "smoke:pi": "pi install .",
-    "smoke:release": "node scripts/release-smoke.mjs"
+    "smoke:release": "node scripts/release-smoke.mjs",
+    "prepack": "node scripts/clean-strip-types.mjs"
   },
   "exports": {
     "./schema.json": "./schema.json",

package/scripts/clean-strip-types.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * prepack hook — strip strip-types `.js` companion cruft from `src/` before
+ * packing/publishing.
+ *
+ * WHY: Pi's strip-types loader (and node:test runs) emit a `.js` companion
+ * next to every `.ts` it transpiles, as a cache. These are gitignored
+ * (the `src slash star-star slash star.js` rule in .gitignore) and never
+ * committed, but they accumulate in dev checkouts. `npm pack` would
+ * otherwise ship ~290 stale `.js` files (~4MB of cruft) that don't exist in
+ * a fresh checkout.
+ *
+ * This hook runs before every `npm pack` / `npm publish` and deletes them so
+ * the published tarball is always clean (only the `.ts` sources ship). They
+ * regenerate harmlessly on the next strip-types load. Deleting is safe: pi-crew
+ * loads via the bundle (`dist/index.mjs`) or by explicit `.ts` path — never the
+ * strip-types `.js` companions.
+ *
+ * Robust: any error is logged + swallowed (never blocks a pack/publish).
+ */
+import { readdirSync, rmSync, statSync } from "node:fs";
+import { resolve, join, relative } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const SRC = join(root, "src");
+// Only `.js` and `.js.map` are strip-types companions. `.d.ts` files are NEVER
+// emitted by strip-types — they are hand-written source type shims (e.g.
+// src/types/diff.d.ts) and must be preserved.
+const STRIP_EXT = [".js", ".js.map"];
+
+function walk(dir) {
+	let out = [];
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		const full = join(dir, e.name);
+		if (e.isDirectory()) {
+			out = out.concat(walk(full));
+		} else if (e.isFile() && STRIP_EXT.some((x) => e.name.endsWith(x))) {
+			out.push(full);
+		}
+	}
+	return out;
+}
+
+try {
+	const files = walk(SRC);
+	for (const f of files) rmSync(f, { force: true });
+	if (files.length > 0) {
+		console.log(
+			`[prepack] removed ${files.length} strip-types companion file(s) from src/`,
+		);
+	}
+} catch (e) {
+	console.warn(`[prepack] non-fatal: ${e?.message ?? e}`);
+}

package/src/adapters/claude-adapter.ts

@@ -0,0 +1,23 @@
+import type { ExportAdapter, ExportContent } from "./types.ts";
+
+export const claudeAdapter: ExportAdapter = {
+	toolId: "claude",
+	toolName: "Claude Code",
+	fileExtension: ".md",
+
+	getFilePath(content: ExportContent): string {
+		return `.claude/commands/pi-crew/${content.id}.md`;
+	},
+
+	formatFile(content: ExportContent): string {
+		const tagLines = content.tags.length > 0 ? ["tags:", ...content.tags.map((tag) => `  - ${JSON.stringify(tag)}`)] : [];
+		const frontmatter = [
+			"---",
+			`description: ${JSON.stringify(content.description)}`,
+			`category: ${JSON.stringify(content.category)}`,
+			...tagLines,
+			"---",
+		].join("\n");
+		return `${frontmatter}\n\n# ${content.name}\n\n${content.body}\n`;
+	},
+};

package/src/adapters/codex-adapter.ts

@@ -0,0 +1,21 @@
+import type { ExportAdapter, ExportContent } from "./types.ts";
+
+export const codexAdapter: ExportAdapter = {
+	toolId: "codex",
+	toolName: "Codex",
+	fileExtension: ".md",
+
+	getFilePath(_content: ExportContent): string {
+		return "AGENTS.md";
+	},
+
+	formatFile(content: ExportContent): string {
+		const tags = content.tags.length > 0 ? ` (${content.tags.join(", ")})` : "";
+		return [
+			`## ${content.name}${tags}\n`,
+			`**Source:** ${content.source.type}/${content.source.name}  `,
+			`**Category:** ${content.category}\n`,
+			content.body,
+		].join("\n");
+	},
+};

package/src/adapters/cursor-adapter.ts

@@ -0,0 +1,17 @@
+import type { ExportAdapter, ExportContent } from "./types.ts";
+
+export const cursorAdapter: ExportAdapter = {
+	toolId: "cursor",
+	toolName: "Cursor",
+	fileExtension: ".md",
+
+	getFilePath(content: ExportContent): string {
+		return `.cursor/rules/pi-crew-${content.id}.md`;
+	},
+
+	formatFile(content: ExportContent): string {
+		const header = `# ${content.name}\n\n> ${content.description}`;
+		const tags = content.tags.length > 0 ? `\n\n**Tags:** ${content.tags.join(", ")}` : "";
+		return `${header}${tags}\n\n${content.body}\n`;
+	},
+};

package/src/adapters/export-util.ts

@@ -0,0 +1,143 @@
+import type { AgentConfig } from "../agents/agent-config.ts";
+import type { SkillDescriptor } from "../skills/discover-skills.ts";
+import type { TeamConfig } from "../teams/team-config.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+import { adapterRegistry } from "./registry.ts";
+import type { ExportContent } from "./types.ts";
+
+function slugify(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+export function agentToExportContent(agent: AgentConfig): ExportContent {
+	const category = agent.routing?.category ?? "agent";
+	const tags = agent.routing?.triggers ?? [];
+	return {
+		id: slugify(agent.name),
+		name: agent.name,
+		description: agent.description,
+		category,
+		tags,
+		body: agent.systemPrompt,
+		source: { type: "agent", name: agent.name },
+	};
+}
+
+export function teamToExportContent(team: TeamConfig): ExportContent {
+	const category = team.routing?.category ?? "team";
+	const tags = team.routing?.triggers ?? [];
+	const rolesDesc = team.roles.map((role) => `- **${role.name}**: ${role.description ?? role.agent}`).join("\n");
+	const body = `${team.description}\n\n### Roles\n${rolesDesc}`;
+	return {
+		id: slugify(team.name),
+		name: team.name,
+		description: team.description,
+		category,
+		tags,
+		body,
+		source: { type: "team", name: team.name },
+	};
+}
+
+export function workflowToExportContent(workflow: WorkflowConfig): ExportContent {
+	const stepsDesc = workflow.steps.map((step) => `- **${step.id}** (${step.role}): ${step.task}`).join("\n");
+	const body = `${workflow.description}\n\n### Steps\n${stepsDesc}`;
+	return {
+		id: slugify(workflow.name),
+		name: workflow.name,
+		description: workflow.description,
+		category: "workflow",
+		tags: [],
+		body,
+		source: { type: "workflow", name: workflow.name },
+	};
+}
+
+export function skillToExportContent(skill: SkillDescriptor): ExportContent {
+	return {
+		id: slugify(skill.name),
+		name: skill.name,
+		description: skill.description || `Skill: ${skill.name}`,
+		category: "skill",
+		tags: [],
+		body: `Skill loaded from ${skill.source}: ${skill.path}`,
+		source: { type: "skill", name: skill.name },
+	};
+}
+
+export type ExportableResource =
+	| { kind: "agent"; config: AgentConfig }
+	| { kind: "team"; config: TeamConfig }
+	| { kind: "workflow"; config: WorkflowConfig }
+	| { kind: "skill"; config: SkillDescriptor };
+
+export function resourcesToExportContent(resources: ExportableResource[]): ExportContent[] {
+	const results: ExportContent[] = [];
+	for (const resource of resources) {
+		switch (resource.kind) {
+			case "agent":
+				results.push(agentToExportContent(resource.config));
+				break;
+			case "team":
+				results.push(teamToExportContent(resource.config));
+				break;
+			case "workflow":
+				results.push(workflowToExportContent(resource.config));
+				break;
+			case "skill":
+				results.push(skillToExportContent(resource.config));
+				break;
+		}
+	}
+	return results;
+}
+
+export interface ToolExportResult {
+	toolId: string;
+	files: Array<{ path: string; content: string }>;
+}
+
+export function generateToolExport(toolId: string, resources: ExportableResource[], projectRoot?: string): ToolExportResult {
+	const adapter = adapterRegistry.get(toolId);
+	if (!adapter) {
+		throw new Error(
+			`Unknown export adapter: ${toolId}. Available: ${adapterRegistry
+				.getAll()
+				.map((a) => a.toolId)
+				.join(", ")}`,
+		);
+	}
+	const contents = resourcesToExportContent(resources);
+	const files = contents.map((content): { path: string; content: string } => {
+		const filePath = adapter.getFilePath(content);
+		// Validate path containment when a project root is provided
+		if (projectRoot) {
+			try {
+				resolveRealContainedPath(projectRoot, filePath);
+			} catch (e) {
+				throw new Error(
+					`Export path '${filePath}' escapes project root '${projectRoot}': ${e instanceof Error ? e.message : String(e)}`,
+				);
+			}
+		}
+		return {
+			path: filePath,
+			content: adapter.formatFile(content),
+		};
+	});
+	// Merge duplicate file paths (e.g., codex adapter maps everything to AGENTS.md)
+	const merged = new Map<string, string>();
+	for (const f of files) {
+		const existing = merged.get(f.path);
+		merged.set(f.path, existing ? `${existing}\n\n${f.content}` : f.content);
+	}
+	const mergedFiles = [...merged.entries()].map(([p, content]) => ({
+		path: p,
+		content,
+	}));
+	return { toolId, files: mergedFiles };
+}

package/src/adapters/index.ts

@@ -0,0 +1,15 @@
+export { claudeAdapter } from "./claude-adapter.ts";
+export { codexAdapter } from "./codex-adapter.ts";
+export { cursorAdapter } from "./cursor-adapter.ts";
+export { generateToolExport, resourcesToExportContent } from "./export-util.ts";
+export { adapterRegistry, createAdapterRegistry } from "./registry.ts";
+export type { AdapterRegistry, ExportAdapter, ExportContent } from "./types.ts";
+
+import { claudeAdapter } from "./claude-adapter.ts";
+import { codexAdapter } from "./codex-adapter.ts";
+import { cursorAdapter } from "./cursor-adapter.ts";
+import { adapterRegistry } from "./registry.ts";
+
+adapterRegistry.register(claudeAdapter);
+adapterRegistry.register(cursorAdapter);
+adapterRegistry.register(codexAdapter);

package/src/adapters/registry.ts

@@ -0,0 +1,18 @@
+import type { AdapterRegistry, ExportAdapter } from "./types.ts";
+
+export function createAdapterRegistry(): AdapterRegistry {
+	const adapters = new Map<string, ExportAdapter>();
+	return {
+		get(toolId: string): ExportAdapter | undefined {
+			return adapters.get(toolId);
+		},
+		getAll(): ExportAdapter[] {
+			return [...adapters.values()];
+		},
+		register(adapter: ExportAdapter): void {
+			adapters.set(adapter.toolId, adapter);
+		},
+	};
+}
+
+export const adapterRegistry: AdapterRegistry = createAdapterRegistry();

package/src/adapters/types.ts

@@ -0,0 +1,23 @@
+export interface ExportContent {
+	id: string;
+	name: string;
+	description: string;
+	category: string;
+	tags: string[];
+	body: string;
+	source: { type: "agent" | "team" | "workflow" | "skill"; name: string };
+}
+
+export interface ExportAdapter {
+	readonly toolId: string;
+	readonly toolName: string;
+	readonly fileExtension: string;
+	getFilePath(content: ExportContent): string;
+	formatFile(content: ExportContent): string;
+}
+
+export interface AdapterRegistry {
+	get(toolId: string): ExportAdapter | undefined;
+	getAll(): ExportAdapter[];
+	register(adapter: ExportAdapter): void;
+}

package/src/agents/agent-config.ts

@@ -0,0 +1,194 @@
+import type { RoleToolConfig } from "../config/role-tools.ts";
+import { getToolConfig } from "../config/role-tools.ts";
+
+/**
+ * F1 (v0.7.9): canonical built-in tool name list. Used by `parseToolsField`
+ * to expand wildcard `*` / `all` patterns in agent frontmatter. Matches
+ * pi-subagents' `BUILTIN_TOOL_NAMES` (derived from pi's `createCodingTools` /
+ * `createReadOnlyTools`). If pi adds a new built-in, update this list and
+ * the wildcard expansion will pick it up. The 7 names below are stable
+ * across pi v0.77+ and cover read, edit, write, bash, grep, find, ls.
+ */
+export const BUILTIN_TOOL_NAMES: readonly string[] = ["read", "edit", "write", "bash", "grep", "find", "ls"];
+
+/**
+ * F1 (v0.7.9): normalize the raw `tools:` frontmatter CSV into a `string[]`.
+ * Semantics (matching pi-subagents' `parseToolsField`):
+ *   - omitted / undefined → returns `undefined` (back-compat: use the
+ *     runtime default — today this is the role-tools default; tomorrow this
+ *     could become the wildcard expansion if the user opts in).
+ *   - `*` or `all` (case-insensitive) → returns the full BUILTIN_TOOL_NAMES
+ *     list (no duplicates).
+ *   - `none` or empty string → returns `[]` (zero built-ins; extension
+ *     tools via `ext:` can still be added, though pi-crew doesn't parse
+ *     `ext:` selectors yet — see F1 sub-gap).
+ *   - CSV → returns the parsed entries (trimmed, empty entries dropped).
+ * Plain tool names (no `*`) pass through unchanged so existing agent
+ * files keep working with no edits.
+ */
+export function parseToolsField(raw: unknown): string[] | undefined {
+	if (raw === undefined || raw === null) return undefined;
+	const s = typeof raw === "string" ? raw.trim() : String(raw).trim();
+	if (!s) return [];
+	const lowered = s.toLowerCase();
+	if (lowered === "none" || lowered === "[]") return [];
+	if (lowered === "*" || lowered === "all") return [...BUILTIN_TOOL_NAMES];
+	const items = s
+		.split(",")
+		.map((t) => t.trim())
+		.filter(Boolean);
+	return items;
+}
+
+export type ResourceSource = "builtin" | "user" | "project" | "git" | "dynamic" | "project-pi";
+
+export interface RoutingMetadata {
+	triggers?: string[];
+	useWhen?: string[];
+	avoidWhen?: string[];
+	cost?: "free" | "cheap" | "expensive";
+	category?: string;
+}
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	source: ResourceSource;
+	filePath: string;
+	systemPrompt: string;
+	model?: string;
+	fallbackModels?: string[];
+	thinking?: string;
+	tools?: string[];
+	extensions?: string[];
+	/**
+	 * F1 (v0.7.9): extension denylist (case-insensitive plain names). Applied
+	 * AFTER `extensions:` (which lists the allowed set) — an excluded
+	 * extension is removed from the allowlist and never loads. Plain names
+	 * only (no paths, no `*`); an unknown name logs a warning but is
+	 * tolerated. Back-compat: omitted = no exclusion.
+	 */
+	excludeExtensions?: string[];
+	skills?: string[];
+	systemPromptMode?: "replace" | "append";
+	inheritProjectContext?: boolean;
+	inheritSkills?: boolean;
+	routing?: RoutingMetadata;
+	memory?: "user" | "project" | "local";
+	/** Tool loading strategy: "essential" = always load all tools, "lean" = only load tools in defaultTools list */
+	loadMode?: "essential" | "lean";
+	/** Explicit tool list when loadMode is "lean". null means all available tools. */
+	defaultTools?: string[] | null;
+	/** Context mode: "fresh" = clean start, "fork" = inherit parent session context */
+	contextMode?: "fresh" | "fork";
+	/** Maximum turns for this agent. Overrides runtime config if set. */
+	maxTurns?: number;
+	/** Cap on output tokens per API call. Set via PI_CREW_MAX_OUTPUT env in child. */
+	maxTokens?: number;
+	/** Effort level for this agent. Controls how much work the agent puts in. */
+	effort?: "low" | "medium" | "high";
+	/** Tools to explicitly forbid for this agent. Takes precedence over allowedTools. */
+	disallowedTools?: string[];
+	/** Disable ALL tools (Pi `--no-tools`). Used by capability-locked agents like the goal-judge (P1)
+	 *  that must have NO agency — only emit a verdict. §0c C6: an empty `tools:[]` is INSUFFICIENT
+	 *  because pi-args.ts skips empty arrays, leaving default tools enabled. */
+	disableTools?: boolean;
+	disabled?: boolean;
+	override?: { source: "config"; path: string };
+}
+
+/**
+ * Get session options (tools/excludeTools) for a specific role.
+ * Used by child-pi to apply role-based tool restrictions.
+ */
+export function getAgentSessionOptions(role: string): {
+	tools?: string[];
+	excludeTools?: string[];
+} {
+	const config: RoleToolConfig = getToolConfig(role);
+
+	if (config.tools || config.excludeTools) {
+		return {
+			tools: config.tools,
+			excludeTools: config.excludeTools,
+		};
+	}
+
+	return {};
+}
+
+/**
+ * F1 unify (v0.8.0): the single source of truth for a worker's tool policy,
+ * used by BOTH spawn paths (child-pi `pi-args.ts` and live-session
+ * `live-session-runtime.ts`). Before this, the two paths disagreed:
+ *   - child-pi: `roleConfig.tools ?? agent.tools` (role authoritative)
+ *   - live-session: `agent.tools` only (frontmatter authoritative, role ignored)
+ * so the same agent behaved differently depending on the runtime. A user
+ * defining `tools:` or `disallowed_tools:` in a custom agent's frontmatter
+ * saw it honored on one path and ignored on the other.
+ *
+ * Unified semantics (stable across both paths):
+ *   - **allowlist precedence is source-aware**:
+ *     - `source === "builtin"` → role-config authoritative (security: a
+ *       builtin explorer MUST stay read-only even if its frontmatter is
+ *       loose). Frontmatter is the fallback when the role has no allowlist.
+ *     - `source !== "builtin"` (user / project) → frontmatter `tools:`
+ *       authoritative (user intent). Role-config is the fallback.
+ *   - **denylist is additive**: `roleConfig.excludeTools` and
+ *     `agent.disallowedTools` are MERGED (dedup, order-insensitive). It is
+ *     always safe to forbid more, and merging means a security exclude
+ *     from the role can never be weakened by a frontmatter omission.
+ *
+ * Returns `{ tools, excludeTools }` where each is `undefined` when no
+ * restriction of that kind applies (so callers no-op cleanly).
+ */
+export interface ResolvedToolPolicy {
+	/** Allowlist; undefined = no allowlist restriction (all built-ins allowed). */
+	tools?: string[];
+	/** Denylist (additive); undefined = no denylist. */
+	excludeTools?: string[];
+}
+
+function uniqueToolMerge(...lists: Array<string[] | undefined>): string[] | undefined {
+	const merged = [...new Set(lists.flatMap((list) => list ?? []))];
+	return merged.length > 0 ? merged : undefined;
+}
+
+export function resolveToolPolicy(agent: AgentConfig, role?: string): ResolvedToolPolicy {
+	const roleConfig = role ? getToolConfig(role) : {};
+	// allowlist: source-aware precedence (see doc above).
+	const explicitTools = agent.source === "builtin" ? (roleConfig.tools ?? agent.tools) : (agent.tools ?? roleConfig.tools);
+	// L5: when the agent opts into `loadMode: "lean"` AND provides a
+	// non-empty `defaultTools` list, merge that list into the resolved
+	// allowlist. The merge is additive (union, dedup, order-preserving) so
+	// the existing source-aware precedence is preserved and a lean agent
+	// gets a focused-but-non-empty tool set. Signal flow:
+	//   agent YAML frontmatter (loadMode, defaultTools)
+	//     → parsed into AgentConfig
+	//     → resolveToolPolicy(agent, role) here
+	//     → policy.tools returned to buildPiWorkerArgs
+	//     → `args.push("--tools", policy.tools.join(","))` in pi-args.ts
+	//     → child pi process sees the merged allowlist
+	const tools =
+		agent.loadMode === "lean" && agent.defaultTools?.length ? uniqueToolMerge(explicitTools, agent.defaultTools) : explicitTools;
+	// denylist: additive merge of role excludeTools + agent disallowedTools.
+	const excludeTools = uniqueToolMerge(roleConfig.excludeTools, agent.disallowedTools);
+	return { tools, excludeTools };
+}
+
+/**
+ * Build agent session options including role-based tool restrictions.
+ * @param agent - The agent configuration
+ * @param role - The role name to use for tool restrictions (defaults to agent.name)
+ */
+/** @internal */
+function buildAgentSessionOptions(
+	agent: AgentConfig,
+	role?: string,
+): {
+	tools?: string[];
+	excludeTools?: string[];
+} {
+	const effectiveRole = role ?? agent.name;
+	return getAgentSessionOptions(effectiveRole);
+}