@sayknow-cli/coding-agent 0.3.7 → 0.3.9

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

@@ -1,17 +1,18 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import type { ThinkingLevel } from "@sayknow-cli/agent-core";
+import { ThinkingLevel } from "@sayknow-cli/agent-core";
 import { type Model, modelsAreEqual } from "@sayknow-cli/ai";
 import { getOAuthProviders } from "@sayknow-cli/ai/utils/oauth";
 import { Spacer, Text } from "@sayknow-cli/tui";
 import { setProjectDir } from "@sayknow-cli/utils";
 import { jobElapsedMs } from "../async";
-import { materializeActiveModelProfileAssignment } from "../config/model-profile-activation";
+import { materializeActiveModelProfileAssignments } from "../config/model-profile-activation";
 import {
 	SKC_MODEL_ASSIGNMENT_TARGET_IDS,
 	SKC_MODEL_ASSIGNMENT_TARGETS,
 	type SkcModelAssignmentTargetId,
 } from "../config/model-registry";
+
 import {
 	extractExplicitThinkingSelector,
 	formatModelSelectorValue,
@@ -32,6 +33,7 @@ import {
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
 import { parseThinkingLevel } from "../thinking";
+import { getDisplayChangelogEntries } from "../utils/changelog";
 import { buildContextReportText } from "./helpers/context-report";
 import { buildFastStatusReport } from "./helpers/fast-status-report";
 import { formatDuration } from "./helpers/format";
@@ -52,6 +54,13 @@ export type { BuiltinSlashCommand, SubcommandDef } from "./types";
 /** TUI-specific runtime accepted by `executeBuiltinSlashCommand`. */
 export type BuiltinSlashCommandRuntime = TuiSlashCommandRuntime;
 
+type SkcModelBatchAssignmentTargetId = "all-role-agents" | "all-targets";
+type ParsedModelCommandArgs =
+	| { kind: "summary" }
+	| { kind: "assign"; targetId: SkcModelAssignmentTargetId | SkcModelBatchAssignmentTargetId; selector: string };
+
+const SKC_MODEL_ROLE_AGENT_TARGET_IDS: SkcModelAssignmentTargetId[] = ["executor", "architect", "planner", "critic"];
+
 function fastStatusRoleTargets(): Array<{ id: SkcModelAssignmentTargetId; label: string; isSubagentRole: boolean }> {
 	return SKC_MODEL_ASSIGNMENT_TARGET_IDS.map(id => ({
 		id,
@@ -60,6 +69,32 @@ function fastStatusRoleTargets(): Array<{ id: SkcModelAssignmentTargetId; label:
 	}));
 }
 
+function toSlashCommandRuntime(runtime: TuiSlashCommandRuntime): SlashCommandRuntime {
+	const ctx = runtime.ctx;
+	return {
+		session: ctx.session,
+		sessionManager: ctx.sessionManager,
+		settings: ctx.settings,
+		cwd: ctx.sessionManager.getCwd(),
+		output: (text: string) => {
+			ctx.showStatus(text);
+		},
+		refreshCommands: () => ctx.refreshSlashCommandState(),
+		reloadPlugins: async () => {
+			const projectPath = await resolveActiveProjectRegistryPath(ctx.sessionManager.getCwd());
+			clearPluginRootsAndCaches(projectPath ? [projectPath] : undefined);
+			await ctx.refreshSlashCommandState();
+			await ctx.session.refreshSshTool({ activateIfAvailable: true });
+		},
+		notifyTitleChanged: () => {
+			ctx.statusLine.invalidate();
+			ctx.updateEditorBorderColor();
+			ctx.ui.requestRender();
+		},
+		notifyConfigChanged: () => ctx.notifyConfigChanged?.(),
+	};
+}
+
 function parseProviderSetupSlashArgs(args: string): {
 	preset?: string;
 	compat?: string;
@@ -147,22 +182,37 @@ function formatModelAssignmentSummary(runtime: SlashCommandRuntime): string {
 	return lines.join("\n");
 }
 
-function parseModelCommandArgs(args: string): { targetId: SkcModelAssignmentTargetId; selector: string } {
+function parseModelCommandArgs(args: string): ParsedModelCommandArgs {
 	const tokens = args.trim().split(/\s+/).filter(Boolean);
 	const first = tokens[0]?.toLowerCase();
-	const explicitTarget = SKC_MODEL_ASSIGNMENT_TARGET_IDS.includes(first as SkcModelAssignmentTargetId)
-		? (first as SkcModelAssignmentTargetId)
-		: undefined;
+	if (first === "roles" || first === "assignments") return { kind: "summary" };
+
+	const parseTarget = (
+		token: string | undefined,
+	): SkcModelAssignmentTargetId | SkcModelBatchAssignmentTargetId | undefined => {
+		const normalized = token?.toLowerCase();
+		if (SKC_MODEL_ASSIGNMENT_TARGET_IDS.includes(normalized as SkcModelAssignmentTargetId)) {
+			return normalized as SkcModelAssignmentTargetId;
+		}
+		if (normalized === "all-role-agents" || normalized === "all-targets") return normalized;
+		return undefined;
+	};
+
+	if (first === "assign") {
+		const targetId = parseTarget(tokens[1]);
+		if (targetId) return { kind: "assign", targetId, selector: tokens.slice(2).join(" ") };
+		return { kind: "assign", targetId: "default", selector: tokens.slice(1).join(" ") };
+	}
+
+	const explicitTarget = parseTarget(first);
 	if (explicitTarget) {
-		return { targetId: explicitTarget, selector: tokens.slice(1).join(" ") };
+		return { kind: "assign", targetId: explicitTarget, selector: tokens.slice(1).join(" ") };
 	}
 	if (first === "set") {
-		const second = tokens[1]?.toLowerCase();
-		if (SKC_MODEL_ASSIGNMENT_TARGET_IDS.includes(second as SkcModelAssignmentTargetId)) {
-			return { targetId: second as SkcModelAssignmentTargetId, selector: tokens.slice(2).join(" ") };
-		}
+		const targetId = parseTarget(tokens[1]);
+		if (targetId) return { kind: "assign", targetId, selector: tokens.slice(2).join(" ") };
 	}
-	return { targetId: "default", selector: args.trim() };
+	return { kind: "assign", targetId: "default", selector: args.trim() };
 }
 
 function splitExplicitThinkingSelector(selector: string): { baseSelector: string; thinkingLevel?: ThinkingLevel } {
@@ -297,23 +347,123 @@ async function resolveModelCommandSelection(
 	};
 }
 
+function getModelAssignmentTargetIds(
+	targetId: SkcModelAssignmentTargetId | SkcModelBatchAssignmentTargetId,
+): SkcModelAssignmentTargetId[] {
+	if (targetId === "all-role-agents") return [...SKC_MODEL_ROLE_AGENT_TARGET_IDS];
+	if (targetId === "all-targets") return [...SKC_MODEL_ASSIGNMENT_TARGET_IDS];
+	return [targetId];
+}
+
+function formatModelAssignmentSuccess(
+	targetId: SkcModelAssignmentTargetId | SkcModelBatchAssignmentTargetId,
+	selector: string,
+): string {
+	if (targetId === "all-role-agents") {
+		return `Role-agent models set to ${selector} for EXECUTOR, ARCHITECT, PLANNER, CRITIC.`;
+	}
+	if (targetId === "all-targets") {
+		return `All model targets set to ${selector} for DEFAULT, EXECUTOR, ARCHITECT, PLANNER, CRITIC.`;
+	}
+	if (targetId === "default") return `Default model set to ${selector}.`;
+	return `${targetId} agent model set to ${selector}.`;
+}
+
 function modelSelectionUsage(runtime: SlashCommandRuntime, currentModelLine?: string): string {
 	return [
 		currentModelLine,
 		formatModelAssignmentSummary(runtime),
-		"ACP/text mode: use /model <model> for DEFAULT, or /model <target> <model> for EXECUTOR, ARCHITECT, PLANNER, or CRITIC.",
+		"Use /model <model> for DEFAULT, or /model <target> <model[:effort]> for EXECUTOR, ARCHITECT, PLANNER, or CRITIC.",
 		formatModelOnboardingGuidance(),
 	]
 		.filter((line): line is string => Boolean(line))
 		.join("\n\n");
 }
 
+const EFFORT_COMMAND_INPUT_HINT = "[inherit|off|minimal|low|medium|high|xhigh|max]";
+const EFFORT_COMMAND_ACCEPTED_VALUES = ["inherit", "off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+function effortCommandUsage(prefix?: string): string {
+	return [prefix, `Usage: /effort ${EFFORT_COMMAND_INPUT_HINT}`]
+		.filter((line): line is string => Boolean(line))
+		.join("\n");
+}
+
+function formatEffortStatus(runtime: SlashCommandRuntime): string {
+	const current = runtime.session.thinkingLevel ?? ThinkingLevel.Off;
+	const configuredDefault = runtime.settings.get("defaultThinkingLevel");
+	const supported = runtime.session.getAvailableThinkingLevels();
+	return [
+		`Current effective effort: ${current}`,
+		`Configured default effort: ${configuredDefault}`,
+		`Accepted values: ${EFFORT_COMMAND_ACCEPTED_VALUES.join(", ")}`,
+		`Current-model supported levels: ${supported.length > 0 ? supported.join(", ") : "(none reported)"}`,
+	].join("\n");
+}
+
+async function handleEffortCommand(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const tokens = command.args.trim().split(/\s+/).filter(Boolean);
+	if (tokens.length === 0) {
+		await runtime.output(formatEffortStatus(runtime));
+		return commandConsumed();
+	}
+	if (tokens.length !== 1) {
+		return usage(effortCommandUsage("Invalid effort input."), runtime);
+	}
+
+	const requestedToken = tokens[0];
+	const requestedLevel = parseThinkingLevel(requestedToken);
+	if (!requestedToken || !requestedLevel) {
+		return usage(effortCommandUsage(`Invalid effort: ${tokens[0] ?? ""}.`), runtime);
+	}
+
+	const levelToApply =
+		requestedLevel === ThinkingLevel.Inherit ? runtime.settings.get("defaultThinkingLevel") : requestedLevel;
+	runtime.session.setThinkingLevel(levelToApply, false);
+	const effectiveLevel = runtime.session.thinkingLevel ?? ThinkingLevel.Off;
+	const requestedLabel =
+		requestedLevel === ThinkingLevel.Inherit ? `${requestedLevel} (${levelToApply})` : requestedLevel;
+	const clampedSuffix =
+		effectiveLevel === levelToApply ? "" : ` Requested ${levelToApply}; effective ${effectiveLevel}.`;
+	await runtime.output(
+		`Reasoning effort set to ${requestedLabel}. Effective effort: ${effectiveLevel}.${clampedSuffix}`,
+	);
+	return commandConsumed();
+}
+
 function refreshStatusLine(ctx: InteractiveModeContext): void {
 	ctx.statusLine.invalidate();
 	ctx.updateEditorTopBorder();
 	ctx.ui.requestRender();
 }
 
+type ChangelogCommandArgs = { showFull: boolean } | { error: string };
+
+function parseChangelogCommandArgs(args: string): ChangelogCommandArgs {
+	const normalized = args.trim().toLowerCase();
+	if (!normalized) return { showFull: false };
+	if (normalized === "full" || normalized === "--full") return { showFull: true };
+	return { error: "Usage: /changelog [full|--full]" };
+}
+
+function buildChangelogCommandOutput(showFull: boolean): string {
+	const allEntries = getDisplayChangelogEntries();
+	const entriesToShow = showFull ? allEntries : allEntries.slice(0, 3);
+	const changelogMarkdown =
+		entriesToShow.length > 0
+			? [...entriesToShow]
+					.reverse()
+					.map(entry => entry.content)
+					.join("\n\n")
+			: "No changelog entries found.";
+	const title = showFull ? "Full Changelog" : "Recent Changes";
+	const hint = showFull ? "" : "\n\nUse `/changelog --full` to view the complete changelog.";
+	return `${title}\n\n${changelogMarkdown}${hint}`;
+}
+
 const shutdownHandlerTui = (_command: ParsedSlashCommand, runtime: TuiSlashCommandRuntime): SlashCommandResult => {
 	runtime.ctx.editor.setText("");
 	void runtime.ctx.shutdown();
@@ -373,9 +523,16 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		acpDescription: "Show current model selection",
 		inlineHint: "[target] <model>",
 		acpInputHint: "[target] <model>",
+		allowArgs: true,
 		handle: async (command, runtime) => {
 			if (command.args) {
 				const parsedArgs = parseModelCommandArgs(command.args);
+				if (parsedArgs.kind === "summary") {
+					await runtime.output(formatModelAssignmentSummary(runtime));
+					return commandConsumed();
+				}
+
+				const targetIds = getModelAssignmentTargetIds(parsedArgs.targetId);
 				const modelId = parsedArgs.selector;
 				if (!modelId) {
 					return usage(
@@ -389,24 +546,9 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 				}
 				const { selection } = resolution;
 				try {
-					const persistedSelector = formatModelSelectorValue(selection.selector, selection.thinkingLevel);
-					if (parsedArgs.targetId === "default") {
-						await runtime.session.setModel(selection.model, "default", {
-							selector: selection.selector,
-							thinkingLevel: selection.thinkingLevel,
-						});
-						materializeActiveModelProfileAssignment({
-							session: runtime.session,
-							settings: runtime.settings,
-							role: parsedArgs.targetId,
-							selector: persistedSelector,
-						});
-						if (selection.thinkingLevel) {
-							runtime.session.setThinkingLevel(selection.thinkingLevel);
-						}
-						await runtime.output(`Default model set to ${persistedSelector}.`);
-						await runtime.notifyTitleChanged?.();
-					} else {
+					const includesDefault = targetIds.includes("default");
+					const includesRoleAgent = targetIds.some(role => role !== "default");
+					if (includesRoleAgent) {
 						const apiKey = await runtime.session.modelRegistry.getApiKey(
 							selection.model,
 							runtime.session.sessionId,
@@ -414,31 +556,60 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 						if (!apiKey) {
 							throw new Error(`No API key for ${selection.model.provider}/${selection.model.id}`);
 						}
-						const overrides = runtime.settings.get("task.agentModelOverrides");
+					}
+
+					const overrides = runtime.settings.get("task.agentModelOverrides");
+					const assignments = new Map<SkcModelAssignmentTargetId, string>();
+					const existingDefaultThinkingLevel =
+						selection.thinkingLevel !== undefined
+							? selection.thinkingLevel
+							: runtime.session.getActiveModelProfile?.()
+								? undefined
+								: extractExplicitThinkingSelector(runtime.settings.getModelRole("default"), runtime.settings);
+					const persistedSelector = formatModelSelectorValue(selection.selector, existingDefaultThinkingLevel);
+					for (const targetId of targetIds) {
+						if (targetId === "default") {
+							assignments.set(targetId, persistedSelector);
+							continue;
+						}
 						const thinkingLevel =
-							selection.thinkingLevel ??
-							extractExplicitThinkingSelector(overrides[parsedArgs.targetId], runtime.settings);
-						const roleSelector = formatModelSelectorValue(selection.selector, thinkingLevel);
-						const materializedProfile = materializeActiveModelProfileAssignment({
-							session: runtime.session,
-							settings: runtime.settings,
-							role: parsedArgs.targetId,
-							selector: roleSelector,
+							selection.thinkingLevel ?? extractExplicitThinkingSelector(overrides[targetId], runtime.settings);
+						assignments.set(targetId, formatModelSelectorValue(selection.selector, thinkingLevel));
+					}
+
+					if (includesDefault) {
+						await runtime.session.setModel(selection.model, "default", {
+							selector: selection.selector,
+							thinkingLevel: existingDefaultThinkingLevel,
 						});
-						if (!materializedProfile) {
-							const target = SKC_MODEL_ASSIGNMENT_TARGETS[parsedArgs.targetId];
+						if (existingDefaultThinkingLevel) {
+							runtime.session.setThinkingLevel(existingDefaultThinkingLevel);
+						}
+					}
+
+					const materializedProfile = materializeActiveModelProfileAssignments({
+						session: runtime.session,
+						settings: runtime.settings,
+						assignments,
+					});
+					if (!materializedProfile) {
+						for (const [targetId, selector] of assignments) {
+							const target = SKC_MODEL_ASSIGNMENT_TARGETS[targetId];
 							if (target.settingsPath === "modelRoles") {
-								runtime.settings.setModelRole(parsedArgs.targetId, roleSelector);
+								runtime.settings.setModelRole(targetId, selector);
 							} else {
-								runtime.settings.set("task.agentModelOverrides", {
-									...overrides,
-									[parsedArgs.targetId]: roleSelector,
-								});
+								runtime.settings.setAgentModelOverride(targetId, selector);
 							}
 						}
-						runtime.settings.getStorage()?.recordModelUsage(`${selection.model.provider}/${selection.model.id}`);
-						await runtime.output(`${parsedArgs.targetId} agent model set to ${roleSelector}.`);
 					}
+					runtime.settings.getStorage()?.recordModelUsage(`${selection.model.provider}/${selection.model.id}`);
+					await runtime.output(
+						formatModelAssignmentSuccess(
+							parsedArgs.targetId,
+							assignments.get(targetIds[0] ?? "default") ?? persistedSelector,
+						),
+					);
+					if (includesDefault) await runtime.notifyTitleChanged?.();
 					await runtime.notifyConfigChanged?.();
 					return commandConsumed();
 				} catch (err) {
@@ -455,11 +626,45 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			);
 			return commandConsumed();
 		},
-		handleTui: (_command, runtime) => {
+		handleTui: async (command, runtime) => {
+			if (command.args.trim()) {
+				const result = await BUILTIN_SLASH_COMMAND_LOOKUP.get(command.name)?.handle?.(
+					command,
+					toSlashCommandRuntime(runtime),
+				);
+				runtime.ctx.statusLine.invalidate();
+				runtime.ctx.updateEditorBorderColor();
+				runtime.ctx.editor.setText("");
+				runtime.ctx.ui.requestRender();
+				return result;
+			}
 			runtime.ctx.showModelSelector();
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "effort",
+		description: "Show or set model reasoning effort",
+		acpDescription: "Show or set model reasoning effort",
+		inlineHint: EFFORT_COMMAND_INPUT_HINT,
+		acpInputHint: EFFORT_COMMAND_INPUT_HINT,
+		allowArgs: true,
+		handle: handleEffortCommand,
+		handleTui: async (command, runtime) => {
+			if (command.args.trim()) {
+				const result = await handleEffortCommand(command, toSlashCommandRuntime(runtime));
+				runtime.ctx.statusLine.invalidate();
+				runtime.ctx.updateEditorBorderColor();
+				runtime.ctx.updateEditorTopBorder();
+				runtime.ctx.editor.setText("");
+				runtime.ctx.ui.requestRender();
+				return result;
+			}
+
+			runtime.ctx.showEffortSelector();
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "fast",
 		description: "Toggle priority service tier (OpenAI service_tier=priority, Anthropic speed=fast)",
@@ -720,6 +925,29 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			runtime.ctx.editor.setText("");
 		},
 	},
+	{
+		name: "changelog",
+		description: "Show release notes and changelog entries",
+		inlineHint: "[full|--full]",
+		subcommands: [{ name: "full", description: "Show complete changelog" }],
+		allowArgs: true,
+		handle: async (command, runtime) => {
+			const parsed = parseChangelogCommandArgs(command.args);
+			if ("error" in parsed) return usage(parsed.error, runtime);
+			await runtime.output(buildChangelogCommandOutput(parsed.showFull));
+			return commandConsumed();
+		},
+		handleTui: async (command, runtime) => {
+			const parsed = parseChangelogCommandArgs(command.args);
+			if ("error" in parsed) {
+				runtime.ctx.showError(parsed.error);
+				runtime.ctx.editor.setText("");
+				return;
+			}
+			await runtime.ctx.handleChangelogCommand(parsed.showFull);
+			runtime.ctx.editor.setText("");
+		},
+	},
 	{
 		name: "help",
 		priority: 100,
@@ -967,6 +1195,22 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 			await runtime.ctx.handleSSHCommand(command.text);
 		},
 	},
+	{
+		name: "clear",
+		priority: 97,
+		description: "Clear context while preserving this session ID",
+		acpDescription: "Clear context while preserving this session ID",
+		handle: async (_command, runtime) => {
+			const beforeSessionId = runtime.session.sessionId;
+			await runtime.session.clearContext();
+			await runtime.output(`Context cleared. Session preserved: ${beforeSessionId}`);
+			return commandConsumed();
+		},
+		handleTui: async (_command, runtime) => {
+			runtime.ctx.editor.setText("");
+			await runtime.ctx.handleContextClearCommand();
+		},
+	},
 	{
 		name: "new",
 		priority: 96,
@@ -1227,6 +1471,7 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 	},
 	{
 		name: "exit",
+		aliases: ["quit"],
 		description: "Exit the application",
 		handleTui: shutdownHandlerTui,
 	},
@@ -1307,29 +1552,8 @@ export async function executeBuiltinSlashCommand(
 		return true;
 	}
 	if (command.handle) {
-		// No TUI-specific override → adapt the ACP/text-mode `handle` to the
-		// TUI by routing `runtime.output` through `ctx.showStatus`, clearing
-		// the editor after the call, and reusing the active session's plugin
-		// reload pipeline. Spec authors get a single body usable from either
-		// dispatcher without forcing every TUI test to construct the full
-		// `SlashCommandRuntime` shape.
 		const ctx = runtime.ctx;
-		const adapted: SlashCommandRuntime = {
-			session: ctx.session,
-			sessionManager: ctx.sessionManager,
-			settings: ctx.settings,
-			cwd: ctx.sessionManager.getCwd(),
-			output: (text: string) => {
-				ctx.showStatus(text);
-			},
-			refreshCommands: () => ctx.refreshSlashCommandState(),
-			reloadPlugins: async () => {
-				const projectPath = await resolveActiveProjectRegistryPath(ctx.sessionManager.getCwd());
-				clearPluginRootsAndCaches(projectPath ? [projectPath] : undefined);
-				await ctx.refreshSlashCommandState();
-				await ctx.session.refreshSshTool({ activateIfAvailable: true });
-			},
-		};
+		const adapted = toSlashCommandRuntime(runtime);
 		const result = await command.handle(parsed, adapted);
 		ctx.editor.setText("");
 		if (result && typeof result === "object" && "prompt" in result) return result.prompt;

package/src/system-prompt.ts

@@ -14,6 +14,7 @@ import { loadSkills, type Skill } from "./extensibility/skills";
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import projectPromptTemplate from "./prompts/system/project-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
+import volatileProjectContextTemplate from "./prompts/system/volatile-project-context.md" with { type: "text" };
 import { shortenPath } from "./tools/render-utils";
 import { AGENTS_MD_LIMIT, buildWorkspaceTree, type WorkspaceTree } from "./workspace-tree";
 
@@ -242,9 +243,12 @@ function dedupeExactContextFiles(
 }
 
 /**
- * Load all project context files using the capability API.
+ * Load all context files using the capability API.
  * Returns {path, content, depth} entries for all discovered context files.
- * Files are sorted by depth (descending) so files closer to cwd appear last/more prominent.
+ * Native user-global files (`~/.skc/agent/AGENTS.md`) come first, then project
+ * files sorted by depth (descending) so files closer to cwd appear last/more
+ * prominent. User-home files from foreign providers (`~/.claude/CLAUDE.md`,
+ * `~/.codex/AGENTS.md`, …) stay excluded — only skc's own user config applies.
  */
 export async function loadProjectContextFiles(
 	options: LoadContextFilesOptions = {},
@@ -252,28 +256,32 @@ export async function loadProjectContextFiles(
 	const resolvedCwd = options.cwd ?? getProjectDir();
 
 	const result = await loadCapability(contextFileCapability.id, { cwd: resolvedCwd });
+	const items = result.items as ContextFile[];
+
+	// Native user-global context applies everywhere and is least specific, so it
+	// renders first — project files rendered later take precedence over it.
+	const userFiles = items
+		.filter(item => item.level === "user" && item._source.provider === "native")
+		.map(item => ({ path: item.path, content: item.content }));
 
 	// Convert project-level ContextFile items and preserve depth info
-	const files = result.items
-		.filter(item => (item as ContextFile).level === "project")
-		.map(item => {
-			const contextFile = item as ContextFile;
-			return {
-				path: contextFile.path,
-				content: contextFile.content,
-				depth: contextFile.depth,
-			};
-		});
+	const projectFiles = items
+		.filter(item => item.level === "project")
+		.map(item => ({
+			path: item.path,
+			content: item.content,
+			depth: item.depth,
+		}));
 
 	// Sort by depth (descending): higher depth (farther from cwd) comes first,
 	// so files closer to cwd appear later and are more prominent
-	files.sort((a, b) => {
+	projectFiles.sort((a, b) => {
 		const depthA = a.depth ?? -1;
 		const depthB = b.depth ?? -1;
 		return depthB - depthA;
 	});
 
-	return dedupeExactContextFiles(files);
+	return dedupeExactContextFiles([...userFiles, ...projectFiles]);
 }
 
 /**
@@ -368,6 +376,13 @@ export interface BuildSystemPromptOptions {
 	secretsEnabled?: boolean;
 	/** Pre-loaded workspace tree (skips discovery if provided). May be a Promise to allow early kick-off. */
 	workspaceTree?: WorkspaceTree | Promise<WorkspaceTree>;
+	/**
+	 * Render a trimmed role-agent base prompt for subagent sessions: omits the
+	 * workflow-surface/routing/self-awareness (`<skc-runtime>`) and `<soul>` blocks
+	 * that only apply to the top-level interactive/print agent. Tool safety, repo
+	 * safety, and the completion contract are retained. Default: false.
+	 */
+	subagent?: boolean;
 }
 
 /** Result of building provider-facing system prompt messages. */
@@ -375,6 +390,29 @@ export interface BuildSystemPromptResult {
 	/** Ordered system prompt blocks. Providers should preserve entries as distinct messages/blocks. */
 	systemPrompt: string[];
 }
+export interface BuildVolatileProjectContextOptions {
+	cwd?: string;
+	date?: string;
+	workspaceTree?: WorkspaceTree;
+}
+
+export function buildVolatileProjectContext(options: BuildVolatileProjectContextOptions = {}): string {
+	const resolvedCwd = options.cwd ?? getProjectDir();
+	const date = options.date ?? new Date().toISOString().slice(0, 10);
+	return prompt
+		.render(volatileProjectContextTemplate, {
+			date,
+			cwd: shortenPath(resolvedCwd.replace(/\\/g, "/")),
+			workspaceTree: options.workspaceTree ?? {
+				rootPath: resolvedCwd,
+				rendered: "",
+				truncated: false,
+				totalLines: 0,
+				agentsMdFiles: [],
+			},
+		})
+		.trim();
+}
 
 /** Build the system prompt with tools, guidelines, and context */
 export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}): Promise<BuildSystemPromptResult> {
@@ -403,6 +441,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		eagerTasks = false,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
+		subagent = false,
 	} = options;
 	const resolvedCwd = cwd ?? getProjectDir();
 
@@ -534,6 +573,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	// Build tool descriptions for system prompt rendering.
 	const toolPromptNames = new Map<string, string>(toolNames.map(name => [name, tools?.get(name)?.wireName ?? name]));
 	const toolRefs = Object.fromEntries(toolPromptNames.entries());
+	const hasHiddenToolDiscoveryTool = Object.hasOwn(toolRefs, "search_tool_bm25");
 	const toolInfo = toolNames.map(name => ({
 		name: toolPromptNames.get(name) ?? name,
 		internalName: name,
@@ -575,13 +615,14 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		cwd: promptCwd,
 		intentTracing: !!intentField,
 		intentField: intentField ?? "",
-		mcpDiscoveryMode,
+		mcpDiscoveryMode: mcpDiscoveryMode && hasHiddenToolDiscoveryTool,
 		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
 		mcpDiscoveryServerSummaries,
-		toolDiscoveryActive,
+		toolDiscoveryActive: toolDiscoveryActive && hasHiddenToolDiscoveryTool,
 		discoverableTools,
 		eagerTasks,
 		secretsEnabled,
+		subagent,
 	};
 	const rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);
 	const systemPrompt = [rendered];