@gajae-code/coding-agent 0.18.7 → 0.18.9

package/src/task/isolation-dir.ts

@@ -0,0 +1,143 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const ALLOCATION_ATTEMPTS = 8;
+
+type PathApi = Pick<typeof path, "dirname" | "isAbsolute" | "relative" | "resolve" | "sep">;
+
+function isErrno(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function defaultToken(): string {
+	return randomBytes(9).toString("hex");
+}
+
+/**
+ * Parent directory of `mergedDir`, but only when it is a single entry inside
+ * `worktreeRoot`. Root, empty, nested, and escaped paths are refused so
+ * cleanup cannot delete the worktree root or another session's tree by
+ * walking up.
+ */
+export function resolveIsolationRemovalTarget(
+	mergedDir: string,
+	worktreeRoot: string,
+	pathApi: PathApi = path,
+): string {
+	if (mergedDir.length === 0) {
+		throw new Error("Refusing to remove an isolation directory for an empty merged path.");
+	}
+	if (worktreeRoot.length === 0) {
+		throw new Error("Refusing to remove an isolation directory without a worktree root.");
+	}
+	const baseDir = pathApi.resolve(pathApi.dirname(mergedDir));
+	const root = pathApi.resolve(worktreeRoot);
+	const relative = pathApi.relative(root, baseDir);
+	if (
+		relative.length === 0 ||
+		relative === "." ||
+		relative.startsWith("..") ||
+		pathApi.isAbsolute(relative) ||
+		relative.includes(pathApi.sep) ||
+		relative.includes("/") ||
+		relative.includes("\\")
+	) {
+		throw new Error("Refusing to remove an isolation directory that is not a single worktree entry.");
+	}
+	return baseDir;
+}
+
+/**
+ * Create an exclusive directory next to `canonicalBaseDir`. Never removes
+ * `canonicalBaseDir` or any path that already exists.
+ */
+export async function allocateDisjointIsolationDir(
+	canonicalBaseDir: string,
+	tokenFactory: () => string = defaultToken,
+): Promise<string> {
+	const parent = path.dirname(canonicalBaseDir);
+	const stem = path.basename(canonicalBaseDir);
+	if (stem.length === 0 || stem === "." || stem === ".." || stem.includes("/") || stem.includes("\\")) {
+		throw new Error("Isolation directory name is not a single path segment.");
+	}
+	await fs.mkdir(parent, { recursive: true, mode: 0o700 });
+
+	for (let attempt = 0; attempt < ALLOCATION_ATTEMPTS; attempt++) {
+		const token = tokenFactory();
+		if (!/^[0-9a-f]+$/i.test(token)) {
+			throw new Error("Isolation directory token is not hexadecimal.");
+		}
+		const name = `${stem}-${token}`;
+		const baseDir = path.join(parent, name);
+		const relative = path.relative(parent, baseDir);
+		if (relative !== name || path.isAbsolute(relative)) {
+			throw new Error("Isolation directory escaped its parent.");
+		}
+		try {
+			await fs.mkdir(baseDir, { mode: 0o700 });
+			return baseDir;
+		} catch (error) {
+			if (isErrno(error, "EEXIST")) continue;
+			if (isErrno(error, "EPERM")) {
+				try {
+					await fs.lstat(baseDir);
+					continue;
+				} catch (statError) {
+					if (!isErrno(statError, "ENOENT")) throw statError;
+				}
+			}
+			throw error;
+		}
+	}
+
+	throw new Error("Failed to allocate a disjoint task isolation directory.");
+}
+
+/**
+ * Confirm native teardown may see `mergedDir`.
+ *
+ * `isoStop` deletes that path. The parent entry and `merged` itself must
+ * already be real directories, because native removal follows symlinks.
+ * A missing parent means there is nothing to stop. This does not close a
+ * replacement that happens after the lstat returns.
+ */
+export async function assertIsolationTeardownTarget(mergedDir: string, worktreeRoot: string): Promise<"stop" | "skip"> {
+	const baseDir = resolveIsolationRemovalTarget(mergedDir, worktreeRoot);
+	let baseInfo: { isSymbolicLink(): boolean };
+	try {
+		baseInfo = await fs.lstat(baseDir);
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return "skip";
+		throw error;
+	}
+	if (baseInfo.isSymbolicLink()) {
+		throw new Error("Refusing to remove a symlinked isolation directory.");
+	}
+	try {
+		const mergedInfo = await fs.lstat(mergedDir);
+		if (mergedInfo.isSymbolicLink()) {
+			throw new Error("Refusing to tear down a symlinked isolation merged directory.");
+		}
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return "stop";
+		throw error;
+	}
+	return "stop";
+}
+
+/** Remove the isolation directory that owns `mergedDir`. Missing directories are ignored. */
+export async function removeIsolationDirectory(mergedDir: string, worktreeRoot: string): Promise<void> {
+	const baseDir = resolveIsolationRemovalTarget(mergedDir, worktreeRoot);
+	let info: { isSymbolicLink(): boolean };
+	try {
+		info = await fs.lstat(baseDir);
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return;
+		throw error;
+	}
+	if (info.isSymbolicLink()) {
+		throw new Error("Refusing to remove a symlinked isolation directory.");
+	}
+	await fs.rm(baseDir, { recursive: true, force: true });
+}

package/src/task/worktree.ts

@@ -5,8 +5,9 @@ import * as path from "node:path";
 
 import type * as natives from "@gajae-code/natives";
 
-import { getWorktreeDir, hashPath, logger, Snowflake } from "@gajae-code/utils";
+import { getWorktreeDir, getWorktreesDir, hashPath, logger, Snowflake } from "@gajae-code/utils";
 import * as git from "../utils/git";
+import { allocateDisjointIsolationDir, assertIsolationTeardownTarget, removeIsolationDirectory } from "./isolation-dir";
 
 let nativeWorktreeBindings: typeof import("@gajae-code/natives") | undefined;
 
@@ -401,8 +402,13 @@ export async function ensureIsolation(
 	preferred?: IsoBackendKind,
 ): Promise<IsolationHandle> {
 	const repoRoot = await getRepoRoot(baseCwd);
-	const baseDir = getWorktreeDir(`${id}-${hashPath(repoRoot)}`);
+	// Task ids are allocated inside one session, so `<id>-<repo hash>` is shared
+	// by every fresh session's first task. Never remove that canonical directory.
+	// Each attempt gets an exclusive sibling and only that sibling is removed.
+	const canonicalBaseDir = getWorktreeDir(`${id}-${hashPath(repoRoot)}`);
+	const baseDir = await allocateDisjointIsolationDir(canonicalBaseDir);
 	const mergedDir = path.join(baseDir, "merged");
+	const worktreeRoot = getWorktreesDir();
 	const natives = nativeWorktree();
 
 	const resolution = natives.isoResolve(preferred ?? null);
@@ -410,7 +416,7 @@ export async function ensureIsolation(
 	let fallbackReason = resolution.reason ?? null;
 
 	for (const candidate of candidates) {
-		await fs.rm(baseDir, { recursive: true, force: true });
+		await removeIsolationDirectory(mergedDir, worktreeRoot);
 		try {
 			await natives.isoStart(candidate, repoRoot, mergedDir);
 			return {
@@ -420,7 +426,7 @@ export async function ensureIsolation(
 				fallbackReason,
 			};
 		} catch (err) {
-			await fs.rm(baseDir, { recursive: true, force: true });
+			await removeIsolationDirectory(mergedDir, worktreeRoot);
 			const message = errorMessage(err);
 			if (!natives.isoIsUnavailableError(message)) {
 				throw err;
@@ -434,6 +440,11 @@ export async function ensureIsolation(
 
 /** Tear down a handle returned by {@link ensureIsolation}. */
 export async function cleanupIsolation(handle: IsolationHandle): Promise<void> {
+	const worktreeRoot = getWorktreesDir();
+	// Native isoStop removes `mergedDir` and follows symlinks. Refuse a
+	// symlink that is already present before that call.
+	const teardown = await assertIsolationTeardownTarget(handle.mergedDir, worktreeRoot);
+	if (teardown === "skip") return;
 	const natives = nativeWorktree();
 	try {
 		try {
@@ -446,9 +457,7 @@ export async function cleanupIsolation(handle: IsolationHandle): Promise<void> {
 			});
 		}
 	} finally {
-		// baseDir is the parent of the merged directory
-		const baseDir = path.dirname(handle.mergedDir);
-		await fs.rm(baseDir, { recursive: true, force: true });
+		await removeIsolationDirectory(handle.mergedDir, worktreeRoot);
 	}
 }
 

package/src/tools/ask.ts

@@ -15,6 +15,7 @@
  *   - Questions may time out and auto-select the recommended option (configurable, disabled in plan mode)
  */
 
+import { randomUUID } from "node:crypto";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@gajae-code/agent-core";
 import type { RawArgumentValidationResult } from "@gajae-code/ai/types";
 import { validateToolArguments } from "@gajae-code/ai/utils/validation";
@@ -36,12 +37,25 @@ import {
 } from "../deep-interview/render-middleware";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { appendOrMergeDeepInterviewRound, syncDeepInterviewRecorderHud } from "../gjc-runtime/deep-interview-recorder";
-import { deepInterviewStatePath } from "../gjc-runtime/deep-interview-runtime";
+import {
+	assertDeepInterviewCrystalCoversLiveTranscript,
+	authoritativeConversationSnapshot,
+	deepInterviewStatePath,
+} from "../gjc-runtime/deep-interview-runtime";
 import {
 	assertDeepInterviewInputWithinLimit,
 	assertDeepInterviewStructuredResponseWithinLimit,
 	MAX_USER_RESPONSE_LENGTH,
 } from "../gjc-runtime/deep-interview-state";
+import type { ExecutionApprovalPresentation } from "../gjc-runtime/state-runtime";
+import {
+	captureExecutionApprovalPresentation,
+	executionApprovalLineage,
+	recordDeepInterviewExecutionApproval,
+	recordNonCrystalExecutionApproval,
+	revokeDeepInterviewExecutionApproval,
+	revokeNonCrystalExecutionApproval,
+} from "../gjc-runtime/state-runtime";
 import {
 	type AskGateQuestion,
 	gateAnswerToResult,
@@ -75,7 +89,7 @@ import {
 export { askSchema } from "./ask-contract";
 
 import { formatErrorMessage, formatMeta, formatTitle } from "./render-utils";
-import { ToolAbortError } from "./tool-errors";
+import { ToolAbortError, ToolError } from "./tool-errors";
 import { assertUltragoalAskAllowed } from "./ultragoal-ask-guard";
 
 // =============================================================================
@@ -158,6 +172,23 @@ function nonEmptyCustomInput(value: string | undefined): string | undefined {
 	return value !== undefined && value.trim().length > 0 ? value : undefined;
 }
 
+function deepInterviewExecutionTarget(selectedOptions: readonly string[]): "ultragoal" | undefined {
+	if (selectedOptions.length !== 1) return undefined;
+	const normalized = selectedOptions[0]
+		?.trim()
+		.replace(/\s*\(Recommended\)\s*$/i, "")
+		.toLowerCase();
+	return normalized === "approve execution via ultragoal" ||
+		/^execute with ultragoal(?: \(only when spec is already implementation-ready and really simple\))?$/.test(
+			normalized ?? "",
+		) ||
+		normalized === "ultragoal" ||
+		normalized === "/skill:ultragoal" ||
+		normalized === "gjc ultragoal"
+		? "ultragoal"
+		: undefined;
+}
+
 function isAskTimeoutError(error: unknown): boolean {
 	return typeof error === "object" && error !== null && (error as { code?: unknown }).code === GJC_ASK_TIMEOUT_CODE;
 }
@@ -320,6 +351,8 @@ interface SelectionResult {
 	selectedOptions: string[];
 	customInput?: string;
 	clarificationQuestion?: string;
+	executionGateId?: string;
+	executionPresentation?: ExecutionApprovalPresentation;
 	timedOut: boolean;
 	navigation?: "back" | "forward";
 	cancelled?: boolean;
@@ -340,6 +373,7 @@ interface AskSingleQuestionOptions {
 	otherOptionLabel?: string;
 	clarificationOptionLabel?: string;
 	autoSelectOnTimeout?: boolean;
+	executionPresentation?: ExecutionApprovalPresentation;
 	onRemoteState?: (state: {
 		interaction: "selector" | "custom_editor" | "clarification_editor";
 		selectedCount: number;
@@ -849,6 +883,65 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 		);
 	}
 
+	/**
+	 * The Deep Interview execution choice is the only ask answer that can mint
+	 * execution authority.  The runtime records only the redacted answer hash;
+	 * the subsequent CLI action must consume that record before it can approve
+	 * the canonical Crystal.
+	 */
+	async #recordDeepInterviewExecutionApproval(
+		q: AskParams["questions"][number],
+		selectedOptions: string[],
+		customInput: string | undefined,
+		toolCallId: string,
+		executionGateId?: string,
+		executionPresentation?: ExecutionApprovalPresentation,
+	): Promise<void> {
+		const deepInterviewExecution = q.workflowGate?.stage === "deep-interview" && q.workflowGate.kind === "execution";
+		const ralplanApproval = q.workflowGate?.stage === "ralplan" && q.workflowGate.kind === "approval";
+		if (!deepInterviewExecution && !ralplanApproval) return;
+		const target = deepInterviewExecutionTarget(selectedOptions);
+		const sessionId = this.session.getSessionId?.();
+		if (!target || customInput !== undefined) {
+			if (sessionId) {
+				await revokeDeepInterviewExecutionApproval(this.session.cwd, sessionId);
+				await revokeNonCrystalExecutionApproval(
+					this.session.cwd,
+					sessionId,
+					ralplanApproval ? "ralplan" : "deep-interview",
+				);
+			}
+			return;
+		}
+		if (!sessionId) throw new ToolAbortError("Deep Interview execution approval requires a session");
+		if (!executionPresentation)
+			throw new ToolAbortError("Execution approval publication could not be authenticated before consent");
+		const approvalStage = ralplanApproval ? "ralplan" : "deep-interview";
+		const lineage = await executionApprovalLineage(this.session.cwd, sessionId, approvalStage);
+		const transcriptEvidence =
+			lineage === "crystal"
+				? await assertDeepInterviewCrystalCoversLiveTranscript(this.session.cwd, sessionId, deepInterviewExecution)
+				: await authoritativeConversationSnapshot(this.session.cwd, sessionId);
+		const recordApproval =
+			lineage === "crystal" ? recordDeepInterviewExecutionApproval : recordNonCrystalExecutionApproval;
+		await recordApproval({
+			cwd: this.session.cwd,
+			sessionId,
+			questionId: q.id,
+			gateId: executionGateId ?? q.id,
+			toolCallId,
+			target,
+			selectedOptions,
+			transcriptPath: transcriptEvidence.transcriptPath,
+			transcriptSha256: transcriptEvidence.transcriptSha256,
+			approvalStage,
+			presentation: executionPresentation,
+		});
+		// Ralplan approval is consumed by the subsequent handoff, after the agent
+		// persists this Ask tool result. Consuming here would validate the boundary
+		// before the matching provider toolResult exists in the transcript.
+	}
+
 	async execute(
 		_toolCallId: string,
 		params: AskParams,
@@ -1200,6 +1293,14 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 		// Send notification if waiting and not suppressed
 		this.#sendAskNotification();
 
+		if (
+			params.questions.filter(
+				question =>
+					(question.workflowGate?.stage === "deep-interview" && question.workflowGate.kind === "execution") ||
+					(question.workflowGate?.stage === "ralplan" && question.workflowGate.kind === "approval"),
+			).length > 1
+		)
+			throw new ToolError("Ask accepts at most one execution-authorizing workflow gate per invocation");
 		const askQuestion = async (
 			q: AskParams["questions"][number],
 			options?: {
@@ -1212,6 +1313,9 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 			const recommended = validRecommendedIndex(q.recommended, rawOptionLabels.length);
 			const questionIndex = params.questions.indexOf(q);
 			const emptyCustomAttempt = options?.emptyCustomAttempt ?? 0;
+			const isExecutionApprovalQuestion =
+				(q.workflowGate?.stage === "deep-interview" && q.workflowGate.kind === "execution") ||
+				(q.workflowGate?.stage === "ralplan" && q.workflowGate.kind === "approval");
 			// Route headless asks through the SDK workflow-gate emitter; a connected
 			// SDK responder supplies the durable answer instead of an interactive UI.
 			if (gateEmitter && canUseWorkflowGate) {
@@ -1226,19 +1330,79 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 					allowEmpty: q.multi === true && params.questions.length > 1,
 					navigationLabel: questionIndex === params.questions.length - 1 ? "Done" : "Next",
 				};
-				const answer = await awaitAskAnswer(() => gateEmitter.emitGate(questionToGate(gateQuestion)));
+				let executionGateId: string | undefined = isExecutionApprovalQuestion
+					? `interactive-${randomUUID()}`
+					: undefined;
+				let executionPresentation: ExecutionApprovalPresentation | undefined;
+				if (isExecutionApprovalQuestion) {
+					const sessionId = this.session.getSessionId?.();
+					if (!sessionId) throw new ToolAbortError("Execution approval requires a session");
+					try {
+						executionPresentation = await captureExecutionApprovalPresentation(
+							this.session.cwd,
+							sessionId,
+							q.workflowGate?.stage === "ralplan" ? "ralplan" : "deep-interview",
+						);
+					} catch (error) {
+						throw new ToolAbortError(
+							error instanceof Error
+								? `Execution approval publication could not be authenticated: ${error.message}`
+								: "Execution approval publication could not be authenticated",
+						);
+					}
+				}
+				const stopGateObservation = gateEmitter.onGateEmitted?.(gate => {
+					const stageState = gate.context?.stage_state;
+					if (
+						gate.stage === q.workflowGate?.stage &&
+						gate.kind === q.workflowGate?.kind &&
+						((gate.stage === "deep-interview" && gate.kind === "execution") ||
+							(gate.stage === "ralplan" && gate.kind === "approval")) &&
+						stageState?.question_id === q.id
+					)
+						executionGateId = gate.gate_id;
+				});
+				let answer: unknown;
+				try {
+					answer = await gateEmitter.emitGate(questionToGate(gateQuestion));
+				} finally {
+					stopGateObservation?.();
+				}
 				const decoded = gateAnswerToResult(gateQuestion, answer);
 				return {
 					optionLabels: rawOptionLabels,
 					selectedOptions: decoded.selectedOptions,
 					customInput: decoded.customInput,
 					clarificationQuestion: decoded.clarificationQuestion,
+					executionGateId,
+					executionPresentation,
 					navigation: undefined as NavigationControls | undefined,
 					cancelled: false,
 					timedOut: false,
 				};
 			}
 			try {
+				let executionPresentation: ExecutionApprovalPresentation | undefined;
+				if (isExecutionApprovalQuestion) {
+					const sessionId = this.session.getSessionId?.();
+					if (!sessionId) throw new ToolAbortError("Execution approval requires a session");
+					try {
+						executionPresentation = await captureExecutionApprovalPresentation(
+							this.session.cwd,
+							sessionId,
+							q.workflowGate?.stage === "ralplan" ? "ralplan" : "deep-interview",
+						);
+					} catch (error) {
+						throw new ToolAbortError(
+							error instanceof Error
+								? `Execution approval publication could not be authenticated: ${error.message}`
+								: "Execution approval publication could not be authenticated",
+						);
+					}
+				}
+				const executionGateId: string | undefined = isExecutionApprovalQuestion
+					? `interactive-${randomUUID()}`
+					: undefined;
 				const deepInterviewPrompt = formatDeepInterviewSelectorPrompt(q.question);
 				const isDeepInterviewQuestion = deepInterviewPrompt !== null || q.deepInterview !== undefined;
 				const baseDisplayQuestion = deepInterviewPrompt ?? q.question;
@@ -1307,6 +1471,7 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 						!intentReview(q.deepInterview) &&
 						(q.workflowGate === undefined || q.workflowGate.kind === "question"),
 					clarificationOptionLabel,
+					executionPresentation,
 					onRemoteState: state => {
 						activeRemoteRequest = {
 							question: displayQuestion,
@@ -1395,6 +1560,8 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 					selectedOptions,
 					customInput,
 					clarificationQuestion,
+					executionGateId,
+					executionPresentation,
 					navigation,
 					cancelled,
 					timedOut,
@@ -1418,8 +1585,16 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 
 		if (params.questions.length === 1) {
 			const [q] = params.questions;
-			const { optionLabels, selectedOptions, customInput, clarificationQuestion, cancelled, timedOut } =
-				await askQuestion(q);
+			const {
+				optionLabels,
+				selectedOptions,
+				customInput,
+				clarificationQuestion,
+				executionGateId,
+				executionPresentation,
+				cancelled,
+				timedOut,
+			} = await askQuestion(q);
 
 			if (
 				!timedOut &&
@@ -1435,6 +1610,14 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 			) {
 				await this.#recordDeepInterviewRound(q, selectedOptions, customInput);
 			}
+			await this.#recordDeepInterviewExecutionApproval(
+				q,
+				selectedOptions,
+				customInput,
+				_toolCallId,
+				executionGateId,
+				executionPresentation,
+			);
 			const details: AskToolDetails = {
 				question: q.question,
 				options: optionLabels,
@@ -1476,6 +1659,10 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 		}
 
 		const resultsByIndex: Array<QuestionResult | undefined> = Array.from({ length: params.questions.length });
+		const executionGateIdsByIndex: Array<string | undefined> = Array.from({ length: params.questions.length });
+		const executionPresentationsByIndex: Array<ExecutionApprovalPresentation | undefined> = Array.from({
+			length: params.questions.length,
+		});
 		let questionIndex = 0;
 		while (questionIndex < params.questions.length) {
 			const q = params.questions[questionIndex]!;
@@ -1490,6 +1677,8 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 				selectedOptions,
 				customInput,
 				clarificationQuestion,
+				executionGateId,
+				executionPresentation,
 				navigation: navAction,
 				cancelled,
 				timedOut,
@@ -1509,6 +1698,8 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 				customInput,
 				clarificationQuestion,
 			};
+			executionGateIdsByIndex[questionIndex] = executionGateId;
+			executionPresentationsByIndex[questionIndex] = executionPresentation;
 
 			if (
 				clarificationQuestion === undefined &&
@@ -1521,7 +1712,6 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 				questionIndex = Math.max(0, questionIndex - 1);
 				continue;
 			}
-
 			questionIndex += 1;
 		}
 
@@ -1538,6 +1728,15 @@ export class AskTool implements AgentTool<AskParametersSchema, AskToolDetails> {
 		});
 
 		const details: AskToolDetails = { results };
+		for (const [index, result] of results.entries())
+			await this.#recordDeepInterviewExecutionApproval(
+				params.questions[index]!,
+				result.selectedOptions,
+				result.customInput,
+				_toolCallId,
+				executionGateIdsByIndex[index],
+				executionPresentationsByIndex[index],
+			);
 		const responseLines = results.map(formatQuestionResult);
 		const responseText = `User answers:\n${responseLines.join("\n")}`;
 

package/src/tools/ast-edit-write-path.ts

@@ -0,0 +1,68 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const MAX_ANCESTOR_WALK = 64;
+
+function isInside(root: string, target: string): boolean {
+	const relative = path.relative(root, target);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+/**
+ * Path the native writer will mutate: realpath of an existing file, or realpath
+ * of the nearest existing ancestor plus the missing tail.
+ */
+export async function canonicalizeAstEditWritePath(absolutePath: string): Promise<string> {
+	const suffix: string[] = [];
+	let current = path.resolve(absolutePath);
+	for (let depth = 0; depth < MAX_ANCESTOR_WALK; depth++) {
+		try {
+			const real = await fs.realpath(current);
+			return suffix.length === 0 ? real : path.join(real, ...suffix.toReversed());
+		} catch {
+			const parent = path.dirname(current);
+			if (parent === current) break;
+			suffix.push(path.basename(current));
+			current = parent;
+		}
+	}
+	return path.resolve(absolutePath);
+}
+
+/**
+ * Preview paths as the workflow guard must see them.
+ *
+ * The guard compares lexically against the session cwd. A raw realpath misses
+ * `.gjc/**` when that cwd is not already canonical (`/var` vs `/private/var`,
+ * or a symlinked workspace), so an in-workspace real path is reattached to `cwd`.
+ */
+export async function resolveAstEditPreviewWritePaths(
+	cwd: string,
+	previewedPaths: readonly string[],
+): Promise<string[]> {
+	const resolvedCwd = path.resolve(cwd);
+	let realCwd = resolvedCwd;
+	try {
+		realCwd = await fs.realpath(resolvedCwd);
+	} catch {
+		// Missing cwd has no canonical spelling; keep the lexical root.
+	}
+	const resolved: string[] = [];
+	for (const previewed of previewedPaths) {
+		const lexical = path.resolve(resolvedCwd, previewed);
+		const real = await canonicalizeAstEditWritePath(lexical);
+		const relative = path.relative(realCwd, real);
+		const canonical =
+			isInside(realCwd, real) && relative !== ""
+				? path.resolve(resolvedCwd, relative)
+				: isInside(realCwd, real)
+					? resolvedCwd
+					: real;
+		// The guard matches `.gjc` lexically. Keep the preview spelling so a
+		// symlinked `.gjc` directory is still recognized, and add the canonical
+		// spelling so `src` → `.gjc` is recognized too.
+		resolved.push(previewed);
+		if (path.resolve(canonical) !== lexical) resolved.push(canonical);
+	}
+	return resolved;
+}

package/src/tools/ast-edit.ts

@@ -13,10 +13,13 @@ import { assertWorkflowMutationRawPathsAllowed } from "../skill-state/workflow-m
 import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
+import { resolveAstEditPreviewWritePaths } from "./ast-edit-write-path";
+import { assertEditableFile } from "./auto-generated-guard";
 import { createFileRecorder, formatResultPath } from "./file-recorder";
 import { formatGroupedFiles } from "./grouped-file-output";
 import type { OutputMeta } from "./output-meta";
 import { resolveToolSearchScope } from "./path-utils";
+import { enforcePlanModeWrite, resolvePlanPath } from "./plan-mode-guard";
 import {
 	appendParseErrorsBulletList,
 	capParseErrors,
@@ -337,11 +340,17 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 					label: `AST Edit: ${result.totalReplacements} replacement${previewReplacementPlural} in ${result.filesTouched} file${previewFilePlural}`,
 					sourceToolName: this.name,
 					apply: async (_reason: string) => {
+						for (const filePath of previewedFiles) {
+							enforcePlanModeWrite(this.session, filePath, { op: "update" });
+						}
 						await assertWorkflowMutationRawPathsAllowed({
 							cwd: this.session.cwd,
 							sessionId: this.session.getSessionId?.() ?? undefined,
-							rawPaths: previewedFiles,
+							rawPaths: await resolveAstEditPreviewWritePaths(this.session.cwd, previewedFiles),
 						});
+						for (const filePath of previewedFiles) {
+							await assertEditableFile(resolvePlanPath(this.session, filePath), filePath, this.session.settings);
+						}
 						const applyResult = await runAstEditOnce(multiTargets, resolvedSearchPath, globFilter, {
 							rewrites: normalizedRewrites,
 							dryRun: false,