@gajae-code/coding-agent 0.13.2 → 0.14.0

package/src/extensibility/skill-management.ts

@@ -0,0 +1,368 @@
+/**
+ * Authoritative skill management contracts for native `.gjc` skills.
+ *
+ * Canonical skill locations are project `<project>/.gjc/skills/` and global
+ * `~/.gjc/agent/skills/` (plus legacy user roots). Claude Code / Codex layouts
+ * are explicit import sources into `.gjc` and are enumerated separately by
+ * `listConventionSkillImportSources`; they are never loaded as ordinary runtime
+ * skills.
+ *
+ * These contracts are the reusable behavior the `/extensions` surface (#4291)
+ * and SDK consumers build on: discovery with provenance + enablement state,
+ * writing a skill file into a scope, and per-skill enable/disable. The import
+ * preview/apply transaction and the UI itself are owned by #4291.
+ */
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parseFrontmatter } from "@gajae-code/utils";
+import { findRepoRoot } from "../capability/fs";
+import type { Skill as CapabilitySkill } from "../capability/skill";
+import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
+import { scanClaudeProjectSkills, scanClaudeUserSkills } from "../discovery/claude";
+import { scanCodexProjectSkills, scanCodexUserSkills } from "../discovery/codex";
+import { compareSkillOrder, SOURCE_PATHS, scanSkillsFromDir } from "../discovery/helpers";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+export type SkillScope = "project" | "user";
+export type ConventionSkillHost = "claude" | "codex";
+
+export interface SkillManagementPolicy {
+	enabled?: boolean;
+	trustProjectSkills?: boolean;
+	trustUserSkills?: boolean;
+	ignoredSkills?: string[];
+	includeSkills?: string[];
+	disabledExtensions?: string[];
+}
+
+export type SkillDisabledReason = "protected" | "scope-trust" | "ignored" | "include" | "disabled-extension";
+
+/** A discovered native skill with provenance and enablement state. */
+export interface ManagedSkillRecord {
+	name: string;
+	description: string;
+	path: string;
+	scope: SkillScope;
+	/** Canonical source label, e.g. "project .gjc/skills" or "user ~/.gjc/agent/skills". */
+	source: string;
+	hidden: boolean;
+	enabled: boolean;
+	disabledReason?: SkillDisabledReason;
+}
+
+/** A Claude Code / Codex skill enumerated as an explicit import source into `.gjc`. */
+export interface ConventionSkillImportSource {
+	host: ConventionSkillHost;
+	scope: SkillScope;
+	name: string;
+	description: string;
+	path: string;
+}
+
+export interface WriteNativeSkillInput {
+	cwd: string;
+	home?: string;
+	scope: SkillScope;
+	name: string;
+	content: string;
+}
+
+export interface WriteNativeSkillReceipt {
+	name: string;
+	scope: SkillScope;
+	directory: string;
+	path: string;
+}
+
+/** Raised when a write targets one of the four bundled workflow skill names. */
+export class SkillNameProtectedError extends Error {
+	readonly code = "SKILL_NAME_PROTECTED";
+	constructor(name: string) {
+		super(
+			`skill "${name}" is a bundled GJC workflow skill (${CANONICAL_GJC_WORKFLOW_SKILLS.join(", ")}) and cannot be written as a custom skill`,
+		);
+		this.name = "SkillNameProtectedError";
+	}
+}
+
+/** Raised when skill content has no parseable frontmatter or lacks a description. */
+export class SkillFrontmatterError extends Error {
+	readonly code = "SKILL_FRONTMATTER_INVALID";
+	constructor(message: string) {
+		super(message);
+		this.name = "SkillFrontmatterError";
+	}
+}
+
+const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
+
+function getRuntimeHome(): string {
+	return process.env.HOME || os.homedir();
+}
+
+/** Ancestor directories from `cwd` (inclusive) up to `stop` (inclusive), excluding `home`. */
+function ancestorDirs(cwd: string, stop: string, home: string): string[] {
+	const dirs: string[] = [];
+	let current = path.resolve(cwd);
+	const resolvedStop = path.resolve(stop);
+	const resolvedHome = path.resolve(home);
+	while (true) {
+		if (current !== resolvedHome) {
+			dirs.push(current);
+		}
+		if (current === resolvedStop) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return dirs;
+}
+
+/**
+ * Canonical project skill directories in precedence order: `.gjc/skills` in
+ * every ancestor from `cwd` up to the repo root (closest first).
+ */
+export async function getProjectSkillDirs(
+	cwd: string,
+	home: string,
+): Promise<{ dirs: string[]; repoRoot: string | null }> {
+	const repoRoot = await findRepoRoot(cwd);
+	const walkDirs = ancestorDirs(cwd, path.resolve(repoRoot ?? cwd), home);
+	return { dirs: walkDirs.map(dir => path.join(dir, ".gjc", "skills")), repoRoot };
+}
+
+/** Canonical user skill directories in precedence order (same resolution as runtime discovery). */
+export function getUserSkillDirs(home: string): string[] {
+	return [
+		...new Set([
+			path.join(home, SOURCE_PATHS.native.userAgent, "skills"),
+			path.join(home, SOURCE_PATHS.native.userBase, "skills"),
+			path.join(home, ".gjc", "skills"),
+		]),
+	];
+}
+
+/**
+ * The canonical directory a write targets for a scope: the repo root (or `cwd`)
+ * `.gjc/skills` for project scope, the canonical `<config>/agent/skills` user
+ * root for user scope (honoring `GJC_CONFIG_DIR` / `PI_CONFIG_DIR`).
+ */
+export async function resolveNativeSkillScopeDir(
+	cwd: string,
+	scope: SkillScope,
+	home = getRuntimeHome(),
+): Promise<string> {
+	if (scope === "user") return path.join(home, SOURCE_PATHS.native.userAgent, "skills");
+	const repoRoot = await findRepoRoot(cwd);
+	return path.join(repoRoot ?? path.resolve(cwd), ".gjc", "skills");
+}
+
+function matchesPattern(name: string, patterns: string[] | undefined): boolean {
+	if (!patterns || patterns.length === 0) return false;
+	return patterns.some(pattern => new Bun.Glob(pattern).match(name));
+}
+
+function isDisabledByExtension(name: string, disabledExtensions: string[] | undefined): boolean {
+	return (disabledExtensions ?? []).some(id => id === `skill:${name}`);
+}
+
+/**
+ * Authoritative discovery of native skills with provenance and enablement
+ * state. Unlike runtime session discovery, this lists every scanned skill —
+ * including disabled, shadowed, and protected ones — so `/extensions` and SDK
+ * consumers can show and toggle the full catalog.
+ */
+export async function listNativeSkillsForManagement(options: {
+	cwd: string;
+	home?: string;
+	policy?: SkillManagementPolicy;
+}): Promise<ManagedSkillRecord[]> {
+	const home = options.home ?? getRuntimeHome();
+	const policy = options.policy;
+	const projectTrusted = resolveSkillScopeTrust(policy ?? {}, "project");
+	const userTrusted = resolveSkillScopeTrust(policy ?? {}, "user");
+
+	const scanJobs: Array<Promise<{ dir: string; items: CapabilitySkill[] }>> = [];
+	const projectDirs = await getProjectSkillDirs(options.cwd, home);
+	if (projectTrusted) {
+		for (const dir of projectDirs.dirs) {
+			scanJobs.push(
+				scanSkillsFromDir(
+					{ cwd: options.cwd, home, repoRoot: projectDirs.repoRoot },
+					{ dir, providerId: "runtime", level: "project", requireDescription: true },
+				).then(result => ({ dir, items: result.items })),
+			);
+		}
+	}
+	if (userTrusted) {
+		for (const dir of getUserSkillDirs(home)) {
+			scanJobs.push(
+				scanSkillsFromDir(
+					{ cwd: options.cwd, home, repoRoot: home },
+					{ dir, providerId: "runtime", level: "user", requireDescription: true },
+				).then(result => ({ dir, items: result.items })),
+			);
+		}
+	}
+
+	const records: ManagedSkillRecord[] = [];
+	const seenNames = new Set<string>();
+	const seenPaths = new Set<string>();
+
+	for (const { dir, items } of await Promise.all(scanJobs)) {
+		const scope: SkillScope = path.resolve(dir).startsWith(`${path.resolve(home)}${path.sep}`) ? "user" : "project";
+		const source = scope === "project" ? "project .gjc/skills" : `user ${dir}`;
+		for (const skill of items) {
+			const realPath = await safeRealpath(skill.path);
+			if (seenPaths.has(realPath)) continue;
+
+			let disabledReason: SkillDisabledReason | undefined;
+			let enabled = true;
+			if (BUILT_IN_SKILL_NAMES.has(skill.name)) {
+				enabled = false;
+				disabledReason = "protected";
+			} else if (!(scope === "project" ? projectTrusted : userTrusted)) {
+				enabled = false;
+				disabledReason = "scope-trust";
+			} else if (matchesPattern(skill.name, policy?.ignoredSkills)) {
+				enabled = false;
+				disabledReason = "ignored";
+			} else if (policy?.includeSkills?.length && !matchesPattern(skill.name, policy.includeSkills)) {
+				enabled = false;
+				disabledReason = "include";
+			} else if (isDisabledByExtension(skill.name, policy?.disabledExtensions)) {
+				enabled = false;
+				disabledReason = "disabled-extension";
+			}
+
+			if (!seenNames.has(skill.name)) {
+				seenNames.add(skill.name);
+				records.push({
+					name: skill.name,
+					description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
+					path: skill.path,
+					scope,
+					source,
+					hidden: skill.frontmatter?.hide === true,
+					enabled,
+					disabledReason,
+				});
+			}
+			seenPaths.add(realPath);
+		}
+	}
+
+	records.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
+	return records;
+}
+
+/**
+ * Write a native skill into the canonical `.gjc` scope directory. The content
+ * must parse as frontmatter with a non-empty `description`; the effective name
+ * comes from `frontmatter.name` when present, else the requested `name`. Bundled
+ * workflow skill names are rejected.
+ */
+export async function writeNativeSkill(input: WriteNativeSkillInput): Promise<WriteNativeSkillReceipt> {
+	const name = input.name.trim();
+	if (!name) throw new SkillFrontmatterError("skill name is required");
+
+	const { frontmatter } = parseFrontmatter(input.content, { source: "<skill-content>" });
+	if (!frontmatter) throw new SkillFrontmatterError("skill content must start with a YAML frontmatter block (---)");
+	const description = typeof frontmatter.description === "string" ? frontmatter.description.trim() : "";
+	if (!description) throw new SkillFrontmatterError("skill frontmatter must include a non-empty description");
+
+	const effectiveName =
+		typeof frontmatter.name === "string" && frontmatter.name.trim() ? frontmatter.name.trim() : name;
+	if (BUILT_IN_SKILL_NAMES.has(effectiveName)) throw new SkillNameProtectedError(effectiveName);
+
+	const directory = await resolveNativeSkillScopeDir(input.cwd, input.scope, input.home ?? getRuntimeHome());
+	const skillDir = path.join(directory, effectiveName);
+	await fs.mkdir(skillDir, { recursive: true });
+	const filePath = path.join(skillDir, "SKILL.md");
+	await Bun.write(filePath, `${input.content.trimEnd()}\n`);
+	return { name: effectiveName, scope: input.scope, directory, path: filePath };
+}
+
+/** Whether a skill is enabled under the current policy (disabledExtensions/ignored/scope trust). */
+export function isNativeSkillEnabled(name: string, policy: SkillManagementPolicy | undefined): boolean {
+	if (BUILT_IN_SKILL_NAMES.has(name)) return true;
+	if (isDisabledByExtension(name, policy?.disabledExtensions)) return false;
+	if (matchesPattern(name, policy?.ignoredSkills)) return false;
+	if (policy?.includeSkills?.length && !matchesPattern(name, policy.includeSkills)) return false;
+	return true;
+}
+
+/**
+ * Toggle per-skill enablement by adding/removing the `skill:<name>` entry in
+ * `disabledExtensions`. Returns the updated list; the caller persists it through
+ * Settings. Bundled workflow skill names cannot be disabled.
+ */
+export function setNativeSkillEnabled(name: string, enabled: boolean, disabledExtensions: string[]): string[] {
+	const id = `skill:${name}`;
+	const next = new Set(disabledExtensions);
+	if (BUILT_IN_SKILL_NAMES.has(name)) return [...next];
+	if (enabled) {
+		next.delete(id);
+	} else {
+		next.add(id);
+	}
+	return [...next];
+}
+
+/**
+ * Enumerate Claude Code / Codex skills (project and user scope) as explicit
+ * import sources into `.gjc`. This only reads the foreign layouts for
+ * inspection/import; nothing is loaded into sessions and user-home content is
+ * never used without an explicit import action (#4291).
+ */
+export async function listConventionSkillImportSources(options: {
+	cwd: string;
+	home?: string;
+	host?: ConventionSkillHost | "all";
+}): Promise<ConventionSkillImportSource[]> {
+	const home = options.home ?? getRuntimeHome();
+	const hosts: ConventionSkillHost[] = options.host === "all" || !options.host ? ["claude", "codex"] : [options.host];
+	const repoRoot = await findRepoRoot(options.cwd);
+	const ctx = { cwd: options.cwd, home, repoRoot };
+
+	const sources: ConventionSkillImportSource[] = [];
+	const seen = new Set<string>();
+	for (const host of hosts) {
+		const scan = host === "claude" ? scanClaudeSkills : scanCodexSkills;
+		const results = await scan(ctx);
+		for (const skill of results.items) {
+			const key = `${host}:${skill.level}:${skill.name}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			sources.push({
+				host,
+				scope: skill.level,
+				name: skill.name,
+				description: typeof skill.frontmatter?.description === "string" ? skill.frontmatter.description : "",
+				path: skill.path,
+			});
+		}
+	}
+	sources.sort((a, b) => compareSkillOrder(a.name, a.path, b.name, b.path));
+	return sources;
+}
+
+async function scanClaudeSkills(ctx: { cwd: string; home: string; repoRoot: string | null }) {
+	const project = await scanClaudeProjectSkills(ctx);
+	const user = await scanClaudeUserSkills(ctx);
+	return { items: [...project.items, ...user.items] };
+}
+
+async function scanCodexSkills(ctx: { cwd: string; home: string; repoRoot: string | null }) {
+	const project = await scanCodexProjectSkills(ctx);
+	const user = await scanCodexUserSkills(ctx);
+	return { items: [...project.items, ...user.items] };
+}
+
+async function safeRealpath(filePath: string): Promise<string> {
+	try {
+		return await fs.realpath(filePath);
+	} catch {
+		return filePath;
+	}
+}

package/src/extensibility/skills.ts

@@ -4,9 +4,11 @@ import { getProjectDir } from "@gajae-code/utils";
 import { skillCapability } from "../capability/skill";
 import type { SourceMeta } from "../capability/types";
 import type { SkillsSettings } from "../config/settings";
+import { resolveSkillScopeTrust } from "../config/skill-settings-defaults";
 import { type Skill as CapabilitySkill, loadCapability } from "../discovery";
 import { compareSkillOrder, scanSkillsFromDir } from "../discovery/helpers";
 import type { SkillPromptDetails } from "../session/messages";
+import { CANONICAL_GJC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
 import { expandTilde } from "../tools/path-utils";
 import type { LoadedSubskillActivation } from "./gjc-plugins";
 import { buildSubskillInjection } from "./gjc-plugins/injection";
@@ -108,6 +110,15 @@ export interface LoadSkillsOptions extends SkillsSettings {
 	cwd?: string;
 }
 
+/**
+ * Skill providers loaded into sessions. Only native `.gjc` skills are live
+ * filesystem skills; Claude/Codex convention skills are explicit import
+ * sources into `.gjc` (see skill-management.ts) and are never loaded directly.
+ */
+const LOADABLE_SKILL_PROVIDERS = new Set(["native"]);
+
+const BUILT_IN_SKILL_NAMES = new Set<string>(CANONICAL_GJC_WORKFLOW_SKILLS);
+
 /**
  * Load skills from all configured locations.
  * Returns skills and any validation warnings.
@@ -116,8 +127,6 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	const {
 		cwd = getProjectDir(),
 		enabled = true,
-		enablePiUser = true,
-		enablePiProject = true,
 		customDirectories = [],
 		ignoredSkills = [],
 		includeSkills = [],
@@ -129,17 +138,24 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 		return { skills: [], warnings: [] };
 	}
 
-	// GJC only accepts native `.gjc` skills. Other providers may still exist for
-	// their own capabilities, but their skill surfaces are intentionally ignored.
+	const projectTrusted = resolveSkillScopeTrust(options, "project");
+	const userTrusted = resolveSkillScopeTrust(options, "user");
+
+	// Skill scope trust decides which canonical locations are loaded: project
+	// scope covers `.gjc/skills` (walk-up), user scope covers `~/.gjc/agent/skills`
+	// and the legacy user roots. Claude/Codex convention skills are import
+	// sources into `.gjc`, never loaded directly.
 	function isSourceEnabled(source: SourceMeta): boolean {
 		const { provider, level } = source;
-		if (provider !== "native") return false;
-		if (level === "user") return enablePiUser;
-		if (level === "project") return enablePiProject;
+		if (!LOADABLE_SKILL_PROVIDERS.has(provider)) return false;
+		if (level === "user") return userTrusted;
+		if (level === "project") return projectTrusted;
 		return false;
 	}
 
-	// Use capability API to load all skills
+	// Use capability API to load all skills. `all` (rather than `items`) keeps
+	// shadowed duplicates so this function can apply the documented precedence
+	// itself: project scope beats user scope.
 	const result = await loadCapability<CapabilitySkill>(skillCapability.id, { cwd, disabledExtensions });
 
 	const skillMap = new Map<string, Skill>();
@@ -161,14 +177,23 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 	const disabledSkillNames = new Set(
 		(disabledExtensions ?? []).filter(id => id.startsWith("skill:")).map(id => id.slice(6)),
 	);
-	// Filter skills by source and patterns first
-	const filteredSkills = result.items.filter(capSkill => {
-		if (disabledSkillNames.has(capSkill.name)) return false;
-		if (!isSourceEnabled(capSkill._source)) return false;
-		if (matchesIgnorePatterns(capSkill.name)) return false;
-		if (!matchesIncludePatterns(capSkill.name)) return false;
-		return true;
-	});
+
+	// Apply scope trust and policy filters, then order candidates by documented
+	// precedence. `all` is already in native provider order with project dirs
+	// before user dirs; a stable sort by level lifts every project item above
+	// every user item, giving: project `.gjc/skills` > user roots.
+	const filteredSkills = result.all
+		.filter(capSkill => {
+			if (!isSourceEnabled(capSkill._source)) return false;
+			if (disabledSkillNames.has(capSkill.name)) return false;
+			if (matchesIgnorePatterns(capSkill.name)) return false;
+			if (!matchesIncludePatterns(capSkill.name)) return false;
+			return true;
+		})
+		.sort((a, b) => {
+			const levelOrder = { project: 0, user: 1 } as const;
+			return levelOrder[a.level] - levelOrder[b.level];
+		});
 
 	// Batch resolve all real paths in parallel
 	const realPaths = await Promise.all(
@@ -191,6 +216,17 @@ export async function loadSkills(options: LoadSkillsOptions = {}): Promise<LoadS
 			continue;
 		}
 
+		// A project-controlled copy of a bundled workflow skill name is a potential
+		// workflow-routing hijack: warn, and let the session merge keep the bundled
+		// definition authoritative (sdk/session.ts). User-scope copies are not
+		// warned about: installed defaults legitimately mirror bundled skills.
+		if (capSkill.level === "project" && BUILT_IN_SKILL_NAMES.has(capSkill.name)) {
+			collisionWarnings.push({
+				skillPath: capSkill.path,
+				message: `name collision: "${capSkill.name}" is a bundled GJC workflow skill; the bundled definition takes precedence in sessions and this project copy is never used`,
+			});
+		}
+
 		const existing = skillMap.get(capSkill.name);
 		if (existing) {
 			collisionWarnings.push({

package/src/gjc-runtime/deep-interview-runtime.ts

@@ -1,8 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { getConfigRootDir } from "@gajae-code/utils";
-import { YAML } from "bun";
+import { isSettingsInitialized, Settings } from "../config/settings";
 import { syncSkillActiveState } from "../skill-state/active-state";
 import { deriveDeepInterviewHud } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
@@ -25,6 +24,7 @@ import { resolveGjcSessionForWrite, writeSessionActivityMarker } from "./session
 import { runNativeStateCommand } from "./state-runtime";
 import { appendJsonl, readExistingStateForMutation, writeArtifact, writeWorkflowEnvelopeAtomic } from "./state-writer";
 import { assertSafePathComponent, CommandError, flagValue, hasFlag } from "./workflow-cli-common";
+import { resolveWorkflowSetting } from "./workflow-settings";
 
 export * from "./deep-interview-recorder";
 
@@ -346,62 +346,37 @@ interface DeepInterviewSpecWriteSummary {
 	};
 }
 
-async function readSettingsAmbiguityThreshold(
-	settingsPath: string,
-): Promise<{ threshold: number; source: string } | undefined> {
-	let raw: string;
-	try {
-		raw = await fs.readFile(settingsPath, "utf-8");
-	} catch (error) {
-		const err = error as NodeJS.ErrnoException;
-		if (err.code === "ENOENT") return undefined;
-		return undefined;
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return undefined;
-	}
-	const candidate = (parsed as { gjc?: { deepInterview?: { ambiguityThreshold?: unknown } } })?.gjc?.deepInterview
-		?.ambiguityThreshold;
-	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1) {
-		return undefined;
-	}
-	return { threshold: candidate, source: settingsPath };
-}
-
-function modernSettingsPath(): string {
-	const configDir = process.env.GJC_CODING_AGENT_DIR?.trim() || process.env.PI_CODING_AGENT_DIR?.trim();
-	if (configDir) return path.join(configDir, "config.yml");
-	return path.join(getConfigRootDir(), "agent", "config.yml");
-}
-
-async function readModernSettingsAmbiguityThreshold(): Promise<{ threshold: number; source: string } | undefined> {
-	const modernConfigPath = modernSettingsPath();
-	let parsed: unknown;
-	try {
-		parsed = YAML.parse(await fs.readFile(modernConfigPath, "utf-8"));
-	} catch {
-		return undefined;
-	}
-	const candidate = (parsed as { gjc?: { deepInterview?: { ambiguityThreshold?: unknown } } })?.gjc?.deepInterview
-		?.ambiguityThreshold;
-	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0 || candidate > 1)
-		return undefined;
-	return { threshold: candidate, source: modernConfigPath };
-}
-
+/**
+ * Resolve the configured ambiguity threshold through the shared five-layer
+ * resolver: project `.gjc/config.yml` > project `.gjc/settings.json` > user
+ * `getAgentDir()/config.yml` > legacy config-root `settings.json` > default.
+ * Project configuration beats user configuration, and invalid optional files
+ * continue to lower layers (tolerant contract). Returns `undefined` when the
+ * resolver falls back to the default so the resolution flags (`--quick`/
+ * `--standard`/`--deep`) still apply.
+ */
 async function resolveConfiguredAmbiguityThreshold(
 	cwd: string,
+	agentDir?: string,
 ): Promise<{ threshold: number; source: string } | undefined> {
-	const modernValue = await readModernSettingsAmbiguityThreshold();
-	if (modernValue) return modernValue;
-	const projectSettings = path.join(cwd, ".gjc", "settings.json");
-	const projectValue = await readSettingsAmbiguityThreshold(projectSettings);
-	if (projectValue) return projectValue;
-	const userSettings = path.join(getConfigRootDir(), "settings.json");
-	return await readSettingsAmbiguityThreshold(userSettings);
+	const resolution = await resolveWorkflowSetting(cwd, "gjc.deepInterview.ambiguityThreshold", {
+		defaultValue: DEFAULT_AMBIGUITY_THRESHOLD,
+		parse: value => {
+			if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > 1) {
+				return {
+					kind: "invalid",
+					reason: "expected gjc.deepInterview.ambiguityThreshold to be a number in (0, 1]",
+				};
+			}
+			return { kind: "valid", value };
+		},
+		// The session's effective agent profile: an SDK session created with
+		// `createAgentSession({ agentDir })` resolves against that directory
+		// instead of the process-global default.
+		agentDir: agentDir ?? (isSettingsInitialized() ? Settings.instance.getAgentDir() : undefined),
+	});
+	if (resolution.source === "default") return undefined;
+	return { threshold: resolution.value, source: resolution.source };
 }
 
 function englishLanguagePreference(): DeepInterviewLanguagePreference {
@@ -502,7 +477,11 @@ async function resolveSpecWriteArgs(args: readonly string[], cwd: string): Promi
 	};
 }
 
-async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): Promise<ResolvedDeepInterviewArgs> {
+async function resolveDeepInterviewArgs(
+	args: readonly string[],
+	cwd: string,
+	agentDir?: string,
+): Promise<ResolvedDeepInterviewArgs> {
 	const session = resolveGjcSessionForWrite(cwd, {
 		flagValue: flagValue(args, "--session-id"),
 		envSessionId: process.env.GJC_SESSION_ID,
@@ -531,7 +510,7 @@ async function resolveDeepInterviewArgs(args: readonly string[], cwd: string): P
 		threshold = parsed;
 		thresholdSource = flagValue(args, "--threshold-source")?.trim() || "flag:--threshold";
 	} else {
-		const configured = await resolveConfiguredAmbiguityThreshold(cwd);
+		const configured = await resolveConfiguredAmbiguityThreshold(cwd, agentDir);
 		if (configured) {
 			threshold = configured.threshold;
 			thresholdSource = configured.source;
@@ -823,7 +802,11 @@ async function syncDeepInterviewHud(options: {
 	}
 }
 
-async function handleSpecWrite(args: readonly string[], cwd: string): Promise<DeepInterviewCommandResult> {
+async function handleSpecWrite(
+	args: readonly string[],
+	cwd: string,
+	agentDir?: string,
+): Promise<DeepInterviewCommandResult> {
 	const resolved = await resolveSpecWriteArgs(args, cwd);
 	const persisted = await persistDeepInterviewSpec(cwd, resolved);
 	const shouldHandoff = resolved.deliberate || resolved.handoff === "ralplan";
@@ -843,7 +826,7 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 		const ralplanArgs = ["--deliberate", "--json"];
 		if (resolved.sessionId) ralplanArgs.push("--session-id", resolved.sessionId);
 		ralplanArgs.push(persisted.path);
-		const ralplanResult = await runNativeRalplanCommand(ralplanArgs, cwd);
+		const ralplanResult = await runNativeRalplanCommand(ralplanArgs, cwd, { agentDir });
 		if (ralplanResult.status !== 0) {
 			throw new DeepInterviewCommandError(
 				ralplanResult.status,
@@ -890,12 +873,13 @@ async function handleSpecWrite(args: readonly string[], cwd: string): Promise<De
 export async function runNativeDeepInterviewCommand(
 	args: string[],
 	cwd = process.cwd(),
+	options: { agentDir?: string } = {},
 ): Promise<DeepInterviewCommandResult> {
 	try {
 		const [firstArg, ...restArgs] = args;
 		if (isDeepInterviewStageVerb(firstArg)) return await runDeepInterviewStageCommand(firstArg, restArgs, cwd);
-		if (isDeepInterviewSpecWriteInvocation(args)) return await handleSpecWrite(args, cwd);
-		const resolved = await resolveDeepInterviewArgs(args, cwd);
+		if (isDeepInterviewSpecWriteInvocation(args)) return await handleSpecWrite(args, cwd, options.agentDir);
+		const resolved = await resolveDeepInterviewArgs(args, cwd, options.agentDir);
 		if (!resolved.idea) {
 			throw new DeepInterviewCommandError(
 				2,