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

package/dist/core/config-reference-redaction.js

@@ -1,21 +1,101 @@
+/**
+ * Resolved-value registry shared by every copy of this module in one JavaScript realm (omo#12965).
+ *
+ * A process can evaluate this module more than once (the bundle's shared chunk, its self-contained session-worker
+ * entry, and the SDK graph an in-process child loads), so the values are not kept in a module-local set: the first
+ * copy pins a frozen registry on `globalThis` under `SLOT_KEY` (non-writable, non-configurable, non-enumerable) and
+ * every later copy adopts it. The backing `Set` lives only in the installing copy's closure; the registry offers no
+ * delete, clear or setter, so in-realm code cannot remove a value, replace the slot or turn redaction off. Any
+ * in-realm code can `add` a string, which can only over-redact. This is a stopgap until one engine instance serves
+ * the whole process; other realms (workers, `vm` contexts, child processes) keep their own registry.
+ *
+ * Compatibility contract, permanent: the key string never changes. The v1 members `version` (1), `add(value)`,
+ * `size` (an accessor reporting the live count) and `values()` (a fresh array) are never removed or repurposed; a
+ * later contract keeps writing through this same slot and only adds members, and adopters ignore members they do not
+ * know. A copy adopts only a slot pinned the way `pin` pins it, frozen, with those four members; anything else (a
+ * slot planted before the first copy loaded, an accessor, another version) makes the import throw
+ * `ConfigReferenceRedactionSlotError`, because a copy running with a private set is the leak this registry removes.
+ */
+const SLOT_KEY_NAME = "@code-yeongyu/senpi/config-reference-redaction/v1";
+const SLOT_KEY = Symbol.for(SLOT_KEY_NAME);
 const MIN_REDACTED_LENGTH = 4;
-const resolvedValues = new Set();
-let redactionForms;
+/** The largest `$file` reference value (`config-reference-file.ts`); longer strings are never remembered. */
+const MAX_REMEMBERED_LENGTH = 65_536;
+class ConfigReferenceRedactionSlotError extends Error {
+    constructor(cause) {
+        super(`The process-wide redaction registry ${SLOT_KEY_NAME} was not installed by senpi or is incompatible; restart the process.`, cause === undefined ? undefined : { cause });
+        this.name = "ConfigReferenceRedactionSlotError";
+        this.code = "SENPI_REDACTION_SLOT_INCOMPATIBLE";
+    }
+}
+function createRegistry() {
+    const values = new Set();
+    return Object.freeze({
+        version: 1,
+        add(value) {
+            if (typeof value !== "string" || value.length < MIN_REDACTED_LENGTH || value.length > MAX_REMEMBERED_LENGTH)
+                return;
+            values.add(value);
+        },
+        get size() {
+            return values.size;
+        },
+        values: () => [...values],
+    });
+}
+function isFrozenV1Registry(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.isFrozen(value) &&
+        Reflect.get(value, "version") === 1 &&
+        typeof Reflect.get(value, "add") === "function" &&
+        typeof Reflect.get(value, "values") === "function" &&
+        typeof Reflect.get(value, "size") === "number");
+}
+function pin(registry) {
+    try {
+        Object.defineProperty(globalThis, SLOT_KEY, {
+            value: registry,
+            writable: false,
+            configurable: false,
+            enumerable: false,
+        });
+    }
+    catch (error) {
+        throw new ConfigReferenceRedactionSlotError(error);
+    }
+    return registry;
+}
+function sharedRegistry() {
+    const slot = Reflect.getOwnPropertyDescriptor(globalThis, SLOT_KEY);
+    if (slot === undefined)
+        return pin(createRegistry());
+    const value = slot.value;
+    if (slot.writable !== false || slot.configurable !== false || !isFrozenV1Registry(value)) {
+        throw new ConfigReferenceRedactionSlotError();
+    }
+    return value;
+}
+const registry = sharedRegistry();
+let redactionForms = [];
+let formsSize = 0;
 /** Every value a reference resolves to is kept for the process lifetime, including rotated ones: no cap, no eviction. */
 export function rememberResolvedReferenceValue(value) {
-    if (value.length < MIN_REDACTED_LENGTH || resolvedValues.has(value))
-        return;
-    resolvedValues.add(value);
-    redactionForms = undefined;
+    registry.add(value);
 }
 function encodings(value) {
     const form = new URLSearchParams([["", value]]).toString().slice(1);
     return [value, JSON.stringify(value).slice(1, -1), encodeURIComponent(value), encodeURI(value), form];
 }
+/** The registry is append-only, so a changed size is the only way its content can change. */
 function forms() {
-    redactionForms ??= [...new Set([...resolvedValues].flatMap(encodings))]
-        .filter((form) => form.length >= MIN_REDACTED_LENGTH)
-        .sort((left, right) => right.length - left.length);
+    const size = registry.size;
+    if (size !== formsSize) {
+        redactionForms = [...new Set(registry.values().flatMap(encodings))]
+            .filter((form) => form.length >= MIN_REDACTED_LENGTH)
+            .sort((left, right) => right.length - left.length);
+        formsSize = size;
+    }
     return redactionForms;
 }
 /** Replaces every resolved reference value, raw or encoded, before text reaches a sink outside the process. */
@@ -134,7 +214,7 @@ function isProtocolValue(key, value) {
     return Object.hasOwn(PROTOCOL_VALUES, key) && PROTOCOL_VALUES[key]?.has(value) === true;
 }
 export function redactResolvedReferenceData(value) {
-    if (resolvedValues.size === 0)
+    if (registry.size === 0)
         return value;
     const copies = new WeakMap();
     const pending = [];

package/dist/core/context-files.d.ts

@@ -16,6 +16,16 @@ export type ContextFiles = ContextFile[] & {
 export interface ContextFileLimits {
     maxBytesPerFile?: number;
     maxTotalBytes?: number;
+    /**
+     * The global (user-scope) context file to load instead of the agent-dir probe (senpi#5567).
+     * Honored from the user's own settings only (`SettingsManager.getGlobalContextFilePath`); a
+     * project's settings never set it. A leading `~` is expanded; a relative path resolves against
+     * the agent dir, like other paths in global settings; a directory runs the same candidate probe
+     * as the agent dir. Unset or blank keeps the agent-dir file. A path that is set but missing,
+     * unreadable, a special file, or a directory with no candidate falls back to the agent-dir probe
+     * and reports one warning diagnostic instead of erroring.
+     */
+    globalPath?: string;
 }
 export declare const DEFAULT_CONTEXT_FILE_MAX_BYTES: number;
 export declare const DEFAULT_CONTEXT_FILES_MAX_TOTAL_BYTES: number;

package/dist/core/context-files.js

@@ -29,6 +29,47 @@ function loadContextFileFromDir(dir) {
     }
     return null;
 }
+/**
+ * The global user-scope context file (senpi#5567). `contextFiles.globalPath` names a file (or a
+ * directory to probe for the usual candidates) to load in place of the agent-dir file. Precedence
+ * is defined and never errors: a blank or unset path keeps the agent-dir probe silently; a
+ * configured target that is missing, unreadable, a special file, or a directory with no candidates
+ * falls back to the agent-dir probe and returns one warning naming the configured path.
+ */
+function loadGlobalContextFile(agentDir, globalPath) {
+    const explicit = typeof globalPath === "string" ? globalPath.trim() : "";
+    if (explicit === "")
+        return { file: loadContextFileFromDir(agentDir) };
+    const resolved = resolvePath(explicit, agentDir);
+    const fallBack = (problem) => ({
+        file: loadContextFileFromDir(agentDir),
+        diagnostic: {
+            type: "warning",
+            path: resolved,
+            message: `contextFiles.globalPath ${problem}; using the global context file from ${agentDir} instead.`,
+        },
+    });
+    let stats;
+    try {
+        stats = statSync(resolved);
+    }
+    catch (error) {
+        const code = error.code;
+        return fallBack(code === "ENOENT" || code === "ENOTDIR" ? "does not exist" : `could not be read (${String(error)})`);
+    }
+    if (stats.isDirectory()) {
+        const file = loadContextFileFromDir(resolved);
+        return file ? { file } : fallBack("is a directory with no AGENTS.md or CLAUDE.md");
+    }
+    if (!stats.isFile())
+        return fallBack("is not a regular file or directory");
+    try {
+        return { file: { path: resolved, content: stripBom(readFileSync(resolved, "utf-8")) } };
+    }
+    catch (error) {
+        return fallBack(`could not be read (${String(error)})`);
+    }
+}
 /**
  * The main repo's context file that a nested linked worktree's own copy shadows: both
  * occupy the same logical repository scope, so loading both applies that context twice. Returns
@@ -142,21 +183,22 @@ function applyContextFileLimits(files, limits) {
     }
     return Object.assign(kept, { diagnostics });
 }
-/** Compares directories by their real path, ignoring case where the filesystem does (Windows). */
-function directoryKey(dir) {
-    const real = canonicalizePath(resolvePath(dir));
+/** Compares files and directories by their real path, ignoring case where the filesystem does (Windows). */
+function pathKey(path) {
+    const real = canonicalizePath(resolvePath(path));
     return process.platform === "win32" ? real.toLowerCase() : real;
 }
 export function loadProjectContextFiles(options) {
     const resolvedCwd = resolvePath(options.cwd);
     const resolvedAgentDir = resolvePath(options.agentDir);
-    const homeKey = directoryKey(options.homeDir ?? homedir());
+    const homeKey = pathKey(options.homeDir ?? homedir());
     const contextFiles = [];
+    // Real-path keys: a symlinked ancestor file that points at an already loaded file is the same file.
     const seenPaths = new Set();
-    const globalContext = loadContextFileFromDir(resolvedAgentDir);
-    if (globalContext) {
-        contextFiles.push({ ...globalContext, scope: "user" });
-        seenPaths.add(globalContext.path);
+    const globalContext = loadGlobalContextFile(resolvedAgentDir, options.globalPath);
+    if (globalContext.file) {
+        contextFiles.push({ ...globalContext.file, scope: "user" });
+        seenPaths.add(pathKey(globalContext.file.path));
     }
     const ancestorContextFiles = [];
     const shadowedContextFile = findShadowedContextFile(resolvedCwd);
@@ -164,9 +206,10 @@ export function loadProjectContextFiles(options) {
     while (true) {
         const contextFile = loadContextFileFromDir(currentDir);
         const isShadowed = shadowedContextFile !== undefined && canonicalizePath(contextFile?.path ?? "") === shadowedContextFile;
-        if (contextFile && !isShadowed && !seenPaths.has(contextFile.path)) {
-            ancestorContextFiles.unshift(directoryKey(currentDir) === homeKey ? { ...contextFile, scope: "user" } : contextFile);
-            seenPaths.add(contextFile.path);
+        const contextFileKey = contextFile ? pathKey(contextFile.path) : undefined;
+        if (contextFile && contextFileKey !== undefined && !isShadowed && !seenPaths.has(contextFileKey)) {
+            ancestorContextFiles.unshift(pathKey(currentDir) === homeKey ? { ...contextFile, scope: "user" } : contextFile);
+            seenPaths.add(contextFileKey);
         }
         const parentDir = dirname(currentDir);
         if (parentDir === currentDir)
@@ -174,6 +217,9 @@ export function loadProjectContextFiles(options) {
         currentDir = parentDir;
     }
     contextFiles.push(...ancestorContextFiles);
-    return applyContextFileLimits(contextFiles, options);
+    const limited = applyContextFileLimits(contextFiles, options);
+    if (globalContext.diagnostic)
+        limited.diagnostics.unshift(globalContext.diagnostic);
+    return limited;
 }
 //# sourceMappingURL=context-files.js.map

package/dist/core/egress/wire.d.ts

@@ -168,11 +168,24 @@ export interface HookModelRequest {
     readonly claim: SignedPlacementClaim;
     readonly input: HookModelRequestInput;
 }
+/** A user hook's failure on the hand: reported with the reply, as a fused session reports it, never thrown. */
+export interface HookFailure {
+    readonly extensionPath: string;
+    readonly event: string;
+    readonly error: string;
+}
 export interface HookModelRequestReply {
     readonly t: "hook.model_request.reply";
     readonly sessionId: string;
     readonly stepId: string;
     readonly output: HookModelRequestInput;
+    /** The hooks that failed; `output` is what the others produced. Absent: none failed. */
+    readonly errors?: readonly HookFailure[];
+    /** The messages and notices the hooks sent during the call, as on every loop-hook reply (S33). Absent: none. */
+    readonly sent?: readonly WireJson[];
+    readonly notices?: readonly WireJson[];
+    /** Late messages and notices the hand dropped past its per-session bound. Absent: none. */
+    readonly droppedLate?: number;
 }
 export interface HandSessionAdvertisement {
     readonly t: "hand.session.advertise";

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

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

@@ -0,0 +1,66 @@
+/**
+ * The request-hook contract of hosted model-key custody (row CK21; custody design 4.9, round-10 fold section 15).
+ *
+ * `HookRequestInput` is the serializable projection of the fused `before_provider_request` input: the provider payload
+ * and the effective request model, without the request headers or the model's own headers, which can carry a
+ * credential and never leave the side that dials. A step call has this input; an aux call has none. A hand serves
+ * `hook.model_request` by running its user's request hooks on the input, only after the request's placement claim
+ * verified, and replies with the payload they produced, with their failures and the messages and notices they sent.
+ */
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExecutionScope } from "@earendil-works/pi-agent-core";
+import { type ClaimVerdict } from "../egress/placement-claim.ts";
+import type { HookModelRequest, HookModelRequestReply, ProviderCallErrorCode, ProviderCallKind, WireJson } from "../egress/wire.ts";
+import type { BeforeProviderRequestEvent } from "../extensions/types.ts";
+/** The pinned shape of `HookModelRequestInput` (and of the reply's `output`). */
+export type HookRequestInput = {
+    readonly payload: WireJson;
+    readonly model?: {
+        readonly [key: string]: WireJson;
+    };
+};
+/** The input or output cannot cross the wire: it is not JSON, or not the closed envelope. */
+export declare class HookContractError extends Error {
+    readonly name = "HookContractError";
+}
+/** The request's placement claim did not verify, so no hook ran; `code`/`retryable` are the claim's wire answer. */
+export declare class HookRequestRefusedError extends Error {
+    readonly name = "HookRequestRefusedError";
+    readonly verdict: Exclude<ClaimVerdict, "valid">;
+    readonly code: ProviderCallErrorCode;
+    readonly retryable: boolean;
+    constructor(verdict: Exclude<ClaimVerdict, "valid">);
+}
+/** The projection of a fused `before_provider_request` input. */
+export declare function hookRequestInputOf(event: Omit<BeforeProviderRequestEvent, "type"> & {
+    type?: string;
+}): HookRequestInput;
+/** A step call's hook input; an aux call runs no request hooks on the hand and has none. */
+export declare function hookRequestInputForCall(call: ProviderCallKind, event: Omit<BeforeProviderRequestEvent, "type"> & {
+    type?: string;
+}): HookRequestInput | undefined;
+/** The reply's `output`: the payload the hooks produced, with the model the request carried. */
+export declare function hookRequestOutputOf(input: HookRequestInput, payload: unknown): HookRequestInput;
+/** Reads a wire value back as the closed envelope `{ payload, model? }`; the model never carries headers. */
+export declare function parseHookRequestInput(value: unknown): HookRequestInput;
+/** The effective model a hand hands its hooks, as the loop sent it. */
+export declare function hookModelOf(input: HookRequestInput): Model<Api> | undefined;
+/** What the user's request hooks produced: the reply's `output`, their failures and what they sent. */
+export type HookRequestHooksResult = Omit<HookModelRequestReply, "t" | "sessionId" | "stepId" | "output"> & {
+    readonly output: HookRequestInput;
+};
+export interface HookServePorts {
+    /** The hand's placement-claim check (CK7's verifier with the hand's trust and clock). */
+    verifyClaim(claim: unknown): Promise<ClaimVerdict>;
+    /** Runs the user's request hooks of `sessionId` on `input` and returns what they produced. */
+    runRequestHooks(sessionId: string, input: HookRequestInput): Promise<HookRequestHooksResult>;
+}
+/** Serves one `hook.model_request`: claim first, then the closed input, then the hooks. */
+export declare function serveHookModelRequest(request: HookModelRequest, ports: HookServePorts): Promise<HookModelRequestReply>;
+/**
+ * `runRequestHooks` over a hand's loop-hook runner (`LooplessHand.loopHooks`): the session's hooks run on the runtime of
+ * `scope`, inside a loop-hook call bound to that session, with the loop busy (a model request is mid-turn). The hooks'
+ * failures and what they sent travel with the output, as they do on every loop-hook reply.
+ */
+export declare function loopHookRequestHooks(loopHooks: (event: string, payload: WireJson) => Promise<unknown>, scope: ExecutionScope): HookServePorts["runRequestHooks"];
+//# sourceMappingURL=hook-contract.d.ts.map