@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/src/slash-commands/builtin-registry.ts

@@ -12,7 +12,12 @@ import {
 	SKC_MODEL_ASSIGNMENT_TARGETS,
 	type SkcModelAssignmentTargetId,
 } from "../config/model-registry";
-import { extractExplicitThinkingSelector, formatModelSelectorValue, parseModelPattern } from "../config/model-resolver";
+import {
+	extractExplicitThinkingSelector,
+	formatModelSelectorValue,
+	parseModelPattern,
+	parseModelString,
+} from "../config/model-resolver";
 import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../discovery/helpers.js";
 import { td } from "../i18n";
 import { resolveMemoryBackend } from "../memory-backend";
@@ -170,11 +175,32 @@ function splitExplicitThinkingSelector(selector: string): { baseSelector: string
 	return thinkingLevel ? { baseSelector: trimmed.slice(0, colonIndex), thinkingLevel } : { baseSelector: trimmed };
 }
 
-function resolveModelCommandSelection(
+interface ModelCommandSelection {
+	model: Model;
+	selector: string;
+	thinkingLevel?: ThinkingLevel;
+}
+
+interface ModelCommandResolutionFailure {
+	message: string;
+}
+
+type ModelCommandResolution =
+	| { ok: true; selection: ModelCommandSelection }
+	| { ok: false; failure: ModelCommandResolutionFailure };
+
+function parseProviderQualifiedSelector(selector: string): { provider: string; modelId: string } | undefined {
+	const splitSelector = splitExplicitThinkingSelector(selector);
+	const parsed = parseModelString(splitSelector.baseSelector);
+	if (!parsed) return undefined;
+	return { provider: parsed.provider, modelId: parsed.id };
+}
+
+function resolveModelCommandSelectionFromAvailable(
 	runtime: SlashCommandRuntime,
 	selector: string,
-): { model: Model; selector: string; thinkingLevel?: ThinkingLevel } | undefined {
-	const availableModels = runtime.session.getAvailableModels?.() ?? [];
+	availableModels: Model[],
+): ModelCommandSelection | undefined {
 	const matchPreferences = { usageOrder: runtime.settings.getStorage()?.getModelUsageOrder() };
 	const resolved = parseModelPattern(selector, availableModels, matchPreferences, {
 		modelRegistry: runtime.session.modelRegistry,
@@ -199,6 +225,78 @@ function resolveModelCommandSelection(
 	};
 }
 
+function formatDiscoverableProviderFailure(
+	selector: string,
+	provider: string,
+	modelId: string,
+	runtime: SlashCommandRuntime,
+): string {
+	const state = runtime.session.modelRegistry.getProviderDiscoveryState?.(provider);
+	const discovered = state?.models ?? [];
+	const base = `Unknown model: ${selector}.`;
+	if (!modelId.trim()) {
+		return `${base} Local provider model selectors must use provider/model-id syntax with a non-empty model id.`;
+	}
+	if (!state) {
+		return `${base} Provider ${provider} is configured for discovery but has not reported models yet.`;
+	}
+	if (state.status === "unavailable") {
+		const details = state.error ? ` (${state.error})` : "";
+		return `${base} Provider ${provider} discovery is unavailable${details}. Check the local endpoint and run /model again.`;
+	}
+	if (state.status === "unauthenticated") {
+		return `${base} Provider ${provider} requires authentication before model discovery.`;
+	}
+	if (state.status === "empty") {
+		return `${base} Provider ${provider} discovery succeeded but returned no models.`;
+	}
+	if (discovered.length > 0) {
+		const preview = discovered.slice(0, 8).join(", ");
+		const suffix = discovered.length > 8 ? ", …" : "";
+		return `${base} Provider ${provider} did not report model ${modelId}. Available local models: ${preview}${suffix}.`;
+	}
+	return `${base} Provider ${provider} did not report model ${modelId}.`;
+}
+
+async function resolveModelCommandSelection(
+	runtime: SlashCommandRuntime,
+	selector: string,
+): Promise<ModelCommandResolution> {
+	let availableModels = runtime.session.getAvailableModels?.() ?? [];
+	const initialSelection = resolveModelCommandSelectionFromAvailable(runtime, selector, availableModels as Model[]);
+	if (initialSelection) {
+		return { ok: true, selection: initialSelection };
+	}
+
+	const providerRef = parseProviderQualifiedSelector(selector);
+	const discoverableProviders = runtime.session.modelRegistry?.getDiscoverableProviders?.() ?? [];
+	if (providerRef && discoverableProviders.includes(providerRef.provider)) {
+		await runtime.session.modelRegistry.refreshProvider?.(providerRef.provider, "online");
+		availableModels = runtime.session.getAvailableModels?.() ?? [];
+		const refreshedSelection = resolveModelCommandSelectionFromAvailable(
+			runtime,
+			selector,
+			availableModels as Model[],
+		);
+		if (refreshedSelection) {
+			return { ok: true, selection: refreshedSelection };
+		}
+		return {
+			ok: false,
+			failure: {
+				message: formatDiscoverableProviderFailure(selector, providerRef.provider, providerRef.modelId, runtime),
+			},
+		};
+	}
+
+	return {
+		ok: false,
+		failure: {
+			message: `Unknown model: ${selector}. Configure or login to a provider first, then list/select models with /model.`,
+		},
+	};
+}
+
 function modelSelectionUsage(runtime: SlashCommandRuntime, currentModelLine?: string): string {
 	return [
 		currentModelLine,
@@ -225,7 +323,8 @@ const shutdownHandlerTui = (_command: ParsedSlashCommand, runtime: TuiSlashComma
 const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	{
 		name: "settings",
-		description: "Open settings menu",
+		priority: 40,
+		description: "Open settings and preferences",
 		handleTui: (_command, runtime) => {
 			runtime.ctx.showSettingsSelector();
 			runtime.ctx.editor.setText("");
@@ -241,7 +340,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "goal",
-		description: "Toggle goal mode (persistent autonomous objective for this session)",
+		priority: 84,
+		description: "Plan and track an autonomous goal",
 		subcommands: [
 			{ name: "set", description: "Set or replace the goal", usage: "<objective>" },
 			{ name: "show", description: "Show current goal details" },
@@ -283,16 +383,11 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 						runtime,
 					);
 				}
-				const selection = resolveModelCommandSelection(runtime, modelId);
-				if (!selection) {
-					return usage(
-						modelSelectionUsage(
-							runtime,
-							`Unknown model: ${modelId}. Configure or login to a provider first, then list/select models with /model.`,
-						),
-						runtime,
-					);
+				const resolution = await resolveModelCommandSelection(runtime, modelId);
+				if (!resolution.ok) {
+					return usage(modelSelectionUsage(runtime, resolution.failure.message), runtime);
 				}
+				const { selection } = resolution;
 				try {
 					const persistedSelector = formatModelSelectorValue(selection.selector, selection.thinkingLevel);
 					if (parsedArgs.targetId === "default") {
@@ -449,7 +544,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "export",
-		description: "Export session to HTML file",
+		priority: 50,
+		description: "Export this session to an HTML file",
 		inlineHint: "[path]",
 		allowArgs: true,
 		handle: async (command, runtime) => {
@@ -476,7 +572,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "copy",
-		description: "Copy last response as markdown",
+		priority: 55,
+		description: "Copy the last response for review or sharing",
 		// Public `/copy` is strict zero-argument, but `allowArgs` lets the
 		// TUI dispatcher route `/copy <arg>` here so it can be rejected locally
 		// instead of falling through as a model prompt.
@@ -493,7 +590,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "dump",
-		description: "Copy session transcript to clipboard",
+		priority: 54,
+		description: "Dump the full transcript for review or sharing",
 		acpDescription: "Return full transcript as plain text",
 		handle: async (_command, runtime) => {
 			const text = runtime.session.formatSessionAsText();
@@ -507,11 +605,12 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "session",
-		description: "Session management commands",
+		priority: 88,
+		description: "Show current session info or delete current session",
 		acpDescription: "Show session information",
 		acpInputHint: "info|delete",
 		subcommands: [
-			{ name: "info", description: "Show session info and stats" },
+			{ name: "info", description: "Show current session id, title, and workspace" },
 			{ name: "delete", description: "Delete current session and return to selector" },
 		],
 		allowArgs: true,
@@ -621,6 +720,15 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "help",
+		priority: 100,
+		description: "Learn commands and beginner workflows",
+		handleTui: (_command, runtime) => {
+			runtime.ctx.handleHelpCommand();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "hotkeys",
 		description: "Show all keyboard shortcuts",
@@ -861,6 +969,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "new",
+		priority: 96,
 		description: "Start a new session",
 		handleTui: async (_command, runtime) => {
 			runtime.ctx.editor.setText("");
@@ -877,7 +986,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "compact",
-		description: "Manually compact the session context",
+		priority: 72,
+		description: "Compact context and continue this session",
 		acpDescription: "Compact the conversation",
 		inlineHint: "[focus instructions]",
 		allowArgs: true,
@@ -934,7 +1044,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "resume",
-		description: "Resume a different session",
+		priority: 92,
+		description: "Resume a previous session",
 		handleTui: (_command, runtime) => {
 			runtime.ctx.showSessionSelector();
 			runtime.ctx.editor.setText("");
@@ -953,7 +1064,8 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "retry",
-		description: "Retry the last failed agent turn",
+		priority: 70,
+		description: "Retry or continue the last interrupted turn",
 		handleTui: async (_command, runtime) => {
 			const didRetry = await runtime.ctx.session.retry();
 			if (!didRetry) {
@@ -1153,6 +1265,7 @@ export const BUILTIN_SLASH_COMMAND_DEFS: ReadonlyArray<BuiltinSlashCommand> = AC
 		},
 		subcommands: command.subcommands,
 		inlineHint: command.inlineHint,
+		priority: command.priority,
 	}),
 );
 

package/src/slash-commands/types.ts

@@ -19,6 +19,8 @@ export interface BuiltinSlashCommand {
 	subcommands?: SubcommandDef[];
 	/** Static inline hint when command takes a simple argument (no subcommands). */
 	inlineHint?: string;
+	/** Higher values sort earlier in TUI slash-command autocomplete. */
+	priority?: number;
 }
 
 /** Parsed slash-command text after stripping the leading "/". */

package/src/system-prompt.ts

@@ -356,6 +356,10 @@ export interface BuildSystemPromptOptions {
 	mcpDiscoveryMode?: boolean;
 	/** Discoverable MCP server summaries to advertise when discovery mode is active. */
 	mcpDiscoveryServerSummaries?: string[];
+	/** Whether built-in tool discovery ("all" mode) is active; enables the tool-discovery prompt block. */
+	toolDiscoveryActive?: boolean;
+	/** Hidden discoverable tools to advertise (name + one-line summary) when tool discovery is active. */
+	discoverableTools?: Array<{ name: string; summary: string }>;
 	/** Encourage the agent to delegate via tasks unless changes are trivial. */
 	eagerTasks?: boolean;
 	/** Rules with alwaysApply=true — their full content is injected into the prompt. */
@@ -394,6 +398,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		intentField,
 		mcpDiscoveryMode = false,
 		mcpDiscoveryServerSummaries = [],
+		toolDiscoveryActive = false,
+		discoverableTools = [],
 		eagerTasks = false,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
@@ -572,6 +578,8 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		mcpDiscoveryMode,
 		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
 		mcpDiscoveryServerSummaries,
+		toolDiscoveryActive,
+		discoverableTools,
 		eagerTasks,
 		secretsEnabled,
 	};

package/src/task/executor.ts

@@ -1535,6 +1535,11 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					);
 					await awaitAbortable(session.waitForIdle());
 				} catch (err) {
+					// An abort (parent cancel, session shutdown, timeout) rejects
+					// awaitAbortable with ToolAbortError — a cancellation, not a prompt
+					// failure. Mirror the outer catch's `!abortSignal.aborted` guard so
+					// expected cancellations aren't logged at error level.
+					if (abortSignal.aborted || err instanceof ToolAbortError) break;
 					logger.error("Subagent prompt failed", {
 						error: err instanceof Error ? err.message : String(err),
 					});

package/src/tools/ast-grep.ts

@@ -223,13 +223,16 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 				const modelOut: string[] = [];
 				const displayOut: string[] = [];
 				const fileMatches = matchesByFile.get(relativePath) ?? [];
-				const lineNumberWidth = fileMatches.reduce((width, match) => {
-					const lineCount = match.text.split("\n").length;
-					const endLine = match.startLine + lineCount - 1;
-					return Math.max(width, String(match.startLine).length, String(endLine).length);
-				}, 0);
-				for (const match of fileMatches) {
-					const matchLines = match.text.split("\n");
+				const preparedMatches = fileMatches.map(match => {
+					const lines = match.text.split("\n");
+					const endLine = match.startLine + lines.length - 1;
+					return { match, lines, endLine };
+				});
+				const lineNumberWidth = preparedMatches.reduce(
+					(width, entry) => Math.max(width, String(entry.match.startLine).length, String(entry.endLine).length),
+					0,
+				);
+				for (const { match, lines: matchLines } of preparedMatches) {
 					for (let index = 0; index < matchLines.length; index++) {
 						const lineNumber = match.startLine + index;
 						const isMatch = index === 0;

package/src/tools/bash.ts

@@ -14,7 +14,10 @@ import bashDescription from "../prompts/tools/bash.md" with { type: "text" };
 import type { ClientBridgeTerminalExitStatus, ClientBridgeTerminalOutput } from "../session/client-bridge";
 import { DEFAULT_MAX_BYTES, streamTailUpdates, TailBuffer } from "../session/streaming-output";
 import { buildSkcRuntimeSessionEnv } from "../skc-runtime/goal-mode-request";
-import { SKC_RESTRICTED_ROLE_AGENT_BASH_ENV } from "../skc-runtime/restricted-role-agent-bash";
+import {
+	SKC_RALPLAN_ARTIFACT_ENV,
+	SKC_RESTRICTED_ROLE_AGENT_BASH_ENV,
+} from "../skc-runtime/restricted-role-agent-bash";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import { getSixelLineMask } from "../utils/sixel";
@@ -530,13 +533,24 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 
 		const rawCommand = input.command;
 		const allowedPrefixes = this.session.bashAllowedPrefixes;
+		const isRestrictedRalplanArtifactEnv =
+			allowedPrefixes &&
+			allowedPrefixes.length > 0 &&
+			this.session.bashRestrictionProfile !== "read-only" &&
+			env &&
+			Object.keys(env).length === 1 &&
+			Object.hasOwn(env, SKC_RALPLAN_ARTIFACT_ENV) &&
+			rawCommand.includes(`--artifact-env ${SKC_RALPLAN_ARTIFACT_ENV}`);
 		if (
 			(this.session.bashRestrictionProfile === "read-only" || (allowedPrefixes && allowedPrefixes.length > 0)) &&
 			env &&
-			Object.keys(env).length > 0
+			Object.keys(env).length > 0 &&
+			!isRestrictedRalplanArtifactEnv
 		) {
 			const mode = this.session.bashRestrictionProfile === "read-only" ? "Read-only" : "Restricted role-agent";
-			throw new ToolError(`${mode} bash does not allow per-command env overrides.`);
+			throw new ToolError(
+				`${mode} bash only allows the ${SKC_RALPLAN_ARTIFACT_ENV} env override for --artifact-env.`,
+			);
 		}
 		if (allowedPrefixes && allowedPrefixes.length > 0) {
 			const commandsToCheck = rawCommand === command ? [command] : [rawCommand, command];
@@ -597,11 +611,13 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 					await Promise.all(
 						Object.entries(env).map(async ([key, value]) => [
 							key,
-							await expandInternalUrls(value, {
-								...internalUrlOptions,
-								ensureLocalParentDirs: true,
-								noEscape: true,
-							}),
+							key === SKC_RALPLAN_ARTIFACT_ENV
+								? value
+								: await expandInternalUrls(value, {
+										...internalUrlOptions,
+										ensureLocalParentDirs: true,
+										noEscape: true,
+									}),
 						]),
 					),
 				)
@@ -817,9 +833,22 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			});
 		}
 
+		// Route through the client terminal when the client advertises the terminal capability.
+		// Skip when pty=true (PTY needs the local terminal UI).
+		const clientBridge =
+			this.session.bashRestrictionProfile === "read-only" ? undefined : this.session.getClientBridge?.();
+		const clientTerminalActive = Boolean(clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty);
+
 		const autoBgManager = AsyncJobManager.instance();
-		if (this.#autoBackgroundEnabled && !pty && autoBgManager) {
-			const autoBackgroundWaitMs = this.#resolveAutoBackgroundWaitMs(timeoutMs);
+		// Run non-PTY bash through the managed job path so Ctrl+B-twice fold-on-demand works
+		// even when auto-background is disabled. When a client terminal will handle the
+		// command, keep the existing bridge path unless auto-background is enabled.
+		if (!pty && autoBgManager && (this.#autoBackgroundEnabled || !clientTerminalActive)) {
+			// With auto-background off, wait past the command's own timeout so the job only
+			// leaves the foreground on an explicit Ctrl+B fold, never on an auto-background timer.
+			const autoBackgroundWaitMs = this.#autoBackgroundEnabled
+				? this.#resolveAutoBackgroundWaitMs(timeoutMs)
+				: timeoutMs + 1_000;
 			const startBackgrounded = autoBackgroundWaitMs === 0;
 			const job = this.#startManagedBashJob({
 				command,
@@ -875,10 +904,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			});
 		}
 
-		// Route through the client terminal when the client advertises the terminal capability.
-		// Skip when pty=true (PTY needs the local terminal UI).
-		const clientBridge =
-			this.session.bashRestrictionProfile === "read-only" ? undefined : this.session.getClientBridge?.();
 		if (clientBridge?.capabilities.terminal && clientBridge.createTerminal && !pty) {
 			const handle = await clientBridge.createTerminal({
 				command,

package/src/tools/index.ts

@@ -325,7 +325,14 @@ export type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool |
 export type BuiltinToolLoadMode = "essential" | "discoverable";
 
 /** Default essential tool names when tools.essentialOverride is empty. */
-export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = ["read", "bash", "edit"] as const;
+export const DEFAULT_ESSENTIAL_TOOL_NAMES: readonly string[] = [
+	"read",
+	"bash",
+	"edit",
+	"write",
+	"search",
+	"find",
+] as const;
 
 /**
  * Resolve the active essential built-in tool names from settings.

package/src/tools/skill.ts

@@ -50,7 +50,7 @@ export class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails
 	readonly name = "skill";
 	readonly label = "Skill";
 	readonly summary = "Chain into another available skill in the current turn";
-	readonly loadMode = "discoverable";
+	readonly loadMode = "essential";
 	readonly description: string;
 	readonly parameters = skillSchema;
 	readonly strict = true;