@gajae-code/coding-agent 0.2.5 → 0.3.0

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

@@ -1,5 +1,10 @@
-import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import {
+	type ActiveSessionScope,
+	rebuildActiveSnapshot,
+	removeActiveEntry,
+	writeActiveEntry,
+} from "../gjc-runtime/state-writer";
 import type { WorkflowStateReceipt } from "./workflow-state-contract";
 
 export const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
@@ -56,6 +61,8 @@ export interface SkillActiveState {
 	session_id?: string;
 	thread_id?: string;
 	turn_id?: string;
+	initialized_mode?: CanonicalGjcWorkflowSkill;
+	initialized_state_path?: string;
 	active_skills?: SkillActiveEntry[];
 	[key: string]: unknown;
 }
@@ -286,14 +293,6 @@ export function getSkillActiveStatePaths(cwd: string, sessionId?: string): Skill
 	};
 }
 
-async function readStateFile(filePath: string): Promise<SkillActiveState | null> {
-	try {
-		return normalizeSkillActiveState(JSON.parse(await Bun.file(filePath).text()));
-	} catch {
-		return null;
-	}
-}
-
 /**
  * Raw read for handoff mutations. Returns the *unnormalized* parsed object so
  * inactive entries remain visible to `rawActiveEntries` — `normalizeSkillActiveState`
@@ -516,15 +515,41 @@ export async function readVisibleSkillActiveState(cwd: string, sessionId?: strin
 	};
 }
 
-async function writeStateFile(filePath: string, state: SkillActiveState): Promise<void> {
-	await fs.mkdir(path.dirname(filePath), { recursive: true });
-	await Bun.write(filePath, `${JSON.stringify(state, null, 2)}\n`);
+function activeStateWriterAudit(verb: string) {
+	return { category: "state" as const, verb, owner: "gjc-runtime" as const };
+}
+
+async function persistActiveEntry(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	if (entry.active === false) {
+		await removeActiveEntry(cwd, sessionScope, entry.skill, {
+			cwd,
+			audit: activeStateWriterAudit("remove-active-entry"),
+		});
+	} else {
+		await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
+			cwd,
+			audit: activeStateWriterAudit("write-active-entry"),
+		});
+	}
 }
 
-function upsertEntry(entries: SkillActiveEntry[], entry: SkillActiveEntry, active: boolean): SkillActiveEntry[] {
-	const key = entryKey(entry);
-	const retained = entries.filter(candidate => entryKey(candidate) !== key);
-	return active ? [...retained, entry] : retained;
+async function writeHandoffEntry(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	await writeActiveEntry(cwd, sessionScope, entry.skill, entry, {
+		cwd,
+		audit: activeStateWriterAudit("write-active-entry"),
+	});
+}
+
+async function rebuildActiveState(cwd: string, sessionScope?: ActiveSessionScope): Promise<void> {
+	await rebuildActiveSnapshot(cwd, sessionScope, { cwd, audit: activeStateWriterAudit("rebuild-active-snapshot") });
 }
 
 export async function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void> {
@@ -545,36 +570,13 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 		...(hud ? { hud } : {}),
 		...(options.receipt ? { receipt: options.receipt } : {}),
 	};
-	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, options.sessionId);
-	const rootState = (await readStateFile(rootPath)) ?? { version: 1, active_skills: [] };
-	const rootEntries = upsertEntry(listActiveSkills(rootState), entry, options.active);
-	const nextRoot: SkillActiveState = {
-		...rootState,
-		version: 1,
-		active: rootEntries.length > 0,
-		skill: rootEntries[0]?.skill ?? "",
-		phase: rootEntries[0]?.phase ?? "",
-		updated_at: nowIso,
-		source: options.source,
-		active_skills: rootEntries,
-	};
-	await writeStateFile(rootPath, nextRoot);
+	await persistActiveEntry(options.cwd, undefined, entry);
+	await rebuildActiveState(options.cwd);
 
-	if (!sessionPath) return;
-	const sessionState = (await readStateFile(sessionPath)) ?? { version: 1, active_skills: [] };
-	const sessionEntries = upsertEntry(listActiveSkills(sessionState), entry, options.active);
-	const nextSession: SkillActiveState = {
-		...sessionState,
-		version: 1,
-		active: sessionEntries.length > 0,
-		skill: sessionEntries[0]?.skill ?? "",
-		phase: sessionEntries[0]?.phase ?? "",
-		session_id: options.sessionId,
-		updated_at: nowIso,
-		source: options.source,
-		active_skills: sessionEntries,
-	};
-	await writeStateFile(sessionPath, nextSession);
+	if (!options.sessionId) return;
+	const sessionScope = { sessionId: options.sessionId };
+	await persistActiveEntry(options.cwd, sessionScope, entry);
+	await rebuildActiveState(options.cwd, sessionScope);
 }
 
 export interface ApplyHandoffOptions {
@@ -604,6 +606,7 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 	const sessionId = options.callee.sessionId ?? options.caller.sessionId;
 	const { rootPath, sessionPath } = getSkillActiveStatePaths(options.cwd, sessionId);
 	const readState = (filePath: string) => readRawActiveStateForHandoff(filePath, options.strict === true);
+	await Promise.all([readState(rootPath), ...(sessionPath ? [readState(sessionPath)] : [])]);
 
 	// A skill can hold more than one visible row in this session's scope — e.g.
 	// it was seeded without a session id (rendered globally) and is now handed
@@ -637,33 +640,23 @@ export async function applyHandoffToActiveState(options: ApplyHandoffOptions): P
 			: callerEntry;
 		return [...kept, mergedCaller, calleeEntry];
 	};
-	const buildNextState = (
+	const writeEntries = async (
+		sessionScope: ActiveSessionScope | undefined,
 		prior: SkillActiveState | null,
-		entries: SkillActiveEntry[],
-		scope: "session" | "root",
-	): SkillActiveState => {
-		const visible = entries.filter(e => e.active !== false);
-		return {
-			...(prior ?? {}),
-			version: 1,
-			active: visible.length > 0,
-			skill: visible[0]?.skill ?? "",
-			phase: visible[0]?.phase ?? "",
-			...(scope === "session" ? { session_id: sessionId } : {}),
-			updated_at: nowIso,
-			source: options.callee.source ?? options.caller.source,
-			active_skills: entries,
-		};
+	): Promise<void> => {
+		const nextEntries = applyEntries(rawActiveEntries(prior));
+		for (const entry of nextEntries) {
+			await writeHandoffEntry(options.cwd, sessionScope, entry);
+		}
+		await rebuildActiveState(options.cwd, sessionScope);
 	};
 
 	if (sessionPath) {
 		const prior = await readState(sessionPath);
-		const next = buildNextState(prior, applyEntries(rawActiveEntries(prior)), "session");
-		await writeStateFile(sessionPath, next);
+		await writeEntries({ sessionId }, prior);
 	}
 	const priorRoot = await readState(rootPath);
-	const nextRoot = buildNextState(priorRoot, applyEntries(rawActiveEntries(priorRoot)), "root");
-	await writeStateFile(rootPath, nextRoot);
+	await writeEntries(undefined, priorRoot);
 }
 
 function buildSyncEntry(options: SyncSkillActiveStateOptions, nowIso: string): SkillActiveEntry {

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

@@ -14,12 +14,16 @@ import {
 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 =
-	"Workflow state JSON is runtime-owned. Use `gjc state <skill> read|write --input '<json>'` for deep-interview, ralplan, ultragoal, and team. Planning artifacts under `.gjc/specs/` and `.gjc/plans/` remain allowed.";
+	".gjc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.gjc/**`; use the sanctioned `gjc` CLI instead.";
 
-const BLOCKED_TOOL_NAMES = new Set(["edit", "write", "ast_edit"]);
+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;
 const INTERNAL_SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 const VIM_FILE_SWITCH_RE = /^\s*:(?:e|e!|edit|edit!)(?:\s+([^<\r\n]+))?(?:<CR>|\r|\n|$)/i;
+const BASH_TOKEN_RE = /'[^']*'|"(?:\\.|[^"\\])*"|\S+/g;
+const BASH_REDIRECT_RE = /^(?:\d*)>>?$/;
+const BASH_HEREDOC_RE = /^(?:\d*)<<-?$/;
+const BASH_MUTATION_COMMANDS = new Set(["rm", "mv", "cp", "touch", "mkdir", "ln", "tee"]);
 
 type ToolWithEditMode = AgentTool & {
 	mode?: unknown;
@@ -219,10 +223,75 @@ function extractEditTargets(args: unknown, tool: ToolWithEditMode): ExtractedTar
 	return targets;
 }
 
+function extractBashTargets(args: unknown): ExtractedTargets {
+	const record = getRecord(args);
+	const command = safeString(record?.command).trim();
+	const targets: ExtractedTargets = { paths: [], unknown: false };
+	if (!command) {
+		targets.unknown = true;
+		return targets;
+	}
+	if (/^gjc(?:\s|$)/.test(command)) return targets;
+
+	const tokens = command.match(BASH_TOKEN_RE)?.map(unquoteBashToken) ?? [];
+	for (let index = 0; index < tokens.length; index++) {
+		const token = tokens[index] ?? "";
+		if (BASH_REDIRECT_RE.test(token)) {
+			addPath(targets, tokens[index + 1]);
+			index++;
+			continue;
+		}
+		const redirectMatch = token.match(/^(?:\d*)>>?(.+)$/);
+		if (redirectMatch?.[1]) {
+			addPath(targets, redirectMatch[1]);
+			continue;
+		}
+		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]);
+			continue;
+		}
+		if (isMutationBashCommand(tokens, index)) {
+			for (let targetIndex = index + 1; targetIndex < tokens.length; targetIndex++) {
+				const target = tokens[targetIndex] ?? "";
+				if (isBashCommandBoundary(target)) break;
+				if (target.startsWith("-")) continue;
+				addPath(targets, target);
+			}
+		}
+	}
+	return targets;
+}
+
+function unquoteBashToken(token: string): string {
+	if (token.length < 2) return token;
+	const quote = token[0];
+	if ((quote === "'" || quote === '"') && token.at(-1) === quote) return token.slice(1, -1);
+	return token;
+}
+
+function isBashCommandBoundary(token: string): boolean {
+	return [";", "&&", "||", "|"].includes(token);
+}
+
+function isMutationBashCommand(tokens: string[], index: number): boolean {
+	const token = path.basename(tokens[index] ?? "");
+	if (BASH_MUTATION_COMMANDS.has(token)) return true;
+	if (token !== "sed") return false;
+	const next = tokens[index + 1] ?? "";
+	return next === "-i" || next.startsWith("-i") || next.includes("i");
+}
+
 function extractTargets(tool: ToolWithEditMode, args: unknown): ExtractedTargets {
 	if (tool.name === "write") return extractWriteTargets(args);
 	if (tool.name === "ast_edit") return extractAstEditTargets(args);
 	if (tool.name === "edit") return extractEditTargets(args, tool);
+	if (tool.name === "bash") return extractBashTargets(args);
 	return { paths: [], unknown: true };
 }
 
@@ -289,6 +358,14 @@ function isAllowlistedPath(cwd: string, rawPath: string): boolean {
 	if (segments?.[0] !== ".gjc") return false;
 	return segments[1] === "specs" || segments[1] === "plans";
 }
+function isBlockedGjcPath(cwd: string, rawPath: string): boolean {
+	const segments = relativeGjcSegments(cwd, rawPath);
+	return segments?.[0] === ".gjc";
+}
+
+function hasBlockedGjcTarget(cwd: string, targets: ExtractedTargets): boolean {
+	return targets.paths.some(rawPath => isBlockedGjcPath(cwd, rawPath));
+}
 
 function allTargetsAllowlisted(cwd: string, targets: ExtractedTargets): boolean {
 	return (
@@ -315,18 +392,16 @@ export async function getDeepInterviewMutationDecision(
 ): Promise<DeepInterviewMutationDecision> {
 	if (!BLOCKED_TOOL_NAMES.has(input.tool.name)) return { blocked: false, targets: [] };
 	const targets = extractTargets(input.tool, input.args);
-	if (input.enforceWorkflowState !== false) {
+	if (input.enforceWorkflowState !== false && hasBlockedGjcTarget(input.cwd, targets)) {
 		const stateSkill = firstBlockedWorkflowStateSkill(input.cwd, targets);
-		if (stateSkill) {
-			const command = sanctionedWorkflowStateCommand(stateSkill);
-			return {
-				blocked: true,
-				message: `${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`,
-				targets: targets.paths,
-				reason: "workflow-state-target",
-				command,
-			};
-		}
+		const command = stateSkill ? sanctionedWorkflowStateCommand(stateSkill) : "gjc <workflow-command>";
+		return {
+			blocked: true,
+			message: `${WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE}\nUse: ${command}`,
+			targets: targets.paths,
+			reason: stateSkill ? "workflow-state-target" : "gjc-target",
+			command,
+		};
 	}
 	if (!(await isActiveDeepInterview(input.cwd, input.sessionId, input.threadId))) {
 		return { blocked: false, targets: [] };
@@ -340,6 +415,9 @@ export async function getDeepInterviewMutationDecision(
 			reason: "unknown-target",
 		};
 	}
+	if (input.tool.name === "bash") {
+		return { blocked: false, targets: targets.paths };
+	}
 	return {
 		blocked: true,
 		message: DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE,

package/src/skill-state/initial-phase.ts

@@ -13,5 +13,7 @@ import type { CanonicalGjcWorkflowSkill } from "./active-state";
 export function initialPhaseForSkill(skill: CanonicalGjcWorkflowSkill | string): string {
 	if (skill === "deep-interview") return "interviewing";
 	if (skill === "ultragoal") return "goal-planning";
+	if (skill === "ralplan") return "planner";
+	if (skill === "team") return "starting";
 	return "planning";
 }

package/src/skill-state/workflow-state-contract.ts

@@ -9,6 +9,13 @@ export const WORKFLOW_STATE_RECEIPT_FRESH_MS = 30 * 60 * 1000;
 export type WorkflowStateMutationOwner = "gjc-state-cli" | "gjc-runtime" | "gjc-hook";
 export type WorkflowStateReceiptStatus = "fresh" | "stale";
 
+export interface WorkflowStateContentChecksum {
+	algorithm: "sha256";
+	value: string;
+	covered_path: string;
+	computed_at: string;
+}
+
 export interface WorkflowStateReceipt {
 	version: 1;
 	skill: CanonicalGjcWorkflowSkill;
@@ -20,6 +27,25 @@ export interface WorkflowStateReceipt {
 	fresh_until: string;
 	status: WorkflowStateReceiptStatus;
 	mutation_id: string;
+	verb?: string;
+	from_phase?: string;
+	to_phase?: string;
+	forced?: boolean;
+	paths?: string[];
+	content_sha256?: WorkflowStateContentChecksum;
+}
+
+export interface AuditEntry {
+	ts: string;
+	skill?: string;
+	category: string;
+	verb: string;
+	owner: WorkflowStateMutationOwner;
+	mutation_id: string;
+	from_phase?: string;
+	to_phase?: string;
+	forced: boolean;
+	paths: string[];
 }
 
 function safeString(value: unknown): string {

package/src/task/executor.ts

@@ -9,6 +9,7 @@ import type { AgentEvent, AgentIdentity, AgentTelemetryConfig, ThinkingLevel } f
 import { recordHandoff, resolveTelemetry } from "@gajae-code/agent-core";
 import { type JsonSchemaValidationIssue, validateJsonSchemaValue } from "@gajae-code/ai/utils/schema";
 import { logger, prompt, untilAborted } from "@gajae-code/utils";
+import { AsyncJobManager } from "../async";
 import { ModelRegistry } from "../config/model-registry";
 import { resolveModelOverrideWithAuthFallback } from "../config/model-resolver";
 import type { PromptTemplate } from "../config/prompt-templates";
@@ -112,6 +113,9 @@ export interface ExecutorOptions {
 	index: number;
 	id: string;
 	modelOverride?: string | string[];
+	runMode?: "initial" | "resume" | "message";
+	resumeMessage?: string;
+	subagentId?: string;
 	/**
 	 * Active model selector of the parent session, used as an auth-aware fallback
 	 * if the resolved subagent model has no working credentials. See #985.
@@ -550,8 +554,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	}
 
 	// Set up artifact paths and write input file upfront if artifacts dir provided
-	let subtaskSessionFile: string | undefined;
-	if (options.artifactsDir) {
+	let subtaskSessionFile: string | undefined = options.sessionFile ?? undefined;
+	if (!subtaskSessionFile && options.artifactsDir) {
 		subtaskSessionFile = path.join(options.artifactsDir, `${id}.jsonl`);
 	}
 
@@ -617,6 +621,8 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 	let activeSession: AgentSession | null = null;
 	let unsubscribe: (() => void) | null = null;
 	let yieldCalled = false;
+	let pauseRequested = false;
+	let paused = false;
 
 	// Accumulate usage incrementally from message_end events (no memory for streaming events)
 	const accumulatedUsage = {
@@ -1006,6 +1012,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 						}
 					}
 				}
+				paused = (event as { stopReason?: string }).stopReason === "paused";
 				flushProgress = true;
 				break;
 		}
@@ -1193,10 +1200,27 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					localProtocolOptions: options.localProtocolOptions,
 					telemetry: subagentTelemetry,
 					forkContextSeed: options.forkContextSeed,
+					shouldPause: () => pauseRequested,
 				}),
 			);
 
 			activeSession = session;
+			const liveSubagentId = options.subagentId ?? id;
+			const manager = AsyncJobManager.instance();
+			if (manager) {
+				manager.registerLiveHandle(liveSubagentId, {
+					requestPause: () => {
+						pauseRequested = true;
+					},
+					injectMessage: async (content, deliverAs) => {
+						if (deliverAs === "nextTurn") {
+							await session.prompt(content, { attribution: "agent" });
+							return;
+						}
+						await session.sendUserMessage(content, { deliverAs });
+					},
+				});
+			}
 
 			// Emit lifecycle start event
 			if (options.eventBus) {
@@ -1306,6 +1330,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					progress.retryState = {
 						attempt: event.attempt,
 						maxAttempts: event.maxAttempts,
+						unbounded: event.unbounded,
 						delayMs: event.delayMs,
 						errorMessage: event.errorMessage,
 						startedAtMs: Date.now(),
@@ -1354,13 +1379,24 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					);
 				}
 			}
-			await awaitAbortable(session.prompt(task, { attribution: "agent" }));
-			await awaitAbortable(session.waitForIdle());
+			const runMode = options.runMode ?? "initial";
+			if (runMode === "message") {
+				await awaitAbortable(session.prompt(options.resumeMessage ?? "", { attribution: "agent" }));
+				await awaitAbortable(session.waitForIdle());
+			} else if (runMode === "resume") {
+				await awaitAbortable(
+					session.prompt("Continue from the paused subagent session state.", { attribution: "agent" }),
+				);
+				await awaitAbortable(session.waitForIdle());
+			} else {
+				await awaitAbortable(session.prompt(task, { attribution: "agent" }));
+				await awaitAbortable(session.waitForIdle());
+			}
 
 			const reminderToolChoice = buildNamedToolChoice("yield", session.model);
 
 			let retryCount = 0;
-			while (!yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
+			while (!paused && !yieldCalled && retryCount < MAX_YIELD_RETRIES && !abortSignal.aborted) {
 				// Skip reminders when the model returned a terminal error (e.g.
 				// rate-limit cap hit, auth failure). Re-prompting would just
 				// hit the same wall, multiplying the failure noise without
@@ -1390,7 +1426,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			}
 
 			await awaitAbortable(session.waitForIdle());
-			if (!yieldCalled && !abortSignal.aborted) {
+			if (!paused && !yieldCalled && !abortSignal.aborted) {
 				exitCode = 0;
 			}
 
@@ -1406,6 +1442,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 					exitCode = 1;
 					error ??= lastAssistant.errorMessage || "Subagent failed";
 				}
+				if (paused) {
+					exitCode = 0;
+					error = undefined;
+				}
 			}
 		} catch (err) {
 			exitCode = 1;
@@ -1421,6 +1461,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				if (exitCode === 0) exitCode = 1;
 			}
 			sessionAbortController.abort();
+			AsyncJobManager.instance()?.removeLiveHandle(options.subagentId ?? id);
 			if (unsubscribe) {
 				try {
 					unsubscribe();
@@ -1527,7 +1568,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				? yieldAbortReason
 				: (done.abortReason ?? (signal?.aborted ? resolveSignalAbortReason() : resolveAbortReasonText()))
 		: undefined;
-	progress.status = wasAborted ? "aborted" : exitCode === 0 ? "completed" : "failed";
+	progress.status = paused ? "paused" : wasAborted ? "aborted" : exitCode === 0 ? "completed" : "failed";
 	scheduleProgress(true);
 
 	// Emit lifecycle end event after finalization so yield status is reflected
@@ -1537,7 +1578,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			agent: agent.name,
 			agentSource: agent.source,
 			description: options.description,
-			status: progress.status as "completed" | "failed" | "aborted",
+			status: progress.status as "completed" | "failed" | "aborted" | "paused",
 			sessionFile: subtaskSessionFile,
 			index,
 		});
@@ -1564,6 +1605,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		error: exitCode !== 0 && stderr ? stderr : undefined,
 		aborted: wasAborted,
 		abortReason: finalAbortReason,
+		paused,
 		usage: hasUsage ? accumulatedUsage : undefined,
 		outputPath,
 		extractedToolData: progress.extractedToolData,