@gajae-code/coding-agent 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [0.4.5] - 2026-06-12
+
+### Added
+
+- Added a dim `(ctrl+s to observe sessions)` discoverability hint under the `subagent` await panel header while any awaited subagent is still running, pointing to the full session observer overlay; the hint shows in both collapsed and expanded states and disappears once no subagent is running.
+- Added a `phase-rollup` receipt family (receipt-of-receipts) to the harness control plane: a hash-sealed rollup that supersedes N child task receipts at a lifecycle boundary, preserving per-child `{id, status, outputUri, outputSha256, receiptSha256, tokens, costTotal, clonedTokens, lowRoi}` pointers plus aggregate ROI totals, with a pure deterministic builder (`buildPhaseRollupReceipt`) and fail-closed semantic validation.
+- Added a pure receipt-ingestion fast path (`ingestReceipts`): fail-closed batch validation + lifecycle transition computation via the existing state machine, plus a deterministic model-facing digest hard-capped at 280 chars — groundwork for LLM-free receipt routing.
+- Added advisory spawn-ROI reconciliation (`reconcileSpawnRoi`) and deterministic fork-context mode advice (`adviseForkContextMode`) surfaced in task receipts without changing task success semantics.
+- Added the Grok Build provider contract design document.
+
+### Changed
+
+- Reduced compiled CLI startup and native bundle pressure with default-small grammar loading, tokenizer tiering, and compiled fast-help paths.
+- Preserved dev/main release metadata and changelog consistency for the 0.4.5 lockstep release.
+
+### Fixed
+
+- Kept the unified `goal` tool registered and active by default whenever `goal.enabled` is true, including explicit tool subsets and `gjc ultragoal create-goals` arming flows.
+- Restored no-argument `gjc` interactive startup instead of launching help.
+- Rendered and executed Cursor-native tool calls, including detached/native handler paths and empty-pattern composer grep guards.
+- Tool-output pruning no longer rewrites already-sent provider-facing history mid prompt-cache epoch and now persists pruned message updates back into canonical session storage.
+- Preserved provider abort root causes in the final TUI abort label, kept replay rendering idempotent, and added a `PI_STREAM_IDLE_TIMEOUT_MS` remediation hint when stream idle watchdogs fire.
+- Hardened harness owner recovery/finalize paths and submit-prompt-file handling.
+
+## [0.4.4] - 2026-06-10
+
+### Added
+
+- Made coordinator turns event-backed, adding an MCP coordinator server and the `gjc coordinator` / `gjc mcp-serve` commands backed by durable turn/session state (#479).
+- Surfaced awaited sub-agent live streaming status in the await panel (#475).
+
+### Changed
+
+- Refreshed the README brand images (#477).
+
+### Fixed
+
+- Persisted ralplan role-agent artifacts via the CLI, returning receipt-only output to the caller (#474).
+- Collected the `ask` tool "Other" custom input inline below the option list (#476).
+
 ## [0.4.3] - 2026-06-10
 
 ### Added

package/dist/types/cli/fast-help.d.ts

@@ -0,0 +1 @@
+export declare function getExtraHelpText(): string;

package/dist/types/cli/setup-cli.d.ts

@@ -18,6 +18,8 @@ export interface SetupCommandArgs {
         repo?: string;
         profile?: string;
         sessionCommand?: string;
+        noWorktree?: boolean;
+        worktreeName?: string;
         stateRoot?: string;
         mutation?: string[];
         artifactByteCap?: string;

package/dist/types/commands/harness.d.ts

@@ -14,6 +14,9 @@ export default class Harness extends Command {
             description: string;
             default: string;
         };
+        "prompt-file": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
         session: import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             char: string;
             description: string;

package/dist/types/commands/setup.d.ts

@@ -43,6 +43,12 @@ export default class Setup extends Command {
         "session-command": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };
+        "no-worktree": import("@gajae-code/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        "worktree-name": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
         "state-root": import("@gajae-code/utils/cli").FlagDescriptor<"string"> & {
             description: string;
         };

package/dist/types/config/model-registry.d.ts

@@ -70,6 +70,7 @@ export declare const ModelsConfigFile: ConfigFile<{
             allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
             requiresAssistantContentForToolCalls?: boolean | undefined;
             supportsToolChoice?: boolean | undefined;
+            supportsForcedToolChoice?: boolean | undefined;
             disableReasoningOnForcedToolChoice?: boolean | undefined;
             disableReasoningOnToolChoice?: boolean | undefined;
             thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
@@ -145,6 +146,7 @@ export declare const ModelsConfigFile: ConfigFile<{
                 allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
                 requiresAssistantContentForToolCalls?: boolean | undefined;
                 supportsToolChoice?: boolean | undefined;
+                supportsForcedToolChoice?: boolean | undefined;
                 disableReasoningOnForcedToolChoice?: boolean | undefined;
                 disableReasoningOnToolChoice?: boolean | undefined;
                 thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;
@@ -216,6 +218,7 @@ export declare const ModelsConfigFile: ConfigFile<{
                 allowsSyntheticReasoningContentForToolCalls?: boolean | undefined;
                 requiresAssistantContentForToolCalls?: boolean | undefined;
                 supportsToolChoice?: boolean | undefined;
+                supportsForcedToolChoice?: boolean | undefined;
                 disableReasoningOnForcedToolChoice?: boolean | undefined;
                 disableReasoningOnToolChoice?: boolean | undefined;
                 thinkingFormat?: "openai" | "openrouter" | "qwen" | "qwen-chat-template" | "zai" | undefined;

package/dist/types/config/models-config-schema.d.ts

@@ -30,6 +30,7 @@ export declare const OpenAICompatSchema: z.ZodObject<{
     allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
     requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
     supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+    supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
     disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
     disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
     thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -182,6 +183,7 @@ export declare const ModelOverrideSchema: z.ZodObject<{
         allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
         requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
         supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+        supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
         disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
         disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
         thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -288,6 +290,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
             allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
             requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
             supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+            supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
             disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
             disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
             thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -442,6 +445,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
                 allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+                supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
                 thinkingFormat: z.ZodOptional<z.ZodEnum<{
@@ -575,6 +579,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
                 allowsSyntheticReasoningContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 requiresAssistantContentForToolCalls: z.ZodOptional<z.ZodBoolean>;
                 supportsToolChoice: z.ZodOptional<z.ZodBoolean>;
+                supportsForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnForcedToolChoice: z.ZodOptional<z.ZodBoolean>;
                 disableReasoningOnToolChoice: z.ZodOptional<z.ZodBoolean>;
                 thinkingFormat: z.ZodOptional<z.ZodEnum<{

package/dist/types/coordinator/contract.d.ts

@@ -1,4 +1,4 @@
 export declare const COORDINATOR_MCP_PROTOCOL_VERSION = "2024-11-05";
 export declare const COORDINATOR_MCP_SERVER_NAME = "gjc-coordinator-mcp";
-export declare const COORDINATOR_MCP_TOOL_NAMES: readonly ["gjc_coordinator_list_sessions", "gjc_coordinator_read_status", "gjc_coordinator_read_tail", "gjc_coordinator_list_questions", "gjc_coordinator_list_artifacts", "gjc_coordinator_read_artifact", "gjc_coordinator_read_coordination_status", "gjc_coordinator_start_session", "gjc_coordinator_send_prompt", "gjc_coordinator_submit_question_answer", "gjc_coordinator_read_turn", "gjc_coordinator_await_turn", "gjc_coordinator_report_status"];
+export declare const COORDINATOR_MCP_TOOL_NAMES: readonly ["gjc_coordinator_list_sessions", "gjc_coordinator_read_status", "gjc_coordinator_read_tail", "gjc_coordinator_list_questions", "gjc_coordinator_list_artifacts", "gjc_coordinator_read_artifact", "gjc_coordinator_read_coordination_status", "gjc_coordinator_register_session", "gjc_coordinator_start_session", "gjc_coordinator_send_prompt", "gjc_coordinator_submit_question_answer", "gjc_coordinator_read_turn", "gjc_coordinator_await_turn", "gjc_coordinator_report_status"];
 export type CoordinatorToolName = (typeof COORDINATOR_MCP_TOOL_NAMES)[number];

package/dist/types/coordinator-mcp/server.d.ts

@@ -8,10 +8,11 @@ interface JsonRpcRequest {
     method: string;
     params?: unknown;
 }
+type JsonRpcResult = any;
 interface JsonRpcResponse {
     jsonrpc: "2.0";
     id: string | number | null;
-    result?: any;
+    result?: JsonRpcResult;
     error?: {
         code: number;
         message: string;
@@ -30,6 +31,11 @@ interface SessionStartInput {
 interface CoordinatorServices {
     listSessions?: () => unknown[] | Promise<unknown[]>;
     startSession?: (input: SessionStartInput) => unknown | Promise<unknown>;
+    commandRunner?: (command: string[]) => Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
 }
 interface CoordinatorMcpServerOptions {
     env?: NodeJS.ProcessEnv;
@@ -48,5 +54,5 @@ export declare function createCoordinatorMcpServer(options?: CoordinatorMcpServe
     handleJsonRpc: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
     handle: (request: JsonRpcRequest) => Promise<JsonRpcResponse>;
 };
-export declare function handleCoordinatorMcpRequest(request: JsonRpcRequest, options?: LegacyHandlerOptions): Promise<any>;
+export declare function handleCoordinatorMcpRequest(request: JsonRpcRequest, options?: LegacyHandlerOptions): Promise<JsonRpcResponse>;
 export declare function runCoordinatorMcpStdio(options?: CoordinatorMcpServerOptions): Promise<void>;

package/dist/types/harness-control-plane/finalize.d.ts

@@ -30,6 +30,11 @@ export interface FinalizeOptions {
     reviewOnly?: boolean;
     /** Operator/loop-supplied terminal review verdict (closed vocabulary). */
     verdict?: string | null;
+    /**
+     * Final assistant text from the live RPC owner, used to extract a closed-vocabulary verdict
+     * for review-only sessions when no explicit {@link verdict} is supplied. Never persisted raw.
+     */
+    assistantText?: string | null;
     /** Bounded PR/issue reference for the review target (e.g. "PR-414"). Never resolved from the live repo. */
     prTarget?: string | null;
     validationCommands?: ValidationCommandSpec[];

package/dist/types/harness-control-plane/phase-rollup.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Phase-boundary receipt rollup builder (receipt-of-receipts).
+ *
+ * At a harness lifecycle boundary, N child task receipts can be superseded by a
+ * single `phase-rollup` receipt that preserves per-child pointers (id, status,
+ * outputRef, sha256) plus aggregate ROI totals. The rollup is hash-sealed via
+ * the standard receipt envelope and validated fail-closed like every other
+ * family (see `validatePhaseRollup` in receipts.ts). Pure builder — no runtime
+ * injection behavior is changed here.
+ */
+import type { TaskResultReceipt } from "../task/receipt";
+import { type BuildReceiptInput, type PhaseRollupEvidence, type ReceiptEnvelope } from "./receipts";
+export interface BuildPhaseRollupInput {
+    receiptId: string;
+    sessionId: string;
+    source: string;
+    subject: BuildReceiptInput<PhaseRollupEvidence>["subject"];
+    phase: string;
+    children: readonly TaskResultReceipt[];
+    /** Supply for deterministic output; defaults to now. */
+    createdAt?: string;
+}
+export declare function buildPhaseRollupReceipt(input: BuildPhaseRollupInput): ReceiptEnvelope<PhaseRollupEvidence>;

package/dist/types/harness-control-plane/receipt-ingest.d.ts

@@ -0,0 +1,19 @@
+import type { ReceiptEnvelope } from "./receipts";
+import type { HarnessLifecycle, ReceiptFamily, SessionState } from "./types";
+export declare const RECEIPT_DIGEST_MAX_CHARS = 280;
+export declare const RECEIPT_FAMILY_LIFECYCLE_TARGETS: Partial<Record<ReceiptFamily, HarnessLifecycle>>;
+export interface ReceiptIngestResult {
+    accepted: ReceiptEnvelope<unknown>[];
+    rejected: {
+        receipt: ReceiptEnvelope<unknown>;
+        reasons: string[];
+    }[];
+    transitions: {
+        from: HarnessLifecycle;
+        to: HarnessLifecycle;
+        receiptId: string;
+    }[];
+    finalLifecycle: HarnessLifecycle;
+    digest: string;
+}
+export declare function ingestReceipts(state: SessionState, receipts: readonly ReceiptEnvelope<unknown>[]): ReceiptIngestResult;

package/dist/types/harness-control-plane/receipts.d.ts

@@ -20,6 +20,8 @@ export interface ReceiptEnvelope<E = Record<string, unknown>> {
     sha256: string;
 }
 export declare const RECEIPT_SCHEMA_VERSION: 1;
+/** Deterministic stringify with sorted keys (stable hash basis). */
+export declare function canonicalJson(value: unknown): string;
 export declare function sha256Hex(input: string): string;
 export interface BuildReceiptInput<E> {
     receiptId: string;
@@ -90,6 +92,10 @@ export interface ReviewVerdictEvidence {
     finalizedAt: string;
     /** Bounded summary code/reference for the verdict; never raw assistant text. */
     summaryRef: string | null;
+    /** Where the verdict came from: explicit operator input or extracted from final assistant text. */
+    verdictSource?: "input" | "assistant";
+    /** sha256 of the assistant text the verdict was extracted from, when sourced from the agent. */
+    assistantDigest?: string | null;
 }
 export interface ReviewFailureEvidence {
     /** Machine-actionable reason the review produced no terminal verdict. */
@@ -98,6 +104,46 @@ export interface ReviewFailureEvidence {
     failedAt: string;
     /** Routing hint for the operator/fallback path. */
     fallback: string;
+    /** sha256 of the assistant text examined for a verdict, when one was available. */
+    assistantDigest?: string | null;
+    /** Bounded, whitespace-collapsed assistant summary (never an unbounded transcript dump). */
+    assistantSummary?: string | null;
 }
+/** Pointer back to one superseded child task receipt. */
+export interface PhaseRollupChildPointer {
+    id: string;
+    status: "completed" | "failed" | "aborted" | "merge_failed" | "paused";
+    /** Artifact URI holding the child's full output, when available. */
+    outputUri: string | null;
+    /** Content hash of the child's output artifact, when available. */
+    outputSha256: string | null;
+    /** Hash of the child receipt itself (canonical JSON), for staleness checks. */
+    receiptSha256: string;
+    /**
+     * Per-child ROI accounting carried into the rollup so the aggregate totals
+     * below are recomputable/verifiable from child evidence (not self-reported).
+     * `tokens` is the child's effective token count; cost/cloned are null when
+     * the child reported no such accounting.
+     */
+    tokens: number;
+    costTotal: number | null;
+    clonedTokens: number | null;
+    lowRoi: boolean;
+}
+export interface PhaseRollupEvidence {
+    /** Harness lifecycle boundary this rollup was emitted at. */
+    phase: string;
+    children: PhaseRollupChildPointer[];
+    aggregate: {
+        childCount: number;
+        completed: number;
+        failed: number;
+        totalTokens: number;
+        totalCostTotal: number | null;
+        totalClonedTokens: number | null;
+        lowRoiChildIds: string[];
+    };
+}
+export declare function validatePhaseRollup(e: PhaseRollupEvidence): string[];
 /** Classifications that MUST have a valid `vanish` receipt before the action proceeds. */
 export declare function requiresVanishBeforeAction(classification: RecoveryClassification): boolean;

package/dist/types/harness-control-plane/rpc-adapter.d.ts

@@ -24,6 +24,8 @@ export interface HarnessRpc {
     isLive?(): boolean;
     /** ISO timestamp of the last observed event frame, or null. */
     lastFrameAt?(): string | null;
+    /** Final assistant text from the live session (for review-verdict extraction); null when unavailable. */
+    getLastAssistantText?(): Promise<string | null>;
 }
 export interface AcceptanceResult {
     accepted: boolean;
@@ -54,6 +56,7 @@ export declare class GajaeCodeRpc implements HarnessRpc {
     isLive(): boolean;
     lastFrameAt(): string | null;
     getState(): Promise<RpcStateSnapshot>;
+    getLastAssistantText(): Promise<string | null>;
     sendPrompt(prompt: string): Promise<{
         commandId: string;
         ack: boolean;

package/dist/types/harness-control-plane/types.d.ts

@@ -16,6 +16,14 @@ export type SessionMode = "implement" | "review";
 export type ReviewVerdict = "APPROVE_MERGE_READY" | "REQUEST_CHANGES" | "OWNER_CONFIRMATION_REQUIRED";
 export declare const REVIEW_VERDICTS: readonly ReviewVerdict[];
 export declare function isReviewVerdict(value: unknown): value is ReviewVerdict;
+/**
+ * Extract a single closed-vocabulary review verdict from free-form assistant text.
+ *
+ * Scans for canonical verdict tokens (and accepted aliases) as whole words and returns the
+ * LAST occurrence — the agent's final stated decision wins over any earlier mention. Returns
+ * null when no allowed token is present, so the finalizer fails closed on a missing verdict.
+ */
+export declare function extractReviewVerdict(text: string | null | undefined): ReviewVerdict | null;
 /** Lifecycle states of an operated session. */
 export type HarnessLifecycle = "new" | "started" | "submitted" | "observing" | "recovering" | "validating" | "finalizing" | "completed" | "blocked" | "retired";
 /** Event severities emitted by the owner. */
@@ -27,7 +35,7 @@ export type RiskKind = "normal" | "prompt-not-accepted" | "deleted-worktree" | "
 /** Deterministic recovery classifications. */
 export type RecoveryClassification = "continue" | "send-enter" | "reinject-prompt" | "restart-clean" | "restart-preserve-delta" | "fallback-codex-exec" | "human-check";
 /** Receipt families persisted under the session storage dir. */
-export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure";
+export type ReceiptFamily = "vanish" | "prompt-acceptance" | "validation" | "completion" | "review-verdict" | "review-failure" | "phase-rollup";
 /** The CLI verbs / primitives exposed by `gjc harness <verb>`. */
 export type HarnessVerb = "start" | "submit" | "observe" | "classify" | "recover" | "validate" | "finalize" | "retire" | "events" | "monitor" | "operate";
 /** Submission transports. */

package/dist/types/main.d.ts

@@ -7,7 +7,7 @@
 import type { Args } from "./cli/args";
 import { ModelRegistry } from "./config/model-registry";
 import { Settings } from "./config/settings";
-import { InteractiveMode, runAcpMode } from "./modes";
+import type { InteractiveMode } from "./modes/interactive-mode";
 import type { SubmittedUserInput } from "./modes/types";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
@@ -51,7 +51,7 @@ export declare function createAcpSessionFactory(args: AcpSessionFactoryOptions):
 interface RunRootCommandDependencies {
     createAgentSession?: typeof createAgentSession;
     discoverAuthStorage?: typeof discoverAuthStorage;
-    runAcpMode?: typeof runAcpMode;
+    runAcpMode?: (createSession: AcpSessionFactory) => Promise<void>;
     settings?: Settings;
 }
 export declare function runRootCommand(parsed: Args, rawArgs: string[], deps?: RunRootCommandDependencies): Promise<void>;

package/dist/types/modes/utils/abort-message.d.ts

@@ -0,0 +1,4 @@
+export declare function buildAbortDisplayMessage({ errorMessage, retryAttempt }: {
+    errorMessage?: string;
+    retryAttempt: number;
+}): string;

package/dist/types/session/session-manager.d.ts

@@ -401,6 +401,14 @@ export declare class SessionManager {
     appendCompaction<T = unknown>(summary: string, shortSummary: string | undefined, firstKeptEntryId: string, tokensBefore: number, details?: T, fromExtension?: boolean, preserveData?: Record<string, unknown>): string;
     /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
     appendCustomEntry(customType: string, data?: unknown): string;
+    /**
+     * Write mutated message entries back into the canonical entry store by id.
+     *
+     * `getBranch()` materializes resident-blob entries into copies, so in-place
+     * mutation of returned entries (e.g. pruning tool outputs) does not affect
+     * the canonical store. This applies such mutations for real.
+     */
+    applyEntryMessageUpdates(entries: readonly SessionMessageEntry[]): void;
     /**
      * Rewrite the session file after in-place entry updates.
      * Use sparingly (e.g., pruning old tool outputs).

package/dist/types/setup/hermes-setup.d.ts

@@ -11,6 +11,8 @@ export interface HermesSetupFlags {
     repo?: string;
     profile?: string;
     sessionCommand?: string;
+    noWorktree?: boolean;
+    worktreeName?: string;
     stateRoot?: string;
     mutation?: string[];
     artifactByteCap?: string;
@@ -33,6 +35,11 @@ export interface CoordinatorSetupSpec {
         repo?: string;
     };
     sessionCommand?: string;
+    sessionCommandSource: "default" | "explicit";
+    worktree: {
+        enabled: boolean;
+        name?: string;
+    };
     stateRoot?: string;
     mutationPolicy: {
         classes: HermesMutationClass[];

package/dist/types/task/fork-context-advisory.d.ts

@@ -0,0 +1,13 @@
+import type { ForkContextMode } from "./types";
+export interface ForkContextAdvisory {
+    recommendedMode: ForkContextMode;
+    reasons: string[];
+    estimatedClonedTokens: Record<ForkContextMode, number>;
+    callerModeRespected: true;
+}
+export declare function adviseForkContextMode(input: {
+    assignment: string;
+    context?: string;
+    explicitMode?: ForkContextMode;
+    parentContextTokens?: number;
+}): ForkContextAdvisory;

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

@@ -56,6 +56,7 @@ export interface TaskResultReceipt {
     };
     extractedToolCounts?: Record<string, number>;
     forkContext?: SingleResult["forkContext"];
+    forkContextAdvisory?: SingleResult["forkContextAdvisory"];
     roi?: TaskRoi;
 }
 /**

package/dist/types/task/roi-reconciliation.d.ts

@@ -0,0 +1,27 @@
+import type { TaskResultReceipt } from "./receipt";
+import type { SpawnPlanReceipt } from "./spawn-gate";
+/**
+ * Pure, advisory-only reconciliation between a spawn plan's inline-token promise
+ * and receipt-safe child outputs. These signals never change task success/failure
+ * semantics or runtime behavior; they only describe budget/ROI observations for
+ * model-facing summaries.
+ */
+export interface SpawnRoiChildReconciliation {
+    id: string;
+    inlineTokens: number;
+    maxInlineTokens: number;
+    overBudget: boolean;
+    overageTokens: number;
+    lowRoi: boolean;
+}
+export interface SpawnRoiReconciliation {
+    childCount: number;
+    promisedMaxInlineTokens: number;
+    children: SpawnRoiChildReconciliation[];
+    overBudgetChildIds: string[];
+    lowRoiChildIds: string[];
+    totalInlineTokens: number;
+    totalOverageTokens: number;
+    advisoryFlags: string[];
+}
+export declare function reconcileSpawnRoi(plan: SpawnPlanReceipt | undefined, receipts: readonly TaskResultReceipt[]): SpawnRoiReconciliation | undefined;

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

@@ -2,6 +2,7 @@ import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Usage } from "@gajae-code/ai";
 import * as z from "zod/v4";
 import type { TaskResultReceipt } from "./receipt";
+import type { SpawnRoiReconciliation } from "./roi-reconciliation";
 import { type TaskSimpleMode } from "./simple-mode";
 import type { SpawnPlanReceipt } from "./spawn-gate";
 import type { NestedRepoPatch } from "./worktree";
@@ -413,6 +414,14 @@ export interface SingleResult {
         mode: ForkContextMode;
         clonedTokens: number;
     };
+    /**
+     * Advisory fork-context mode recommendation for this task (logged only;
+     * never changes the actual mode selection).
+     */
+    forkContextAdvisory?: {
+        recommendedMode: ForkContextMode;
+        reasons: string[];
+    };
 }
 /** Tool details for TUI rendering */
 export interface TaskToolDetails {
@@ -431,6 +440,7 @@ export interface TaskToolDetails {
         /** Advisory ids for terminal children that spent tokens without detectable output/review/changes. */
         lowRoiChildIds: string[];
     };
+    roiReconciliation?: SpawnRoiReconciliation;
     progress?: AgentProgress[];
     async?: {
         state: "running" | "paused" | "queued" | "completed" | "failed";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/coding-agent",
-	"version": "0.4.4",
+	"version": "0.4.5",
 	"description": "Gajae Code CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://gaebal-gajae.dev",
 	"author": "Yeachan-Heo",
@@ -36,6 +36,7 @@
 		"check:types": "tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
 		"test": "bun test",
+		"bench:context": "bun run bench/context-optimization.bench.ts",
 		"generate-schemas": "bun ../../scripts/generate-json-schemas.ts",
 		"check:schemas": "bun ../../scripts/generate-json-schemas.ts --check",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index",
@@ -50,12 +51,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@gajae-code/stats": "0.4.4",
-		"@gajae-code/agent-core": "0.4.4",
-		"@gajae-code/ai": "0.4.4",
-		"@gajae-code/natives": "0.4.4",
-		"@gajae-code/tui": "0.4.4",
-		"@gajae-code/utils": "0.4.4",
+		"@gajae-code/stats": "0.4.5",
+		"@gajae-code/agent-core": "0.4.5",
+		"@gajae-code/ai": "0.4.5",
+		"@gajae-code/natives": "0.4.5",
+		"@gajae-code/tui": "0.4.5",
+		"@gajae-code/utils": "0.4.5",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",

package/scripts/build-binary.ts

@@ -39,6 +39,10 @@ async function main(): Promise<void> {
 					"bun",
 					"build",
 					"--compile",
+					// Minify shrinks the bundled JS the compiled binary must parse at
+					// startup (302MB → ~114MB --help RSS measured on darwin-arm64).
+					// --keep-names below preserves identifiers for error reports.
+					"--minify",
 					"--no-compile-autoload-bunfig",
 					"--no-compile-autoload-dotenv",
 					"--no-compile-autoload-tsconfig",

package/src/cli/fast-help.ts

@@ -0,0 +1,80 @@
+import { APP_NAME, CONFIG_DIR_NAME } from "@gajae-code/utils/dirs";
+
+export function getExtraHelpText(): string {
+	return `Environment Variables:
+  # Core Providers
+  ANTHROPIC_API_KEY          - Anthropic Claude models
+  ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
+  CLAUDE_CODE_USE_FOUNDRY    - Enable Anthropic Foundry mode (uses Foundry endpoint + mTLS)
+  FOUNDRY_BASE_URL           - Anthropic Foundry base URL (e.g., https://<foundry-host>)
+  ANTHROPIC_FOUNDRY_API_KEY  - Anthropic token used as Authorization: Bearer <token> in Foundry mode
+  ANTHROPIC_CUSTOM_HEADERS   - Extra Foundry headers (e.g., "user-id: USERNAME")
+  CLAUDE_CODE_CLIENT_CERT    - Client certificate (PEM path or inline PEM) for mTLS
+  CLAUDE_CODE_CLIENT_KEY     - Client private key (PEM path or inline PEM) for mTLS
+  NODE_EXTRA_CA_CERTS        - CA bundle path (or inline PEM) for server certificate validation
+  OPENAI_API_KEY             - OpenAI GPT models
+  GEMINI_API_KEY             - Google Gemini models
+  GITHUB_TOKEN               - GitHub Copilot (or GH_TOKEN, COPILOT_GITHUB_TOKEN)
+
+  # Additional LLM Providers
+  AZURE_OPENAI_API_KEY       - Azure OpenAI models
+  GROQ_API_KEY               - Groq models
+  CEREBRAS_API_KEY           - Cerebras models
+  XAI_API_KEY                - xAI Grok models
+  OPENROUTER_API_KEY         - OpenRouter aggregated models
+  KILO_API_KEY               - Kilo Gateway models
+  MISTRAL_API_KEY            - Mistral models
+  ZAI_API_KEY                - z.ai models (ZhipuAI/GLM)
+  MINIMAX_API_KEY            - MiniMax models
+  OPENCODE_API_KEY           - OpenCode Zen/OpenCode Go models
+  CURSOR_ACCESS_TOKEN        - Cursor AI models
+  AI_GATEWAY_API_KEY         - Vercel AI Gateway
+
+  # Cloud Providers
+  AWS_PROFILE                - AWS Bedrock (or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+  GOOGLE_CLOUD_PROJECT       - Google Vertex AI (requires GOOGLE_CLOUD_LOCATION)
+  GOOGLE_APPLICATION_CREDENTIALS - Service account for Vertex AI
+
+  # Search & Tools
+  EXA_API_KEY                - Exa web search
+  BRAVE_API_KEY              - Brave web search
+  PERPLEXITY_API_KEY         - Perplexity web search (API)
+  PERPLEXITY_COOKIES         - Perplexity web search (session cookie)
+  TAVILY_API_KEY             - Tavily web search
+  ANTHROPIC_SEARCH_API_KEY   - Anthropic search provider
+
+  # Configuration
+  GJC_CODING_AGENT_DIR       - Session storage directory (default: ~/${CONFIG_DIR_NAME}/agent)
+  GJC_PACKAGE_DIR            - Override package directory (for Nix/Guix store paths)
+  GJC_SMOL_MODEL              - Override smol/fast model (see --smol)
+  GJC_SLOW_MODEL              - Override slow/reasoning model (see --slow)
+  GJC_PLAN_MODEL              - Override planning model (see --plan)
+  GJC_NO_PTY                  - Disable PTY-based interactive bash execution
+  --tmux                       - Launch interactive startup inside a new tmux session
+  gjc session                  - List, inspect, create, remove, or attach tagged GJC-managed tmux sessions
+  GJC_LAUNCH_POLICY           - Launch policy for --tmux startup: tmux or direct
+  GJC_TMUX_SESSION            - Explicit tmux session name override for --tmux startup
+
+  For complete environment variable reference, see:
+  docs/environment-variables.md
+Available Tools (default-enabled unless noted):
+  read          - Read file contents
+  bash          - Execute bash commands
+  edit          - Edit files with find/replace
+  write         - Write files (creates/overwrites)
+  grep          - Search file contents
+  find          - Find files by glob pattern
+  lsp           - Language server protocol (code intelligence)
+  python        - Execute Python code (requires: ${APP_NAME} setup python)
+  notebook      - Edit Jupyter notebooks
+  inspect_image - Analyze images with a vision model
+  browser       - Browser automation (Puppeteer)
+  task          - Launch sub-agents for parallel tasks
+  todo_write    - Manage todo/task lists
+  web_search    - Search the web
+  ask           - Ask user questions (interactive mode only)
+
+Useful Commands:
+  ${APP_NAME} --list-models        - List configured provider models
+  ${APP_NAME} --help               - Show this help`;
+}