@code-yeongyu/senpi 2026.11.10-1 → 2026.11.10-3

package/dist/core/extensions/builtin/mcp/catalog.js

@@ -3,7 +3,8 @@ import { isModernMcpClient } from "./modern/request.js";
 import { hasSupportedModernToolSchemas } from "./modern/tool-schema.js";
 import { collectAllPages } from "./expose/pagination.js";
 export async function collectToolCatalog(server, connection, config, options = {}) {
-    const result = await collectAllPages((cursor) => listMcpTools(connection.client, cursor === undefined ? {} : { cursor }, { timeout: config.requestTimeoutMs }));
+    const client = connection.client;
+    const result = await collectAllPages((cursor) => listMcpTools(client, cursor === undefined ? {} : { cursor }, { timeout: config.requestTimeoutMs }));
     return result.items.map((tool) => ({
         requestOrigin: options.requestOrigin,
         annotations: tool.annotations,
@@ -17,7 +18,7 @@ export async function collectToolCatalog(server, connection, config, options = {
         requestTimeoutMs: config.requestTimeoutMs,
         schema: tool.inputSchema,
         outputSchema: tool.outputSchema,
-        modern: isModernMcpClient(connection.client),
+        modern: isModernMcpClient(client),
         server,
         tool: tool.name,
     }));

package/dist/core/extensions/builtin/mcp/invocation.js

@@ -61,6 +61,12 @@ export function createMcpInvocationResolver(scope) {
             try {
                 await Promise.race([ready, interrupted]);
             }
+            catch (error) {
+                readySignal.throwIfAborted();
+                if (!scope.isCurrent())
+                    return refuse("unavailable", "MCP session or server configuration was replaced.");
+                throw error;
+            }
             finally {
                 clearTimeout(timeout);
                 readySignal.removeEventListener("abort", abort);

package/dist/core/extensions/builtin/mcp/service-register.js

@@ -3,7 +3,7 @@ import { computeMcpExposurePolicy } from "./expose/policy.js";
 import { registerDirectMcpTools } from "./expose/session.js";
 import { ensureMcpToolCallConnection } from "./health.js";
 import { createMcpInvocationResolver } from "./invocation.js";
-import { connectAndRefreshMcpCatalog } from "./startup-race.js";
+import { connectAndRefreshMcpCatalog, prepareMcpAuthentication } from "./startup-race.js";
 export async function registerMcpServiceDirectTools(pi, config, entries, toolSearchService, options = {}) {
     return await registerDirectMcpTools(pi, config, [...entries].map((entry) => {
         const serverConfig = config.servers[entry.name]?.config;
@@ -18,7 +18,21 @@ export async function registerMcpServiceDirectTools(pi, config, entries, toolSea
             servesSession: options.servesSession,
             isCurrent: () => entry.isCurrent?.() !== false && options.isCurrent?.(entry) !== false,
             ready: async () => {
-                await ensureMcpToolCallConnection(entry.connection, () => entry.authPlan?.refresh?.ensureFresh().then(() => undefined) ?? Promise.resolve());
+                if (!(await prepareMcpAuthentication(entry)))
+                    return;
+                if (entry.isCurrent?.() === false || options.isCurrent?.(entry) === false)
+                    return;
+                if (entry.credentialsCurrent?.() === false) {
+                    await entry.onCredentialsChanged?.();
+                    return;
+                }
+                await ensureMcpToolCallConnection(entry.connection);
+                if (entry.isCurrent?.() === false || options.isCurrent?.(entry) === false)
+                    return;
+                if (entry.credentialsCurrent?.() === false) {
+                    await entry.onCredentialsChanged?.();
+                    return;
+                }
                 await connectAndRefreshMcpCatalog(entry, serverConfig);
                 await entry.startupCatalogClaim?.settled();
                 if (entry.isCurrent?.() === false || options.isCurrent?.(entry) === false)

package/dist/core/extensions/builtin/mcp/service-tools-changed.js

@@ -54,71 +54,78 @@ export async function refreshMcpToolsOnListChanged(entry, targets, config, conne
     // The startup connect that still owns registration registers its refreshed catalog itself.
     if (connectOnly && entry.startupCatalogClaim?.ownsRegistration() === true)
         return;
-    const registeredCatalog = entry.cachedCatalog;
-    if (entry.connection instanceof SharedMcpLease) {
-        const refreshed = await entry.connection.catalog();
-        if (!ownsCatalog())
-            return;
-        entry.cachedCatalog = refreshed;
-    }
-    const catalog = await collectToolCatalog(entry.name, entry.connection, server.config, {
-        agentDir: entry.agentDir,
-        outputGuard: config.settings.outputGuard,
-    });
-    if (!ownsCatalog())
-        return;
-    const newNames = mapMcpCatalogNames(catalog).map(({ name }) => name);
-    // Before the first refresh, the registered names are the catalog the startup pass registered.
-    const knownNames = entry.knownToolNames ??
-        (registeredCatalog === undefined
-            ? newNames
-            : mapMcpCatalogNames(cachedToolsToCatalogEntries(entry.name, registeredCatalog, entry.connection, server.config.requestTimeoutMs, async () => { })).map(({ name }) => name));
-    const diff = diffMcpToolNames(knownNames, newNames);
-    const identity = mcpRegistrationIdentity(catalog, entry.cachedCatalog);
-    const initial = targets();
-    const stale = connectOnly ? initial.filter((target) => target.registeredIdentity() !== identity) : initial;
-    if (stale.length > 0) {
-        // Registration reads entry.cachedCatalog. A shared lease refreshed it above; nothing else
-        // refreshes a non-shared connection's catalog after its startup connect (#2188).
-        if (!(entry.connection instanceof SharedMcpLease)) {
-            const refreshed = await collectServerCatalogForCache(entry.connection, server.config, entry.generationHash ?? entry.configHash, entry.credentialIdentity);
+    try {
+        const registeredCatalog = entry.cachedCatalog;
+        if (entry.connection instanceof SharedMcpLease) {
+            const refreshed = await entry.connection.catalog();
             if (!ownsCatalog())
                 return;
             entry.cachedCatalog = refreshed;
-            await writeMcpCachedServer(entry.agentDir, entry.name, refreshed, ownsCatalog);
         }
+        const catalog = await collectToolCatalog(entry.name, entry.connection, server.config, {
+            agentDir: entry.agentDir,
+            outputGuard: config.settings.outputGuard,
+        });
         if (!ownsCatalog())
             return;
-        // Tombstone removed tools BEFORE re-registration so the subsequent
-        // setActiveTools (which excludes them) leaves the tombstones inactive.
-        const seen = new Set(initial.map((target) => target.pi));
-        const failures = [];
-        let pending = stale;
-        while (pending.length > 0) {
-            for (const target of pending) {
+        const newNames = mapMcpCatalogNames(catalog).map(({ name }) => name);
+        // Before the first refresh, the registered names are the catalog the startup pass registered.
+        const knownNames = entry.knownToolNames ??
+            (registeredCatalog === undefined
+                ? newNames
+                : mapMcpCatalogNames(cachedToolsToCatalogEntries(entry.name, registeredCatalog, entry.connection, server.config.requestTimeoutMs, async () => { })).map(({ name }) => name));
+        const diff = diffMcpToolNames(knownNames, newNames);
+        const identity = mcpRegistrationIdentity(catalog, entry.cachedCatalog);
+        const initial = targets();
+        const stale = connectOnly ? initial.filter((target) => target.registeredIdentity() !== identity) : initial;
+        if (stale.length > 0) {
+            // Registration reads entry.cachedCatalog. A shared lease refreshed it above; nothing else
+            // refreshes a non-shared connection's catalog after its startup connect (#2188).
+            if (!(entry.connection instanceof SharedMcpLease)) {
+                const refreshed = await collectServerCatalogForCache(entry.connection, server.config, entry.generationHash ?? entry.configHash, entry.credentialIdentity);
                 if (!ownsCatalog())
                     return;
-                try {
-                    for (const removed of diff.removed)
-                        target.pi.registerTool(buildMcpTombstoneDefinition(removed, entry.name));
-                    await target.register();
-                }
-                catch (error) {
-                    failures.push(error);
+                entry.cachedCatalog = refreshed;
+                await writeMcpCachedServer(entry.agentDir, entry.name, refreshed, ownsCatalog);
+            }
+            if (!ownsCatalog())
+                return;
+            // Tombstone removed tools BEFORE re-registration so the subsequent
+            // setActiveTools (which excludes them) leaves the tombstones inactive.
+            const seen = new Set(initial.map((target) => target.pi));
+            const failures = [];
+            let pending = stale;
+            while (pending.length > 0) {
+                for (const target of pending) {
+                    if (!ownsCatalog())
+                        return;
+                    try {
+                        for (const removed of diff.removed)
+                            target.pi.registerTool(buildMcpTombstoneDefinition(removed, entry.name));
+                        await target.register();
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
                 }
+                // A session that attached during this refresh registered the catalog cached before it.
+                pending = targets().filter((target) => !seen.has(target.pi));
+                for (const target of pending)
+                    seen.add(target.pi);
+            }
+            if (failures.length > 0) {
+                entry.knownToolNames = newNames;
+                entry.lastListChangedDelta = formatMcpListChangedDelta(diff);
+                throw new AggregateError(failures, `MCP ${entry.name} tool refresh failed in ${failures.length} of ${seen.size} session(s)`);
             }
-            // A session that attached during this refresh registered the catalog cached before it.
-            pending = targets().filter((target) => !seen.has(target.pi));
-            for (const target of pending)
-                seen.add(target.pi);
-        }
-        if (failures.length > 0) {
-            entry.knownToolNames = newNames;
-            entry.lastListChangedDelta = formatMcpListChangedDelta(diff);
-            throw new AggregateError(failures, `MCP ${entry.name} tool refresh failed in ${failures.length} of ${seen.size} session(s)`);
         }
+        entry.knownToolNames = newNames;
+        entry.lastListChangedDelta = formatMcpListChangedDelta(diff);
+    }
+    catch (error) {
+        if (!ownsCatalog())
+            return;
+        throw error;
     }
-    entry.knownToolNames = newNames;
-    entry.lastListChangedDelta = formatMcpListChangedDelta(diff);
 }
 //# sourceMappingURL=service-tools-changed.js.map

package/dist/core/extensions/builtin/mcp/startup-race.d.ts

@@ -43,6 +43,8 @@ export declare class McpDeferredAttach {
 }
 export declare function raceMcpStartupConnect(options: RaceMcpStartupConnectOptions): Promise<void>;
 export declare function connectAndRefreshMcpCatalog(entry: McpConnectionEntry, serverConfig: ResolvedMcpServer["config"]): Promise<void>;
+/** Reconcile the grant before health recovery without attempting a transport connection. */
+export declare function prepareMcpAuthentication(entry: McpConnectionEntry): Promise<boolean>;
 export declare function ignoreStartupNeedsAuth(entry: McpConnectionEntry, connect: Promise<void>): Promise<void>;
 export declare function waitForMcpStartupRace(connect: Promise<void>, deadlineMs?: number): Promise<McpStartupRaceResult>;
 export declare function shouldRaceMcpStartup(lifecycle: "lazy" | "eager" | "keep-alive"): boolean;

package/dist/core/extensions/builtin/mcp/startup-race.js

@@ -91,15 +91,16 @@ export function connectAndRefreshMcpCatalog(entry, serverConfig) {
     void refresh.then(finish, finish);
     return refresh;
 }
-async function refreshConnectedMcpCatalog(entry, serverConfig) {
-    if (serverConfig === undefined || entry.isCurrent?.() === false)
-        return;
+/** Reconcile the grant before health recovery without attempting a transport connection. */
+export async function prepareMcpAuthentication(entry) {
+    if (entry.isCurrent?.() === false)
+        return false;
     try {
         await entry.authPlan?.refresh?.ensureFresh();
     }
     catch (error) {
-        if (entry.connection.state === "disabled")
-            return;
+        if (entry.isCurrent?.() === false || entry.connection.state === "disabled")
+            return false;
         const authError = markMcpConnectionNeedsAuth(entry.connection, error);
         if (authError !== undefined) {
             entry.logger.warn(authError.message);
@@ -107,10 +108,17 @@ async function refreshConnectedMcpCatalog(entry, serverConfig) {
         }
         throw error;
     }
+    if (entry.isCurrent?.() === false)
+        return false;
     if (entry.credentialsCurrent?.() === false) {
         await entry.onCredentialsChanged?.();
-        return;
+        return false;
     }
+    return true;
+}
+async function refreshConnectedMcpCatalog(entry, serverConfig) {
+    if (serverConfig === undefined || !(await prepareMcpAuthentication(entry)))
+        return;
     await connectMcpServer(entry.connection, entry.logger);
     if (entry.connection.state !== "connected" || entry.isCurrent?.() === false)
         return;
@@ -120,7 +128,15 @@ async function refreshConnectedMcpCatalog(entry, serverConfig) {
         entry.connection.state === "connected" &&
         entry.connection.generation === generation;
     if (entry.connection instanceof SharedMcpLease) {
-        const catalog = await entry.connection.catalog();
+        let catalog;
+        try {
+            catalog = await entry.connection.catalog();
+        }
+        catch (error) {
+            if (!ownsCatalog())
+                return;
+            throw error;
+        }
         if (!ownsCatalog()) {
             if (entry.credentialsCurrent?.() === false)
                 await entry.onCredentialsChanged?.();
@@ -150,6 +166,8 @@ async function refreshConnectedMcpCatalog(entry, serverConfig) {
             await ensureMcpResourceSubscriptions(entry.connection.client, catalog.resources ?? []);
     }
     catch (error) {
+        if (!ownsCatalog())
+            return;
         entry.logger.warn("Failed to refresh MCP catalog cache", {
             error: error instanceof Error ? error.message : String(error),
         });

package/dist/core/extensions/builtin/prompt-preset/claude-fable-5-2.js

@@ -16,10 +16,10 @@
 //   retries after a busy tool from nearly all tries to four in ten. "Blind
 //   retries" becomes the exact action it meant, repeating a failure that has not
 //   been diagnosed, so it no longer collides with "wait and retry".
-// - Scope, structure ("Say who owns the code"): with no ownership statement 5.2
-//   repeats existing code instead of reusing it. The user owns the code here, so
-//   the guide's ownership sentence stays out (it invites unrequested changes);
-//   the smallest-change rule says to build on the code that already does the job.
+// - Scope, structure ("Say who owns the code"): the guide's ownership sentence
+//   opens the structure paragraph and replaces the smallest-change sentence
+//   (owner order). Without it, 5.2 acts as a guest: parallel code, duplicates
+//   left in place, and nearby bugs only mentioned.
 // - Working the Task, delegation ("Set expectations for subagents"): the 5.1
 //   sentence was a standing invitation to delegate, which the guide says to
 //   review first. It now states the cost before the invitation, what a brief
@@ -29,7 +29,7 @@
 //   mannered-prose sentence. 5.2 reports run dense, so the rule asks for plain
 //   words, mostly short one-idea sentences, one word per thing, and no names
 //   made up during the work, for a reader switching in from something else.
-// Deliberately absent: the ownership sentence; "answer directly" or think-less
+// Deliberately absent: "answer directly" or think-less
 // lines (the guide: no effect at medium effort and above, lower the effort
 // instead); a token budget; the "treat that answer as done" lines; hard
 // sentence-length limits; any instruction to write reasoning in the reply (a
@@ -77,7 +77,7 @@ The request sets the scope, and the scope is the deliverable: deliver all of it
 
 Errors, timeouts, locked files, empty results, and failing tools are ordinary obstacles, not blockers: diagnose them, then work through them with the access you have (wait and retry a call that is safe to repeat, fix the request, use another tool or source) without asking first. A file marked not to be touched, withheld access, or a safety guardrail is a deliberate blocker: leave it alone and look for another safe way to finish. If part of the task stays blocked, finish every other part and say exactly what you left out and why.
 
-Smallest correct change wins: build on the code that already does the job instead of adding a parallel copy, with no refactors beside a focused fix, no helpers or abstractions for hypothetical needs, and no defensive checks inside trusted code; validate only at system boundaries. A pre-existing bug or performance concern you notice is a follow-up for your summary, not a change in this diff. Scratch checks verify and get discarded; commit tests only where the task asks for them or the repository already keeps tests for that kind of change, sized like the neighboring test files. Prefer a surgical edit over rewriting a file when the result would be identical.
+This codebase is yours: what it's for and how it's built are your call, and you'll keep building on it. Add no helpers or abstractions for hypothetical needs and no defensive checks inside trusted code; validate only at system boundaries. A pre-existing bug or performance concern you notice is a follow-up for your summary, not a change in this diff. Scratch checks verify and get discarded; commit tests only where the task asks for them or the repository already keeps tests for that kind of change, sized like the neighboring test files. Prefer a surgical edit over rewriting a file when the result would be identical.
 
 ## Working the Task
 

package/dist/core/extensions/loader.js

@@ -68,6 +68,19 @@ function assertExtensionSide(extension, runs, registration) {
         return;
     throw new Error(`Extension "${extension.path}" declared runs: ${JSON.stringify(runs)} for ${registration}; runs must be "brain" or "hand".`);
 }
+/** The events whose handlers may declare `{ providers }` (CK21). */
+const PROVIDER_HOOK_EVENTS = [
+    "before_provider_request",
+    "provider_stream_event",
+    "after_provider_response",
+];
+function declaredProviders(extension, providers, registration) {
+    if (Array.isArray(providers) &&
+        providers.length > 0 &&
+        providers.every((provider) => typeof provider === "string" && provider !== ""))
+        return Object.freeze([...providers]);
+    throw new Error(`Extension "${extension.path}" declared providers: ${JSON.stringify(providers)} for ${registration}; providers must be a non-empty array of provider ids.`);
+}
 /** Modules available to extensions via virtualModules (for compiled binaries) */
 const VIRTUAL_MODULES = {
     typebox: _bundledTypebox,
@@ -355,11 +368,14 @@ function createExtensionAPI(extension, runtime, cwd, eventBus, session) {
         on(event, handler, options) {
             assertActive();
             const runs = options?.runs;
-            if (runs !== undefined) {
+            if (runs !== undefined)
                 assertExtensionSide(extension, runs, `"${event}"`);
-                if (session.side !== undefined && runs !== session.side)
-                    return () => { };
-            }
+            // Checked on every side, also for a handler this side does not register: a malformed declaration always throws.
+            const providers = PROVIDER_HOOK_EVENTS.includes(event) && options?.providers !== undefined
+                ? declaredProviders(extension, options.providers, `"${event}"`)
+                : undefined;
+            if (runs !== undefined && session.side !== undefined && runs !== session.side)
+                return () => { };
             const registeredHandler = ownedBy(extension, (...args) => {
                 // A child event can run inside its parent's task-tool async scope.
                 // Bind the host context here, preserving registered-handler metadata.
@@ -376,6 +392,10 @@ function createExtensionAPI(extension, runtime, cwd, eventBus, session) {
                 extension.handlerSides ??= new WeakMap();
                 extension.handlerSides.set(registeredHandler, runs);
             }
+            if (providers !== undefined) {
+                extension.handlerProviders ??= new WeakMap();
+                extension.handlerProviders.set(registeredHandler, providers);
+            }
             if (event === "before_agent_start" && options?.previewSafe === true) {
                 extension.previewSafeHandlers ??= new WeakSet();
                 extension.previewSafeHandlers.add(registeredHandler);

package/dist/core/extensions/runner.d.ts

@@ -129,6 +129,14 @@ export type ShutdownHandler = () => void;
 export declare function emitSessionShutdownEvent(extensionRunner: ExtensionRunner, event: SessionShutdownEvent, options?: {
     readonly processExit?: boolean;
 }): Promise<boolean>;
+/**
+ * A hand's dispatch of a hosted loop's request hooks (CK21): only the extensions `only` accepts, with the effective
+ * model the loop sent and no headers (they never leave the loop's side).
+ */
+export interface HandRequestHookDispatch {
+    readonly only: (extensionPath: string) => boolean;
+    readonly model?: Model<Api>;
+}
 export declare function emitProjectTrustEvent(extensionsResult: LoadExtensionsResult, event: ProjectTrustEvent, ctx: ProjectTrustContext): Promise<{
     result?: ProjectTrustEventResult;
     errors: ExtensionError[];
@@ -422,7 +430,7 @@ export declare class ExtensionRunner {
     emitBeforeProviderRequest(payload: unknown, excludeExtensionPath?: string, request?: {
         model: Model<Api>;
         headers: ProviderHeaders;
-    }): Promise<unknown>;
+    }, hand?: HandRequestHookDispatch): Promise<unknown>;
     emitBeforeProviderHeaders(headers: ProviderHeaders): Promise<ProviderHeaders>;
     /** Use the loader's provenance, including bundled modules and generated global-default shims. */
     getThirdPartySessionStartPaths(): string[];

package/dist/core/extensions/runner.js

@@ -2111,11 +2111,15 @@ export class ExtensionRunner {
             transformHeaders: async (headers) => await this.emitBeforeProviderHeaders(headers),
         };
     }
-    async emitBeforeProviderRequest(payload, excludeExtensionPath, request) {
+    async emitBeforeProviderRequest(payload, excludeExtensionPath, request, hand) {
         let currentPayload = payload;
-        const requestHandlers = this.dropsLoopEvent("before_provider_request")
-            ? []
-            : snapshotEventHandlers(this.extensions, "before_provider_request");
+        // A hand running a hosted loop's request hooks (CK21) names whose handlers run; it has no loop of its own, so the
+        // sessionless drop does not apply to that explicit dispatch. Every other caller keeps the dispatch it had.
+        const requestHandlers = hand !== undefined
+            ? snapshotEventHandlers(this.extensions, "before_provider_request").filter(({ ext }) => hand.only(ext.path))
+            : this.dropsLoopEvent("before_provider_request")
+                ? []
+                : snapshotEventHandlers(this.extensions, "before_provider_request");
         for (const { ext, handlers } of requestHandlers) {
             if (ext.path === excludeExtensionPath)
                 continue;
@@ -2125,6 +2129,7 @@ export class ExtensionRunner {
                         type: "before_provider_request",
                         payload: currentPayload,
                         ...(request ? { model: request.model, headers: request.headers } : {}),
+                        ...(hand?.model === undefined ? {} : { model: hand.model }),
                     };
                     const handlerResult = await handler(event, this.createContext(ext.path));
                     if (handlerResult !== undefined) {

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

@@ -1473,6 +1473,18 @@ export interface HandlerRegistrationOptions {
      */
     runs?: ExtensionSide;
 }
+/**
+ * Registration options for the provider request and stream hooks (`before_provider_request`, `provider_stream_event`,
+ * `after_provider_response`).
+ */
+export interface ProviderHookOptions extends HandlerRegistrationOptions {
+    /**
+     * The providers whose requests or streams this handler reads or changes; omitted, every provider. A hand advertises
+     * these to a hosted brain so it knows which calls need the device's hooks (hosted model-key custody CK21). The
+     * declaration never filters dispatch: the handler still receives every event wherever it runs.
+     */
+    providers?: readonly ProviderId[];
+}
 /** Registration options for `pi.on("before_agent_start", handler, options)`. */
 export interface BeforeAgentStartHandlerOptions extends HandlerRegistrationOptions {
     /**
@@ -2157,10 +2169,10 @@ export interface ExtensionAPI {
     on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>, options?: HandlerRegistrationOptions): () => void;
     on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>, options?: ContextHandlerOptions): () => void;
     on(event: "context_with_system", handler: ExtensionHandler<ContextWithSystemEvent, ContextEventResult>, options?: ContextHandlerOptions): () => void;
-    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>, options?: HandlerRegistrationOptions): () => void;
+    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>, options?: ProviderHookOptions): () => void;
     on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>, options?: HandlerRegistrationOptions): () => void;
-    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>, options?: HandlerRegistrationOptions): () => void;
-    on(event: "provider_stream_event", handler: ExtensionHandler<ProviderStreamEvent>, options?: HandlerRegistrationOptions): () => void;
+    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>, options?: ProviderHookOptions): () => void;
+    on(event: "provider_stream_event", handler: ExtensionHandler<ProviderStreamEvent>, options?: ProviderHookOptions): () => void;
     on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>, options?: BeforeAgentStartHandlerOptions): () => void;
     on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>, options?: HandlerRegistrationOptions): () => void;
     on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>, options?: HandlerRegistrationOptions): () => void;
@@ -3057,6 +3069,8 @@ export interface Extension {
     nonMutatingContextHandlers?: WeakSet<HandlerFn>;
     /** The declared side of each handler registered with `{ runs }`; a handler that declared none has no entry. */
     handlerSides?: WeakMap<HandlerFn, ExtensionSide>;
+    /** The declared providers of each provider hook registered with `{ providers }`; undeclared hooks have no entry. */
+    handlerProviders?: WeakMap<HandlerFn, readonly ProviderId[]>;
     tools: Map<string, RegisteredTool>;
     /** Optional for compatibility with extension records created before child modules. */
     childModules?: Map<string, RegisteredChildModule>;

package/dist/core/hand/hook-advertise.d.ts

@@ -0,0 +1,41 @@
+import type { ProviderId } from "@earendil-works/pi-ai";
+import type { HandSessionAdvertisement, HookModelRequest, HookModelRequestReply } from "../egress/wire.ts";
+import type { Extension } from "../extensions/types.ts";
+export type HookProviders = readonly ProviderId[] | "*";
+export interface HandHookAccess {
+    readonly requestHooks: HookProviders;
+    readonly streamHooks: HookProviders;
+}
+/** The request and stream hooks of the extensions `only` accepts (the ones that run on this hand). */
+export declare function handHookAccess(extensions: readonly Extension[], only: (extensionPath: string) => boolean): HandHookAccess;
+export interface AdvertHashParts {
+    readonly extensionSetHash: string;
+    readonly cwd: string;
+    /** The project-local hook set, as hook identities; its order does not matter. */
+    readonly projectHooks: readonly string[];
+}
+/** `H(extension set hash, cwd, project-local hook set)` (4.9): `sha256:` + hex SHA-256 of their canonical JSON. */
+export declare function computeAdvertHash(parts: AdvertHashParts): string;
+/** A bound session's advertisement, before a connection stamps it. */
+export type HandHookSession = Omit<HandSessionAdvertisement, "t" | "connectionId">;
+/** A hook request for a session not advertised on the connection it names; nothing ran. */
+export declare class HookNotAdvertisedError extends Error {
+    readonly name = "HookNotAdvertisedError";
+}
+export interface HandHookLinkOptions {
+    send(message: HandSessionAdvertisement | HookModelRequestReply): Promise<void>;
+    serve(request: HookModelRequest): Promise<HookModelRequestReply>;
+}
+export interface HandHookLink {
+    /** A new connection: every bound session's advertisement goes out first, in order, under `connectionId`. */
+    connect(connectionId: string, sessions: readonly HandHookSession[]): Promise<void>;
+    /** A session bound (or re-hashed) mid-connection: its advertisement goes out before anything else for it. */
+    advertise(session: HandHookSession): Promise<void>;
+    /**
+     * One `hook.model_request` received on `connectionId`; its reply follows that session's advertisement. Its hooks run
+     * outside the outgoing order, so a slow hook holds back no other request's reply and no advertisement.
+     */
+    receive(connectionId: string, request: HookModelRequest): Promise<void>;
+}
+export declare function createHandHookLink(options: HandHookLinkOptions): HandHookLink;
+//# sourceMappingURL=hook-advertise.d.ts.map

package/dist/core/hand/hook-advertise.js

@@ -0,0 +1,98 @@
+/**
+ * The hand's hook advertisement of hosted model-key custody (row CK21; custody design 4.9, round-10 fold section 15).
+ *
+ * A hand tells a hosted brain, per bound session, which providers' calls need the device's hooks: the request hooks
+ * (`before_provider_request`) and the stream hooks (`provider_stream_event`, `after_provider_response`) of the user's
+ * extensions, each scoped by its `{ providers }` declaration or, undeclared, every provider (`"*"`). The advertisement
+ * carries the `connectionId`, the session's `cwd` and its `advertHash`, and it is the first message for its session on
+ * every (re)connect: the link serves no `hook.model_request` that its session's advertisement on that connection did
+ * not precede.
+ */
+import { createHash } from "node:crypto";
+import { canonicalJson } from "@earendil-works/pi-agent-core";
+const REQUEST_HOOK_EVENTS = ["before_provider_request"];
+const STREAM_HOOK_EVENTS = ["provider_stream_event", "after_provider_response"];
+function hookProviders(extensions, events, only) {
+    const declared = new Set();
+    for (const extension of extensions) {
+        if (!only(extension.path))
+            continue;
+        for (const event of events)
+            for (const handler of extension.handlers.get(event) ?? []) {
+                const providers = extension.handlerProviders?.get(handler);
+                if (providers === undefined)
+                    return "*";
+                for (const provider of providers)
+                    declared.add(provider);
+            }
+    }
+    return [...declared].sort();
+}
+/** The request and stream hooks of the extensions `only` accepts (the ones that run on this hand). */
+export function handHookAccess(extensions, only) {
+    return {
+        requestHooks: hookProviders(extensions, REQUEST_HOOK_EVENTS, only),
+        streamHooks: hookProviders(extensions, STREAM_HOOK_EVENTS, only),
+    };
+}
+/** `H(extension set hash, cwd, project-local hook set)` (4.9): `sha256:` + hex SHA-256 of their canonical JSON. */
+export function computeAdvertHash(parts) {
+    const canonical = canonicalJson({
+        cwd: parts.cwd,
+        extensionSetHash: parts.extensionSetHash,
+        projectHooks: [...parts.projectHooks].sort(),
+    });
+    return `sha256:${createHash("sha256").update(canonical, "utf8").digest("hex")}`;
+}
+/** A hook request for a session not advertised on the connection it names; nothing ran. */
+export class HookNotAdvertisedError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "HookNotAdvertisedError";
+    }
+}
+export function createHandHookLink(options) {
+    let connectionId;
+    let advertised = new Set();
+    // One outgoing order: an advertisement queued before a reply is sent before it.
+    let outgoing = Promise.resolve();
+    const enqueue = (work) => {
+        const run = outgoing.then(work);
+        outgoing = run.then(() => undefined, () => undefined);
+        return run;
+    };
+    const sendAdvert = (connection, session, into) => enqueue(async () => {
+        if (connectionId !== connection)
+            return;
+        await options.send({ t: "hand.session.advertise", connectionId: connection, ...session });
+        into.add(session.sessionId);
+    });
+    return {
+        async connect(next, sessions) {
+            connectionId = next;
+            const fresh = new Set();
+            advertised = fresh;
+            await Promise.all(sessions.map((session) => sendAdvert(next, session, fresh)));
+        },
+        async advertise(session) {
+            if (connectionId === undefined)
+                throw new HookNotAdvertisedError("no connection to advertise on");
+            await sendAdvert(connectionId, session, advertised);
+        },
+        async receive(connection, request) {
+            // Only the advertised check and the reply's send take a place in the outgoing order.
+            await enqueue(async () => {
+                if (connection !== connectionId || !advertised.has(request.sessionId))
+                    throw new HookNotAdvertisedError(`hook.model_request for session ${JSON.stringify(request.sessionId)} was not preceded by its advertisement on connection ${JSON.stringify(connection)}`);
+            });
+            const reply = await options.serve(request);
+            await enqueue(async () => {
+                // A reconnect since the request arrived: its connection is gone, so its reply is not sent.
+                if (connection !== connectionId)
+                    return;
+                await options.send(reply);
+            });
+        },
+    };
+}
+//# sourceMappingURL=hook-advertise.js.map