@gajae-code/coding-agent 0.2.2 → 0.2.3

package/dist/types/task/types.d.ts

@@ -5,6 +5,7 @@ import { type TaskSimpleMode } from "./simple-mode";
 import type { NestedRepoPatch } from "./worktree";
 /** Source of an agent definition */
 export type AgentSource = "bundled" | "user" | "project";
+export type ForkContextPolicy = "forbidden" | "allowed";
 /** Maximum output bytes per agent */
 export declare const MAX_OUTPUT_BYTES: number;
 /** Maximum output lines per agent */
@@ -40,6 +41,7 @@ export declare const taskItemSchema: z.ZodObject<{
     id: z.ZodString;
     description: z.ZodString;
     assignment: z.ZodString;
+    inheritContext: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type TaskItem = z.infer<typeof taskItemSchema>;
 export declare const taskSchema: z.ZodObject<{
@@ -48,6 +50,7 @@ export declare const taskSchema: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const taskSchemaNoIsolation: z.ZodObject<{
@@ -56,6 +59,7 @@ export declare const taskSchemaNoIsolation: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
@@ -64,6 +68,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     agent: z.ZodString;
@@ -71,6 +76,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     agent: z.ZodString;
@@ -78,6 +84,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     agent: z.ZodString;
@@ -85,6 +92,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     agent: z.ZodString;
@@ -92,6 +100,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     agent: z.ZodString;
@@ -99,6 +108,7 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        inheritContext: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>];
 type DynamicTaskSchema = (typeof ALL_TASK_SCHEMAS)[number];
@@ -150,6 +160,7 @@ export interface AgentDefinition {
     blocking?: boolean;
     autoloadSkills?: string[];
     hide?: boolean;
+    forkContext?: ForkContextPolicy;
     source: AgentSource;
     filePath?: string;
 }

package/dist/types/tools/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTelemetryConfig, AgentTool } from "@gajae-code/agent-core";
-import type { ToolChoice } from "@gajae-code/ai";
+import type { Model, ToolChoice } from "@gajae-code/ai";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
@@ -7,10 +7,12 @@ import type { GoalModeState, GoalRuntime } from "../goals";
 import type { HindsightSessionState } from "../hindsight/state";
 import type { PlanModeState } from "../plan-mode/state";
 import type { AgentRegistry } from "../registry/agent-registry";
+import type { ForkContextSeed, ForkContextSeedOptions } from "../session/agent-session";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
 import type { CustomMessage } from "../session/messages";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
+import type { SkillActiveEntry } from "../skill-state/active-state";
 import type { AgentOutputManager } from "../task/output-manager";
 import type { DiscoverableTool, DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
 import type { EventBus } from "../utils/event-bus";
@@ -48,6 +50,7 @@ export * from "./resolve";
 export * from "./review";
 export * from "./search";
 export * from "./search-tool-bm25";
+export * from "./skill";
 export * from "./ssh";
 export * from "./subagent";
 export * from "./todo-write";
@@ -77,6 +80,12 @@ export interface ToolSession {
     workspaceTree?: WorkspaceTree;
     /** Pre-loaded skills */
     skills?: Skill[];
+    /** Currently executing skill prompt, when this tool session is inside one. */
+    getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;
+    /** Get the active skill prompt's current phase so the skill tool can apply
+     *  its terminal-phase chain guard. Returns the raw phase string or undefined
+     *  when no active skill (or accessor) is available. */
+    getActiveSkillPhase?: () => string | undefined;
     /** Pre-loaded prompt templates */
     promptTemplates?: PromptTemplate[];
     /** Whether LSP integrations are enabled */
@@ -122,6 +131,8 @@ export interface ToolSession {
     getSessionSpawns: () => string | null;
     /** Get resolved model string if explicitly set for this session */
     getModelString?: () => string | undefined;
+    /** Current model, when selected. */
+    model?: Model;
     /** Get the current session model string, regardless of how it was chosen */
     getActiveModelString?: () => string | undefined;
     /** Auth storage for passing to subagents (avoids re-discovery) */
@@ -204,9 +215,17 @@ export interface ToolSession {
     conflictHistory?: import("./conflict-detect").ConflictHistory;
     /** Queue a hidden message to be injected at the next agent turn. */
     queueDeferredMessage?(message: CustomMessage): void;
+    /** Dispatch a custom message through the active session. Used by the `skill`
+     *  tool to dispatch another skill prompt same-turn after recording a handoff. */
+    sendCustomMessage?(message: Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
     /** Get the active OpenTelemetry config so subagent dispatch can forward
      *  the parent's tracer/hooks with the subagent's own identity stamped. */
     getTelemetry?: () => AgentTelemetryConfig | undefined;
+    /** Build a sanitized fork-context seed for task subagents. */
+    buildForkContextSeed?: (options: ForkContextSeedOptions) => Promise<ForkContextSeed>;
 }
 export type ToolFactory = (session: ToolSession) => Tool | null | Promise<Tool | null>;
 export type BuiltinToolLoadMode = "essential" | "discoverable";

package/dist/types/tools/skill.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Skill Tool — agent-initiated skill chaining.
+ *
+ * Lets the agent hand off to another available skill in the current turn. The
+ * callee's SKILL.md is dispatched through the same custom-message path used by
+ * `/skill:<name>` typing, as a user-attribution message delivered same-turn
+ * (without `deliverAs: "nextTurn"`). Before dispatch, the tool calls
+ * `gjc state <caller> handoff --to <callee>` in-process via the state-runtime
+ * function so caller and callee mode-states plus `skill-active-state.json`
+ * transition atomically.
+ *
+ * Chaining is refused unless the caller's `current_phase` is in
+ * `{complete, completed, handoff, failed, cancelled, canceled, inactive}`. The
+ * agent declares readiness either by writing `current_phase: "handoff"` to its
+ * mode-state or by running the handoff verb directly.
+ */
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import * as z from "zod/v4";
+import type { ToolSession } from ".";
+declare const skillSchema: z.ZodObject<{
+    name: z.ZodString;
+    args: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type SkillToolInput = z.infer<typeof skillSchema>;
+export interface SkillToolDetails {
+    name: string;
+    path: string;
+    args?: string;
+    lineCount: number;
+}
+export declare class SkillTool implements AgentTool<typeof skillSchema, SkillToolDetails> {
+    #private;
+    readonly name = "skill";
+    readonly label = "Skill";
+    readonly summary = "Chain into another available skill in the current turn";
+    readonly loadMode = "discoverable";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        name: z.ZodString;
+        args: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly strict = true;
+    constructor(session: ToolSession);
+    static createIf(session: ToolSession): SkillTool | null;
+    execute(_toolCallId: string, input: SkillToolInput, signal?: AbortSignal): Promise<AgentToolResult<SkillToolDetails>>;
+}
+export {};

package/dist/types/utils/changelog.d.ts

@@ -5,10 +5,26 @@ export interface ChangelogEntry {
     content: string;
 }
 /**
- * Parse changelog entries from CHANGELOG.md
- * Scans for ## lines and collects content until next ## or EOF
+ * Parse changelog entries from a CHANGELOG.md text body.
+ * Scans for ## lines and collects content until next ## or EOF.
+ * Pure and synchronous so it can be reused by the embedded display path.
+ */
+export declare function parseChangelogContent(content: string): ChangelogEntry[];
+/**
+ * Parse changelog entries from a CHANGELOG.md file on disk.
+ * Returns [] on ENOENT; logs and returns [] on other read/parse errors.
  */
 export declare function parseChangelog(changelogPath: string): Promise<ChangelogEntry[]>;
+/**
+ * Return changelog entries from the CHANGELOG.md that shipped with this binary.
+ *
+ * The text is embedded at build time via `with { type: "text" }`, so the
+ * displayed changelog is deterministic across compiled binaries, source-tree
+ * dev runs, and `GJC_PACKAGE_DIR` / `PI_PACKAGE_DIR` overrides (which scope to
+ * optional package assets like docs/examples and do not influence the
+ * binary-identity changelog).
+ */
+export declare function getDisplayChangelogEntries(): ChangelogEntry[];
 /**
  * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
  */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -48,12 +48,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.2.2",
-		"@gajae-code/agent-core": "0.2.2",
-		"@gajae-code/ai": "0.2.2",
-		"@gajae-code/natives": "0.2.2",
-		"@gajae-code/tui": "0.2.2",
-		"@gajae-code/utils": "0.2.2",
+		"@gajae-code/stats": "0.2.3",
+		"@gajae-code/agent-core": "0.2.3",
+		"@gajae-code/ai": "0.2.3",
+		"@gajae-code/natives": "0.2.3",
+		"@gajae-code/tui": "0.2.3",
+		"@gajae-code/utils": "0.2.3",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/src/cli/setup-cli.ts

@@ -16,6 +16,7 @@ import {
 import { theme } from "../modes/theme/theme";
 import {
 	addApiCompatibleProvider,
+	formatProviderPresetList,
 	formatProviderSetupResult,
 	parseProviderCompatibility,
 } from "../setup/provider-onboarding";
@@ -28,6 +29,7 @@ export interface SetupCommandArgs {
 		json?: boolean;
 		check?: boolean;
 		force?: boolean;
+		preset?: string;
 		compat?: string;
 		provider?: string;
 		baseUrl?: string;
@@ -42,6 +44,7 @@ const VALID_COMPONENTS: SetupComponent[] = ["defaults", "hooks", "provider", "py
 function hasProviderSetupFlags(flags: SetupCommandArgs["flags"]): boolean {
 	return (
 		flags.compat !== undefined ||
+		flags.preset !== undefined ||
 		flags.provider !== undefined ||
 		flags.baseUrl !== undefined ||
 		flags.apiKeyEnv !== undefined ||
@@ -57,7 +60,7 @@ function rejectProviderFlagsOutsideProvider(component: SetupComponent, flags: Se
 	console.error(chalk.red("Provider setup flags require the explicit `provider` component."));
 	console.error(
 		chalk.dim(
-			`Run: ${APP_NAME} setup provider --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <id>`,
+			`Run: ${APP_NAME} setup provider --preset <minimax|glm> or ${APP_NAME} setup provider --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <id>`,
 		),
 	);
 	process.exit(1);
@@ -87,6 +90,8 @@ export function parseSetupArgs(args: string[]): SetupCommandArgs | undefined {
 			flags.force = true;
 		} else if (arg === "--compat") {
 			flags.compat = args[++i];
+		} else if (arg === "--preset") {
+			flags.preset = args[++i];
 		} else if (arg === "--provider") {
 			flags.provider = args[++i];
 		} else if (arg === "--base-url") {
@@ -190,6 +195,7 @@ export async function runSetupCommand(cmd: SetupCommandArgs): Promise<void> {
 async function handleProviderSetup(flags: {
 	json?: boolean;
 	force?: boolean;
+	preset?: string;
 	compat?: string;
 	provider?: string;
 	baseUrl?: string;
@@ -199,20 +205,25 @@ async function handleProviderSetup(flags: {
 }): Promise<void> {
 	try {
 		const missing: string[] = [];
-		if (!flags.compat) missing.push("--compat");
-		if (!flags.provider) missing.push("--provider");
-		if (!flags.baseUrl) missing.push("--base-url");
-		if (!flags.apiKeyEnv) missing.push("--api-key-env");
-		if (!flags.model || flags.model.length === 0) missing.push("--model");
+		if (!flags.preset) {
+			if (!flags.compat) missing.push("--compat");
+			if (!flags.provider) missing.push("--provider");
+			if (!flags.baseUrl) missing.push("--base-url");
+			if (!flags.apiKeyEnv) missing.push("--api-key-env");
+			if (!flags.model || flags.model.length === 0) missing.push("--model");
+		}
 		if (missing.length > 0) {
-			throw new Error(`Missing required provider setup option(s): ${missing.join(", ")}`);
+			throw new Error(
+				`Missing required provider setup option(s): ${missing.join(", ")}. Or use --preset <preset>.\nAvailable presets:\n${formatProviderPresetList()}`,
+			);
 		}
 		const result = await addApiCompatibleProvider({
-			compatibility: parseProviderCompatibility(flags.compat!),
-			providerId: flags.provider!,
-			baseUrl: flags.baseUrl!,
+			compatibility: flags.compat ? parseProviderCompatibility(flags.compat) : undefined,
+			preset: flags.preset,
+			providerId: flags.provider,
+			baseUrl: flags.baseUrl,
 			apiKeyEnv: flags.apiKeyEnv,
-			models: flags.model!,
+			models: flags.model,
 			modelsPath: flags.modelsPath,
 			force: flags.force,
 		});
@@ -400,18 +411,21 @@ ${chalk.bold("Usage:")}
 ${chalk.bold("Components:")}
   defaults  Install bundled GJC default workflow skills (default)
   hooks     Optional: install GJC native Codex UserPromptSubmit/Stop skill-state hooks
-  provider  Optional: add an OpenAI-compatible or Anthropic-compatible API provider
+  provider  Optional: add a preset, OpenAI-compatible, or Anthropic-compatible API provider
   python    Optional: verify a Python 3 interpreter is reachable for code execution
   stt       Optional: install speech-to-text dependencies (openai-whisper, recording tools)
 
 
 ${chalk.bold("Provider example:")}
+  ${APP_NAME} setup provider --preset minimax
+  ${APP_NAME} setup provider --preset glm
   MY_PROVIDER_KEY=sk-... ${APP_NAME} setup provider --compat openai --provider my-oai --base-url https://api.example.com/v1 --api-key-env MY_PROVIDER_KEY --model gpt-example
 
 ${chalk.bold("Options:")}
   -c, --check       Check if dependencies are installed without installing
   -f, --force       Overwrite existing default workflow skill files
   --json            Output status as JSON
+  --preset          Provider preset: minimax, minimax-cn, or glm (aliases include minimax-code and zai)
   --compat          Provider compatibility: openai or anthropic
   --provider        Provider id to add to models.yml
   --base-url        Provider API base URL

package/src/cli.ts

@@ -44,6 +44,7 @@ const commands: CommandEntry[] = [
 		load: () => import("./commands/contribution-prep").then(m => m.default),
 	},
 	{ name: "deep-interview", load: () => import("./commands/deep-interview").then(m => m.default) },
+	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
 ];
 

package/src/commands/deep-interview.ts

@@ -1,10 +1,33 @@
-import { Command } from "@gajae-code/utils/cli";
+import { Command, Flags } from "@gajae-code/utils/cli";
 import { runNativeDeepInterviewCommand } from "../gjc-runtime/deep-interview-runtime";
 
 export default class DeepInterview extends Command {
 	static description = "Run native GJC deep-interview workflow";
 	static strict = false;
-	static examples = ['$ gjc deep-interview --standard "<idea>"'];
+	static flags = {
+		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
+		standard: Flags.boolean({ description: "Seed a standard deep-interview run" }),
+		deep: Flags.boolean({ description: "Seed a deep deep-interview run" }),
+		threshold: Flags.string({ description: "Override ambiguity threshold for kickoff" }),
+		"threshold-source": Flags.string({ description: "Describe the threshold override source" }),
+		"session-id": Flags.string({
+			description: "Route state/spec handoff through a session-scoped .gjc state directory",
+		}),
+		write: Flags.boolean({ description: "Persist a final deep-interview spec through the sanctioned GJC CLI/API" }),
+		stage: Flags.string({ description: 'Spec stage for --write (currently "final")' }),
+		slug: Flags.string({ description: "Safe slug for .gjc/specs/deep-interview-<slug>.md" }),
+		spec: Flags.string({ description: "Final spec markdown or a path to the final spec markdown" }),
+		handoff: Flags.string({ description: 'After --write, hand off to a workflow target (currently "ralplan")' }),
+		deliberate: Flags.boolean({
+			description: "Shortcut for --write handoff to ralplan in deliberate consensus mode",
+		}),
+		json: Flags.boolean({ description: "Output JSON" }),
+	};
+	static examples = [
+		'$ gjc deep-interview --standard "<idea>"',
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
+		"$ gjc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
+	];
 
 	async run(): Promise<void> {
 		const result = await runNativeDeepInterviewCommand(this.argv, process.cwd());

package/src/commands/setup.ts

@@ -22,6 +22,7 @@ export default class Setup extends Command {
 		check: Flags.boolean({ char: "c", description: "Check if dependencies are installed" }),
 		force: Flags.boolean({ char: "f", description: "Overwrite existing default workflow skill files" }),
 		json: Flags.boolean({ description: "Output status as JSON" }),
+		preset: Flags.string({ description: "Provider preset: minimax, minimax-cn, or glm" }),
 		compat: Flags.string({ description: "Provider compatibility: openai or anthropic" }),
 		provider: Flags.string({ description: "Provider id to add to models.yml" }),
 		"base-url": Flags.string({ description: "Provider API base URL" }),
@@ -38,6 +39,7 @@ export default class Setup extends Command {
 				json: flags.json,
 				check: flags.check,
 				force: flags.force,
+				preset: flags.preset,
 				compat: flags.compat,
 				provider: flags.provider,
 				baseUrl: flags["base-url"],

package/src/commands/state.ts

@@ -11,6 +11,7 @@ export default class State extends Command {
 		"$ gjc state deep-interview read --json",
 		'$ gjc state ralplan write --input \'{"phase":"approval","active":true}\' --json',
 		"$ gjc state team contract",
+		"$ gjc state deep-interview handoff --to ralplan --json",
 	];
 
 	async run(): Promise<void> {

package/src/config/settings-schema.ts

@@ -1940,6 +1940,16 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"skill.enabled": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "tools",
+			label: "Skill",
+			description: "Enable the skill tool so the agent can chain into another available skill on its next turn",
+		},
+	},
+
 	// Fetching and browser
 	"fetch.enabled": {
 		type: "boolean",
@@ -2344,6 +2354,37 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"task.forkContext.enabled": {
+		type: "boolean",
+		default: false,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context for Subagents",
+			description:
+				"Allow explicitly opted-in subagents to start from a sanitized snapshot of parent context when both the agent and task item also opt in.",
+		},
+	},
+
+	"task.forkContext.maxMessages": {
+		type: "number",
+		default: 50,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context Max Messages",
+			description: "Maximum parent messages copied into an explicitly opted-in subagent fork-context seed.",
+		},
+	},
+
+	"task.forkContext.maxTokens": {
+		type: "number",
+		default: 0,
+		ui: {
+			tab: "tasks",
+			label: "Fork Context Max Tokens",
+			description: "Approximate token cap for fork-context seeds. 0 uses 25% of the target model context window.",
+		},
+	},
+
 	"task.maxRecursionDepth": {
 		type: "number",
 		default: 2,

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -389,8 +389,9 @@ When ambiguity ≤ threshold (or hard cap / early exit):
 1. **Generate the specification** using opus model with the prompt-safe transcript. If the full interview transcript or initial context is too large, include the summary plus all concrete decisions, acceptance criteria, unresolved gaps, and ontology snapshots; never overflow the prompt with raw oversized context.
 2. **Write the final spec through the workflow CLI**: persist the artifact at `.gjc/specs/deep-interview-{slug}.md`
    - Always use this exact final spec path. Do not write temporary working files to the repo root or other ad hoc paths; repos may allowlist `.gjc/` for planning artifacts while protecting product branches.
-   - Use the GJC workflow/state CLI for artifact and state persistence; direct `.gjc/` file edits are forbidden unless an explicit force override is active.
+   - Use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> [--json]` for artifact and state persistence; direct `.gjc/` file edits are forbidden unless an explicit force override is active.
    - Persist the final `spec_path` in state when available so downstream skills and resumed sessions can pass the artifact path explicitly.
+   - If the user preselected the deliberate ralplan path, use the native deep-interview write command with `--write --stage final --slug {slug} --spec <markdown-or-path> --deliberate [--json]` so the final spec is persisted before deep-interview hands off to ralplan.
 
 Spec structure:
 
@@ -515,6 +516,23 @@ After the spec is written, mark it `pending approval` and present execution opti
 
 **IMPORTANT:** On explicit execution selection, **MUST** use the chosen bundled GJC workflow skill entrypoint (`/skill:ralplan` or `/skill:team`) inside the agent session. `gjc ralplan` is a native CLI that accepts the documented skill flags and seeds local `.gjc/state` receipts; agent sessions should still drive the consensus loop through `/skill:ralplan`. `gjc team` is a native tmux runtime command and may be used only when the Team workflow explicitly requires the CLI runtime. Do NOT implement directly. The deep-interview agent is a requirements agent, not an execution agent. If oversized initial context was summarized, pass the spec and prompt-safe summary forward, not the raw oversized source material. Without explicit execution selection, stop with the spec marked `pending approval`.
 
+### Phase 5b: Handoff before chain
+
+Before invoking `/skill:ralplan`, `/skill:team`, or `/skill:ultragoal`, the final spec must already be persisted through the native deep-interview write command. For ordinary user-selected handoff, mark deep-interview ready for the skill tool's chain guard:
+
+```
+gjc state deep-interview write --input '{"current_phase":"handoff"}' --json
+```
+
+For a preselected deliberate ralplan path, prefer the single sanctioned bridge command instead:
+
+```
+gjc \
+deep-interview --write --stage final --slug {slug} --spec <markdown-or-path> --deliberate --json
+```
+
+That command persists `.gjc/specs/deep-interview-{slug}.md`, seeds ralplan in deliberate mode, and performs the safe deep-interview → ralplan state handoff. Skipping spec persistence leaves the Phase 5 chain blocked by design.
+
 ### Approval-Gated Refinement Path (Recommended)
 
 ```

package/src/defaults/gjc/skills/ralplan/SKILL.md

@@ -72,6 +72,14 @@ The consensus workflow:
 7. *(--interactive only)* User chooses: Approve team execution, Request changes, or Reject
 8. *(--interactive only)* On approval: invoke `/skill:team` for execution -- never implement directly
 
+   Before invoking `/skill:team` or `/skill:ultragoal`, mark ralplan ready for handoff so the skill tool's chain guard permits the transition:
+
+   ```
+   gjc state ralplan write --input '{"current_phase":"handoff"}' --json
+   ```
+
+   The skill tool then dispatches the execution skill same-turn and runs `gjc state ralplan handoff --to <team|ultragoal> --json` in-process to atomically demote ralplan, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+
 > **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent Task calls in the same parallel batch. Always await the Architect result before issuing the Critic Task.
 
 Follow the Plan skill's full documentation for consensus mode details.

package/src/defaults/gjc/skills/team/SKILL.md

@@ -394,3 +394,13 @@ Two cleanup paths exist and must not be confused:
 **Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.
 
 **Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification/evidence is gathered.
+
+## Handoff back to planning or persistence
+
+When the team task-set completes OR the user requests return to planning/persistence, mark team ready for handoff so the skill tool's chain guard permits the transition:
+
+```
+gjc state team write --input '{"current_phase":"handoff"}' --json
+```
+
+The skill tool then dispatches `/skill:ralplan`, `/skill:deep-interview`, or `/skill:ultragoal` same-turn and runs `gjc state team handoff --to <ralplan|deep-interview|ultragoal> --json` in-process to atomically demote team, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -192,6 +192,16 @@ Receipts are freshness-scoped:
 - Normal later `goal_started` or clean receipt-backed `goal_checkpointed` events for other goals do not stale older per-goal receipts.
 - Appending required goals or changing final required-goal state stales final aggregate receipts. Final aggregate completion requires a fresh final aggregate receipt proving no incomplete, blocked, or `review_blocked` required goals remain.
 
+## Handoff back to planning
+
+When the aggregate ultragoal is complete OR the user requests return to planning/clarification, mark ultragoal ready for handoff so the skill tool's chain guard permits the backward transition:
+
+```
+gjc state ultragoal write --input '{"current_phase":"handoff"}' --json
+```
+
+The skill tool then dispatches `/skill:ralplan` or `/skill:deep-interview` same-turn and runs `gjc state ultragoal handoff --to <ralplan|deep-interview> --json` in-process to atomically demote ultragoal, promote the callee, and sync both `skill-active-state.json` files. You do not need to run the handoff verb yourself.
+
 ## Constraints
 
 - The shell command cannot directly invoke interactive `/goal`; it emits a model-facing handoff for the active GJC agent.

package/src/discovery/helpers.ts

@@ -8,6 +8,7 @@ import {
 	getConfigDirName,
 	getPluginsDir,
 	getProjectDir,
+	logger,
 	parseFrontmatter,
 	tryParseJson,
 } from "@gajae-code/utils";
@@ -16,6 +17,7 @@ import { invalidate as invalidateFsCache, readDirEntries, readFile } from "../ca
 import { parseRuleConditionAndScope, type Rule, type RuleFrontmatter } from "../capability/rule";
 import type { Skill, SkillFrontmatter } from "../capability/skill";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import type { ForkContextPolicy } from "../task/types";
 import { parseThinkingLevel } from "../thinking";
 
 import { buildPluginDirRoot } from "./plugin-dir-roots";
@@ -214,6 +216,7 @@ export interface ParsedAgentFields {
 	autoloadSkills?: string[];
 	blocking?: boolean;
 	hide?: boolean;
+	forkContext?: ForkContextPolicy;
 }
 
 /**
@@ -267,10 +270,30 @@ export function parseAgentFields(frontmatter: Record<string, unknown>): ParsedAg
 	const model = parseModelList(frontmatter.model);
 	const blocking = parseBoolean(frontmatter.blocking);
 	const hide = parseBoolean(frontmatter.hide);
+	const forkContext = parseForkContextPolicy(frontmatter.forkContext);
 	const autoloadSkills = parseArrayOrCSV(frontmatter.autoloadSkills)
 		?.map(s => s.trim())
 		.filter(Boolean);
-	return { name, description, tools, spawns, model, output, thinkingLevel, blocking, autoloadSkills, hide };
+	return {
+		name,
+		description,
+		tools,
+		spawns,
+		model,
+		output,
+		thinkingLevel,
+		blocking,
+		autoloadSkills,
+		hide,
+		forkContext,
+	};
+}
+
+function parseForkContextPolicy(value: unknown): ForkContextPolicy | undefined {
+	if (value === undefined) return undefined;
+	if (value === "forbidden" || value === "allowed") return value;
+	logger.warn("Invalid agent forkContext frontmatter; expected 'allowed' or 'forbidden', ignoring", { value });
+	return undefined;
 }
 
 async function globIf(

package/src/extensibility/extensions/types.ts

@@ -110,6 +110,12 @@ export interface ExtensionUIDialogOptions {
 	onExternalEditor?: () => void;
 	/** Optional footer hint text rendered by interactive selector */
 	helpText?: string;
+	/**
+	 * For interactive TUI select dialogs, render the focused option across
+	 * multiple rows instead of truncating it. This is a select-only rendering
+	 * hint; non-TUI bridges (RPC, ACP) drop it and do not serialize it.
+	 */
+	wrapFocused?: boolean;
 }
 
 /** Raw terminal input listener for extensions. */