@gajae-code/coding-agent 0.14.2 → 0.15.0

package/dist/types/system-prompt.d.ts

@@ -109,9 +109,32 @@ export interface BuildSystemPromptResult {
     /** Context-file discovery warnings visible to SDK and session callers. */
     warnings: string[];
 }
+/** Host wall-clock facts injected with every turn. */
+export interface LocalTimeContext {
+    /** Local calendar date with weekday, e.g. `2026-08-19 (Wed)`. */
+    date: string;
+    /** Local clock time with UTC offset and IANA zone, e.g. `21:04 UTC+09:00 (Asia/Seoul)`. */
+    time: string;
+}
+/**
+ * Render the host's local date and clock time for the volatile turn context.
+ *
+ * Every field is derived from a single `Intl.DateTimeFormat` pass over one
+ * resolved zone, so the date, clock, offset, and zone name can never disagree
+ * with each other the way `Date`'s local getters can. Falls back to UTC only
+ * when the runtime has no usable ICU zone.
+ *
+ * @param timeZone IANA zone override. Default: the host zone.
+ */
+export declare function getLocalTimeContext(now?: Date, timeZone?: string): LocalTimeContext;
 export interface BuildVolatileProjectContextOptions {
     cwd?: string;
+    /** Clock source for the rendered local date/time. Default: `new Date()`. */
+    now?: Date;
+    /** Trusted/test-only override in the derived `YYYY-MM-DD (Www)` or `YYYY-MM-DD` format. */
     date?: string;
+    /** Trusted/test-only override in the derived `HH:MM UTC±HH:MM (IANA/Zone)` format. */
+    localTime?: string;
     workspaceTree?: WorkspaceTree;
 }
 export declare function buildVolatileProjectContext(options?: BuildVolatileProjectContextOptions): string;

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

@@ -6,6 +6,7 @@
 import type { AgentTelemetryConfig, ThinkingLevel } from "@gajae-code/agent-core";
 import { type Model, type ServiceTier } from "@gajae-code/ai/core";
 import { AsyncJobManager } from "../async";
+import { type AutoroutingReasonCode } from "../config/autorouting-contract";
 import { ModelRegistry } from "../config/model-registry";
 import type { PromptTemplate } from "../config/prompt-templates";
 import { Settings } from "../config/settings";
@@ -14,14 +15,15 @@ import type { HindsightSessionState } from "../hindsight/state";
 import type { LocalProtocolOptions } from "../internal-urls";
 import { AgentRegistry } from "../registry/agent-registry";
 import type { ForkContextSeed } from "../session/agent-session";
-import type { ArtifactManager } from "../session/artifacts";
+import { ArtifactManager } from "../session/artifacts";
 import type { AuthStorage } from "../session/auth-storage";
 import { SessionManager, type SessionMemoryMode } from "../session/session-manager";
 import "../tools/yield";
 import type { ContextFileEntry } from "../tools";
 import type { EventBus } from "../utils/event-bus";
 import type { WorkspaceTree } from "../workspace-tree";
-import { type AgentDefinition, type AgentProgress, type SingleResult } from "./types";
+import { type AgentDefinition, type AgentProgress, type AutoroutingPreflightFailure, type SingleResult, type TaskRoutingEvidence } from "./types";
+export type { AutoroutingPreflightFailure } from "./types";
 import { type ExecutorExecutionMode } from "./ultragoal-redteam-activation";
 export declare function trimForkContextSeedForModel(seed: ForkContextSeed, model: Model | undefined): ForkContextSeed;
 /** Options for subagent execution */
@@ -38,6 +40,19 @@ export interface ExecutorOptions {
     executionMode?: ExecutorExecutionMode;
     context?: string;
     description?: string;
+    routing?: TaskRoutingEvidence;
+    /** Ordered, normalized autorouting candidates for the cross-phase preflight ledger. */
+    autoroutingCandidates?: string[];
+    autoroutingSkips?: Array<{
+        selector: string;
+        code: AutoroutingReasonCode;
+    }>;
+    autoroutingPreflightErrors?: Map<string, unknown>;
+    autoroutingPreflight?: boolean;
+    autoroutingAttemptId?: string;
+    preflightProbe?: boolean;
+    preflightDurable?: boolean;
+    preflightFenceCallback?: () => void;
     index: number;
     id: string;
     modelOverride?: string | string[];
@@ -129,6 +144,7 @@ export declare class ManagedTaskPersistence {
     #private;
     constructor(artifacts: ArtifactManager, taskId: string);
     openSession(cwd: string, sessionMemoryMode?: SessionMemoryMode): Promise<SessionManager>;
+    openStagedSession(attemptId?: string): Promise<SessionManager>;
     publishOutput(rawOutput: string, metadata: Uint8Array): Promise<void>;
 }
 export declare function createManagedTaskPersistence(artifacts: ArtifactManager, taskId: string): ManagedTaskPersistence;
@@ -142,6 +158,7 @@ interface FinalizeSubprocessOutputArgs {
     rawOutput: string;
     exitCode: number;
     stderr: string;
+    terminalFailure?: boolean;
     doneAborted: boolean;
     signalAborted: boolean;
     yieldItems?: YieldItem[];
@@ -160,7 +177,21 @@ export declare const SUBAGENT_WARNING_PLACEHOLDER_YIELD = "SYSTEM WARNING: Subag
 export declare function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): FinalizeSubprocessOutputResult;
 export declare function createSubagentSettings(baseSettings: Settings, inheritedServiceTier?: ServiceTier): Settings;
 /**
- * Run a single agent in-process.
+ * Finalize routing evidence at the executor return boundary: the effective
+ * model is the terminal provider-reported model when present, otherwise the
+ * auth-resolved model; substitution causes are appended in order.
  */
+export declare function finalizeRoutingEvidence(routing: TaskRoutingEvidence | undefined, state: {
+    resolvedModelString: string | undefined;
+    lastAssistantModelString: string | undefined;
+    authFallbackUsed: boolean;
+    assistantModelMismatch: boolean;
+}): TaskRoutingEvidence | undefined;
+export declare function classifyAutoroutingPreflightFailure(error: unknown, op: Extract<AutoroutingPreflightFailure, {
+    kind: "local";
+}>["op"]): AutoroutingPreflightFailure;
+export declare function runSubprocessOnce(options: ExecutorOptions): Promise<SingleResult>;
+export declare function boundedSelector(value: string): string;
+export declare function buildBoundedRoutingSkips(skips: ExecutorOptions["autoroutingSkips"]): Pick<TaskRoutingEvidence, "skips" | "omittedSkipCount" | "omittedByCode">;
+/** Run routed initial tasks through the bounded probe/durable candidate ledger. */
 export declare function runSubprocess(options: ExecutorOptions): Promise<SingleResult>;
-export {};

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

@@ -3,11 +3,12 @@ import type { Model } from "@gajae-code/ai/core";
 import { type SubagentRunOutcome } from "@gajae-code/coding-agent/async";
 import type { ToolSession } from "..";
 import type { Theme } from "../modes/theme/theme";
-import { type SingleResult, type TaskToolDetails, type TaskToolSchemaInstance } from "./types";
+import { type SingleResult, type TaskRoutingEvidence, type TaskToolDetails, type TaskToolSchemaInstance } from "./types";
 import "../tools/review";
+import { runSubprocess } from "./executor";
 import { type TaskResultReceipt } from "./receipt";
 import { renderResult, renderCall as renderTaskCall } from "./render";
-export declare function subagentRunOutcomeFromSingleResult(finalText: string, singleResult: (Pick<SingleResult, "aborted" | "exitCode" | "paused" | "setupFailure"> & Partial<Pick<TaskResultReceipt, "status">>) | undefined): string | SubagentRunOutcome;
+export declare function subagentRunOutcomeFromSingleResult(finalText: string, singleResult: (Pick<SingleResult, "aborted" | "exitCode" | "paused" | "setupFailure" | "localErrorSummary"> & Partial<Pick<TaskResultReceipt, "status">>) | undefined): string | SubagentRunOutcome;
 export { loadBundledAgents as BUNDLED_AGENTS } from "./agents";
 export { discoverCommands, expandCommand, getCommand } from "./commands";
 export { discoverAgents, getAgent } from "./discovery";
@@ -18,6 +19,17 @@ export { assertNoRawTaskFields, buildTaskReceipt, buildTaskRoi, buildTaskRoiSumm
 export type { AgentDefinition, AgentProgress, SingleResult, SubagentLifecyclePayload, SubagentProgressPayload, TaskParams, TaskToolDetails, } from "./types";
 export { TASK_SUBAGENT_EVENT_CHANNEL, TASK_SUBAGENT_LIFECYCLE_CHANNEL, TASK_SUBAGENT_PROGRESS_CHANNEL, taskSchema, } from "./types";
 export declare function resolveForkContextMaxTokens(configured: number, model: Model | undefined): number;
+export declare function findRoutingSnapshotModel(selector: string, routingSnapshot: readonly Model[]): Model | undefined;
+/**
+ * Project routing evidence into the XML-attribute-safe display view consumed by
+ * the task-summary template. The template runtime uses noEscape, so every
+ * interpolated attribute value must be escaped here.
+ */
+export declare function projectRoutingForSummary(routing: TaskRoutingEvidence | undefined): {
+    tier: string;
+    effectiveModel: string;
+    note: string;
+} | undefined;
 /**
  * Task tool - Delegate tasks to specialized agents.
  *
@@ -47,7 +59,9 @@ export declare class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskT
      * Repository authority is captured from session cwd *before* agent discovery so
      * multi-repo workspaces fail closed prior to context/discovery (#2901).
      */
-    static create(session: ToolSession): Promise<TaskTool>;
+    static create(session: ToolSession, options?: {
+        runSubprocess?: typeof runSubprocess;
+    }): Promise<TaskTool>;
     /** Create catalog metadata from bundled agents only, without ambient filesystem discovery. */
     static createForToolCatalog(session: ToolSession): Promise<TaskTool>;
     execute(_toolCallId: string, rawParams: unknown, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TaskToolDetails>): Promise<AgentToolResult<TaskToolDetails>>;

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

@@ -1,4 +1,4 @@
-import { type ReviewFindingsArtifactRef, type SingleResult, type TaskToolDetails } from "./types";
+import { type ReviewFindingsArtifactRef, type SingleResult, type TaskRoutingEvidence, type TaskToolDetails } from "./types";
 export interface TaskRoi {
     tokens: number;
     contextTokens?: number;
@@ -28,6 +28,7 @@ export interface TaskResultReceipt {
     contextTokens?: number;
     contextWindow?: number;
     modelOverride?: string | string[];
+    routing?: TaskRoutingEvidence;
     modelSubstitutionWarning?: SingleResult["modelSubstitutionWarning"];
     fastMode?: boolean;
     usage?: SingleResult["usage"];
@@ -42,6 +43,7 @@ export interface TaskResultReceipt {
     setupFailure?: {
         summary: string;
     };
+    localErrorSummary?: SingleResult["localErrorSummary"];
     errorSummary?: string;
     duplicateDisposition?: SingleResult["duplicateDisposition"];
     abortSummary?: string;

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

@@ -1,6 +1,8 @@
 import type { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Usage } from "@gajae-code/ai/core";
+import type { FallbackTriggerClass } from "@gajae-code/ai/utils/fallback-transport";
 import * as z from "zod/v4";
+import { type AutoroutingReasonCode } from "../config/autorouting-contract";
 import type { TaskResultReceipt } from "./receipt";
 import type { SpawnRoiReconciliation } from "./roi-reconciliation";
 import { type TaskSimpleMode } from "./simple-mode";
@@ -45,6 +47,11 @@ export declare const taskItemSchema: z.ZodObject<{
     id: z.ZodString;
     description: z.ZodString;
     assignment: z.ZodString;
+    tier: z.ZodOptional<z.ZodEnum<{
+        balanced: "balanced";
+        fast: "fast";
+        strong: "strong";
+    }>>;
     executionMode: z.ZodOptional<z.ZodEnum<{
         default: "default";
         "ultragoal-red-team": "ultragoal-red-team";
@@ -77,6 +84,11 @@ export declare const taskSchema: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -116,6 +128,11 @@ export declare const taskSchemaNoIsolation: z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -155,6 +172,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -193,6 +215,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -231,6 +258,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -269,6 +301,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -307,6 +344,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -345,6 +387,11 @@ declare const ALL_TASK_SCHEMAS: readonly [z.ZodObject<{
         id: z.ZodString;
         description: z.ZodString;
         assignment: z.ZodString;
+        tier: z.ZodOptional<z.ZodEnum<{
+            balanced: "balanced";
+            fast: "fast";
+            strong: "strong";
+        }>>;
         executionMode: z.ZodOptional<z.ZodEnum<{
             default: "default";
             "ultragoal-red-team": "ultragoal-red-team";
@@ -532,6 +579,56 @@ export interface SetupFailureSummary {
 }
 /** Create a bounded diagnostic that preserves a setup failure's cause without exposing credentials or local paths. */
 export declare function createSetupFailureSummary(error: unknown): SetupFailureSummary;
+/** Bounded, redaction-safe summary of a terminal local (non-provider) subagent failure. */
+export interface LocalErrorSummary {
+    kind: string;
+    summary: string;
+}
+/**
+ * Runtime-validate a structured overflow diagnostic at the consuming trust
+ * boundary. Presence on an `AssistantMessage` is NOT authenticity: a foreign
+ * provider/stream payload could set the field, so every value is checked —
+ * closed `stage`/`exceeded` literals and finite non-negative integer counters.
+ * Returns `undefined` for anything that fails, and the caller then degrades to
+ * a fixed neutral sentence instead of interpolating untrusted values (#4618).
+ */
+export declare function validateLocalOverflowShape(overflow: unknown): {
+    stage: string;
+    exceeded: "events" | "bytes" | "both";
+    stagedEventCount: number;
+    stagedBytes: number;
+    incomingEventBytes: number;
+    maxStagedEvents: number;
+    maxStagedBytes: number;
+} | undefined;
+/**
+ * Render the parent-facing summary of a validated overflow diagnostic. Built
+ * ONLY from the closed-vocabulary stage/exceeded literals and the numeric
+ * counters — no producer-controlled text participates, so a hostile or buggy
+ * child can inject nothing through this path (#4618).
+ */
+export declare function formatBufferOverflowSummary(overflow: {
+    stage: string;
+    exceeded: "events" | "bytes" | "both";
+    stagedEventCount: number;
+    stagedBytes: number;
+    incomingEventBytes: number;
+    maxStagedEvents: number;
+    maxStagedBytes: number;
+}): string;
+/**
+ * Build the safe parent-facing summary for a terminal local failure.
+ *
+ * Trust boundary: the structured `bufferOverflow` shape is runtime-validated
+ * (`validateLocalOverflowShape`) before any value is interpolated — closed
+ * literals and checked integers only. A shape that fails validation, or an
+ * overflow kind with no shape at all, degrades to a fixed neutral sentence.
+ * `local_snapshot_failure` uses a fixed sentence too: regex redaction cannot
+ * make arbitrary child message text safe to embed in a parent receipt.
+ */
+export declare function createLocalErrorSummary(kind: unknown, _message: string | undefined, overflow?: unknown): LocalErrorSummary;
+/** Whether an assistant terminal message carries a known local (non-provider) failure kind. */
+export declare function isAssistantLocalErrorKind(kind: unknown): kind is "local_buffer_overflow" | "local_snapshot_failure";
 export interface TaskRecoveryArtifactRef {
     uri: string;
     sizeBytes: number;
@@ -549,6 +646,45 @@ export interface TaskPersistenceResult {
     ownerWorktreeApplied: boolean;
     recoveryRef?: TaskRecoveryArtifactRef;
 }
+export type RoutingSubstitution = "auth_substituted" | "assistant_model_mismatch";
+/** A typed failure observed while an autorouting candidate is still before the real provider fence. */
+export type AutoroutingPreflightFailure = {
+    kind: "local";
+    op: "auth_resolve" | "session_open" | "tool_bootstrap" | "preflight_validation";
+    transient: boolean;
+} | {
+    kind: "transport";
+    class: FallbackTriggerClass;
+};
+export type AutoroutingAttemptCode = "probe_passed" | "accepted" | "spawn_transient_retry" | "credential_unavailable" | "config_invalid_terminal" | "post_acceptance_failure" | "unclassified_terminal";
+export type AutoroutingAttempt = {
+    selector: string;
+    phase: "probe" | "durable";
+    code: AutoroutingAttemptCode;
+};
+export type AutoroutingSkip = {
+    selector: string;
+    code: AutoroutingReasonCode;
+};
+export interface TaskRoutingEvidence {
+    tier: "fast" | "balanced" | "strong";
+    requestedTier?: "fast" | "balanced" | "strong";
+    defaultTierApplied?: true;
+    requestedSelector: string;
+    authResolvedModel?: string;
+    effectiveModel?: string;
+    notExecuted?: true;
+    substitutions: RoutingSubstitution[];
+    manualFallbackReason?: "tier_unmatched" | "tier_missing_in_map";
+    freshOnResume?: true;
+    note?: string;
+    skips?: AutoroutingSkip[];
+    omittedSkipCount?: number;
+    omittedByCode?: Partial<Record<AutoroutingSkip["code"], number>>;
+    attempts?: AutoroutingAttempt[];
+    terminal?: "preflight_exhausted" | "all_candidates_skipped";
+}
+export declare function assertRoutingEvidenceInvariant(evidence: TaskRoutingEvidence): void;
 /** Result from a single agent execution */
 export interface SingleResult {
     index: number;
@@ -570,13 +706,21 @@ export interface SingleResult {
     contextTokens?: number;
     /** Model's context window in tokens, when known. */
     contextWindow?: number;
+    routing?: TaskRoutingEvidence;
     modelOverride?: string | string[];
     modelSubstitutionWarning?: ModelSubstitutionWarning;
     /** Whether the resolved subagent model ran under the effective fast service tier. */
     fastMode?: boolean;
     error?: string;
+    /** Safe summary of a terminal local (non-provider) failure kind, e.g. `local_buffer_overflow`. */
+    localErrorSummary?: LocalErrorSummary;
     /** Safe diagnostic for a failure before the subagent sent its first LLM request. */
     setupFailure?: SetupFailureSummary;
+    /** Internal typed autorouting preflight outcome; receipt sanitization omits this field. */
+    preflightFailure?: AutoroutingPreflightFailure;
+    preflightFenceCrossed?: boolean;
+    preflightProbeAccepted?: boolean;
+    preflightCommitFailure?: boolean;
     aborted?: boolean;
     abortReason?: string;
     duplicateDisposition?: DuplicateDisposition;

package/dist/types/tools/atomic-file-write.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fail-atomic user-file writes for the write/edit/LSP writethrough path.
+ *
+ * The guarantee is visibility, not crash durability: a failed write never
+ * publishes partial or truncated bytes, and the destination is left byte-
+ * identical. It is deliberately NOT crash-atomic -- the parent directory is
+ * never fsynced, so a rename can be lost across a system crash.
+ *
+ * Publication is last-writer-wins, not conditional. Identity is revalidated
+ * immediately before the rename, which rejects a destination that was replaced
+ * or retargeted while staging, but `rename(2)` commits against the pathname:
+ * a writer that publishes a successor inside the window between that check and
+ * the rename is overwritten. Closing that window needs an OS conditional-
+ * replace primitive; the exchange-based one available here was removed because
+ * it validated only after committing and leaked protocol debris into user
+ * directories on every successful write. `write` is a last-writer-wins tool by
+ * contract, so this is the documented behavior rather than a silent race.
+ *
+ * `Bun.write` truncates the destination then copies bytes. A permission or IO
+ * failure after that truncate leaves a 0-byte target even though the tool
+ * reported an error. Stage to a sibling temp, then rename over the destination
+ * so a failed attempt never publishes a truncated file. Directory fsync is
+ * intentionally omitted: Windows reports `EPERM` for it (#4457) and user-file
+ * publication does not need that durability barrier.
+ *
+ * Destination symlinks are followed: the referent is replaced, the link stays.
+ * The referent is re-resolved immediately before publication so a retargeted
+ * link cannot silently repoint the write, and when the lexical destination
+ * sits inside a session-scoped `gjc-local` root the resolved referent and its
+ * parent must remain inside that root (a link there must not redirect the
+ * write out of the trust boundary).
+ *
+ * Staging uses exclusive create (`wx`) so a colliding leftover temp is never
+ * truncated or unlinked; only the temp this call created is cleaned on failure.
+ * Existing-file mode and ownership are re-applied after staging so a process
+ * umask or replacement inode never changes the target's identity. Hard-linked
+ * targets are rejected because replacement would split their link group, and
+ * target identity is revalidated before the final same-directory rename. The
+ * staged bytes are synced before publication; directory fsync is intentionally not
+ * promised because Windows reports EPERM for it (#4457).
+ */
+export type FileWritePublicationState = "not_published" | "published" | "unknown";
+export declare class FileWriteNotPublishedError extends Error {
+    readonly dest: string;
+    readonly destUnchanged: boolean;
+    readonly publicationState: FileWritePublicationState;
+    readonly cause: unknown;
+    constructor(dest: string, cause: unknown, options?: {
+        destUnchanged?: boolean;
+        publicationState?: FileWritePublicationState;
+    });
+}
+export declare function isFileWritePermissionError(error: unknown): boolean;
+export declare function formatFileWriteError(error: unknown, dest: string, options?: {
+    destUnchanged?: boolean;
+}): string;
+export interface WriteFileAtomicallyOptions {
+    /**
+     * Trusted root that a resolved symlink referent and its parent must not
+     * leave. When omitted, the helper still enforces the session-scoped
+     * `gjc-local` boundary implied by a lexical destination under
+     * `<tmpdir>/gjc-local/<session-id>`.
+     */
+    trustBoundary?: string;
+    /** Platform override used by deterministic retry tests. */
+    platform?: NodeJS.Platform;
+    /** Sleep seam used by deterministic retry tests. */
+    sleep?: (delayMs: number) => Promise<void>;
+    /** Test seam invoked after the fallback handle is opened and before mutation. */
+    beforeInPlaceMutation?: () => Promise<void>;
+}
+export declare function writeFileAtomically(dest: string, content: string | Uint8Array, options?: WriteFileAtomicallyOptions): Promise<void>;

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

@@ -88,6 +88,7 @@ export interface ToolDiscoverySettingsSource {
     get(key: string): unknown;
 }
 export declare function resolveEffectiveDiscoveryMode(settings: ToolDiscoverySettingsSource, explicitMcpConfigPath?: string): EffectiveToolDiscoveryMode;
+export declare function evictCachedTool(key: string): void;
 export declare const PLATFORM_EXCLUDED_TOOL_DESCRIPTORS: Record<string, ToolDescriptor>;
 export declare const BUILTIN_TOOL_DESCRIPTORS: Record<string, ToolDescriptor>;
 export declare const HIDDEN_TOOL_DESCRIPTORS: Record<string, ToolDescriptor>;

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

@@ -33,6 +33,16 @@ export { TOOL_CATALOG } from "./tool-catalog.generated";
 export type { WriteToolDetails, WriteToolInput } from "./write";
 /** Tool type (AgentTool from pi-ai) */
 export type Tool = AgentTool<any, any, any>;
+/** Built-in automation surfaces that an SDK host may back with its own transport. */
+export type AutomationToolName = "browser" | "computer";
+/**
+ * Host-owned implementations for the built-in automation surfaces.
+ *
+ * Each implementation must use the matching built-in name. The normal
+ * AgentTool execute signature carries cancellation through its AbortSignal,
+ * while the implementation owns the model-facing schema and description.
+ */
+export type AutomationTools = Partial<Record<AutomationToolName, Tool>>;
 export type ContextFileEntry = {
     path: string;
     content: string;
@@ -131,6 +141,16 @@ export interface ToolSession {
     /** Pre-loaded workspace tree (forwarded to subagents to skip re-scanning) */
     workspaceTree?: WorkspaceTree;
     /** Pre-loaded skills */
+    /**
+     * Explicit user home for runtime skill discovery. Tests construct sessions
+     * against an isolated home because the trusted-home resolver deliberately
+     * ignores `$HOME` on Linux (it reads the NSS account database instead), so a
+     * `process.env.HOME` override cannot steer user-scope discovery there.
+     *
+     * Production sessions leave this unset and the trusted OS home governs.
+     * Runtime discovery only; never threaded into capability loading.
+     */
+    home?: string;
     skills?: Skill[];
     /** Currently executing skill prompt, when this tool session is inside one. */
     getActiveSkillState?: () => Pick<SkillActiveEntry, "skill" | "session_id"> | undefined;
@@ -264,6 +284,21 @@ export interface ToolSession {
     goalToolAllowedOps?: readonly ("create" | "get" | "complete" | "resume" | "drop" | "pause")[];
     /** Goal runtime for the active agent session. */
     getGoalRuntime?: () => GoalRuntime | undefined;
+    /**
+     * Agent-invokable session rescope (issue #4629): move the whole session to
+     * an existing directory, running the same sequence as the `/move` handler
+     * (flush → moveTo → setProjectDir → plugin/capability cache reset). Absent
+     * in contexts where relocation must not happen: subagent sessions
+     * (taskDepth > 0) and read-only/restricted bash profiles. Bound to one
+     * successful move per session, rejects re-entrant calls, and only narrows:
+     * the canonical (realpath) target must be a strict descendant of the
+     * canonical current cwd. Throws when the target does not exist, is not a
+     * directory, or escapes the current scope.
+     */
+    rescopeSessionCwd?: (path: string) => Promise<{
+        from: string;
+        to: string;
+    }>;
     /** Bridge to the connected client (e.g. ACP editor host). Tools should route fs/terminal/permission requests through this when available. */
     getClientBridge?: () => ClientBridge | undefined;
     /** Get compact conversation context for subagents (excludes tool results, system prompts) */
@@ -400,4 +435,4 @@ export declare function resolveEvalBackends(session: ToolSession): EvalBackendsA
 /**
  * Create tools from the descriptor registry.
  */
-export declare function createTools(session: ToolSession, toolNames?: string[]): Promise<Tool[]>;
+export declare function createTools(session: ToolSession, toolNames?: string[], automationTools?: AutomationTools): Promise<Tool[]>;

package/dist/types/tools/move-session.d.ts

@@ -0,0 +1,40 @@
+import type { AgentTool, AgentToolResult } from "@gajae-code/agent-core";
+import type { Component } from "@gajae-code/tui";
+import * as z from "zod/v4";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import type { ToolSession } from "./index";
+declare const moveSessionSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export type MoveSessionToolInput = z.infer<typeof moveSessionSchema>;
+export interface MoveSessionToolDetails {
+    from: string;
+    to: string;
+}
+export declare class MoveSessionTool implements AgentTool<typeof moveSessionSchema, MoveSessionToolDetails> {
+    #private;
+    readonly name = "move_session";
+    readonly label = "Move Session";
+    readonly loadMode: "essential";
+    readonly description: string;
+    readonly parameters: z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strip>;
+    readonly strict = true;
+    readonly intent: "omit";
+    readonly concurrency: "exclusive";
+    readonly nonAbortable = true;
+    constructor(session: ToolSession);
+    execute(_toolCallId: string, params: MoveSessionToolInput): Promise<AgentToolResult<MoveSessionToolDetails>>;
+}
+export declare const moveSessionToolRenderer: {
+    renderCall: (args: unknown) => Component;
+    renderResult: (result: {
+        details?: unknown;
+        isError?: boolean;
+    }, _options: RenderResultOptions & {
+        renderContext?: Record<string, unknown>;
+    }, theme: Theme) => Component;
+};
+export {};

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

@@ -0,0 +1,12 @@
+import type { AgentTool } from "@gajae-code/agent-core";
+export declare const PYTHON_TOOL_NAME = "python";
+export declare function pythonKernelOwnerId(sessionId: string): string;
+export interface SessionPythonToolInput {
+    /** Working directory for kernel execution (session cwd). */
+    cwd: string;
+    /** Resolve the GJC session id used for the kernel owner and transcript paths. */
+    getSessionId: () => string | null;
+    /** Register cleanup with the current logical session lifecycle. */
+    registerSessionCleanup: (cleanup: () => Promise<void> | void) => void;
+}
+export declare function createSessionPythonTool(input: SessionPythonToolInput): AgentTool;

package/dist/types/tools/resource-gc.d.ts

@@ -1,6 +1,5 @@
 import type { WindowsJobMemoryProbeResult } from "@gajae-code/natives";
 import type { Settings } from "../config/settings";
-import type { MemoryGuardWorkerSample } from "../runtime/memory-guard-contract";
 import { type TabGcSnapshot } from "./browser/tab-supervisor";
 export interface BrowserGcPolicy {
     enabled: boolean;
@@ -36,8 +35,6 @@ export interface ResourceGcDeps {
         removed: number;
     }>;
     screenshotArmed: () => boolean;
-    listTeamWorkers?: (cwd: string, sessionId: string) => Promise<MemoryGuardWorkerSample[]>;
-    applyTeamWorkerGuard?: (cwd: string, sessionId: string, workerId: string, excessBytes: number, incidentId: string) => Promise<void>;
 }
 /** Request collection without synchronously stopping the main event loop. */
 export declare function requestMemoryPressureGc(): void;

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

@@ -51,9 +51,16 @@ export interface SearchToolDetails {
      * non-fatal warning in the renderer and in the model-facing text. */
     missingPaths?: string[];
 }
+export interface SearchToolOptions {
+    /** Per-call symmetric context width used by Cursor's native Pi grep frame. */
+    context?: number;
+    /** Per-call total match cap used by Cursor's native Pi grep frame. */
+    totalMatchLimit?: number;
+}
 type SearchParams = z.infer<typeof searchSchema>;
 export declare class SearchTool implements AgentTool<typeof searchSchema, SearchToolDetails> {
     private readonly session;
+    private readonly options;
     readonly name = "search";
     readonly label = "Search";
     readonly loadMode = "discoverable";
@@ -67,7 +74,7 @@ export declare class SearchTool implements AgentTool<typeof searchSchema, Search
         skip: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     readonly strict = true;
-    constructor(session: ToolSession);
+    constructor(session: ToolSession, options?: SearchToolOptions);
     execute(_toolCallId: string, params: SearchParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<SearchToolDetails>, _toolContext?: AgentToolContext): Promise<AgentToolResult<SearchToolDetails>>;
 }
 interface SearchRenderArgs {