@makaio/client-codex 1.0.0-dev-1783973359164 → 1.0.0-dev-1784806252593

package/README.md

@@ -41,13 +41,31 @@ is preserved without overwriting a concurrently changed canonical credential.
 
 ### Hook Events
 
-| Hook Name | Framework Subject |
-|-----------|------------------|
-| `SessionStart` | `client.session.started` |
-| `UserPromptSubmit` | `client.session.userPrompt.submitted` |
-| `PreToolUse` | `client.session.tool.pre` |
-| `PostToolUse` | `client.session.tool.post` |
-| `Stop` | `client.session.turn.completed` |
+| Hook Name | Framework Subject | Response Capabilities |
+|-----------|------------------|----------------------|
+| `SessionStart` | `client.session.started` | `context.append`, `openai.codex-hook-response.block` |
+| `UserPromptSubmit` | `client.session.userPrompt.submitted` | `context.append`, `openai.codex-hook-response.block` |
+| `PreToolUse` | `client.session.tool.pre` | `context.append`, `openai.codex-hook-response.block`, `openai.codex-hook-response.permission.deny`, `openai.codex-hook-response.input.update` |
+| `PostToolUse` | `client.session.tool.post` | `context.append`, `openai.codex-hook-response.block` |
+| `Stop` | `client.session.turn.completed` | `openai.codex-hook-response.block` |
+
+All five events synchronously consume JSON output in the pinned upstream source tag `rust-v0.144.1`. Live CLI probes remain pending; the contract only exposes source-accepted fields.
+
+### Hook Response Contract (`openai.codex-hook-response@1`)
+
+The `./runtime` entrypoint registers a `ProviderContractCatalogEntry` that defines how contributions are validated for Codex:
+
+| Field | Value |
+|-------|-------|
+| `contractId` | `openai.codex-hook-response` |
+| `version` | `1.1.0` |
+| `supportedInteractions` | `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop` |
+
+**Blockability:** All five events support blocking responses. SessionStart uses `continue: false` with `stopReason`; the other events use their event-specific block form.
+
+**Composition:** Contributions are collected deterministically. Context appends render as `hookSpecificOutput.additionalContext`; blocks use `decision: "block"` with a non-empty reason; PreToolUse additionally supports `permissionDecision: "deny"` and an allowed `updatedInput` rewrite.
+
+See [Client Hook Response Pipeline](../../docs/architecture/client-hook-responses.md) for the full architecture.
 
 ## Native Tools
 
@@ -106,6 +124,8 @@ Capabilities are sourced from `codexCapabilityMap` in `@makaio/contracts`, keepi
 | `CodexClientSubjects` | namespace subjects | Typed bus subjects for `client:codex.*` |
 | `CODEX_CLIENT_NAMESPACE` | `string` | Fully-qualified namespace domain (`'client:codex'`) |
 | `normalizeCodexHook` | function | Normalizes a raw Codex hook payload into a `CodexNormalizedEvent` |
+| `codexProviderContractCatalog` | `ProviderContractCatalogEntry` | Provider contract catalog entry for the `openai.codex-hook-response` contract |
+| `composeCodexHookResponse` | function | Collects and renders source-verified synchronous hook responses |
 
 ### Server entrypoint (`./server`)
 

package/dist/{codex-client-session-service-B-E98xgY.mjs → codex-client-session-service-CTJ576Q4.mjs}

@@ -1,6 +1,6 @@
 import { codexCapabilityMap, createClientDefinition } from "@makaio/framework/contracts";
 import { z } from "zod";
-import { AbsolutePathSchema, BinaryNotFoundError, ClientSubjects, ClientWiringApplyResponseSchema, ClientWiringListResponseSchema, ClientWiringRemoveResponseSchema, assertAbsoluteProjectDir, atomicModifyFile, buildHookCommand, createClientNamespace, deriveSessionEventDescriptors, pickNonEmptyString } from "@makaio/framework/clients";
+import { AbsolutePathSchema, BinaryNotFoundError, ClientSubjects, ClientWiringApplyResponseSchema, ClientWiringListResponseSchema, ClientWiringRemoveResponseSchema, DEFAULT_HOOK_HANDLE_TIMEOUT_MS, NOOP_HOOK_HANDLE_RESPONSE, assertAbsoluteProjectDir, atomicModifyFile, buildClientCommand, buildHookCommand, collectContributions, createClientNamespace, deriveSessionEventDescriptors, pickNonEmptyString } from "@makaio/framework/clients";
 import { MakaioBus, RequestError } from "@makaio/framework/bus";
 import { BaseService } from "@makaio/framework/service-base";
 import * as fs$1 from "node:fs/promises";
@@ -10,6 +10,7 @@ import path from "node:path";
 import * as os$1 from "node:os";
 import os from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { ClientConfigPrimeSchema, SessionConfigSetupRequestSchema, SessionConfigSetupResponseSchema, SessionConfigTeardownRequestSchema, SessionConfigTeardownResponseSchema } from "@makaio/framework/contracts/client";
 import { parse } from "smol-toml";
 import { lock } from "proper-lockfile";
@@ -24,6 +25,12 @@ import { lock } from "proper-lockfile";
 * capability taxonomy in a single canonical location.
 * @packageDocumentation
 */
+/** Namespaced Codex hook-response capabilities exposed to contributors. */
+const CODEX_HOOK_RESPONSE_CAPABILITIES = Object.freeze({
+	block: "openai.codex-hook-response.block",
+	permissionDeny: "openai.codex-hook-response.permission.deny",
+	inputUpdate: "openai.codex-hook-response.input.update"
+});
 /**
 * Static client definition for `@makaio/client-codex`.
 *
@@ -101,23 +108,33 @@ const clientDefinition = createClientDefinition({
 		hookEvents: [
 			{
 				name: "SessionStart",
-				frameworkSubject: "client.session.started"
+				frameworkSubject: "client.session.started",
+				responseCapabilities: ["context.append", CODEX_HOOK_RESPONSE_CAPABILITIES.block]
 			},
 			{
 				name: "UserPromptSubmit",
-				frameworkSubject: "client.session.userPrompt.submitted"
+				frameworkSubject: "client.session.userPrompt.submitted",
+				responseCapabilities: ["context.append", CODEX_HOOK_RESPONSE_CAPABILITIES.block]
 			},
 			{
 				name: "PreToolUse",
-				frameworkSubject: "client.session.tool.pre"
+				frameworkSubject: "client.session.tool.pre",
+				responseCapabilities: [
+					"context.append",
+					CODEX_HOOK_RESPONSE_CAPABILITIES.block,
+					CODEX_HOOK_RESPONSE_CAPABILITIES.permissionDeny,
+					CODEX_HOOK_RESPONSE_CAPABILITIES.inputUpdate
+				]
 			},
 			{
 				name: "PostToolUse",
-				frameworkSubject: "client.session.tool.post"
+				frameworkSubject: "client.session.tool.post",
+				responseCapabilities: ["context.append", CODEX_HOOK_RESPONSE_CAPABILITIES.block]
 			},
 			{
 				name: "Stop",
-				frameworkSubject: "client.session.turn.completed"
+				frameworkSubject: "client.session.turn.completed",
+				responseCapabilities: [CODEX_HOOK_RESPONSE_CAPABILITIES.block]
 			}
 		]
 	}
@@ -993,17 +1010,7 @@ function extractToolName(payload) {
 * @returns Tool call ID string, or `undefined` when absent
 */
 function extractToolCallId(payload) {
-	return pickNonEmptyString(payload, "call_id");
-}
-/**
-* Extract optional tool execution outcome from a raw Codex post-tool payload.
-*
-* Codex reports whether the tool call succeeded under `success`.
-* @param payload - Raw hook payload object
-* @returns Boolean success flag, or `undefined` when absent
-*/
-function extractSuccess(payload) {
-	return typeof payload["success"] === "boolean" ? payload["success"] : void 0;
+	return pickNonEmptyString(payload, "tool_use_id");
 }
 /**
 * Extract optional prompt text from a raw Codex user-prompt payload.
@@ -1068,14 +1075,410 @@ function normalizeCodexHook(raw, machineId) {
 			payload: {
 				...base,
 				toolName: extractToolName(raw.payload),
-				toolCallId: extractToolCallId(raw.payload),
-				success: extractSuccess(raw.payload)
+				toolCallId: extractToolCallId(raw.payload)
 			}
 		};
 		default: return null;
 	}
 }
 
+//#endregion
+//#region src/runtime/schemas.ts
+/**
+* Hook events emitted by Codex that map to the v1 observed-semantics set.
+*
+* These are the events the normalizer translates into `client.session.*` bus
+* emissions. Any event NOT listed here is left as raw `client:codex`
+* namespace data only.
+*/
+const CODEX_HOOK_SESSION_START = "SessionStart";
+const CODEX_HOOK_USER_PROMPT_SUBMIT = "UserPromptSubmit";
+const CODEX_HOOK_PRE_TOOL_USE = "PreToolUse";
+const CODEX_HOOK_POST_TOOL_USE = "PostToolUse";
+const CODEX_HOOK_STOP = "Stop";
+
+//#endregion
+//#region src/runtime/hook-response-contracts.ts
+const CODEX_CLIENT_ID = "codex";
+const CODEX_CONTRACT_ID = "openai.codex-hook-response";
+const CODEX_CONTRACT_VERSION = "1.1.0";
+/**
+* Build a frozen Codex provider envelope.
+* @param effects - Provider-native effect record.
+* @returns A frozen Codex contribution envelope.
+*/
+function envelope(effects) {
+	return Object.freeze({
+		clientId: CODEX_CLIENT_ID,
+		contractId: CODEX_CONTRACT_ID,
+		effects: Object.freeze(effects)
+	});
+}
+/**
+* Builds a SessionStart context response.
+* @param value - Context appended when the session starts.
+* @returns A Codex SessionStart context envelope.
+*/
+function createCodexSessionStartContextEffect(value) {
+	return envelope({ additionalContext: value });
+}
+/**
+* Builds a SessionStart stop response.
+* @param reason - Reason for stopping session startup.
+* @returns A Codex SessionStart block envelope.
+*/
+function createCodexSessionStartBlockEffect(reason) {
+	return envelope({
+		decision: "block",
+		reason
+	});
+}
+/**
+* Builds a UserPromptSubmit context response.
+* @param value - Context appended to the submitted prompt.
+* @returns A Codex UserPromptSubmit context envelope.
+*/
+function createCodexUserPromptSubmitContextEffect(value) {
+	return envelope({ additionalContext: value });
+}
+/**
+* Builds a UserPromptSubmit block response.
+* @param reason - Reason for blocking the submitted prompt.
+* @returns A Codex UserPromptSubmit block envelope.
+*/
+function createCodexUserPromptSubmitBlockEffect(reason) {
+	return envelope({
+		decision: "block",
+		reason
+	});
+}
+/**
+* Builds a PreToolUse block response.
+* @param reason - Reason for blocking the tool invocation.
+* @returns A Codex PreToolUse block envelope.
+*/
+function createCodexPreToolUseBlockEffect(reason) {
+	return envelope({
+		decision: "block",
+		reason
+	});
+}
+/**
+* Builds a PreToolUse deny-permission response.
+* @param reason - Reason for denying the tool invocation.
+* @returns A Codex PreToolUse permission-denial envelope.
+*/
+function createCodexPreToolUseDenyEffect(reason) {
+	return envelope({
+		permissionDecision: "deny",
+		permissionDecisionReason: reason
+	});
+}
+/**
+* Builds additional model context for PreToolUse.
+* @param value - Context appended before the tool invocation.
+* @returns A Codex PreToolUse context envelope.
+*/
+function createCodexPreToolUseContextEffect(value) {
+	return envelope({ additionalContext: value });
+}
+/**
+* Builds a PreToolUse allowed input update.
+* @param updatedInput - JSON value that replaces the native tool input.
+* @returns A Codex PreToolUse input-update envelope.
+*/
+function createCodexPreToolUseUpdateEffect(updatedInput) {
+	return envelope({
+		permissionDecision: "allow",
+		updatedInput
+	});
+}
+/**
+* Builds a PostToolUse context response.
+* @param value - Context appended after the tool invocation.
+* @returns A Codex PostToolUse context envelope.
+*/
+function createCodexPostToolUseContextEffect(value) {
+	return envelope({ additionalContext: value });
+}
+/**
+* Builds a PostToolUse block response.
+* @param reason - Reason for blocking after the tool invocation.
+* @returns A Codex PostToolUse block envelope.
+*/
+function createCodexPostToolUseBlockEffect(reason) {
+	return envelope({
+		decision: "block",
+		reason
+	});
+}
+/**
+* Builds a Stop block response.
+* @param reason - Reason for requesting another turn.
+* @returns A Codex Stop block envelope.
+*/
+function createCodexStopBlockEffect(reason) {
+	return envelope({
+		decision: "block",
+		reason
+	});
+}
+const CODEX_RESPONSE_CAPABILITIES = Object.freeze([
+	"context.append",
+	CODEX_HOOK_RESPONSE_CAPABILITIES.block,
+	CODEX_HOOK_RESPONSE_CAPABILITIES.permissionDeny,
+	CODEX_HOOK_RESPONSE_CAPABILITIES.inputUpdate
+]);
+const CODEX_SUPPORTED_INTERACTIONS = Object.freeze([
+	CODEX_HOOK_SESSION_START,
+	CODEX_HOOK_USER_PROMPT_SUBMIT,
+	CODEX_HOOK_PRE_TOOL_USE,
+	CODEX_HOOK_POST_TOOL_USE,
+	CODEX_HOOK_STOP,
+	...CODEX_RESPONSE_CAPABILITIES
+]);
+const CODEX_INTERACTION_BLOCKABILITY = Object.freeze(CODEX_SUPPORTED_INTERACTIONS.map((interaction) => Object.freeze({
+	interaction,
+	blockable: interaction === CODEX_HOOK_RESPONSE_CAPABILITIES.block || interaction === CODEX_HOOK_RESPONSE_CAPABILITIES.permissionDeny || interaction === CODEX_HOOK_RESPONSE_CAPABILITIES.inputUpdate || interaction === "SessionStart" || interaction === "UserPromptSubmit" || interaction === "PreToolUse" || interaction === "PostToolUse" || interaction === "Stop"
+})));
+/**
+* Determine whether a runtime value is losslessly representable as JSON.
+* @param value - Runtime value to inspect.
+* @param ancestors - Objects already visited on the current recursion path.
+* @returns Whether the value is an acyclic JSON value.
+*/
+function isJsonValue(value, ancestors = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (typeof value !== "object") return false;
+	if (ancestors.has(value)) return false;
+	const nextAncestors = new Set(ancestors).add(value);
+	if (Array.isArray(value)) return value.every((entry) => isJsonValue(entry, nextAncestors));
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return false;
+	return Object.values(value).every((entry) => isJsonValue(entry, nextAncestors));
+}
+const EVENT_EFFECTS = Object.freeze({
+	[CODEX_HOOK_SESSION_START]: new Set(["context", "block"]),
+	[CODEX_HOOK_USER_PROMPT_SUBMIT]: new Set(["context", "block"]),
+	[CODEX_HOOK_PRE_TOOL_USE]: new Set([
+		"context",
+		"block",
+		"deny",
+		"update"
+	]),
+	[CODEX_HOOK_POST_TOOL_USE]: new Set(["context", "block"]),
+	[CODEX_HOOK_STOP]: new Set(["block"])
+});
+/**
+* Classify an exact provider-native Codex effects record.
+* @param effects - Provider-native effects to classify.
+* @returns The recognized effect kind, or `undefined` for an invalid shape.
+*/
+function classifyEffects(effects) {
+	const keys = Object.keys(effects);
+	if (keys.length === 1 && typeof effects.additionalContext === "string") return "context";
+	if (keys.length !== 2) return void 0;
+	if (effects.decision === "block" && typeof effects.reason === "string" && effects.reason.trim() !== "") return "block";
+	if (effects.permissionDecision === "deny" && typeof effects.permissionDecisionReason === "string" && effects.permissionDecisionReason.trim() !== "") return "deny";
+	if (effects.permissionDecision === "allow" && "updatedInput" in effects && effects.updatedInput !== null && isJsonValue(effects.updatedInput)) return "update";
+}
+/**
+* Extract and validate the provider-native effects record.
+* @param output - Contributor response to inspect.
+* @returns The effects record, `undefined` for an empty response, or a diagnostic string.
+*/
+function extractEffects(output) {
+	if (output === void 0 || output === null) return void 0;
+	if (typeof output !== "object" || Array.isArray(output)) return "Contributor response must be an object or undefined";
+	const response = output;
+	if (Object.keys(response).some((key) => key !== "providerEnvelope")) return "Codex provider responses may contain only providerEnvelope";
+	if (response.providerEnvelope === void 0) return void 0;
+	if (typeof response.providerEnvelope !== "object" || response.providerEnvelope === null || Array.isArray(response.providerEnvelope)) return "providerEnvelope must be an object";
+	const envelope = response.providerEnvelope;
+	const unsupportedField = Object.keys(envelope).find((key) => key !== "clientId" && key !== "contractId" && key !== "effects");
+	if (unsupportedField !== void 0) return `Unsupported Codex providerEnvelope field '${unsupportedField}'`;
+	if (envelope.clientId !== "codex" || envelope.contractId !== "openai.codex-hook-response") return "providerEnvelope clientId and contractId must target the Codex contract";
+	if (typeof envelope.effects !== "object" || envelope.effects === null || Array.isArray(envelope.effects)) return "providerEnvelope.effects must be an object";
+	return envelope.effects;
+}
+/**
+* Validate a provider response against the event-specific Codex parser surface.
+* @param output - Contributor response to validate.
+* @param ctx - Current provider validation context.
+* @returns `true` when valid, otherwise a diagnostic string.
+*/
+function validateCodexContractOutput(output, ctx) {
+	const effects = extractEffects(output);
+	if (effects === void 0) return true;
+	if (typeof effects === "string") return effects;
+	const effectKind = classifyEffects(effects);
+	if (effectKind !== void 0 && EVENT_EFFECTS[String(ctx.eventName)]?.has(effectKind)) return true;
+	return `Unsupported Codex response effects for '${String(ctx.eventName)}'`;
+}
+const codexProviderContractCatalog = Object.freeze({
+	clientId: CODEX_CLIENT_ID,
+	contractId: CODEX_CONTRACT_ID,
+	version: CODEX_CONTRACT_VERSION,
+	supportedInteractions: CODEX_SUPPORTED_INTERACTIONS,
+	blockability: CODEX_INTERACTION_BLOCKABILITY,
+	validate: validateCodexContractOutput
+});
+
+//#endregion
+//#region src/runtime/hook-response-composer.ts
+/** Deterministic Codex 0.144.1 hook-response composition. @packageDocumentation */
+/**
+* Resolve the declared response capabilities for one Codex event.
+* @param eventName - Native Codex hook event name.
+* @returns Declared capabilities for the event.
+*/
+function capabilities(eventName) {
+	return clientDefinition.runtimeCapabilities.hookEvents.find((event) => event.name === eventName)?.responseCapabilities ?? [];
+}
+const FIRST_BLOCK_EVENTS = new Set([
+	CODEX_HOOK_SESSION_START,
+	CODEX_HOOK_USER_PROMPT_SUBMIT,
+	CODEX_HOOK_PRE_TOOL_USE
+]);
+/**
+* Collect one provider-native effect into its composition bucket.
+* @param collected - Mutable composition buckets for this request.
+* @param effect - Provider contribution envelope to inspect.
+* @param supportsContext - Whether the current event accepts additional context.
+*/
+function collectProviderEffect(collected, effect, supportsContext) {
+	if (effect.clientId !== "codex" || effect.contractId !== "openai.codex-hook-response") return;
+	const value = effect.effects;
+	if (supportsContext && typeof value.additionalContext === "string") collected.contexts.push(value.additionalContext);
+	if (value.decision === "block" && typeof value.reason === "string") collected.blocks.push(value.reason);
+	if (value.permissionDecision === "deny" && typeof value.permissionDecisionReason === "string") collected.denyReasons.push(value.permissionDecisionReason);
+	if (value.permissionDecision === "allow" && "updatedInput" in value) collected.updates.push(value.updatedInput);
+}
+/**
+* Collect canonical and provider-native effects for one event.
+* @param eventName - Native Codex hook event name.
+* @param effects - Deterministically ordered effects to collect.
+* @returns Effects grouped by native output behavior.
+*/
+function collectEffects(eventName, effects) {
+	const collected = {
+		contexts: [],
+		blocks: [],
+		denyReasons: [],
+		updates: []
+	};
+	const supportsContext = capabilities(eventName).includes("context.append");
+	for (const effect of effects) if ("kind" in effect) {
+		if (supportsContext && effect.kind === "context.append") collected.contexts.push(effect.value);
+	} else collectProviderEffect(collected, effect, supportsContext);
+	return collected;
+}
+/**
+* Select the native block reason according to the pinned event rule.
+* @param eventName - Native Codex hook event name.
+* @param blocks - Ordered block reasons.
+* @returns The selected reason, or `undefined` when no block was contributed.
+*/
+function selectBlockReason(eventName, blocks) {
+	if (blocks.length === 0) return void 0;
+	return FIRST_BLOCK_EVENTS.has(eventName) ? blocks[0] : blocks.join("\n\n");
+}
+/**
+* Serialize a native Codex response.
+* @param body - Native JSON response body.
+* @returns Hook handle response with the serialized body on stdout.
+*/
+function serialize(body) {
+	return {
+		exitCode: 0,
+		stdout: JSON.stringify(body),
+		stderr: ""
+	};
+}
+/**
+* Render a blocking native response outside PreToolUse.
+* @param eventName - Native Codex hook event name.
+* @param reason - Selected block reason.
+* @param hookSpecificOutput - Event-specific context output.
+* @param hasContext - Whether context was contributed.
+* @returns Blocking native response.
+*/
+function renderBlock(eventName, reason, hookSpecificOutput, hasContext) {
+	const context = hasContext ? { hookSpecificOutput } : {};
+	if (eventName === "SessionStart") return serialize({
+		continue: false,
+		stopReason: reason,
+		...context
+	});
+	return serialize({
+		decision: "block",
+		reason,
+		...context
+	});
+}
+/**
+* Render the precedence-sensitive PreToolUse response.
+* @param collected - Effects grouped by native behavior.
+* @param blockReason - Selected block reason, if any.
+* @param hookSpecificOutput - Mutable native event-specific output.
+* @returns A terminal response, or `undefined` when only context remains to render.
+*/
+function renderPreToolUse(collected, blockReason, hookSpecificOutput) {
+	if (blockReason !== void 0) return serialize({
+		decision: "block",
+		reason: blockReason,
+		...collected.contexts.length ? { hookSpecificOutput } : {}
+	});
+	if (collected.denyReasons.length > 0) {
+		hookSpecificOutput.permissionDecision = "deny";
+		hookSpecificOutput.permissionDecisionReason = collected.denyReasons.join("\n");
+	} else if (collected.updates.length > 0) {
+		hookSpecificOutput.permissionDecision = "allow";
+		hookSpecificOutput.updatedInput = collected.updates[0];
+	}
+}
+/**
+* Reduce ordered effects into one provider-valid Codex response.
+* @param eventName - Native Codex hook event name.
+* @param effects - Deterministically ordered effects to reduce.
+* @returns The terminal native hook response.
+*/
+function output(eventName, effects) {
+	const collected = collectEffects(eventName, effects);
+	if (collected.updates.length > 1 && collected.updates.some((candidate) => !isDeepStrictEqual(candidate, collected.updates[0]))) throw new Error("Conflicting Codex PreToolUse input.update effects");
+	const hookSpecificOutput = { hookEventName: eventName };
+	if (collected.contexts.length) hookSpecificOutput.additionalContext = collected.contexts.join("\n");
+	const blockReason = selectBlockReason(eventName, collected.blocks);
+	if (eventName === "PreToolUse") {
+		const response = renderPreToolUse(collected, blockReason, hookSpecificOutput);
+		if (response !== void 0) return response;
+	} else if (blockReason !== void 0) return renderBlock(eventName, blockReason, hookSpecificOutput, collected.contexts.length > 0);
+	if (!collected.contexts.length && collected.denyReasons.length === 0 && collected.updates.length === 0) return NOOP_HOOK_HANDLE_RESPONSE;
+	return serialize({ hookSpecificOutput });
+}
+/**
+* Compose one terminal Codex native hook response.
+* @param registry - Active response contributor registry.
+* @param payload - Normalized native hook payload.
+* @param options - Request deadline, cancellation, and diagnostics hooks.
+* @returns The composed native response envelope.
+*/
+async function composeCodexHookResponse(registry, payload, options) {
+	const snapshot = registry.snapshot(CODEX_CLIENT_ID, CODEX_CONTRACT_ID, payload.eventName, capabilities(payload.eventName));
+	if (!snapshot.length) return NOOP_HOOK_HANDLE_RESPONSE;
+	const result = await collectContributions(snapshot, CODEX_CLIENT_ID, options?.deadline, options?.signal, payload.eventName, payload.payload, codexProviderContractCatalog);
+	if (result.diagnostics.length) options?.onDiagnostics?.(result.diagnostics);
+	if (result.closedFailure) return output(payload.eventName, [{
+		clientId: CODEX_CLIENT_ID,
+		contractId: CODEX_CONTRACT_ID,
+		effects: {
+			decision: "block",
+			reason: result.closedFailure.detail
+		}
+	}]);
+	return output(payload.eventName, result.outcomes.flatMap((outcome) => outcome.effects ?? []));
+}
+
 //#endregion
 //#region src/runtime/namespace.ts
 /**
@@ -2167,6 +2570,8 @@ function mergeOperationErrors(existing, next, message) {
 * the `commandContains` filter in {@link removeCodexWiring}.
 */
 const CODEX_HOOK_COMMAND_SENTINEL = "hook received codex";
+/** Sentinel for synchronous Codex hook responses. */
+const CODEX_HOOK_HANDLE_COMMAND_SENTINEL = "hook handle codex";
 /**
 * Descriptors for all session-events hooks derived from the client definition.
 *
@@ -2188,8 +2593,8 @@ const SESSION_EVENTS = deriveSessionEventDescriptors(clientDefinition);
 */
 async function buildCodexWiringList(settings, makaioCommand, projectDir) {
 	const { effective } = await settings.listHooks(projectDir !== void 0 ? { projectDir } : {});
-	return { entries: SESSION_EVENTS.map(({ eventName }) => {
-		const command = buildHookCommand(makaioCommand, CODEX_HOOK_COMMAND_SENTINEL, eventName, void 0, ["--debounce-failure"]);
+	return { entries: SESSION_EVENTS.map(({ eventName, mode }) => {
+		const command = buildModeCommand(makaioCommand, eventName, mode);
 		return {
 			group: "session-events",
 			name: eventName,
@@ -2218,9 +2623,9 @@ async function applyCodexWiring(settings, scope, makaioCommand, projectDir) {
 	let skipped = 0;
 	const { perScope } = await settings.listHooks(projectDir !== void 0 ? { projectDir } : {});
 	const scopeHooks = perScope.find((s) => s.scope === scope)?.hooks ?? [];
-	for (const { eventName } of SESSION_EVENTS) {
-		const sentinel = `${CODEX_HOOK_COMMAND_SENTINEL} ${eventName}`;
-		const command = buildHookCommand(makaioCommand, CODEX_HOOK_COMMAND_SENTINEL, eventName, void 0, ["--debounce-failure"]);
+	for (const { eventName, mode } of SESSION_EVENTS) {
+		const sentinel = `${mode === "request" ? CODEX_HOOK_HANDLE_COMMAND_SENTINEL : CODEX_HOOK_COMMAND_SENTINEL} ${eventName}`;
+		const command = buildModeCommand(makaioCommand, eventName, mode);
 		const existingEntry = scopeHooks.find((entry) => entry.event === eventName && entry.command.includes(sentinel));
 		if (existingEntry !== void 0) {
 			if (existingEntry.command === command) {
@@ -2261,17 +2666,33 @@ async function applyCodexWiring(settings, scope, makaioCommand, projectDir) {
 */
 async function removeCodexWiring(settings, scope, projectDir) {
 	let removed = 0;
-	for (const { eventName } of SESSION_EVENTS) {
+	for (const { eventName } of SESSION_EVENTS) for (const sentinel of [CODEX_HOOK_COMMAND_SENTINEL, CODEX_HOOK_HANDLE_COMMAND_SENTINEL]) {
 		const result = await settings.removeHook({
 			scope,
 			event: eventName,
-			match: { commandContains: `${CODEX_HOOK_COMMAND_SENTINEL} ${eventName}` },
+			match: { commandContains: `${sentinel} ${eventName}` },
 			...projectDir !== void 0 ? { projectDir } : {}
 		});
 		removed += result.removed;
 	}
 	return { removed };
 }
+/**
+* Build the managed command for one capability-derived hook mode.
+* @param makaioCommand - Makaio CLI executable.
+* @param eventName - Native Codex event name.
+* @param mode - Capability-derived transport mode.
+* @returns Shell-safe managed hook command.
+*/
+function buildModeCommand(makaioCommand, eventName, mode) {
+	return mode === "request" ? buildClientCommand(makaioCommand, [
+		"--no-launch",
+		...CODEX_HOOK_HANDLE_COMMAND_SENTINEL.split(" "),
+		eventName,
+		"--timeout",
+		String(DEFAULT_HOOK_HANDLE_TIMEOUT_MS)
+	]) : buildHookCommand(makaioCommand, CODEX_HOOK_COMMAND_SENTINEL, eventName, void 0, ["--debounce-failure"]);
+}
 
 //#endregion
 //#region src/runtime/codex-client-session-service.ts
@@ -2333,6 +2754,16 @@ var CodexClientSessionService = class extends BaseService {
 	*/
 	managedAdapterSessionIds = /* @__PURE__ */ new Set();
 	/**
+	* Optional provider contract registry for registering and unregistering
+	* the Codex hook response contract during the service lifecycle.
+	*
+	* When `undefined`, contract registration is skipped — this allows
+	* lightweight test construction without requiring a full clients-core
+	* dependency.
+	*/
+	providerContractRegistry;
+	hookResponseRegistry;
+	/**
 	* Creates a new Codex client session service.
 	* @param bus - Bus instance used for subscribing and emitting events
 	* @param settings - Optional {@link CodexClientSettings} instance for tests
@@ -2342,22 +2773,37 @@ var CodexClientSessionService = class extends BaseService {
 	*   caller-supplied from the extension context. Omit in tests or when the
 	*   identity is unavailable.
 	* @param sessionConfigHandler - Optional native auth lease handler override.
+	* @param providerContractRegistry - Optional provider contract registry
+	*   from clients-core for registering the Codex hook response contract.
+	*   Omit in tests that do not exercise the response pipeline.
+	* @param hookResponseRegistry - Optional contributor registry used by the terminal composer.
 	*/
-	constructor(bus = MakaioBus, settings, machineId, sessionConfigHandler = new CodexSessionConfigHandler()) {
+	constructor(bus = MakaioBus, settings, machineId, sessionConfigHandler = new CodexSessionConfigHandler(), providerContractRegistry, hookResponseRegistry) {
 		super(bus);
 		this.settingsOverride = settings;
 		this.machineId = machineId;
 		this.sessionConfigHandler = sessionConfigHandler;
+		this.providerContractRegistry = providerContractRegistry;
+		this.hookResponseRegistry = hookResponseRegistry;
 	}
 	/**
-	* Register the raw hook ingress handler, config management request handlers,
-	* wiring management request handlers, the config-prime lifecycle handler,
-	* and the session config setup/teardown handlers on the bus.
+	* Register the raw hook ingress handler, the `hook.handle` request handler,
+	* config management request handlers, wiring management request handlers,
+	* the config-prime lifecycle handler, and the session config
+	* setup/teardown handlers on the bus.
 	*
 	* Also subscribes to `client.runtime.started` to track adapter-managed
 	* sessions for the {@link handleHookReceived} suppression gate.
+	*
+	* When a {@link ClientHookProviderContractRegistry} was supplied at
+	* construction time, the Codex provider contract is registered so that
+	* contributors can be validated against it during extension activation.
 	*/
 	onInit() {
+		if (this.providerContractRegistry !== void 0) {
+			this.providerContractRegistry.registerProviderContract("codex.runtime", codexProviderContractCatalog);
+			this.addCleanup(() => this.providerContractRegistry?.unregisterProviderContract("codex.runtime", codexProviderContractCatalog.clientId, codexProviderContractCatalog.contractId));
+		}
 		this.registerHandler(ClientSubjects.runtime.started, ({ payload }) => {
 			this.handleRuntimeStarted(payload);
 		});
@@ -2367,6 +2813,7 @@ var CodexClientSessionService = class extends BaseService {
 		this.registerHandler(CodexClientSubjects.hook.received, async ({ payload }) => {
 			await this.handleHookReceived(payload);
 		});
+		this.registerHookHandleHandler();
 		this.registerHandler(CodexClientSubjects.config.hooks.list, async (ctx) => {
 			ctx.setResult(await (await this.createSettings()).listHooks(ctx.payload));
 		});
@@ -2401,13 +2848,44 @@ var CodexClientSessionService = class extends BaseService {
 		});
 	}
 	/**
-	* Clear the adapter-managed session ID set on teardown.
+	* Clear the adapter-managed session ID set and config cache on teardown.
+	*
+	* Provider contract unregistration is handled via {@link addCleanup} in
+	* {@link onInit}, so it runs automatically during the base-class destroy
+	* sequence alongside handler unsubscription.
 	*/
 	onDestroy() {
 		this.managedAdapterSessionIds.clear();
 		this.cachedConfigDir = void 0;
 	}
 	/**
+	* Register the `hook.handle` request handler.
+	*
+	* The handler receives request-mode hook payloads and returns a
+	* {@link ClientHookHandleResponse} composed by
+	* {@link composeCodexHookResponse}. The pinned Codex `0.144.1` source
+	* parses synchronous responses for all five declared events.
+	*
+	* Extracted from {@link onInit} to keep the init method concise.
+	*/
+	registerHookHandleHandler() {
+		this.registerHandler(CodexClientSubjects.hook.handle, (ctx) => {
+			if (!this.hookResponseRegistry) {
+				ctx.setResult({
+					exitCode: 0,
+					stdout: "",
+					stderr: ""
+				});
+				return;
+			}
+			return composeCodexHookResponse(this.hookResponseRegistry, ctx.payload, {
+				deadline: ctx.deadline,
+				signal: ctx.signal,
+				onDiagnostics: (diagnostics) => diagnostics.forEach((diagnostic) => console.warn(`[CodexClientSessionService] Hook contributor '${diagnostic.contributorId}': ${diagnostic.message}`))
+			}).then((response) => ctx.setResult(response));
+		});
+	}
+	/**
 	* Create a settings delegate for the active Codex config root.
 	* @returns Settings instance bound to the managed config dir when available.
 	*/
@@ -2550,4 +3028,4 @@ function isResolveBinaryMissingGlobalBinary(error) {
 }
 
 //#endregion
-export { clientDefinition as C, CodexScopeSchema as S, CodexHookEntrySchema as _, CODEX_CLIENT_NAMESPACE as a, CodexNativeHooksFileSchema as b, CodexWiringSchemas as c, CodexConfigHooksAddResponseSchema as d, CodexConfigHooksListRequestSchema as f, CodexConfigSchemas as g, CodexConfigHooksRemoveResponseSchema as h, withCodexNativeAuthSourceLock as i, AbsolutePathSchema as l, CodexConfigHooksRemoveRequestSchema as m, buildCodexNativeAuthSourceLockPath as n, CodexClientSubjects as o, CodexConfigHooksListResponseSchema as p, executeCodexNativeAuthSourceLock as r, normalizeCodexHook as s, CodexClientSessionService as t, CodexConfigHooksAddRequestSchema as u, CodexNativeCommandHookSchema as v, CodexScopeHookRecordSchema as x, CodexNativeHookMatcherGroupSchema as y };
+export { CodexConfigHooksAddResponseSchema as A, CodexScopeHookRecordSchema as B, createCodexStopBlockEffect as C, CodexWiringSchemas as D, normalizeCodexHook as E, CodexConfigSchemas as F, CODEX_HOOK_RESPONSE_CAPABILITIES as H, CodexHookEntrySchema as I, CodexNativeCommandHookSchema as L, CodexConfigHooksListResponseSchema as M, CodexConfigHooksRemoveRequestSchema as N, AbsolutePathSchema as O, CodexConfigHooksRemoveResponseSchema as P, CodexNativeHookMatcherGroupSchema as R, createCodexSessionStartContextEffect as S, createCodexUserPromptSubmitContextEffect as T, clientDefinition as U, CodexScopeSchema as V, createCodexPreToolUseBlockEffect as _, CODEX_CLIENT_NAMESPACE as a, createCodexPreToolUseUpdateEffect as b, CODEX_CLIENT_ID as c, CODEX_INTERACTION_BLOCKABILITY as d, CODEX_RESPONSE_CAPABILITIES as f, createCodexPostToolUseContextEffect as g, createCodexPostToolUseBlockEffect as h, withCodexNativeAuthSourceLock as i, CodexConfigHooksListRequestSchema as j, CodexConfigHooksAddRequestSchema as k, CODEX_CONTRACT_ID as l, codexProviderContractCatalog as m, buildCodexNativeAuthSourceLockPath as n, CodexClientSubjects as o, CODEX_SUPPORTED_INTERACTIONS as p, executeCodexNativeAuthSourceLock as r, composeCodexHookResponse as s, CodexClientSessionService as t, CODEX_CONTRACT_VERSION as u, createCodexPreToolUseContextEffect as v, createCodexUserPromptSubmitBlockEffect as w, createCodexSessionStartBlockEffect as x, createCodexPreToolUseDenyEffect as y, CodexNativeHooksFileSchema as z };

package/dist/definition.d.ts

@@ -7,6 +7,12 @@
  * capability taxonomy in a single canonical location.
  * @packageDocumentation
  */
+/** Namespaced Codex hook-response capabilities exposed to contributors. */
+export declare const CODEX_HOOK_RESPONSE_CAPABILITIES: Readonly<{
+    readonly block: 'openai.codex-hook-response.block';
+    readonly permissionDeny: 'openai.codex-hook-response.permission.deny';
+    readonly inputUpdate: 'openai.codex-hook-response.input.update';
+}>;
 /**
  * Static client definition for `@makaio/client-codex`.
  *
@@ -79,7 +85,7 @@ export declare const clientDefinition: {
         hookEvents: {
             name: string;
             frameworkSubject?: string | undefined;
-            mode: "event" | "request";
+            responseCapabilities: readonly string[];
         }[];
     };
     managedInstall?: {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { C as clientDefinition, S as CodexScopeSchema, _ as CodexHookEntrySchema, b as CodexNativeHooksFileSchema, c as CodexWiringSchemas, d as CodexConfigHooksAddResponseSchema, f as CodexConfigHooksListRequestSchema, g as CodexConfigSchemas, h as CodexConfigHooksRemoveResponseSchema, l as AbsolutePathSchema, m as CodexConfigHooksRemoveRequestSchema, o as CodexClientSubjects, p as CodexConfigHooksListResponseSchema, t as CodexClientSessionService, u as CodexConfigHooksAddRequestSchema, v as CodexNativeCommandHookSchema, x as CodexScopeHookRecordSchema, y as CodexNativeHookMatcherGroupSchema } from "./codex-client-session-service-B-E98xgY.mjs";
-import { t as codexPackage } from "./src-CXxq1vvn.mjs";
+import { A as CodexConfigHooksAddResponseSchema, B as CodexScopeHookRecordSchema, D as CodexWiringSchemas, F as CodexConfigSchemas, I as CodexHookEntrySchema, L as CodexNativeCommandHookSchema, M as CodexConfigHooksListResponseSchema, N as CodexConfigHooksRemoveRequestSchema, O as AbsolutePathSchema, P as CodexConfigHooksRemoveResponseSchema, R as CodexNativeHookMatcherGroupSchema, U as clientDefinition, V as CodexScopeSchema, j as CodexConfigHooksListRequestSchema, k as CodexConfigHooksAddRequestSchema, o as CodexClientSubjects, t as CodexClientSessionService, z as CodexNativeHooksFileSchema } from "./codex-client-session-service-CTJ576Q4.mjs";
+import { t as codexPackage } from "./src-DXsdjc9S.mjs";
 
 export { AbsolutePathSchema, CodexClientSessionService, CodexClientSubjects, CodexConfigHooksAddRequestSchema, CodexConfigHooksAddResponseSchema, CodexConfigHooksListRequestSchema, CodexConfigHooksListResponseSchema, CodexConfigHooksRemoveRequestSchema, CodexConfigHooksRemoveResponseSchema, CodexConfigSchemas, CodexHookEntrySchema, CodexNativeCommandHookSchema, CodexNativeHookMatcherGroupSchema, CodexNativeHooksFileSchema, CodexScopeHookRecordSchema, CodexScopeSchema, CodexWiringSchemas, clientDefinition, codexPackage };

package/dist/runtime/codex-client-session-service.d.ts

@@ -39,6 +39,7 @@
  * @packageDocumentation
  */
 import type { IMakaioBus } from '@makaio/framework/bus';
+import type { ClientHookProviderContractRegistry, ClientHookResponseRegistry } from '@makaio/framework/clients';
 import { BaseService } from '@makaio/framework/service-base';
 import { CodexClientSettings } from './client-settings.js';
 import { CodexSessionConfigHandler } from './session-config-handler.js';
@@ -97,6 +98,16 @@ export declare class CodexClientSessionService extends BaseService {
      * emissions for sessions that the adapter path already covers.
      */
     private readonly managedAdapterSessionIds;
+    /**
+     * Optional provider contract registry for registering and unregistering
+     * the Codex hook response contract during the service lifecycle.
+     *
+     * When `undefined`, contract registration is skipped — this allows
+     * lightweight test construction without requiring a full clients-core
+     * dependency.
+     */
+    private readonly providerContractRegistry;
+    private readonly hookResponseRegistry;
     /**
      * Creates a new Codex client session service.
      * @param bus - Bus instance used for subscribing and emitting events
@@ -107,21 +118,45 @@ export declare class CodexClientSessionService extends BaseService {
      *   caller-supplied from the extension context. Omit in tests or when the
      *   identity is unavailable.
      * @param sessionConfigHandler - Optional native auth lease handler override.
+     * @param providerContractRegistry - Optional provider contract registry
+     *   from clients-core for registering the Codex hook response contract.
+     *   Omit in tests that do not exercise the response pipeline.
+     * @param hookResponseRegistry - Optional contributor registry used by the terminal composer.
      */
-    constructor(bus?: IMakaioBus, settings?: CodexClientSettings, machineId?: string, sessionConfigHandler?: CodexSessionConfigHandler);
+    constructor(bus?: IMakaioBus, settings?: CodexClientSettings, machineId?: string, sessionConfigHandler?: CodexSessionConfigHandler, providerContractRegistry?: ClientHookProviderContractRegistry, hookResponseRegistry?: ClientHookResponseRegistry);
     /**
-     * Register the raw hook ingress handler, config management request handlers,
-     * wiring management request handlers, the config-prime lifecycle handler,
-     * and the session config setup/teardown handlers on the bus.
+     * Register the raw hook ingress handler, the `hook.handle` request handler,
+     * config management request handlers, wiring management request handlers,
+     * the config-prime lifecycle handler, and the session config
+     * setup/teardown handlers on the bus.
      *
      * Also subscribes to `client.runtime.started` to track adapter-managed
      * sessions for the {@link handleHookReceived} suppression gate.
+     *
+     * When a {@link ClientHookProviderContractRegistry} was supplied at
+     * construction time, the Codex provider contract is registered so that
+     * contributors can be validated against it during extension activation.
      */
     protected onInit(): void;
     /**
-     * Clear the adapter-managed session ID set on teardown.
+     * Clear the adapter-managed session ID set and config cache on teardown.
+     *
+     * Provider contract unregistration is handled via {@link addCleanup} in
+     * {@link onInit}, so it runs automatically during the base-class destroy
+     * sequence alongside handler unsubscription.
      */
     protected onDestroy(): void;
+    /**
+     * Register the `hook.handle` request handler.
+     *
+     * The handler receives request-mode hook payloads and returns a
+     * {@link ClientHookHandleResponse} composed by
+     * {@link composeCodexHookResponse}. The pinned Codex `0.144.1` source
+     * parses synchronous responses for all five declared events.
+     *
+     * Extracted from {@link onInit} to keep the init method concise.
+     */
+    private registerHookHandleHandler;
     private createSettings;
     /**
      * Return the cached config directory promise, resolving it on first access.

package/dist/runtime/hook-response-composer.d.ts

@@ -0,0 +1,15 @@
+import { type ClientHookHandleResponse, type ClientHookResponseRegistry, type CollectionDiagnostic } from '@makaio/framework/clients';
+import { type RawClientHookPayload } from './schemas.js';
+export interface ComposeCodexHookResponseOptions {
+    readonly deadline?: number;
+    readonly signal?: AbortSignal;
+    readonly onDiagnostics?: (diagnostics: readonly CollectionDiagnostic[]) => void;
+}
+/**
+ * Compose one terminal Codex native hook response.
+ * @param registry - Active response contributor registry.
+ * @param payload - Normalized native hook payload.
+ * @param options - Request deadline, cancellation, and diagnostics hooks.
+ * @returns The composed native response envelope.
+ */
+export declare function composeCodexHookResponse(registry: ClientHookResponseRegistry, payload: RawClientHookPayload, options?: ComposeCodexHookResponseOptions): Promise<ClientHookHandleResponse>;

package/dist/runtime/hook-response-contracts.d.ts

@@ -0,0 +1,103 @@
+/** Codex 0.144.1 synchronous hook-response contract. @packageDocumentation */
+import type { InteractionBlockability, ProviderContractCatalogEntry, ProviderContributionEnvelope } from '@makaio/framework/contracts/client';
+export declare const CODEX_CLIENT_ID = "codex";
+export declare const CODEX_CONTRACT_ID = "openai.codex-hook-response";
+export declare const CODEX_CONTRACT_VERSION = "1.1.0";
+export type CodexBlockEffects = Readonly<{
+    decision: 'block';
+    reason: string;
+}> & Record<string, unknown>;
+export type CodexContextEffects = Readonly<{
+    additionalContext: string;
+}> & Record<string, unknown>;
+export type CodexPermissionDenyEffects = Readonly<{
+    permissionDecision: 'deny';
+    permissionDecisionReason: string;
+}> & Record<string, unknown>;
+/** JSON value accepted by Codex's `serde_json::Value` hook parser. */
+export type CodexJsonValue = string | number | boolean | null | readonly CodexJsonValue[] | {
+    readonly [key: string]: CodexJsonValue;
+};
+/**
+ * JSON input accepted as a Codex `updated_input` replacement.
+ *
+ * The pinned Rust hook contract represents the field as `Option<Value>`:
+ * a top-level JSON `null` therefore deserializes as an absent value, while
+ * nested null values remain valid JSON within a present replacement.
+ */
+export type CodexUpdatedInput = Exclude<CodexJsonValue, null>;
+export type CodexInputUpdateEffects = Readonly<{
+    permissionDecision: 'allow';
+    updatedInput: CodexUpdatedInput;
+}> & Record<string, unknown>;
+export type CodexEffects = CodexBlockEffects | CodexContextEffects | CodexPermissionDenyEffects | CodexInputUpdateEffects;
+/**
+ * Builds a SessionStart context response.
+ * @param value - Context appended when the session starts.
+ * @returns A Codex SessionStart context envelope.
+ */
+export declare function createCodexSessionStartContextEffect(value: string): ProviderContributionEnvelope<CodexContextEffects>;
+/**
+ * Builds a SessionStart stop response.
+ * @param reason - Reason for stopping session startup.
+ * @returns A Codex SessionStart block envelope.
+ */
+export declare function createCodexSessionStartBlockEffect(reason: string): ProviderContributionEnvelope<CodexBlockEffects>;
+/**
+ * Builds a UserPromptSubmit context response.
+ * @param value - Context appended to the submitted prompt.
+ * @returns A Codex UserPromptSubmit context envelope.
+ */
+export declare function createCodexUserPromptSubmitContextEffect(value: string): ProviderContributionEnvelope<CodexContextEffects>;
+/**
+ * Builds a UserPromptSubmit block response.
+ * @param reason - Reason for blocking the submitted prompt.
+ * @returns A Codex UserPromptSubmit block envelope.
+ */
+export declare function createCodexUserPromptSubmitBlockEffect(reason: string): ProviderContributionEnvelope<CodexBlockEffects>;
+/**
+ * Builds a PreToolUse block response.
+ * @param reason - Reason for blocking the tool invocation.
+ * @returns A Codex PreToolUse block envelope.
+ */
+export declare function createCodexPreToolUseBlockEffect(reason: string): ProviderContributionEnvelope<CodexBlockEffects>;
+/**
+ * Builds a PreToolUse deny-permission response.
+ * @param reason - Reason for denying the tool invocation.
+ * @returns A Codex PreToolUse permission-denial envelope.
+ */
+export declare function createCodexPreToolUseDenyEffect(reason: string): ProviderContributionEnvelope<CodexPermissionDenyEffects>;
+/**
+ * Builds additional model context for PreToolUse.
+ * @param value - Context appended before the tool invocation.
+ * @returns A Codex PreToolUse context envelope.
+ */
+export declare function createCodexPreToolUseContextEffect(value: string): ProviderContributionEnvelope<CodexContextEffects>;
+/**
+ * Builds a PreToolUse allowed input update.
+ * @param updatedInput - JSON value that replaces the native tool input.
+ * @returns A Codex PreToolUse input-update envelope.
+ */
+export declare function createCodexPreToolUseUpdateEffect(updatedInput: CodexUpdatedInput): ProviderContributionEnvelope<CodexInputUpdateEffects>;
+/**
+ * Builds a PostToolUse context response.
+ * @param value - Context appended after the tool invocation.
+ * @returns A Codex PostToolUse context envelope.
+ */
+export declare function createCodexPostToolUseContextEffect(value: string): ProviderContributionEnvelope<CodexContextEffects>;
+/**
+ * Builds a PostToolUse block response.
+ * @param reason - Reason for blocking after the tool invocation.
+ * @returns A Codex PostToolUse block envelope.
+ */
+export declare function createCodexPostToolUseBlockEffect(reason: string): ProviderContributionEnvelope<CodexBlockEffects>;
+/**
+ * Builds a Stop block response.
+ * @param reason - Reason for requesting another turn.
+ * @returns A Codex Stop block envelope.
+ */
+export declare function createCodexStopBlockEffect(reason: string): ProviderContributionEnvelope<CodexBlockEffects>;
+export declare const CODEX_RESPONSE_CAPABILITIES: readonly string[];
+export declare const CODEX_SUPPORTED_INTERACTIONS: readonly string[];
+export declare const CODEX_INTERACTION_BLOCKABILITY: readonly InteractionBlockability[];
+export declare const codexProviderContractCatalog: ProviderContractCatalogEntry;

package/dist/runtime/namespace.d.ts

@@ -47,7 +47,7 @@ export declare const CodexClientSubjects: import("@makaio/framework/core").BusSu
         payload: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>;
         metadata: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodUnknown>>;
     }, import("zod/v4/core").$strip>;
-    'hook.handle': {
+    'hook.handle': import("@makaio/framework/core").HostLocalRequestSubjectSchema<{
         request: import("zod").ZodObject<{
             eventName: import("zod").ZodString;
             receivedAt: import("zod").ZodNumber;
@@ -59,7 +59,7 @@ export declare const CodexClientSubjects: import("@makaio/framework/core").BusSu
             stdout: import("zod").ZodDefault<import("zod").ZodString>;
             stderr: import("zod").ZodDefault<import("zod").ZodString>;
         }, import("zod/v4/core").$strip>;
-    };
+    }>;
 } & {
     'config.hooks.list': {
         request: import("zod").ZodObject<{

package/dist/runtime/package.d.ts

@@ -3,6 +3,12 @@
  *
  * Exports the {@link MakaioExtension} manifest for the Codex client runtime and
  * re-exports the namespace subjects for client-native integrations.
+ *
+ * The `create()` factory resolves the `clients-core` service via
+ * {@link ClientsCoreToken} and passes its
+ * {@link ClientHookProviderContractRegistry} to the
+ * {@link CodexClientSessionService} so the Codex provider contract is
+ * registered and unregistered alongside the service lifecycle.
  * @packageDocumentation
  */
 import type { IMakaioBus } from '@makaio/framework/bus';
@@ -13,11 +19,19 @@ export { normalizeCodexHook } from './hook-normalizer.js';
 export type { CodexNormalizedEvent, CodexNormalizedSubject } from './hook-normalizer.js';
 export { buildCodexNativeAuthSourceLockPath, executeCodexNativeAuthSourceLock, withCodexNativeAuthSourceLock, } from './native-auth-source-lock.js';
 export type { CodexNativeAuthSourceLockExecution } from './native-auth-source-lock.js';
+export { CODEX_HOOK_RESPONSE_CAPABILITIES } from '../definition.js';
+export { codexProviderContractCatalog, CODEX_CLIENT_ID, CODEX_CONTRACT_ID, CODEX_CONTRACT_VERSION, CODEX_SUPPORTED_INTERACTIONS, CODEX_RESPONSE_CAPABILITIES, CODEX_INTERACTION_BLOCKABILITY, createCodexSessionStartContextEffect, createCodexSessionStartBlockEffect, createCodexUserPromptSubmitContextEffect, createCodexUserPromptSubmitBlockEffect, createCodexPreToolUseBlockEffect, createCodexPreToolUseContextEffect, createCodexPreToolUseDenyEffect, createCodexPreToolUseUpdateEffect, createCodexPostToolUseContextEffect, createCodexPostToolUseBlockEffect, createCodexStopBlockEffect, } from './hook-response-contracts.js';
+export type { CodexEffects, CodexJsonValue } from './hook-response-contracts.js';
+export { composeCodexHookResponse } from './hook-response-composer.js';
 /**
  * MakaioExtension manifest for the Codex client session normalization service.
  *
  * Creates a {@link CodexClientSessionService} that bridges raw
  * `client:codex.hook.received` events into normalized `client.session.*`
  * observations when the Codex descriptor server entry activates.
+ *
+ * The `create()` factory requires the `clients-core` service so provider
+ * contract registration and terminal hook composition cannot silently start
+ * in a non-functional state.
  */
 export declare const codexClientRuntimePackage: MakaioNodeExtension<IMakaioBus>;

package/dist/runtime/package.mjs

@@ -1,5 +1,6 @@
-import { a as CODEX_CLIENT_NAMESPACE, i as withCodexNativeAuthSourceLock, n as buildCodexNativeAuthSourceLockPath, o as CodexClientSubjects, r as executeCodexNativeAuthSourceLock, s as normalizeCodexHook, t as CodexClientSessionService } from "../codex-client-session-service-B-E98xgY.mjs";
+import { C as createCodexStopBlockEffect, E as normalizeCodexHook, H as CODEX_HOOK_RESPONSE_CAPABILITIES, S as createCodexSessionStartContextEffect, T as createCodexUserPromptSubmitContextEffect, _ as createCodexPreToolUseBlockEffect, a as CODEX_CLIENT_NAMESPACE, b as createCodexPreToolUseUpdateEffect, c as CODEX_CLIENT_ID, d as CODEX_INTERACTION_BLOCKABILITY, f as CODEX_RESPONSE_CAPABILITIES, g as createCodexPostToolUseContextEffect, h as createCodexPostToolUseBlockEffect, i as withCodexNativeAuthSourceLock, l as CODEX_CONTRACT_ID, m as codexProviderContractCatalog, n as buildCodexNativeAuthSourceLockPath, o as CodexClientSubjects, p as CODEX_SUPPORTED_INTERACTIONS, r as executeCodexNativeAuthSourceLock, s as composeCodexHookResponse, t as CodexClientSessionService, u as CODEX_CONTRACT_VERSION, v as createCodexPreToolUseContextEffect, w as createCodexUserPromptSubmitBlockEffect, x as createCodexSessionStartBlockEffect, y as createCodexPreToolUseDenyEffect } from "../codex-client-session-service-CTJ576Q4.mjs";
 import { dep } from "@makaio/framework/contracts";
+import { ClientsCoreToken } from "@makaio/framework/clients";
 
 //#region src/runtime/package.ts
 /**
@@ -7,6 +8,12 @@ import { dep } from "@makaio/framework/contracts";
 *
 * Exports the {@link MakaioExtension} manifest for the Codex client runtime and
 * re-exports the namespace subjects for client-native integrations.
+*
+* The `create()` factory resolves the `clients-core` service via
+* {@link ClientsCoreToken} and passes its
+* {@link ClientHookProviderContractRegistry} to the
+* {@link CodexClientSessionService} so the Codex provider contract is
+* registered and unregistered alongside the service lifecycle.
 * @packageDocumentation
 */
 /**
@@ -15,6 +22,10 @@ import { dep } from "@makaio/framework/contracts";
 * Creates a {@link CodexClientSessionService} that bridges raw
 * `client:codex.hook.received` events into normalized `client.session.*`
 * observations when the Codex descriptor server entry activates.
+*
+* The `create()` factory requires the `clients-core` service so provider
+* contract registration and terminal hook composition cannot silently start
+* in a non-functional state.
 */
 const codexClientRuntimePackage = {
 	name: "codex.runtime",
@@ -23,11 +34,19 @@ const codexClientRuntimePackage = {
 	dependencies: [dep("makaio.clients-core")],
 	/**
 	* Create the Codex client session service bound to the runtime bus.
+	*
+	* Resolves the clients-core service via {@link ClientsCoreToken} to
+	* obtain the {@link ClientHookProviderContractRegistry} for provider
+	* contract registration during the service lifecycle.
 	* @param ctx - Runtime package context
 	* @returns Uninitialized Codex client session service
 	*/
-	create: (ctx) => new CodexClientSessionService(ctx.bus, void 0, ctx.machineId)
+	create: (ctx) => {
+		const clientsCore = ctx.getService(ClientsCoreToken);
+		if (!clientsCore) throw new Error("codex.runtime requires makaio.clients-core");
+		return new CodexClientSessionService(ctx.bus, void 0, ctx.machineId, void 0, clientsCore.providerContractRegistry, clientsCore.hookResponseRegistry);
+	}
 };
 
 //#endregion
-export { CODEX_CLIENT_NAMESPACE, CodexClientSessionService, CodexClientSubjects, buildCodexNativeAuthSourceLockPath, codexClientRuntimePackage, executeCodexNativeAuthSourceLock, normalizeCodexHook, withCodexNativeAuthSourceLock };
+export { CODEX_CLIENT_ID, CODEX_CLIENT_NAMESPACE, CODEX_CONTRACT_ID, CODEX_CONTRACT_VERSION, CODEX_HOOK_RESPONSE_CAPABILITIES, CODEX_INTERACTION_BLOCKABILITY, CODEX_RESPONSE_CAPABILITIES, CODEX_SUPPORTED_INTERACTIONS, CodexClientSessionService, CodexClientSubjects, buildCodexNativeAuthSourceLockPath, codexClientRuntimePackage, codexProviderContractCatalog, composeCodexHookResponse, createCodexPostToolUseBlockEffect, createCodexPostToolUseContextEffect, createCodexPreToolUseBlockEffect, createCodexPreToolUseContextEffect, createCodexPreToolUseDenyEffect, createCodexPreToolUseUpdateEffect, createCodexSessionStartBlockEffect, createCodexSessionStartContextEffect, createCodexStopBlockEffect, createCodexUserPromptSubmitBlockEffect, createCodexUserPromptSubmitContextEffect, executeCodexNativeAuthSourceLock, normalizeCodexHook, withCodexNativeAuthSourceLock };

package/dist/runtime/wiring.d.ts

@@ -41,6 +41,8 @@ export interface CodexWiringSettings {
  * the `commandContains` filter in {@link removeCodexWiring}.
  */
 export declare const CODEX_HOOK_COMMAND_SENTINEL = "hook received codex";
+/** Sentinel for synchronous Codex hook responses. */
+export declare const CODEX_HOOK_HANDLE_COMMAND_SENTINEL = "hook handle codex";
 /**
  * Build the wiring entry list, annotated with installation status, by
  * comparing the expected entries against the currently installed Codex hooks.

package/dist/server.mjs

@@ -1,4 +1,4 @@
-import { t as codexPackage } from "./src-CXxq1vvn.mjs";
+import { t as codexPackage } from "./src-DXsdjc9S.mjs";
 import { codexClientRuntimePackage } from "./runtime/package.mjs";
 
 //#region src/server.ts

package/dist/{src-CXxq1vvn.mjs → src-DXsdjc9S.mjs}

@@ -1,4 +1,4 @@
-import { C as clientDefinition } from "./codex-client-session-service-B-E98xgY.mjs";
+import { U as clientDefinition } from "./codex-client-session-service-CTJ576Q4.mjs";
 
 //#region src/package.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makaio/client-codex",
-  "version": "1.0.0-dev-1783973359164",
+  "version": "1.0.0-dev-1784806252593",
   "type": "module",
   "main": "dist/index.mjs",
   "exports": {
@@ -27,7 +27,7 @@
   "dependencies": {
     "@napi-rs/keyring": "^1.2.0",
     "proper-lockfile": "^4.1.2",
-    "smol-toml": "^1.3.0",
+    "smol-toml": "^1.7.0",
     "zod": "4.4.3"
   },
   "files": [