@gajae-code/coding-agent 0.16.4 → 0.16.6

package/src/tools/github-cache.ts

@@ -152,6 +152,26 @@ function evictExpired(db: Database, hardTtlMs: number): void {
  */
 const SWEEP_INTERVAL_MS = 60_000;
 let lastSweepAt = 0;
+const backgroundRefreshes = new Map<string, { generation: number; controller: AbortController }>();
+let backgroundRefreshGeneration = 0;
+const BACKGROUND_REFRESH_TIMEOUT_MS = 30_000;
+
+function cacheIdentityKey(
+	authKey: string,
+	repo: string,
+	kind: CacheKind,
+	number: number,
+	includeComments: boolean,
+): string {
+	return JSON.stringify([authKey, normalizeRepo(repo), kind, number, includeComments]);
+}
+
+function retireBackgroundRefresh(key: string): void {
+	const entry = backgroundRefreshes.get(key);
+	if (!entry) return;
+	entry.controller.abort();
+	backgroundRefreshes.delete(key);
+}
 
 function sweepIfDue(hardTtlMs: number): void {
 	const now = Date.now();
@@ -296,6 +316,12 @@ export function invalidate(
 	includeComments?: boolean,
 	authKey: string = DEFAULT_CACHE_AUTH_KEY,
 ): void {
+	if (includeComments === undefined) {
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, false));
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, true));
+	} else {
+		retireBackgroundRefresh(cacheIdentityKey(authKey, repo, kind, number, includeComments));
+	}
 	const db = openDb();
 	if (!db) return;
 	try {
@@ -342,6 +368,9 @@ export function resetForTests(): void {
 	cachedDb = null;
 	openAttempted = false;
 	lastSweepAt = 0;
+	for (const { controller } of backgroundRefreshes.values()) controller.abort();
+	backgroundRefreshes.clear();
+	backgroundRefreshGeneration += 1;
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -365,9 +394,10 @@ export interface CacheLookupOptions<T> {
 	 * must bypass persistent cache reads/writes.
 	 */
 	authKey?: string | null;
-	fetchFresh: () => Promise<FreshResult<T>>;
+	fetchFresh: (signal?: AbortSignal) => Promise<FreshResult<T>>;
 	settings?: Settings | undefined;
 	now?: number;
+	signal?: AbortSignal;
 }
 
 export type CacheStatus = "miss" | "fresh" | "stale" | "disabled";
@@ -448,22 +478,41 @@ function scheduleBackgroundRefresh<T>(
 	kind: CacheKind,
 	number: number,
 	includeComments: boolean,
-	fetchFresh: () => Promise<FreshResult<T>>,
+	fetchFresh: (signal?: AbortSignal) => Promise<FreshResult<T>>,
 ): void {
-	queueMicrotask(() => {
-		const promise = fetchFresh();
-		promise
-			.then(fresh => {
+	const key = cacheIdentityKey(authKey, repo, kind, number, includeComments);
+	if (backgroundRefreshes.has(key)) return;
+	const generation = backgroundRefreshGeneration;
+	const controller = new AbortController();
+	const entry = { generation, controller };
+	backgroundRefreshes.set(key, entry);
+	queueMicrotask(async () => {
+		const timeoutHandle = setTimeout(() => {
+			controller.abort(new Error("GitHub background refresh timed out"));
+			if (backgroundRefreshes.get(key) === entry) backgroundRefreshes.delete(key);
+			logger.debug("github cache: background refresh timed out", { repo, kind, number });
+		}, BACKGROUND_REFRESH_TIMEOUT_MS);
+		try {
+			const fresh = await fetchFresh(controller.signal);
+			if (
+				!controller.signal.aborted &&
+				backgroundRefreshes.get(key) === entry &&
+				backgroundRefreshGeneration === generation
+			) {
 				storeResult(authKey, repo, kind, number, includeComments, fresh, Date.now());
-			})
-			.catch(err => {
-				logger.debug("github cache: background refresh failed", {
-					err: String(err),
-					repo,
-					kind,
-					number,
-				});
+			}
+		} catch (err) {
+			controller.abort();
+			logger.debug("github cache: background refresh failed", {
+				err: String(err),
+				repo,
+				kind,
+				number,
 			});
+		} finally {
+			clearTimeout(timeoutHandle);
+			if (backgroundRefreshes.get(key) === entry) backgroundRefreshes.delete(key);
+		}
 	});
 }
 
@@ -473,9 +522,10 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 	const authKey = options.authKey === undefined ? DEFAULT_CACHE_AUTH_KEY : options.authKey;
 
 	if (!ttl.enabled || authKey === null) {
-		const fresh = await options.fetchFresh();
+		const fresh = await options.fetchFresh(options.signal);
 		return { ...fresh, status: "disabled", fetchedAt: now };
 	}
+	const cacheKey = cacheIdentityKey(authKey, options.repo, options.kind, options.number, options.includeComments);
 
 	// Enforce the *configured* hard TTL against on-disk rows. This is what
 	// makes `github.cache.hardTtlSec` a real retention cap rather than a soft
@@ -496,6 +546,7 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 			// Past hard TTL: drop the row eagerly so the on-disk exposure window
 			// is bounded even if `fetchFresh()` then fails (network down, gh
 			// auth lapse, etc.) and we never get to overwrite it.
+			retireBackgroundRefresh(cacheKey);
 			invalidate(options.repo, options.kind, options.number, options.includeComments, authKey);
 		} else if (age <= ttl.softMs) {
 			return {
@@ -524,8 +575,9 @@ export async function getOrFetchView<T>(options: CacheLookupOptions<T>): Promise
 		}
 	}
 
-	const fresh = await options.fetchFresh();
+	const fresh = await options.fetchFresh(options.signal);
 	const fetchedAt = Date.now();
+	retireBackgroundRefresh(cacheKey);
 	storeResult(authKey, options.repo, options.kind, options.number, options.includeComments, fresh, fetchedAt);
 	return { ...fresh, status: "miss", fetchedAt };
 }

package/src/tools/index.ts

@@ -203,6 +203,8 @@ export interface ToolSession {
 	 * Runtime discovery only; never threaded into capability loading.
 	 */
 	home?: string;
+	/** Resolver-owned classification for the session's selected agent directory. */
+	profileAuthority?: "default" | "custom";
 	skills?: Skill[];
 	/** Currently executing skill prompt, when this tool session is inside one. */
 	getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;

package/src/tools/job.ts

@@ -256,10 +256,21 @@ export class JobTool implements AgentTool<typeof jobSchema, JobToolDetails> {
 				},
 			});
 		};
-		const progressTimer = onUpdate ? setInterval(emitProgress, PROGRESS_INTERVAL_MS) : undefined;
-		emitProgress();
+		const { promise: progressError, reject: rejectProgress } = Promise.withResolvers<never>();
+		racePromises.push(progressError);
+		let progressTimer: Timer | undefined;
 
 		try {
+			progressTimer = onUpdate
+				? setInterval(() => {
+						try {
+							emitProgress();
+						} catch (error) {
+							rejectProgress(error);
+						}
+					}, PROGRESS_INTERVAL_MS)
+				: undefined;
+			emitProgress();
 			if (signal) {
 				const { promise: abortPromise, resolve: abortResolve } = Promise.withResolvers<void>();
 				const onAbort = () => abortResolve();

package/src/tools/read.ts

@@ -818,10 +818,22 @@ export async function streamLinesFromFile(
 					fitBytes += separatorBytes + currentLineLength;
 				} else {
 					transitionToSplit();
-					pushSplit(lineIndex, lineText, currentLineLength, currentLineDropped, capturePartialPreview());
+					pushSplit(
+						lineIndex,
+						lineText,
+						currentLineLength,
+						currentLineDropped,
+						currentLineDropped || currentLineLength > ringBudgetBytes ? capturePartialPreview() : undefined,
+					);
 				}
 			} else {
-				pushSplit(lineIndex, lineText, currentLineLength, currentLineDropped, capturePartialPreview());
+				pushSplit(
+					lineIndex,
+					lineText,
+					currentLineLength,
+					currentLineDropped,
+					currentLineDropped || currentLineLength > ringBudgetBytes ? capturePartialPreview() : undefined,
+				);
 			}
 		}
 

package/src/tools/render-utils.ts

@@ -308,6 +308,7 @@ export function formatDiagnostics(
 	// Count total diagnostics for "... X more" calculation
 	const totalParsedDiags = files.reduce((sum, [, diags]) => sum + diags.length, 0);
 	const totalDiags = totalParsedDiags + unparsed.length;
+	const willShowAllRemaining = totalDiags <= maxDiags;
 
 	// Helper to check if this is the very last item in the tree
 	const isTreeEnd = (fileIdx: number, diagIdx: number | null, unparsedIdx: number | null): boolean => {
@@ -329,9 +330,6 @@ export function formatDiagnostics(
 	for (let fi = 0; fi < files.length && diagsShown < maxDiags; fi++) {
 		const [filePath, diagnostics] = files[fi];
 		// File is "last" only if no more files AND no unparsed AND we'll show all diags AND no "... X more"
-		const remainingDiagsInFile = diagnostics.length;
-		const remainingDiagsAfter = files.slice(fi + 1).reduce((sum, [, d]) => sum + d.length, 0) + unparsed.length;
-		const willShowAllRemaining = diagsShown + remainingDiagsInFile + remainingDiagsAfter <= maxDiags;
 		const isLastFileNode = fi === files.length - 1 && unparsed.length === 0 && willShowAllRemaining;
 		const fileBranch = isLastFileNode ? theme.tree.last : theme.tree.branch;
 

package/src/tools/resource-gc.ts

@@ -106,7 +106,10 @@ const defaultDeps: ResourceGcDeps = {
 };
 
 // ── Controller state (process-global; tabs/browsers are module-global too) ──────────────────
-const activeSessions = new Map<string, { settings: Settings; cwd: () => string }>();
+const activeSessions = new Map<
+	string,
+	{ settings: Settings; cwd: () => string; memoryGuardGeneration: symbol; memoryGuardEnabled: boolean }
+>();
 const scheduler = new MemoryGuardHost({
 	run: async () => {
 		await sweepOnce(deps);
@@ -141,12 +144,26 @@ function resolveSessionSweepIntervalMs(settings: Settings): number {
 export function registerResourceGcSession(reg: ResourceGcRegistration): () => void {
 	const registeredCwd = reg.cwd;
 	const cwd = typeof registeredCwd === "function" ? registeredCwd : () => registeredCwd ?? process.cwd();
-	activeSessions.set(reg.sessionId, { settings: reg.settings, cwd });
+	const registration = {
+		settings: reg.settings,
+		cwd,
+		memoryGuardGeneration: Symbol(),
+		memoryGuardEnabled: resolveMemoryGuardPolicy(reg.settings).enabled,
+	};
+	activeSessions.set(reg.sessionId, registration);
 	const unregisterSchedule = scheduler.register({
 		ownerId: reg.sessionId,
 		intervalMs: resolveSessionSweepIntervalMs(reg.settings),
 	});
 	const unregisterSettings = reg.settings.onChanged(path => {
+		if (path === "memoryGuard.enabled") {
+			const enabled = resolveMemoryGuardPolicy(reg.settings).enabled;
+			if (enabled !== registration.memoryGuardEnabled) {
+				// Fence samples already in flight, even if the guard is re-enabled before they settle.
+				registration.memoryGuardGeneration = Symbol();
+				registration.memoryGuardEnabled = enabled;
+			}
+		}
 		if (
 			path === "memoryGuard.enabled" ||
 			path === "memoryGuard.checkIntervalMs" ||
@@ -498,8 +515,8 @@ function sweepMemoryPressureGuard(d: ResourceGcDeps): Promise<void> | undefined
 }
 async function sweepEnabledMemoryPressureGuard(d: ResourceGcDeps): Promise<void> {
 	const now = d.monotonicNow();
-	const dueSessions: Array<{ sessionId: string; policy: MemoryGuardPolicy; cwd: string }> = [];
-	for (const [sessionId, { settings, cwd: resolveCwd }] of activeSessions) {
+	const dueSessions: Array<{ sessionId: string; policy: MemoryGuardPolicy; cwd: string; generation: symbol }> = [];
+	for (const [sessionId, { settings, cwd: resolveCwd, memoryGuardGeneration }] of activeSessions) {
 		const policy = resolveMemoryGuardPolicy(settings);
 		const cwd = resolveCwd();
 		if (!policy.enabled) {
@@ -511,14 +528,15 @@ async function sweepEnabledMemoryPressureGuard(d: ResourceGcDeps): Promise<void>
 		const lastEvaluated = memoryGuardLastEvaluatedAt.get(sessionId);
 		if (lastEvaluated !== undefined && now - lastEvaluated < policy.checkIntervalMs) continue;
 		memoryGuardLastEvaluatedAt.set(sessionId, now);
-		dueSessions.push({ sessionId, policy, cwd });
+		dueSessions.push({ sessionId, policy, cwd, generation: memoryGuardGeneration });
 	}
 	if (dueSessions.length === 0) return;
 
 	const snapshot = await d.memorySnapshot();
 	let gcRequested = false;
-	const gcTelemetry: Array<{ sessionId: string } & Record<string, unknown>> = [];
-	for (const { sessionId, policy } of dueSessions) {
+	const gcTelemetry: Array<{ sessionId: string; generation: symbol } & Record<string, unknown>> = [];
+	for (const { sessionId, policy, generation } of dueSessions) {
+		if (activeSessions.get(sessionId)?.memoryGuardGeneration !== generation) continue;
 		const pressure = __selectMemoryPressureDomainForTest(snapshot, policy.policyLimitBytes);
 		const limit = resolveEffectiveMemoryLimit({
 			hardCapBytes: pressure.hardCapBytes,
@@ -548,6 +566,7 @@ async function sweepEnabledMemoryPressureGuard(d: ResourceGcDeps): Promise<void>
 				gcRequested = true;
 				gcTelemetry.push({
 					sessionId,
+					generation,
 					parentBytes: pressure.parentBytes,
 					totalUsageBytes: pressure.totalUsageBytes,
 					effectiveLimitBytes: limit.effectiveBytes,
@@ -587,7 +606,8 @@ async function sweepEnabledMemoryPressureGuard(d: ResourceGcDeps): Promise<void>
 	if (gcRequested) {
 		try {
 			d.runGc();
-			for (const { sessionId, ...telemetry } of gcTelemetry) {
+			for (const { sessionId, generation, ...telemetry } of gcTelemetry) {
+				if (activeSessions.get(sessionId)?.memoryGuardGeneration !== generation) continue;
 				memoryGuardGcActive.add(sessionId);
 				d.logWarn("Memory guard: GC threshold reached", { sessionId, ...telemetry });
 			}

package/src/tools/skill-discovery.ts

@@ -76,9 +76,14 @@ export class SkillDiscoveryTool implements AgentTool<typeof skillDiscoverySchema
 	): Promise<AgentToolResult<SkillDiscoveryToolDetails>> {
 		return untilAborted(signal, async () => {
 			const source = input.source ?? "all";
+			const agentDir =
+				this.#session.getSessionAgentDir?.() ??
+				(this.#session.home === undefined ? this.#session.settings.getAgentDir() : undefined);
 			const result = await discoverRuntimeSkills({
 				cwd: this.#session.cwd,
 				home: this.#session.home,
+				agentDir,
+				profileAuthority: this.#session.profileAuthority,
 				query: input.query,
 				source,
 				limit: input.limit,

package/src/tools/skill.ts

@@ -32,6 +32,10 @@ import { getSkillManifest } from "../gjc-runtime/workflow-manifest";
 import skillDescription from "../prompts/tools/skill.md" with { type: "text" };
 import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
 import { isCanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+import {
+	getSkillFilesystemIdentity,
+	isCanonicalGjcWorkflowSkillFilesystemAlias,
+} from "../skill-state/canonical-skills";
 import type { ToolSession } from ".";
 import { ToolError } from "./tool-errors";
 
@@ -157,6 +161,12 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 					`skill tool: "${requestedName}" is not a valid skill name. The name must be a single concrete skill (e.g. "ralplan"), not a glob or wildcard pattern. Pass one exact skill name as shown in /skill:<name>.`,
 				);
 			}
+			if (
+				isCanonicalGjcWorkflowSkillFilesystemAlias(requestedName) &&
+				getSkillFilesystemIdentity(requestedName) !== requestedName.toLowerCase()
+			) {
+				throw new ToolError(`skill tool: refusing filesystem alias for bundled workflow skill "${requestedName}"`);
+			}
 			const activeState = this.#session.getActiveSkillState?.();
 			const activeSkill = normalizeSkillName(activeState?.skill);
 			if (activeSkill && requestedName === activeSkill) {
@@ -165,6 +175,9 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 				);
 			}
 
+			const agentDir =
+				this.#session.getSessionAgentDir?.() ??
+				(this.#session.home === undefined ? this.#session.settings.getAgentDir() : undefined);
 			const skill =
 				skills.find(s => s.name === requestedName) ??
 				(await findRuntimeSkillByName(
@@ -172,6 +185,8 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 					requestedName,
 					this.#getRuntimeSkillPolicy(),
 					this.#session.home,
+					agentDir,
+					this.#session.profileAuthority,
 				));
 			if (!skill) {
 				const available = formatAvailableSkills(skills);

package/src/tools/subagent.ts

@@ -12,6 +12,7 @@ import { ToolError } from "./tool-errors";
 
 const DEFAULT_AWAIT_TIMEOUT_MS = 30_000;
 const MAX_AWAIT_TIMEOUT_MS = 60 * 60 * 1000;
+const MAX_AWAIT_HEARTBEAT_MS = 60_000;
 /**
  * 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
@@ -47,9 +48,9 @@ const subagentSchema = z.object({
 		.describe("terminal wait condition; defaults to all_terminal"),
 	heartbeat_ms: z
 		.number()
-		.refine(value => value === 0 || (Number.isInteger(value) && value >= 100 && value <= 5000))
+		.refine(value => value === 0 || (Number.isInteger(value) && value >= 100 && value <= MAX_AWAIT_HEARTBEAT_MS))
 		.optional()
-		.describe("heartbeat interval; 0 disables"),
+		.describe(`heartbeat interval in milliseconds (100-${MAX_AWAIT_HEARTBEAT_MS}); 0 disables`),
 	timeout_ms: z.number().min(0).max(MAX_AWAIT_TIMEOUT_MS).optional().describe("await timeout in milliseconds"),
 	limit: z.number().min(1).max(MAX_LIST_LIMIT).optional().describe("maximum subagents to return"),
 	verbosity: z

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

@@ -2243,7 +2243,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"subagent": {
 		"name": "subagent",
 		"label": "Subagent",
-		"description": "Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.\n\nTask launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.\n\n`verbosity` controls output size: `receipt` (default) returns status metadata plus a single ≤280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns ≤2000 characters; `full` returns ≤12000 characters and requires explicit `ids`.\n\n# Operations\n\n## `action: \"list\"`\nSnapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Optional `limit` (1–50) caps how many subagents are returned. Output is receipt-only by default; use `verbosity: \"preview\"` for a bounded preview or inspect explicit `ids` with `verbosity: \"full\"` when fuller retained text is necessary.\n\n## `action: \"inspect\"`\nInspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: \"full\"` requires explicit `ids`.\n\n## `action: \"await\"`\nWait for selected subagents by `ids`; omit `ids` to wait for current running subagents.\n- Always set `timeout_ms` when the result is not immediately required forever.\n- Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.\n- On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n- Completed results are receipt-first by default: bounded preview plus `agent://<id>` output ref when available, not full retained output.\n\n## `action: \"pause\"`\nRequest a graceful safe-boundary pause for selected subagents by `ids`.\n- Non-running subagents are a no-op and return their current status snapshot.\n- A paused subagent keeps its session context and can be resumed later.\n\n## `action: \"resume\"`\nResume one subagent by `id` (preferred) or a single-item `ids` array.\n- Optional `message` is delivered into that one resumed run.\n- Running subagents are a no-op and return their current status snapshot.\n- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.\n- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"steer\"`\nSend a non-empty `message` to one subagent by `id` (preferred) or a single-item `ids` array.\n- A running subagent receives the message through its live handle.\n- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.\n- `pause` only matters while the target is running.\n- A non-active subagent (`paused`, `queued`, or terminal) automatically resumes with the message; `pause` is ignored for that target.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"cancel\"`\nStop selected subagents by `ids`, including running, paused, or queued subagents.\n- Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.\n- Cancellation keeps the subagent session file for possible later context recovery.\n\n# Statuses\n\n- `running` — currently executing.\n- `paused` — stopped at a safe boundary with resumable context.\n- `queued` — resume requested and waiting for execution capacity.\n- `completed` — finished successfully.\n- `failed` — finished with an error.\n- `cancelled` — stopped by cancellation.\n- `not_found` — no visible subagent matches the requested id.",
+		"description": "Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.\n\nTask launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.\n\n`verbosity` controls output size: `receipt` (default) returns status metadata plus a single ≤280-character result/error preview and an `agent://<id>` output ref when available; `preview` returns ≤2000 characters; `full` returns ≤12000 characters and requires explicit `ids`.\n\n# Operations\n\n## `action: \"list\"`\nSnapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained. Optional `limit` (1–50) caps how many subagents are returned. Output is receipt-only by default; use `verbosity: \"preview\"` for a bounded preview or inspect explicit `ids` with `verbosity: \"full\"` when fuller retained text is necessary.\n\n## `action: \"inspect\"`\nInspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents return receipt-only output by default, with an `agent://<id>` ref when a verified output artifact is available. `verbosity: \"full\"` requires explicit `ids`.\n\n## `action: \"await\"`\nWait for selected subagents by `ids`; omit `ids` to wait for current running subagents.\n- Always set `timeout_ms` when the result is not immediately required forever.\n- `heartbeat_ms` accepts integer intervals from 100 to 60,000 milliseconds (for example, 10,000 for ten seconds); `0` disables heartbeat updates and omission retains the 500 ms default. Terminal completion is event-driven, not delayed until the next heartbeat.\n- Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.\n- On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.\n- Completed results are receipt-first by default: bounded preview plus `agent://<id>` output ref when available, not full retained output.\n\n## `action: \"pause\"`\nRequest a graceful safe-boundary pause for selected subagents by `ids`.\n- Non-running subagents are a no-op and return their current status snapshot.\n- A paused subagent keeps its session context and can be resumed later.\n\n## `action: \"resume\"`\nResume one subagent by `id` (preferred) or a single-item `ids` array.\n- Optional `message` is delivered into that one resumed run.\n- Running subagents are a no-op and return their current status snapshot.\n- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.\n- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"steer\"`\nSend a non-empty `message` to one subagent by `id` (preferred) or a single-item `ids` array.\n- A running subagent receives the message through its live handle.\n- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.\n- `pause` only matters while the target is running.\n- A non-active subagent (`paused`, `queued`, or terminal) automatically resumes with the message; `pause` is ignored for that target.\n- Multiple targets are rejected because one global `message` must not broadcast to several subagents.\n\n## `action: \"cancel\"`\nStop selected subagents by `ids`, including running, paused, or queued subagents.\n- Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.\n- Cancellation keeps the subagent session file for possible later context recovery.\n\n# Statuses\n\n- `running` — currently executing.\n- `paused` — stopped at a safe boundary with resumable context.\n- `queued` — resume requested and waiting for execution capacity.\n- `completed` — finished successfully.\n- `failed` — finished with an error.\n- `cancelled` — stopped by cancellation.\n- `not_found` — no visible subagent matches the requested id.",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2288,7 +2288,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 					]
 				},
 				"heartbeat_ms": {
-					"description": "heartbeat interval; 0 disables",
+					"description": "heartbeat interval in milliseconds (100-60000); 0 disables",
 					"type": "number"
 				},
 				"timeout_ms": {

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

@@ -70,9 +70,9 @@ export function guardToolForUltragoalAsk<T extends AgentTool>(
 	const candidate = tool as GuardedTool;
 	if (candidate[ULTRAGOAL_ASK_GUARD]) return tool;
 	const wrapped = new Proxy(tool, {
-		get(target, prop, receiver) {
+		get(target, prop) {
 			if (prop === ULTRAGOAL_ASK_GUARD) return true;
-			if (prop !== "execute") return Reflect.get(target, prop, receiver);
+			if (prop !== "execute") return Reflect.get(target, prop);
 			return async (...args: unknown[]): Promise<unknown> => {
 				// The wrapper runs BEFORE AskTool.execute(): resolve the nudge
 				// budget against the SESSION profile, never the process-global one.