@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/src/notifications/telegram-daemon.ts

@@ -10,7 +10,14 @@ import type { DaemonRuntimeInfo } from "../daemon/control-types";
 import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
 import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
 import { parseInThreadConfigCommand } from "./config-commands";
-import { buildCompactChoiceGrid, TELEGRAM_PARSE_MODE } from "./html-format";
+import { daemonPaths } from "./daemon-paths";
+import {
+	buildCompactChoiceGrid,
+	code,
+	splitTelegramHtml,
+	TELEGRAM_MESSAGE_LIMIT,
+	TELEGRAM_PARSE_MODE,
+} from "./html-format";
 import type {
 	SessionCloseTarget,
 	SessionCreateTarget,
@@ -62,16 +69,6 @@ export interface DaemonState {
 	version: 1;
 	stoppedAt?: number;
 }
-
-export interface DaemonPaths {
-	dir: string;
-	lock: string;
-	state: string;
-	roots: string;
-	steal: string;
-	aliases: string;
-}
-
 export interface TelegramDaemonFs {
 	mkdir(path: string, opts?: fs.MakeDirectoryOptions): Promise<void>;
 	readFile(path: string, encoding: BufferEncoding): Promise<string>;
@@ -131,6 +128,24 @@ const QUEUED_REACTION = "👀";
 const PENDING_TOPIC_FRAME_LIMIT = 20;
 const CONSUMED_REACTION = "✅";
 
+function splitTelegramPlainText(text: string, max = TELEGRAM_MESSAGE_LIMIT): string[] {
+	if (text.length <= max) return [text];
+	const chunks: string[] = [];
+	let out = "";
+	for (const ch of text) {
+		if (out.length + ch.length > max) {
+			chunks.push(out);
+			out = "";
+		}
+		out += ch;
+	}
+	if (out) chunks.push(out);
+	return chunks;
+}
+function endpointGenerationKey(url: string, token: string): string {
+	return `${url}\0${token}`;
+}
+
 /**
  * Whether `err` is a transient network failure worth retrying. Telegram API
  * calls over HTTP/2 occasionally surface mid-stream `ECONNRESET` (and similar)
@@ -184,17 +199,7 @@ async function fetchWithRetry(
 	throw lastErr;
 }
 
-export function daemonPaths(agentDir: string): DaemonPaths {
-	const dir = path.join(agentDir, "notifications");
-	return {
-		dir,
-		lock: path.join(dir, "telegram-daemon.lock"),
-		state: path.join(dir, "telegram-daemon.state.json"),
-		roots: path.join(dir, "telegram-daemon.roots.json"),
-		steal: path.join(dir, "telegram-daemon.steal"),
-		aliases: path.join(dir, "telegram-callback-aliases.json"),
-	};
-}
+export { type DaemonPaths, daemonPaths } from "./daemon-paths";
 
 /**
  * Attach session-lifecycle control (create/close/resume) to the running daemon.
@@ -770,6 +775,7 @@ export interface TelegramDaemonOptions {
 interface SessionSocket {
 	sessionId: string;
 	token: string;
+	endpointKey: string;
 	ws: WebSocket;
 	pending: Map<string, { sessionId: string; actionId: string }>;
 	/** True once the server advertised the `client_ping_pong` capability. */
@@ -806,6 +812,8 @@ export class TelegramNotificationDaemon {
 	private readonly topicOwnerByIdentity = new Map<string, string>();
 	/** Non-identity frames held until identity creates the correct thread. */
 	private readonly pendingThreadedFrames = new Map<string, PendingThreadedFrame[]>();
+	/** Endpoint generation tombstones for sessions that already sent session_closed. */
+	private readonly closedEndpointKeys = new Map<string, string>();
 	/** True once the daemon has nudged the user to enable Threaded Mode. */
 	private threadedFallbackNoticeSent = false;
 	/** Sessions whose identity header was already sent flat (Threaded Mode off). */
@@ -1072,14 +1080,29 @@ export class TelegramNotificationDaemon {
 		threadId: number | undefined,
 	): Promise<boolean> {
 		if (!isLifecycleCommandText(text)) return false;
-		const reply = (body: string) =>
-			this.botApi
-				.call("sendMessage", {
-					chat_id: this.opts.chatId,
-					...(threadId !== undefined ? { message_thread_id: threadId } : {}),
-					text: body,
-				})
-				.catch(() => undefined);
+		const reply = async (body: string): Promise<void> => {
+			for (const text of splitTelegramPlainText(body)) {
+				await this.botApi
+					.call("sendMessage", {
+						chat_id: this.opts.chatId,
+						...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+						text,
+					})
+					.catch(() => undefined);
+			}
+		};
+		const replyHtml = async (body: string): Promise<void> => {
+			for (const text of splitTelegramHtml(body)) {
+				await this.botApi
+					.call("sendMessage", {
+						chat_id: this.opts.chatId,
+						...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+						text,
+						parse_mode: TELEGRAM_PARSE_MODE,
+					})
+					.catch(() => undefined);
+			}
+		};
 
 		if (!this.lifecycleControlActive) {
 			await reply("Session lifecycle control is not available right now.");
@@ -1098,11 +1121,12 @@ export class TelegramNotificationDaemon {
 			const recent = listRecentSessions({
 				sessionsRoot: path.join(this.opts.settings.getAgentDir(), "sessions"),
 				limit: 10,
+				includeInternal: false,
 			});
-			const lines = recent.length
-				? recent.map(e => `\u2022 ${e.sessionId}${e.path ? ` (${e.path})` : ""}`).join("\n")
+			const body = recent.length
+				? recent.map(e => `• ${code(e.sessionId)}${e.path ? ` (${code(e.path)})` : ""}`).join("\n")
 				: "No recent sessions.";
-			await reply(lines);
+			await replyHtml(body);
 			return true;
 		}
 
@@ -1205,7 +1229,9 @@ export class TelegramNotificationDaemon {
 				matches: msg => msg.type === "session_closed",
 				handle: async session => {
 					this.busy.delete(session.sessionId);
+					this.closedEndpointKeys.set(session.sessionId, session.endpointKey);
 					await this.deleteTopic(session.sessionId);
+					this.dropSession(session, "session_closed");
 				},
 			});
 	}
@@ -1242,6 +1268,9 @@ export class TelegramNotificationDaemon {
 					// would chase a dead, token-bearing record forever.
 					const pidAlive = this.opts.pidAlive ?? defaultPidAlive;
 					if (endpoint.stale || (endpoint.pid !== undefined && !pidAlive(endpoint.pid))) continue;
+					const endpointKey = endpointGenerationKey(endpoint.url, endpoint.token);
+					if (this.closedEndpointKeys.get(sessionId) === endpointKey) continue;
+					this.closedEndpointKeys.delete(sessionId);
 					this.connectSession(sessionId, endpoint.url, endpoint.token);
 				} catch {}
 			}
@@ -1251,9 +1280,12 @@ export class TelegramNotificationDaemon {
 	connectSession(sessionId: string, url: string, token: string): void {
 		const WS = this.opts.WebSocketImpl ?? WebSocket;
 		const ws = new WS(`${url}/?token=${encodeURIComponent(token)}`);
+		const endpointKey = endpointGenerationKey(url, token);
+		this.closedEndpointKeys.delete(sessionId);
 		const session: SessionSocket = {
 			sessionId,
 			token,
+			endpointKey,
 			ws,
 			pending: new Map(),
 			capable: false,
@@ -1631,12 +1663,14 @@ export class TelegramNotificationDaemon {
 						parse_mode: TELEGRAM_PARSE_MODE,
 					});
 				} else if (send.text) {
-					await this.botApi.call("sendMessage", {
-						chat_id: this.opts.chatId,
-						...threadField,
-						text: send.text,
-						parse_mode: TELEGRAM_PARSE_MODE,
-					});
+					for (const text of splitTelegramHtml(send.text)) {
+						await this.botApi.call("sendMessage", {
+							chat_id: this.opts.chatId,
+							...threadField,
+							text,
+							parse_mode: TELEGRAM_PARSE_MODE,
+						});
+					}
 				}
 			} catch {
 				// Best-effort: a failed send must never stop the daemon.
@@ -1839,13 +1873,17 @@ export class TelegramNotificationDaemon {
 			const inline_keyboard = buildCompactChoiceGrid(options, (i: number) =>
 				this.aliasTable.put({ sessionId: session.sessionId, actionId: msg.id, answer: i }),
 			);
-			const result = (await this.botApi.call("sendMessage", {
-				chat_id: this.opts.chatId,
-				...threadField,
-				text: rendered.text,
-				parse_mode: TELEGRAM_PARSE_MODE,
-				...(inline_keyboard.length ? { reply_markup: { inline_keyboard } } : {}),
-			})) as { result?: { message_id?: number } };
+			const chunks = splitTelegramHtml(rendered.text);
+			let result: { result?: { message_id?: number } } = {};
+			for (let i = 0; i < chunks.length; i++) {
+				result = (await this.botApi.call("sendMessage", {
+					chat_id: this.opts.chatId,
+					...threadField,
+					text: chunks[i]!,
+					parse_mode: TELEGRAM_PARSE_MODE,
+					...(i === chunks.length - 1 && inline_keyboard.length ? { reply_markup: { inline_keyboard } } : {}),
+				})) as { result?: { message_id?: number } };
+			}
 			const messageId = result.result?.message_id;
 			if (messageId !== undefined)
 				this.messageRoutes.set(String(messageId), { sessionId: session.sessionId, actionId: msg.id });
@@ -2005,6 +2043,10 @@ export class TelegramNotificationDaemon {
 					{ command: "verbose", description: "Mirror full tool output + reasoning in this thread" },
 					{ command: "lean", description: "Mirror assistant text + tool names only (default)" },
 					{ command: "redact", description: "Toggle redaction of streamed content: /redact <on|off>" },
+					{ command: "session_create", description: "Create a SKC session: path, worktree, or dir" },
+					{ command: "session_recent", description: "List recent SKC sessions" },
+					{ command: "session_close", description: "Close a SKC-managed session" },
+					{ command: "session_resume", description: "Resume or reattach a session" },
 				],
 			});
 		} catch {

package/src/notifications/telegram-reference.ts

@@ -20,8 +20,8 @@ import {
 	buildCompactChoiceGrid,
 	escapeHtml,
 	numberedOptionList,
+	splitTelegramHtml,
 	TELEGRAM_PARSE_MODE,
-	truncateTelegramHtml,
 } from "./html-format";
 import { renderThreadedFrame } from "./threaded-render";
 
@@ -37,6 +37,8 @@ export interface RenderedMessage {
 	inline_keyboard?: InlineButton[][];
 }
 
+type TelegramSend = (method: string, body: unknown) => Promise<Response>;
+
 /** Encode `actionId` + option `index` into Telegram callback_data (<=64 bytes). */
 export function encodeCallbackData(actionId: string, index: number): string {
 	return `r:${index}:${actionId}`.slice(0, 64);
@@ -131,14 +133,32 @@ export function buildActionMessage(action: {
 }): RenderedMessage {
 	if (action.kind === "idle") {
 		const text = action.summary ? `🟢 Agent idle\n${escapeHtml(action.summary)}` : "🟢 Agent idle";
-		return { text: truncateTelegramHtml(text) };
+		return { text };
 	}
 	const text = `❓ ${bold(action.question ?? "Question")}`;
 	const options = action.options ?? [];
-	if (options.length === 0) return { text: truncateTelegramHtml(`${text}\n\n(reply with text)`) };
+	if (options.length === 0) return { text: `${text}\n\n(reply with text)` };
 	const body = `${text}\n\n${numberedOptionList(options)}`;
 	const inline_keyboard = buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i));
-	return { text: truncateTelegramHtml(body), inline_keyboard };
+	return { text: body, inline_keyboard };
+}
+
+/** Send Telegram HTML text chunks sequentially so long messages preserve order. */
+export async function sendTelegramHtmlChunks(
+	send: TelegramSend,
+	chatId: string,
+	text: string,
+	inlineKeyboard?: InlineButton[][],
+): Promise<void> {
+	const chunks = splitTelegramHtml(text);
+	for (let i = 0; i < chunks.length; i++) {
+		await send("sendMessage", {
+			chat_id: chatId,
+			text: chunks[i]!,
+			parse_mode: TELEGRAM_PARSE_MODE,
+			...(i === chunks.length - 1 && inlineKeyboard ? { reply_markup: { inline_keyboard: inlineKeyboard } } : {}),
+		});
+	}
 }
 
 /** A protocol `reply` frame the client should send to the server. */
@@ -285,15 +305,15 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 	const ws = new WebSocket(`${url}/?token=${encodeURIComponent(token)}`);
 	let latestPendingAskId: string | undefined;
 
-	const send = (method: string, body: unknown): Promise<Response> =>
+	const send: TelegramSend = (method, body) =>
 		fetchImpl(`${api}/${method}`, {
 			method: "POST",
 			headers: { "content-type": "application/json" },
 			body: JSON.stringify(body),
 		});
 
-	ws.addEventListener("message", (ev: MessageEvent) => {
-		const msg = JSON.parse(String(ev.data)) as {
+	const handleServerMessage = async (data: string): Promise<void> => {
+		const msg = JSON.parse(data) as {
 			type: string;
 			kind?: "ask" | "idle";
 			id?: string;
@@ -311,12 +331,7 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 				options: msg.options,
 				summary: msg.summary,
 			});
-			void send("sendMessage", {
-				chat_id: opts.chatId,
-				text: rendered.text,
-				parse_mode: TELEGRAM_PARSE_MODE,
-				...(rendered.inline_keyboard ? { reply_markup: { inline_keyboard: rendered.inline_keyboard } } : {}),
-			});
+			await sendTelegramHtmlChunks(send, opts.chatId, rendered.text, rendered.inline_keyboard);
 		} else if (msg.type === "action_resolved" && msg.id === latestPendingAskId) {
 			latestPendingAskId = undefined;
 		} else {
@@ -325,9 +340,16 @@ export async function runTelegramReferenceClient(opts: TelegramReferenceOptions)
 			// session's forum topic; this reference shows the minimal handling.
 			const threaded = renderThreadedFrame(msg as never);
 			if (threaded?.text) {
-				void send("sendMessage", { chat_id: opts.chatId, text: threaded.text, parse_mode: TELEGRAM_PARSE_MODE });
+				await sendTelegramHtmlChunks(send, opts.chatId, threaded.text);
 			}
 		}
+	};
+
+	let messageQueue = Promise.resolve();
+	ws.addEventListener("message", ev => {
+		const data = String(ev.data);
+		messageQueue = messageQueue.catch(() => undefined).then(() => handleServerMessage(data));
+		void messageQueue.catch(() => undefined);
 	});
 
 	// Telegram long-poll loop.

package/src/notifications/threaded-render.ts

@@ -49,6 +49,7 @@ interface ThreadedFrame {
 	tokenUsage?: unknown;
 	model?: unknown;
 	diff?: unknown;
+	cwd?: unknown;
 	// turn_stream
 	phase?: unknown;
 	text?: unknown;
@@ -89,18 +90,25 @@ export function formatIdentityHeader(frame: {
 /** Format a streamed context update into a compact block (omitting empty fields). */
 export function formatContextUpdate(frame: ThreadedFrame): string | undefined {
 	const lines: string[] = [];
+	const session = str(frame.sessionId);
+	const cwd = str(frame.cwd);
 	const last = str(frame.lastMessage);
-	if (last) lines.push(escapeHtml(truncate(last, 600)));
 	const task = str(frame.task);
-	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
 	const goal = str(frame.goal);
-	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
 	const usage = str(frame.tokenUsage);
 	const model = str(frame.model);
-	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
 	const diff = str(frame.diff);
+	if (!cwd && !last && !task && !goal && !usage && !model && !diff) return undefined;
+	const meta = [session ? `session: ${code(session)}` : undefined, cwd ? `cwd: ${code(cwd)}` : undefined].filter(
+		Boolean,
+	);
+	if (meta.length > 0) lines.push(meta.join(" · "));
+	if (last) lines.push(escapeHtml(truncate(last, 600)));
+	if (task) lines.push(`${italic("task:")} ${escapeHtml(task)}`);
+	if (goal) lines.push(`${italic("goal:")} ${escapeHtml(goal)}`);
+	if (usage || model) lines.push(`ctx: ${code([usage, model].filter(Boolean).join(" · "))}`);
 	if (diff) lines.push(`diff:\n${pre(truncate(diff, 1200))}`);
-	return lines.length ? lines.join("\n") : undefined;
+	return lines.join("\n");
 }
 
 /**
@@ -125,7 +133,7 @@ export function renderThreadedFrame(frame: ThreadedFrame): ThreadedSend | undefi
 		case "turn_stream": {
 			const raw = str(frame.text);
 			if (!raw) return undefined;
-			const text = finalizeTelegramHtml(markdownToTelegramHtml(raw));
+			const text = markdownToTelegramHtml(raw);
 			const finalized = frame.phase === "finalized";
 			return {
 				method: "sendMessage",

package/src/prompts/agents/architect.md

@@ -25,7 +25,7 @@ You may receive a forked parent-conversation snapshot as background. Your read-o
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the verdict markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the verdict markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Never approve code or plans you have not grounded in inspected files.
 - Never give generic advice detached from this codebase.
 - Never approve CRITICAL or HIGH severity issues.
@@ -63,6 +63,9 @@ A narrow compatibility fallback can be acceptable only when it is scoped to a kn
 ## Summary
 2-3 sentences with result and main recommendation.
 
+## Claims
+Evidence-backed claims being reviewed or introduced.
+
 ## Analysis
 Evidence-backed findings.
 
@@ -81,12 +84,12 @@ Prioritized concrete actions.
 ## Code Review Recommendation
 `APPROVE` / `COMMENT` / `REQUEST CHANGES`
 
-## Trade-offs
+## Tradeoffs
 Table or bullets comparing viable options when relevant.
 
-Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full review as the durable artifact via the restricted bash CLI, passing the markdown through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+  skc ralplan --write --stage architect --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (Architectural Status + Code Review Recommendation). Never paste the full review body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/critic.md

@@ -17,7 +17,7 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 
 <constraints>
 - Read-only: do not write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the evaluation markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the evaluation markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - A lone file path is valid input; read and evaluate it.
 - Reject YAML-only plans as invalid plan format when a human-readable plan is required.
 - Do not invent problems; report no issues found when the plan passes.
@@ -42,11 +42,19 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 </success_criteria>
 
 <output_contract>
+## Verdict
 **[OKAY / ITERATE / REJECT]**
 
-**Justification**: concise evidence-backed explanation.
+## Claim Checks
+Concise evidence-backed explanation of verified claims.
 
-**Summary**:
+## Missing Evidence
+Definitely missing or unverified evidence, or `None`.
+
+## Approval Boundary
+What execution may proceed with, and what remains outside approval.
+
+## Summary
 - Clarity
 - Verifiability
 - Completeness
@@ -55,11 +63,12 @@ Review plan clarity, completeness, verification, big-picture fit, referenced fil
 - Alternatives Depth
 - Risk/Verification Rigor
 
-If not OKAY, list concrete required fixes.
+## Required Changes
+If not OKAY, list concrete required fixes; otherwise write `None`.
 
-Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown inline (never a file path, never `/tmp`):
+Persist this full evaluation as the durable artifact via the restricted bash CLI, passing the markdown through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+  skc ralplan --write --stage critic --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus the compact verdict (OKAY / ITERATE / REJECT). Never paste the full evaluation body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

package/src/prompts/agents/planner.md

@@ -17,7 +17,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 
 <constraints>
 - Read-only: never write, edit, format, commit, push, or mutate files.
-- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the plan markdown inline in `--artifact`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
+- Exception: you may use the restricted `bash` tool only for sanctioned SKC workflow CLI persistence (`skc ralplan --write ...`) and SKC workflow state read/write/contract commands (`skc state ...`). For `skc ralplan --write`, pass the plan markdown through the `SKC_RALPLAN_ARTIFACT` env override and `--artifact-env SKC_RALPLAN_ARTIFACT`, not as a file path. Do not use bash for product-source writes, direct handoffs, state clears, or general shell work.
 - Persist durable plans only through `skc ralplan --write`. Never write plan files to `/tmp`, the repository, or any other path, and never rely on a file the caller must read back. The CLI is your only persistence channel.
 - Inspect the repository before asking about code facts.
 - Ask only about priorities, tradeoffs, scope decisions, timelines, or preferences that repository inspection cannot resolve.
@@ -45,16 +45,21 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 <output_contract>
 Build the full plan as a single markdown document containing:
 - Summary
+- Intent Diff
+- Decision Drivers
+- Options
 - In scope / out of scope
 - File-level changes
 - Sequencing and dependencies
 - Acceptance criteria
 - Verification
+- Escalation/Risk Gate
+- Verification Plan
 - Risks and mitigations
 
-Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan inline (never a file path, never `/tmp`):
+Persist that markdown as the durable artifact via the restricted bash CLI, passing the plan through the `SKC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  skc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+  skc ralplan --write --stage planner --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json
 
 Then return to the caller ONLY the write receipt (`run_id`, `path`, `sha256`, `stage`, `stage_n`) plus a compact plan summary (<=10 lines). Never paste the full plan body back into your response — the caller reads the persisted artifact when it needs the full text.
 </output_contract>

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

@@ -60,8 +60,13 @@ Use for read-only plan critique. It approves only when execution can proceed wit
 
 <routing>
 - Clear, low-risk implementation request → implement directly with focused verification.
+- Do not invoke `deep-interview`, `ralplan`, `ultragoal`, `team`, or role agents for simple clear implementation requests; direct tools and the default launch path are enough.
+- The runtime records a `workflow-intent-diff` CustomEntry for direct-path traceability; it does not participate in LLM context and is not a reason to slow down direct execution.
+- When a task is clear, bounded, and low-risk, the default action is to make the smallest correct change and verify it, not to interview, plan, open a durable ledger, or delegate.
+- Small verification needs do not make a task a planning workflow. Escalate only for real ambiguity, non-trivial architecture/sequence risk, durable multi-goal tracking, or useful coordinated workers.
+- Root-cause phase schema is active only for contradiction, regression, or high-risk transition work; otherwise keep ordinary verification and do not add root-cause ceremony.
 - Vague requirements → use `deep-interview` before planning or execution.
-- Clear requirements but non-trivial architecture/sequence risk → use `ralplan` and stop at pending approval.
+- Clear requirements but non-trivial architecture/sequence risk → use `ralplan --deliberate` and stop at pending approval.
 - Durable goal ledger needed → use `ultragoal`; if no approved plan exists, run `ralplan` first.
 - Approved work benefits from coordinated persistent workers → use `team`.
 - Large enough implementation work → delegate bounded slices to `executor` through the task/sub-agent tool when it improves quality or throughput.
@@ -131,6 +136,18 @@ Use tools whenever they materially improve correctness, completeness, or groundi
 </inventory>
 {{/if}}
 
+{{#if toolDiscoveryActive}}
+<tool-discovery>
+Only essential tools are loaded up front; other tools are hidden to save context and are available on demand. Call `{{toolRefs.search_tool_bm25}}` with a short natural-language query to find and activate the tool you need, then call it. Prefer discovering a purpose-built tool over forcing the task onto a resident one.
+{{#if discoverableTools.length}}
+Discoverable tools:
+{{#each discoverableTools}}
+- `{{name}}`{{#if summary}} — {{summary}}{{/if}}
+{{/each}}
+{{/if}}
+</tool-discovery>
+{{/if}}
+
 <inputs>
 - Keep tool inputs concise where possible.
 - For `path` or path-like fields, prefer relative paths.
@@ -233,9 +250,10 @@ For image understanding, call `{{toolRefs.read}}` on the image path; the image i
 </before-editing>
 
 <decomposition>
-- Use todo tracking for tasks with three or more distinct steps.
+- Use todo tracking for tasks with three or more distinct steps; skip it for one-step or obvious two-step fixes where the next action is already clear.
 - Mark completed tasks immediately and continue to the next task without yielding.
 - Delegate rather than silently shrinking scope. Prefer `executor` for bounded implementation slices, `planner` for sequencing, `architect` for architecture/code-review lanes, and `critic` for plan critique.
+- Do not delegate for single-line typos, obvious syntax errors, single-file known-location fixes, or direct answers.
 </decomposition>
 
 <verification>

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 SKC workflow CLI persistence or state read/write/contract operations; per-command env overrides and all other shell command shapes are blocked before execution.
+Use it only for sanctioned SKC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `SKC_RALPLAN_ARTIFACT` when paired with `skc ralplan --write ... --artifact-env SKC_RALPLAN_ARTIFACT`, and all other shell command shapes are blocked before execution.
 {{/when}}
 </restricted-bash-mode>
 {{/if}}

package/src/runtime-mcp/config-writer.ts

@@ -237,6 +237,34 @@ export async function listMCPServers(filePath: string): Promise<string[]> {
 	return Object.keys(config.mcpServers ?? {});
 }
 
+/**
+ * Set a server's autoload flag (connect automatically at session startup).
+ *
+ * Autoload defaults to true, so turning it on removes the key to keep the
+ * config file free of redundant fields; turning it off writes `autoload: false`.
+ *
+ * @throws Error if the server doesn't exist
+ */
+export async function setServerAutoload(filePath: string, name: string, autoload: boolean): Promise<void> {
+	const existing = await readMCPConfigFile(filePath);
+	const server = existing.mcpServers?.[name];
+	if (!server) {
+		throw new Error(`Server "${name}" not found in ${filePath}`);
+	}
+
+	const { autoload: _removed, ...rest } = server;
+	const updatedServer = (autoload ? rest : { ...rest, autoload: false }) as MCPServerConfig;
+	const updated: MCPConfigFile = {
+		...existing,
+		mcpServers: {
+			...existing.mcpServers,
+			[name]: updatedServer,
+		},
+	};
+
+	await writeMCPConfigFile(filePath, updated);
+}
+
 /**
  * Read the disabled servers list from a config file.
  */

package/src/runtime-mcp/config.ts

@@ -20,6 +20,8 @@ export interface LoadMCPConfigsOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only include servers eligible for startup connection, i.e. autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 }
 
 /** Result of loading MCP configs */
@@ -40,6 +42,7 @@ function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
 	const transport = server.transport ?? (server.command ? "stdio" : server.url ? "http" : "stdio");
 	const shared = {
 		enabled: server.enabled,
+		autoload: server.autoload,
 		timeout: server.timeout,
 		auth: server.auth,
 		oauth: server.oauth,
@@ -96,6 +99,7 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 	const enableProjectConfig = options?.enableProjectConfig ?? true;
 	const filterExa = options?.filterExa ?? true;
 	const filterBrowser = options?.filterBrowser ?? false;
+	const autoloadOnly = options?.autoloadOnly ?? false;
 
 	// Load MCP servers via capability system
 	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
@@ -115,6 +119,9 @@ export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOpt
 		if (config.enabled === false || disabledServers.has(server.name)) {
 			continue;
 		}
+		if (autoloadOnly && config.autoload === false) {
+			continue;
+		}
 		configs[server.name] = config;
 		sources[server.name] = server._source;
 	}

package/src/runtime-mcp/loader.ts

@@ -34,6 +34,8 @@ export interface MCPToolsLoadOptions {
 	filterExa?: boolean;
 	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
 	filterBrowser?: boolean;
+	/** Only connect servers with autoload !== false (default: false) */
+	autoloadOnly?: boolean;
 	/** SQLite storage for MCP tool cache (null disables cache) */
 	cacheStorage?: AgentStorage | null;
 	/** Auth storage used to resolve OAuth credentials before initial MCP connect */
@@ -72,6 +74,7 @@ export async function discoverAndLoadMCPTools(cwd: string, options?: MCPToolsLoa
 			enableProjectConfig: options?.enableProjectConfig,
 			filterExa: options?.filterExa,
 			filterBrowser: options?.filterBrowser,
+			autoloadOnly: options?.autoloadOnly,
 		});
 	} catch (error) {
 		// If discovery fails entirely, return empty result