@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/tools/subagent.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
-import { prompt } from "@gajae-code/utils";
+import { formatDuration, logger, prompt } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { type AsyncJob, AsyncJobManager, jobElapsedMs, type SubagentRecord } from "../async";
 import subagentDescription from "../prompts/tools/subagent.md" with { type: "text" };
@@ -12,6 +12,15 @@ import { ToolError } from "./tool-errors";
 
 const DEFAULT_AWAIT_TIMEOUT_MS = 30_000;
 const MAX_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
+/**
+ * Bounded cadence for await liveness: even when the rendered-state signature is
+ * stable (a running subagent emitting no new progress), the await panel re-emits
+ * so a healthy wait never looks like a hung session (issue #4465). Derived from
+ * `heartbeat_ms` so callers keep one knob, floor-bounded so a small heartbeat
+ * cannot turn liveness into transcript spam, and injected for tests.
+ */
+const AWAIT_LIVENESS_MULTIPLIER = 30;
+const AWAIT_LIVENESS_MIN_INTERVAL_MS = 15_000;
 const DEFAULT_LIST_LIMIT = 10;
 const MAX_LIST_LIMIT = 50;
 const RECEIPT_PREVIEW_WIDTH = 280;
@@ -123,6 +132,22 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 	readonly parameters = subagentSchema;
 	readonly strict = true;
 	readonly loadMode = "discoverable";
+	/**
+	 * Injected monotonic clock for await-liveness tests. Production callers leave
+	 * this undefined and the await falls back to `Date.now`; tests substitute a
+	 * virtual clock so a 15s+ liveness interval is exercised without any real
+	 * multi-minute sleep (#4465).
+	 */
+	#livenessNowMs?: () => number;
+
+	/** Test-only seam: substitute the liveness clock. Returns a restore function. */
+	withLivenessClock(nowMs: () => number): () => void {
+		const prior = this.#livenessNowMs;
+		this.#livenessNowMs = nowMs;
+		return () => {
+			this.#livenessNowMs = prior;
+		};
+	}
 
 	constructor(private readonly session: ToolSession) {
 		this.description = prompt.render(subagentDescription);
@@ -135,7 +160,16 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		onUpdate?: AgentToolUpdateCallback<SubagentToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<SubagentToolDetails>> {
-		const manager = AsyncJobManager.instance();
+		// The session's ENDPOINT-owned manager first: concurrent top-level
+		// sessions register their manager under their endpoint (sdk/session.ts),
+		// so list/pause/resume/message/cancel/await must inspect THIS session's
+		// manager — the process-global instance belongs to the last-created
+		// session, where this session's subagent records and jobs are absent
+		// or belong to a same-id subagent of another session (review thread P1).
+		const manager =
+			this.session.getAsyncJobManager?.() ??
+			AsyncJobManager.forEndpoint(this.session.getSessionId?.() ?? undefined) ??
+			AsyncJobManager.instance();
 		if (!manager) {
 			return {
 				content: [{ type: "text", text: "No subagent manager is available in this session." }],
@@ -241,7 +275,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 				records.push(record);
 				terminalGuidanceIds.add(record.subagentId);
 			} else {
-				const result = manager.resumeSubagent(record.subagentId, ownerFilter, params.message);
+				const result = manager.resumeSubagent(record.subagentId, ownerFilter, params.message, _toolCallId);
 				if (!result.ok && result.reason === "context_unavailable") throw new ToolError("context unavailable");
 				if (!result.ok && result.reason === "not_found") {
 					missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
@@ -293,7 +327,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 					records.push(manager.getSubagentRecord(record.subagentId, ownerFilter) ?? record);
 					steerStates.set(record.subagentId, "queued");
 				} else {
-					const result = manager.resumeSubagent(record.subagentId, ownerFilter, message);
+					const result = manager.resumeSubagent(record.subagentId, ownerFilter, message, _toolCallId);
 					if (!result.ok && result.reason === "not_found") {
 						missing.push(this.#missingSnapshot(id, "not_found", "No visible detached subagent matches this id."));
 					} else if (!result.ok) {
@@ -402,23 +436,71 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			});
 		}
 		const watchedJobIds = targets.map(target => target.jobId).filter((jobId): jobId is string => jobId !== null);
-		manager.watchJobs(watchedJobIds);
+		const watchHandle = manager.watchJobGenerations(watchedJobIds);
 		const heartbeatMs = params.heartbeat_ms === undefined ? 500 : params.heartbeat_ms;
+		// Liveness interval: force a re-emit even when the rendered-state signature
+		// is stable so a healthy wait never looks like a hung session (#4465). The
+		// `#livenessNowMs` clock is injected for deterministic tests; `Date.now`
+		// is the production fallback. The interval is floor-bounded so a caller who
+		// sets a tiny `heartbeat_ms` cannot turn liveness into transcript spam.
+		const livenessIntervalMs = Math.max(AWAIT_LIVENESS_MIN_INTERVAL_MS, heartbeatMs * AWAIT_LIVENESS_MULTIPLIER);
+		const nowMs = this.#livenessNowMs ?? Date.now;
+		let lastEmitMs = nowMs();
 		let lastEmittedSignature: string | undefined;
+		let streamingDisabled = false;
+		let stopProgressTimer = (): void => {};
+		const disableStreaming = (error: unknown): void => {
+			if (streamingDisabled) return;
+			streamingDisabled = true;
+			stopProgressTimer();
+			try {
+				logger.warn("Subagent await progress update failed; streaming disabled for this wait", {
+					error: safeThrownValue(error),
+				});
+			} catch {
+				// Diagnostics must never turn a recoverable progress-channel failure
+				// into an await or process-lifecycle failure.
+			}
+		};
 		const emitIfChanged = (force: boolean): void => {
-			if (!onUpdate) return;
-			const result = this.#progressResult(manager, records, true);
-			const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
-			if (!force && signature === lastEmittedSignature) return;
-			lastEmittedSignature = signature;
-			onUpdate(result);
+			if (!onUpdate || streamingDisabled) return;
+			try {
+				const result = this.#progressResult(manager, records, true);
+				const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
+				const t = nowMs();
+				const livenessDue = force || t - lastEmitMs >= livenessIntervalMs;
+				if (!livenessDue && signature === lastEmittedSignature) return;
+				lastEmittedSignature = signature;
+				lastEmitMs = t;
+				// A TypeScript void-return callback may still be implemented by an
+				// async function. Observe its runtime result so a rejected promise or
+				// thenable cannot become an unhandled rejection outside this span.
+				const updateResult = (onUpdate as (update: AgentToolResult<SubagentToolDetails>) => unknown)(result);
+				if (isPromiseLike(updateResult)) void Promise.resolve(updateResult).catch(disableStreaming);
+			} catch (error) {
+				// The liveness timer fires outside this function's promise chain, so a
+				// throwing progress consumer would otherwise escape `setInterval` as an
+				// uncaught exception, leave the wait's cleanup unreached, and let the
+				// interval keep firing and rethrowing for the rest of the await. Retire
+				// the streaming channel instead and keep waiting: losing progress output
+				// is recoverable, losing the timer and the watch registration is not.
+				disableStreaming(error);
+			}
 		};
-		const progressTimer =
-			onUpdate && heartbeatMs > 0 ? setInterval(() => emitIfChanged(false), heartbeatMs) : undefined;
-		emitIfChanged(true);
+		// The initial emission and the timer own process-lifetime resources together
+		// with the watch registration and the terminal-wait handle, so they all live
+		// inside one guarded span rather than straddling it.
+		let progressTimer: Timer | undefined;
 		let waitOutcome: "completed" | "timed_out_wait" | "interrupted";
 		let onAbort: (() => void) | undefined;
+		let terminalJobIds: string[] | undefined;
 		try {
+			progressTimer = onUpdate && heartbeatMs > 0 ? setInterval(() => emitIfChanged(false), heartbeatMs) : undefined;
+			stopProgressTimer = () => {
+				if (progressTimer) clearInterval(progressTimer);
+				progressTimer = undefined;
+			};
+			emitIfChanged(true);
 			const abortPromise = new Promise<"interrupted">(resolve => {
 				onAbort = () => resolve("interrupted");
 				if (signal?.aborted) onAbort();
@@ -432,14 +514,16 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 							Bun.sleep(timeoutMs).then(() => "timed_out_wait" as const),
 							abortPromise,
 						]);
+			if (waitOutcome === "completed") {
+				terminalJobIds = (await handle.result).terminalJobIds;
+				handle.acknowledge(terminalJobIds);
+			}
 		} finally {
 			if (signal && onAbort) signal.removeEventListener("abort", onAbort);
-			if (progressTimer) clearInterval(progressTimer);
+			stopProgressTimer();
+			watchHandle.close();
+			handle.close();
 		}
-		const waitResult = waitOutcome === "completed" ? await handle.result : undefined;
-		if (waitOutcome === "completed") handle.acknowledge(waitResult?.terminalJobIds);
-		manager.unwatchJobs(watchedJobIds);
-		handle.close();
 		const awaitOutcome: SubagentAwaitOutcome =
 			waitOutcome === "completed" ? "completed" : waitOutcome === "timed_out_wait" ? "timed_out" : "interrupted";
 		const finalRecords = this.#visibleRecordsByIds(
@@ -456,7 +540,7 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			awaitOutcome,
 			waitOutcome,
 			condition,
-			terminalIds: waitResult?.terminalJobIds,
+			terminalIds: terminalJobIds,
 		});
 	}
 
@@ -558,11 +642,10 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 		records: SubagentRecord[],
 		attachLiveProgress = false,
 	): AgentToolResult<SubagentToolDetails> {
+		const subagents = this.#recordSnapshots(manager, records, false, "receipt", new Set(), attachLiveProgress);
 		return {
-			content: [{ type: "text", text: "" }],
-			details: {
-				subagents: this.#recordSnapshots(manager, records, false, "receipt", new Set(), attachLiveProgress),
-			},
+			content: [{ type: "text", text: awaitProgressSummary(subagents) }],
+			details: { subagents },
 		};
 	}
 
@@ -810,6 +893,41 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 	}
 }
 
+/**
+ * Human-readable line for streamed `await` progress.
+ *
+ * Consumers that render structured content (ACP) previously received an empty
+ * text block here, which made `extractStructuredText` fail and the mapper fall
+ * back to serializing the whole result object as the human-readable content. A
+ * real sentence keeps the elapsed time legible there and in any log that only
+ * shows tool text.
+ */
+function awaitProgressSummary(subagents: readonly SubagentSnapshot[]): string {
+	const waiting = subagents.filter(snapshot => !isTerminalStatus(snapshot.status));
+	if (waiting.length === 0) return "";
+	// Accumulate rather than spreading into Math.max: explicit `ids` are not
+	// capped by MAX_LIST_LIMIT, so a large await would hit the argument limit.
+	let longestMs = 0;
+	for (const snapshot of waiting) if (snapshot.durationMs > longestMs) longestMs = snapshot.durationMs;
+	return `Awaiting ${waiting.length} subagent(s) for ${formatDuration(longestMs)}: ${waiting
+		.map(snapshot => snapshot.id)
+		.join(", ")}`;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	if ((typeof value !== "object" || value === null) && typeof value !== "function") return false;
+	return typeof (value as { then?: unknown }).then === "function";
+}
+
+function safeThrownValue(error: unknown): string {
+	try {
+		if (error instanceof Error) return error.message;
+		return String(error);
+	} catch {
+		return "[unprintable thrown value]";
+	}
+}
+
 function isTerminalStatus(status: SubagentStatus): boolean {
 	return status === "completed" || status === "failed" || status === "cancelled";
 }

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

@@ -58,7 +58,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"bash": {
 		"name": "bash",
 		"label": "Bash",
-		"description": "Executes bash command in shell session for terminal operations like git, bun, cargo, python.\n\n<instruction>\n- Use `cwd` to set working directory, not `cd dir && …`\n- Prefer `env: { NAME: \"…\" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`\n- Quote variable expansions like `\"$NAME\"` to preserve exact content\n- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`\n- Use `;` only when later commands should run regardless of earlier failures\n- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths\n</instruction>\n\n<critical>\n- Use bash only for terminal operations that dedicated tools do not cover.\n- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated. Recover omitted output only when the result includes an `artifact://<id>` footer or metadata reference; truncation without a reference leaves the visible output incomplete with no recoverable artifact.\n- Never redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.\n</critical>\n\n<output>\n- Returns output and exit code.\n- Truncated output is recoverable only when the result includes an `artifact://<id>` footer or metadata reference; truncation evidence without such a reference means the visible output is incomplete and no artifact is recoverable.\n- Exit codes shown on non-zero exit\n</output>\n# Output minimizer\n\n- Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.\n- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.\n- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.",
+		"description": "Executes bash command in shell session for terminal operations like git, bun, cargo, python.\n\n<instruction>\n- Use `cwd` to set working directory, not `cd dir && …`\n- Prefer `env: { NAME: \"…\" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`\n- Quote variable expansions like `\"$NAME\"` to preserve exact content\n- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`\n- Use `;` only when later commands should run regardless of earlier failures\n- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths\n</instruction>\n\n<critical>\n- Use bash only for terminal operations that dedicated tools do not cover.\n- Never pipe through `| head -n N` or `| tail -n N` — output is already truncated. Recover omitted output only when the result includes an `artifact://<id>` footer or metadata reference; truncation without a reference leaves the visible output incomplete with no recoverable artifact.\n- Never redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.\n</critical>\n\n<output>\n- Returns output and exit code.\n- Truncated output is recoverable only when the result includes an `artifact://<id>` footer or metadata reference; truncation evidence without such a reference means the visible output is incomplete and no artifact is recoverable.\n- Exit codes shown on non-zero exit\n</output>\n\n# Waiting for background work\n\n- A long blocking `sleep N` (or `sleep N && …`) emits nothing for the entire duration and is indistinguishable from a hung session. Never use it to wait for subagents or background jobs.\n- To wait for detached task subagents, use `subagent await` — it emits periodic liveness while waiting.\n- To wait for background bash jobs, use `job poll` — it reports status on each tick.\n- Short sleeps for rate-limiting or pacing (e.g. `sleep 2` between retries) are fine.\n\n# Output minimizer\n\n- Bash stdout/stderr may be rewritten before you see it: long output keeps only the last 1 KiB by default to reduce noise and input-token use. Explicit `tools.artifactTailBytes` / `tools.artifactHeadBytes` settings can set the tail budget or retain both ends. Prefer focused commands and dedicated `search`/`find` tools over producing broad output. Test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are also passed through heuristic filters that drop noise and keep failures.\n- When the local minimizer changes visible text, successful artifact storage appends a footer containing an `artifact://<id>` reference. Complete artifacts are labeled as full output; hard-capped artifacts report omitted bytes instead. If artifact allocation/storage is unavailable before a writer/save operation is attempted, truncation may have no reference or diagnostic. If an artifact writer/save operation is attempted and fails, a bounded diagnostic is emitted without inventing an artifact URI.\n- ACP/client-terminal output can arrive already truncated from the beginning. Treat any truncation notice or metadata as evidence that the visible tail is incomplete. Recover omitted output only when an `artifact://` footer or metadata reference is present; truncation evidence without a reference means the visible output is incomplete and no artifact is recoverable. Output with neither truncation evidence nor an artifact reference is the complete emitted output.",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -1073,7 +1073,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"browser": {
 		"name": "browser",
 		"label": "Browser",
-		"description": "Drives a real Chromium tab with full puppeteer access via JS execution.\n\n<instruction>\n- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL. Use this tool only when you need JS execution, authentication, or interactive actions.\n- Four actions:\n  - `open` — acquire (or reuse) a named tab. `name` defaults to `\"main\"`. Optional `url`, `viewport`, and `dialogs: \"accept\" | \"dismiss\"` (auto-handles `alert`/`confirm`/`beforeunload`). The `app` field selects the browser kind (spawned binary, saved Chrome profile, or existing CDP endpoint); omitted means headless Chromium with stealth patches.\n  - `close` — release a tab by `name`, or every tab with `all: true`. `kill: true` also terminates a spawned-app process tree.\n  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns per-step results.\n  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The return value is JSON-stringified into the tool result; `display(value)` calls accumulate text/images. Use `run` only when an `act` verb does not cover what you need.\n- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.\n- Browser kinds: no `app` launches headless Chromium; `app.path` reuses CDP or kills stale same-path processes before spawning — NEVER use it for a daily Chrome profile; use explicit `app.browser: \"chrome\"` profile mode instead. Saved-profile/CDP automation has access to that profile's cookies and authenticated accounts. Profile mode refuses a matching non-CDP Chrome instead of killing/relaunching it, and `kill: true` can terminate only a Chrome process GJC launched; `app.cdp_url` is externally owned and disconnect-only. CDP must stay on `127.0.0.1`: it grants full browser-account access.\n- Inside `run`, `tab` exposes high-level helpers (`goto`, `observe`, `id`, `click`, `type`, `fill`, `press`, `waitFor`, `screenshot`, `extract`, …); reach for `page` (raw puppeteer Page) when they don't cover it.\n- Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`.\n- Runtime diagnostics are opt-in: pass `diagnostics: true` to `open` to subscribe the tab to page `Runtime.exceptionThrown` and `console.error` events. The next successful `act`/`run` response then includes at most 20 `runtimeDiagnostics` entries plus `runtimeDiagnosticsDropped`, then drains them. Entries contain only kind, time, origin-only URL, line/column, and a built-in error class from a fixed allowlist — never path segments, query strings, messages, console arguments, values, or stacks. Output is byte-bounded and marks truncation explicitly.\n- Full reference — helpers, browser kinds, CDP/security details, and more examples — read `gjc://tools/browser.md`.\n</instruction>\n\n<critical>\n- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.\n- You MUST observe before taking a screenshot to understand page state; screenshot only when visual appearance matters.\n- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.\n- `code` runs with full Node access. Treat it as your code, not sandboxed code.\n</critical>\n\n<examples>\n# Open a tab and read structured page data\n`{\"action\":\"open\",\"name\":\"docs\",\"url\":\"https://example.com\"}`\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"observe\"}]}`\n\n# Click an observed element, then fill and submit a form\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"click\",\"id\":12},{\"verb\":\"fill\",\"selector\":\"input[name=email]\",\"value\":\"me@example.com\"},{\"verb\":\"click\",\"selector\":\"text/Continue\"}]}`\n\n# Use `run` only when `act` has no suitable verb\n`{\"action\":\"run\",\"name\":\"docs\",\"code\":\"const count = await page.locator('canvas').count(); return { count };\"}`\n</examples>\n\n<output>\n- Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.\n</output>",
+		"description": "Drives a real Chromium tab with full puppeteer access via JS execution.\n\n<instruction>\n- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL. Use this tool only when you need JS execution, authentication, or interactive actions.\n- Four actions:\n  - `open` — acquire (or reuse) a named tab. `name` defaults to `\"main\"`. Optional `url`, `viewport`, and `dialogs: \"accept\" | \"dismiss\"` (auto-handles `alert`/`confirm`/`beforeunload`). The `app` field selects the browser kind (spawned binary, saved Chrome profile, or existing CDP endpoint); omitted means headless Chromium with stealth patches.\n  - `close` — release a tab by `name`, or every tab with `all: true`. `kill: true` also terminates a spawned-app process tree.\n  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns per-step results.\n  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The return value is JSON-stringified into the tool result; `display(value)` calls accumulate text/images. Use `run` only when an `act` verb does not cover what you need.\n- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.\n- Browser kinds: no `app` launches headless Chromium; `app.path` reuses CDP or kills stale same-path processes before spawning — NEVER use it for a daily Chrome profile; use explicit `app.browser: \"chrome\"` profile mode instead. In profile mode, `path` defaults to installed Chrome/Chromium and `profile_directory` defaults to `\"Default\"`, but `user_data_dir` must name a separate non-default Chrome data directory: Chrome 136+ disables remote debugging for its default data directory. Only Chrome/Chromium executables are admitted; Edge, Brave, Vivaldi, Opera, unknown browser brands, and default Chrome data roots are rejected. Use `app.cdp_url` to attach to an already-authorized browser. Saved-profile/CDP automation has access to that profile's cookies and authenticated accounts. Profile mode refuses a matching non-CDP Chrome instead of killing/relaunching it, and `kill: true` can terminate only a Chrome process GJC launched; `app.cdp_url` is externally owned and disconnect-only. CDP must stay on `127.0.0.1`: it grants full browser-account access.\n- Inside `run`, `tab` exposes high-level helpers (`goto`, `observe`, `id`, `click`, `type`, `fill`, `press`, `waitFor`, `screenshot`, `extract`, …); reach for `page` (raw puppeteer Page) when they don't cover it.\n- Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`.\n- Runtime diagnostics are opt-in: pass `diagnostics: true` to `open` to subscribe the tab to page `Runtime.exceptionThrown` and `console.error` events. The next successful `act`/`run` response then includes at most 20 `runtimeDiagnostics` entries plus `runtimeDiagnosticsDropped`, then drains them. Entries contain only kind, time, origin-only URL, line/column, and a built-in error class from a fixed allowlist — never path segments, query strings, messages, console arguments, values, or stacks. Output is byte-bounded and marks truncation explicitly.\n- Full reference — helpers, browser kinds, CDP/security details, and more examples — read `gjc://tools/browser.md`.\n</instruction>\n\n<critical>\n- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.\n- You MUST observe before taking a screenshot to understand page state; screenshot only when visual appearance matters.\n- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.\n- `code` runs with full Node access. Treat it as your code, not sandboxed code.\n</critical>\n\n<examples>\n# Open a tab and read structured page data\n`{\"action\":\"open\",\"name\":\"docs\",\"url\":\"https://example.com\"}`\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"observe\"}]}`\n\n# Click an observed element, then fill and submit a form\n`{\"action\":\"act\",\"name\":\"docs\",\"actions\":[{\"verb\":\"click\",\"id\":12},{\"verb\":\"fill\",\"selector\":\"input[name=email]\",\"value\":\"me@example.com\"},{\"verb\":\"click\",\"selector\":\"text/Continue\"}]}`\n\n# Use `run` only when `act` has no suitable verb\n`{\"action\":\"run\",\"name\":\"docs\",\"code\":\"const count = await page.locator('canvas').count(); return { count };\"}`\n</examples>\n\n<output>\n- Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.\n</output>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -1100,7 +1100,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 					"properties": {
 						"path": {
 							"type": "string",
-							"description": "binary path to spawn"
+							"description": "binary path to spawn (default: the installed Chrome/Chromium)"
 						},
 						"cdp_url": {
 							"type": "string",
@@ -1115,11 +1115,11 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 						},
 						"user_data_dir": {
 							"type": "string",
-							"description": "Chrome user data directory containing profiles"
+							"description": "non-default Chrome user data directory containing profiles (required for Chrome 136+ CDP)"
 						},
 						"profile_directory": {
 							"type": "string",
-							"description": "Chrome profile directory name, e.g. Profile 10"
+							"description": "Chrome profile directory name, e.g. \"Profile 10\" (default \"Default\")"
 						},
 						"background": {
 							"type": "boolean",
@@ -2708,7 +2708,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"skill_discovery": {
 		"name": "skill_discovery",
 		"label": "SkillDiscovery",
-		"description": "Discover project and user runtime skills without loading full skill content.\n\n<instruction>\n- Searches only custom runtime skill locations: nearest project `.gjc/skills`; then, under the home directory, canonical `<config>/agent/skills`, configured legacy `<config>/skills`, and historical legacy `.gjc/skills`. `<config>` is the home-relative directory name from `GJC_CONFIG_DIR`, then `PI_CONFIG_DIR`, then `.gjc`; even an absolute-looking configured name is joined beneath `<home>`. Duplicate names use that exact precedence. Built-in, bundled, and internal workflow skills are intentionally excluded.\n- Returns thin metadata only: name, description, source scope, path, and use conditions when present.\n- When zero candidates are returned because discovery config is disabled (`skills.enabled`, `skills.enablePiProject`, `skills.enablePiUser`), the result carries a `notice` explaining which setting blocked the search — an empty result without a `notice` means the searched scopes genuinely contain no matching skills.\n- To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.\n</instruction>\n\nInput:\n- `query` (optional): words to match against skill name, description, source, or use conditions.\n- `source` (optional): `all`, `project`, or `user`.\n- `limit` (optional): maximum results, 1-50.",
+		"description": "Discover project and user runtime skills without loading full skill content.\n\n<instruction>\n- Searches canonical GJC skill locations in precedence order: project `.gjc/skills` (ancestors from cwd to repo root, closest first), then user locations under the home directory: canonical `<config>/agent/skills`, configured legacy `<config>/skills`, and historical legacy `.gjc/skills`. `<config>` is the home-relative directory name from `GJC_CONFIG_DIR`, then `PI_CONFIG_DIR`, then `.gjc`; even an absolute-looking configured name is joined beneath `<home>`. Project scope shadows user scope; within a scope, earlier locations above win. Bundled GJC workflow skills (`deep-interview`, `ralplan`, `team`, `ultragoal`) are always available and cannot be replaced by filesystem skills.\n- Returns thin metadata only: name, description, source scope, path, and use conditions when present.\n- Claude Code (`.claude/skills`) and Codex (`.codex/skills`) layouts are explicit import sources into `.gjc`, never invokable candidates. They are not returned as candidates; instead, each convention skill found in a trusted scope is reported in `diagnostics` with the exact copy command that enables it (copy into `.gjc/skills`), so a skill placed in a documented convention location is discoverable in a normal session without being silently loaded.\n- Discovery is on by default in a normal session. When zero candidates are returned because discovery config is disabled (`skills.enabled` master switch, or `skills.trustProjectSkills` / `skills.trustUserSkills` scope trust), the result carries a `notice` explaining which setting blocked the search — an empty result without a `notice` means the searched scopes genuinely contain no matching skills.\n- When skills were scanned but not advertised (protected-name collision with a bundled workflow skill, include/ignore/disable policy filters, invalid frontmatter, shadowing), the result carries a bounded `diagnostics` list explaining why.\n- To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.\n</instruction>\n\nInput:\n- `query` (optional): words to match against skill name, description, source, or use conditions.\n- `source` (optional): `all`, `project`, or `user`.\n- `limit` (optional): maximum results, 1-50.",
 		"parameters": {
 			"type": "object",
 			"properties": {

package/src/tools/ultragoal-ask-guard.ts

@@ -41,7 +41,11 @@ export function formatUltragoalAskBlockMessage(diagnostic: UltragoalAskBlockDiag
 	].join("\n");
 }
 
-export async function assertUltragoalAskAllowed(cwd: string, context: UltragoalAskGuardContext = {}): Promise<void> {
+export async function assertUltragoalAskAllowed(
+	cwd: string,
+	context: UltragoalAskGuardContext = {},
+	agentDir?: string,
+): Promise<void> {
 	const activeSkill = normalizedActiveSkill(context);
 	// Deep-interview and ralplan are upstream planning workflows whose core gates
 	// are `ask` calls. Scope their Ultragoal check to the current session so stale
@@ -51,7 +55,7 @@ export async function assertUltragoalAskAllowed(cwd: string, context: UltragoalA
 	const sessionId = sessionScopedAskGuardId(context, activeSkill);
 	const diagnostic = await isUltragoalAskBlocked(cwd, { sessionId });
 	if (!diagnostic.active) return;
-	const nudge = await consumeUltragoalAskNudge(cwd, sessionId);
+	const nudge = await consumeUltragoalAskNudge(cwd, sessionId, agentDir);
 	if (nudge.nudged) throw new ToolError(nudge.message);
 	throw new ToolError(formatUltragoalAskBlockMessage(diagnostic));
 }
@@ -60,6 +64,7 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 	tool: T,
 	getCwd: () => string,
 	getContext: () => UltragoalAskGuardContext = () => ({}),
+	getSessionAgentDir: () => string | undefined = () => undefined,
 ): T {
 	if (tool.name !== "ask") return tool;
 	const candidate = tool as GuardedTool;
@@ -69,7 +74,9 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 			if (prop === ULTRAGOAL_ASK_GUARD) return true;
 			if (prop !== "execute") return Reflect.get(target, prop, receiver);
 			return async (...args: unknown[]): Promise<unknown> => {
-				await assertUltragoalAskAllowed(getCwd(), getContext());
+				// The wrapper runs BEFORE AskTool.execute(): resolve the nudge
+				// budget against the SESSION profile, never the process-global one.
+				await assertUltragoalAskAllowed(getCwd(), getContext(), getSessionAgentDir());
 				return Reflect.apply(target.execute, target, args);
 			};
 		},