@gajae-code/coding-agent 0.16.3 → 0.16.6

package/dist/types/exec/bash-shell-supervisor.d.ts

@@ -0,0 +1,10 @@
+import { type BashShellWorkerResponse } from "./bash-shell-worker-protocol";
+export declare function createUtf8LineDecoder(onLine: (line: string) => void, options?: {
+    maxBufferedBytes?: number;
+    onOverflow?: () => void;
+}): {
+    push(chunk: Uint8Array): void;
+    end(): void;
+};
+export declare function parseAuthenticatedWorkerResponse(line: string, protocolToken: string | undefined): BashShellWorkerResponse | undefined;
+export declare function runBashShellSupervisor(): Promise<void>;

package/dist/types/exec/bash-shell-worker-entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/types/exec/bash-shell-worker-protocol.d.ts

@@ -0,0 +1,63 @@
+import type { MinimizerOptions, ShellOptions, ShellRunOptions, ShellRunResult } from "@gajae-code/natives";
+export declare const BASH_SHELL_WORKER_ARG = "--internal-bash-shell-worker";
+export declare const BASH_SHELL_SUPERVISOR_ARG = "--internal-bash-shell-supervisor";
+export declare const BASH_SHELL_RUNTIME_ARG = "--internal-bash-shell-runtime";
+export type IsolatedShellOptions = Pick<ShellOptions, "sessionEnv" | "snapshotPath"> & {
+    minimizer?: MinimizerOptions;
+    containedProcessGroup?: boolean;
+};
+export type IsolatedShellRunOptions = Omit<ShellRunOptions, "signal">;
+export type IsolatedShellRunResult = ShellRunResult & {
+    /** POSIX signal that terminated the isolated shell worker, when applicable. */
+    signal?: string;
+};
+export type BashShellWorkerRequest = {
+    type: "init";
+    token: string;
+    options?: IsolatedShellOptions;
+    ownershipLedger?: {
+        path: string;
+        token: string;
+    };
+} | {
+    type: "run";
+    token: string;
+    id: number;
+    options: IsolatedShellRunOptions;
+} | {
+    type: "abort";
+    token: string;
+    id: number;
+} | {
+    type: "close";
+    token: string;
+    id: number;
+};
+export type BashShellWorkerResponse = {
+    type: "ready";
+    token: string;
+    supervisorPid?: number;
+} | {
+    type: "chunk";
+    token: string;
+    id: number;
+    chunk: string;
+} | {
+    type: "result";
+    token: string;
+    id: number;
+    result: IsolatedShellRunResult;
+} | {
+    type: "void";
+    token: string;
+    id: number;
+} | {
+    type: "retiring";
+    token: string;
+    message: string;
+} | {
+    type: "error";
+    token: string;
+    id?: number;
+    message: string;
+};

package/dist/types/exec/bash-shell-worker.d.ts

@@ -0,0 +1 @@
+export declare function runBashShellWorker(): Promise<void>;

package/dist/types/exec/isolated-shell.d.ts

@@ -0,0 +1,19 @@
+import type { ShellRunOptions } from "@gajae-code/natives";
+import { type IsolatedShellOptions, type IsolatedShellRunResult } from "./bash-shell-worker-protocol";
+export interface IsolatedShellLifecycle {
+    onTerminal?: (shell: IsolatedShell) => void;
+    workerArgv?: string[];
+}
+export declare class IsolatedShell {
+    #private;
+    constructor(options?: IsolatedShellOptions, lifecycle?: IsolatedShellLifecycle);
+    isTerminal(): boolean;
+    ready(): Promise<void>;
+    supervisorPid(): number | undefined;
+    isRunSignalActive(signal: AbortSignal): boolean;
+    wasRunSignalDispatched(signal: AbortSignal): boolean;
+    run(options: ShellRunOptions, onChunk?: (error: Error | null, chunk: string) => void): Promise<IsolatedShellRunResult>;
+    abort(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function smokeTestIsolatedShell(): Promise<void>;

package/dist/types/extensibility/extensions/function-hooks-internal.d.ts

@@ -0,0 +1,9 @@
+import { type FunctionHookRegistration } from "./function-hooks";
+export type TaggedFunctionHookHandler = (...args: unknown[]) => Promise<unknown>;
+export declare function tagExtensionHandlerRegistrationOrder<T extends (...args: never[]) => unknown>(handler: T, registrationOrder: number): T;
+export declare function wrapExtensionHandlerRegistration<T extends (...args: never[]) => unknown>(handler: T, registrationOrder: number): T;
+export declare function getExtensionHandlerRegistrationOrder(value: unknown): number | undefined;
+export declare function tagFunctionHookHandler(registration: FunctionHookRegistration): TaggedFunctionHookHandler;
+export declare function getFunctionHookRegistration(value: unknown): FunctionHookRegistration | undefined;
+/** Host-only root-confined read used by the mediated filesystem capability. */
+export declare function readConstrainedFunctionHookFile(filePath: string, cwd: string, roots: readonly string[]): Promise<string>;

package/dist/types/extensibility/extensions/function-hooks.d.ts

@@ -0,0 +1,169 @@
+import type { ImageContent, TextContent } from "@gajae-code/ai/core";
+import type { CustomMessage } from "../../session/messages";
+import type { ExtensionEvent, ExtensionSessionMetadata, ExtensionUIContext } from "./types";
+/** Function hooks use the existing extension event stream; `*` is observation middleware. */
+export type FunctionHookEventType = ExtensionEvent["type"] | "*";
+export type FunctionHookPayloadFor<T extends FunctionHookEventType> = T extends "*" ? ExtensionEvent : Extract<ExtensionEvent, {
+    type: T;
+}>;
+/** Narrow capability vocabulary. Parent names expand only to their children. */
+export type FunctionHookCapability = "tool" | "tool.inspect" | "tool.transform" | "tool.deny" | "ui" | "ui.status" | "ui.widget" | "ui.notify" | "ui.transform" | "session" | "session.read" | "session.message" | "session.deny" | "audit" | "audit.append" | "network" | "network.fetch" | "filesystem" | "filesystem.read";
+export declare const FUNCTION_HOOK_CAPABILITIES: readonly FunctionHookCapability[];
+export type FunctionHookOperation = Exclude<FunctionHookCapability, "tool" | "ui" | "session" | "audit" | "network" | "filesystem">;
+export interface FunctionHookGrantInput {
+    capabilities?: readonly FunctionHookCapability[];
+    networkDestinations?: readonly string[];
+    filesystemRoots?: readonly string[];
+    /** An attenuation boundary can only remove downstream operations. */
+    attenuateDownstream?: readonly FunctionHookCapability[];
+}
+export interface FunctionHookGrant {
+    readonly capabilities: readonly FunctionHookCapability[];
+    readonly networkDestinations: readonly string[];
+    readonly filesystemRoots: readonly string[];
+    readonly attenuateDownstream?: readonly FunctionHookCapability[];
+}
+export interface FunctionHookRegistrationOptions extends FunctionHookGrantInput {
+    target?: string;
+    registrationId?: string;
+}
+export interface FunctionHookProvenance {
+    readonly source: "builtin" | "user" | "project" | "extension" | "plugin-bundle";
+    readonly scope?: "user" | "project" | "native";
+    readonly plugin?: string;
+    readonly extensionId?: string;
+    readonly path: string;
+    readonly activationGeneration?: number;
+}
+export interface FunctionHookInvocation<TEvent extends ExtensionEvent = ExtensionEvent> {
+    readonly eventId: string;
+    readonly correlationId: string;
+    readonly eventType: TEvent["type"];
+    readonly provenance: FunctionHookProvenance;
+    readonly registrationOrder: number;
+    readonly payload: Readonly<TEvent>;
+    readonly signal: AbortSignal;
+}
+export interface FunctionHookMessage {
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display?: boolean;
+    details?: unknown;
+    attribution?: CustomMessage["attribution"];
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp";
+}
+export interface FunctionHookAuditRecord {
+    readonly sequence: number;
+    readonly eventId: string;
+    readonly correlationId: string;
+    readonly eventType: string;
+    readonly action: "continue" | "deny" | "return" | "error" | "timeout";
+    readonly registrationOrder: number;
+    readonly provenance: {
+        source: FunctionHookProvenance["source"];
+        scope?: FunctionHookProvenance["scope"];
+        plugin?: string;
+        extensionId?: string;
+        path: string;
+    };
+    readonly reason?: string;
+    readonly payloadHash?: string;
+    readonly evidence?: unknown;
+    readonly requestedCapabilities?: readonly FunctionHookCapability[];
+    readonly effectiveCapabilities?: readonly FunctionHookCapability[];
+    readonly capabilityHash?: string;
+    readonly activationGeneration?: number;
+}
+export interface FunctionHookCapabilities {
+    readonly tool?: {
+        readonly canInspect: boolean;
+        readonly canTransform: boolean;
+        readonly canDeny: boolean;
+    };
+    readonly ui?: {
+        readonly canTransform: boolean;
+        readonly setStatus: (key: string, text: string | undefined) => void;
+        readonly setWidget: (key: string, content: string[] | undefined) => void;
+        readonly notify: (message: string, type?: "info" | "warning" | "error") => void;
+    };
+    readonly session?: {
+        readonly canRead: boolean;
+        readonly canDeny: boolean;
+        readonly metadata: Readonly<ExtensionSessionMetadata> | undefined;
+        readonly emitMessage: (message: FunctionHookMessage, options?: {
+            triggerTurn?: boolean;
+            deliverAs?: "steer" | "followUp";
+        }) => void;
+    };
+    readonly audit?: {
+        readonly append: (evidence: Record<string, unknown>) => void;
+    };
+    readonly network?: {
+        readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    };
+    readonly filesystem?: {
+        readonly readFile: (filePath: string) => Promise<string>;
+    };
+}
+export type FunctionHookResult<TEvent extends ExtensionEvent = ExtensionEvent> = {
+    action: "continue";
+    event?: TEvent;
+} | {
+    action: "deny";
+    reason: string;
+} | {
+    action: "return";
+    value: unknown;
+};
+export type FunctionHookNext<TEvent extends ExtensionEvent = ExtensionEvent> = (event?: TEvent) => Promise<FunctionHookResult<TEvent>>;
+export type FunctionHook<TEvent extends ExtensionEvent = ExtensionEvent> = (invocation: FunctionHookInvocation<TEvent>, capabilities: FunctionHookCapabilities, next: FunctionHookNext<TEvent>) => FunctionHookResult<TEvent> | undefined | Promise<FunctionHookResult<TEvent> | undefined>;
+export interface FunctionHookRegistration {
+    readonly event: FunctionHookEventType;
+    readonly target?: string;
+    readonly registrationId?: string;
+    readonly handler: FunctionHook;
+    readonly grant: FunctionHookGrant;
+    readonly provenance: FunctionHookProvenance;
+    readonly registrationOrder?: number;
+}
+export declare function validateFunctionHookTarget(target: string): string;
+export declare function normalizeFunctionHookGrant(input?: FunctionHookGrantInput): FunctionHookGrant;
+export declare function compatibilityFunctionHookGrant(event: string): FunctionHookGrant;
+export declare function functionHookGrantOperations(grant: FunctionHookGrant): ReadonlySet<FunctionHookOperation>;
+export declare function intersectFunctionHookGrants(grant: FunctionHookGrant, allowed: FunctionHookGrant | undefined): FunctionHookGrant;
+/** Host-owned ceiling for caller-registered in-process extension and hook middleware. */
+export declare const DEFAULT_EXTENSION_FUNCTION_HOOK_GRANT: FunctionHookGrant;
+export declare function attenuateFunctionHookGrant(grant: FunctionHookGrant, removed: readonly FunctionHookCapability[] | undefined): FunctionHookGrant;
+export declare function functionHookGrantHash(grant: FunctionHookGrant): string;
+/** Bounded JSON-shaped redaction for diagnostics and audit sinks. Accessors are never invoked. */
+export declare function redactFunctionHookValue(value: unknown, depth?: number, seen?: WeakSet<object>): unknown;
+export declare function functionHookPayloadHash(value: unknown): string;
+export declare function isPlainFunctionHookData(value: unknown, seen?: WeakSet<object>): boolean;
+export declare function isSafeFunctionHookValue(value: unknown, seen?: WeakSet<object>): boolean;
+export declare function isValidFunctionHookEventValue(event: ExtensionEvent): boolean;
+export declare function functionHookEventIdentityMatches(original: ExtensionEvent, candidate: ExtensionEvent): boolean;
+export declare function cloneFunctionHookData<T>(value: T): T;
+/** Security-boundary clone for transformed events; never aliases caller-owned data. */
+export declare function cloneFunctionHookDataStrict<T>(value: T): T;
+export interface FunctionHookCapabilityBindings {
+    readonly cwd: string;
+    readonly ui: ExtensionUIContext;
+    readonly sessionMetadata?: ExtensionSessionMetadata;
+    readonly isActive?: () => boolean;
+    readonly emitMessage: (message: FunctionHookMessage, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp";
+    }) => void;
+    readonly appendAudit: (evidence: Record<string, unknown>) => void;
+    readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    readonly readFile: (filePath: string, roots: readonly string[]) => Promise<string>;
+}
+export declare function createFunctionHookCapabilities(grant: FunctionHookGrant, bindings: FunctionHookCapabilityBindings): FunctionHookCapabilities;
+export declare function compatibilityPayloadForFunctionHook(event: ExtensionEvent, grant: FunctionHookGrant, wildcard: boolean): ExtensionEvent;
+export declare function functionHookInspectAllowed(event: ExtensionEvent, grant: FunctionHookGrant, wildcard: boolean): boolean;
+export declare function functionHookTransformAllowed(event: ExtensionEvent, grant: FunctionHookGrant): boolean;
+export declare function functionHookDenyAllowed(event: ExtensionEvent, grant: FunctionHookGrant): boolean;
+export declare function sanitizeFunctionHookReason(reason: unknown, fallback: string): string;
+/** Validate terminal short-circuit values before they enter event-specific host control flow. */
+export declare function isValidFunctionHookReturnValue(event: ExtensionEvent, value: unknown): boolean;

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/mcp-policy.d.ts

@@ -16,6 +16,22 @@ export declare function assertDnsResolvesPublic(hostname: string, label?: string
 export interface StdioPolicyContext {
     pluginRoot: string;
 }
+export interface StdioInvocationTarget {
+    kind: "launcher";
+    launcher: "node" | "bun";
+    entrypoint: string;
+    executablePath: string;
+    ownedRelativePath: string;
+    ownedRelativePaths: string[];
+    cwd: string;
+}
+/**
+ * Resolve the exact executable file selected by the supported stdio grammar.
+ * Bare Node/Bun launchers accept a direct bundled entrypoint as argv[0]; no
+ * manifest-controlled runtime options or subcommands precede it. Path-qualified
+ * commands are unsupported because they bypass the verified module wrapper.
+ */
+export declare function classifyStdioInvocation(entry: GjcPluginMcpManifestEntry, ctx: StdioPolicyContext): StdioInvocationTarget;
 /** stdio launcher/path confinement policy. */
 export declare function assertStdioAllowed(entry: GjcPluginMcpManifestEntry, ctx: StdioPolicyContext): void;
 /**

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

@@ -1,5 +1,7 @@
 export declare function gjcPluginUserRoot(): string;
 export declare function gjcPluginProjectRoot(cwd: string): string;
+export declare function gjcPluginSafeDirectoryName(name: string): string;
+export declare function gjcPluginInstallRoot(scope: "user" | "project", cwd: string, name: string): string;
 export declare function rootContainsGjcManifest(dir: string): Promise<boolean>;
 export declare function discoverGjcPluginRoots({ cwd }: {
     cwd: string;

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.