@gajae-code/coding-agent 0.6.0 → 0.6.3

package/src/lsp/startup-events.ts

@@ -11,3 +11,27 @@ export type LspStartupEvent =
 			type: "failed";
 			error: string;
 	  };
+const OPTIONAL_STARTUP_FAILURE_SERVERS = new Set(["rust-analyzer"]);
+
+function isOptionalStartupFailure(server: LspStartupServerInfo): boolean {
+	return server.status === "error" && OPTIONAL_STARTUP_FAILURE_SERVERS.has(server.name);
+}
+
+export function getLspStartupWarningMessage(event: LspStartupEvent): string | null {
+	if (event.type === "failed") {
+		return "LSP startup failed. It will retry lazily on write.";
+	}
+
+	const failedServers = event.servers.filter(server => server.status === "error" && !isOptionalStartupFailure(server));
+
+	if (failedServers.length === 1) {
+		return `LSP startup failed for ${failedServers[0].name}. It will retry lazily on write.`;
+	}
+
+	if (failedServers.length > 1) {
+		const failedNames = failedServers.map(server => server.name).join(", ");
+		return `LSP startup failed for ${failedNames}. It will retry lazily on write.`;
+	}
+
+	return null;
+}

package/src/modes/interactive-mode.ts

@@ -44,7 +44,7 @@ import { BUILTIN_SLASH_COMMANDS, loadSlashCommands } from "../extensibility/slas
 import { consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
 import { type Goal, type GoalModeState, normalizeGoal } from "../goals/state";
 import { resolveLocalUrlToPath } from "../internal-urls";
-import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
+import { getLspStartupWarningMessage, LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
 import {
 	humanizePlanTitle,
 	type PlanApprovalDetails,
@@ -71,6 +71,7 @@ import { normalizeLocalScheme } from "../tools/path-utils";
 import { type ResolveToolDetails, runResolveInvocation } from "../tools/resolve";
 import { formatPhaseDisplayName } from "../tools/todo-write";
 import { ToolError } from "../tools/tool-errors";
+
 import type { EventBus } from "../utils/event-bus";
 import { getEditorCommand, openInEditor } from "../utils/external-editor";
 import { getSessionAccentAnsi, getSessionAccentHex } from "../utils/session-color";
@@ -2061,23 +2062,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	#handleLspStartupEvent(event: LspStartupEvent): void {
 		this.#updateWelcomeLspServers();
 
-		if (event.type === "failed") {
-			this.showWarning(`LSP startup failed: ${event.error}. It will retry lazily on write.`);
-			return;
-		}
-
-		const failedServers = event.servers.filter(server => server.status === "error");
-
-		if (failedServers.length === 1) {
-			const failedServer = failedServers[0];
-			const detail = failedServer.error ? `: ${failedServer.error}` : "";
-			this.showWarning(`LSP startup failed for ${failedServer.name}${detail}. It will retry lazily on write.`);
-			return;
-		}
-
-		if (failedServers.length > 1) {
-			const failedNames = failedServers.map(server => server.name).join(", ");
-			this.showWarning(`LSP startup failed for ${failedNames}. It will retry lazily on write.`);
+		const warningMessage = getLspStartupWarningMessage(event);
+		if (warningMessage) {
+			this.showWarning(warningMessage);
 		}
 	}
 

package/src/session/agent-session.ts

@@ -44,7 +44,6 @@ import {
 	type EmergencyCompactionSample,
 	emergencyCompactionReason,
 	estimateMessageTokensHeuristic,
-	estimateTokens,
 	generateBranchSummary,
 	generateHandoff,
 	prepareCompaction,
@@ -225,7 +224,7 @@ import {
 	readVisibleSkillActiveState,
 	syncSkillActiveState,
 } from "../skill-state/active-state";
-import { assertDeepInterviewMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
+import { assertWorkflowMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import {
@@ -1475,7 +1474,7 @@ export class AgentSession {
 			}
 			const sanitized = sanitizeMessage(providerMessages[i]!);
 			if (!sanitized) continue;
-			const messageTokens = estimateTokens(sanitized);
+			const messageTokens = estimateMessageTokensHeuristic(sanitized);
 			if (maxTokens > 0 && approximateTokens + messageTokens > maxTokens) {
 				recordSkip("token-limit");
 				continue;
@@ -3775,7 +3774,7 @@ export class AgentSession {
 					onUpdate: never,
 					ctx: never,
 				) => {
-					await assertDeepInterviewMutationAllowed({
+					await assertWorkflowMutationAllowed({
 						cwd: this.sessionManager.getCwd(),
 						sessionId: this.sessionManager.getSessionId(),
 						tool: target,
@@ -9901,9 +9900,9 @@ export class AgentSession {
 	#estimateContextTokensForCompaction(pendingMessages: readonly AgentMessage[]): {
 		tokens: number;
 	} {
-		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageNativeContextTokens(message));
+		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageCompactionDeltaTokens(message));
 		return {
-			tokens: estimate.tokens + this.#estimateMessagesNativeContextTokens(pendingMessages),
+			tokens: estimate.tokens + this.#estimateMessagesCompactionDeltaTokens(pendingMessages),
 		};
 	}
 
@@ -9949,10 +9948,10 @@ export class AgentSession {
 		};
 	}
 
-	#estimateMessagesNativeContextTokens(messages: readonly AgentMessage[]): number {
+	#estimateMessagesCompactionDeltaTokens(messages: readonly AgentMessage[]): number {
 		let tokens = 0;
 		for (const message of messages) {
-			tokens += this.#estimateMessageNativeContextTokens(message);
+			tokens += this.#estimateMessageCompactionDeltaTokens(message);
 		}
 		return tokens;
 	}
@@ -9965,11 +9964,17 @@ export class AgentSession {
 		return tokens;
 	}
 
-	#nativeTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
+	/**
+	 * Conservative inflation applied to the native-free chars/4 estimate of the
+	 * UNSENT context delta. chars/4 undercounts dense code/CJK, so we bias high
+	 * to compact slightly early rather than overflow the model window before the
+	 * next provider response re-anchors the exact count.
+	 */
+	#compactionDeltaInflation = 1.2;
+	#compactionDeltaTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
 
-	/** Cheap content-size signal to invalidate the native token cache on mutation (growth). */
 	/**
-	 * Cheap content-size signal to invalidate the native token cache on mutation. Recursively
+	 * Cheap content-size signal to invalidate the compaction-delta token cache on mutation. Recursively
 	 * sums string lengths across the whole message (depth-bounded), so it covers every
 	 * provider-visible shape (text/thinking/tool args, toolResult output, tool names, etc.)
 	 * without allocating a serialized copy. A size-preserving in-place edit yields only a
@@ -9992,19 +9997,22 @@ export class AgentSession {
 		return 0;
 	}
 
-	#estimateMessageNativeContextTokens(message: AgentMessage): number {
-		// F10/F22: cache the expensive native token count per message object, invalidated by a
-		// cheap content-size signal, so unchanged (stable-size) messages are not re-tokenized on
-		// every pre-prompt estimate. A rare size-preserving in-place edit yields only a benign
-		// token-estimate drift, never wrong output.
+	#estimateMessageCompactionDeltaTokens(message: AgentMessage): number {
+		// Provider usage anchors the already-sent context (see calculatePromptTokens); this
+		// estimates only the UNSENT delta with the native-free chars/4 heuristic, inflated by
+		// #compactionDeltaInflation so dense input cannot undercount us past the compaction
+		// threshold before the next provider response re-anchors the exact count. Cached per
+		// message object, invalidated by a cheap content-size signal; a rare size-preserving
+		// in-place edit yields only a benign estimate drift, never wrong output.
 		const len = this.#messageTokenSize(message);
-		const cached = this.#nativeTokenCache.get(message);
+		const cached = this.#compactionDeltaTokenCache.get(message);
 		if (cached && cached.len === len) return cached.tokens;
-		let tokens = 0;
+		let heuristic = 0;
 		for (const llmMessage of convertToLlm([message])) {
-			tokens += estimateTokens(llmMessage);
+			heuristic += estimateMessageTokensHeuristic(llmMessage);
 		}
-		this.#nativeTokenCache.set(message, { len, tokens });
+		const tokens = Math.ceil(heuristic * this.#compactionDeltaInflation);
+		this.#compactionDeltaTokenCache.set(message, { len, tokens });
 		return tokens;
 	}
 

package/src/skill-state/active-state.ts

@@ -559,39 +559,44 @@ function dedupeVisibleBySkill(entries: SkillActiveEntry[], sessionId?: string):
 
 /**
  * The planning pipeline advances one stage at a time: `deep-interview →
- * ralplan → ultragoal`. Each stage is activated through its own command path
- * (`gjc deep-interview`, `gjc ralplan`, `gjc ultragoal`), and those activations
- * do not demote the previous stage's row — only the explicit `handoff` verb
- * does. Without this collapse, activating ultragoal while ralplan is still
- * `active:true` would render both stages and keep showing a workflow that has
- * already handed control forward. Keep only the most recently updated pipeline
- * stage so the HUD reflects the single current workflow. `team` is intentionally
- * excluded — it runs alongside ultragoal — and every non-pipeline skill is left
- * untouched.
- *
- * This is a HUD-display policy only. It is applied by the skill HUD renderer and
- * deliberately NOT folded into `readVisibleSkillActiveState`, whose callers (the
- * deep-interview mutation guard and handoff caller inference) must keep seeing
- * every genuinely-active skill rather than the single most-recent pipeline stage.
+ * ralplan → ultragoal`. Activating a downstream stage supersedes upstream
+ * stages so stale rows cannot keep owning the HUD, gate, or primary active
+ * snapshot. `team` is intentionally excluded — it runs alongside ultragoal —
+ * and every non-pipeline skill is left untouched.
  */
 const PLANNING_PIPELINE_SKILLS = new Set<string>(["deep-interview", "ralplan", "ultragoal"]);
+const PLANNING_PIPELINE_RANK = new Map<string, number>([
+	["deep-interview", 0],
+	["ralplan", 1],
+	["ultragoal", 2],
+]);
+
+function planningPipelineRank(skill: string): number | undefined {
+	return PLANNING_PIPELINE_RANK.get(skill);
+}
+
+function comparePipelineEntry(a: SkillActiveEntry, b: SkillActiveEntry): number {
+	const aRank = planningPipelineRank(a.skill);
+	const bRank = planningPipelineRank(b.skill);
+	if (aRank !== undefined || bRank !== undefined) return (bRank ?? -1) - (aRank ?? -1);
+	const aRecency = entryRecency(a);
+	const bRecency = entryRecency(b);
+	if (Number.isFinite(aRecency) || Number.isFinite(bRecency)) return (bRecency || 0) - (aRecency || 0);
+	return 0;
+}
+
+function upstreamPlanningPipelineSkills(skill: string): string[] {
+	const rank = planningPipelineRank(skill);
+	if (rank === undefined) return [];
+	return [...PLANNING_PIPELINE_RANK.entries()]
+		.filter(([, candidateRank]) => candidateRank < rank)
+		.map(([candidate]) => candidate);
+}
 
 export function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[] {
 	const pipeline = entries.filter(entry => PLANNING_PIPELINE_SKILLS.has(entry.skill));
 	if (pipeline.length <= 1) return [...entries];
-	let current = pipeline[0];
-	let currentRecency = entryRecency(current);
-	for (const entry of pipeline) {
-		const recency = entryRecency(entry);
-		// Prefer a strictly-newer valid timestamp; a valid timestamp also beats a
-		// missing/unparseable one. Ties (or all-invalid) keep the first stage
-		// deterministically rather than letting an unknown-recency row win.
-		const better = Number.isFinite(recency) && (!Number.isFinite(currentRecency) || recency > currentRecency);
-		if (better) {
-			current = entry;
-			currentRecency = recency;
-		}
-	}
+	const current = pipeline.toSorted(comparePipelineEntry)[0];
 	return entries.filter(entry => !PLANNING_PIPELINE_SKILLS.has(entry.skill) || entry === current);
 }
 
@@ -618,9 +623,11 @@ async function mergeVisibleEntries(
 		merged.set(entryKey(entry), entry);
 	}
 	const canonicalRalplanPhase = await readModeStatePhase(cwd, sessionId, "ralplan");
-	return dedupeVisibleBySkill([...merged.values()], sessionId)
-		.filter(entry => entry.active !== false)
-		.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase));
+	return collapsePlanningPipeline(
+		dedupeVisibleBySkill([...merged.values()], sessionId)
+			.filter(entry => entry.active !== false)
+			.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase)),
+	);
 }
 
 export async function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null> {
@@ -682,6 +689,20 @@ async function rebuildActiveState(cwd: string, sessionScope?: ActiveSessionScope
 	await rebuildActiveSnapshot(cwd, sessionScope, { cwd, audit: activeStateWriterAudit("rebuild-active-snapshot") });
 }
 
+async function removeSupersededPlanningPipelineEntries(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	if (entry.active === false) return;
+	for (const skill of upstreamPlanningPipelineSkills(entry.skill)) {
+		await removeActiveEntry(cwd, sessionScope, skill, {
+			cwd,
+			audit: activeStateWriterAudit("remove-superseded-pipeline-entry"),
+		});
+	}
+}
+
 async function activeSubskillsForExistingEntry(
 	cwd: string,
 	sessionId: string | undefined,
@@ -725,11 +746,13 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 				? { active_subskills: preservedActiveSubskills }
 				: {}),
 	};
+	await removeSupersededPlanningPipelineEntries(options.cwd, undefined, entry);
 	await persistActiveEntry(options.cwd, undefined, entry);
 	await rebuildActiveState(options.cwd);
 
 	if (!options.sessionId) return;
 	const sessionScope = { sessionId: options.sessionId };
+	await removeSupersededPlanningPipelineEntries(options.cwd, sessionScope, entry);
 	await persistActiveEntry(options.cwd, sessionScope, entry);
 	await rebuildActiveState(options.cwd, sessionScope);
 }

package/src/skill-state/deep-interview-mutation-guard.ts

@@ -1,3 +1,5 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentTool } from "@gajae-code/agent-core";
 import { logger } from "@gajae-code/utils";
@@ -17,6 +19,17 @@ export const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE =
 	"Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `gjc deep-interview --write --stage final` or hand off to an execution phase.";
 export const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE =
 	".gjc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.gjc/**`; use the sanctioned `gjc` CLI instead.";
+export const RALPLAN_MUTATION_BLOCK_MESSAGE =
+	"Ralplan planning phase boundary: keep refining the consensus plan and persist plan artifacts through `gjc ralplan --write` (stage scratch files under a temp dir if needed). Product-code mutation tools and patch execution are blocked while ralplan is active; mutate only after the plan is approved and execution begins.";
+export const ULTRAGOAL_GOAL_PLANNING_MUTATION_BLOCK_MESSAGE =
+	"Ultragoal goal-planning phase boundary: finish goal planning and record goals through `gjc ultragoal` before editing code. Product-code mutation tools and patch execution are blocked until goal planning completes and execution begins.";
+
+/** Resolve the phase-boundary block message for the active planning skill. */
+function planningPhaseBlockMessage(skill: CanonicalGjcWorkflowSkill): string {
+	if (skill === "ralplan") return RALPLAN_MUTATION_BLOCK_MESSAGE;
+	if (skill === "ultragoal") return ULTRAGOAL_GOAL_PLANNING_MUTATION_BLOCK_MESSAGE;
+	return DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE;
+}
 
 const BLOCKED_TOOL_NAMES = new Set(["edit", "write", "ast_edit", "bash"]);
 const ARCHIVE_OR_SQLITE_BASE_RE = /^(.+?\.(?:tar\.gz|sqlite3|sqlite|db3|zip|tgz|tar|db))(?:$|:)/i;
@@ -25,6 +38,19 @@ const VIM_FILE_SWITCH_RE = /^\s*:(?:e|e!|edit|edit!)(?:\s+([^<\r\n]+))?(?:<CR>|\
 const BASH_TOKEN_RE = /'[^']*'|"(?:\\.|[^"\\])*"|\S+/g;
 const BASH_REDIRECT_RE = /^(?:\d*)>>?$/;
 const BASH_HEREDOC_RE = /^(?:\d*)<<-?$/;
+// Shell command-list / redirection / substitution operators. Includes `\r` and
+// `\n` because the shell treats a newline as a command separator and tool command
+// strings can be multiline (e.g. heredocs).
+const BASH_CONTROL_OPERATOR_RE = /[;&|<>`\r\n]|\$\(/;
+// Best-effort, defense-in-depth bash mutation detection. The authoritative
+// planning-phase guard is the dedicated `write`/`edit`/`ast_edit` tools (fully
+// pathed); this catches the common shell mutators plus all redirect targets so a
+// cooperative agent cannot trivially side-step those tools. It is deliberately
+// NOT exhaustive: arbitrary interpreters (`python -c`, `node -e`) and the
+// `key=value` operand forms of utilities like `dd of=` are not parsed, and path
+// classification is lexical (no realpath), matching the rest of this guard and
+// the broader `.gjc` path handling. Hardening any of these would require a real
+// shell parser / symlink resolution and is out of scope for the planning rails.
 const BASH_MUTATION_COMMANDS = new Set(["rm", "mv", "cp", "touch", "mkdir", "ln", "tee"]);
 
 type ToolWithEditMode = AgentTool & {
@@ -111,13 +137,13 @@ async function readVisibleModeState(cwd: string, skill: string, sessionId?: stri
 	return await readValidatedModeState(modeStatePath(cwd, skill));
 }
 
-function isTerminalModeState(state: ModeState | null): boolean {
-	if (state?.active !== true) return true;
-	const phase = String(state.current_phase ?? "")
-		.trim()
-		.toLowerCase();
-	return ["complete", "completed", "failed", "cancelled", "canceled", "inactive"].includes(phase);
-}
+/**
+ * Phases that genuinely finish a workflow skill. Mirrors the Stop hook's
+ * `STOP_RELEASING_PHASES` (`hooks/skill-state.ts`): `handoff` is intentionally
+ * absent so a handoff-required planning skill (deep-interview/ralplan) keeps
+ * blocking through its handoff/ask window until it is demoted or cleared.
+ */
+const WORKFLOW_FINISHED_PHASES = new Set(["complete", "completed", "failed", "cancelled", "canceled", "inactive"]);
 
 function entryMatchesContext(entry: SkillActiveEntry, sessionId?: string, threadId?: string): boolean {
 	if (sessionId && entry.session_id && entry.session_id !== sessionId) return false;
@@ -131,17 +157,90 @@ function modeStateMatchesContext(state: ModeState, sessionId?: string, threadId?
 	return true;
 }
 
-async function isActiveDeepInterview(cwd: string, sessionId?: string, threadId?: string): Promise<boolean> {
+/** Workflow skills that have a pre-approval planning posture this guard enforces. `team` never does. */
+function isPlanningSkill(skill: string): skill is "deep-interview" | "ralplan" | "ultragoal" {
+	return skill === "deep-interview" || skill === "ralplan" || skill === "ultragoal";
+}
+
+/**
+ * Whether `skill` in `phase` is a pre-approval planning posture that must block
+ * product-code mutation. `deep-interview` and `ralplan` are wholly pre-approval
+ * (every phase blocks except a genuinely-finished one — `handoff` and ralplan's
+ * `final` keep blocking until execution is approved and the skill is demoted).
+ * `ultragoal` only blocks during `goal-planning`; once goals are created it is an
+ * executor and mutates freely.
+ */
+function isBlockingPlanningPhase(skill: "deep-interview" | "ralplan" | "ultragoal", phase: string): boolean {
+	const normalized = phase.trim().toLowerCase();
+	if (skill === "ultragoal") return normalized === "goal-planning";
+	return !WORKFLOW_FINISHED_PHASES.has(normalized);
+}
+
+interface ActivePlanningSkill {
+	skill: "deep-interview" | "ralplan" | "ultragoal";
+	phase: string;
+}
+
+/**
+ * Pick the single CURRENT workflow entry among active entries.
+ *
+ * Steady state has exactly one active workflow skill (handoff demotes the prior
+ * to `active:false`, which `listActiveSkills` already filters out). If several
+ * are momentarily active, prefer the most-recently-updated entry so a stale
+ * planning row (e.g. a still-active ralplan `final`) can never be selected over a
+ * newer executor (ultragoal/team), and a planning *return* (newer `updated_at`)
+ * reliably wins. Ties fall back to the resolved top-level `skill`, then to the
+ * first entry, matching how the HUD/chain guard pick `activeSkills[0]`.
+ */
+function resolveCurrentWorkflowEntry(entries: SkillActiveEntry[], topLevelSkill: string): SkillActiveEntry {
+	const ts = (entry: SkillActiveEntry): number => {
+		const value = Date.parse(safeString(entry.updated_at) || safeString(entry.activated_at));
+		return Number.isNaN(value) ? -1 : value;
+	};
+	let best = entries[0];
+	for (const entry of entries) {
+		const delta = ts(entry) - ts(best);
+		if (delta > 0) best = entry;
+		else if (delta === 0 && topLevelSkill && entry.skill === topLevelSkill) best = entry;
+	}
+	return best;
+}
+
+/**
+ * Resolve the single active pre-approval planning skill for this context, or null.
+ *
+ * Transition/return safety: this keys off the ONE canonical current workflow
+ * skill (the resolved top-level `skill` that the HUD and the skill-tool chain
+ * guard treat as active), not an independent scan of every skill. A handoff
+ * atomically demotes the prior skill and promotes the callee, and a return
+ * (e.g. re-entering ralplan/deep-interview after an ultragoal goal completes)
+ * re-activates the planning skill — in every case "whatever skill is current"
+ * governs, so a stale planning entry can never block while an executor runs and
+ * a resumed planning phase reliably re-blocks.
+ *
+ * Fail-open contract: a missing or invalid durable mode-state releases the block
+ * (a corrupt state file must not lock all mutation), matching the guard's
+ * historical behavior — this is intentionally looser than the Stop hook, which
+ * fails closed for handoff-required skills.
+ */
+async function getActivePlanningSkill(
+	cwd: string,
+	sessionId?: string,
+	threadId?: string,
+): Promise<ActivePlanningSkill | null> {
 	const skillState = await readVisibleSkillActiveState(cwd, sessionId);
-	const activeDeepInterview = listActiveSkills(skillState).find(
-		entry => entry.skill === "deep-interview" && entryMatchesContext(entry, sessionId, threadId),
-	);
-	if (!activeDeepInterview) return false;
-
-	const modeState = await readVisibleModeState(cwd, "deep-interview", sessionId);
-	if (isTerminalModeState(modeState)) return false;
-	if (modeState && !modeStateMatchesContext(modeState, sessionId, threadId)) return false;
-	return true;
+	if (!skillState) return null;
+	const activeEntries = listActiveSkills(skillState).filter(entry => entryMatchesContext(entry, sessionId, threadId));
+	if (activeEntries.length === 0) return null;
+	const current = resolveCurrentWorkflowEntry(activeEntries, safeString(skillState.skill).trim());
+	if (!isPlanningSkill(current.skill)) return null;
+	const modeState = await readVisibleModeState(cwd, current.skill, sessionId);
+	if (!modeState) return null;
+	if (modeState.active !== true) return null;
+	if (!modeStateMatchesContext(modeState, sessionId, threadId)) return null;
+	const phase = String(modeState.current_phase ?? current.phase ?? "").trim();
+	if (!isBlockingPlanningPhase(current.skill, phase)) return null;
+	return { skill: current.skill, phase };
 }
 
 function normalizePosix(value: string): string {
@@ -251,7 +350,13 @@ function extractBashTargets(args: unknown): ExtractedTargets {
 		targets.unknown = true;
 		return targets;
 	}
-	if (/^gjc(?:\s|$)/.test(command)) return targets;
+	// Fast path for a sanctioned `gjc …` invocation, but ONLY when it is a single
+	// command with no shell control operators or redirects. Otherwise a compound
+	// like `gjc … ; tee src/x` or `gjc … > .gjc/state/foo` would skip scanning and
+	// bypass both the planning block and the always-on `.gjc/**` block, so fall
+	// through to full token scanning (which leaves the `gjc` segment's own args
+	// unextracted but still catches the trailing mutation/redirect).
+	if (/^gjc(?:\s|$)/.test(command) && !BASH_CONTROL_OPERATOR_RE.test(command)) return targets;
 
 	const tokens = command.match(BASH_TOKEN_RE)?.map(unquoteBashToken) ?? [];
 	for (let index = 0; index < tokens.length; index++) {
@@ -266,14 +371,14 @@ function extractBashTargets(args: unknown): ExtractedTargets {
 			addPath(targets, redirectMatch[1]);
 			continue;
 		}
+		// A heredoc delimiter (`<<EOF`) is a here-document word, NOT a filesystem
+		// target. Consume it without recording a target so a legitimate
+		// `cat <<EOF > /tmp/scratch.md` is judged solely by its redirect target.
 		if (BASH_HEREDOC_RE.test(token)) {
-			addPath(targets, tokens[index + 1]);
 			index++;
 			continue;
 		}
-		const heredocMatch = token.match(/^(?:\d*)<<-?(.+)$/);
-		if (heredocMatch?.[1]) {
-			addPath(targets, heredocMatch[1]);
+		if (/^(?:\d*)<<-?.+$/.test(token)) {
 			continue;
 		}
 		if (isMutationBashCommand(tokens, index)) {
@@ -392,6 +497,84 @@ function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean
 		!targets.unknown && targets.paths.length > 0 && targets.paths.every(rawPath => isAllowlistedPath(cwd, rawPath))
 	);
 }
+
+function neutralTempRoots(): string[] {
+	const roots = new Set<string>();
+	const add = (value: string | undefined): void => {
+		const trimmed = value?.trim();
+		if (trimmed) roots.add(path.resolve(trimmed));
+	};
+	add(os.tmpdir());
+	add(process.env.TMPDIR);
+	for (const fixed of ["/tmp", "/var/tmp", "/private/tmp", "/private/var/tmp"]) add(fixed);
+	return [...roots];
+}
+
+function isPathWithin(root: string, target: string): boolean {
+	const rel = path.relative(root, target);
+	return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+async function realpathOrSelf(target: string): Promise<string> {
+	try {
+		return await fs.realpath(target);
+	} catch {
+		return target;
+	}
+}
+
+/**
+ * Canonicalize a target whose leaf may not exist yet (we are about to write it):
+ * realpath the nearest existing ancestor and re-append the not-yet-existing
+ * suffix, so a symlinked ancestor (or macOS `/tmp` → `/private/tmp` alias) is
+ * resolved to its real location.
+ */
+async function canonicalizeForContainment(absolutePath: string): Promise<string> {
+	const suffix: string[] = [];
+	let current = absolutePath;
+	for (let depth = 0; depth < 64; depth++) {
+		try {
+			const real = await fs.realpath(current);
+			return suffix.length > 0 ? path.join(real, ...suffix.reverse()) : real;
+		} catch {
+			const parent = path.dirname(current);
+			if (parent === current) break;
+			suffix.push(path.basename(current));
+			current = parent;
+		}
+	}
+	return absolutePath;
+}
+
+/**
+ * A neutral scratch path the planning-phase block tolerates: it resolves to a
+ * system temp directory and lives OUTSIDE the project cwd. Files inside the
+ * project tree (product code, `.gjc/**`) are never neutral, even when the cwd
+ * itself is rooted under a temp dir. The lexical checks run first; a canonical
+ * (symlink/alias-resolved) re-check then ensures the REAL target is still outside
+ * the project and inside a real temp root, defeating a temp symlink that points
+ * back into the repo or `.gjc/`.
+ */
+async function isNeutralTempPath(cwd: string, rawPath: string): Promise<boolean> {
+	const { absolutePath, unknown } = resolveRawPath(cwd, rawPath);
+	if (unknown || !absolutePath) return false;
+	const resolvedCwd = path.resolve(cwd);
+	if (isPathWithin(resolvedCwd, absolutePath)) return false;
+	if (!neutralTempRoots().some(root => isPathWithin(root, absolutePath))) return false;
+	const realTarget = await canonicalizeForContainment(absolutePath);
+	if (isPathWithin(await realpathOrSelf(resolvedCwd), realTarget)) return false;
+	const realRoots = await Promise.all(neutralTempRoots().map(realpathOrSelf));
+	return realRoots.some(root => isPathWithin(root, realTarget));
+}
+
+/** Targets that remain disallowed during a planning phase (excludes neutral temp scratch). */
+async function planningBlockedTargets(cwd: string, targets: ExtractedTargets): Promise<string[]> {
+	const blocked: string[] = [];
+	for (const rawPath of targets.paths) {
+		if (!(await isNeutralTempPath(cwd, rawPath))) blocked.push(rawPath);
+	}
+	return blocked;
+}
 export async function assertDeepInterviewMutationRawPathsAllowed(input: {
 	cwd: string;
 	sessionId?: string;
@@ -399,12 +582,21 @@ export async function assertDeepInterviewMutationRawPathsAllowed(input: {
 	rawPaths: string[];
 	forceOverride?: boolean;
 }): Promise<void> {
-	if (input.forceOverride) return;
-	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) return;
 	const targets: ExtractedTargets = { paths: input.rawPaths, unknown: input.rawPaths.length === 0 };
-	if (targets.unknown || targets.paths.length > 0) {
-		throw new ToolError(DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE);
+	// Always-on `.gjc/**` runtime-owned block, in parity with getDeepInterviewMutationDecision
+	// and ahead of forceOverride: a deferred ast_edit apply must not reach `.gjc/**` either.
+	if (hasBlockedGjcTarget(input.cwd, targets)) {
+		const stateSkill = firstBlockedWorkflowStateSkill(input.cwd, targets);
+		const command = stateSkill ? sanctionedWorkflowStateCommand(stateSkill) : "gjc <workflow-command>";
+		throw new ToolError(`${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`);
 	}
+	if (input.forceOverride) return;
+	const planning = await getActivePlanningSkill(input.cwd, input.sessionId, input.threadId);
+	if (!planning) return;
+	const message = planningPhaseBlockMessage(planning.skill);
+	if (input.rawPaths.length === 0) throw new ToolError(message);
+	const blocked = await planningBlockedTargets(input.cwd, targets);
+	if (blocked.length > 0) throw new ToolError(message);
 }
 
 export async function getDeepInterviewMutationDecision(
@@ -423,24 +615,30 @@ export async function getDeepInterviewMutationDecision(
 			command,
 		};
 	}
-	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) {
+	const planning = await getActivePlanningSkill(input.cwd, input.sessionId, input.threadId);
+	if (!planning) {
 		return { blocked: false, targets: [] };
 	}
 	if (input.forceOverride) return { blocked: false, targets: [] };
+	const message = planningPhaseBlockMessage(planning.skill);
 	if (targets.unknown) {
 		return {
 			blocked: true,
-			message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
+			message,
 			targets: targets.paths,
 			reason: "unknown-target",
 		};
 	}
-	if (input.tool.name === "bash") {
+	// Neutral temp scratch (outside the project tree) stays writable so agents can
+	// stage artifacts and feed their path to the sanctioned `gjc ... --write` CLIs.
+	// Read-only / `gjc` bash extract no targets and fall through to allowed here.
+	const blockedTargets = await planningBlockedTargets(input.cwd, targets);
+	if (blockedTargets.length === 0) {
 		return { blocked: false, targets: targets.paths };
 	}
 	return {
 		blocked: true,
-		message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,
+		message,
 		targets: targets.paths,
 		reason: allTargetsAllowlisted(input.cwd, targets) ? "handoff-artifact-tool-target" : "phase-boundary",
 	};
@@ -450,3 +648,13 @@ export async function assertDeepInterviewMutationAllowed(input: DeepInterviewMut
 	const decision = await getDeepInterviewMutationDecision(input);
 	if (decision.blocked) throw new ToolError(decision.message ?? DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE);
 }
+
+/*
+ * Generic cross-workflow names for this planning-phase mutation guard. The guard
+ * now governs deep-interview, ralplan, and ultragoal goal-planning, so new
+ * callers SHOULD use these names; the `*DeepInterview*` exports above remain as
+ * compatibility aliases (and are still what the test-suite imports).
+ */
+export const getWorkflowMutationDecision = getDeepInterviewMutationDecision;
+export const assertWorkflowMutationAllowed = assertDeepInterviewMutationAllowed;
+export const assertWorkflowMutationRawPathsAllowed = assertDeepInterviewMutationRawPathsAllowed;