@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/tools/job.ts

@@ -7,6 +7,7 @@ import { type AsyncJob, AsyncJobManager, type FoldReason, isBackgroundJobSupport
 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" };
+import type { FoldAdapter } from "../session/fold-coordinator";
 import { lookupOwnedRegistration, unregisterOwnedRegistration } from "../session/terminal-abort";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import type { ToolSession } from "./index";
@@ -21,6 +22,7 @@ import {
 	type ToolUIColor,
 	type ToolUIStatus,
 } from "./render-utils";
+import { foldAwaitReasonLine, watchSteerForFold } from "./steer-fold";
 import { ToolError } from "./tool-errors";
 
 const jobSchema = z.object({
@@ -47,7 +49,9 @@ function parseWaitDurationMs(value: string | undefined): number {
 interface JobSnapshot {
 	id: string;
 	type: "bash" | "task";
-	status: "running" | "completed" | "failed" | "cancelled";
+	// Mirrors the manager's job statuses, including "paused": a folded subagent
+	// stays listed and resumable, so its snapshot is paused rather than terminal.
+	status: "running" | "paused" | "completed" | "failed" | "cancelled";
 	label: string;
 	durationMs: number;
 	/** Present when the job was folded out of a foreground wait. */
@@ -56,6 +60,11 @@ interface JobSnapshot {
 	errorText?: string;
 }
 
+/** Terminal statuses are the ones a consumer may treat as finished work. */
+function isTerminalJobStatus(status: JobSnapshot["status"]): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled";
+}
+
 type CancelStatus = "cancelled" | "not_found" | "already_completed" | "already_cancelled";
 
 interface CancelOutcome {
@@ -234,6 +243,73 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		const waitMs = parseWaitDurationMs(this.session.settings.get("async.pollWaitDuration"));
 		const { promise: timeoutPromise, resolve: timeoutResolve } = Promise.withResolvers<void>();
 		const timeoutHandle = setTimeout(() => timeoutResolve(), waitMs);
+		// Settled the moment ANY watched wait is released by a fold, so the await
+		// never outlives its own fold. `job-await` adapters are never implicit
+		// chord / SDK-control targets (the jobs are already in the background);
+		// only the steer watcher below folds them, explicitly. `task`/`subagent`
+		// waits are a non-goal, so task-backed jobs are watched but never folded.
+		const foldedAwait = Promise.withResolvers<void>();
+		const foldedJobs = new Map<string, FoldReason>();
+		const foldTargets: Array<{ adapter: FoldAdapter; release: (reason: FoldReason) => boolean }> = [];
+		const unregisterFoldAdapters: Array<() => void> = [];
+		const startedAt = Date.now();
+		for (const job of runningJobs) {
+			if (job.type === "task" || job.metadata?.subagent !== undefined) continue;
+			const generation = job.generation;
+			let detached = false;
+			const release = (reason: FoldReason): boolean => {
+				if (detached) return false;
+				detached = true;
+				manager.markBackgrounded(job.id, generation, reason);
+				foldedJobs.set(job.id, reason);
+				foldedAwait.resolve();
+				return true;
+			};
+			const adapter: FoldAdapter = {
+				kind: "job-await",
+				jobId: job.id,
+				jobGeneration: generation,
+				label: job.label,
+				cwdSensitive: false,
+				signal,
+				originatingTurn: false,
+				outputRef: {
+					jobId: job.id,
+					generation,
+					instruction: `Use the job tool's tail operation for ${job.id} to read this job's output.`,
+				},
+				getJob: () => {
+					const current = manager.getJob(job.id);
+					return current?.generation === generation ? current : undefined;
+				},
+				detachObserver: receipt => (release(receipt.reason) ? "resolved" : "already-settled"),
+				resolveForegroundObserver: () => (detached ? "already-settled" : "resolved"),
+			};
+			foldTargets.push({ adapter, release });
+			unregisterFoldAdapters.push(this.session.registerForegroundFoldParticipant?.(adapter) ?? (() => {}));
+		}
+		// Fold every foldable wait on one steer. A job that an earlier fold already
+		// moved still owns its receipt slot until it completes, so the coordinator
+		// refuses a second fold for it; that receipt already guarantees the wake,
+		// so this await is simply released for it. Every other job folds through
+		// the coordinator, whose `detachObserver` call releases the await with the
+		// recorded reason.
+		const stopSteerWatch =
+			foldTargets.length > 0
+				? watchSteerForFold(this.session, startedAt, async fold => {
+						await Promise.all(
+							foldTargets.map(async ({ adapter, release }) => {
+								const current = adapter.getJob();
+								if (current?.status !== "running") return;
+								if (current.metadata?.foldReason !== undefined) {
+									release("steer");
+									return;
+								}
+								await fold("steer", adapter);
+							}),
+						);
+					})
+				: () => {};
 		racePromises.push(timeoutPromise);
 
 		const watchedJobIds = runningJobs.map(job => job.id);
@@ -277,25 +353,35 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 				signal.addEventListener("abort", onAbort, { once: true });
 				racePromises.push(abortPromise);
 				try {
-					await Promise.race(racePromises);
+					await Promise.race([...racePromises, foldedAwait.promise]);
 				} finally {
 					signal.removeEventListener("abort", onAbort);
 				}
 			} else {
-				await Promise.race(racePromises);
+				await Promise.race([...racePromises, foldedAwait.promise]);
 			}
 		} finally {
+			stopSteerWatch();
+			for (const unregister of unregisterFoldAdapters) unregister();
 			manager.unwatchJobs(watchedJobIds);
 			clearTimeout(timeoutHandle);
 			if (progressTimer) clearInterval(progressTimer);
 		}
 
-		return this.#buildResult(
+		const result = this.#buildResult(
 			manager,
 			allTrackedJobs,
 			cancelOutcomes,
 			this.#readOutputTails(manager, params.tail, ownerFilter),
 		);
+		if (foldedJobs.size > 0) {
+			const existingText = result.content.find(block => block.type === "text")?.text ?? "";
+			return {
+				...result,
+				content: [{ type: "text", text: `${existingText}\n\n${foldAwaitReasonLine(foldedJobs)}`.trim() }],
+			};
+		}
+		return result;
 	}
 
 	/**
@@ -396,9 +482,7 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 		// — otherwise a scope:"owned" abort could find an empty causal set and
 		// report stopped_owned while the job remains visibly paused (review
 		// thread P2).
-		const terminalJobs = jobResults.filter(
-			j => j.status === "completed" || j.status === "failed" || j.status === "cancelled",
-		);
+		const terminalJobs = jobResults.filter(j => isTerminalJobStatus(j.status));
 		manager.acknowledgeDeliveries(terminalJobs.map(j => j.id));
 		// A terminal job whose deliveries were just acknowledged is
 		// synchronously consumed: its owned registration is settled and must
@@ -417,8 +501,11 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			if (registration) unregisterOwnedRegistration(registration);
 		}
 
-		const completed = jobResults.filter(j => j.status !== "running");
-		const running = jobResults.filter(j => j.status === "running");
+		const runningJobs = jobResults.filter(j => j.status === "running");
+		// Paused work (a folded or queued-resume subagent) and any status this build
+		// does not know are non-terminal: reporting them under ## Completed would
+		// tell consumers that resumable work finished.
+		const waitingJobs = jobResults.filter(j => !isTerminalJobStatus(j.status) && j.status !== "running");
 
 		const lines: string[] = [];
 
@@ -428,9 +515,9 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			lines.push("");
 		}
 
-		if (completed.length > 0) {
-			lines.push(`## Completed (${completed.length})\n`);
-			for (const j of completed) {
+		if (terminalJobs.length > 0) {
+			lines.push(`## Completed (${terminalJobs.length})\n`);
+			for (const j of terminalJobs) {
 				lines.push(`### ${j.id} [${j.type}] — ${j.status}`);
 				lines.push(`Label: ${j.label}`);
 				if (j.resultText) {
@@ -443,13 +530,20 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 			}
 		}
 
-		if (running.length > 0) {
-			lines.push(`## Still Running (${running.length})\n`);
-			for (const j of running) {
+		if (runningJobs.length > 0) {
+			lines.push(`## Still Running (${runningJobs.length})\n`);
+			for (const j of runningJobs) {
 				lines.push(`- \`${j.id}\` [${j.type}] — ${j.label}`);
 			}
 		}
 
+		if (waitingJobs.length > 0) {
+			lines.push(`## Waiting (${waitingJobs.length})\n`);
+			for (const j of waitingJobs) {
+				lines.push(`- \`${j.id}\` [${j.type}] — ${j.label} (${j.status})`);
+			}
+		}
+
 		if (outputTails.length > 0) {
 			lines.push("", `## Retained Output (${outputTails.length})\n`);
 			for (const tail of outputTails) {
@@ -498,6 +592,12 @@ function statusToIcon(status: JobSnapshot["status"]): ToolUIStatus {
 			return "aborted";
 		case "running":
 			return "running";
+		case "paused":
+			return "pending";
+		// Snapshot details are read back from persisted sessions, so a status this
+		// build does not know must still render instead of dropping the component.
+		default:
+			return "pending";
 	}
 }
 
@@ -511,6 +611,12 @@ function statusToColor(status: JobSnapshot["status"]): ToolUIColor {
 			return "warning";
 		case "running":
 			return "accent";
+		case "paused":
+			return "muted";
+		// Never fall through to undefined: theme.fg() throws on an undefined color
+		// and would take the whole job list render down with it.
+		default:
+			return "muted";
 	}
 }
 
@@ -554,19 +660,36 @@ export const jobToolRenderer = {
 			return new Text([header, formatEmptyMessage(fallback, uiTheme)].join("\n"), 0, 0);
 		}
 
-		const counts = { completed: 0, failed: 0, cancelled: 0, running: 0 };
-		for (const job of jobs) counts[job.status]++;
+		const counts: Record<JobSnapshot["status"], number> = {
+			running: 0,
+			paused: 0,
+			completed: 0,
+			failed: 0,
+			cancelled: 0,
+		};
+		// Snapshots are read back from persisted sessions, so a status this build
+		// does not know must stay out of the typed counts instead of becoming NaN.
+		let unknownStatusCount = 0;
+		for (const job of jobs) {
+			if (job.status in counts) counts[job.status] += 1;
+			else unknownStatusCount += 1;
+		}
 
 		const meta: string[] = [];
 		if (counts.completed > 0) meta.push(uiTheme.fg("success", `${counts.completed} done`));
 		if (counts.failed > 0) meta.push(uiTheme.fg("error", `${counts.failed} failed`));
 		if (counts.cancelled > 0) meta.push(uiTheme.fg("warning", `${counts.cancelled} cancelled`));
+		if (counts.paused > 0) meta.push(uiTheme.fg("muted", `${counts.paused} paused`));
 		if (counts.running > 0) meta.push(uiTheme.fg("accent", `${counts.running} running`));
+		if (unknownStatusCount > 0) meta.push(uiTheme.fg("muted", `${unknownStatusCount} unknown`));
 
-		const headerIcon: ToolUIStatus = counts.failed > 0 ? "warning" : counts.running > 0 ? "info" : "success";
+		// Paused and unknown-status rows are unsettled work: reporting success and a
+		// "settled" description for a resumable snapshot would contradict the rows.
+		const pendingCount = counts.running + counts.paused + unknownStatusCount;
+		const headerIcon: ToolUIStatus = counts.failed > 0 ? "warning" : pendingCount > 0 ? "info" : "success";
 		const description =
-			counts.running > 0
-				? `waiting on ${counts.running} of ${jobs.length}`
+			pendingCount > 0
+				? `waiting on ${pendingCount} of ${jobs.length}`
 				: `${jobs.length} ${jobs.length === 1 ? "job" : "jobs"} settled`;
 
 		const header = renderStatusLine(
@@ -580,15 +703,18 @@ export const jobToolRenderer = {
 			uiTheme,
 		);
 
-		// Sort: running first (so user sees what's still pending), then failed, then completed/cancelled.
+		// Sort: running first (so user sees what's still pending), then paused, then
+		// failed, then completed/cancelled.
 		const statusOrder: Record<JobSnapshot["status"], number> = {
 			running: 0,
-			failed: 1,
-			cancelled: 2,
-			completed: 3,
+			paused: 1,
+			failed: 2,
+			cancelled: 3,
+			completed: 4,
 		};
+		const statusRank = (status: JobSnapshot["status"]): number => statusOrder[status] ?? Number.MAX_SAFE_INTEGER;
 		const sortedJobs = [...jobs].sort((a, b) => {
-			const diff = statusOrder[a.status] - statusOrder[b.status];
+			const diff = statusRank(a.status) - statusRank(b.status);
 			if (diff !== 0) return diff;
 			return b.durationMs - a.durationMs;
 		});

package/src/tools/output-meta.ts

@@ -26,7 +26,7 @@ import {
 } from "../session/streaming-output";
 
 import { formatBytes, wrapBrackets } from "./render-utils";
-import { renderError } from "./tool-errors";
+import { renderError, ToolError } from "./tool-errors";
 
 /**
  * Truncation metadata for the output notice.
@@ -1130,7 +1130,20 @@ async function wrappedExecute(
 		}
 		return result;
 	} catch (e) {
-		// Re-throw with formatted message so agent-loop sets isError flag
+		// Preserve the original Error class and stack so designed tool outcomes can
+		// be classified by the agent telemetry path and genuine failures retain the
+		// frame where they actually occurred. Non-Error throws still need a stable
+		// Error envelope for the agent loop.
+		if (e instanceof ToolError) {
+			const rendered = renderError(e);
+			if (rendered !== e.message) {
+				const renderedError = new ToolError(rendered, e.context);
+				if (e.stack) renderedError.stack = e.stack;
+				throw renderedError;
+			}
+			throw e;
+		}
+		if (e instanceof Error) throw e;
 		throw new Error(renderError(e));
 	}
 }

package/src/tools/path-utils.ts

@@ -48,6 +48,18 @@ function rawSkillPrefixForName(authority: string, skillName: string): string | u
 	return undefined;
 }
 
+function splitSkillPathSel(rawPath: string, authorityEnd: number): { path: string; sel?: string } {
+	const suffix = rawPath.slice(authorityEnd);
+	const suffixQueryOrFragment = suffix.search(/[?#]/);
+	const pathnameEnd = suffixQueryOrFragment === -1 ? rawPath.length : authorityEnd + suffixQueryOrFragment;
+	const pathnameTarget = splitPathAndSel(rawPath.slice(authorityEnd, pathnameEnd));
+	if (pathnameTarget.sel === undefined) return { path: rawPath };
+	return {
+		path: `${rawPath.slice(0, authorityEnd)}${pathnameTarget.path}${rawPath.slice(pathnameEnd)}`,
+		sel: pathnameTarget.sel,
+	};
+}
+
 function tryMacOSScreenshotPath(filePath: string): string {
 	// macOS writes a narrow no-break space before AM/PM, but the model normalizes it
 	// to a plain space. The original name is not always `…PM.png`: attachment paths
@@ -177,6 +189,9 @@ export function splitInternalUrlSel(
 	const schemeMatch = rawPath.match(INTERNAL_URL_SCHEME_RE);
 	if (!schemeMatch) return { path: rawPath };
 	const scheme = schemeMatch[1].toLowerCase();
+	// `embedded://gjc/<path>` identifies a bundled file, so the selector always
+	// trails the path rather than the identifier-shaped authority.
+	if (scheme === "embedded") return splitPathAndSel(rawPath);
 	if (!INTERNAL_SCHEMES_WITH_SELECTORS[scheme]) return { path: rawPath };
 
 	const schemeEnd = schemeMatch[0].length;
@@ -185,7 +200,14 @@ export function splitInternalUrlSel(
 	const authority = rawPath.slice(schemeEnd, authorityEnd);
 	const authoritySuffix = rawPath.slice(authorityEnd);
 	const firstColon = authority.indexOf(":");
-	if (firstColon === -1) return { path: rawPath };
+	if (firstColon === -1) {
+		if (scheme === "skill") {
+			// Skill relative paths carry selectors after the authority (for example,
+			// `skill://foo/docs/reference.md:10-20`).
+			return splitSkillPathSel(rawPath, authorityEnd);
+		}
+		return { path: rawPath };
+	}
 	if (firstColon === 0) return { path: rawPath };
 
 	if (scheme === "skill") {
@@ -197,7 +219,9 @@ export function splitInternalUrlSel(
 			// Let the resolver report malformed URL encoding when no selector boundary
 			// can be established from the raw authority.
 		}
-		if (decodedAuthority !== undefined && activeSkillNames.includes(decodedAuthority)) return { path: rawPath };
+		if (decodedAuthority !== undefined && activeSkillNames.includes(decodedAuthority)) {
+			return splitSkillPathSel(rawPath, authorityEnd);
+		}
 		const rawSkillPrefix = activeSkillNames
 			.map(name => ({ name, prefix: rawSkillPrefixForName(authority, name) }))
 			.filter(item => item.prefix !== undefined)
@@ -217,7 +241,7 @@ export function splitInternalUrlSel(
 			return { path: `${rawPath.slice(0, schemeEnd + firstColon)}${authoritySuffix}`, sel: firstTail };
 		}
 		const selectorColon = authority.indexOf(":", firstColon + 1);
-		if (selectorColon === -1) return { path: rawPath };
+		if (selectorColon === -1) return splitSkillPathSel(rawPath, authorityEnd);
 		return {
 			path: `${rawPath.slice(0, schemeEnd + selectorColon)}${authoritySuffix}`,
 			sel: authority.slice(selectorColon + 1),

package/src/tools/read.ts

@@ -14,7 +14,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { getActiveSkills } from "../extensibility/skills";
 import { formatHashLine, formatHashLines, formatLineHash, HL_BODY_SEP } from "../hashline/hash";
 import { InternalUrlRouter } from "../internal-urls";
-import { parseInternalUrl } from "../internal-urls/parse";
+import { normalizeInternalUrlInput, parseInternalUrl } from "../internal-urls/parse";
 import type { InternalUrl } from "../internal-urls/types";
 import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
 import readDescription from "../prompts/tools/read.md" with { type: "text" };
@@ -2745,7 +2745,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		// off the URL and surfaced via parseSel rather than confusing handlers.
 		const internalRouter = InternalUrlRouter.instance();
 		if (internalRouter.canHandle(readPath)) {
-			const internalTarget = splitInternalUrlSel(readPath, {
+			const internalTarget = splitInternalUrlSel(normalizeInternalUrlInput(readPath), {
 				activeSkillNames: getActiveSkills().map(skill => skill.name),
 			});
 			const parsed = parseSel(internalTarget.sel);
@@ -3590,7 +3590,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			sourcePath: resource.sourcePath,
 			sourceInternal: url,
 			entityLabel: "resource",
-			ignoreResultLimits: scheme === "skill",
+			ignoreResultLimits: scheme === "skill" || scheme === "embedded",
 			immutable: resource.immutable,
 			raw,
 			truncationDirection: direction,

package/src/tools/steer-fold.ts

@@ -0,0 +1,107 @@
+import { logger } from "@gajae-code/utils";
+import type { FoldReason } from "../async/job-manager";
+import type { ToolSession } from ".";
+
+/** A short foreground wait stays in the foreground even when a steer is admitted. */
+export const STEER_FOLD_GRACE_MS = 2_000;
+
+/** Model-facing line appended to a steer-folded background-start result. */
+export function steerFoldReasonLine(jobId: string): string {
+	return `Folded into background job ${jobId} because a user steer arrived; the command keeps running with its original timeout and its result will wake a later turn.`;
+}
+
+/** Model-facing cause clause for a fold, keyed by the recorded {@link FoldReason}. */
+export function foldReasonClause(reason: FoldReason): string {
+	switch (reason) {
+		case "steer":
+			return "because a user steer arrived";
+		case "chord":
+			return "because the user pressed the fold chord";
+		case "sdk_control":
+			return "because an SDK client requested it";
+		case "timer":
+			return "because the auto-background threshold elapsed";
+	}
+}
+
+/** Model-facing line used when the `job` tool's own wait is folded; states the real trigger. */
+export function foldAwaitReasonLine(folded: ReadonlyMap<string, FoldReason>): string {
+	const jobIds = [...folded.keys()];
+	const names = jobIds.map(id => `\`${id}\``).join(", ");
+	const reasons = [...new Set(folded.values())];
+	const single = reasons.length === 1 ? reasons[0] : undefined;
+	const cause = single ? foldReasonClause(single) : "because the waits were folded";
+	const plural = jobIds.length !== 1;
+	return `Folded the job await for ${names} ${cause}; the job${plural ? "s keep" : " keeps"} running with ${plural ? "their original deadlines" : "its original deadline"}, and ${plural ? "their results" : "its result"} will wake a later turn.`;
+}
+
+type SteerFoldSession = Pick<ToolSession, "settings" | "waitForUserSteering" | "requestForegroundBashBackground">;
+
+/** The session hooks a steer fold needs, resolved once so callers never re-read and non-null-assert them. */
+interface SteerFoldHooks {
+	waitForSteer: NonNullable<ToolSession["waitForUserSteering"]>;
+	requestFold: NonNullable<ToolSession["requestForegroundBashBackground"]>;
+}
+
+/**
+ * Whether a queued user steer may fold the running foreground wait. Mirrors
+ * the loop's steer admission: `busyPromptMode=queue` never admits a steer
+ * into the busy run, so it never folds. `toolInterruptPolicy` is
+ * deliberately NOT a gate: `finish_tools` means "do not kill the batch to
+ * deliver a steer", and a fold kills nothing. It is the one way to deliver
+ * the steer now AND let the command finish, so it applies under both
+ * policies; the policy only decides what the loop does with sibling tools
+ * after the fold returns. The auto-background setting is likewise not
+ * consulted: like the chord, a steer fold is a user action.
+ *
+ * Fails closed: a session that cannot report newly admitted steering or
+ * accept a fold request is not steer-foldable.
+ */
+function steerFoldHooks(session: SteerFoldSession): SteerFoldHooks | undefined {
+	const { waitForUserSteering, requestForegroundBashBackground } = session;
+	if (!waitForUserSteering || !requestForegroundBashBackground) return undefined;
+	if (session.settings.get("busyPromptMode") !== "steer") return undefined;
+	return { waitForSteer: waitForUserSteering, requestFold: requestForegroundBashBackground };
+}
+
+/**
+ * Fold on the first user steer that ARRIVES after the wait has run for
+ * {@link STEER_FOLD_GRACE_MS} since `startedAt`. A steer already queued when
+ * the wait starts, or one that arrives inside the grace window, never folds:
+ * the wait finishes normally and that steer is consumed at the ordinary tool
+ * boundary. The watcher keeps observing so a later qualifying steer still
+ * folds, and re-checks the gate at that moment so a `busyPromptMode` change
+ * during the wait is honored. `requestFold` receives the session's resolved
+ * fold request so the caller targets its own adapter without re-reading the
+ * optional session hook.
+ * Returns a stop function; call it when the wait settles. No-op when steer
+ * folding is gated off at start.
+ */
+export function watchSteerForFold(
+	session: SteerFoldSession,
+	startedAt: number,
+	requestFold: (fold: SteerFoldHooks["requestFold"]) => Promise<unknown>,
+	jobId?: string,
+): () => void {
+	const hooks = steerFoldHooks(session);
+	if (!hooks) return () => {};
+	const watch = new AbortController();
+	const observe = async (): Promise<void> => {
+		while (!watch.signal.aborted) {
+			await hooks.waitForSteer(watch.signal);
+			if (watch.signal.aborted) return;
+			if (Date.now() - startedAt < STEER_FOLD_GRACE_MS) continue;
+			const current = steerFoldHooks(session);
+			if (!current) continue;
+			await requestFold(current.requestFold);
+			return;
+		}
+	};
+	observe().catch((error: unknown) => {
+		logger.warn("Steer-triggered fold failed", {
+			...(jobId ? { jobId } : {}),
+			error: error instanceof Error ? error.message : String(error),
+		});
+	});
+	return () => watch.abort();
+}

package/src/tools/tool-catalog.generated.ts

@@ -27,7 +27,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"read": {
 		"name": "read",
 		"label": "Read",
-		"description": "Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.\n\n<instruction>\n- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).\n- You SHOULD parallelize independent reads when exploring related files.\n- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.\n</instruction>\n\n## Parameters\n\n- `path` — required. Local path, internal URI (`agent://`, `artifact://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).\n- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: last (factory default: `last`); structural summaries and routes such as URLs, directories and converted documents default to `head`. A line-range selector still bounds the selection — this only picks which end of that selection survives the byte/line cap. SQLite row queries page via their own `limit`/`offset` and ignore it.\n## Selectors\nAppend `:<sel>` to `path`. The bare path falls back to the default mode.\n\n- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about undefined lines or undefined KiB, whichever is smaller; the configured truncation direction is last (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger 3000-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.\n- `:50` / `:50-` — read from line 50 onward.\n- `:50-200` — lines 50–200 inclusive.\n- `:50+150` — 150 lines starting at line 50.\n- `:20+1` — exactly one line.\n- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).\n- `:raw` — verbatim text; no anchors, no summary, no line prefixes.\n- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.\n- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.\n\n# Files\n\n- Reading a directory path returns a depth-limited dirent listing.\n- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:\n\n  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`\n\n  If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.\n- Structural summaries honor explicit `truncation`: `head` retains the beginning, `last` the end, and `both` both ends within the summary byte budget. Complete summary units and their original source anchors stay intact and in source order; budget omissions are marked where they occur. This does not switch to raw source. Summaries that fit are unchanged by direction.\n- Directional windows identify the retained first/last lines and the omitted range; use the `re-read <path>:1-<total>` or `:raw` hint in the footer to recover the full content.\n\n# Documents & Notebooks\n\nExtracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.\n\n# Images\n\nReading an image path returns the image itself for visual inspection by a vision-capable model.\n\n# Archives\n\nSupports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.\n\n# SQLite\n\nFor `.sqlite`, `.sqlite3`, `.db`, `.db3`:\n- `file.db` — list tables with row counts\n- `file.db:table` — schema + sample rows\n- `file.db:table:key` — single row by primary key\n- `file.db:table?limit=50&offset=100` — paginated rows\n- `file.db:table?where=status='active'&order=created:desc` — filtered rows\n- `file.db?q=SELECT …` — read-only SELECT query\n\n# URLs\n\n- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.\n- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.\n- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.\n\n# Internal URIs\n\n`agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.\n\n<critical>\n- Always include `path`; never call `read` with `{}`.\n- For line ranges, append the selector to `path`.\n- Re-issue the selector named by a summary footer before relying on elided content.\n</critical>",
+		"description": "Read files, directories, archives, SQLite databases, images, documents, internal resources, and web URLs through a single `path` string.\n\n<instruction>\n- One tool for filesystem, archives, SQLite, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), internal URIs, and web URLs (reader-mode by default).\n- You SHOULD parallelize independent reads when exploring related files.\n- You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching web content.\n</instruction>\n\n## Parameters\n\n- `path` — required. Local path, internal URI (`agent://`, `artifact://`, `rule://`, `local://`), or URL. Append `:<sel>` for line ranges, raw mode, or special modes (e.g. `src/foo.ts:50-200`, `src/foo.ts:raw`, `db.sqlite:users:42`).\n- `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: last (factory default: `last`); structural summaries and routes such as URLs, directories and converted documents default to `head`. A line-range selector still bounds the selection — this only picks which end of that selection survives the byte/line cap. SQLite row queries page via their own `limit`/`offset` and ignore it.\n## Selectors\nAppend `:<sel>` to `path`. The bare path falls back to the default mode.\n\n- _(none)_ — parseable code → structural summary (signatures kept, bodies elided); a plain text file → a bounded receipt of about undefined lines or undefined KiB, whichever is smaller; the configured truncation direction is last (factory default: last). Line+hash anchors keep their real file line numbers and a footer names the omitted range. Archive members use the larger 3000-line / 50 KiB budget. Converted documents, notebooks, URLs and directory listings still start from the beginning.\n- `:50` / `:50-` — read from line 50 onward.\n- `:50-200` — lines 50–200 inclusive.\n- `:50+150` — 150 lines starting at line 50.\n- `:20+1` — exactly one line.\n- `:5-16,960-973` — multiple ranges in one call (sorted, overlaps merged).\n- `:raw` — verbatim text; no anchors, no summary, no line prefixes.\n- `:2-4:raw` or `:raw:2-4` — range AND verbatim; the two compose in either order.\n- `:conflicts` — one-line-per-block index of every unresolved git merge conflict.\n\n# Files\n\n- Reading a directory path returns a depth-limited dirent listing.\n- Parseable code without a selector returns a **structural summary**: declarations kept, large bodies collapsed to `..` (merged brace pair) or `…` (standalone). Summarized output ends with a footer of the form:\n\n  `[NN lines across MM elided regions; read <path>:raw or a line range like <path>:1-9999 for verbatim content]`\n\n  If the elided body is what you actually need, re-issue the **exact selector the footer names**. NEVER guess what's inside `..` / `…` — those markers carry no content.\n- Structural summaries honor explicit `truncation`: `head` retains the beginning, `last` the end, and `both` both ends within the summary byte budget. Complete summary units and their original source anchors stay intact and in source order; budget omissions are marked where they occur. This does not switch to raw source. Summaries that fit are unchanged by direction.\n- Directional windows identify the retained first/last lines and the omitted range; use the `re-read <path>:1-<total>` or `:raw` hint in the footer to recover the full content.\n\n# Documents & Notebooks\n\nExtracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipynb`) are shown as editable `# %% [type] cell:N` text; edits round-trip back to the underlying JSON preserving notebook metadata. Add `:raw` to a notebook to bypass the converter and read the JSON directly.\n\n# Images\n\nReading an image path returns the image itself for visual inspection by a vision-capable model.\n\n# Archives\n\nSupports `.tar`, `.tar.gz`, `.tgz`, `.zip`. Use `archive.ext:path/inside/archive` to read a member, and append a normal selector to the inner path: `archive.zip:dir/file.ts:50-60`.\n\n# SQLite\n\nFor `.sqlite`, `.sqlite3`, `.db`, `.db3`:\n- `file.db` — list tables with row counts\n- `file.db:table` — schema + sample rows\n- `file.db:table:key` — single row by primary key\n- `file.db:table?limit=50&offset=100` — paginated rows\n- `file.db:table?where=status='active'&order=created:desc` — filtered rows\n- `file.db?q=SELECT …` — read-only SELECT query\n\n# URLs\n\n- Default reader-mode: HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs → clean text/markdown.\n- `:raw` returns untouched HTML; line selectors (`:50`, `:50-100`, `:50+150`) paginate the cached fetched output.\n- Bare `host:port` URLs collide with the selector grammar — add a trailing slash before the selector: `https://example.com/:80`.\n\n# Internal URIs\n\n`agent://<id>`, `artifact://<id>`, `rule://<name>`, and `local://<name>.md` resolve transparently and accept the same line selectors as filesystem paths. Use `artifact://<id>` to recover full output that a previous bash/eval/tool result spilled or truncated.\n\nBundled skills have no filesystem home, so the skill tool and skill discovery report them as `embedded:gjc/skills/<name>/SKILL.md`; read that identifier verbatim. Bundled skill fragments, when surfaced, likewise use `embedded:gjc/skill-fragments/...` identifiers.\n\n<critical>\n- Always include `path`; never call `read` with `{}`.\n- For line ranges, append the selector to `path`.\n- Re-issue the selector named by a summary footer before relying on elided content.\n</critical>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -89,6 +89,33 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 				"pty": {
 					"type": "boolean",
 					"description": "run in pty mode"
+				},
+				"activity": {
+					"description": "declare browser activity for the aside browser backend: repl or exec",
+					"type": "object",
+					"properties": {
+						"kind": {
+							"type": "string",
+							"const": "browser"
+						},
+						"provider": {
+							"type": "string",
+							"const": "aside"
+						},
+						"mode": {
+							"type": "string",
+							"enum": [
+								"repl",
+								"exec"
+							]
+						}
+					},
+					"required": [
+						"kind",
+						"provider",
+						"mode"
+					],
+					"additionalProperties": false
 				}
 			},
 			"required": [
@@ -2326,7 +2353,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"job": {
 		"name": "job",
 		"label": "Job",
-		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
+		"description": "Inspects, waits, or cancels async jobs.\n\nBackground job results are delivered automatically when complete. Jobs that back task subagents should be controlled via the `subagent` tool when it is available; use `job` for non-subagent jobs (async bash, monitors) and as a compatibility fallback. Running job output stays quiet by default to avoid flooding the conversation; use `tail` when you explicitly want to show/reopen retained output. Reach for this tool only when you need to inspect or intervene.\n\nIn the interactive TUI, a running foreground command can be folded into a background job by pressing the fold chord twice (default `Alt+Shift+B`, plus `Cmd+B` on macOS; remappable via `app.tool.backgroundFold`), or automatically when the user sends a steer after the command has run for at least 2 seconds (with `busyPromptMode=steer` (`toolInterruptPolicy` is not a gate)). This covers managed non-PTY bash, editor/ACP client-terminal commands, and PTY-mode commands. A folded job keeps its original deadline, is never killed or restarted by folding, and its result wakes a later turn automatically; a folded PTY continues output-only and no longer accepts input. A `job` await also folds after the same 2-second grace window when a steer arrives, returning immediately with the still-running job id(s) while those jobs keep their original deadlines and wake a later turn with their results. Job listings expose `foldReason` (`steer`, `chord`, `timer`, or `sdk_control`) beside `backgrounded` so you can tell why a job left the foreground. `task`/`subagent` waits are not foldable. Raw shell `Ctrl+Z`/`bg` is not the supported path inside GJC because it bypasses job ownership and output-routing contracts.\n\n# Operations\n\n## `list: true`\nUse to inspect what's running.\n\n## `tail: [id, …]`\nShow the retained output buffer for one or more background jobs without waiting.\n- Use this to reopen/tail a backgrounded long-running bash/tool output after folding it away.\n- Output is bounded by the manager retention window; stale cursors may report that only the retained tail is available.\n- Prefer `tail` over polling when you only need to peek at progress, so the conversation can continue without flooding the TUI.\n\n## `poll: [id, …]`\nBlock until the specified jobs finish or the wait window (~30 s, not configurable) elapses.\n- Use when you are genuinely blocked on a result and have no other work to do.\n- Returns the current snapshot when the timer elapses; running jobs remain running.\n- Completed jobs include their final output in the returned snapshot.\n\n## `cancel: [id, …]`\nStop running jobs.\n- Use when a job is stalled, hung, or no longer needed.\n- Returns immediately after cancelling.",
 		"parameters": {
 			"type": "object",
 			"properties": {

package/src/tools/tool-errors.ts

@@ -1,3 +1,5 @@
+import { markDesignedError } from "@gajae-code/utils/error-classification";
+
 /**
  * Standardized error types for tool execution.
  *
@@ -16,6 +18,7 @@ export class ToolError extends Error {
 	) {
 		super(message);
 		this.name = "ToolError";
+		markDesignedError(this);
 	}
 
 	/** Render error for LLM consumption. Override for custom formatting. */
@@ -33,6 +36,7 @@ export class ToolAbortError extends Error {
 	constructor(message: string = ToolAbortError.MESSAGE) {
 		super(message);
 		this.name = "ToolAbortError";
+		markDesignedError(this);
 	}
 }