@gajae-code/coding-agent 0.13.3 → 0.14.0

package/src/modes/print-mode.ts

@@ -10,6 +10,7 @@ import { isKnownSinkPeerClosedError, logger, sanitizeText } from "@gajae-code/ut
 import { loadSlashCommands } from "../extensibility/slash-commands";
 import type { AgentSession } from "../session/agent-session";
 import { isSilentAbort } from "../session/messages";
+import { executeLocalHeadlessBuiltinSlashCommand } from "../slash-commands/builtin-registry";
 import { initializeExtensions } from "./runtime-init";
 
 /**
@@ -197,6 +198,8 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 	const stdout = createPrintStdoutOwner();
 	const failures: unknown[] = [];
 	let unsubscribe: (() => void) | undefined;
+	let submittedPrompt = false;
+	let consumedCommand = false;
 
 	try {
 		for (const warning of new Set(session.configWarnings)) {
@@ -236,19 +239,45 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 				stdout.write(`${JSON.stringify(event)}\n`);
 			});
 		}
+		const submitInput = async (text: string, images?: ImageContent[]): Promise<void> => {
+			if (text.startsWith("/")) {
+				const command = await executeLocalHeadlessBuiltinSlashCommand(text, {
+					session,
+					sessionManager: session.sessionManager,
+					settings: session.settings,
+					cwd:
+						typeof session.sessionManager.getCwd === "function" ? session.sessionManager.getCwd() : process.cwd(),
+					output: value =>
+						stdout.write(
+							mode === "json"
+								? `${JSON.stringify({ type: "local_command_output", command: text.split(/\s/u, 1)[0], output: value })}\n`
+								: `${value}\n`,
+						),
+					refreshCommands: () => {},
+					reloadPlugins: async () => {},
+				});
+				if (command !== false && "consumed" in command) {
+					consumedCommand = true;
+					if (command.exitCode !== undefined && !options.suppressProcessExit) process.exitCode = command.exitCode;
+					return;
+				}
+				if (command !== false) text = command.prompt;
+			}
+			submittedPrompt = true;
+			await session.prompt(text, images ? { images } : undefined);
+		};
 
-		// Send initial message with attachments.
+		// Send the initial input and remaining inputs, dispatching only commands
+		// explicitly authorized for trusted local headless mode.
 		if (initialMessage !== undefined) {
-			await logger.time("print:prompt:initial", () => session.prompt(initialMessage, { images: initialImages }));
+			await logger.time("print:prompt:initial", () => submitInput(initialMessage, initialImages));
 		}
-
-		// Send remaining messages.
 		for (const message of messages) {
-			await logger.time("print:prompt:next", () => session.prompt(message));
+			await logger.time("print:prompt:next", () => submitInput(message));
 		}
 
 		// In text mode, output final response.
-		if (mode === "text") {
+		if (mode === "text" && (!consumedCommand || submittedPrompt)) {
 			const lastMessage = session.state.messages.findLast(message => message.role === "assistant");
 			if (lastMessage?.role === "assistant") {
 				const assistantMsg = lastMessage as AssistantMessage;

package/src/modes/runtime-init.ts

@@ -18,10 +18,26 @@ import {
 	syntheticNamespaceCollision,
 } from "../sdk/model-profile-model";
 import type { AgentSession } from "../session/agent-session";
-
 import { parseThinkingLevel } from "../thinking";
 import type { TodoPhase } from "../tools/todo-write";
 
+const BROKER_LIFECYCLE_OPERATIONS = new Set([
+	"session.new",
+	"session.fork",
+	"session.resume",
+	"session.close",
+	"session.switch",
+	"session.branch",
+	"session.handoff",
+	"session.delete",
+]);
+
+function prohibitBrokerLifecycleOperation(operation: string): never {
+	throw Object.assign(new Error(`${operation} is available only through the Broker lifecycle service.`), {
+		code: "operation_prohibited",
+	});
+}
+
 /** Action name for an extension-originated send failure. */
 export type ExtensionSendAction = "extension_send" | "extension_send_user";
 
@@ -343,57 +359,8 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 					case "retry.abort":
 						session.abortRetry();
 						return { aborted: true };
-					case "session.new":
-						return { created: await session.newSession() };
-					case "session.fork":
-						return { session: await session.fork() };
-					case "session.resume":
-						return { resumed: await session.switchSession(String(input.id)) };
-					case "session.close":
-						await session.sessionManager.flush();
-						return { closed: true };
-					case "session.switch":
-						return { switched: await session.switchSession(String(input.id)) };
-					case "session.branch":
-						try {
-							return await session.branch(String(input.entryId));
-						} catch (error) {
-							throw Object.assign(
-								new Error(error instanceof Error ? error.message : "Branch entry was not found."),
-								{ code: "resource_gone" },
-							);
-						}
 					case "session.rename":
 						return { renamed: await session.setSessionName(String(input.name), "user") };
-					case "session.handoff":
-						try {
-							return {
-								handoff: await session.handoff(
-									typeof input.target === "string"
-										? input.target
-										: typeof input.instructions === "string"
-											? input.instructions
-											: undefined,
-								),
-							};
-						} catch (error) {
-							const typed = error as { code?: unknown; handoffDocument?: unknown };
-							const handoffDocument =
-								typeof typed?.handoffDocument === "string"
-									? { handoffDocument: typed.handoffDocument }
-									: undefined;
-							// Preserve a safe typed code (e.g. transient `busy`) so clients keep
-							// correct retry/backoff semantics; only synthesize invalid_request for
-							// otherwise-untyped failures.
-							const code = typed?.code === "busy" ? "busy" : "invalid_request";
-							throw Object.assign(
-								new Error(
-									error instanceof Error ? error.message : "Handoff is unavailable for the current state.",
-								),
-								{ code },
-								handoffDocument,
-							);
-						}
 					case "session.export_html":
 						try {
 							return {
@@ -467,13 +434,11 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 						}
 						return { changed: true, enabled: on };
 					}
-					case "session.delete":
-						await session.sessionManager.dropSession(String(input.id));
-						return { deleted: true };
 					case "session.cwd.move":
 						await session.sessionManager.moveTo(String(input.path));
 						return { moved: true, cwd: session.sessionManager.getCwd() };
 					default:
+						if (BROKER_LIFECYCLE_OPERATIONS.has(operation)) prohibitBrokerLifecycleOperation(operation);
 						throw Object.assign(new Error(`${operation} has no AgentSession implementation.`), {
 							code: "unavailable",
 						});
@@ -484,25 +449,13 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 		{
 			getContextUsage: () => session.getContextUsage(),
 			waitForIdle: () => session.agent.waitForIdle(),
-			newSession: async newOptions => {
-				const success = await session.newSession({ parentSession: newOptions?.parentSession });
-				if (success && newOptions?.setup) {
-					await newOptions.setup(session.sessionManager);
-				}
-				return { cancelled: !success };
-			},
-			branch: async entryId => {
-				const result = await session.branch(entryId);
-				return { cancelled: result.cancelled };
-			},
+			newSession: async () => prohibitBrokerLifecycleOperation("session.new"),
+			branch: async () => prohibitBrokerLifecycleOperation("session.branch"),
 			navigateTree: async (targetId, navOptions) => {
 				const result = await session.navigateTree(targetId, { summarize: navOptions?.summarize });
 				return { cancelled: result.cancelled };
 			},
-			switchSession: async sessionPath => {
-				const success = await session.switchSession(sessionPath);
-				return { cancelled: !success };
-			},
+			switchSession: async () => prohibitBrokerLifecycleOperation("session.switch"),
 			reload: async () => {
 				await session.reload();
 			},

package/src/modes/types.ts

@@ -402,6 +402,7 @@ export interface InteractiveModeContext {
 	showPetSelector(): void;
 	showHistorySearch(): Promise<void>;
 	showExtensionsDashboard(): void;
+	showCustomizationDashboard(): void;
 	showAgentsDashboard(): void;
 	showModelSelector(options?: { temporaryOnly?: boolean }): void;
 	showEffortSelector(): void;

package/src/modes/utils/injected-user-submission.ts

@@ -7,6 +7,31 @@ import type { InteractiveModeContext } from "../types";
  * `AgentSession.sendUserMessage` (text parts joined with "\n") so the resulting
  * text matches the eventual user `message_start` payload.
  */
+/**
+ * Validate extension `sendUserMessage` content at the owning interactive
+ * boundary, before session delivery and UI bookkeeping. Returns a typed
+ * `invalid_input` Error when the content container or any array element is
+ * absent/null/malformed — exactly the shapes that would make
+ * `normalizeInjectedUserContent`'s `for-of` dereference (`part.type`) throw an
+ * untyped TypeError synchronously before the caller's `send.catch` is attached
+ * (unhandled rejection → resident crash).
+ */
+export function extensionUserMessageContentError(content: string | (TextContent | ImageContent)[]): Error | undefined {
+	if (typeof content === "string") return undefined;
+	if (!Array.isArray(content)) {
+		return Object.assign(new Error("sendUserMessage requires string or content-array content."), {
+			code: "invalid_input",
+		});
+	}
+	for (const part of content) {
+		if (part === null || typeof part !== "object") {
+			return Object.assign(new Error("sendUserMessage content array contains a null or non-object part."), {
+				code: "invalid_input",
+			});
+		}
+	}
+	return undefined;
+}
 export function normalizeInjectedUserContent(content: string | (TextContent | ImageContent)[]): {
 	text: string;
 	images: ImageContent[];

package/src/modes/utils/terminal-bell.ts

@@ -15,8 +15,22 @@ function getBellSetting(key: Parameters<typeof settings.get>[0]): boolean {
 	}
 }
 
+function terminalBellEnabled(): boolean {
+	try {
+		// macOS terminals commonly use OSC notification protocols for background
+		// status, while an interactive completion does not send that notification.
+		// Make the local BEL audible by default on macOS; an explicit setting still
+		// wins so users can disable it.
+		return settings.has("notifications.terminalBell")
+			? Boolean(settings.get("notifications.terminalBell"))
+			: process.platform === "darwin";
+	} catch {
+		return false;
+	}
+}
+
 function enabledForEvent(event: TerminalBellEvent): boolean {
-	if (!getBellSetting("notifications.terminalBell")) return false;
+	if (!terminalBellEnabled()) return false;
 	switch (event) {
 		case "complete":
 			return getBellSetting("notifications.bellOnComplete");

package/src/prompts/agent-fragments/ralplan-persistence.md

@@ -4,4 +4,4 @@ Persistence (ralplan runs only):
 
   gjc ralplan --write --session-id <owner-session-id> --run-id <run-id> --stage {{stage}} --stage_n <N> --artifact-env GJC_RALPLAN_ARTIFACT --json
 
-  Use the assignment-provided owner `session_id`, `run_id`, and `stage_n`; never substitute the role subagent's own session id. On a duplicate-write error retry with the incremented N. Return the write receipt (`session_id`, `run_id`, `path`, `sha256`, `stage`, `stage_n`) and the role's compact verdict only. Otherwise, do not call `gjc ralplan --write`; return the full result in `yield.result.data`.
+  Use the assignment-provided owner `session_id`, `run_id`, and `stage_n`; never substitute the role subagent's own session id. On a duplicate-write error retry with the incremented N. Return the write receipt (`session_id`, `run_id`, `path`, `sha256`, `stage`, `stage_n`) and the role's compact verdict only. Otherwise, do not call `gjc ralplan --write`; return the full result in `yield.result.data`.

package/src/prompts/agent-fragments/restricted-bash.md

@@ -1 +1 @@
-- Exception: restricted `bash` is only for sanctioned GJC workflow persistence (`gjc ralplan --write ...`), GJC workflow state commands (`gjc state ...`), and read-only git inspection (`git status`, `git log`, `git show`, `git diff`, `git blame`, `git rev-parse`, `git ls-files`). Pass artifacts through `GJC_RALPLAN_ARTIFACT` with `--artifact-env GJC_RALPLAN_ARTIFACT`; never use bash for product-source writes, commits, pushes, or other mutating/general shell work.
+- Exception: restricted `bash` is only for sanctioned GJC workflow persistence (`gjc ralplan --write …`), GJC workflow state commands (`gjc state …`), and read-only git inspection (`git status`, `git log`, `git show`, `git diff`, `git blame`, `git rev-parse`, `git ls-files`). Pass artifacts through `GJC_RALPLAN_ARTIFACT` with `--artifact-env GJC_RALPLAN_ARTIFACT`; never use bash for product-source writes, commits, pushes, or other mutating/general shell work.

package/src/prompts/agents/critic.md

@@ -35,7 +35,7 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 <re_review_ratchet>
 - Rule 1 (delta-only): from pass 2, review only the delta against the prior pass plus the resolution of previously raised findings; do not re-litigate previously-approved ground. The prior pass is identified by the re-review context bundle (WI-3): prior reviewed-plan path, prior same-lane review path, and the explicit run-level pass number supplied in the assignment.
 - Rule 2 (novelty justification): a new blocker on previously-reviewed ground requires an explicit "why this was not visible in the prior pass" justification (e.g. revealed by a fix, new file evidence); without it, demote to a non-blocking caveat.
-- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, the verdict must not worsen (e.g. ITERATE -> REJECT) absent a rule-2-justified new blocker.
+- Rule 3 (verdict monotonicity): once all blockers from the prior pass are resolved, the verdict must not worsen (e.g. ITERATE → REJECT) absent a rule-2-justified new blocker.
 - Rule 4 (severity discipline): carryover blockers (raised in a prior pass, still unresolved) remain blocking regardless of pass number. A fresh high-severity concern minted from pass 2 on previously-approved ground follows rule 2: it blocks only with the why-not-visible-earlier justification, else it is recorded as a non-blocking caveat with severity noted.
 - Rule 5 (counter-review duty): from pass 2, Critic also reviews the Architect output (routed via the context bundle) for over-engineering and unnecessary scope expansion; flag inflation as a review defect and do NOT convert unjustified Architect demands into ITERATE — inflating demands must not force revision passes.
 - Enrichment lane ("spec too thin — expand") preserved verbatim but justification-gated from pass 2: expansion requests on already-reviewed ground need the rule-2 justification.

package/src/prompts/system/rlm-research.md

@@ -4,7 +4,7 @@ You are operating in **RLM research mode** — a Jupyter-notebook-style research
 
 - Drive the investigation with the `python` tool. The kernel is **persistent**: variables, imports, and loaded data survive across calls, exactly like notebook cells. Build up state incrementally instead of re-running everything each time.
 - Each `python` call is recorded as a notebook cell (code + output) in this session's `notebook.ipynb`. Write focused cells that each make one clear step of progress.
-- Prefer the managed scientific stack (`numpy`, `pandas`, `matplotlib`, `polars`) when useful. If an additional package is missing, use the kernel's `%pip install ...` magic only when it is necessary for the investigation; that install cell is recorded in the notebook as provenance.
+- Prefer the managed scientific stack (`numpy`, `pandas`, `matplotlib`, `polars`) when useful. If an additional package is missing, use the kernel's `%pip install …` magic only when it is necessary for the investigation; that install cell is recorded in the notebook as provenance.
 - Use `read` to inspect local files, `web_search` to gather external facts, and read-only `bash` only for simple inspection commands where shell-native views are materially useful (`grep`, `rg`, `tree`, `ls`, `pwd`, `wc`, `du`, `file`, `stat`). The `bash` surface is restricted to a single command with no pipelines, redirects, env overrides, command substitution, shell expansion, or write-capable flags. You do **not** have file-editing or arbitrary-mutation tools in this mode by design: keep all work inside the Python kernel, read-only inspection, and the notebook/report artifacts.
 - RLM always runs under goal mode. Use `goal({"op":"get"})` to inspect the active research goal. When the research objective is actually satisfied and the report-worthy conclusions are grounded in notebook outputs, call `goal({"op":"complete"})`, then call `complete_research` with a concise final summary. Do not present the session as complete without both tool calls.
 

package/src/prompts/system/system-prompt.md

@@ -122,8 +122,6 @@ Do not claim a web search, browser action, integration, or subagent ran without
 Some tool output values are intentionally redacted as versioned `#GJC1_…#` tokens. Treat them as opaque sensitive strings.
 </redacted-content>
 {{/if}}
-
-
 {{#has tools "lsp"}}
 <lsp>
 Use language-server intelligence for symbol-aware operations whenever available:

package/src/prompts/tools/bash.md

@@ -33,7 +33,7 @@ This session's bash tool is restricted. It only accepts commands beginning with:
 {{#each restrictedAllowedPrefixes}}
 - `{{this}}`
 {{/each}}
-Use it only for sanctioned GJC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `GJC_RALPLAN_ARTIFACT` when paired with `gjc ralplan --write ... --artifact-env GJC_RALPLAN_ARTIFACT`, and all other shell command shapes are blocked before execution.
+Use it only for sanctioned GJC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `GJC_RALPLAN_ARTIFACT` when paired with `gjc ralplan --write … --artifact-env GJC_RALPLAN_ARTIFACT`, and all other shell command shapes are blocked before execution.
 {{/when}}
 </restricted-bash-mode>
 {{/if}}
@@ -61,6 +61,12 @@ Use it only for sanctioned GJC workflow CLI persistence or state read/write/cont
 - `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
 - For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
 {{/if}}
+# Waiting for background work
+
+- 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.
+- To wait for detached task subagents, use `subagent await` — it emits periodic liveness while waiting.
+- To wait for background bash jobs, use `job poll` — it reports status on each tick.
+- Short sleeps for rate-limiting or pacing (e.g. `sleep 2` between retries) are fine.
 
 # Output minimizer
 

package/src/prompts/tools/browser.md

@@ -8,7 +8,7 @@ Drives a real Chromium tab with full puppeteer access via JS execution.
   - `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.
   - `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.
 - Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
-- 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.
+- 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.
 - 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.
 - Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`.
 - 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.

package/src/prompts/tools/cron.md

@@ -12,12 +12,12 @@ Use a single `op` field to select the operation:
 
 `op: "create"` accepts 5-field cron: `minute hour day-of-month month day-of-week`. All fields support `*`, single values (`5`), steps (`*/15`), ranges (`1-5`), and comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, or month/weekday names is not supported.
 
-| Example       | Meaning                      |
-| :------------ | :--------------------------- |
-| `*/5 * * * *` | Every 5 minutes              |
-| `0 * * * *`   | Every hour on the hour       |
-| `0 9 * * *`   | Every day at 9am local       |
-| `0 9 * * 1-5` | Weekdays at 9am local        |
+|Example|Meaning|
+|:---|:---|
+|`*/5 * * * *`|Every 5 minutes|
+|`0 * * * *`|Every hour on the hour|
+|`0 9 * * *`|Every day at 9am local|
+|`0 9 * * 1-5`|Weekdays at 9am local|
 
 ## Lifecycle
 

package/src/prompts/tools/read.md

@@ -10,8 +10,6 @@ Read files, directories, archives, SQLite databases, images, documents, internal
 
 - `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`).
 - `truncation` — optional `head` | `last` | `both`; selects which end of an over-budget result to retain. Configured default: {{TRUNCATION_DEFAULT}} (factory default: `last`); non-file 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.
-
-
 ## Selectors
 Append `:<sel>` to `path`. The bare path falls back to the default mode.
 

package/src/prompts/tools/skill-discovery.md

@@ -1,9 +1,11 @@
 Discover project and user runtime skills without loading full skill content.
 
 <instruction>
-- 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.
+- 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.
 - Returns thin metadata only: name, description, source scope, path, and use conditions when present.
-- 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.
+- 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.
+- 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.
+- 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.
 - To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.
 </instruction>