@gajae-code/coding-agent 0.18.10 → 0.18.12

package/src/tools/subagent.ts

@@ -540,8 +540,11 @@ export class SubagentTool implements AgentTool<typeof subagentSchema, SubagentTo
 			if (!onUpdate || streamingDisabled) return;
 			try {
 				const result = this.#progressResult(manager, records, true);
-				const signature = subagentAwaitRenderedStateSignature(result.details?.subagents ?? []);
 				const t = nowMs();
+				const snapshots = result.details?.subagents ?? [];
+				const signature = this.session.settings.get("task.compactSubagentPanel")
+					? subagentCompactRenderedStateSignature(snapshots, Date.now())
+					: subagentAwaitRenderedStateSignature(snapshots);
 				const livenessDue = force || t - lastEmitMs >= livenessIntervalMs;
 				if (!livenessDue && signature === lastEmittedSignature) return;
 				lastEmittedSignature = signature;
@@ -1136,6 +1139,110 @@ export function subagentAwaitRenderedStateSignature(
 	});
 }
 
+/** A running subagent with no activity for longer than this counts as idle in the compact panel. */
+export const SUBAGENT_COMPACT_IDLE_MS = 30_000;
+
+/** Group counts behind the compact await panel's single summary line. */
+export interface SubagentGroupSummary {
+	running: number;
+	idle: number;
+	retrying: number;
+	queued: number;
+	paused: number;
+	completed: number;
+	failed: number;
+	cancelled: number;
+	/** Running subagents in provider retry, per provider; drives the degradation warning. */
+	retryingByProvider: Record<string, number>;
+}
+
+export function summarizeSubagentGroup(subagents: readonly SubagentSnapshot[], nowMs: number): SubagentGroupSummary {
+	const summary: SubagentGroupSummary = {
+		running: 0,
+		idle: 0,
+		retrying: 0,
+		queued: 0,
+		paused: 0,
+		completed: 0,
+		failed: 0,
+		cancelled: 0,
+		retryingByProvider: {},
+	};
+	for (const snapshot of subagents) {
+		switch (snapshot.status) {
+			case "running": {
+				summary.running += 1;
+				const live = snapshot.liveProgressAvailable !== false ? snapshot.progress : undefined;
+				if (live?.status === "running" && live.retryState) {
+					summary.retrying += 1;
+					const provider = live.retryState.provider ?? "provider";
+					summary.retryingByProvider[provider] = (summary.retryingByProvider[provider] ?? 0) + 1;
+				}
+				// Before its first activity a subagent has no timestamp; its elapsed job time
+				// is then the age, so one stalled from the start still turns idle.
+				const quietMs = live?.lastActivityMs !== undefined ? nowMs - live.lastActivityMs : snapshot.durationMs;
+				if (quietMs > SUBAGENT_COMPACT_IDLE_MS) summary.idle += 1;
+				break;
+			}
+			case "queued":
+				summary.queued += 1;
+				break;
+			case "paused":
+				summary.paused += 1;
+				break;
+			case "completed":
+			case "already_completed":
+				summary.completed += 1;
+				break;
+			case "failed":
+			case "not_found":
+				summary.failed += 1;
+				break;
+			case "cancelled":
+				summary.cancelled += 1;
+				break;
+		}
+	}
+	return summary;
+}
+
+/**
+ * The compact degradation row shows only the most-degraded provider, its count, and
+ * how many other providers degrade (providers with a single retrying subagent are
+ * not a degradation). Signing exactly that keeps invisible per-provider churn from
+ * re-emitting.
+ */
+function compactDegradationSignature(
+	retryingByProvider: Record<string, number>,
+): { provider: string; count: number; moreProviders: number } | null {
+	const groups = Object.entries(retryingByProvider)
+		.filter(([, count]) => count > 1)
+		.sort(([a, countA], [b, countB]) => countB - countA || a.localeCompare(b));
+	const [worst] = groups;
+	return worst ? { provider: worst[0], count: worst[1], moreProviders: groups.length - 1 } : null;
+}
+
+/**
+ * Rendered-state signature for the compact await panel. It covers only what the
+ * compact view shows (group counts and the single degradation row), so per-subagent activity that does not move
+ * a count no longer re-emits: the update rate is bounded by count transitions and
+ * the liveness interval instead of growing with the number of live subagents.
+ */
+export function subagentCompactRenderedStateSignature(
+	subagents: readonly SubagentSnapshot[],
+	nowMs: number,
+	receipt?: Pick<SubagentToolDetails, "awaitOutcome" | "interrupted">,
+): string {
+	return JSON.stringify({
+		awaitOutcome: receipt?.awaitOutcome ?? null,
+		interrupted: receipt?.interrupted === true,
+		summary: (({ retryingByProvider, ...counts }) => ({
+			...counts,
+			degradation: compactDegradationSignature(retryingByProvider),
+		}))(summarizeSubagentGroup(subagents, nowMs)),
+	});
+}
+
 function canonicalizeSnapshotForSignature(snapshot: SubagentSnapshot): unknown {
 	return {
 		id: snapshot.id,

package/src/tools/todo-write.ts

@@ -268,6 +268,14 @@ function removeTasks(phases: TodoPhase[], entry: TodoOpEntryValue, errors: strin
 	return phases;
 }
 
+/** Type of a value that was expected to be a string, with its article. */
+function describeArgument(value: unknown): string {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "object") return "an object";
+	return `a ${typeof value}`;
+}
+
 function applyEntry(phases: TodoPhase[], entry: TodoOpEntryValue, errors: string[]): TodoPhase[] {
 	switch (entry.op) {
 		case "init":
@@ -302,6 +310,16 @@ function applyEntry(phases: TodoPhase[], entry: TodoOpEntryValue, errors: string
 		case "note": {
 			const hit = resolveTaskOrError(phases, entry.task, errors);
 			if (!hit) return phases;
+			// The schema types `text`, but bridges and replays reach `execute` without
+			// raw validation, and `.replace` on a non-string body used to crash the
+			// call. Reject it with a correction instead of storing it.
+			if (entry.text !== undefined && typeof entry.text !== "string") {
+				errors.push(
+					`Note text must be a string; got ${describeArgument(entry.text)}. ` +
+						'Pass the note body as "text", for example { op: "note", task: "<task content>", text: "why" }.',
+				);
+				return phases;
+			}
 			const text = (entry.text ?? "").replace(/\s+$/u, "");
 			if (!text) {
 				errors.push("Missing text for note operation");
@@ -337,6 +355,26 @@ export function applyOpsToPhases(
 // Markdown round-trip
 // =============================================================================
 
+/**
+ * Notes are declared as `string[]`, but the array is only typed, never validated:
+ * a session persisted elsewhere or a bridged caller that reached `execute`
+ * without raw validation can hand over any element, and every render path splits
+ * each note on newlines. One non-string element used to crash the call with a
+ * minified `.split is not a function` TypeError instead of a tool result. String
+ * notes render exactly as before.
+ */
+function noteDisplayText(note: unknown): string {
+	if (typeof note === "string") return note;
+	if (note !== null && typeof note === "object") {
+		try {
+			return JSON.stringify(note) ?? "[unrenderable note]";
+		} catch {
+			return "[unrenderable note]";
+		}
+	}
+	return String(note);
+}
+
 const STATUS_TO_MARKER: Record<TodoStatus, string> = {
 	pending: " ",
 	in_progress: "/",
@@ -356,7 +394,7 @@ export function phasesToMarkdown(phases: TodoPhase[]): string {
 			if (task.notes && task.notes.length > 0) {
 				for (let j = 0; j < task.notes.length; j++) {
 					if (j > 0) out.push("  >");
-					for (const noteLine of task.notes[j].split("\n")) {
+					for (const noteLine of noteDisplayText(task.notes[j]).split("\n")) {
 						out.push(noteLine === "" ? "  >" : `  > ${noteLine}`);
 					}
 				}
@@ -504,7 +542,7 @@ function formatSummary(phases: TodoPhase[], errors: string[]): string {
 			if (task.status === "in_progress" && task.notes && task.notes.length > 0) {
 				for (let j = 0; j < task.notes.length; j++) {
 					if (j > 0) lines.push("        ---");
-					for (const noteLine of task.notes[j].split("\n")) {
+					for (const noteLine of noteDisplayText(task.notes[j]).split("\n")) {
 						lines.push(`        ${noteLine}`);
 					}
 				}
@@ -685,7 +723,7 @@ function renderNoteAttachments(phases: TodoPhase[], uiTheme: Theme): string[] {
 			lines.push(`  ${title}`);
 			for (let j = 0; j < task.notes.length; j++) {
 				if (j > 0) lines.push(`  ${bar}`);
-				for (const noteLine of task.notes[j].split("\n")) {
+				for (const noteLine of noteDisplayText(task.notes[j]).split("\n")) {
 					lines.push(`  ${bar} ${uiTheme.fg("dim", noteLine)}`);
 				}
 			}

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 50 lines or 10 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>",
+		"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 50 lines or 10 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": {
@@ -407,7 +407,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"debug": {
 		"name": "debug",
 		"label": "Debug",
-		"description": "Provides debugger access through the Debug Adapter Protocol (DAP).\nUse for launching or attaching debuggers, setting breakpoints, stepping through execution, inspecting threads/stack/variables, evaluating expressions, capturing output, and interrupting hung programs.\n\n<instruction>\n- Prefer over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.\n- `action: \"launch\"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).\n  For Python, set `adapter: \"debugpy\"` and `program` to the target `.py` file; put interpreter/script flags in `args`.\n- `action: \"attach\"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.\n- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.\n- **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).\n- **Inspect**: `threads` (list), `stack_trace` (frames for current stopped thread), `scopes` (needs `frame_id` or a current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: \"repl\"` for raw debugger commands when the adapter supports them), `output` (captured stdout/stderr/console), `sessions` (tracked debug sessions), `terminate`.\n- Timeouts apply per-request, not to the full session lifetime.\n</instruction>\n\n<caution>\n- Only one active debug session is supported at a time.\n- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.\n- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.\n- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.\n</caution>\n\n<examples>\n# Launch and inspect hang\n1. `debug(action: \"launch\", program: \"./my_app\")`\n2. `debug(action: \"set_breakpoint\", file: \"src/main.c\", line: 42)`\n3. `debug(action: \"continue\")`\n4. If the program appears hung: `debug(action: \"pause\")`\n5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`\n# Launch a Python script with debugpy\n`debug(action: \"launch\", adapter: \"debugpy\", program: \"scripts/job.py\", args: [\"--flag\"])`\n# Raw debugger command through repl\n`debug(action: \"evaluate\", expression: \"info registers\", context: \"repl\")`\n</examples>",
+		"description": "Provides debugger access through the Debug Adapter Protocol (DAP).\nUse for launching or attaching debuggers, setting breakpoints, stepping through execution, inspecting threads/stack/variables, evaluating expressions, capturing output, and interrupting hung programs.\n\n<instruction>\n- Prefer over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.\n- `action: \"launch\"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).\n  For Python, set `adapter: \"debugpy\"` and `program` to the target `.py` file; put interpreter/script flags in `args`.\n- `action: \"attach\"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.\n- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.\n- **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).\n- **Inspect**: `threads` (list), `stack_trace` (frames for current stopped thread), `scopes` (needs `frame_id` or a current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: \"repl\"` for raw debugger commands when the adapter supports them), `output` (captured stdout/stderr/console), `sessions` (tracked debug sessions), `terminate`.\n- Timeouts apply per-request, not to the full session lifetime.\n</instruction>\n\n<caution>\n- Only one active debug session is supported at a time.\n- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.\n- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -I -m debugpy.adapter`, `dlv dap`.\n- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.\n</caution>\n\n<examples>\n# Launch and inspect hang\n1. `debug(action: \"launch\", program: \"./my_app\")`\n2. `debug(action: \"set_breakpoint\", file: \"src/main.c\", line: 42)`\n3. `debug(action: \"continue\")`\n4. If the program appears hung: `debug(action: \"pause\")`\n5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`\n# Launch a Python script with debugpy\n`debug(action: \"launch\", adapter: \"debugpy\", program: \"scripts/job.py\", args: [\"--flag\"])`\n# Raw debugger command through repl\n`debug(action: \"evaluate\", expression: \"info registers\", context: \"repl\")`\n</examples>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2096,7 +2096,7 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 	"task": {
 		"name": "task",
 		"label": "Task",
-		"description": "Launches subagents to parallelize workflows.\n\n- Results are delivered automatically when complete.\n- The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.\n- Coordinate with running tasks via `irc` when available, using those ids. `subagent` cancel terminates a task and **cannot carry a message**.\n- Use `subagent` action `inspect` or `list` to snapshot manager state.\n- To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.\n\nSubagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in `context` or `assignment`.\nUse `irc` for live coordination when it is available.\n\n<parameters>\n- `agent`: agent type for all tasks\n- `tasks`: tasks to execute in parallel\n - `.id`: filesystem-safe, ≤48 chars, matching `[A-Za-z0-9][A-Za-z0-9_-]*`; prefer CamelCase\n - `.description`: UI label only — subagent never sees it\n - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED\n- `context`: shared background prepended to every assignment; session-specific only\n- `.inheritContext` (optional): fork-context mode for seeding the subagent with sanitized parent conversation. Omit it or set `\"none\"` for no copied context. `\"receipt\"` copies a minimal receipt-sized snapshot, `\"last-turn\"` copies only the latest exchange, `\"bounded\"` copies the bounded default snapshot, and `\"full\"` copies a larger snapshot up to the configured/model token cap. Non-`none` modes work only when global `task.forkContext.enabled` is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use inherited context only when the subagent's value depends on parent context; cloned tokens are billed to the child as fresh input and surfaced in task receipts as fork-context cloned-token accounting.\n\n- `schema`: JTD schema for expected structured output (do not put format rules in assignments)\n- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.\n\n- `repositoryBinding`: optional authoritative repository/worktree identity. It must match the active session and cannot authorize a foreign repository from this session. For another approved repository, start a fresh session rooted there (for example, `gjc --cwd <approved-worktree>`); do not use `/move` because materialized tasks retain their original binding.\n</parameters>\n\n<rules>\n- HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.\n- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.\n- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.\n- Each task: ≤3–5 explicit files. No globs, no \"update all\", no package-wide scope. Use `irc` to coordinate overlapping work when it is available; otherwise keep file sets independent.\n- Pass large payloads via `local://<path>` URIs, not inline.\n- Put shared constraints in `context` once; do not duplicate across assignments.\n- Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.\n</rules>\n\n<parallelization>\nTest: can task B run correctly without seeing A's output? If no, sequence A → B, unless `irc` is available and A can answer a small clarification.\nStill sequence when one task produces a large, evolving contract (generated types, schema migration, core module API); live coordination is not a substitute for a finished contract.\nParallel when tasks touch disjoint files, are independent refactors/tests, or need only occasional peer clarification.\n</parallelization>\n\n<context-fmt>\n# Goal         ← one sentence: what the batch accomplishes\n# Constraints  ← MUST/NEVER rules and session decisions\n# Contract     ← exact types/signatures if tasks share an interface\n</context-fmt>\n\n<assignment-fmt>\n# Target       ← exact files and symbols; explicit non-goals\n# Change       ← step-by-step add/remove/rename; APIs and patterns\n# Acceptance   ← observable result; no project-wide commands\n</assignment-fmt>\n\n<agents>\nBundled role names: executor, architect, planner, critic. A configured agent may override a bundled role name and takes precedence.\nOther configured agents (project, user, plugin) may also be available; calling with an unknown `agent` lists the agents callable in this session.\n</agents>",
+		"description": "Launches subagents to parallelize workflows.\n\n- Results are delivered automatically when complete.\n- The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.\n- Coordinate with running tasks via `irc` when available, using those ids. `subagent` cancel terminates a task and **cannot carry a message**.\n- Use `subagent` action `inspect` or `list` to snapshot manager state.\n- To wait or cancel, use the `subagent` tool; its await/cancel doctrine is authoritative.\n\nSubagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in `context` or `assignment`.\nUse `irc` for live coordination when it is available.\n\n<parameters>\n- `agent`: agent type for all tasks\n- `tasks`: tasks to execute in parallel\n - `.id`: filesystem-safe, ≤48 chars, matching `[A-Za-z0-9][A-Za-z0-9_-]*`; prefer CamelCase\n - `.description`: UI label only — subagent never sees it\n - `.assignment`: complete self-contained instructions; one-liners and missing acceptance criteria are PROHIBITED\n- `context`: shared background prepended to every assignment; session-specific only\n- `.inheritContext` (optional): fork-context mode for seeding the subagent with sanitized parent conversation. Omit it or set `\"none\"` for no copied context. `\"receipt\"` copies a minimal receipt-sized snapshot, `\"last-turn\"` copies only the latest exchange, `\"bounded\"` copies the bounded default snapshot, and `\"full\"` copies a larger snapshot up to the configured/model token cap. Non-`none` modes work only when global `task.forkContext.enabled` is true and the target agent declares `forkContext: allowed`; otherwise the call is rejected. Bundled agents that support it: `executor`, `architect`. Use inherited context only when the subagent's value depends on parent context; cloned tokens are billed to the child as fresh input and surfaced in task receipts as fork-context cloned-token accounting.\n\n- `schema`: JTD schema for expected structured output (do not put format rules in assignments)\n- `spawnPlan` (optional): required before any batch with more than 4 tasks; include whyParallel, whyNotLocal, independence, expectedReceiptShape, and maxInlineTokens.\n\n- `repositoryBinding`: optional authoritative repository/worktree identity. It must match the session's committed cwd and cannot itself authorize relocation. After an authorized session move, new work uses the committed target; already-admitted work retains its source execution inputs. Verified storage relocation of that same parent does not change child execution cwd; a logical session switch does not substitute successor storage. For another approved repository, start a fresh session rooted there (for example, `gjc --cwd <approved-worktree>`) or use the existing user-authorized relocation surface; `move_session` still only narrows to a descendant directory.\n</parameters>\n\n<rules>\n- HARD runtime gate: calls with more than 4 tasks are rejected before any child launches unless `spawnPlan` is complete.\n- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.\n- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.\n- Each task: ≤3–5 explicit files. No globs, no \"update all\", no package-wide scope. Use `irc` to coordinate overlapping work when it is available; otherwise keep file sets independent.\n- Pass large payloads via `local://<path>` URIs, not inline.\n- Put shared constraints in `context` once; do not duplicate across assignments.\n- Prefer agents that investigate **and** edit in one pass; only spin a read-only discovery step when affected files are genuinely unknown.\n</rules>\n\n<parallelization>\nTest: can task B run correctly without seeing A's output? If no, sequence A → B, unless `irc` is available and A can answer a small clarification.\nStill sequence when one task produces a large, evolving contract (generated types, schema migration, core module API); live coordination is not a substitute for a finished contract.\nParallel when tasks touch disjoint files, are independent refactors/tests, or need only occasional peer clarification.\n</parallelization>\n\n<context-fmt>\n# Goal         ← one sentence: what the batch accomplishes\n# Constraints  ← MUST/NEVER rules and session decisions\n# Contract     ← exact types/signatures if tasks share an interface\n</context-fmt>\n\n<assignment-fmt>\n# Target       ← exact files and symbols; explicit non-goals\n# Change       ← step-by-step add/remove/rename; APIs and patterns\n# Acceptance   ← observable result; no project-wide commands\n</assignment-fmt>\n\n<agents>\nBundled role names: executor, architect, planner, critic. A configured agent may override a bundled role name and takes precedence.\nOther configured agents (project, user, plugin) may also be available; calling with an unknown `agent` lists the agents callable in this session.\n</agents>",
 		"parameters": {
 			"type": "object",
 			"properties": {
@@ -2955,6 +2955,34 @@ export const TOOL_CATALOG: Readonly<Record<string, ToolCatalogEntry>> = {
 		"concurrency": "exclusive",
 		"intent": "omit"
 	},
+	"report_issue": {
+		"name": "report_issue",
+		"label": "Report Issue",
+		"description": "Records a tool that behaved inconsistently with its own description, for local quality tracking.\n\n<instruction>\n- Call this when a tool's output contradicts what its description or parameters promise: ignored or misapplied parameters, wrong or truncated results, misleading errors, silent no-ops.\n- `tool` is the misbehaving tool's name; `report` states what you called, what you expected, and what actually happened, in one or two sentences.\n- Do not report your own mistakes, user-caused failures, or expected errors (missing files, failing tests, network outages).\n- Do not paste secrets, tokens, credentials, or raw tool output into report; summarize it instead.\n- False positives are acceptable. Report once per distinct problem, then continue the task; this never fixes or retries anything.\n</instruction>\n\n<output>\nConfirms whether the report was recorded. Reports stay on this machine.\n</output>",
+		"parameters": {
+			"type": "object",
+			"properties": {
+				"tool": {
+					"type": "string",
+					"description": "name of the tool that misbehaved"
+				},
+				"report": {
+					"type": "string",
+					"description": "what was called, what was expected, what happened"
+				}
+			},
+			"required": [
+				"tool",
+				"report"
+			],
+			"additionalProperties": false
+		},
+		"strict": true,
+		"deferrable": false,
+		"loadMode": "essential",
+		"summary": "Record a tool that behaved inconsistently with its description",
+		"intent": "omit"
+	},
 	"yield": {
 		"name": "yield",
 		"label": "Submit Result",

package/src/tools/write.ts

@@ -3,7 +3,7 @@ import * as fs from "node:fs/promises";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import type { Component } from "@gajae-code/tui";
 import { Text } from "@gajae-code/tui";
-import { isEnoent, isRecord, prompt, untilAborted } from "@gajae-code/utils";
+import { isEnoent, isRecord, pathIsWithin, prompt, untilAborted } from "@gajae-code/utils";
 import * as z from "zod/v4";
 import { stripHashlinePrefixes } from "../edit";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -177,6 +177,31 @@ function parseSqliteWriteTarget(subPath: string, queryString: string): { table:
 	return { table, key };
 }
 
+/**
+ * `new Database` follows symlinks. A lexical path inside the workspace can
+ * still name a file outside it, so open only the real path that stays inside
+ * the same session workspace an ordinary write resolves against.
+ */
+async function realSqliteDatabaseInWorkspace(
+	workspaceRoot: string,
+	absolutePath: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	signal?.throwIfAborted();
+	let realPath: string;
+	try {
+		realPath = await fs.realpath(absolutePath);
+	} catch (error) {
+		if (isEnoent(error)) throw error;
+		throw new ToolError(error instanceof Error ? error.message : String(error));
+	}
+	signal?.throwIfAborted();
+	if (!pathIsWithin(workspaceRoot, realPath)) {
+		throw new ToolError(`SQLite write target resolves outside the workspace: ${absolutePath}`);
+	}
+	return realPath;
+}
+
 /**
  * Write tool implementation.
  *
@@ -372,6 +397,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 		displayPath: string,
 		content: string,
 		resolvedSqlitePath: ResolvedSqliteWritePath,
+		signal?: AbortSignal,
 	): Promise<AgentToolResult<WriteToolDetails>> {
 		let db: Database | null = null;
 		try {
@@ -379,7 +405,13 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 				throw new ToolError(`SQLite database '${displayPath}' not found`);
 			}
 
-			db = new Database(resolvedSqlitePath.absolutePath, { create: false, strict: true });
+			const realDatabasePath = await realSqliteDatabaseInWorkspace(
+				this.session.cwd,
+				resolvedSqlitePath.absolutePath,
+				signal,
+			);
+			signal?.throwIfAborted();
+			db = new Database(realDatabasePath, { create: false, strict: true });
 			db.run("PRAGMA busy_timeout = 3000");
 
 			const trimmedContent = content.trim();
@@ -718,7 +750,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			if (resolvedSqlitePath) {
 				enforcePlanModeWrite(this.session, resolvedSqlitePath.sqlitePath, { op: "update" });
 
-				const sqliteResult = await this.#writeSqliteRow(path, cleanContent, resolvedSqlitePath);
+				const sqliteResult = await this.#writeSqliteRow(path, cleanContent, resolvedSqlitePath, signal);
 				if (stripped) {
 					const firstText = sqliteResult.content.find(
 						(block): block is { type: "text"; text: string } =>

package/src/utils/commit-message-generator.ts

@@ -5,7 +5,8 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, Model } from "@gajae-code/ai/core";
 import { completeSimple } from "@gajae-code/ai/core";
-import { logger, prompt } from "@gajae-code/utils";
+import { logger, prompt, redactCrashSecrets } from "@gajae-code/utils";
+import { redactChangelogEntry } from "../commit/changelog";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveModelRoleValue } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -35,6 +36,11 @@ function filterDiffNoise(diff: string): string {
 	return filtered.join("\n");
 }
 
+/** Keep changelog patterns, then scrub known credential shapes on the whole string. */
+function redactCommitMessageText(text: string): string {
+	return redactCrashSecrets(redactChangelogEntry(text));
+}
+
 function getModelCandidates(
 	registry: ModelRegistry,
 	settings: Settings,
@@ -87,7 +93,7 @@ export async function generateCommitMessage(
 		logger.debug("commit-msg-generator: diff is empty after noise filtering");
 		return null;
 	}
-	const userMessage = `<diff>\n${truncatedDiff}\n</diff>`;
+	const userMessage = `<diff>\n${redactCommitMessageText(truncatedDiff)}\n</diff>`;
 
 	for (const candidate of candidates) {
 		const apiKey = await registry.getApiKey(candidate.model, sessionId);
@@ -120,6 +126,7 @@ export async function generateCommitMessage(
 
 			// Clean up: remove wrapping quotes, backticks, trailing period
 			msg = msg.replace(/^[`"']|[`"']$/g, "").replace(/\.$/, "");
+			msg = redactCommitMessageText(msg);
 
 			logger.debug("commit-msg-generator: generated", { model: candidate.model.id, msg });
 			return msg;

package/src/utils/file-mentions.ts

@@ -80,6 +80,7 @@ type MentionCandidate = {
 	path: string;
 	pathLower: string;
 	normalizedPath: string;
+	segments: string[];
 };
 
 function normalizeMentionQuery(query: string): string {
@@ -117,11 +118,37 @@ async function listMentionCandidates(cwd: string): Promise<MentionCandidate[]> {
 		if (normalizedPath.length === 0) {
 			continue;
 		}
-		candidates.push({ path: entry, pathLower, normalizedPath });
+		const segments = pathLower.split(PATH_SEPARATOR_REGEX).filter(segment => segment.length > 0);
+		candidates.push({ path: entry, pathLower, normalizedPath, segments });
 	}
 	return candidates;
 }
 
+/**
+ * True when `query` can be spelled as prefixes of path segments taken in order
+ * (segments may be skipped), e.g. `httpserap` → `http_server_api_tests`.
+ * Plain subsequence matching would also accept letters scattered mid-word across
+ * any long path, so a stray `@handle` or `@word` would resolve to an unrelated file.
+ */
+function matchesSegmentPrefixes(query: string, segments: string[]): boolean {
+	const failed = new Set<number>();
+	const visit = (segmentIndex: number, queryIndex: number): boolean => {
+		if (queryIndex === query.length) return true;
+		if (segmentIndex === segments.length) return false;
+		const key = segmentIndex * (query.length + 1) + queryIndex;
+		if (failed.has(key)) return false;
+		const segment = segments[segmentIndex]!;
+		for (let taken = 1; taken <= segment.length && queryIndex + taken <= query.length; taken++) {
+			if (segment[taken - 1] !== query[queryIndex + taken - 1]) break;
+			if (visit(segmentIndex + 1, queryIndex + taken)) return true;
+		}
+		if (visit(segmentIndex + 1, queryIndex)) return true;
+		failed.add(key);
+		return false;
+	};
+	return visit(0, 0);
+}
+
 async function resolveMentionPath(
 	filePath: string,
 	cwd: string,
@@ -148,6 +175,7 @@ async function resolveMentionPath(
 	}
 
 	const scored = candidates
+		.filter(candidate => matchesSegmentPrefixes(normalizedQuery, candidate.segments))
 		.map(candidate => ({ candidate, match: fuzzyMatch(normalizedQuery, candidate.normalizedPath) }))
 		.filter(entry => entry.match.matches)
 		.sort((a, b) => {

package/src/utils/title-generator.ts

@@ -5,7 +5,7 @@ import * as path from "node:path";
 
 import type { AgentMessage } from "@gajae-code/agent-core";
 import { type Api, type AssistantMessage, completeSimple, type Model, type Tool } from "@gajae-code/ai/core";
-import { logger, prompt } from "@gajae-code/utils";
+import { logger, prompt, redactCrashSecrets } from "@gajae-code/utils";
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
 import type { Settings } from "../config/settings";
@@ -159,7 +159,12 @@ ${truncatedMessage}
 		userMessage,
 		maxTokens,
 	};
-	logger.debug("title-generator: request", request);
+	logger.debug("title-generator: request", {
+		model: request.model,
+		systemPrompt: request.systemPrompt,
+		userMessage: redactCrashSecrets(request.userMessage),
+		maxTokens: request.maxTokens,
+	});
 
 	try {
 		const response = await completeSimple(

package/src/web/scrapers/index.ts

@@ -169,7 +169,9 @@ specialHandlers.push(
 	handleGitHub,
 	handleGitLab,
 	// Video/Media
-	(url, timeout, signal) => handleYouTube(url, timeout, signal),
+	// Registered directly (not through an argument-dropping adapter) so the
+	// handler receives the caller's storage and settings.
+	handleYouTube,
 	handleVimeo,
 	handleSpotify,
 	handleDiscogs,

package/src/web/scrapers/types.ts

@@ -2,6 +2,7 @@
  * Shared types and utilities for web-fetch handlers
  */
 import { ptree } from "@gajae-code/utils";
+import type { Settings } from "../../config/settings";
 import type { AgentStorage } from "../../session/agent-storage";
 import { ToolAbortError } from "../../tools/tool-errors";
 import type { AddressResolver } from "../insane/url-guard";
@@ -20,11 +21,18 @@ export interface RenderResult {
 	notes: string[];
 }
 
+/**
+ * `settings` is the caller's session settings. Handlers must read through it
+ * rather than the process-global singleton: the SDK/ACP host path runs tools
+ * without ever calling `Settings.init()`, where a global read throws
+ * "Settings not initialized" instead of scraping the page.
+ */
 export type SpecialHandler = (
 	url: string,
 	timeout: number,
 	signal?: AbortSignal,
 	storage?: AgentStorage | null,
+	settings?: Settings,
 ) => Promise<RenderResult | null>;
 
 export const MAX_OUTPUT_CHARS = 500_000;

package/src/web/scrapers/youtube.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { ptree, Snowflake } from "@gajae-code/utils";
-import { settings } from "../../config/settings";
+import type { Settings } from "../../config/settings";
 import type { AgentStorage } from "../../session/agent-storage";
 import { throwIfAborted } from "../../tools/tool-errors";
 import { ensureTool } from "../../utils/tools-manager";
@@ -115,6 +115,7 @@ export const handleYouTube: SpecialHandler = async (
 	timeout: number,
 	userSignal?: AbortSignal,
 	storage?: AgentStorage | null,
+	settings?: Settings,
 ): Promise<RenderResult | null> => {
 	throwIfAborted(userSignal);
 	const yt = parseYouTubeUrl(url);
@@ -126,7 +127,7 @@ export const handleYouTube: SpecialHandler = async (
 	const videoUrl = `https://www.youtube.com/watch?v=${yt.videoId}`;
 
 	// Prefer Parallel extract when credentials are available
-	if (settings.get("providers.parallelFetch") && findParallelApiKey(storage)) {
+	if (settings?.get("providers.parallelFetch") === true && findParallelApiKey(storage)) {
 		try {
 			const parallelResult = await extractWithParallel(
 				[videoUrl],