@gajae-code/coding-agent 0.3.0 → 0.3.2

package/src/hooks/skill-state.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import type { SkillDiscoverySettings } from "../config/skill-settings-defaults";
-import { writeJsonAtomic } from "../gjc-runtime/state-writer";
+import { ModeStateSchema, SkillActiveStateSchema } from "../gjc-runtime/state-schema";
+import { writeJsonAtomic, writeWorkflowEnvelopeAtomic } from "../gjc-runtime/state-writer";
 import { isUltragoalBypassPrompt, readUltragoalVerificationState } from "../gjc-runtime/ultragoal-guard";
 import { buildSessionContext, loadEntriesFromFile, type SessionEntry } from "../session/session-manager";
 import {
@@ -8,6 +9,7 @@ import {
 	type SkillActiveEntry,
 	type SkillActiveState,
 } from "../skill-state/active-state";
+import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
 import {
 	compareSkillKeywordMatches,
 	GJC_SKILL_KEYWORD_DEFINITIONS,
@@ -218,14 +220,36 @@ function skillStatePath(stateDir: string, sessionId?: string): string {
 	return path.join(stateDir, SKILL_ACTIVE_STATE_FILE);
 }
 
-async function readJsonFile<T>(filePath: string): Promise<T | null> {
+function warnInvalidState(kind: string, filePath: string, error: string): void {
+	console.warn(`gjc skill-state: invalid ${kind} at ${filePath}: ${error}`);
+}
+
+async function readValidatedJsonFile<T>(
+	filePath: string,
+	kind: string,
+	schema: { safeParse: (value: unknown) => { success: true } | { success: false; error: { message: string } } },
+): Promise<T | null> {
+	let raw: string;
 	try {
-		const raw = await Bun.file(filePath).text();
-		return JSON.parse(raw) as T;
+		raw = await Bun.file(filePath).text();
 	} catch (error) {
 		if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return null;
+		warnInvalidState(kind, filePath, `read error: ${(error as Error).message}`);
 		return null;
 	}
+	let value: T;
+	try {
+		value = JSON.parse(raw) as T;
+	} catch (error) {
+		warnInvalidState(kind, filePath, `invalid JSON: ${(error as Error).message}`);
+		return null;
+	}
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) {
+		warnInvalidState(kind, filePath, parsed.error.message);
+		return null;
+	}
+	return value;
 }
 
 async function writeJsonFile(filePath: string, value: unknown, cwd: string): Promise<void> {
@@ -265,22 +289,41 @@ export async function readVisibleSkillActiveState(
 	if (!stateDir) return await readCanonicalVisibleSkillActiveState(cwd, sessionId);
 	const resolvedStateDir = resolveGjcStateDir(cwd, stateDir);
 	if (sessionId) {
-		const sessionState = await readJsonFile<SkillActiveState>(skillStatePath(resolvedStateDir, sessionId));
+		const sessionState = await readValidatedJsonFile<SkillActiveState>(
+			skillStatePath(resolvedStateDir, sessionId),
+			"skill-active-state",
+			SkillActiveStateSchema,
+		);
 		if (sessionState) return sessionState;
 	}
-	return await readJsonFile<SkillActiveState>(skillStatePath(resolvedStateDir));
+	return await readValidatedJsonFile<SkillActiveState>(
+		skillStatePath(resolvedStateDir),
+		"skill-active-state",
+		SkillActiveStateSchema,
+	);
 }
 
-export async function recordSkillActivation(input: RecordSkillActivationInput): Promise<SkillActiveState | null> {
-	const match = detectPrimarySkillKeyword(input.text);
-	if (!match) return null;
+interface SeedSkillActivationStateInput {
+	cwd: string;
+	sessionId?: string;
+	threadId?: string;
+	turnId?: string;
+	nowIso?: string;
+	stateDir?: string;
+}
 
+async function seedSkillActivationState(
+	skill: GjcWorkflowSkill,
+	keyword: string,
+	source: string,
+	input: SeedSkillActivationStateInput,
+): Promise<SkillActiveState> {
 	const resolvedStateDir = resolveGjcStateDir(input.cwd, input.stateDir);
 	const nowIso = input.nowIso ?? new Date().toISOString();
-	const phase = initialPhaseForSkill(match.skill);
-	const initializedStatePath = modeStatePath(resolvedStateDir, match.skill, input.sessionId);
+	const phase = initialPhaseForSkill(skill);
+	const initializedStatePath = modeStatePath(resolvedStateDir, skill, input.sessionId);
 	const entry: SkillActiveEntry = {
-		skill: match.skill,
+		skill,
 		phase,
 		active: true,
 		activated_at: nowIso,
@@ -292,41 +335,102 @@ export async function recordSkillActivation(input: RecordSkillActivationInput):
 	const state: SkillActiveState = {
 		version: 1,
 		active: true,
-		skill: match.skill,
-		keyword: match.keyword,
+		skill,
+		keyword,
 		phase,
 		activated_at: nowIso,
 		updated_at: nowIso,
-		source: "gjc-skill-state-hook",
+		source,
 		...(input.sessionId ? { session_id: input.sessionId } : {}),
 		...(input.threadId ? { thread_id: input.threadId } : {}),
 		...(input.turnId ? { turn_id: input.turnId } : {}),
-		initialized_mode: match.skill,
+		initialized_mode: skill,
 		initialized_state_path: initializedStatePath,
 		active_skills: [entry],
 	};
 	const modeState: ModeState = {
 		active: true,
+		version: WORKFLOW_STATE_VERSION,
 		current_phase: phase,
-		skill: match.skill,
+		skill,
 		cwd: input.cwd,
 		updated_at: nowIso,
 		...(input.sessionId ? { session_id: input.sessionId } : {}),
 		...(input.threadId ? { thread_id: input.threadId } : {}),
 		...(input.turnId ? { turn_id: input.turnId } : {}),
 	};
-	if (match.skill === "deep-interview") {
+	if (skill === "deep-interview") {
 		modeState.threshold = DEFAULT_DEEP_INTERVIEW_AMBIGUITY_THRESHOLD;
 		modeState.threshold_source = "default";
 	}
 
-	await writeJsonFile(initializedStatePath, modeState, input.cwd);
+	await writeWorkflowEnvelopeAtomic(initializedStatePath, modeState, {
+		cwd: input.cwd,
+		receipt: {
+			cwd: input.cwd,
+			skill,
+			owner: "gjc-hook",
+			command: source,
+			sessionId: input.sessionId,
+		},
+		audit: { category: "state", verb: "write", owner: "gjc-hook", skill },
+	});
 	await writeJsonFile(skillStatePath(resolvedStateDir, input.sessionId), state, input.cwd);
-	if (!input.sessionId) return state;
-	await writeJsonFile(skillStatePath(resolvedStateDir), state, input.cwd);
+	if (input.sessionId) {
+		await writeJsonFile(skillStatePath(resolvedStateDir), state, input.cwd);
+	}
 	return state;
 }
 
+export async function recordSkillActivation(input: RecordSkillActivationInput): Promise<SkillActiveState | null> {
+	const match = detectPrimarySkillKeyword(input.text);
+	if (!match) return null;
+	return await seedSkillActivationState(match.skill, match.keyword, "gjc-skill-state-hook", input);
+}
+
+export interface EnsureWorkflowSkillActivationInput {
+	cwd: string;
+	skill: string;
+	sessionId?: string;
+	threadId?: string;
+	turnId?: string;
+	nowIso?: string;
+	stateDir?: string;
+}
+
+/**
+ * Idempotently seed `.gjc/state` for a workflow skill that was invoked directly
+ * (e.g. via `/skill:<name>`) rather than through keyword detection. This ensures
+ * the mutation guard and Stop hook engage the moment a workflow skill becomes
+ * active, instead of relying on the skill prompt to run its own state-init steps.
+ *
+ * The seed is non-destructive: if an active entry for this skill already exists
+ * (for example after a `gjc state handoff` promotion that carries
+ * `handoff_from`/`handoff_at` lineage), nothing is written so lineage is
+ * preserved. Non-workflow skills are ignored.
+ */
+export async function ensureWorkflowSkillActivationState(
+	input: EnsureWorkflowSkillActivationInput,
+): Promise<SkillActiveState | null> {
+	const skill = input.skill.trim();
+	if (!isGjcWorkflowSkill(skill)) return null;
+	const existing = await readVisibleSkillActiveState(input.cwd, input.sessionId, input.stateDir);
+	const alreadyActive = listActiveSkills(existing).some(
+		entry =>
+			entry.skill === skill &&
+			(existing ? entryMatchesContext(entry, existing, input.sessionId, input.threadId) : true),
+	);
+	if (alreadyActive) return existing;
+	return await seedSkillActivationState(skill, `/skill:${skill}`, "gjc-skill-invocation", {
+		cwd: input.cwd,
+		sessionId: input.sessionId,
+		threadId: input.threadId,
+		turnId: input.turnId,
+		nowIso: input.nowIso,
+		stateDir: input.stateDir,
+	});
+}
+
 function isTerminalModeState(state: ModeState | null): boolean {
 	if (state?.active !== true) return true;
 	const phase = String(state.current_phase ?? "")
@@ -335,6 +439,45 @@ function isTerminalModeState(state: ModeState | null): boolean {
 	return ["complete", "completed", "handoff", "failed", "cancelled", "canceled", "inactive"].includes(phase);
 }
 
+/**
+ * Phases that genuinely finish a skill and release the Stop block. Note that
+ * "handoff" is intentionally absent: a skill sitting in the handoff phase has
+ * declared it is ready to chain but has not yet been demoted/cleared, so it
+ * must keep blocking until the chain (or an explicit clear) removes it.
+ */
+const STOP_RELEASING_PHASES = ["complete", "completed", "failed", "cancelled", "canceled", "inactive"] as const;
+
+/**
+ * Handoff workflows must never stop silently — they always have to offer the
+ * user a next step (refine, hand off, or finish) via the ask tool. The Stop
+ * hook keeps blocking these even in the "handoff" phase until they are demoted
+ * (active:false) or cleared.
+ */
+function isHandoffRequiredSkill(skill: GjcWorkflowSkill): boolean {
+	return skill === "deep-interview" || skill === "ralplan";
+}
+
+/**
+ * Decide whether an active-state entry's mode-state releases the Stop block.
+ *
+ * For handoff-required skills a missing or unreadable mode-state does NOT
+ * release the block: those workflows must always end by offering the user a
+ * next step, so the `skill-active-state.json` entry stays authoritative until
+ * the skill is demoted or cleared. For other skills a missing/corrupt
+ * mode-state preserves the historical fail-open behavior so a broken state file
+ * cannot lock a session.
+ */
+function modeStateReleasesStop(state: ModeState | null, handoffRequired: boolean): boolean {
+	if (!state) return !handoffRequired;
+	if (state.active !== true) return true;
+	const phase = String(state.current_phase ?? "")
+		.trim()
+		.toLowerCase();
+	if ((STOP_RELEASING_PHASES as readonly string[]).includes(phase)) return true;
+	if (!handoffRequired && phase === "handoff") return true;
+	return false;
+}
+
 async function readVisibleModeState(
 	cwd: string,
 	skill: GjcWorkflowSkill,
@@ -344,11 +487,11 @@ async function readVisibleModeState(
 	const resolvedStateDir = resolveGjcStateDir(cwd, stateDir);
 	if (sessionId) {
 		const sessionStatePath = modeStatePath(resolvedStateDir, skill, sessionId);
-		const sessionState = await readJsonFile<ModeState>(sessionStatePath);
+		const sessionState = await readValidatedJsonFile<ModeState>(sessionStatePath, "mode-state", ModeStateSchema);
 		if (sessionState) return { state: sessionState, statePath: sessionStatePath };
 	}
 	const rootStatePath = modeStatePath(resolvedStateDir, skill);
-	const rootState = await readJsonFile<ModeState>(rootStatePath);
+	const rootState = await readValidatedJsonFile<ModeState>(rootStatePath, "mode-state", ModeStateSchema);
 	if (!rootState) return null;
 	return { state: rootState, statePath: rootStatePath };
 }
@@ -421,8 +564,13 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 	if (!skillState || activeEntries.length === 0) return null;
 
 	for (const entry of activeEntries) {
-		const modeState = await readJsonFile<ModeState>(modeStatePath(resolvedStateDir, entry.skill, input.sessionId));
-		if (isTerminalModeState(modeState)) continue;
+		const modeState = await readValidatedJsonFile<ModeState>(
+			modeStatePath(resolvedStateDir, entry.skill, input.sessionId),
+			"mode-state",
+			ModeStateSchema,
+		);
+		const handoffRequired = isHandoffRequiredSkill(entry.skill);
+		if (modeStateReleasesStop(modeState, handoffRequired)) continue;
 		const phase = String(modeState?.current_phase ?? entry.phase ?? skillState.phase ?? "active");
 		const statePath = modeStatePath(resolvedStateDir, entry.skill, input.sessionId);
 		if (entry.skill === "ultragoal") {
@@ -450,7 +598,9 @@ export async function buildSkillStopOutput(input: StopHookInput): Promise<Record
 				}
 			}
 		}
-		const systemMessage = `GJC skill "${entry.skill}" is still active (phase: ${phase}; state: ${statePath}). Continue or explicitly finish/cancel the skill before stopping.`;
+		const systemMessage = handoffRequired
+			? `GJC handoff skill "${entry.skill}" must not stop without offering a next step (phase: ${phase}; state: ${statePath}). Use the ask tool to present the next handoff step — e.g. refine further, hand off to ralplan/team/ultragoal, or finish — then chain or explicitly clear the skill before stopping.`
+			: `GJC skill "${entry.skill}" is still active (phase: ${phase}; state: ${statePath}). Continue or explicitly finish/cancel the skill before stopping.`;
 		return {
 			decision: "block",
 			reason: systemMessage,

package/src/internal-urls/agent-protocol.ts

@@ -1,23 +1,72 @@
 /**
  * Protocol handler for agent:// URLs.
  *
- * Resolves agent output IDs against the artifacts directories of every active
- * session. Parents and subagents share outputs via this registry: a subagent
- * can read its parent's output IDs because both sessions are registered in
- * the shared context.
+ * Resolves agent output IDs only against artifacts directories explicitly
+ * authorized by the caller's ResolveContext. Parents and subagents can share
+ * outputs by passing their tree's artifacts dir at that API boundary.
  *
  * URL forms:
  * - agent://<id> - Full output content
  * - agent://<id>/<path> - JSON extraction via path form
  * - agent://<id>?q=<query> - JSON extraction via query form
  */
+import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent } from "@gajae-code/utils";
 import { applyQuery, pathToQuery } from "./json-query";
-import { artifactsDirsFromRegistry } from "./registry-helpers";
-import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+import { authorizedArtifactsDirsFromContext } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext } from "./types";
 
+interface AgentOutputMetadata {
+	id: string;
+	kind: "agent-output";
+	sizeBytes: number;
+	lineCount: number;
+	sha256: string;
+	createdAt: string;
+}
+
+function isAgentOutputMetadata(value: unknown, outputId: string): value is AgentOutputMetadata {
+	if (!value || typeof value !== "object") return false;
+	const meta = value as Record<string, unknown>;
+	return (
+		meta.id === outputId &&
+		meta.kind === "agent-output" &&
+		typeof meta.sizeBytes === "number" &&
+		typeof meta.lineCount === "number" &&
+		typeof meta.sha256 === "string" &&
+		typeof meta.createdAt === "string"
+	);
+}
+
+async function verifyAgentOutputMetadata(outputId: string, foundPath: string, bytes: Buffer): Promise<void> {
+	const metaPath = `${foundPath}.meta.json`;
+	let metaRaw: string;
+	try {
+		metaRaw = await Bun.file(metaPath).text();
+	} catch (err) {
+		if (isEnoent(err)) throw new Error(`agent://${outputId} missing metadata`);
+		throw err;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(metaRaw);
+	} catch {
+		throw new Error(`agent://${outputId} malformed metadata`);
+	}
+	if (!isAgentOutputMetadata(parsed, outputId)) {
+		throw new Error(`agent://${outputId} malformed metadata`);
+	}
+	const stat = await fs.stat(foundPath);
+	if (stat.size !== parsed.sizeBytes || bytes.byteLength !== parsed.sizeBytes) {
+		throw new Error(`agent://${outputId} size mismatch`);
+	}
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	if (sha256 !== parsed.sha256) {
+		throw new Error(`agent://${outputId} hash mismatch`);
+	}
+}
 /**
  * Handler for agent:// URLs.
  *
@@ -28,11 +77,17 @@ export class AgentProtocolHandler implements ProtocolHandler {
 	readonly scheme = "agent";
 	readonly immutable = true;
 
-	async resolve(url: InternalUrl): Promise<InternalResource> {
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
 		const outputId = url.rawHost || url.hostname;
 		if (!outputId) {
 			throw new Error("agent:// URL requires an output ID: agent://<id>");
 		}
+		// Output IDs address a single file inside a session artifacts dir. Reject
+		// path separators / traversal so a crafted id cannot escape the dir via
+		// path.join(dir, `${outputId}.md`).
+		if (outputId.includes("/") || outputId.includes("\\") || outputId.includes("..")) {
+			throw new Error(`agent://${outputId} invalid id: path separators are not allowed`);
+		}
 
 		const urlPath = url.pathname;
 		const queryParam = url.searchParams.get("q");
@@ -43,7 +98,7 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			throw new Error("agent:// URL cannot combine path extraction with ?q=");
 		}
 
-		const dirs = artifactsDirsFromRegistry();
+		const dirs = authorizedArtifactsDirsFromContext(context);
 
 		if (dirs.length === 0) {
 			throw new Error("No session - agent outputs unavailable");
@@ -51,7 +106,6 @@ export class AgentProtocolHandler implements ProtocolHandler {
 
 		let foundPath: string | undefined;
 		let anyDirExists = false;
-		const availableIds = new Set<string>();
 
 		for (const dir of dirs) {
 			try {
@@ -64,18 +118,10 @@ export class AgentProtocolHandler implements ProtocolHandler {
 			const candidate = path.join(dir, `${outputId}.md`);
 			try {
 				await fs.stat(candidate);
+				if (foundPath) throw new Error(`agent://${outputId} ambiguous id in authorized artifacts`);
 				foundPath = candidate;
-				break;
 			} catch (err) {
 				if (!isEnoent(err)) throw err;
-				try {
-					const files = await fs.readdir(dir);
-					for (const f of files) {
-						if (f.endsWith(".md")) availableIds.add(f.replace(/\.md$/, ""));
-					}
-				} catch {
-					// Listing failures are non-fatal; continue searching.
-				}
 			}
 		}
 
@@ -84,11 +130,12 @@ export class AgentProtocolHandler implements ProtocolHandler {
 		}
 
 		if (!foundPath) {
-			const availableStr = availableIds.size > 0 ? [...availableIds].join(", ") : "none";
-			throw new Error(`Not found: ${outputId}\nAvailable: ${availableStr}`);
+			throw new Error(`agent://${outputId} not found`);
 		}
 
-		const rawContent = await Bun.file(foundPath).text();
+		const rawBytes = Buffer.from(await Bun.file(foundPath).arrayBuffer());
+		await verifyAgentOutputMetadata(outputId, foundPath, rawBytes);
+		const rawContent = rawBytes.toString("utf8");
 		const notes: string[] = [];
 		let content = rawContent;
 		let contentType: InternalResource["contentType"] = "text/markdown";

package/src/internal-urls/artifact-protocol.ts

@@ -1,8 +1,8 @@
 /**
  * Protocol handler for artifact:// URLs.
  *
- * Resolves artifact IDs against the artifacts directories of every active
- * session. Unlike agent://, artifacts are raw text with no JSON extraction.
+ * Resolves artifact IDs only against artifacts directories explicitly authorized
+ * by the caller's ResolveContext. Unlike agent://, artifacts are raw text.
  *
  * URL form:
  * - artifact://<id> - Full artifact content
@@ -12,14 +12,14 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isEnoent } from "@gajae-code/utils";
-import { artifactsDirsFromRegistry } from "./registry-helpers";
-import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+import { authorizedArtifactsDirsFromContext } from "./registry-helpers";
+import type { InternalResource, InternalUrl, ProtocolHandler, ResolveContext } from "./types";
 
 export class ArtifactProtocolHandler implements ProtocolHandler {
 	readonly scheme = "artifact";
 	readonly immutable = true;
 
-	async resolve(url: InternalUrl): Promise<InternalResource> {
+	async resolve(url: InternalUrl, context?: ResolveContext): Promise<InternalResource> {
 		const id = url.rawHost || url.hostname;
 		if (!id) {
 			throw new Error("artifact:// URL requires a numeric ID: artifact://0");
@@ -28,7 +28,7 @@ export class ArtifactProtocolHandler implements ProtocolHandler {
 			throw new Error(`artifact:// ID must be numeric, got: ${id}`);
 		}
 
-		const dirs = artifactsDirsFromRegistry();
+		const dirs = authorizedArtifactsDirsFromContext(context);
 
 		if (dirs.length === 0) {
 			throw new Error("No session - artifacts unavailable");
@@ -36,7 +36,6 @@ export class ArtifactProtocolHandler implements ProtocolHandler {
 
 		let foundPath: string | undefined;
 		let anyDirExists = false;
-		const availableIds = new Set<string>();
 
 		for (const dir of dirs) {
 			let files: string[];
@@ -47,14 +46,12 @@ export class ArtifactProtocolHandler implements ProtocolHandler {
 				if (isEnoent(err)) continue;
 				throw err;
 			}
-			const match = files.find(f => f.startsWith(`${id}.`));
-			if (match) {
-				foundPath = path.join(dir, match);
-				break;
-			}
 			for (const f of files) {
-				const m = f.match(/^(\d+)\./);
-				if (m) availableIds.add(m[1]);
+				if (f.endsWith(".meta.json")) continue;
+				if (f.startsWith(`${id}.`)) {
+					if (foundPath) throw new Error(`artifact://${id} ambiguous id in authorized artifacts`);
+					foundPath = path.join(dir, f);
+				}
 			}
 		}
 
@@ -63,9 +60,7 @@ export class ArtifactProtocolHandler implements ProtocolHandler {
 		}
 
 		if (!foundPath) {
-			const sorted = [...availableIds].sort((a, b) => Number(a) - Number(b));
-			const availableStr = sorted.length > 0 ? sorted.join(", ") : "none";
-			throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+			throw new Error(`artifact://${id} not found`);
 		}
 
 		const content = await Bun.file(foundPath).text();