@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/src/config/settings-schema.ts

@@ -36,7 +36,8 @@ export type SettingTab =
 	| "editing"
 	| "tools"
 	| "tasks"
-	| "providers";
+	| "providers"
+	| "integrations";
 
 /** Tab display metadata - icon is resolved via theme.symbol() */
 export type TabMetadata = { label: string; icon: `tab.${string}` };
@@ -52,6 +53,7 @@ export const SETTING_TABS: SettingTab[] = [
 	"tools",
 	"tasks",
 	"providers",
+	"integrations",
 ];
 
 /** Tab display metadata - icon is a symbol key from theme.ts (tab.*) */
@@ -65,6 +67,7 @@ export const TAB_METADATA: Record<SettingTab, { label: string; icon: `tab.${stri
 	tools: { label: "Tools", icon: "tab.tools" },
 	tasks: { label: "Tasks", icon: "tab.tasks" },
 	providers: { label: "Providers", icon: "tab.providers" },
+	integrations: { label: "Integrations", icon: "tab.integrations" },
 };
 
 /** Status line segment identifiers */
@@ -281,7 +284,8 @@ export const SETTINGS_SCHEMA = {
 		ui: {
 			tab: "interaction",
 			label: "Terminal Bell",
-			description: "Emit a BEL character for local terminal notifications",
+			description:
+				"Emit a BEL character for local terminal notifications. Windows Terminal may keep BEL silent depending on profile/system sound settings; use completion.notifyCommand for a PowerShell Console.Beep workaround.",
 		},
 	},
 	"notifications.bellOnComplete": {
@@ -476,7 +480,7 @@ export const SETTINGS_SCHEMA = {
 	// Status line
 	"statusLine.preset": {
 		type: "enum",
-		values: ["default", "minimal", "compact", "full", "nerd", "ascii", "custom"] as const,
+		values: ["default", "default-usage", "minimal", "compact", "full", "nerd", "ascii", "custom"] as const,
 		default: "default",
 		ui: {
 			tab: "appearance",
@@ -484,6 +488,11 @@ export const SETTINGS_SCHEMA = {
 			description: "Pre-built status line configurations",
 			options: [
 				{ value: "default", label: "Default", description: "Model, path, git, context, tokens, cost" },
+				{
+					value: "default-usage",
+					label: "Default + Usage",
+					description: "Default layout with provider usage quota",
+				},
 				{ value: "minimal", label: "Minimal", description: "Path and git only" },
 				{ value: "compact", label: "Compact", description: "Model, git, cost, context" },
 				{ value: "full", label: "Full", description: "All segments including time" },
@@ -523,6 +532,21 @@ export const SETTINGS_SCHEMA = {
 			description: "Use the session name color for the editor border and status line gap",
 		},
 	},
+	"statusLine.maxRows": {
+		type: "number",
+		default: 1,
+		ui: {
+			tab: "appearance",
+			label: "Status Line Rows",
+			description:
+				"Maximum rows for the status line. When greater than 1, overflowing segments wrap onto additional rows instead of being dropped.",
+			options: [
+				{ value: "1", label: "1 row", description: "Single line; overflow is truncated (default)" },
+				{ value: "2", label: "2 rows", description: "Wrap overflow onto a second row" },
+				{ value: "3", label: "3 rows", description: "Wrap overflow across up to three rows" },
+			],
+		},
+	},
 	"tools.artifactSpillThreshold": {
 		type: "number",
 		default: 50,
@@ -1201,7 +1225,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "interaction",
 			label: "Completion Notification Command",
 			description:
-				"Optional user-level shell command to run when an agent turn completes; receives SKC_NOTIFICATION_* environment variables.",
+				"Optional user-level shell command to run when an agent turn completes; receives SKC_NOTIFICATION_* environment variables. On Windows, this can call PowerShell [Console]::Beep when terminal BEL is silent.",
 		},
 	},
 
@@ -2226,6 +2250,11 @@ export const SETTINGS_SCHEMA = {
 		ui: { tab: "tools", label: "Web Search", description: "Enable the web_search tool for web searching" },
 	},
 
+	"web_search.provider": {
+		type: "enum",
+		values: ["auto", ...CONFIGURABLE_SEARCH_PROVIDER_IDS] as const,
+		default: "auto",
+	},
 	"web_search.fallback": {
 		type: "array",
 		default: EMPTY_STRING_ARRAY,
@@ -2489,7 +2518,7 @@ export const SETTINGS_SCHEMA = {
 	"tools.discoveryMode": {
 		type: "enum",
 		values: ["off", "all"] as const,
-		default: "off",
+		default: "all",
 		ui: {
 			tab: "tools",
 			label: "Tool Discovery",
@@ -2504,7 +2533,7 @@ export const SETTINGS_SCHEMA = {
 			tab: "tools",
 			label: "Essential Tools Override",
 			description:
-				"Override the always-loaded built-in tools (default: read, bash, edit). Leave empty to use defaults.",
+				"Override the always-loaded built-in tools (default: read, bash, edit, write, search, find). Leave empty to use defaults.",
 		},
 	},
 
@@ -3156,6 +3185,151 @@ export const SETTINGS_SCHEMA = {
 			description: "Score threshold (0–100) above which block mode denies install. Default 60.",
 		},
 	},
+
+	// Telegram Remote — two-way messaging integration.
+	// Maps to SKC_TELEGRAM_REMOTE_* env vars consumed by the
+	// @sayknow-cli/telegram-remote gateway (packages/telegram-remote).
+	// The settings bridge converts these into env before spawning the gateway.
+	"telegram.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Telegram Remote",
+			description: "Enable two-way Telegram bot control of skc sessions",
+		},
+	},
+
+	"telegram.botToken": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Bot Token",
+			description: "Telegram bot token from @BotFather (required when enabled)",
+		},
+	},
+
+	"telegram.allowedUserIds": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Allowed User IDs",
+			description: "Comma-separated Telegram user IDs permitted to send commands",
+		},
+	},
+
+	"telegram.allowedChatIds": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Allowed Chat IDs",
+			description: "Comma-separated Telegram chat IDs permitted to send commands",
+		},
+	},
+
+	"telegram.backend": {
+		type: "enum",
+		values: ["coordinator", "rpc"] as const,
+		default: "coordinator",
+		ui: {
+			tab: "integrations",
+			label: "Backend",
+			description: "Coordinator (multi-session lifecycle) or RPC (single persistent session)",
+			options: [
+				{ value: "coordinator", label: "Coordinator", description: "Multi-session lifecycle + observation" },
+				{ value: "rpc", label: "RPC", description: "Attach/detach to one persistent session socket" },
+			],
+		},
+	},
+
+	"telegram.enableStop": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Enable /stop",
+			description: "Allow graceful stop requests (adds the reports mutation class)",
+		},
+	},
+
+	"telegram.enableRich": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "integrations",
+			label: "Rich Messages",
+			description: "HTML formatting + inline keyboards",
+		},
+	},
+
+	"telegram.enablePush": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "integrations",
+			label: "Push Notifications",
+			description: "Follow/Mute subscriptions via coordinator event watch",
+		},
+	},
+
+	"telegram.registerCommands": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "integrations",
+			label: "Register Bot Menu",
+			description: "Register the Bot command menu at startup",
+		},
+	},
+
+	"telegram.presets": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "Session Presets",
+			description: "JSON array of {id, workdir, sessionCommand, taskTemplate?, taskMaxLen?}",
+		},
+	},
+
+	"telegram.rpcSocket": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "RPC Socket",
+			description: "Path to the skc launch --output rpc UNIX socket (RPC backend only)",
+		},
+	},
+
+	"telegram.stateDir": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "integrations",
+			label: "State Directory",
+			description: "Gateway state dir for reconnect/resync (required for RPC backend)",
+		},
+	},
+
+	// Telegram advanced — hidden from UI, editable via config.yml
+	"telegram.pollTimeoutSec": { type: "number", default: 30 },
+	"telegram.apiBase": { type: "string", default: undefined },
+	"telegram.coordinatorCommand": { type: "string", default: "skc" },
+	"telegram.coordinatorArgs": { type: "string", default: "mcp-serve,coordinator" },
+	"telegram.enableEditMessageText": { type: "boolean", default: false },
+	"telegram.richCallbackTtlMs": { type: "number", default: 600000 },
+	"telegram.richCallbackMaxTokens": { type: "number", default: 500 },
+	"telegram.defaultTaskMaxLen": { type: "number", default: 2000 },
+	"telegram.livenessMs": { type: "number", default: 60000 },
+	"telegram.followTtlMs": { type: "number", default: 86400000 },
+	"telegram.subscriptionsMax": { type: "number", default: 1000 },
+	"telegram.longPollMs": { type: "number", default: 25000 },
+	"telegram.digestThreshold": { type: "number", default: 5 },
+	"telegram.allowAttachSocketArg": { type: "boolean", default: false },
 } as const;
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -3323,6 +3497,7 @@ export interface ExaSettings {
 export interface StatusLineSettings {
 	preset: StatusLinePreset;
 	separator: StatusLineSeparatorStyle;
+	maxRows: number;
 	showHookStatus: boolean;
 	showSkillHud: boolean;
 	leftSegments: StatusLineSegmentId[];
@@ -3383,6 +3558,35 @@ export interface NotificationsSettings {
 	};
 }
 
+export interface TelegramSettings {
+	enabled: boolean;
+	botToken: string | undefined;
+	allowedUserIds: string | undefined;
+	allowedChatIds: string | undefined;
+	backend: "coordinator" | "rpc";
+	enableStop: boolean;
+	enableRich: boolean;
+	enablePush: boolean;
+	registerCommands: boolean;
+	presets: string | undefined;
+	rpcSocket: string | undefined;
+	stateDir: string | undefined;
+	pollTimeoutSec: number;
+	apiBase: string | undefined;
+	coordinatorCommand: string;
+	coordinatorArgs: string;
+	enableEditMessageText: boolean;
+	richCallbackTtlMs: number;
+	richCallbackMaxTokens: number;
+	defaultTaskMaxLen: number;
+	livenessMs: number;
+	followTtlMs: number;
+	subscriptionsMax: number;
+	longPollMs: number;
+	digestThreshold: number;
+	allowAttachSocketArg: boolean;
+}
+
 /** Map group prefix -> typed settings interface */
 export interface GroupTypeMap {
 	compaction: CompactionSettings;
@@ -3401,6 +3605,7 @@ export interface GroupTypeMap {
 	modelTags: ModelTagsSettings;
 	cycleOrder: string[];
 	shellMinimizer: ShellMinimizerSettings;
+	telegram: TelegramSettings;
 	notifications: NotificationsSettings;
 }
 

package/src/config/telegram-autostart.ts

@@ -0,0 +1,107 @@
+/**
+ * Auto-start the Telegram Remote gateway when `telegram.enabled` is on.
+ *
+ * Called once during skc startup (interactive / persistent modes only — not
+ * `-p` print or auto-print). Spawns the gateway as a detached background
+ * process, tracks its PID so repeated skc invocations don't double-spawn,
+ * and redirects output to a log file under the config root.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfigRootDir, isCompiledBinary, logger } from "@sayknow-cli/utils";
+import { settings } from "./settings";
+import type { TelegramSettings } from "./settings-schema";
+import { telegramSettingsToEnv, validateTelegramSettings } from "./telegram-env-bridge";
+
+function readTelegramSettings(): TelegramSettings {
+	return {
+		enabled: settings.get("telegram.enabled"),
+		botToken: settings.get("telegram.botToken"),
+		allowedUserIds: settings.get("telegram.allowedUserIds"),
+		allowedChatIds: settings.get("telegram.allowedChatIds"),
+		backend: settings.get("telegram.backend"),
+		enableStop: settings.get("telegram.enableStop"),
+		enableRich: settings.get("telegram.enableRich"),
+		enablePush: settings.get("telegram.enablePush"),
+		registerCommands: settings.get("telegram.registerCommands"),
+		presets: settings.get("telegram.presets"),
+		rpcSocket: settings.get("telegram.rpcSocket"),
+		stateDir: settings.get("telegram.stateDir"),
+		pollTimeoutSec: settings.get("telegram.pollTimeoutSec"),
+		apiBase: settings.get("telegram.apiBase"),
+		coordinatorCommand: settings.get("telegram.coordinatorCommand") ?? "skc",
+		coordinatorArgs: settings.get("telegram.coordinatorArgs") ?? "mcp-serve,coordinator",
+		enableEditMessageText: settings.get("telegram.enableEditMessageText"),
+		richCallbackTtlMs: settings.get("telegram.richCallbackTtlMs"),
+		richCallbackMaxTokens: settings.get("telegram.richCallbackMaxTokens"),
+		defaultTaskMaxLen: settings.get("telegram.defaultTaskMaxLen"),
+		livenessMs: settings.get("telegram.livenessMs"),
+		followTtlMs: settings.get("telegram.followTtlMs"),
+		subscriptionsMax: settings.get("telegram.subscriptionsMax"),
+		longPollMs: settings.get("telegram.longPollMs"),
+		digestThreshold: settings.get("telegram.digestThreshold"),
+		allowAttachSocketArg: settings.get("telegram.allowAttachSocketArg"),
+	};
+}
+
+function resolveGatewayCommand(): { cmd: string; args: string[] } {
+	if (isCompiledBinary()) {
+		return { cmd: "skc-telegram-remote", args: [] };
+	}
+	const cliPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../telegram-remote/src/cli.ts");
+	return { cmd: process.execPath, args: ["run", cliPath] };
+}
+
+function isAlreadyRunning(pidFile: string): boolean {
+	try {
+		const pid = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+		if (!Number.isInteger(pid)) return false;
+		process.kill(pid, 0); // signal 0 — throws if the process is gone
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * If `telegram.enabled` is true and the gateway is not already running, spawn
+ * it in the background. Never throws — failures are logged as warnings so the
+ * main skc session is unaffected.
+ */
+export async function maybeAutostartTelegramRemote(): Promise<void> {
+	if (!settings.get("telegram.enabled")) return;
+
+	const config = readTelegramSettings();
+	const errors = validateTelegramSettings(config);
+	if (errors.length > 0) {
+		logger.warn("Telegram Remote enabled but misconfigured, skipping autostart", { errors });
+		return;
+	}
+
+	const configRoot = getConfigRootDir();
+	const pidFile = path.join(configRoot, "telegram-remote.pid");
+	if (isAlreadyRunning(pidFile)) {
+		logger.info("Telegram Remote already running, skipping autostart");
+		return;
+	}
+
+	const env = telegramSettingsToEnv(config);
+	const { cmd, args } = resolveGatewayCommand();
+	const logDir = path.join(configRoot, "logs");
+	fs.mkdirSync(logDir, { recursive: true });
+	const logFd = fs.openSync(path.join(logDir, "telegram-remote.log"), "a");
+
+	try {
+		const proc = Bun.spawn([cmd, ...args], {
+			env: { ...process.env, ...env },
+			stdio: ["ignore", logFd, logFd],
+			detached: true,
+		});
+		proc.unref();
+		fs.writeFileSync(pidFile, String(proc.pid));
+		logger.info("Telegram Remote gateway auto-started", { pid: proc.pid });
+	} catch (err) {
+		logger.warn("Failed to auto-start Telegram Remote gateway", { error: String(err) });
+	}
+}

package/src/config/telegram-env-bridge.ts

@@ -0,0 +1,92 @@
+/**
+ * Bridge between skc settings (`telegram.*`) and the
+ * `@sayknow-cli/telegram-remote` gateway's environment-driven config
+ * (`loadConfigFromEnv` in packages/telegram-remote/src/config.ts).
+ *
+ * The gateway is a standalone process (`skc-telegram-remote`) that reads all
+ * configuration from `SKC_TELEGRAM_REMOTE_*` env vars. This module converts the
+ * typed settings group into those env vars so skc can spawn the gateway with a
+ * consistent, settings-page-driven configuration.
+ */
+import type { TelegramSettings } from "./settings-schema";
+
+/** Convert telegram settings into the env-var map the gateway expects. */
+export function telegramSettingsToEnv(s: TelegramSettings): Record<string, string> {
+	const env: Record<string, string> = {};
+
+	const str = (v: string | undefined, key: string): void => {
+		if (v !== undefined && v !== "") env[key] = v;
+	};
+	const num = (v: number, key: string): void => {
+		env[key] = String(v);
+	};
+	const bool = (v: boolean, key: string): void => {
+		env[key] = v ? "true" : "false";
+	};
+
+	// Required
+	str(s.botToken, "SKC_TELEGRAM_REMOTE_BOT_TOKEN");
+
+	// Allowlists
+	str(s.allowedUserIds, "SKC_TELEGRAM_REMOTE_ALLOWED_USER_IDS");
+	str(s.allowedChatIds, "SKC_TELEGRAM_REMOTE_ALLOWED_CHAT_IDS");
+
+	// Presets
+	str(s.presets, "SKC_TELEGRAM_REMOTE_PRESETS");
+
+	// Toggles
+	bool(s.enableStop, "SKC_TELEGRAM_REMOTE_ENABLE_STOP");
+	bool(s.enableRich, "SKC_TELEGRAM_REMOTE_ENABLE_RICH");
+	bool(s.enablePush, "SKC_TELEGRAM_REMOTE_ENABLE_PUSH");
+	bool(s.registerCommands, "SKC_TELEGRAM_REMOTE_REGISTER_COMMANDS");
+	bool(s.enableEditMessageText, "SKC_TELEGRAM_REMOTE_ENABLE_EDIT_MESSAGE_TEXT");
+	bool(s.allowAttachSocketArg, "SKC_TELEGRAM_REMOTE_ALLOW_ATTACH_SOCKET_ARG");
+
+	// Backend + RPC
+	str(s.backend, "SKC_TELEGRAM_REMOTE_BACKEND");
+	str(s.rpcSocket, "SKC_TELEGRAM_REMOTE_RPC_SOCKET");
+	str(s.stateDir, "SKC_TELEGRAM_REMOTE_STATE_DIR");
+	num(s.livenessMs, "SKC_TELEGRAM_REMOTE_LIVENESS_MS");
+
+	// Transport
+	str(s.apiBase, "SKC_TELEGRAM_REMOTE_API_BASE");
+	num(s.pollTimeoutSec, "SKC_TELEGRAM_REMOTE_POLL_TIMEOUT_SEC");
+	num(s.longPollMs, "SKC_TELEGRAM_REMOTE_WATCH_TIMEOUT_MS");
+
+	// Rich callback tuning
+	num(s.richCallbackTtlMs, "SKC_TELEGRAM_REMOTE_RICH_CALLBACK_TTL_MS");
+	num(s.richCallbackMaxTokens, "SKC_TELEGRAM_REMOTE_RICH_CALLBACK_MAX_TOKENS");
+
+	// Push / subscriptions
+	num(s.followTtlMs, "SKC_TELEGRAM_REMOTE_FOLLOW_TTL_MS");
+	num(s.subscriptionsMax, "SKC_TELEGRAM_REMOTE_SUBSCRIPTIONS_MAX");
+	num(s.digestThreshold, "SKC_TELEGRAM_REMOTE_DIGEST_THRESHOLD");
+
+	// Coordinator subprocess
+	str(s.coordinatorCommand, "SKC_TELEGRAM_REMOTE_COORDINATOR_COMMAND");
+	str(s.coordinatorArgs, "SKC_TELEGRAM_REMOTE_COORDINATOR_ARGS");
+
+	// Preset task cap
+	num(s.defaultTaskMaxLen, "SKC_TELEGRAM_REMOTE_DEFAULT_TASK_MAX_LEN");
+
+	return env;
+}
+
+/**
+ * Validate telegram settings before spawning the gateway.
+ * Returns a list of human-readable error strings (empty when valid).
+ */
+export function validateTelegramSettings(s: TelegramSettings): string[] {
+	const errors: string[] = [];
+
+	if (!s.botToken) errors.push("Bot Token is required");
+	if (!s.allowedUserIds && !s.allowedChatIds) {
+		errors.push("At least one of Allowed User IDs or Allowed Chat IDs is required");
+	}
+	if (s.backend === "rpc") {
+		if (!s.rpcSocket) errors.push("RPC Socket is required for the RPC backend");
+		if (!s.stateDir) errors.push("State Directory is required for the RPC backend");
+	}
+
+	return errors;
+}

package/src/defaults/skc/skills/ralplan/SKILL.md

@@ -19,7 +19,7 @@ Ralplan is the consensus planning workflow. It triggers iterative planning with
 
 ## Flags
 
-- `--interactive`: Enables user prompts at key decision points (draft review in step 2 and final approval in step 6). Without this flag the workflow runs fully automated — Planner → Architect → Critic loop — marks the final plan `pending approval`, outputs it, and stops without asking for confirmation or executing changes.
+- `--interactive`: Enables extra mid-loop user prompts (draft review in step 2 and one-at-a-time reconciliation in step 6c). Regardless of this flag, the workflow always finishes the post-interview gate with an `ask`-tool prompt offering Refine further / Approve ultragoal / Approve team / Stop here, and never auto-executes — execution always requires explicit approval through that prompt.
 - `--deliberate`: Forces deliberate mode for high-risk work. Adds pre-mortem (3 scenarios) and expanded test planning (unit/integration/e2e/observability). Without this flag, deliberate mode can still auto-enable when the request explicitly signals high risk (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage).
 - `--architect openai-code`: Use OpenAI code for the Architect pass when OpenAI code CLI is available. Otherwise, briefly note the fallback and keep the default SKC Architect review.
 - `--critic openai-code`: Use OpenAI code for the Critic pass when OpenAI code CLI is available. Otherwise, briefly note the fallback and keep the default SKC Critic review.
@@ -45,13 +45,15 @@ Planning artifacts and stage handoffs MUST be persisted through the ralplan CLI
 
 ```bash
 skc ralplan --write --stage <type> --stage_n <N> --artifact "markdown file path or markdown string"
+# restricted role agents use:
+skc ralplan --write --stage <type> --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT
 ```
 
-Use stage values that match the producer or artifact kind, such as `planner`, `architect`, `critic`, `revision`, `post-interview`, `adr`, or `final`. Increment `--stage_n` for each consensus-loop pass. The `--artifact` value may be either a markdown file path prepared outside `.skc/` for ingestion or the markdown content string itself. The native `--write` handler persists markdown under `.skc/_session-{sessionid}/plans/ralplan/<run-id>/stage-<NN>-<stage>.md`, maintains an `index.jsonl` audit log, and for `final` stages additionally writes a `pending-approval.md` copy. Direct `write`, `edit`, or `ast_edit` calls against `.skc/_session-{sessionid}/specs`, `.skc/_session-{sessionid}/plans`, `.skc/_session-{sessionid}/state`, or any other `.skc/` path are forbidden unless an explicit force override is active.
+Use stage values that match the producer or artifact kind, such as `planner`, `architect`, `critic`, `revision`, `post-interview`, `adr`, or `final`. Increment `--stage_n` for each consensus-loop pass. The `--artifact` value may be either a markdown file path prepared outside `.skc/` for ingestion or the markdown content string itself. The native `--write` handler also accepts `--artifact-env SKC_RALPLAN_ARTIFACT` to read markdown from that per-command env override. It persists markdown under `.skc/_session-{sessionid}/plans/ralplan/<run-id>/stage-<NN>-<stage>.md`, maintains an `index.jsonl` audit log, and for `final` stages additionally writes a `pending-approval.md` copy. Direct `write`, `edit`, or `ast_edit` calls against `.skc/_session-{sessionid}/specs`, `.skc/_session-{sessionid}/plans`, `.skc/_session-{sessionid}/state`, or any other `.skc/` path are forbidden unless an explicit force override is active.
 
-While ralplan is active it is a pre-approval planning phase: product-code mutation tools (`write`/`edit`/`ast_edit`) and product-mutating `bash` (e.g. `tee src/...`, redirects into the project tree) are blocked, exactly like deep-interview. Prefer passing the `--artifact` markdown **inline** (the content string) so no scratch file is needed; this is mandatory for restricted role agents (see below). Only the leader, and only when an artifact is too large to pass inline, may stage it as a file in a system temp directory (`os.tmpdir()`/`$TMPDIR`, `/tmp`, `/var/tmp`) outside the project tree and pass that path — never write scratch files into the repo or `.skc/`. Product code is mutated only after the plan is approved and execution begins.
+While ralplan is active it is a pre-approval planning phase: product-code mutation tools (`write`/`edit`/`ast_edit`) and product-mutating `bash` (e.g. `tee src/...`, redirects into the project tree) are blocked, exactly like deep-interview. Leaders may pass `--artifact` markdown inline or, when an artifact is too large to pass inline, stage it as a file in a system temp directory (`os.tmpdir()`/`$TMPDIR`, `/tmp`, `/var/tmp`) outside the project tree and pass that path — never write scratch files into the repo or `.skc/`. Product code is mutated only after the plan is approved and execution begins.
 
-Restricted read-only role agents (`planner`, `architect`, and `critic`) must pass markdown content directly in `--artifact`; their restricted bash environment intentionally disables artifact file-path ingestion so a verdict command cannot persist arbitrary file contents.
+Restricted read-only role agents (`planner`, `architect`, and `critic`) must pass markdown content through the `SKC_RALPLAN_ARTIFACT` env override with `--artifact-env SKC_RALPLAN_ARTIFACT`; their restricted bash environment intentionally disables artifact file-path ingestion so a verdict command cannot persist arbitrary file contents.
 
 After a role agent persists a stage artifact, its model-facing response to the caller SHOULD be receipt-only: return the `skc ralplan --write --json` receipt (`run_id`, `path`, `stage`, `stage_n`, `sha256`, `created_at`) plus the minimal verdict/status fields the caller needs for routing, and do **not** paste the full persisted markdown back into the parent conversation. Downstream reviewers should receive the artifact path/receipt and read the persisted file themselves when they actually need the body. This preserves the audit trail while preventing Planner/Architect/Critic verdict bodies from being duplicated into the main-agent context.
 
@@ -60,7 +62,7 @@ RECEIPT-ONLY guideline: role agents (`planner`, `architect`, and `critic`) persi
 This skill runs SKC planning in consensus mode for the provided arguments.
 
 The consensus workflow:
-1. **Planner** creates the initial plan and a compact **RALPLAN-DR summary** before review. Launch the Planner ONCE per run as a detached, resumable subagent (await it before the Architect) and record its returned subagent id as the run's persisted Planner id; persist the stage with `skc ralplan --write --stage planner --stage_n 1 --artifact "..." --planner-id <id> --planner-resumable <true|false>` (see **Persisted Planner** below):
+1. **Planner** creates the initial plan and a compact **RALPLAN-DR summary** before review. Launch the Planner ONCE per run as a detached, resumable subagent (await it before the Architect) and record its returned subagent id as the run's persisted Planner id; persist the stage with `skc ralplan --write --stage planner --stage_n 1 --artifact-env SKC_RALPLAN_ARTIFACT --planner-id <id> --planner-resumable <true|false>` (see **Persisted Planner** below):
    - After persistence, return only the receipt/path plus compact planning status; do not paste the full plan markdown back to the caller unless explicitly requested.
    - Principles (3-5)
    - Decision Drivers (top 3)
@@ -69,27 +71,34 @@ The consensus workflow:
    - Deliberate mode only: pre-mortem (3 scenarios) + expanded test plan (unit/integration/e2e/observability)
 2. **User feedback** *(--interactive only)*: If `--interactive` is set, use the `ask` tool to present the draft plan **plus the Principles / Drivers / Options summary** before review (Proceed to review / Request changes / Skip review). Otherwise, automatically proceed to review.
 3. **Architect** reviews for architectural soundness and must provide the strongest steelman antithesis, at least one real tradeoff tension, and (when possible) synthesis — **await completion before step 4**. In deliberate mode, Architect should explicitly flag principle violations.
-   - The Architect agent/subagent must persist its review with `skc ralplan --write --stage architect --stage_n <N> --artifact "..." --json`, then return the receipt/path plus compact verdict/status (`CLEAR`/`WATCH`/`BLOCK`, `APPROVE`/`COMMENT`/`REQUEST CHANGES`) instead of pasting the full review body.
+   - The Architect agent/subagent must persist its review with `skc ralplan --write --stage architect --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json`, then return the receipt/path plus compact verdict/status (`CLEAR`/`WATCH`/`BLOCK`, `APPROVE`/`COMMENT`/`REQUEST CHANGES`) instead of pasting the full review body.
 4. **Critic** evaluates against quality criteria — run only after step 3 completes. Critic must enforce principle-option consistency, fair alternatives, risk mitigation clarity, testable acceptance criteria, and concrete verification steps. In deliberate mode, Critic must reject missing/weak pre-mortem or expanded test plan.
-   - The Critic agent/subagent must persist its evaluation with `skc ralplan --write --stage critic --stage_n <N> --artifact "..." --json`, then return the receipt/path plus compact verdict/status (`OKAY`/`ITERATE`/`REJECT`) instead of pasting the full evaluation body.
-5. **Re-review loop** (max 5 iterations): Any non-`APPROVE` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
+   - The Critic agent/subagent must persist its evaluation with `skc ralplan --write --stage critic --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json`, then return the receipt/path plus compact verdict/status (`OKAY`/`ITERATE`/`REJECT`) instead of pasting the full evaluation body.
+5. **Re-review loop** (max 5 iterations): Any non-`OKAY` Critic verdict (`ITERATE` or `REJECT`) MUST run the same full closed loop:
    a. Collect Architect + Critic feedback
    b. Revise the plan by resuming the SAME persisted Planner subagent with consolidated Architect + Critic feedback (see **Persisted Planner** below); fall back to a fresh Planner spawn only per the fallback routing table
    c. Return to Architect review
-      - Persist each Planner revision with `skc ralplan --write --stage revision --stage_n <N> --artifact "..." --json` before re-review, then pass the receipt/path forward instead of duplicating the full revision markdown in the parent conversation.
+      - Persist each Planner revision with `skc ralplan --write --stage revision --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json` before re-review, then pass the receipt/path forward instead of duplicating the full revision markdown in the parent conversation.
    d. Return to Critic evaluation
-   e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
-   f. If 5 iterations are reached without `APPROVE`, present the best version to the user
-6. **Post-ralplan interview** (intent reconciliation gate): After Critic returns `APPROVE` and before the plan is finalized, reconcile the consensus plan against the user's actual intent. The goal is to make sure ralplan did not silently bake in assumptions that conflict with what the user wants.
+   e. Repeat this loop until Critic returns `OKAY` or 5 iterations are reached
+   f. If 5 iterations are reached without `OKAY`, present the best version to the user
+6. **Post-ralplan interview** (intent reconciliation gate): After Critic returns `OKAY` and before the plan is finalized, reconcile the consensus plan against the user's actual intent. The goal is to make sure ralplan did not silently bake in assumptions that conflict with what the user wants.
    a. **Collect open items** from the run: every assumption the Planner/Architect/Critic resolved by assumption rather than by stated fact, every ambiguity flagged during review, and every decision the loop made without explicit user input. Source these from the persisted `planner`/`architect`/`critic`/`revision` stage artifacts, not from memory.
    b. **Cross-check prior context for conflicts**: glob `.skc/_session-{sessionid}/specs/deep-interview-*.md` and other prior specs/plans/context relevant by topic. For each, list points where the consensus plan contradicts, weakens, or expands beyond a previously crystallized decision, constraint, or non-goal. Cite the conflicting artifact and line/section.
-   c. **Reconcile with the user**:
-      - *(--interactive only)* Use the `ask` tool to confirm the open assumptions and conflicts **one at a time**, weakest/highest-impact first, polishing intent. If any confirmation reveals that the plan diverges from user intent, route the consolidated correction back into the re-review loop (step 5b Planner revision) and re-run Architect + Critic before returning here. Cap at the same 5-iteration ceiling.
-      - *(automated mode)* Do not ask. Embed every unconfirmed assumption and every detected prior-context conflict into the final plan under an **## Intent Reconciliation** section as explicit open confirmations the user must review at the `pending approval` gate, so nothing is silently assumed.
-   d. Persist the reconciliation with `skc ralplan --write --stage post-interview --stage_n <N> --artifact "..." --json`, then return the receipt/path plus a compact status (reconciled-clean / reconciled-with-revision / open-confirmations-pending) instead of pasting the full body.
-7. On reconciliation completion, mark the plan `pending approval` unless explicit execution approval has already been captured, persist the ADR/final plan via `skc ralplan --write --stage final --stage_n <N> --artifact "..."`, and do not directly edit `.skc/_session-{sessionid}/plans`. *(--interactive only)* If `--interactive` is set, use the `ask` tool to present the plan with approval options (Approve execution via ultragoal (Recommended) / Approve execution via team (only when tmux-based interactive worker parallelization is required) / Compact then return for execution approval / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups) and, when present, the **## Intent Reconciliation** section. Otherwise, output the final plan and stop before any mutation or delegation.
-8. *(--interactive only)* User chooses: Approve ultragoal execution (recommended), Approve team execution (tmux parallelization only), Request changes, or Reject
-9. *(--interactive only)* On approval: invoke `/skill:ultragoal` for execution by default; invoke `/skill:team` only when the user explicitly needs tmux-based interactive worker parallelization -- never implement directly
+   c. **Reconcile with the user via the `ask` tool (always, regardless of `--interactive`)**: Never stop idle with plain-text prose after the consensus loop. Every reconciliation question MUST go through the `ask` tool with contextual options plus free-text.
+      - If open items exist, confirm the open assumptions and conflicts **one at a time** with the `ask` tool, weakest/highest-impact first, polishing intent. If any confirmation reveals that the plan diverges from user intent, route the consolidated correction back into the re-review loop (step 5b Planner revision) and re-run Architect + Critic before returning here. Cap at the same 5-iteration ceiling.
+      - If the plan is crystal clear (no open assumptions or prior-context conflicts), skip straight to the step 8 final-options `ask` instead of inventing filler questions.
+      - For every confirmed open item, embed the resolved outcome into the final plan under an **## Intent Reconciliation** section so the `pending approval` artifact records each decision; record any item the user explicitly defers as an open confirmation under that same section.
+   d. Persist the reconciliation with `skc ralplan --write --stage post-interview --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT --json`, then return the receipt/path plus a compact status (reconciled-clean / reconciled-with-revision / open-confirmations-pending) instead of pasting the full body.
+7. On reconciliation completion, mark the plan `pending approval` unless explicit execution approval has already been captured, persist the ADR/final plan via `skc ralplan --write --stage final --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT`, and do not directly edit `.skc/_session-{sessionid}/plans`. Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups) and, when present, the **## Intent Reconciliation** section.
+8. **Always** present the finalized plan via the `ask` tool (regardless of `--interactive`) with `workflowGate: { stage: "ralplan", kind: "approval" }` on the final question so RPC/headless clients receive a `ralplan`/`approval` workflow gate, not a deep-interview question gate. Use these options:
+   - **Refine further** — re-run the consensus loop / request changes, then return here
+   - **Approve execution via ultragoal (Recommended)** — goal-tracked autonomous execution
+   - **Approve execution via team** — only when tmux-based interactive worker parallelization is required
+   - **Stop here** — keep the plan as `pending approval` and make no further changes
+
+   Always include a free-text option. Do not stop with plain text and no `ask`; the post-interview gate's terminal action is this `ask`.
+9. On approval: invoke `/skill:ultragoal` for execution by default; invoke `/skill:team` only when the user explicitly needs tmux-based interactive worker parallelization. On **Refine further**, return to the step 5 re-review loop. On **Stop here**, leave the `pending approval` artifact and stop. Never implement directly.
 
    Before invoking `/skill:team` or `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition:
 
@@ -121,7 +130,7 @@ The Planner is a **same-session persisted subagent**: launched detached once, aw
 **Recording persisted-Planner metadata** (audit/routing only — never claim `subagent list` proves resumability, since the snapshot does not expose `resumable`). Ride these optional flags on the normal `--write` for the planner/revision stage of the pass:
 
 ```
-skc ralplan --write --stage revision --stage_n <N> --artifact "..." \
+skc ralplan --write --stage revision --stage_n <N> --artifact-env SKC_RALPLAN_ARTIFACT \
   --planner-id <id> --planner-resumable <true|false> \
   --fallback-reason <context_unavailable|not_found|no_runner|resume_failed|process_restart|missing_record> \
   --fallback-attempted-id <id> --fallback-stage-n <N> \