@gajae-code/coding-agent 0.11.5 → 0.11.7

package/src/modes/controllers/btw-controller.ts

@@ -1,12 +1,28 @@
-import { prompt } from "@gajae-code/utils";
 import btwUserPrompt from "../../prompts/system/btw-user.md" with { type: "text" };
+import type { BtwConversationScope, BtwTurnCapture } from "../../session/agent-session";
+import {
+	BTW_MAX_QUESTION_UTF8_BYTES,
+	type BtwTextExchange,
+	boundBtwExchanges,
+	sanitizeBtwError,
+	utf8ByteLength,
+} from "../../session/btw-contract";
 import { BtwPanelComponent } from "../components/btw-panel";
 import type { InteractiveModeContext } from "../types";
 
+type BtwFollowUpResult = "accepted" | "busy" | "closed" | "rejected";
+
+interface ActiveBtwTurn extends BtwTurnCapture {
+	abortController: AbortController | undefined;
+	active: boolean;
+}
+
 interface BtwRequest {
 	component: BtwPanelComponent;
-	abortController: AbortController;
-	question: string;
+	conversationScope: BtwConversationScope | undefined;
+	activeTurn: ActiveBtwTurn | undefined;
+	inFlight: boolean;
+	contextExchanges: BtwTextExchange[];
 }
 
 export class BtwController {
@@ -18,84 +34,151 @@ export class BtwController {
 		return this.#activeRequest !== undefined;
 	}
 
+	hasOpenPanel(): boolean {
+		return this.hasActiveRequest();
+	}
+
+	isTurnInFlight(): boolean {
+		return this.#activeRequest?.inFlight ?? false;
+	}
+
 	handleEscape(): boolean {
 		if (!this.#activeRequest) return false;
-		this.#closeActiveRequest({ abort: this.#activeRequest.abortController.signal.aborted === false });
+		this.#closeActiveRequest();
 		return true;
 	}
 
 	dispose(): void {
-		this.#closeActiveRequest({ abort: true });
+		this.#closeActiveRequest();
 	}
 
 	async start(question: string): Promise<void> {
+		if (this.hasOpenPanel()) {
+			this.ctx.showStatus("A /btw chat is already open. Type a follow-up or press Esc to return to the main chat.");
+			return;
+		}
 		const trimmedQuestion = question.trim();
 		if (!trimmedQuestion) {
 			this.ctx.showStatus("Usage: /btw <question>");
 			return;
 		}
+		if (!this.#acceptQuestion(trimmedQuestion) || !this.#hasModel()) return;
+		const scope = this.ctx.session.createBtwConversationScope(btwUserPrompt);
+		const request = this.#openRequest(trimmedQuestion, scope);
+		void this.#runRequest(request);
+	}
 
-		const model = this.ctx.session.model;
-		if (!model) {
-			this.ctx.showError("No active model available for /btw.");
-			return;
+	async submitFollowUp(question: string): Promise<BtwFollowUpResult> {
+		const request = this.#activeRequest;
+		if (!request) return "closed";
+		if (request.inFlight) {
+			this.ctx.showStatus("The /btw chat is still answering. Wait for it to finish.");
+			return "busy";
 		}
+		const trimmedQuestion = question.trim();
+		if (!trimmedQuestion) return "closed";
+		if (!this.#acceptQuestion(trimmedQuestion)) return "rejected";
+		if (!request.conversationScope) return "closed";
+		request.activeTurn = this.#createTurn(trimmedQuestion, request.conversationScope);
+		request.inFlight = true;
+		request.component.beginTurn(trimmedQuestion);
+		void this.#runRequest(request);
+		return "accepted";
+	}
+
+	#acceptQuestion(question: string): boolean {
+		if (utf8ByteLength(question) <= BTW_MAX_QUESTION_UTF8_BYTES) return true;
+		this.ctx.showError(`/btw questions are limited to ${BTW_MAX_QUESTION_UTF8_BYTES} UTF-8 bytes.`);
+		return false;
+	}
+
+	#hasModel(): boolean {
+		if (this.ctx.session.model) return true;
+		this.ctx.showError("No active model available for /btw.");
+		return false;
+	}
 
-		this.#closeActiveRequest({ abort: true });
+	#createTurn(question: string, scope: BtwConversationScope): ActiveBtwTurn {
+		return { question, scope, abortController: new AbortController(), active: true };
+	}
 
+	#openRequest(question: string, scope: BtwConversationScope): BtwRequest {
 		const request: BtwRequest = {
-			component: new BtwPanelComponent({ question: trimmedQuestion, tui: this.ctx.ui }),
-			abortController: new AbortController(),
-			question: trimmedQuestion,
+			component: new BtwPanelComponent({ question, tui: this.ctx.ui }),
+			conversationScope: scope,
+			activeTurn: this.#createTurn(question, scope),
+			inFlight: true,
+			contextExchanges: [],
 		};
 		this.ctx.btwContainer.clear();
 		this.ctx.btwContainer.addChild(request.component);
 		this.ctx.ui.requestRender();
 		this.#activeRequest = request;
-		void this.#runRequest(request);
+		return request;
 	}
 
 	async #runRequest(request: BtwRequest): Promise<void> {
+		const turn = request.activeTurn;
+		const abortController = turn?.abortController;
+		if (!turn?.scope || !abortController) return;
 		try {
-			const promptText = prompt.render(btwUserPrompt, { question: request.question });
 			const { replyText } = await this.ctx.session.runEphemeralTurn({
 				purpose: "btw",
-				promptText,
+				turn,
+				contextExchanges: request.contextExchanges.map(exchange => ({ ...exchange })),
 				onTextDelta: delta => {
-					if (this.#isActiveRequest(request)) {
-						request.component.appendText(delta);
-					}
+					if (turn.active && this.#isActiveRequest(request)) request.component.appendText(delta);
 				},
-				signal: request.abortController.signal,
+				signal: abortController.signal,
 			});
-
-			if (!this.#isActiveRequest(request)) {
-				return;
-			}
-			if (replyText) {
-				request.component.setAnswer(replyText);
-			}
+			if (!turn.active || !this.#isActiveRequest(request)) return;
+			request.inFlight = false;
+			request.contextExchanges = boundBtwExchanges([
+				...request.contextExchanges,
+				{ question: turn.question, answer: replyText },
+			]);
+			if (replyText) request.component.setAnswer(replyText);
 			request.component.markComplete();
-		} catch (error) {
-			if (!this.#isActiveRequest(request)) {
-				return;
-			}
-			if (request.abortController.signal.aborted) {
+		} catch {
+			if (!turn.active || !this.#isActiveRequest(request)) return;
+			request.inFlight = false;
+			if (abortController.signal.aborted) {
 				request.component.markAborted();
 				return;
 			}
-			request.component.markError(error instanceof Error ? error.message : String(error));
+			request.component.markError(sanitizeBtwError("Side-chat request failed."));
+		} finally {
+			if (request.activeTurn === turn) request.activeTurn = undefined;
+			this.#scrubTurn(turn);
 		}
 	}
 
-	#closeActiveRequest(options: { abort: boolean }): void {
+	#scrubTurn(turn: ActiveBtwTurn): void {
+		turn.active = false;
+		turn.question = "";
+		turn.abortController = undefined;
+		turn.scope = undefined;
+	}
+
+	#closeActiveRequest(): void {
 		const request = this.#activeRequest;
 		if (!request) return;
 		this.#activeRequest = undefined;
-		if (options.abort) {
-			request.abortController.abort();
+		const turn = request.activeTurn;
+		const abortController = turn?.abortController;
+		if (turn) this.#scrubTurn(turn);
+		request.activeTurn = undefined;
+		request.contextExchanges.splice(0);
+		request.inFlight = false;
+		if (request.conversationScope) {
+			request.conversationScope.messages.splice(0);
+			request.conversationScope.systemPrompt.splice(0);
+			request.conversationScope = undefined;
 		}
+		abortController?.abort();
 		request.component.close();
+		this.ctx.editor?.setText("");
+		this.ctx.pendingImages = [];
 		this.ctx.btwContainer.clear();
 		this.ctx.ui.requestRender();
 	}

package/src/modes/controllers/command-controller.ts

@@ -1260,6 +1260,10 @@ export class CommandController {
 	}
 
 	async handleHandoffCommand(customInstructions?: string): Promise<void> {
+		if (this.ctx.session.isStreaming) {
+			this.ctx.showWarning("Wait for the current response to finish or abort it before handing off.");
+			return;
+		}
 		const entries = this.ctx.sessionManager.getEntries();
 		const messageCount = entries.filter(e => e.type === "message").length;
 
@@ -1321,6 +1325,17 @@ export class CommandController {
 			} else {
 				this.ctx.showError(`Handoff failed: ${message}`);
 			}
+			// The failure is non-destructive: the current session is unchanged. If the
+			// document was already generated, preserve it on the clipboard for retry.
+			const retainedDocument =
+				error &&
+				typeof error === "object" &&
+				typeof (error as { handoffDocument?: unknown }).handoffDocument === "string"
+					? (error as { handoffDocument: string }).handoffDocument
+					: undefined;
+			if (retainedDocument) {
+				this.#doCopy(retainedDocument, "Handoff document preserved on clipboard; current session is unchanged.");
+			}
 		} finally {
 			handoffLoader.stop();
 			this.ctx.statusContainer.clear();

package/src/modes/controllers/extension-ui-controller.ts

@@ -214,13 +214,25 @@ export class ExtensionUiController {
 				try {
 					return {
 						handoff: await session.handoff(
-							typeof input.instructions === "string" ? input.instructions : undefined,
+							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: "invalid_request" },
+						{ code },
+						handoffDocument,
 					);
 				}
 			case "session.export_html":

package/src/modes/controllers/input-controller.ts

@@ -752,6 +752,29 @@ export class InputController {
 	async submitText(text: string, composer: ComposerSubmissionOptions): Promise<void> {
 		text = text.trim();
 		if ((!isSettingsInitialized() || settings.get("emojiAutocomplete")) && text) text = expandEmoticons(text);
+		if (this.ctx.hasActiveBtw()) {
+			if (!text) return;
+			if (!text.startsWith("/")) {
+				const result = await this.ctx.handleBtwFollowUp(text);
+				if (result === "accepted" && this.#canModifyComposer(composer)) {
+					this.ctx.editor.setText("");
+					this.ctx.pendingImages = [];
+				}
+				return;
+			}
+		}
+
+		if (/^\/btw(?:\s|$)/.test(text)) {
+			const slashResult = await executeBuiltinSlashCommand(text, {
+				ctx: this.ctx,
+				handleBackgroundCommand: () => this.handleBackgroundCommand(),
+				composer,
+			});
+			if (slashResult === true) {
+				this.ctx.pendingImages = [];
+				return;
+			}
+		}
 
 		// Empty submit while streaming with queued messages: flush queues immediately
 		if (!text && this.ctx.session.isStreaming && this.ctx.session.queuedMessageCount > 0) {
@@ -1357,6 +1380,14 @@ export class InputController {
 	async handleFollowUp(): Promise<void> {
 		const text = this.ctx.editor.getText().trim();
 		if (!text) return;
+		// While /btw is open, plain text stays in the side chat. Slash-origin
+		// input keeps normal dispatch so commands remain available.
+		if (this.ctx.hasActiveBtw() && !text.startsWith("/")) {
+			if ((await this.ctx.handleBtwFollowUp(text)) === "accepted") {
+				this.ctx.editor.setText("");
+			}
+			return;
+		}
 
 		// Compaction first: while compacting, queue free text and `/skill:*`
 		// commands in the compaction-local queue. `flushCompactionQueue`

package/src/modes/controllers/selector-controller.ts

@@ -101,8 +101,10 @@ import {
 } from "../../setup/model-onboarding-guidance";
 import { addApiCompatibleProvider, formatProviderSetupResult } from "../../setup/provider-onboarding";
 import {
+	IMAGE_PROVIDER_DEFAULTS,
 	isConfigurableSearchProviderId,
 	isSearchProviderPreference,
+	setConfiguredImageModel,
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
@@ -190,6 +192,7 @@ export function buildStatusLineSettings(settingsInstance: Settings): StatusLineS
 		rightSegments: settingsInstance.get("statusLine.rightSegments"),
 		separator: settingsInstance.get("statusLine.separator"),
 		showHookStatus: settingsInstance.get("statusLine.showHookStatus"),
+		showActionHints: settingsInstance.get("statusLine.showActionHints"),
 		sessionAccent: settingsInstance.get("statusLine.sessionAccent"),
 		maxRows: settingsInstance.get("statusLine.maxRows"),
 		segmentOptions: settingsInstance.get("statusLine.segmentOptions"),
@@ -1103,6 +1106,68 @@ export class SelectorController {
 		}
 	}
 
+	async #handleImageGenerationConfig(): Promise<void> {
+		const provider = await this.ctx.showHookInput(
+			"Image Generation provider (auto, openai, gemini, openrouter, antigravity, custom)",
+			"auto",
+		);
+		if (provider === undefined) return;
+		const normalized = provider.trim().toLowerCase();
+		const validProviders = ["auto", "openai", "gemini", "openrouter", "antigravity", "custom"];
+		if (!validProviders.includes(normalized)) {
+			this.ctx.showStatus(`Invalid image provider: ${normalized}. Valid: ${validProviders.join(", ")}`);
+			return;
+		}
+		let model: string | undefined;
+		if (normalized !== "auto" && normalized !== "custom") {
+			const defaultModel = IMAGE_PROVIDER_DEFAULTS[normalized];
+			model = await this.ctx.showHookInput(`Image model for ${normalized} (default: ${defaultModel})`, defaultModel);
+			if (model === undefined) return;
+			model = model.trim() || defaultModel;
+		}
+		let customUrl: string | undefined;
+		let customKey: string | undefined;
+		if (normalized === "custom") {
+			customUrl = await this.ctx.showHookInput("Custom image endpoint base URL");
+			if (!customUrl?.trim()) {
+				this.ctx.showStatus("Custom image endpoint requires a base URL");
+				return;
+			}
+			model = await this.ctx.showHookInput("Custom image model", IMAGE_PROVIDER_DEFAULTS.openai);
+			if (model === undefined) return;
+			model = model.trim() || IMAGE_PROVIDER_DEFAULTS.openai;
+			customKey = await this.ctx.showHookInput("Custom image endpoint API key");
+		}
+		const scope = await this.ctx.showHookInput(
+			"Scope: 'session' (this session only) or 'default' (persist)",
+			"session",
+		);
+		if (scope === undefined) return;
+		const persistDefault = scope.trim().toLowerCase() === "default";
+
+		const imageProvider = normalized as "auto" | "openai" | "gemini" | "openrouter" | "antigravity" | "custom";
+		setPreferredImageProvider(imageProvider === "custom" ? "auto" : imageProvider);
+		setConfiguredImageModel({
+			provider: imageProvider,
+			model: model ?? null,
+			customUrl: customUrl?.trim(),
+			customKey: customKey?.trim(),
+		});
+
+		if (persistDefault) {
+			this.ctx.settings.set("providers.image", imageProvider);
+			if (model) this.ctx.settings.set("providers.imageModel", model);
+			if (customUrl?.trim()) this.ctx.settings.set("providers.imageCustomUrl", customUrl.trim());
+			if (customKey?.trim()) this.ctx.settings.set("providers.imageCustomKey", customKey.trim());
+		}
+
+		const displayModel =
+			model ?? (normalized !== "auto" && normalized !== "custom" ? IMAGE_PROVIDER_DEFAULTS[normalized] : undefined);
+		const label = normalized === "auto" ? "Auto" : `${normalized}${displayModel ? ` (${displayModel})` : ""}`;
+		this.ctx.showStatus(`Image Generation: ${label}${persistDefault ? " (default)" : " (session)"}`);
+		this.ctx.ui.requestRender();
+	}
+
 	showCustomProviderWizard(): void {
 		this.showSelector(done => {
 			let wizard: CustomProviderWizardComponent;
@@ -1516,6 +1581,7 @@ export class SelectorController {
 			case "statusLine.separator":
 			case "statusLineShowHooks":
 			case "statusLine.showHookStatus":
+			case "statusLine.showActionHints":
 			case "statusLine.sessionAccent":
 			case "statusLine.maxRows":
 			case "statusLine.leftSegments":
@@ -1563,16 +1629,34 @@ export class SelectorController {
 				}
 				break;
 			case "providers.image":
+			case "providers.imageModel":
+			case "providers.imageCustomUrl":
+			case "providers.imageCustomKey":
+			case "providers.imageCustomKeyEnv": {
+				const imgProvider = this.ctx.settings.get("providers.image");
+				const imgModel = this.ctx.settings.get("providers.imageModel");
+				const imgCustomUrl = this.ctx.settings.get("providers.imageCustomUrl");
+				const imgCustomKey = this.ctx.settings.get("providers.imageCustomKey");
+				const imgCustomKeyEnv = this.ctx.settings.get("providers.imageCustomKeyEnv");
 				if (
-					value === "auto" ||
-					value === "openai" ||
-					value === "gemini" ||
-					value === "openrouter" ||
-					value === "antigravity"
+					imgProvider === "auto" ||
+					imgProvider === "openai" ||
+					imgProvider === "gemini" ||
+					imgProvider === "openrouter" ||
+					imgProvider === "antigravity" ||
+					imgProvider === "custom"
 				) {
-					setPreferredImageProvider(value);
+					setPreferredImageProvider(imgProvider === "custom" ? "auto" : imgProvider);
+					setConfiguredImageModel({
+						provider: imgProvider,
+						model: imgModel ?? null,
+						customUrl: imgCustomUrl,
+						customKey: imgCustomKey,
+						customKeyEnv: imgCustomKeyEnv,
+					});
 				}
 				break;
+			}
 
 			// MCP update injection - live subscribe/unsubscribe
 			case "mcp.notifications":
@@ -1631,6 +1715,11 @@ export class SelectorController {
 							await this.#deleteCustomModelPreset(selection.profileName, modelSelector);
 							return;
 						}
+						if (selection.kind === "imageGeneration") {
+							done();
+							await this.#handleImageGenerationConfig();
+							return;
+						}
 						if (selection.kind === "profile") {
 							await this.#applyModelProfile(selection.profileName, selection.setDefault);
 							done();
@@ -2057,10 +2146,7 @@ export class SelectorController {
 	}
 
 	async showSessionSelector(): Promise<void> {
-		const sessions = await SessionManager.listForResumePickerReadOnly(
-			this.ctx.sessionManager.getCwd(),
-			this.ctx.sessionManager.getSessionDir(),
-		);
+		const sessions = await this.ctx.sessionManager.listForResumePickerReadOnly();
 		this.showSelector(done => {
 			const selector = new SessionSelectorComponent(
 				sessions,
@@ -2156,8 +2242,16 @@ export class SelectorController {
 		this.#clearTransientSessionUi();
 		const migrationPolicy =
 			this.ctx.settings?.get("session.directoryMigration") === "disabled" ? "disabled" : "copy-retain";
-		const writableSessionPath = await SessionManager.prepareManagedCandidateForWrite(sessionPath, migrationPolicy);
-
+		let writableSessionPath = sessionPath;
+		if (this.ctx.sessionManager.isManagedDestination()) {
+			const inspection = await SessionManager.inspectSessionTailReadOnly(sessionPath);
+			if (inspection.kind === "error") throw new Error(`Could not inspect selected session: ${inspection.reason}`);
+			writableSessionPath = await this.ctx.sessionManager.prepareManagedCandidateForStrictAdoption(
+				sessionPath,
+				migrationPolicy,
+				inspection.identity,
+			);
+		}
 		// Switch session via AgentSession (emits hook and tool session events)
 		if (!(await this.ctx.session.switchSession(writableSessionPath))) return;
 		const switchingToDifferentSession = previousSessionId !== this.ctx.sessionManager.getSessionId();

package/src/modes/interactive-mode.ts

@@ -264,6 +264,10 @@ export interface InteractiveModeOptions {
 	initialMessages?: string[];
 }
 
+export function selectShutdownDraft(editorText: string, hasActiveBtw: boolean): string {
+	return hasActiveBtw ? "" : editorText;
+}
+
 export class InteractiveMode implements InteractiveModeContext {
 	session: AgentSession;
 	sessionManager: SessionManager;
@@ -1322,19 +1326,20 @@ export class InteractiveMode implements InteractiveModeContext {
 		if (this.#isShuttingDown) return;
 		this.#isShuttingDown = true;
 
-		// Snapshot the editor before any teardown empties it. Persisting the draft
-		// here covers Ctrl+D shutdown with non-empty text; for /exit the editor is
-		// already cleared so saveDraft("") just removes any stale sidecar.
-		const draftText = this.editor.getText();
+		// `/btw` owns the shared composer while its panel is open. Never persist a
+		// side-chat draft or pending side-chat images into the main-session draft.
+		const hadActiveBtw = this.#btwController.hasOpenPanel();
+		const draftText = selectShutdownDraft(this.editor.getText(), hadActiveBtw);
+		if (hadActiveBtw) this.pendingImages = [];
+		this.#btwController.dispose();
 
-		// Flush pending session writes before shutdown
+		// Flush pending session writes before shutdown.
 		await this.sessionManager.flush();
 		try {
 			await this.sessionManager.saveDraft(draftText);
 		} catch (err) {
 			logger.warn("Failed to save session draft", { error: String(err) });
 		}
-		this.#btwController.dispose();
 
 		// Emit shutdown event to hooks
 		this.session.setSdkPlanModeHandler(null);
@@ -2025,7 +2030,11 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 
 	hasActiveBtw(): boolean {
-		return this.#btwController.hasActiveRequest();
+		return this.#btwController.hasOpenPanel();
+	}
+
+	handleBtwFollowUp(question: string): Promise<"accepted" | "busy" | "closed" | "rejected"> {
+		return this.#btwController.submitFollowUp(question);
 	}
 
 	handleBtwEscape(): boolean {

package/src/modes/runtime-init.ts

@@ -301,15 +301,29 @@ export async function initializeExtensions(session: AgentSession, options: Initi
 						try {
 							return {
 								handoff: await session.handoff(
-									typeof input.instructions === "string" ? input.instructions : undefined,
+									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: "invalid_request" },
+								{ code },
+								handoffDocument,
 							);
 						}
 					case "session.export_html":

package/src/modes/types.ts

@@ -338,6 +338,7 @@ export interface InteractiveModeContext {
 	handleBackgroundCommand(): void;
 	handleImagePaste(): Promise<boolean>;
 	handleBtwCommand(question: string): Promise<void>;
+	handleBtwFollowUp(question: string): Promise<"accepted" | "busy" | "closed" | "rejected">;
 	hasActiveBtw(): boolean;
 	handleBtwEscape(): boolean;
 	cycleThinkingLevel(): void;

package/src/prompts/system/btw-user.md

@@ -1,8 +1,3 @@
-<btw>
-This is an ephemeral side question for the current interactive session.
-Answer briefly and directly using the conversation context already provided.
-Do not use tools.
-Do not ask follow-up questions.
-Question:
-{{question}}
-</btw>
+You are answering inside an ephemeral multi-turn side chat for the interactive session.
+Use only the sanitized visible-text conversation scope and prior side-chat turns provided as messages.
+Answer directly. Do not use tools or request hidden session state.

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

@@ -3,6 +3,7 @@ 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.
 - 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.
 - To load a selected skill's full `SKILL.md`, invoke it through the existing `skill` tool with the exact `name` returned here.
 </instruction>