@gajae-code/coding-agent 0.6.1 → 0.6.4

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;

package/src/slash-commands/builtin-registry.ts

@@ -250,11 +250,15 @@ const BUILTIN_SLASH_COMMAND_REGISTRY: ReadonlyArray<SlashCommandSpec> = [
 		inlineHint: "[objective]",
 		allowArgs: true,
 		handleTui: async (command, runtime) => {
-			const hadArgs = !!command.args;
-			// Capture state BEFORE the call (see /plan above for rationale).
-			const wasGoalModeEnabled = runtime.ctx.goalModeEnabled;
+			// The goal command always consumes the typed input: it either submits
+			// the bare objective (never the literal `/goal …` text the user typed)
+			// or shows a warning, so the normal submission path never records it in
+			// input history. Preserve the typed command whenever args were supplied
+			// — including the first-time `/goal set <objective>` case where goal
+			// mode was not yet active. A previous `wasGoalModeEnabled` guard dropped
+			// that first-time case from history (up/down-arrow recall).
 			await runtime.ctx.handleGoalModeCommand(command.args || undefined);
-			if (hadArgs && wasGoalModeEnabled) {
+			if (command.args) {
 				runtime.ctx.editor.addToHistory(command.text);
 			}
 			runtime.ctx.editor.setText("");

package/src/system-prompt.ts

@@ -253,15 +253,17 @@ export async function loadProjectContextFiles(
 
 	const result = await loadCapability(contextFileCapability.id, { cwd: resolvedCwd });
 
-	// Convert ContextFile items and preserve depth info
-	const files = result.items.map(item => {
-		const contextFile = item as ContextFile;
-		return {
-			path: contextFile.path,
-			content: contextFile.content,
-			depth: contextFile.depth,
-		};
-	});
+	// Convert project-level ContextFile items and preserve depth info
+	const files = result.items
+		.filter(item => (item as ContextFile).level === "project")
+		.map(item => {
+			const contextFile = item as ContextFile;
+			return {
+				path: contextFile.path,
+				content: contextFile.content,
+				depth: contextFile.depth,
+			};
+		});
 
 	// Sort by depth (descending): higher depth (farther from cwd) comes first,
 	// so files closer to cwd appear later and are more prominent

package/src/tools/ast-edit.ts

@@ -9,7 +9,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { computeLineHash, HL_BODY_SEP } from "../hashline/hash";
 import type { Theme } from "../modes/theme/theme";
 import astEditDescription from "../prompts/tools/ast-edit.md" with { type: "text" };
-import { assertDeepInterviewMutationRawPathsAllowed } from "../skill-state/deep-interview-mutation-guard";
+import { assertWorkflowMutationRawPathsAllowed } from "../skill-state/deep-interview-mutation-guard";
 import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
@@ -329,7 +329,7 @@ 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) => {
-						await assertDeepInterviewMutationRawPathsAllowed({
+						await assertWorkflowMutationRawPathsAllowed({
 							cwd: this.session.cwd,
 							sessionId: this.session.getSessionId?.() ?? undefined,
 							rawPaths: previewedFiles,

package/src/utils/edit-mode.ts

@@ -1,4 +1,4 @@
-import { $env } from "../../../utils/src/env";
+import { $env } from "@gajae-code/utils/env";
 
 export type EditMode = "replace" | "patch" | "hashline" | "vim" | "apply_patch";