@gajae-code/coding-agent 0.7.10 → 0.8.0

package/src/modes/shared/agent-wire/deep-interview-gate.ts

@@ -131,7 +131,12 @@ function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJ
 		properties: {
 			selected: selectedBase,
 			other: { type: "boolean", description: "set true to provide a free-text answer in `custom`" },
-			custom: { type: "string", minLength: 1, description: "free-text answer; required when `other` is true" },
+			custom: {
+				type: "string",
+				minLength: 1,
+				pattern: "\\S",
+				description: "free-text answer; required when `other` is true",
+			},
 			action: {
 				type: "string",
 				enum: ["answer", "clarify"],
@@ -140,6 +145,7 @@ function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJ
 			question: {
 				type: "string",
 				minLength: 1,
+				pattern: "\\S",
 				description: "clarification question; required when action is `clarify`",
 			},
 		},
@@ -156,7 +162,7 @@ function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJ
 				properties: {
 					selected: selectedWithOther,
 					other: { const: true },
-					custom: { type: "string", minLength: 1 },
+					custom: { type: "string", minLength: 1, pattern: "\\S" },
 					action: { const: "answer" },
 				},
 				required: ["selected", "other", "custom"],
@@ -166,7 +172,7 @@ function questionAnswerSchema(question: AskGateQuestion, labels: string[]): RpcJ
 				type: "object",
 				properties: {
 					action: { const: "clarify" },
-					question: { type: "string", minLength: 1 },
+					question: { type: "string", minLength: 1, pattern: "\\S" },
 				},
 				required: ["action", "question"],
 				additionalProperties: false,

package/src/modes/shared/agent-wire/workflow-gate-schema.ts

@@ -25,6 +25,7 @@ const SUPPORTED_KEYWORDS = new Set<keyof RpcJsonSchema>([
 	"items",
 	"minLength",
 	"maxLength",
+	"pattern",
 	"minItems",
 	"maxItems",
 	"uniqueItems",
@@ -107,6 +108,17 @@ function walkSchema(schema: RpcJsonSchema, depth: number, path: string): void {
 			throw new WorkflowGateSchemaError(`${meta} at ${path} must be a string`);
 		}
 	}
+	if (schema.pattern !== undefined) {
+		if (typeof schema.pattern !== "string") {
+			throw new WorkflowGateSchemaError(`pattern at ${path} must be a string`);
+		}
+		try {
+			new RegExp(schema.pattern);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new WorkflowGateSchemaError(`pattern at ${path} must be a valid regular expression: ${message}`);
+		}
+	}
 	for (const limit of ["minLength", "maxLength", "minItems", "maxItems"] as const) {
 		const v = schema[limit];
 		if (v !== undefined && (typeof v !== "number" || !Number.isInteger(v) || v < 0)) {
@@ -242,6 +254,14 @@ function validateValue(schema: RpcJsonSchema, value: unknown, path: string, erro
 				expected: schema.maxLength,
 			});
 		}
+		if (schema.pattern !== undefined && !new RegExp(schema.pattern).test(value)) {
+			errors.push({
+				path,
+				keyword: "pattern",
+				message: `does not match pattern ${schema.pattern}`,
+				expected: schema.pattern,
+			});
+		}
 	}
 	if (typeof value === "number") {
 		if (schema.minimum !== undefined && value < schema.minimum) {

package/src/modes/slash-command-visibility.ts

@@ -0,0 +1,9 @@
+const BEGINNER_HIDDEN_EXTENSION_COMMANDS = new Set(["grok-build-usage"]);
+
+export function shouldShowExtensionCommand(name: string, activeProvider: string | undefined): boolean {
+	if (!BEGINNER_HIDDEN_EXTENSION_COMMANDS.has(name)) return true;
+	if (name === "grok-build-usage") {
+		return activeProvider === "grok-build" || Boolean(process.env.GROK_CLI_OAUTH_TOKEN);
+	}
+	return true;
+}

package/src/modes/types.ts

@@ -110,6 +110,7 @@ export interface InteractiveModeContext {
 	retryLoader: Loader | undefined;
 	autoCompactionEscapeHandler?: () => void;
 	retryEscapeHandler?: () => void;
+	retryEscapePrimed: boolean;
 	retryCountdownTimer?: NodeJS.Timeout;
 	unsubscribe?: () => void;
 	onInputCallback?: (input: SubmittedUserInput) => void;
@@ -209,6 +210,7 @@ export interface InteractiveModeContext {
 	handleUsageCommand(reports?: UsageReport[] | null): Promise<void>;
 	handleChangelogCommand(showFull?: boolean): Promise<void>;
 	handleHotkeysCommand(): void;
+	handleHelpCommand(): void;
 	handleToolsCommand(): void;
 	handleContextCommand(): void;
 	handleDumpCommand(): void;

package/src/modes/utils/hotkeys-markdown.ts

@@ -38,6 +38,8 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		`| \`${appKey(bindings, "app.clear")}\` | Clear editor (first) / exit (second) |`,
 		`| \`${appKey(bindings, "app.exit")}\` | Exit (when editor is empty) |`,
 		`| \`${appKey(bindings, "app.suspend")}\` | Suspend to background |`,
+		`| \`${appKey(bindings, "app.commandPalette.open")}\` | Open command palette |`,
+		`| \`${appKey(bindings, "app.session.new")}\` | Start a fresh session |`,
 		`| \`${appKey(bindings, "app.thinking.cycle")}\` | Cycle thinking level |`,
 		`| \`${appKey(bindings, "app.model.cycleForward")}\` | Cycle configured model roles |`,
 		`| \`${appKey(bindings, "app.model.cycleBackward")}\` | Cycle configured model roles temporarily |`,
@@ -51,8 +53,9 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 		`| \`${appKey(bindings, "app.editor.external")}\` | Edit message in external editor |`,
 		`| \`${appKey(bindings, "app.clipboard.pasteImage")}\` | Paste image from clipboard |`,
 		`| \`${appKey(bindings, "app.stt.toggle")}\` | Toggle speech-to-text recording |`,
-		"| `#` | Open prompt actions |",
-		"| `/` | Slash commands |",
+		"| `?` | Show help / shortcuts |",
+		"| `#` | Prompt actions (command-palette style actions) |",
+		"| `/` | Slash commands (try `/help` or `/new`) |",
 		"| `!` | Run bash command |",
 		"| `!!` | Run bash command (excluded from context) |",
 		"| `$` | Run Python in shared kernel |",

package/src/modes/utils/ui-helpers.ts

@@ -2,6 +2,8 @@ import type { AgentMessage } from "@gajae-code/agent-core";
 import type { AssistantMessage, ImageContent, Message } from "@gajae-code/ai";
 import { type Component, Spacer, Text, TruncatedText } from "@gajae-code/tui";
 import { settings } from "../../config/settings";
+import { resolveSubskillActivationForSkillInvocation } from "../../extensibility/gjc-plugins";
+import { buildSkillPromptMessage, parseSkillInvocations } from "../../extensibility/skills";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
 import { BashExecutionComponent } from "../../modes/components/bash-execution";
 import { BranchSummaryMessageComponent } from "../../modes/components/branch-summary-message";
@@ -610,9 +612,80 @@ export class UiHelpers {
 		this.ctx.updatePendingMessagesDisplay();
 		this.ctx.showStatus("Queued message for after compaction");
 	}
+	#hasSkillInvocations(text: string): boolean {
+		return parseSkillInvocations(text, this.ctx.skillCommands ?? new Map()).length > 0;
+	}
+
+	#isCompactionCommandMessage(text: string): boolean {
+		return this.#hasSkillInvocations(text) || this.isKnownSlashCommand(text);
+	}
+
+	async #deliverQueuedSkillMessage(message: CompactionQueuedMessage): Promise<boolean> {
+		const invocations = parseSkillInvocations(message.text, this.ctx.skillCommands ?? new Map());
+		if (invocations.length === 0) {
+			return false;
+		}
+
+		for (let index = 0; index < invocations.length; index += 1) {
+			const invocation = invocations[index];
+			if (!invocation) continue;
+
+			const activationResult = await resolveSubskillActivationForSkillInvocation({
+				cwd: this.ctx.sessionManager.getCwd(),
+				sessionId: this.ctx.session.sessionId,
+				skillName: invocation.skill.name,
+				args: invocation.args,
+			});
+			const built = await buildSkillPromptMessage(invocation.skill, activationResult.cleanedArgs, {
+				subskillActivation: activationResult.activation,
+				subskillActivationSet: activationResult.activeSubskillsToPersist,
+				cwd: this.ctx.sessionManager.getCwd(),
+				sessionId: this.ctx.session.sessionId,
+			});
+			const details: SkillPromptDetails = built.details;
+			const displayText = `/${invocation.commandName}${activationResult.cleanedArgs ? ` ${activationResult.cleanedArgs}` : ""}`;
+
+			if (this.ctx.session.isStreaming) {
+				const tag = this.ctx.session.enqueueCustomMessageDisplay(displayText, message.mode);
+				details.__pendingDisplayTag = tag;
+			}
+
+			const isLast = index === invocations.length - 1;
+			if (!this.ctx.session.isStreaming && !isLast) {
+				await this.ctx.session.sendCustomMessage({
+					customType: SKILL_PROMPT_MESSAGE_TYPE,
+					content: built.message,
+					display: true,
+					details,
+					attribution: "user",
+				});
+				continue;
+			}
 
+			await this.ctx.session.promptCustomMessage(
+				{
+					customType: SKILL_PROMPT_MESSAGE_TYPE,
+					content: built.message,
+					display: true,
+					details,
+					attribution: "user",
+				},
+				{ streamingBehavior: message.mode },
+			);
+		}
+
+		if (this.ctx.session.isStreaming) {
+			this.ctx.updatePendingMessagesDisplay();
+			this.ctx.ui.requestRender();
+		}
+
+		return true;
+	}
 	async #deliverQueuedMessage(message: CompactionQueuedMessage): Promise<void> {
-		if (this.ctx.isKnownSlashCommand(message.text)) {
+		if (await this.#deliverQueuedSkillMessage(message)) {
+			return;
+		}
+		if (this.isKnownSlashCommand(message.text)) {
 			await this.ctx.session.prompt(message.text);
 			return;
 		}
@@ -671,14 +744,14 @@ export class UiHelpers {
 
 			let firstPromptIndex = -1;
 			for (let i = 0; i < queuedMessages.length; i++) {
-				if (!this.ctx.isKnownSlashCommand(queuedMessages[i].text)) {
+				if (!this.#isCompactionCommandMessage(queuedMessages[i].text)) {
 					firstPromptIndex = i;
 					break;
 				}
 			}
 			if (firstPromptIndex === -1) {
 				for (const message of queuedMessages) {
-					await this.ctx.session.prompt(message.text);
+					await this.#deliverQueuedMessage(message);
 				}
 				return;
 			}

package/src/notifications/index.ts

@@ -26,7 +26,7 @@ import * as path from "node:path";
 import { promisify } from "node:util";
 import type { ImageContent, TextContent } from "@gajae-code/ai";
 import { NotificationServer } from "@gajae-code/natives";
-import { logger } from "@gajae-code/utils";
+import { logger, postmortem } from "@gajae-code/utils";
 import { Settings } from "../config/settings";
 import type { ExtensionCommandContext, ExtensionContext, ExtensionFactory } from "../extensibility/extensions";
 import { registerAskAnswerSource } from "../tools/ask-answer-registry";
@@ -348,6 +348,8 @@ interface SessionRuntime {
 	/** Assistant text already flushed before an ask this turn (turn-scoped dedupe
 	 * so turn_end does not re-emit the pre-ask lead-in). Reset each turn. */
 	preAskFlushedText?: string;
+	/** Cancels the postmortem cleanup that emits `session_closed` on process teardown. */
+	cancelPostmortemCleanup: () => void;
 }
 
 interface ResolvedSettings {
@@ -500,6 +502,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		if (!rt) return false;
 		runtimes.delete(id);
 		try {
+			rt.cancelPostmortemCleanup();
 			rt.disposeAnswerSource();
 			rt.disposeFileSink();
 		} catch {}
@@ -680,6 +683,7 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				pendingInteractive,
 				disposeAnswerSource,
 				disposeFileSink,
+				cancelPostmortemCleanup: () => {},
 				redact,
 				verbosity,
 				sessionTag: tag,
@@ -687,6 +691,15 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 				pendingInbound: new Set<number>(),
 			};
 			runtimes.set(id, runtime);
+			// A native terminal close (SIGHUP), SIGTERM, Ctrl+C exit, or fatal error
+			// skips AgentSession.dispose(), so the `session_shutdown` extension event
+			// never fires and the daemon-side topic would be orphaned. postmortem
+			// awaits registered cleanups on those paths, so send the graceful
+			// `session_closed` frame from there too. stopSession() cancels this
+			// registration on every other teardown path, so it never double-fires.
+			runtime.cancelPostmortemCleanup = postmortem.register(`notifications-session-closed:${id}`, async () => {
+				await stopSession(id);
+			});
 			logger.info(`notifications: serving session ${id} at ${endpoint.url} (unattended=${unattended})`);
 
 			if (settingsAvailable && settings && isGloballyConfigured(cfg)) {
@@ -848,9 +861,15 @@ export const createNotificationsExtension: ExtensionFactory = api => {
 		// Re-bind the interactive ask answer source: the ask tool resolves the
 		// source by the current session id, which just changed.
 		try {
+			rt.cancelPostmortemCleanup();
 			rt.disposeAnswerSource();
 			rt.disposeFileSink();
 		} catch {}
+		// Follow the id change so a later process teardown closes the re-keyed
+		// session (the old closure captured the retired id).
+		rt.cancelPostmortemCleanup = postmortem.register(`notifications-session-closed:${newId}`, async () => {
+			await stopSession(newId);
+		});
 		rt.disposeAnswerSource = registerInteractiveAnswerSource(
 			newId,
 			rt.server,

package/src/notifications/lifecycle-control-runtime.ts

@@ -238,6 +238,7 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 		// restart, so an unknown or ambiguous prefix fails closed instead of
 		// blindly spawning `gjc --resume <prefix>` against a non-authoritative id.
 		let resumeId = target.sessionIdOrPrefix;
+		let resumeCwd = target.path;
 		if (opts.sessionsRoot) {
 			const saved = listRecentSessions({ sessionsRoot: opts.sessionsRoot, limit: 1000 });
 			const prefixed = saved.filter(
@@ -249,11 +250,19 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 			if (resolved.length > 1) {
 				return { ambiguous: resolved.map(s => ({ sessionId: s.sessionId, path: s.path })) };
 			}
-			resumeId = resolved[0]!.sessionId;
+			const selected = resolved[0]!;
+			resumeId = selected.sessionId;
+			resumeCwd = selected.path;
+		}
+		const resolvedResumeCwd = resumeCwd ? path.resolve(resumeCwd) : undefined;
+		const resumeCwdStat = resolvedResumeCwd ? fs.statSync(resolvedResumeCwd, { throwIfNoEntry: false }) : undefined;
+		if (!resumeCwdStat?.isDirectory()) {
+			throw new Error(`gjc_lifecycle_resume_cwd_unavailable: ${resolvedResumeCwd ?? "(missing)"}`);
 		}
 		const tmux = resolveGjcTmuxCommand(env);
 		const name = tmuxSessionNameFor(resumeId);
-		const command = `exec env GJC_TMUX_LAUNCHED=1 GJC_NOTIFICATIONS=1 gjc --resume ${shellQuote(resumeId)}`;
+		const cwdPrefix = resolvedResumeCwd ? `cd ${shellQuote(resolvedResumeCwd)} && ` : "";
+		const command = `${cwdPrefix}exec env GJC_TMUX_LAUNCHED=1 GJC_NOTIFICATIONS=1 gjc --resume ${shellQuote(resumeId)}`;
 		const r = Bun.spawnSync([tmux, "new-session", "-d", "-s", name, "sh", "-c", command], {
 			stdout: "pipe",
 			stderr: "pipe",
@@ -261,7 +270,7 @@ export function daemonResumeSession(env: NodeJS.ProcessEnv = process.env, opts:
 		});
 		if (r.exitCode !== 0) throw new Error(r.stderr.toString().trim() || "gjc_lifecycle_resume_failed");
 		const tgt = buildGjcTmuxExactOptionTarget(name);
-		for (const cmd of buildGjcTmuxProfileCommands(tgt, env, { sessionId: resumeId })) {
+		for (const cmd of buildGjcTmuxProfileCommands(tgt, env, { sessionId: resumeId, project: resolvedResumeCwd })) {
 			Bun.spawnSync([tmux, ...cmd.args], { stdout: "pipe", stderr: "pipe", env });
 		}
 		return {

package/src/notifications/telegram-daemon.ts

@@ -13,7 +13,7 @@ import { parseInThreadConfigCommand } from "./config-commands";
 import { daemonPaths } from "./daemon-paths";
 import {
 	buildCompactChoiceGrid,
-	pre,
+	code,
 	splitTelegramHtml,
 	TELEGRAM_MESSAGE_LIMIT,
 	TELEGRAM_PARSE_MODE,
@@ -1117,10 +1117,10 @@ export class TelegramNotificationDaemon {
 				limit: 10,
 				includeInternal: false,
 			});
-			const lines = recent.length
-				? recent.map(e => `• ${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 replyHtml(pre(lines));
+			await replyHtml(body);
 			return true;
 		}
 

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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc 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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the verdict markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_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 `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage architect --stage_n <N> --artifact "<full review markdown>" --json
+  gjc ralplan --write --stage architect --stage_n <N> --artifact-env GJC_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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc 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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the evaluation markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_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 `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage critic --stage_n <N> --artifact "<full evaluation markdown>" --json
+  gjc ralplan --write --stage critic --stage_n <N> --artifact-env GJC_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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc 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 GJC workflow CLI persistence (`gjc ralplan --write ...`) and GJC workflow state read/write/contract commands (`gjc state ...`). For `gjc ralplan --write`, pass the plan markdown through the `GJC_RALPLAN_ARTIFACT` env override and `--artifact-env GJC_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 `gjc 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 `GJC_RALPLAN_ARTIFACT` env override (never a file path, never `/tmp`):
 
-  gjc ralplan --write --stage planner --stage_n <N> --artifact "<full plan markdown>" --json
+  gjc ralplan --write --stage planner --stage_n <N> --artifact-env GJC_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

@@ -61,10 +61,12 @@ 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.
@@ -139,6 +141,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.

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 GJC 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 GJC workflow CLI persistence or state read/write/contract operations; the only per-command env override allowed is `GJC_RALPLAN_ARTIFACT` when paired with `gjc ralplan --write ... --artifact-env GJC_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

package/src/runtime-mcp/manager.ts

@@ -147,6 +147,8 @@ export interface MCPDiscoverOptions {
 	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;
 	/** Called when starting to connect to servers */
 	onConnecting?: (serverNames: string[]) => void;
 }
@@ -325,6 +327,7 @@ export class MCPManager {
 			enableProjectConfig: options?.enableProjectConfig,
 			filterExa: options?.filterExa,
 			filterBrowser: options?.filterBrowser,
+			autoloadOnly: options?.autoloadOnly,
 		});
 		const result = await this.connectServers(configs, sources, options?.onConnecting);
 		result.exaApiKeys = exaApiKeys;

package/src/runtime-mcp/types.ts

@@ -61,6 +61,12 @@ export interface MCPAuthConfig {
 interface MCPServerConfigBase {
 	/** Whether this server is enabled (default: true) */
 	enabled?: boolean;
+	/**
+	 * Whether to connect this server automatically at session startup (default: true).
+	 * When false the server stays configured-but-disconnected until connected
+	 * explicitly (e.g. `/mcp connect <name>`).
+	 */
+	autoload?: boolean;
 	/** Connection timeout in milliseconds (default: 30000) */
 	timeout?: number;
 	/** Authentication configuration (optional) */