@prometheus-ai/agent 0.5.4 → 0.5.8

package/src/export/share.ts

@@ -0,0 +1,269 @@
+/**
+ * Session sharing.
+ *
+ * The session JSON is gzipped and sealed with a fresh AES-256-GCM key
+ * (`[12B IV][ciphertext+tag]`, same layout as collab frames), then pushed to
+ * one of two stores:
+ *
+ *   1. A secret GitHub gist (preferred — free, durable, no relay storage)
+ *      holding base64 of the sealed blob, when an authenticated `gh` exists.
+ *   2. The share server (`POST <serverUrl>` → `{"id":"…"}`), capped at 1 MB;
+ *      oversized sessions are truncated (images first, then long strings,
+ *      then oldest entries) until the sealed blob fits.
+ *
+ * Either way the link is `<serverUrl>/<id>#<base64url key>`. The viewer page
+ * served there fetches the blob (gist ids are hex; server ids never are),
+ * decrypts with the fragment key — which never leaves the browser — and
+ * renders the same template as `/export`.
+ */
+
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { AgentState } from "@prometheus-ai/agent-core";
+import { $which, logger } from "@prometheus-ai/utils";
+import { DEFAULT_SHARE_URL } from "@prometheus-ai/wire";
+import { $ } from "bun";
+import type { SecretObfuscator } from "../secrets/obfuscator";
+import type { SessionManager } from "../session/session-manager";
+import { buildSessionData, type SessionData } from "./html";
+
+export { DEFAULT_SHARE_URL };
+
+/** Hard cap for blobs accepted by the share server (mirrors relay shareMaxBytes). */
+export const SERVER_MAX_SEALED_BYTES = 1_000_000;
+/** Gist raw fetches cap at 10 MB; keep base64 (×4/3) comfortably under it. */
+const GIST_MAX_SEALED_BYTES = 5_000_000;
+
+const IV_LENGTH = 12;
+const SHARE_KEY_BYTES = 32;
+/** The viewer picks the gist file by this suffix. */
+const GIST_FILENAME = "session.prometheusshare.txt";
+/** Gist ids are hex; the relay never issues pure-hex ids, so the viewer can route on shape. */
+const GIST_ID_RE = /^[0-9a-f]{20,64}$/;
+
+/** Progressively harsher per-string caps applied when the sealed blob is over budget. */
+const TEXT_CAPS = [32_768, 8_192, 2_048, 512];
+/** 1×1 transparent GIF; stands in for stripped data-URL images so <img> tags stay valid. */
+const BLANK_IMAGE_DATA_URL = "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==";
+const IMAGE_OMITTED_TEXT = "[image omitted from share]";
+
+export interface ShareSessionOptions {
+	/** Share server/viewer base URL; defaults to {@link DEFAULT_SHARE_URL}. */
+	serverUrl?: string;
+	/** Agent state for system prompt + tool descriptions in the snapshot. */
+	state?: AgentState;
+	/**
+	 * Redacts the snapshot before sealing: deep-walks every string (entries,
+	 * header, system prompt, tool descriptions) through the obfuscator, so
+	 * secrets that landed in persisted entries (tool outputs reading .env,
+	 * etc.) never leave the machine. Pass undefined to skip.
+	 */
+	obfuscator?: SecretObfuscator;
+}
+
+export interface ShareSessionResult {
+	/** Viewer link: `<serverUrl>/<id>#<key>`. */
+	url: string;
+	method: "gist" | "server";
+	/** Underlying gist URL (gist method only). */
+	gistUrl?: string;
+	/** True when content was trimmed to fit the upload budget. */
+	truncated: boolean;
+	sealedBytes: number;
+}
+
+/** Build the snapshot that gets sealed and uploaded, redacted when an obfuscator is provided. */
+export function buildShareSnapshot(sm: SessionManager, options?: ShareSessionOptions): SessionData {
+	const data = buildSessionData(sm, options?.state);
+	return options?.obfuscator?.hasSecrets() ? options.obfuscator.obfuscateObject(data) : data;
+}
+
+/** Share the session; tries a secret gist first, then the share server. */
+export async function shareSession(sm: SessionManager, options?: ShareSessionOptions): Promise<ShareSessionResult> {
+	const data = buildShareSnapshot(sm, options);
+	const keyBytes = new Uint8Array(SHARE_KEY_BYTES);
+	crypto.getRandomValues(keyBytes);
+	const key = await crypto.subtle.importKey("raw", keyBytes, "AES-GCM", false, ["encrypt"]);
+	const keyText = Buffer.from(keyBytes).toString("base64url");
+	const base = normalizeShareServerUrl(options?.serverUrl);
+
+	const forGist = await sealToFit(key, data, GIST_MAX_SEALED_BYTES);
+	const gist = await tryCreateGist(forGist.sealed);
+	if (gist) {
+		return {
+			url: `${base}/${gist.id}#${keyText}`,
+			method: "gist",
+			gistUrl: gist.url,
+			truncated: forGist.truncated,
+			sealedBytes: forGist.sealed.byteLength,
+		};
+	}
+
+	const forServer =
+		forGist.sealed.byteLength <= SERVER_MAX_SEALED_BYTES
+			? forGist
+			: await sealToFit(key, data, SERVER_MAX_SEALED_BYTES);
+	const id = await uploadToServer(forServer.sealed, base);
+	return {
+		url: `${base}/${id}#${keyText}`,
+		method: "server",
+		truncated: forServer.truncated,
+		sealedBytes: forServer.sealed.byteLength,
+	};
+}
+
+/** Strip trailing slashes so `<base>/<id>` composes cleanly. */
+export function normalizeShareServerUrl(serverUrl?: string): string {
+	const base = (serverUrl ?? DEFAULT_SHARE_URL).trim().replace(/\/+$/, "");
+	return base || DEFAULT_SHARE_URL;
+}
+
+interface SealedSession {
+	sealed: Uint8Array<ArrayBuffer>;
+	truncated: boolean;
+}
+
+/** Seal `data`, trimming content until the sealed blob fits `maxBytes`. Exported for tests. */
+export async function sealToFit(key: CryptoKey, data: SessionData, maxBytes: number): Promise<SealedSession> {
+	let sealed = await sealSessionData(key, data);
+	if (sealed.byteLength <= maxBytes) return { sealed, truncated: false };
+
+	// Work on a deep copy; the caller may re-fit the original at another budget.
+	const working = structuredClone(data);
+	stripImagePayloads(working);
+	sealed = await sealSessionData(key, working);
+	if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+
+	for (const cap of TEXT_CAPS) {
+		capLongStrings(working, cap);
+		sealed = await sealSessionData(key, working);
+		if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+	}
+
+	// Last resort: drop oldest entries (orphaned children render as roots).
+	while (working.entries.length > 4) {
+		working.entries = working.entries.slice(Math.ceil(working.entries.length / 2));
+		sealed = await sealSessionData(key, working);
+		if (sealed.byteLength <= maxBytes) return { sealed, truncated: true };
+	}
+
+	throw new Error(`Session too large to share: ${sealed.byteLength} bytes sealed exceeds the ${maxBytes} byte limit`);
+}
+
+/** `[12B IV][AES-256-GCM(gzip(JSON))]` — decrypted and gunzipped by share-loader.js. */
+async function sealSessionData(key: CryptoKey, data: SessionData): Promise<Uint8Array<ArrayBuffer>> {
+	const compressed = Bun.gzipSync(new TextEncoder().encode(JSON.stringify(data)));
+	const iv = new Uint8Array(IV_LENGTH);
+	crypto.getRandomValues(iv);
+	const ciphertext = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, compressed));
+	const out = new Uint8Array(IV_LENGTH + ciphertext.byteLength);
+	out.set(iv, 0);
+	out.set(ciphertext, IV_LENGTH);
+	return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** Replace inline image payloads (image blocks + data: URLs) with tiny placeholders, in place. */
+function stripImagePayloads(value: unknown): void {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const item: unknown = value[i];
+			if (isRecord(item) && item.type === "image" && typeof item.data === "string" && item.data.length > 1024) {
+				value[i] = { type: "text", text: IMAGE_OMITTED_TEXT };
+				continue;
+			}
+			stripImagePayloads(item);
+		}
+		return;
+	}
+	if (!isRecord(value)) return;
+	for (const k in value) {
+		const v = value[k];
+		if (typeof v === "string") {
+			if (v.length > 1024 && v.startsWith("data:")) value[k] = BLANK_IMAGE_DATA_URL;
+			continue;
+		}
+		stripImagePayloads(v);
+	}
+}
+
+/** Truncate every string longer than `cap`, in place. */
+function capLongStrings(value: unknown, cap: number): void {
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const item: unknown = value[i];
+			if (typeof item === "string" && item.length > cap) value[i] = `${item.slice(0, cap)}\n…[truncated for share]`;
+			else capLongStrings(item, cap);
+		}
+		return;
+	}
+	if (!isRecord(value)) return;
+	for (const k in value) {
+		const v = value[k];
+		if (typeof v === "string") {
+			if (v.length > cap) value[k] = `${v.slice(0, cap)}\n…[truncated for share]`;
+			continue;
+		}
+		capLongStrings(v, cap);
+	}
+}
+
+/** Create a secret gist holding base64 of the sealed blob; null when `gh` is unusable. */
+async function tryCreateGist(sealed: Uint8Array): Promise<{ id: string; url: string } | null> {
+	if (!$which("gh")) return null;
+	const auth = await $`gh auth status`.quiet().nothrow();
+	if (auth.exitCode !== 0) {
+		logger.debug("share: gh present but not authenticated; falling back to share server");
+		return null;
+	}
+
+	const dir = await fs.mkdtemp(path.join(os.tmpdir(), "prometheus-share-"));
+	try {
+		const file = path.join(dir, GIST_FILENAME);
+		await Bun.write(file, Buffer.from(sealed).toString("base64"));
+		const result = await $`gh gist create --public=false ${file}`.quiet().nothrow();
+		if (result.exitCode !== 0) {
+			logger.warn("share: gist creation failed; falling back to share server", {
+				stderr: result.stderr.toString("utf-8").trim().slice(0, 500),
+			});
+			return null;
+		}
+		const url = result.text().trim().split("\n").pop()?.trim() ?? "";
+		const id = url.split("/").pop() ?? "";
+		if (!GIST_ID_RE.test(id)) {
+			logger.warn("share: could not parse gist id from gh output", { url });
+			return null;
+		}
+		return { id, url };
+	} finally {
+		await fs.rm(dir, { recursive: true, force: true });
+	}
+}
+
+/** POST the sealed blob to the share server; returns the assigned id. */
+async function uploadToServer(sealed: Uint8Array, base: string): Promise<string> {
+	let res: Response;
+	try {
+		res = await fetch(base, {
+			method: "POST",
+			headers: { "Content-Type": "application/octet-stream" },
+			body: sealed,
+		});
+	} catch (err) {
+		throw new Error(`Share upload to ${base} failed: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!res.ok) {
+		const detail = (await res.text().catch(() => "")).trim().slice(0, 200);
+		throw new Error(`Share upload to ${base} failed: HTTP ${res.status}${detail ? ` (${detail})` : ""}`);
+	}
+	const body = (await res.json().catch(() => null)) as { id?: unknown } | null;
+	const id = body && typeof body.id === "string" ? body.id : "";
+	if (!/^[A-Za-z0-9_-]{10,64}$/.test(id)) {
+		throw new Error(`Share upload to ${base} failed: server returned no usable id`);
+	}
+	return id;
+}

package/src/export/ttsr.ts

@@ -5,6 +5,8 @@
  * the agent's output. When a match occurs, the stream is aborted, the rule is
  * injected as a system reminder, and the request is retried.
  */
+import * as path from "node:path";
+import { AstMatchStrictness, astMatch } from "@prometheus-ai/natives";
 import { logger } from "@prometheus-ai/utils";
 import type { Rule } from "../capability/rule";
 import type { TtsrSettings } from "../config/settings";
@@ -38,6 +40,8 @@ interface TtsrScope {
 interface TtsrEntry {
 	rule: Rule;
 	conditions: RegExp[];
+	/** ast-grep pattern strings; matched only against edit/write tool snapshots. */
+	astConditions: string[];
 	scope: TtsrScope;
 	globalPathGlobs?: Bun.Glob[];
 }
@@ -70,6 +74,8 @@ export class TtsrManager {
 	readonly #rules = new Map<string, TtsrEntry>();
 	readonly #injectionRecords = new Map<string, InjectionRecord>();
 	readonly #buffers = new Map<string, string>();
+	/** Last snapshot evaluated for AST conditions, keyed by stream key, to dedupe matcher runs. */
+	readonly #lastAstSnapshots = new Map<string, string>();
 	#messageCount = 0;
 
 	constructor(settings?: TtsrSettings) {
@@ -302,7 +308,8 @@ export class TtsrManager {
 		}
 
 		const conditions = this.#compileConditions(rule);
-		if (conditions.length === 0) {
+		const astConditions = (rule.astCondition ?? []).map(pattern => pattern.trim()).filter(p => p.length > 0);
+		if (conditions.length === 0 && astConditions.length === 0) {
 			return false;
 		}
 
@@ -318,6 +325,7 @@ export class TtsrManager {
 		this.#rules.set(rule.name, {
 			rule,
 			conditions,
+			astConditions,
 			scope,
 			globalPathGlobs,
 		});
@@ -325,6 +333,7 @@ export class TtsrManager {
 		logger.debug("TTSR rule registered", {
 			ruleName: rule.name,
 			conditions: rule.condition,
+			astConditions: rule.astCondition,
 			scope: rule.scope,
 			globs: rule.globs,
 		});
@@ -359,6 +368,112 @@ export class TtsrManager {
 		return this.#matchBuffer(snapshot, context);
 	}
 
+	/** Derive an ast-grep language alias from candidate paths (bare extension, e.g. "ts"), if any. */
+	#deriveLang(filePaths: string[] | undefined): string | undefined {
+		for (const filePath of filePaths ?? []) {
+			const ext = path.extname(this.#normalizePath(filePath));
+			if (ext.length > 1) {
+				return ext.slice(1).toLowerCase();
+			}
+		}
+		return undefined;
+	}
+
+	/**
+	 * Evaluate ast-grep `astCondition` rules against a reconstructed tool snapshot.
+	 *
+	 * Only edit/write tool streams reach here (AST conditions need a language, which
+	 * we infer from the file extension on the tool's path argument). The snapshot is
+	 * matched in memory by the native engine (`astMatch`), so this is async and
+	 * intentionally throttled: identical consecutive snapshots (the common case when
+	 * only non-source arguments change between deltas) are skipped.
+	 */
+	async checkAstSnapshot(snapshot: string, context: TtsrMatchContext): Promise<Rule[]> {
+		if (!this.#settings.enabled || context.source !== "tool") {
+			return [];
+		}
+
+		const lang = this.#deriveLang(context.filePaths);
+		if (!lang) {
+			return [];
+		}
+
+		const candidates: TtsrEntry[] = [];
+		for (const [name, entry] of this.#rules) {
+			if (entry.astConditions.length === 0) {
+				continue;
+			}
+			if (
+				!this.#canTrigger(name) ||
+				!this.#matchesScope(entry, context) ||
+				!this.#matchesGlobalPaths(entry, context)
+			) {
+				continue;
+			}
+			candidates.push(entry);
+		}
+		if (candidates.length === 0) {
+			return [];
+		}
+
+		// Throttle: skip re-running the matcher when the source content is unchanged.
+		const bufferKey = this.#bufferKey(context);
+		if (this.#lastAstSnapshots.get(bufferKey) === snapshot) {
+			return [];
+		}
+		this.#lastAstSnapshots.set(bufferKey, snapshot);
+
+		const matches: Rule[] = [];
+		for (const entry of candidates) {
+			if (await this.#astConditionsMatch(entry.astConditions, snapshot, lang)) {
+				matches.push(entry.rule);
+				logger.debug("TTSR ast condition matched", {
+					ruleName: entry.rule.name,
+					astConditions: entry.rule.astCondition,
+					toolName: context.toolName,
+					filePaths: context.filePaths,
+				});
+			}
+		}
+		return matches;
+	}
+
+	async #astConditionsMatch(patterns: string[], source: string, lang: string): Promise<boolean> {
+		try {
+			const result = await astMatch({
+				patterns,
+				source,
+				lang,
+				strictness: AstMatchStrictness.Smart,
+				limit: 1,
+			});
+			if (result.parseErrors && result.parseErrors.length > 0) {
+				logger.debug("TTSR ast match reported parse errors", { parseErrors: result.parseErrors });
+			}
+			return result.totalMatches > 0;
+		} catch (error) {
+			logger.warn("TTSR ast match failed, treating as no match", {
+				patterns,
+				lang,
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return false;
+		}
+	}
+
+	/** True when any registered rule carries ast-grep conditions. */
+	hasAstRules(): boolean {
+		if (!this.#settings.enabled) {
+			return false;
+		}
+		for (const entry of this.#rules.values()) {
+			if (entry.astConditions.length > 0) {
+				return true;
+			}
+		}
+		return false;
+	}
+
 	#matchBuffer(buffer: string, context: TtsrMatchContext): Rule[] {
 		if (!this.#settings.enabled) {
 			return [];
@@ -435,6 +550,7 @@ export class TtsrManager {
 	/** Reset stream buffers (called on new turn). */
 	resetBuffer(): void {
 		this.#buffers.clear();
+		this.#lastAstSnapshots.clear();
 	}
 
 	/** Check if any TTSR rules are registered. */
@@ -445,6 +561,11 @@ export class TtsrManager {
 		return this.#rules.size > 0;
 	}
 
+	/** All rules currently registered for TTSR monitoring, in registration order. */
+	getRules(): Rule[] {
+		return Array.from(this.#rules.values(), entry => entry.rule);
+	}
+
 	/** Increment message counter (call after each turn). */
 	incrementMessageCount(): void {
 		this.#messageCount++;

package/src/extensibility/custom-commands/loader.ts

@@ -1,15 +1,17 @@
 /**
  * Custom command loader - loads TypeScript command modules using native Bun import.
  *
- * Dependencies (the zod-backed typebox shim and Prometheus coding-agent) are injected via the
+ * Dependencies (the zod-backed typebox shim and pi-coding-agent) are injected via the
  * CustomCommandAPI to avoid import resolution issues with custom commands loaded from user directories.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir, getProjectDir, isEnoent, logger } from "@prometheus-ai/utils";
-import * as zod from "zod/v4";
+import { z as zod } from "zod/v4";
 import { getConfigDirs } from "../../config";
 import { execCommand } from "../../exec/exec";
+// Runtime self-reference: dereference this namespace only inside loader functions to keep the index.ts cycle safe.
+import * as PiCodingAgent from "../../index";
 import * as typebox from "../typebox";
 import { GreenCommand } from "./bundled/ci-green";
 import { ReviewCommand } from "./bundled/review";
@@ -143,7 +145,7 @@ export interface LoadCustomCommandsOptions {
 }
 
 /**
- * Load bundled commands (shipped with Prometheus coding-agent).
+ * Load bundled commands (shipped with pi-coding-agent).
  */
 function loadBundledCommands(sharedApi: CustomCommandAPI): LoadedCustomCommand[] {
 	const bundled: LoadedCustomCommand[] = [];
@@ -185,7 +187,8 @@ export async function loadCustomCommands(options: LoadCustomCommandsOptions = {}
 			execCommand(command, args, execOptions?.cwd ?? cwd, execOptions),
 		typebox,
 		zod,
-		pi: await import("@prometheus-ai/agent"),
+		prometheus: PiCodingAgent,
+		pi: PiCodingAgent,
 	};
 
 	// 1. Load bundled commands first (lowest priority - can be overridden)

package/src/extensibility/custom-commands/types.ts

@@ -5,7 +5,10 @@
  * Unlike markdown commands which expand to prompts, custom commands can execute
  * arbitrary logic with full access to the hook context.
  */
+import type { z } from "zod/v4";
 import type { ExecOptions, ExecResult, HookCommandContext } from "../../extensibility/hooks/types";
+import type * as PiCodingAgent from "../../index";
+import type * as TypeBox from "../typebox";
 
 // Re-export for custom commands to use
 export type { ExecOptions, ExecResult, HookCommandContext };
@@ -20,11 +23,13 @@ export interface CustomCommandAPI {
 	/** Execute a shell command */
 	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
 	/** Injected zod-backed typebox shim (legacy/compat). */
-	typebox: typeof import("../typebox");
+	typebox: typeof TypeBox;
 	/** Injected zod module for Zod-authored custom commands. */
-	zod: typeof import("zod/v4");
-	/** Injected coding-agent exports */
-	pi: typeof import("../..");
+	zod: typeof z;
+	/** Injected Prometheus coding agent exports */
+	prometheus: typeof PiCodingAgent;
+	/** Legacy alias for injected Prometheus coding agent exports */
+	pi: typeof PiCodingAgent;
 }
 
 /**

package/src/extensibility/custom-tools/loader.ts

@@ -1,19 +1,22 @@
 /**
  * Custom tool loader - loads TypeScript tool modules using native Bun import.
  *
- * Dependencies (the zod-backed typebox shim and Prometheus coding-agent) are injected via the
+ * Dependencies (the zod-backed typebox shim and pi-coding-agent) are injected via the
  * CustomToolAPI to avoid import resolution issues with custom tools loaded from user directories.
  */
+
 import * as path from "node:path";
 import type { AgentToolResult } from "@prometheus-ai/agent-core";
 import { logger } from "@prometheus-ai/utils";
-import * as z from "zod/v4";
+import { z } from "zod/v4";
 import { toolCapability } from "../../capability/tool";
 import { type CustomTool, loadCapability } from "../../discovery";
 import type { ExecOptions } from "../../exec/exec";
 import { execCommand } from "../../exec/exec";
 import type { HookUIContext } from "../../extensibility/hooks/types";
 import { getAllPluginToolPaths } from "../../extensibility/plugins/loader";
+// Runtime self-reference: dereference this namespace only inside loader functions to keep the index.ts cycle safe.
+import * as PiCodingAgent from "../../index";
 import * as typebox from "../typebox";
 import { createNoOpUIContext, resolvePath } from "../utils";
 import type { CustomToolAPI, CustomToolFactory, LoadedCustomTool, ToolLoadError } from "./types";
@@ -66,8 +69,10 @@ async function loadTool(
 	}
 }
 
-/** Tool path with optional source metadata */
-interface ToolPathWithSource {
+/** Tool path with optional source metadata, suitable for forwarding from a
+ * parent session to a subagent so the subagent can re-bind tools to its own
+ * `CustomToolAPI` without redoing the filesystem scan. */
+export interface ToolPathWithSource {
 	path: string;
 	source?: { provider: string; providerName: string; level: "user" | "project" };
 }
@@ -86,7 +91,7 @@ export class CustomToolLoader {
 	#seenNames: Set<string>;
 
 	constructor(
-		pi: typeof import("@prometheus-ai/agent"),
+		pi: typeof PiCodingAgent,
 		cwd: string,
 		builtInToolNames: string[],
 		pushPendingAction?: (action: {
@@ -105,6 +110,7 @@ export class CustomToolLoader {
 			logger,
 			typebox,
 			zod: z,
+			prometheus: pi,
 			pi,
 			pushPendingAction: action => {
 				if (!pushPendingAction) {
@@ -172,7 +178,7 @@ export async function loadCustomTools(
 		reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
 	}) => void,
 ) {
-	const loader = new CustomToolLoader(await import("@prometheus-ai/agent"), cwd, builtInToolNames, pushPendingAction);
+	const loader = new CustomToolLoader(PiCodingAgent, cwd, builtInToolNames, pushPendingAction);
 	await loader.load(pathsWithSources);
 	return {
 		tools: loader.tools,
@@ -184,26 +190,19 @@ export async function loadCustomTools(
 }
 
 /**
- * Discover and load tools from standard locations via capability system:
- * 1. User and project tools discovered by capability providers
- * 2. Installed plugins (~/.prometheus/plugins/node_modules/*)
- * 3. Explicitly configured paths from settings or CLI
+ * Collect the absolute tool-source paths to load, without importing or
+ * binding factories. Hot path on session startup — the scan walks
+ * `.prometheus/tools/`, `.claude/tools/`, the plugin tree, and any configured paths.
+ *
+ * Subagents reuse the parent's collected paths via the SDK's
+ * `preloadedCustomToolPaths` option, then call `loadCustomTools` themselves
+ * so each session re-binds factories with its own session-scoped
+ * `CustomToolAPI` (cwd, exec, pushPendingAction, UI).
  *
  * @param configuredPaths - Explicit paths from settings.json and CLI --tool flags
  * @param cwd - Current working directory
- * @param builtInToolNames - Names of built-in tools to check for conflicts
  */
-export async function discoverAndLoadCustomTools(
-	configuredPaths: string[],
-	cwd: string,
-	builtInToolNames: string[],
-	pushPendingAction?: (action: {
-		label: string;
-		sourceToolName: string;
-		apply(reason: string): Promise<AgentToolResult<unknown>>;
-		reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
-	}) => void,
-) {
+export async function discoverCustomToolPaths(configuredPaths: string[], cwd: string): Promise<ToolPathWithSource[]> {
 	const allPathsWithSources: ToolPathWithSource[] = [];
 	const seen = new Set<string>();
 
@@ -236,5 +235,34 @@ export async function discoverAndLoadCustomTools(
 		addPath(resolvePath(configPath, cwd), { provider: "config", providerName: "Config", level: "project" });
 	}
 
-	return loadCustomTools(allPathsWithSources, cwd, builtInToolNames, pushPendingAction);
+	return allPathsWithSources;
+}
+
+/**
+ * Discover and load tools from standard locations via capability system:
+ * 1. User and project tools discovered by capability providers
+ * 2. Installed plugins (~/.prometheus/plugins/node_modules/*)
+ * 3. Explicitly configured paths from settings or CLI
+ *
+ * Composed of {@link discoverCustomToolPaths} (FS scan) + {@link loadCustomTools}
+ * (per-session binding). Subagents skip the first step and just call
+ * `loadCustomTools` against the parent's collected paths.
+ *
+ * @param configuredPaths - Explicit paths from settings.json and CLI --tool flags
+ * @param cwd - Current working directory
+ * @param builtInToolNames - Names of built-in tools to check for conflicts
+ */
+export async function discoverAndLoadCustomTools(
+	configuredPaths: string[],
+	cwd: string,
+	builtInToolNames: string[],
+	pushPendingAction?: (action: {
+		label: string;
+		sourceToolName: string;
+		apply(reason: string): Promise<AgentToolResult<unknown>>;
+		reject?(reason: string): Promise<AgentToolResult<unknown> | undefined>;
+	}) => void,
+) {
+	const pathsWithSources = await discoverCustomToolPaths(configuredPaths, cwd);
+	return loadCustomTools(pathsWithSources, cwd, builtInToolNames, pushPendingAction);
 }