@gajae-code/coding-agent 0.15.6 → 0.16.1

package/src/tools/browser/launch.ts

@@ -293,6 +293,43 @@ function resolveSystemChromium(): string | undefined {
 	return found;
 }
 
+export function resolveSystemChromiumForTest(): string | undefined {
+	return resolveSystemChromium();
+}
+
+export function resetSystemChromiumForTest(): void {
+	resolvedChromium = undefined;
+}
+
+export function headlessExecutableForProfileReuse(): string | undefined {
+	return resolveSystemChromium() ?? trustedBrowserEnv("PUPPETEER_EXECUTABLE_PATH");
+}
+
+/**
+ * On macOS the Cookies DB is encrypted with a Keychain key whose service name is
+ * brand-specific ("Chrome Safe Storage" vs "Chromium Safe Storage"). A Chrome profile
+ * copied into a bundled Chromium therefore decrypts to garbage with no warning.
+ * Return true only when the headless executable can actually decrypt the discovered profile.
+ */
+export function canDecryptProfileCookies(
+	executablePath: string | undefined,
+	discoveredUserDataDir: string | undefined,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	if (platform !== "darwin") return true;
+	if (!discoveredUserDataDir) return true;
+	if (!executablePath) return false;
+	const lowerExe = executablePath.toLowerCase();
+	const lowerDir = discoveredUserDataDir.toLowerCase();
+	const isChromiumExe = lowerExe.includes("chromium");
+	const isChromeExe = lowerExe.includes("google chrome") || lowerExe.includes("/google/chrome");
+	const isChromiumProfile = lowerDir.includes("chromium");
+	const isChromeProfile = lowerDir.includes("google") && lowerDir.includes("chrome");
+	if (isChromeProfile && isChromiumExe && !isChromeExe) return false;
+	if (isChromiumProfile && isChromeExe) return false;
+	return true;
+}
+
 /** Edge is Chromium-based but keeps its own profile format under its own user data root. */
 const EDGE_EXECUTABLE_PATTERN =
 	/(?:^|[/\\])(?:msedge(?:\.exe)?|microsoft-edge(?:-(?:stable|beta|dev|canary))?|com\.microsoft\.Edge|Microsoft Edge(?: Beta| Dev| Canary)?)$/i;

package/src/tools/browser/registry.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { logger } from "@gajae-code/utils";
 import type { Subprocess } from "bun";
@@ -12,7 +13,14 @@ import {
 	killExistingByPath,
 	waitForCdp,
 } from "./attach";
-import { BROWSER_PROTOCOL_TIMEOUT_MS, launchHeadlessBrowser, loadPuppeteer, type UserAgentOverride } from "./launch";
+import {
+	BROWSER_PROTOCOL_TIMEOUT_MS,
+	canDecryptProfileCookies,
+	headlessExecutableForProfileReuse,
+	launchHeadlessBrowser,
+	loadPuppeteer,
+	type UserAgentOverride,
+} from "./launch";
 import { defaultDiscoveryEnv } from "./profile-discovery";
 import type { ProfileReusePosture } from "./profile-posture";
 import { resolveProfileReuse } from "./profile-reuse";
@@ -55,6 +63,17 @@ type SpawnedChromeProfileKind = Extract<BrowserKind, { kind: "chrome-profile" }>
 const browsers = new Map<string, BrowserHandle>();
 const browserOpenPromises = new Map<string, Promise<BrowserHandle>>();
 
+/**
+ * Chrome profile warm-up dirs this module created, keyed by the handle that owns one.
+ *
+ * Ownership is a registry-internal fact, not a property of the handle: `BrowserHandle`
+ * is exported and mutable, so a field would let any caller point recursive deletion at
+ * an arbitrary path. Recording the dir here — only on the launch path that created it —
+ * means disposal can delete exactly what this module made and nothing else. A path
+ * prefix check would not prove ownership; an entry in this map does.
+ */
+const ownedWarmupDirs = new WeakMap<BrowserHandle, string>();
+
 /**
  * Upper bound on the CDP `browser.close()` round-trip during a forced (signal-path)
  * teardown before we fall back to killing the Chrome process tree. Only applies when
@@ -110,6 +129,19 @@ export function browserKeyForTest(
 	return browserKey(kind, geo, opts.profileReuse);
 }
 
+/**
+ * Create and register a warm-up dir as registry-owned for `handle`.
+ *
+ * Exists so tests can exercise disposal without spawning Chrome. The caller cannot
+ * supply the deletion target: this module creates the directory itself before recording
+ * ownership, preserving the same invariant as the production launch path.
+ */
+export function createOwnedWarmupDirForTest(handle: BrowserHandle): string {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gjc-profile-warmup-"));
+	ownedWarmupDirs.set(handle, dir);
+	return dir;
+}
+
 export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
 	const geo = kind.kind === "headless" ? normalizeGeo(opts.geo) : undefined;
 	const key = browserKey(kind, geo, opts.profileReuse);
@@ -148,17 +180,38 @@ async function openBrowserHandle(
 				discoveryEnv: defaultDiscoveryEnv(fs.existsSync),
 			});
 			if (reuse.warning) logger.warn(reuse.warning);
-			if (reuse.mode === "real" && reuse.warmupDir) {
+			if (reuse.mode === "real" && reuse.warmupDir && reuse.discovered) {
+				const executablePath = headlessExecutableForProfileReuse();
+				if (!canDecryptProfileCookies(executablePath, reuse.discovered.userDataDir)) {
+					try {
+						fs.rmSync(reuse.warmupDir, { recursive: true, force: true });
+					} catch {}
+					const hint = executablePath
+						? `Real Chrome profile at ${reuse.discovered.userDataDir} cannot be decrypted by ${executablePath} on macOS (Chrome Safe Storage vs Chromium Safe Storage Keychain mismatch). Using synthetic browser state instead. Set PUPPETEER_EXECUTABLE_PATH to the matching Chrome/Chromium binary.`
+						: `Real Chrome profile at ${reuse.discovered.userDataDir} found but no compatible browser executable is available on macOS (bundled Chromium cannot decrypt Chrome's cookies — Chrome Safe Storage vs Chromium Safe Storage). Using synthetic browser state instead. Set PUPPETEER_EXECUTABLE_PATH to /Applications/Google Chrome.app/Contents/MacOS/Google Chrome or install Chrome.`;
+					logger.warn(hint);
+				} else {
+					profileWarmupDir = reuse.warmupDir;
+				}
+			} else if (reuse.mode === "real" && reuse.warmupDir) {
 				profileWarmupDir = reuse.warmupDir;
 			}
 		}
-		const browser = await launchHeadlessBrowser({
-			headless: kind.headless,
-			viewport: opts.viewport,
-			profileWarmupDir,
-			...(geo ? { geo } : {}),
-		});
-		return {
+		let browser: Browser;
+		try {
+			browser = await launchHeadlessBrowser({
+				headless: kind.headless,
+				viewport: opts.viewport,
+				profileWarmupDir,
+				...(geo ? { geo } : {}),
+			});
+		} catch (error) {
+			// Launch failed after the warm-up copy landed: drop the temp dir here,
+			// because no handle will exist to carry it into releaseBrowser().
+			removeWarmupDir(profileWarmupDir);
+			throw error;
+		}
+		const handle: BrowserHandle = {
 			key,
 
 			kind,
@@ -168,6 +221,11 @@ async function openBrowserHandle(
 			refCount: 0,
 			stealth: { browserSession: null, override: null },
 		};
+		// Record ownership only here, where this module created the dir. Disposal
+		// deletes solely what this map holds, so a caller-supplied path is never
+		// a deletion target.
+		if (profileWarmupDir) ownedWarmupDirs.set(handle, profileWarmupDir);
+		return handle;
 	}
 	if (kind.kind === "connected") {
 		const cdpUrl = kind.cdpUrl.replace(/\/+$/, "");
@@ -418,6 +476,35 @@ export async function releaseBrowser(handle: BrowserHandle, opts: { kill: boolea
 	}
 }
 
+/**
+ * Delete the warm-up dir this module created for `handle`, if any.
+ *
+ * The path comes from `ownedWarmupDirs`, never from the caller, so recursive deletion
+ * can only ever target a dir this registry made. The entry is consumed first, making a
+ * second call a no-op even if disposal runs twice.
+ *
+ * Best-effort: a leftover temp dir is preferable to a teardown that throws.
+ */
+function removeOwnedWarmupDir(handle: BrowserHandle): void {
+	const dir = ownedWarmupDirs.get(handle);
+	if (dir === undefined) return;
+	ownedWarmupDirs.delete(handle);
+	removeWarmupDir(dir);
+}
+
+/** Delete a dir this module created. Callers must have proven ownership first. */
+function removeWarmupDir(dir: string | undefined): void {
+	if (!dir) return;
+	try {
+		fs.rmSync(dir, { recursive: true, force: true });
+	} catch (err) {
+		logger.debug("Failed to remove Chrome profile warm-up dir", {
+			dir,
+			error: (err as Error).message,
+		});
+	}
+}
+
 async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean }): Promise<void> {
 	if (handle.kind.kind === "headless") {
 		// Capture the launched Chrome process before close() so a forced (signal-path)
@@ -436,6 +523,9 @@ async function disposeBrowserHandle(handle: BrowserHandle, opts: { kill: boolean
 			}
 		}
 		if (opts.kill && proc?.pid !== undefined) await gracefulKillTreeOnce(proc.pid);
+		// Chrome owns files under the warm-up dir until the process is gone, so this
+		// runs after close()/kill rather than alongside them.
+		removeOwnedWarmupDir(handle);
 		return;
 	}
 	if (handle.kind.kind === "connected") {

package/src/tools/cron.ts

@@ -453,13 +453,15 @@ function deliverCronFire(record: CronScheduleRecord): Promise<void> | undefined
 		cron_expression: record.snapshot.cron_expression,
 		recurring: record.snapshot.recurring,
 	};
-	const sendPromise = record.session.sendCustomMessage?.(
+	if (!record.session.sendCustomMessage) {
+		// The custom-message router is the only delivery path; treating its absence
+		// as a successful fire would silently retire a one-shot schedule.
+		return Promise.reject(new Error("Cron delivery requires a session custom-message router."));
+	}
+	return record.session.sendCustomMessage(
 		{ customType: "cron-fire", content, display: false, attribution: "agent", details },
 		{ triggerTurn: true, deliverAs: "followUp" },
 	);
-	if (sendPromise) return sendPromise;
-	record.session.steer?.({ customType: "cron-fire", content, details });
-	return undefined;
 }
 
 function scheduleRecord(ownerId: string | undefined, state: OwnerScheduleState, record: CronScheduleRecord): void {

package/src/tools/descriptors.test.ts

@@ -39,6 +39,7 @@ function makeSession(overrides: Record<string, unknown> = {}): any {
 		"calc.enabled": true,
 		"skill.enabled": true,
 		"browser.enabled": true,
+		"browser.backend": "native",
 		"computer.enabled": true,
 		"checkpoint.enabled": true,
 		"irc.enabled": true,
@@ -371,6 +372,20 @@ describe("tool descriptor compatibility gate", () => {
 		}
 	});
 
+	test("hides the built-in browser tool when Aside is the selected backend", () => {
+		const context = availabilityContext();
+
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": "aside" }), context)).toBe(
+			false,
+		);
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": "native" }), context)).toBe(
+			true,
+		);
+		expect(BUILTIN_TOOL_DESCRIPTORS.browser.isAvailable(makeSession({ "browser.backend": undefined }), context)).toBe(
+			true,
+		);
+	});
+
 	test("descriptor creation is side-effect free; materialization registers cleanup exactly once", () => {
 		const cleanupCalls: Array<() => void> = [];
 		let constructed = 0;

package/src/tools/descriptors.ts

@@ -1,6 +1,7 @@
 import type { AgentTool } from "@gajae-code/agent-core";
 import type { RawArgumentValidationResult, TSchema } from "@gajae-code/ai/types";
 import { $which } from "@gajae-code/utils";
+import { resolveBrowserBackend } from "../browser-backend";
 import type { ToolFactory, ToolSession } from ".";
 import { selectAskParameters } from "./ask-contract";
 import { isComputerCallable, isComputerLoadablePlatform } from "./computer-policy";
@@ -260,7 +261,10 @@ function availableFor(name: string, session: ToolSession, context = defaultAvail
 	if (name === "search_tool_bm25") return context.discoveryActive ?? resolveDiscoveryActive(session);
 	if (name === "calc") return Boolean(session.settings.get("calc.enabled"));
 	if (name === "skill" || name === "skill_discovery") return Boolean(session.settings.get("skill.enabled"));
-	if (name === "browser") return Boolean(session.settings.get("browser.enabled"));
+	if (name === "browser")
+		return (
+			Boolean(session.settings.get("browser.enabled")) && resolveBrowserBackend(session.settings).exposesBuiltinTool
+		);
 	if (name === "computer") return isComputerCallable(session);
 	if (name === "checkpoint" || name === "rewind")
 		return Boolean(session.settings.get("checkpoint.enabled")) && (session.taskDepth ?? 0) === 0;

package/src/tools/gh.ts

@@ -2806,6 +2806,14 @@ export interface PrDiffFile {
 	changeType: "modified" | "added" | "deleted" | "renamed" | "binary";
 	/** Pre-image path for renames/deletes; same as `path` otherwise. */
 	oldPath?: string;
+	/**
+	 * Set when `path` kept its C-style escaped source form because the quoted
+	 * token held invalid UTF-8 or a malformed escape; distinguishes it from a
+	 * valid path whose decoded text looks identical.
+	 */
+	pathEscaped?: boolean;
+	/** Same as {@link PrDiffFile.pathEscaped}, for `oldPath`. */
+	oldPathEscaped?: boolean;
 	/** Byte offset of the section's `diff --git` line in the unified diff. */
 	startOffset: number;
 	/** Byte offset of the next section (or end-of-text). */
@@ -2861,6 +2869,8 @@ export function parsePrUnifiedDiff(text: string): PrDiffPayload {
 interface ParsedDiffHeaderToken {
 	value: string;
 	nextIndex: number;
+	/** Set when the token kept its C-style escaped source form. */
+	escaped?: boolean;
 }
 
 function skipDiffHeaderSpaces(text: string, index: number): number {
@@ -2869,63 +2879,87 @@ function skipDiffHeaderSpaces(text: string, index: number): number {
 	return i;
 }
 
-function parseDiffQuotedEscape(text: string, slashIndex: number): ParsedDiffHeaderToken {
-	const next = text.charAt(slashIndex + 1);
-	if (next === "") return { value: "\\", nextIndex: slashIndex + 1 };
+interface ParsedDiffQuotedEscape {
+	byte: number;
+	nextIndex: number;
+}
 
-	if (next >= "0" && next <= "7") {
-		let end = slashIndex + 1;
-		while (end < text.length && end < slashIndex + 4) {
-			const digit = text.charAt(end);
-			if (digit < "0" || digit > "7") break;
-			end += 1;
-		}
-		return {
-			value: String.fromCharCode(Number.parseInt(text.slice(slashIndex + 1, end), 8)),
-			nextIndex: end,
-		};
-	}
+const DIFF_PATH_ENCODER = new TextEncoder();
+const DIFF_PATH_DECODER = new TextDecoder("utf-8", { fatal: true });
 
-	switch (next) {
-		case "a":
-			return { value: "\x07", nextIndex: slashIndex + 2 };
-		case "b":
-			return { value: "\b", nextIndex: slashIndex + 2 };
-		case "f":
-			return { value: "\f", nextIndex: slashIndex + 2 };
-		case "n":
-			return { value: "\n", nextIndex: slashIndex + 2 };
-		case "r":
-			return { value: "\r", nextIndex: slashIndex + 2 };
-		case "t":
-			return { value: "\t", nextIndex: slashIndex + 2 };
-		case "v":
-			return { value: "\v", nextIndex: slashIndex + 2 };
-		case "\\":
-		case '"':
-			return { value: next, nextIndex: slashIndex + 2 };
-		default:
-			return { value: next, nextIndex: slashIndex + 2 };
+const DIFF_NAMED_ESCAPE_BYTES: Record<string, number> = {
+	a: 0x07,
+	b: 0x08,
+	f: 0x0c,
+	n: 0x0a,
+	r: 0x0d,
+	t: 0x09,
+	v: 0x0b,
+	"\\": 0x5c,
+	'"': 0x22,
+};
+
+/**
+ * Git quotes paths C-style: its named escapes plus exactly three octal digits
+ * per byte (leading digit 0-3), so a multi-byte UTF-8 character arrives as
+ * consecutive octal escapes. Anything else is malformed for this grammar.
+ */
+function parseDiffQuotedEscape(text: string, slashIndex: number): ParsedDiffQuotedEscape | undefined {
+	const first = text.charAt(slashIndex + 1);
+	if (first >= "0" && first <= "3") {
+		const second = text.charAt(slashIndex + 2);
+		const third = text.charAt(slashIndex + 3);
+		if (second < "0" || second > "7" || third < "0" || third > "7") return undefined;
+		return { byte: Number.parseInt(text.slice(slashIndex + 1, slashIndex + 4), 8), nextIndex: slashIndex + 4 };
 	}
+	const named = DIFF_NAMED_ESCAPE_BYTES[first];
+	if (named === undefined) return undefined;
+	return { byte: named, nextIndex: slashIndex + 2 };
 }
 
+/**
+ * Escaped bytes are decoded as strict UTF-8. A token holding invalid UTF-8 or
+ * a malformed escape keeps its escaped source form, so distinct non-UTF-8
+ * byte sequences never collapse into one replacement-character path.
+ */
 function parseDiffQuotedToken(text: string, startIndex: number): ParsedDiffHeaderToken | undefined {
 	if (text.charAt(startIndex) !== '"') return undefined;
-	let value = "";
-	for (let i = startIndex + 1; i < text.length; i += 1) {
-		const ch = text.charAt(i);
-		if (ch === '"') return { value, nextIndex: i + 1 };
+	const bytes: number[] = [];
+	let malformed = false;
+	for (let i = startIndex + 1; i < text.length; ) {
+		const codePoint = text.codePointAt(i) as number;
+		const ch = String.fromCodePoint(codePoint);
+		if (ch === '"') {
+			if (!malformed) {
+				try {
+					return { value: DIFF_PATH_DECODER.decode(Uint8Array.from(bytes)), nextIndex: i + 1 };
+				} catch {}
+			}
+			return { value: text.slice(startIndex + 1, i), nextIndex: i + 1, escaped: true };
+		}
 		if (ch !== "\\") {
-			value += ch;
+			bytes.push(...DIFF_PATH_ENCODER.encode(ch));
+			i += ch.length;
 			continue;
 		}
 		const escaped = parseDiffQuotedEscape(text, i);
-		value += escaped.value;
-		i = escaped.nextIndex - 1;
+		if (escaped === undefined) {
+			malformed = true;
+			i += 2;
+			continue;
+		}
+		bytes.push(escaped.byte);
+		i = escaped.nextIndex;
 	}
 	return undefined;
 }
 
+function parseDiffPathLine(line: string, prefix: string): { value: string; escaped?: boolean } {
+	const rest = line.slice(prefix.length);
+	const token = parseDiffQuotedToken(rest, 0);
+	return token ? { value: token.value, escaped: token.escaped } : { value: rest };
+}
+
 function parseDiffHeaderToken(text: string, startIndex: number): ParsedDiffHeaderToken | undefined {
 	const start = skipDiffHeaderSpaces(text, startIndex);
 	if (start >= text.length) return undefined;
@@ -2940,7 +2974,14 @@ function stripPrDiffPathPrefix(value: string, prefix: "a/" | "b/"): string | und
 	return value.startsWith(prefix) ? value.slice(prefix.length) : undefined;
 }
 
-function parsePrDiffHeaderPaths(header: string): { oldPath?: string; newPath?: string } {
+interface PrDiffHeaderPaths {
+	oldPath?: string;
+	newPath?: string;
+	oldPathEscaped?: boolean;
+	newPathEscaped?: boolean;
+}
+
+function parsePrDiffHeaderPaths(header: string): PrDiffHeaderPaths {
 	const trail = header.slice("diff --git ".length);
 	if (trail.startsWith('"')) {
 		const oldToken = parseDiffQuotedToken(trail, 0);
@@ -2950,6 +2991,8 @@ function parsePrDiffHeaderPaths(header: string): { oldPath?: string; newPath?: s
 		return {
 			oldPath: stripPrDiffPathPrefix(oldToken.value, "a/"),
 			newPath: stripPrDiffPathPrefix(newToken.value, "b/"),
+			oldPathEscaped: oldToken.escaped,
+			newPathEscaped: newToken.escaped,
 		};
 	}
 
@@ -2980,6 +3023,8 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 	const headerPaths = parsePrDiffHeaderPaths(header);
 	let oldPath = headerPaths.oldPath;
 	let newPath = headerPaths.newPath;
+	let oldPathEscaped = headerPaths.oldPathEscaped;
+	let newPathEscaped = headerPaths.newPathEscaped;
 
 	let changeType: PrDiffFile["changeType"] = "modified";
 	let isBinary = false;
@@ -2999,11 +3044,11 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 		}
 		if (line.startsWith("rename from ")) {
 			changeType = "renamed";
-			oldPath = line.slice("rename from ".length);
+			({ value: oldPath, escaped: oldPathEscaped } = parseDiffPathLine(line, "rename from "));
 			continue;
 		}
 		if (line.startsWith("rename to ")) {
-			newPath = line.slice("rename to ".length);
+			({ value: newPath, escaped: newPathEscaped } = parseDiffPathLine(line, "rename to "));
 			continue;
 		}
 		if (line.startsWith("Binary files ") && line.endsWith(" differ")) {
@@ -3028,8 +3073,15 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 		deletions = 0;
 	}
 
-	const displayPath =
-		changeType === "deleted" ? (oldPath ?? newPath ?? "(unknown)") : (newPath ?? oldPath ?? "(unknown)");
+	const preferOld = changeType === "deleted";
+	const displayPath = preferOld ? (oldPath ?? newPath ?? "(unknown)") : (newPath ?? oldPath ?? "(unknown)");
+	const displayEscaped = preferOld
+		? oldPath !== undefined
+			? oldPathEscaped
+			: newPathEscaped
+		: newPath !== undefined
+			? newPathEscaped
+			: oldPathEscaped;
 	const file: PrDiffFile = {
 		path: displayPath,
 		additions,
@@ -3038,8 +3090,12 @@ function parsePrDiffSection(section: string, startOffset: number, endOffset: num
 		startOffset,
 		endOffset,
 	};
-	if (oldPath && oldPath !== displayPath) {
+	if (displayEscaped) {
+		file.pathEscaped = true;
+	}
+	if (oldPath && (oldPath !== displayPath || oldPathEscaped !== displayEscaped)) {
 		file.oldPath = oldPath;
+		if (oldPathEscaped) file.oldPathEscaped = true;
 	}
 	return file;
 }

package/src/tools/github-cache.ts

@@ -103,7 +103,7 @@ export function openDb(): Database | null {
 		// than running an in-place ALTER dance.
 		const userVersion = (db.prepare("PRAGMA user_version").get() as { user_version?: number } | undefined)
 			?.user_version;
-		if (userVersion !== undefined && userVersion < 3) {
+		if (userVersion !== undefined && userVersion < 4) {
 			db.run("DROP TABLE IF EXISTS github_view_cache");
 		}
 		db.run(`
@@ -120,7 +120,7 @@ export function openDb(): Database | null {
 				PRIMARY KEY (auth_key, repo, kind, number, include_comments)
 			);
 			CREATE INDEX IF NOT EXISTS idx_github_view_cache_fetched ON github_view_cache(fetched_at);
-			PRAGMA user_version = 3;
+			PRAGMA user_version = 4;
 		`);
 		protectDbFiles(dbPath);
 		cachedDb = db;

package/src/tools/index.ts

@@ -1,7 +1,7 @@
 import type { AgentTelemetryConfig, AgentTool } from "@gajae-code/agent-core";
 import type { Model, ServiceTier, ToolChoice } from "@gajae-code/ai/core";
 import { $env, logger } from "@gajae-code/utils";
-import type { AsyncJobManager } from "../async";
+import type { AsyncJobManager, FoldReason } from "../async";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
@@ -240,12 +240,14 @@ export interface ToolSession {
 	registerForegroundFoldParticipant?: (adapter: FoldAdapter) => () => void;
 	/** Whether a foreground wait is currently foldable into a background job. */
 	hasForegroundBashBackgroundRequestHandler?: () => boolean;
-	/** Request that the active foreground wait fold into a background job, if supported. */
-	requestForegroundBashBackground?: () => Promise<boolean>;
+	/** Request that a foreground wait fold into a background job, if supported. `reason` names the trigger; `adapter` targets a specific wait instead of the newest registration. */
+	requestForegroundBashBackground?: (reason?: FoldReason, adapter?: FoldAdapter) => Promise<boolean>;
+	/** Current tool interrupt policy; `finish_tools` lets the running tool finish, so a steer must not fold it. */
+	getToolInterruptPolicy?: () => "abort_tools" | "finish_tools";
 
 	/** Get the session-owned or inherited async job manager. */
 	getAsyncJobManager?: () => AsyncJobManager | undefined;
-	/** Resolves when the session queues user steering (or `signal` aborts) without consuming it; wait-style tools use this to end their observation early. */
+	/** Resolves on a steer admitted after the wait starts, or when `signal` aborts, without consuming the steer. */
 	waitForUserSteering?: (signal: AbortSignal) => Promise<void>;
 	/** Get session ID */
 	getSessionId?: () => string | null;
@@ -271,6 +273,10 @@ export interface ToolSession {
 	bashAllowedPrefixes?: string[];
 	/** Restriction policy for sessions that deliberately expose a narrow bash surface. */
 	bashRestrictionProfile?: BashRestrictionProfile;
+	/** Process-local master capability injected into direct Bash children only. */
+	getMasterBashCapability?: () => string | undefined;
+	/** Stable master lineage identity used across session switches and branches. */
+	getMasterOwnerSessionId?: () => string | undefined;
 	/** Optional per-session allowlist for tools exposed through search_tool_bm25. */
 	discoverableToolAllowedNames?: readonly string[];
 	/** Throw instead of warn when toolNames contains an unknown name. */
@@ -375,8 +381,6 @@ export interface ToolSession {
 	buildToolChoice?(toolName: string): ToolChoice | undefined;
 	/** Build a named tool-choice decision, preserving whether exact named forcing survived capability degradation. */
 	buildToolChoiceResult?(toolName: string): import("../utils/tool-choice").NamedToolChoiceResult;
-	/** Steer a hidden custom message into the conversation (e.g. a preview reminder). */
-	steer?(message: { customType: string; content: string; details?: unknown }): void;
 	/** Peek the currently in-flight tool-choice queue directive's invocation handler. Used by the `resolve` tool to dispatch to the pending action. */
 	peekQueueInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
 	/** Peek the long-lived "standing" resolve handler registered by a mode (e.g. plan mode).

package/src/tools/job.ts

@@ -3,7 +3,7 @@ import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
 import { prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
-import { type AsyncJob, AsyncJobManager, isBackgroundJobSupportEnabled, jobElapsedMs } from "../async";
+import { type AsyncJob, AsyncJobManager, type FoldReason, isBackgroundJobSupportEnabled, jobElapsedMs } from "../async";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import jobDescription from "../prompts/tools/job.md" with { type: "text" };
@@ -50,6 +50,8 @@ interface JobSnapshot {
 	status: "running" | "completed" | "failed" | "cancelled";
 	label: string;
 	durationMs: number;
+	/** Present when the job was folded out of a foreground wait. */
+	foldReason?: FoldReason;
 	resultText?: string;
 	errorText?: string;
 }
@@ -344,6 +346,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 				status: latest.status as JobSnapshot["status"],
 				label: latest.label,
 				durationMs: jobElapsedMs(latest, now),
+				...(current?.metadata?.foldReason ? { foldReason: current.metadata.foldReason } : {}),
 				...(latest.resultText ? { resultText: latest.resultText } : {}),
 				...(latest.errorText ? { errorText: latest.errorText } : {}),
 			};

package/src/tools/monitor.ts

@@ -229,19 +229,22 @@ export class MonitorTool implements AgentTool<typeof monitorSchema, MonitorToolD
 				);
 				pendingNotifications = MAX_PENDING_MONITOR_NOTIFICATIONS;
 			}
-			const sendPromise = this.session.sendCustomMessage?.(
-				{ customType: "task-notification", content, display: false, attribution: "agent", details },
-				{ triggerTurn: true, deliverAs: "followUp" },
-			);
-			if (sendPromise) {
-				void sendPromise.catch(error => {
+			if (!this.session.sendCustomMessage) {
+				logger.warn("Monitor task-notification dropped: session has no custom-message router", {
+					taskId: jobId,
+				});
+				return;
+			}
+			void this.session
+				.sendCustomMessage(
+					{ customType: "task-notification", content, display: false, attribution: "agent", details },
+					{ triggerTurn: true, deliverAs: "followUp" },
+				)
+				.catch(error => {
 					logger.warn("Monitor task-notification delivery failed", {
 						error: error instanceof Error ? error.message : String(error),
 					});
 				});
-			} else {
-				this.session.steer?.({ customType: "task-notification", content, details });
-			}
 		};
 		const schedulePersistentNotification = (line: string) => {
 			latestLine = line;