@gajae-code/coding-agent 0.16.4 → 0.16.6

package/dist/types/extensibility/extensions/index.d.ts

@@ -2,6 +2,7 @@
  * Extension system for lifecycle events and custom tools.
  */
 export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from "../slash-commands";
+export { attenuateFunctionHookGrant, cloneFunctionHookData, compatibilityFunctionHookGrant, createFunctionHookCapabilities, DEFAULT_EXTENSION_FUNCTION_HOOK_GRANT, FUNCTION_HOOK_CAPABILITIES, functionHookDenyAllowed, functionHookEventIdentityMatches, functionHookGrantHash, functionHookGrantOperations, functionHookPayloadHash, functionHookTransformAllowed, intersectFunctionHookGrants, isPlainFunctionHookData, isSafeFunctionHookValue, isValidFunctionHookEventValue, normalizeFunctionHookGrant, redactFunctionHookValue, sanitizeFunctionHookReason, validateFunctionHookTarget, } from "./function-hooks";
 export { discoverAndLoadExtensions, ExtensionRuntimeNotInitializedError, loadExtensionFromFactory, loadExtensions, } from "./loader";
 export * from "./ouroboros-ooo-bridge";
 export * from "./prefix-command-bridge";

package/dist/types/extensibility/extensions/runner.d.ts

@@ -8,11 +8,14 @@ import type { ModelRegistry } from "../../config/model-registry";
 import type { Settings } from "../../config/settings";
 import type { AttemptRecordStore } from "../../session/attempt-record-store";
 import { type SessionManager } from "../../session/session-manager";
+import { type FunctionHookAuditRecord, type FunctionHookRegistration } from "./function-hooks";
 import type { AfterProviderResponseEvent, BeforeAgentStartEvent, BeforeAgentStartEventResult, BeforeProviderRequestEvent, BeforeProviderRequestEventResult, ContextEvent, Extension, ExtensionActions, ExtensionCommandContext, ExtensionCommandContextActions, ExtensionContext, ExtensionContextActions, ExtensionError, ExtensionEvent, ExtensionFlag, ExtensionRuntime, ExtensionShortcut, ExtensionUIContext, InputEvent, InputEventResult, MessageRenderer, RegisteredCommand, RegisteredTool, ResourcesDiscoverEvent, SessionBeforeBranchResult, SessionBeforeCompactResult, SessionBeforeSwitchResult, SessionBeforeTreeResult, SessionCompactingResult, ToolCallEvent, ToolCallEventResult, ToolResultEvent, ToolResultEventResult, UserBashEvent, UserBashEventResult, UserPythonEvent, UserPythonEventResult } from "./types";
 /** Combined result from all before_agent_start handlers */
 interface BeforeAgentStartCombinedResult {
     messages?: NonNullable<BeforeAgentStartEventResult["message"]>[];
     systemPrompt?: string[];
+    prompt?: string;
+    images?: ImageContent[];
 }
 export type ExtensionErrorListener = (error: ExtensionError) => void;
 /** Bounded timeout for session_shutdown handlers — generous but never infinite. */
@@ -36,6 +39,24 @@ type RunnerEmitResult<TEvent extends RunnerEmitEvent> = TEvent extends {
 } ? SessionBeforeTreeResult | undefined : TEvent extends {
     type: "session.compacting";
 } ? SessionCompactingResult | undefined : undefined;
+type Handler = Extension["handlers"] extends Map<string, Array<infer T>> ? T : never;
+type IndexedHandler = {
+    ext: Extension;
+    handler: Handler;
+    registrationOrder: number;
+};
+export type FunctionHookDispatchResult<TEvent extends ExtensionEvent> = {
+    action: "continue";
+    event: TEvent;
+    transformed?: boolean;
+} | {
+    action: "deny";
+    reason: string;
+} | {
+    action: "return";
+    value: unknown;
+};
+export type FunctionHookAuditSink = (record: FunctionHookAuditRecord) => void;
 export type NewSessionHandler = (options?: {
     parentSession?: string;
     setup?: (sessionManager: SessionManager) => Promise<void>;
@@ -97,6 +118,12 @@ export declare class ExtensionRunner {
     onError(listener: ExtensionErrorListener): () => void;
     emitError(error: ExtensionError): void;
     hasHandlers(eventType: string): boolean;
+    hasToolResultMediation(toolName: string): boolean;
+    /** Return immutable registration metadata in authoritative registration order. */
+    getFunctionHookRegistrations(): readonly FunctionHookRegistration[];
+    /** Install the optional deterministic audit sink used by hosts and tests. */
+    setFunctionHookAuditSink(sink: FunctionHookAuditSink | undefined): void;
+    getFunctionHookAudit(): readonly FunctionHookAuditRecord[];
     setAttemptRecordStore(store: AttemptRecordStore): void;
     getMessageRenderer(customType: string): MessageRenderer | undefined;
     getRegisteredCommands(reserved?: Set<string>): RegisteredCommand[];
@@ -112,9 +139,22 @@ export declare class ExtensionRunner {
      */
     shutdown(): void;
     createCommandContext(): ExtensionCommandContext;
+    /** Execute capability-scoped middleware stored in Extension.handlers. */
+    emitFunctionHooks<TEvent extends ExtensionEvent>(event: TEvent, options?: {
+        signal?: AbortSignal;
+        correlationId?: string;
+        scope?: AttemptScopeRef;
+        legacyHandler?: (handler: IndexedHandler, event: TEvent) => Promise<FunctionHookDispatchResult<TEvent>>;
+    }): Promise<FunctionHookDispatchResult<TEvent>>;
     emit<TEvent extends RunnerEmitEvent>(event: TEvent, continueWhile?: () => boolean, scope?: AttemptScopeRef): Promise<RunnerEmitResult<TEvent>>;
-    emitToolResult(event: ToolResultEvent, scope?: AttemptScopeRef): Promise<ToolResultEventResult | undefined>;
-    emitToolCall(event: ToolCallEvent, scope?: AttemptScopeRef): Promise<ToolCallEventResult | undefined>;
+    emitToolResult(event: ToolResultEvent, scope?: AttemptScopeRef, options?: {
+        signal?: AbortSignal;
+        correlationId?: string;
+    }): Promise<ToolResultEventResult | undefined>;
+    emitToolCall(event: ToolCallEvent, scope?: AttemptScopeRef, options?: {
+        signal?: AbortSignal;
+        correlationId?: string;
+    }): Promise<ToolCallEventResult | undefined>;
     emitUserBash(event: UserBashEvent): Promise<UserBashEventResult | undefined>;
     emitUserPython(event: UserPythonEvent): Promise<UserPythonEventResult | undefined>;
     private emitUserEvent;
@@ -134,9 +174,9 @@ export declare class ExtensionRunner {
     }>;
     /** Emit input event. Transforms chain, "handled" short-circuits. */
     emitInput(text: string, images: ImageContent[] | undefined, source: "interactive" | "sdk" | "extension"): Promise<InputEventResult>;
-    emitContext(messages: AgentMessage[], scope?: AttemptScopeRef): Promise<AgentMessage[]>;
-    emitBeforeProviderRequest(payload: unknown, scope?: AttemptScopeRef): Promise<BeforeProviderRequestEventResult>;
-    emitAfterProviderResponse(response: ProviderResponseMetadata, _model?: Model, scope?: AttemptScopeRef): Promise<void>;
-    emitBeforeAgentStart(prompt: string, images: ImageContent[] | undefined, systemPrompt: string[]): Promise<BeforeAgentStartCombinedResult | undefined>;
+    emitContext(messages: AgentMessage[], scope?: AttemptScopeRef, signal?: AbortSignal): Promise<AgentMessage[]>;
+    emitBeforeProviderRequest(payload: unknown, scope?: AttemptScopeRef, signal?: AbortSignal): Promise<BeforeProviderRequestEventResult>;
+    emitAfterProviderResponse(response: ProviderResponseMetadata, _model?: Model, scope?: AttemptScopeRef, signal?: AbortSignal): Promise<void>;
+    emitBeforeAgentStart(prompt: string, images: ImageContent[] | undefined, systemPrompt: string[], signal?: AbortSignal): Promise<BeforeAgentStartCombinedResult | undefined>;
 }
 export {};

package/dist/types/extensibility/extensions/types.d.ts

@@ -27,6 +27,7 @@ import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { WorkflowGateEmitter } from "../../modes/shared/agent-wire/workflow-gate-broker";
 import type { Theme } from "../../modes/theme/theme";
+import type { AgentSessionEventListener } from "../../session/agent-session";
 import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome, ClientBridgePermissionToolCall } from "../../session/client-bridge";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
@@ -34,6 +35,7 @@ import type { BashToolDetails, BashToolInput, FindToolDetails, FindToolInput, Re
 import type { EventBus } from "../../utils/event-bus";
 import type { AgentEndEvent, AutoCompactionEndEvent, AutoCompactionStartEvent, AutoRetryEndEvent, AutoRetryStartEvent, ContextEvent, GoalUpdatedEvent, SessionBeforeBranchEvent, SessionBeforeBranchResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionBranchEvent, SessionCompactEvent, SessionCompactingEvent, SessionCompactingResult, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, AgentStartEvent as SharedAgentStartEvent, TodoReminderEvent, ToolCallEventResult, ToolResultEventResult, TtsrTriggeredEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
 import type { SlashCommandInfo } from "../slash-commands";
+import type { FunctionHook, FunctionHookEventType, FunctionHookPayloadFor, FunctionHookRegistrationOptions } from "./function-hooks";
 export type { AppKeybinding, KeybindingsManager } from "../../config/keybindings";
 export type { ExecOptions, ExecResult } from "../../exec/exec";
 export type { AgentToolResult, AgentToolUpdateCallback };
@@ -336,6 +338,8 @@ export interface ExtensionContext {
     getJobs(): unknown;
     /** Subscribe to foreground-wait folds (`bash_folded`). Returns an unsubscribe function. */
     onJobFold?(listener: (event: JobFoldEvent) => void): () => void;
+    /** Observe session events synchronously in producer order. Returns an unsubscribe function. */
+    onSessionEvent?(listener: AgentSessionEventListener): () => void;
     /** Typed skill and mode controls exposed to the SDK host. */
     invokeSkill?(name: string, args?: string, options?: {
         onPreflightAccepted?: () => void;
@@ -489,6 +493,8 @@ export type { AgentEndEvent, TurnEndEvent, TurnStartEvent } from "../shared-even
 /** Fired when an agent loop starts. `sdkRunToken` is an internal SDK queue-owner binding. */
 export interface AgentStartEvent extends SharedAgentStartEvent {
     sdkRunToken?: string;
+    /** Complete set of SDK queue owners consumed together by this run. */
+    sdkRunTokens?: string[];
 }
 /** Fired when an agent run fails before emitting agent_end. The error is the
  * sanitized `{ code, message }` diagnostic from the agent runtime — never the raw
@@ -796,6 +802,13 @@ export interface ExtensionAPI {
     on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
     on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
     on(event: "user_python", handler: ExtensionHandler<UserPythonEvent, UserPythonEventResult>): void;
+    /**
+     * Register capability-scoped middleware on the authoritative ExtensionRunner.
+     * The host supplies grants; an extension cannot self-grant capabilities.
+     * Wildcard registrations receive a redacted payload unless the host explicitly
+     * grants a tool inspection/transform capability.
+     */
+    registerFunctionHook<T extends FunctionHookEventType>(event: T, handler: FunctionHook<FunctionHookPayloadFor<T>>, options?: FunctionHookRegistrationOptions): void;
     /** Register a tool that the LLM can call. */
     registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
     /** Register a custom command. */
@@ -1157,6 +1170,8 @@ export interface ExtensionContextActions {
     getJobs?: () => unknown;
     /** Subscribe to foreground-wait folds so the SDK host can publish `bash_folded`. Returns an unsubscribe. */
     onJobFold?: (listener: (event: JobFoldEvent) => void) => () => void;
+    /** Ordered, synchronous AgentSession subscription, independent of async extension hooks. */
+    onSessionEvent?: (listener: AgentSessionEventListener) => () => void;
     setSdkPermissionProvider?: (provider: ((toolCall: ClientBridgePermissionToolCall, options: ClientBridgePermissionOption[], signal?: AbortSignal) => Promise<ClientBridgePermissionOutcome>) | undefined) => void;
     setSdkClientBridge?: (bridge: ClientBridge | undefined) => void;
     sdkControl?: (operation: string, input: Record<string, unknown>) => unknown | Promise<unknown>;
@@ -1214,6 +1229,7 @@ export interface Extension {
     flags: Map<string, ExtensionFlag>;
     shortcuts: Map<KeyId, ExtensionShortcut>;
 }
+export type { FunctionHook, FunctionHookAuditRecord, FunctionHookCapabilities, FunctionHookCapability, FunctionHookEventType, FunctionHookGrant, FunctionHookGrantInput, FunctionHookNext, FunctionHookOperation, FunctionHookPayloadFor, FunctionHookProvenance, FunctionHookRegistration, FunctionHookRegistrationOptions, FunctionHookResult, } from "./function-hooks";
 /** Result of loading extensions. */
 export interface LoadExtensionsResult {
     extensions: Extension[];

package/dist/types/extensibility/extensions/wrapper.d.ts

@@ -2,7 +2,7 @@
  * Tool wrappers for extensions.
  */
 import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@gajae-code/agent-core";
-import type { Static, TSchema } from "@gajae-code/ai/core";
+import { type Static, type TSchema } from "@gajae-code/ai/core";
 import type { ExtensionRunner } from "./runner";
 import type { RegisteredTool } from "./types";
 /**
@@ -44,6 +44,8 @@ export declare class ExtensionToolWrapper<TParameters extends TSchema = TSchema,
     label: string;
     strict: boolean;
     constructor(tool: AgentTool<TParameters, TDetails>, runner: ExtensionRunner);
+    /** Host composition hook: guards must run inside Function Hook preflight. */
+    getInnerTool(): AgentTool<TParameters, TDetails>;
     /**
      * Forward browser mode changes when available.
      */

package/dist/types/extensibility/gjc-plugins/constrained-hooks.d.ts

@@ -1,3 +1,4 @@
+import { type FunctionHookGrant } from "../extensions/function-hooks";
 import { type SessionQuarantine } from "./session-validation";
 import { type GjcPluginScope } from "./types";
 /**
@@ -11,10 +12,23 @@ import { type GjcPluginScope } from "./types";
  */
 export interface ConstrainedPluginHook {
     plugin: string;
+    scope?: GjcPluginScope;
+    extensionId?: string;
     event: string;
     target?: string;
     phase?: "before" | "after";
-    handler: (...args: any[]) => unknown;
+    handler: (...args: never[]) => unknown;
+    grant?: FunctionHookGrant;
+    provenance?: {
+        source: "plugin-bundle";
+        scope: GjcPluginScope;
+        plugin: string;
+        path: string;
+        extensionId: string;
+        activationGeneration?: number;
+    };
+    functionHook?: boolean;
+    activationGeneration?: number;
 }
 export interface ConstrainedHookLoadResult {
     hooks: ConstrainedPluginHook[];
@@ -23,21 +37,39 @@ export interface ConstrainedHookLoadResult {
 export interface DeclaredHook {
     plugin: string;
     scope: GjcPluginScope;
+    extensionId?: string;
     event: string;
     target?: string;
     phase?: "before" | "after";
     relativePath: string;
     implementationHash?: string;
+    capabilities?: string[];
+    networkDestinations?: string[];
+    filesystemRoots?: string[];
+    capabilityHash?: string;
+    pluginRoot?: string;
+    functionHook?: boolean;
+    activationGeneration?: number;
 }
 /** Lazy declaration for one constrained hook. Importing this descriptor is metadata-only. */
 export declare class ConstrainedPluginHookDescriptor {
     readonly plugin: string;
-    readonly scope: GjcPluginScope;
+    readonly scope?: GjcPluginScope;
+    readonly extensionId?: string;
     readonly event: string;
     readonly target?: string;
     readonly phase?: "before" | "after";
     readonly relativePath: string;
     readonly implementationHash?: string;
+    readonly capabilities?: string[];
+    readonly networkDestinations?: string[];
+    readonly filesystemRoots?: string[];
+    readonly capabilityHash?: string;
+    readonly pluginRoot?: string;
+    readonly grant: FunctionHookGrant;
+    readonly functionHook: boolean;
+    readonly activationGeneration?: number;
+    readonly persistedFunctionHook?: unknown;
     constructor(input: DeclaredHook);
     load(): Promise<ConstrainedPluginHook>;
 }
@@ -48,4 +80,5 @@ export declare class ConstrainedPluginHookDescriptor {
  */
 export declare function loadConstrainedPluginHooks(input: {
     cwd: string;
+    activationGeneration?: number;
 }): Promise<ConstrainedHookLoadResult>;

package/dist/types/extensibility/gjc-plugins/types.d.ts

@@ -1,4 +1,5 @@
 import type { CanonicalGjcWorkflowSkill } from "../../skill-state/active-state";
+import type { FunctionHookCapability } from "../extensions/function-hooks";
 export declare const GJC_PLUGIN_MANIFEST_FILENAME = "gajae-plugin.json";
 export declare const GJC_PLUGIN_KIND = "gajae-code-plugin";
 export declare const GJC_SUBSKILL_PARENT_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "autoresearch"];
@@ -35,6 +36,10 @@ export interface GjcPluginHookManifestEntry {
     phase?: "before" | "after";
     path: string;
     sha256?: string;
+    /** Requested capability families; the runtime never grants more than declared. */
+    capabilities?: FunctionHookCapability[];
+    networkDestinations?: string[];
+    filesystemRoots?: string[];
 }
 export type GjcPluginMcpTransport = "stdio" | "http" | "sse";
 export interface GjcPluginMcpManifestEntry {
@@ -206,6 +211,11 @@ export interface NormalizedHookSurface {
     relativePath: string;
     sha256: string;
     implementationHash?: string;
+    capabilities?: FunctionHookCapability[];
+    networkDestinations?: string[];
+    filesystemRoots?: string[];
+    capabilityHash?: string;
+    functionHook?: boolean;
 }
 export interface NormalizedMcpSurface {
     extensionId: string;
@@ -406,6 +416,21 @@ export interface GjcRuntimeFinding {
     surfaceId: string;
     code: GjcPluginLoadErrorCode;
     message: string;
+    decision?: "loaded" | "quarantined" | "blocked" | "error";
+    event?: string;
+    phase?: "before" | "after";
+    requestedCapabilities?: readonly FunctionHookCapability[];
+    effectiveCapabilities?: readonly FunctionHookCapability[];
+    capabilityHash?: string;
+    provenance?: {
+        source: "builtin" | "user" | "project" | "extension" | "plugin-bundle";
+        scope?: "user" | "project" | "native";
+        plugin?: string;
+        path?: string;
+        extensionId?: string;
+    };
+    audit?: Record<string, unknown>;
+    generation?: number;
 }
 export interface GjcRuntimeSnapshot {
     /** Monotonic activation generation this snapshot describes. */

package/dist/types/extensibility/hooks/types.d.ts

@@ -7,8 +7,11 @@ import type { Theme } from "../../modes/theme/theme";
 import type { HookMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type { BashToolDetails, FindToolDetails, ReadToolDetails, SearchToolDetails } from "../../tools";
+import type { FunctionHook, FunctionHookEventType, FunctionHookPayloadFor, FunctionHookRegistrationOptions } from "../extensions/function-hooks";
 import type { AgentEndEvent, AgentStartEvent, AutoCompactionEndEvent, AutoCompactionStartEvent, AutoRetryEndEvent, AutoRetryStartEvent, ContextEvent, SessionBeforeBranchEvent, SessionBeforeBranchResult, SessionBeforeCompactEvent, SessionBeforeCompactResult, SessionBeforeSwitchEvent, SessionBeforeSwitchResult, SessionBeforeTreeEvent, SessionBeforeTreeResult, SessionBranchEvent, SessionCompactEvent, SessionCompactingEvent, SessionCompactingResult, SessionEvent, SessionShutdownEvent, SessionStartEvent, SessionSwitchEvent, SessionTreeEvent, TodoReminderEvent, ToolCallEventResult, ToolResultEventResult, TtsrTriggeredEvent, TurnEndEvent, TurnStartEvent } from "../shared-events";
 export type { ExecOptions, ExecResult } from "../../exec/exec";
+/** Capability-scoped Function Hooks share the ExtensionRunner event contract. */
+export type { FunctionHook, FunctionHookAuditRecord, FunctionHookCapabilities, FunctionHookCapability, FunctionHookEventType, FunctionHookGrant, FunctionHookGrantInput, FunctionHookNext, FunctionHookOperation, FunctionHookPayloadFor, FunctionHookProvenance, FunctionHookRegistration, FunctionHookRegistrationOptions, FunctionHookResult, } from "../extensions/function-hooks";
 /**
  * UI context for hooks to request interactive UI from the harness.
  * Interactive and headless callers provide their own implementation.
@@ -340,6 +343,7 @@ export interface HookAPI {
     on(event: "todo_reminder", handler: HookHandler<TodoReminderEvent>): void;
     on(event: "tool_call", handler: HookHandler<ToolCallEvent, ToolCallEventResult>): void;
     on(event: "tool_result", handler: HookHandler<ToolResultEvent, ToolResultEventResult>): void;
+    registerFunctionHook<T extends FunctionHookEventType>(event: T, handler: FunctionHook<FunctionHookPayloadFor<T>>, options?: FunctionHookRegistrationOptions): void;
     /**
      * Send a custom message to the session. Creates a CustomMessageEntry that
      * participates in LLM context and can be displayed in the TUI.

package/dist/types/extensibility/runtime-skill-discovery.d.ts

@@ -24,6 +24,9 @@ export interface RuntimeSkillDiscoveryResult {
 export interface DiscoverRuntimeSkillsOptions {
     cwd: string;
     home?: string;
+    agentDir?: string;
+    /** Resolver-owned profile classification; unlike path comparison, this survives HOME refreshes. */
+    profileAuthority?: "default" | "custom";
     query?: string;
     limit?: number;
     source?: RuntimeSkillDiscoverySource | "all";
@@ -38,4 +41,4 @@ export interface DiscoverRuntimeSkillsOptions {
  */
 export declare function describeDisabledSkillScopes(source: RuntimeSkillDiscoverySource | "all", policy: SkillsSettings | undefined): string | undefined;
 export declare function discoverRuntimeSkills(options: DiscoverRuntimeSkillsOptions): Promise<RuntimeSkillDiscoveryResult>;
-export declare function findRuntimeSkillByName(cwd: string, name: string, policy?: SkillsSettings, home?: string): Promise<Skill | undefined>;
+export declare function findRuntimeSkillByName(cwd: string, name: string, policy?: SkillsSettings, home?: string, agentDir?: string, profileAuthority?: "default" | "custom"): Promise<Skill | undefined>;

package/dist/types/extensibility/skill-management.d.ts

@@ -32,6 +32,7 @@ export interface ConventionSkillImportSource {
 export interface WriteNativeSkillInput {
     cwd: string;
     home?: string;
+    agentDir?: string;
     scope: SkillScope;
     name: string;
     content: string;
@@ -61,13 +62,14 @@ export declare function getProjectSkillDirs(cwd: string, home: string): Promise<
     repoRoot: string | null;
 }>;
 /** Canonical user skill directories in precedence order (same resolution as runtime discovery). */
-export declare function getUserSkillDirs(home: string): string[];
+export declare function getUserSkillDirs(home: string, agentDir?: string, profileAuthority?: "default" | "custom"): string[];
 /**
  * The canonical directory a write targets for a scope: the repo root (or `cwd`)
- * `.gjc/skills` for project scope, the canonical `<config>/agent/skills` user
- * root for user scope (honoring `GJC_CONFIG_DIR` / `PI_CONFIG_DIR`).
+ * `.gjc/skills` for project scope, the agent directory's `skills` root for user
+ * scope — the same directory every reader scans first (`gjc config path` prints
+ * it; `--agent-dir` / `GJC_CODING_AGENT_DIR` / `setAgentDir()` move it).
  */
-export declare function resolveNativeSkillScopeDir(cwd: string, scope: SkillScope, home?: string): Promise<string>;
+export declare function resolveNativeSkillScopeDir(cwd: string, scope: SkillScope, _home?: string, agentDir?: string): Promise<string>;
 /**
  * Authoritative discovery of native skills with provenance and enablement
  * state. Unlike runtime session discovery, this lists every scanned skill —
@@ -77,6 +79,9 @@ export declare function resolveNativeSkillScopeDir(cwd: string, scope: SkillScop
 export declare function listNativeSkillsForManagement(options: {
     cwd: string;
     home?: string;
+    agentDir?: string;
+    /** Resolver-owned profile classification; unlike path comparison, this survives HOME refreshes. */
+    profileAuthority?: "default" | "custom";
     policy?: SkillManagementPolicy;
 }): Promise<ManagedSkillRecord[]>;
 /**

package/dist/types/extensibility/skills.d.ts

@@ -57,6 +57,8 @@ export interface LoadSkillsOptions extends SkillsSettings {
     home?: string;
     /** Explicit user agent directory for native user-scope skill discovery. */
     agentDir?: string;
+    /** Resolver-owned classification for the selected agent directory. */
+    profileAuthority?: "default" | "custom";
 }
 /**
  * Load skills from all configured locations.

package/dist/types/gjc-runtime/empty-delete-gc.d.ts

@@ -13,7 +13,7 @@ export interface EmptyDeleteIdentity {
     mtimeNs: bigint;
     parentDev: bigint;
     parentIno: bigint;
-    sha256: string;
+    sha256?: string;
 }
 export interface EmptyDeleteGcRecord {
     root: string;
@@ -44,11 +44,14 @@ export interface EmptyDeleteGcReport {
 export interface EmptyDeleteGcOptions {
     roots: string[];
     prune: boolean;
+    /** Disk artifact GC must not remove unrelated file receipts. */
+    artifactRootsOnly?: boolean;
 }
 export interface EmptyDeleteGcDependencies {
     /** Internal seam for deterministic collect-to-prune race tests. */
     collect?: (root: string) => Promise<EmptyDeleteGcRecord[]>;
     exactUnlinkDirect?: typeof exactUnlinkDirect;
+    rmdir?: (directory: string) => Promise<void>;
 }
 export declare function collectEmptyDeleteReceipts(root: string, deps?: {
     lstat?: (file: string, options: {

package/dist/types/gjc-runtime/linux-proc.d.ts

@@ -26,6 +26,8 @@ export declare function parseLinuxProcStartTime(stat: string | null | undefined)
 export declare function parseLinuxProcTtyDevice(stat: string | null | undefined): string | null;
 /** Parse field 3 (single-letter process state) from a `/proc/<pid>/stat` record. */
 export declare function parseLinuxProcState(stat: string | null | undefined): string | null;
+/** Parse field 4 (`ppid`) from a `/proc/<pid>/stat` record. */
+export declare function parseLinuxProcParentPid(stat: string | null | undefined): number | null;
 export declare function probeLinuxProcPidSync(pid: number): LinuxProcPidProbeResult;
 export declare function probeLinuxProcPid(pid: number): Promise<LinuxProcPidProbeResult>;
 /**

package/dist/types/gjc-runtime/session-state-lock.d.ts

@@ -170,4 +170,16 @@ export declare function reclaimStaleSessionStateLock(lockFile: string, quarantin
  * lock file itself and may run for as long as it needs.
  */
 export declare function withSessionStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * Try one admission without joining a live owner's queue or backing off on contention.
+ * A stale reclaim may return `acquired: false` after making the next attempt possible.
+ * Once admitted, the operation and identity-safe release use the normal lock protocol;
+ * their failures propagate rather than being reported as contention.
+ */
+export declare function tryWithSessionStateFileLock<T>(stateFile: string, operation: () => Promise<T>): Promise<{
+    acquired: true;
+    value: T;
+} | {
+    acquired: false;
+}>;
 export {};

package/dist/types/gjc-runtime/ultragoal-runtime.d.ts

@@ -208,7 +208,36 @@ export declare function recordUltragoalNudgeIfBudgetRemaining(input: {
     reason: string;
     currentGoalObjective?: string;
 }): Promise<UltragoalNudgeOutcome>;
-export declare function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void>;
+export declare function writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null, 
+/** Set by callers already inside {@link withUltragoalPlanOwnership} for this plan. */
+options?: {
+    lockHeld?: boolean;
+}): Promise<void>;
+/**
+ * The single exclusion that decides who owns an Ultragoal run (#5353).
+ *
+ * Establishing ownership is a read-decide-write sequence, not a write: a start
+ * reads the plan, checks the outgoing succession fence, then commits `active`.
+ * Checking quiescence at a point in time and writing afterwards is not enough —
+ * an offer can observe `pending` in the window between an in-flight start's
+ * check and its commit, and both runs then believe they own the goal.
+ *
+ * Every caller that decides ownership — source admission (`start`/`checkpoint`),
+ * succession offer/fence issuance, and successor publication — runs its whole
+ * decision inside this lock, keyed on the plan it is deciding about, and
+ * re-reads the plan under it. Writers inside pass `lockHeld` because
+ * `withFileLock` intentionally serializes same-process callers as well.
+ *
+ * Lock ordering: this lock is always taken BEFORE any ledger lock. The existing
+ * ledger-scoped critical sections (nudge budget, critic verdict, critic gate
+ * override) never write the plan, so no cycle exists.
+ */
+export declare function withUltragoalPlanOwnership<T>(cwd: string, sessionId: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Resolve the session whose plan ownership is being decided, without changing
+ * the resolution behaviour callers already depend on.
+ */
+export declare function resolveUltragoalOwnershipSession(cwd: string, sessionId?: string | null): Promise<string>;
 export declare function nonEmptyString(value: unknown): string | null;
 export declare function stringArray(value: unknown): string[] | null;
 export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
@@ -324,13 +353,22 @@ export declare function validateUltragoalQualityGateReadOnly(input: {
     valid: boolean;
     errors: readonly UltragoalQualityGateDiagnostic[];
 }>;
-export declare function checkpointUltragoalGoal(input: {
+export interface UltragoalCheckpointInput {
     cwd: string;
     goalId: string;
     status: UltragoalGoalStatus;
     evidence: string;
     qualityGateJson?: string;
-}): Promise<UltragoalPlan>;
+}
+/**
+ * Checkpointing shares its plan with a succession offer, but only its *commit*
+ * is fenced against one (#5353). Completion validation must observe the same
+ * repository basis `quality-gate source-hash` did, and the ownership lock's own
+ * on-disk artifact lives under `.gjc/` — a path repositories are not required to
+ * ignore — so capturing the basis while holding it would make the runtime digest
+ * disagree with the gate the caller was told to produce.
+ */
+export declare function checkpointUltragoalGoal(input: UltragoalCheckpointInput): Promise<UltragoalPlan>;
 export interface UltragoalCheckpointContinuation {
     plan: UltragoalPlan;
     checkpointedGoal: UltragoalGoal;