@makaio/client-codex 1.0.0-dev-1779051654000

package/dist/codex-client-session-service-DD2LkxP1.mjs

@@ -0,0 +1,1551 @@
+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 { MakaioBus, RequestError } from "@makaio/framework/bus";
+import { BaseService } from "@makaio/framework/service-base";
+import * as fs$1 from "node:fs/promises";
+import fs from "node:fs/promises";
+import * as path$1 from "node:path";
+import path from "node:path";
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { ClientConfigPrimeSchema, SessionConfigSetupRequestSchema, SessionConfigSetupResponseSchema } from "@makaio/framework/contracts/client";
+
+//#region src/definition.ts
+/**
+* Client definition for the OpenAI Codex CLI.
+*
+* Codex is a first-party agentic coding assistant binary (`codex`) that
+* Makaio harnesses via the codex-app-server adapter. Capability annotations
+* are derived from `codexCapabilityMap` in `@makaio/contracts` to keep
+* capability taxonomy in a single canonical location.
+* @packageDocumentation
+*/
+/**
+* Static client definition for `@makaio/client-codex`.
+*
+* Declares the two native tools the `codex` binary exposes (`bash` and
+* `patch`) and the recommended default approval policy for new harnesses
+* targeting this client.
+*/
+const clientDefinition = createClientDefinition({
+	id: "codex",
+	name: "Codex",
+	version: "0.1.0",
+	description: "OpenAI Codex CLI — an agentic coding assistant",
+	binary: {
+		name: "codex",
+		supportedVersions: "0.130.0"
+	},
+	managedInstall: {
+		type: "npm",
+		package: "@openai/codex",
+		version: "0.130.0"
+	},
+	versionCommand: {
+		executable: {
+			default: "node_modules/.bin/codex",
+			win32: "node_modules/.bin/codex.cmd"
+		},
+		args: ["--version"]
+	},
+	configIsolation: {
+		envVar: "CODEX_HOME",
+		defaultPath: "~/.codex"
+	},
+	nativeTools: [{
+		name: "bash",
+		friendlyName: "Terminal",
+		description: "Execute shell commands in the Codex sandbox",
+		category: "System",
+		capabilities: (codexCapabilityMap.bash ?? []).map((tag) => ({ tag }))
+	}, {
+		name: "patch",
+		friendlyName: "Patch File",
+		description: "Apply unified diff patches to files",
+		category: "Files",
+		capabilities: (codexCapabilityMap.patch ?? []).map((tag) => ({ tag }))
+	}],
+	defaultApprovalPolicy: "full-access",
+	defaultProviderId: "openai-codex",
+	runtimeCapabilities: {
+		supportsHooks: true,
+		supportsStatusline: false,
+		supportsSupervisorLaunch: true,
+		supportsManagedBinary: true,
+		hookEvents: [
+			{
+				name: "SessionStart",
+				frameworkSubject: "client.session.started"
+			},
+			{
+				name: "UserPromptSubmit",
+				frameworkSubject: "client.session.userPrompt.submitted"
+			},
+			{
+				name: "PreToolUse",
+				frameworkSubject: "client.session.tool.pre"
+			},
+			{
+				name: "PostToolUse",
+				frameworkSubject: "client.session.tool.post"
+			},
+			{
+				name: "Stop",
+				frameworkSubject: "client.session.turn.completed"
+			}
+		]
+	}
+});
+
+//#endregion
+//#region src/schemas/config.ts
+/**
+* Codex config management schemas.
+*
+* Defines request/response schema pairs for the `config.hooks.*` subjects in
+* the Codex client namespace. Public request and response payloads expose a
+* flat command-hook view, while `CodexNativeHooksFileSchema` models Codex's
+* nested on-disk `hooks.json` structure for lossless runtime I/O.
+*
+* **Subjects:**
+* - `config.hooks.list` — list effective hooks for a project directory
+* - `config.hooks.add` — add a new hook entry to a scope's config
+* - `config.hooks.remove` — remove hook entries matching a command pattern
+* @packageDocumentation
+*/
+/**
+* Scope enum for Codex hook configuration.
+*
+* - `global` — applies to all Codex sessions regardless of project directory
+* - `project` — scoped to a specific project directory
+*/
+const CodexScopeSchema = z.enum(["global", "project"]);
+/**
+* A single command hook entry in the public config-management API.
+*
+* Codex stores command hooks under `hooks[event][].hooks[]` on disk. The bus
+* API flattens that native shape into `{ event, matcher?, command, timeout? }`
+* so callers can manage hooks without duplicating file-format details.
+*/
+const CodexHookEntrySchema = z.object({
+	/**
+	* The hook event name that triggers this hook (e.g. `SessionStart`,
+	* `PreToolUse`).
+	*/
+	event: z.string(),
+	/**
+	* Optional glob pattern to restrict which tool names trigger the hook.
+	* Absent means the hook applies to all tools for the given event.
+	*/
+	matcher: z.string().optional(),
+	/**
+	* Shell command to execute when the hook fires.
+	*/
+	command: z.string(),
+	/**
+	* Optional timeout in seconds for the hook command.
+	* Absent means no timeout override (the Codex CLI default applies).
+	*/
+	timeout: z.number().optional()
+});
+/**
+* Native Codex command hook handler as stored inside a matcher group.
+*/
+const CodexNativeCommandHookSchema = z.object({
+	/** Codex hook handler type. */
+	type: z.literal("command"),
+	/** Shell command to execute when the hook fires. */
+	command: z.string(),
+	/** Optional UI status message shown while the hook runs. */
+	statusMessage: z.string().optional(),
+	/** Optional timeout in seconds. */
+	timeout: z.number().optional(),
+	/** Alternate timeout spelling accepted by Codex. */
+	timeoutSec: z.number().optional()
+}).passthrough();
+/**
+* Native Codex matcher group as stored under a hook event key.
+*/
+const CodexNativeHookMatcherGroupSchema = z.object({
+	/**
+	* Optional regex matcher. `undefined`, `""`, and `"*"` are all handled by
+	* Codex as broad matches depending on event support.
+	*/
+	matcher: z.string().optional(),
+	/** Hook handlers to run when the matcher group applies. */
+	hooks: z.array(z.unknown())
+}).passthrough();
+/**
+* Native Codex `hooks.json` file shape.
+*
+* Top-level and nested objects are passthrough so runtime writes preserve
+* fields introduced by newer Codex versions instead of stripping them.
+*/
+const CodexNativeHooksFileSchema = z.object({ hooks: z.record(z.string(), z.array(CodexNativeHookMatcherGroupSchema)).optional() }).passthrough();
+/**
+* Per-scope hook configuration record returned by `config.hooks.list`.
+*
+* Describes all hooks registered at a single config scope together with
+* the path to the backing config file and whether it can be written.
+*/
+const CodexScopeHookRecordSchema = z.object({
+	/**
+	* Config scope this record belongs to.
+	*/
+	scope: CodexScopeSchema,
+	/**
+	* Absolute path to the config file backing this scope.
+	*/
+	path: z.string(),
+	/**
+	* Whether the backing config file can be written by the current process.
+	*/
+	writable: z.boolean(),
+	/**
+	* All hooks registered at this scope.
+	*/
+	hooks: z.array(CodexHookEntrySchema)
+});
+/**
+* Request schema for `config.hooks.list`.
+*
+* Returns the effective hook configuration for the given project directory,
+* optionally filtered to a specific event name.
+*/
+const CodexConfigHooksListRequestSchema = z.object({
+	/**
+	* Optional absolute path to the project directory.
+	* When absent, only the global scope is included — project-scoped hooks
+	* are omitted from both `effective` and `perScope`.
+	*/
+	projectDir: AbsolutePathSchema.optional(),
+	/**
+	* Optional event name to filter hooks by (e.g. `PreToolUse`).
+	* When absent all event hooks are returned.
+	*/
+	eventName: z.string().optional()
+});
+/**
+* Response schema for `config.hooks.list`.
+*
+* Returns the merged effective hook list alongside the per-scope breakdown so
+* consumers can determine which config file contributes each hook.
+*/
+const CodexConfigHooksListResponseSchema = z.object({
+	/**
+	* Effective merged hook list after applying scope precedence rules.
+	* This is the set of hooks that actually fire for a Codex session
+	* targeting the given project directory.
+	*/
+	effective: z.array(CodexHookEntrySchema),
+	/**
+	* Per-scope breakdown of hook configuration, ordered from lowest precedence
+	* (global) to highest (project). Each entry includes the backing file path
+	* and writability flag.
+	*/
+	perScope: z.array(CodexScopeHookRecordSchema)
+});
+/**
+* Request schema for `config.hooks.add`.
+*
+* Adds a new hook entry to the specified scope's configuration.
+* The hook entry fields (`event`, `matcher`, `command`, `timeout`) are
+* composed via {@link CodexHookEntrySchema} so any change to the hook shape
+* propagates here automatically.
+*/
+const CodexConfigHooksAddRequestSchema = z.object({
+	/**
+	* Optional absolute path to the project directory.
+	* Required when `scope` is `project` so the correct project config file
+	* can be located.
+	*/
+	projectDir: AbsolutePathSchema.optional(),
+	/**
+	* Config scope to write the hook into.
+	*/
+	scope: CodexScopeSchema
+}).merge(CodexHookEntrySchema).refine((data) => data.scope === "global" || data.projectDir !== void 0, {
+	message: "projectDir is required when scope is project",
+	path: ["projectDir"]
+});
+/**
+* Response schema for `config.hooks.add`.
+*/
+const CodexConfigHooksAddResponseSchema = z.object({ 
+/**
+* Whether the hook entry was successfully written to the config file.
+*/
+added: z.boolean() });
+/**
+* Request schema for `config.hooks.remove`.
+*
+* Removes hook entries from the specified scope's configuration that match
+* both the `event` and the command substring filter.
+*/
+const CodexConfigHooksRemoveRequestSchema = z.object({
+	/**
+	* Optional absolute path to the project directory.
+	* Required when `scope` is `project`.
+	*/
+	projectDir: AbsolutePathSchema.optional(),
+	/**
+	* Config scope from which to remove matching hooks.
+	*/
+	scope: CodexScopeSchema,
+	/**
+	* Event name to match against when selecting hooks for removal.
+	*/
+	event: z.string(),
+	/**
+	* Filter criteria selecting which hooks to remove.
+	* All hooks whose `command` field contains {@link commandContains} as a
+	* substring are removed.
+	*/
+	match: z.object({ 
+	/**
+	* Substring that must appear in the hook command for removal.
+	*/
+commandContains: z.string() })
+}).refine((data) => data.scope === "global" || data.projectDir !== void 0, {
+	message: "projectDir is required when scope is project",
+	path: ["projectDir"]
+});
+/**
+* Response schema for `config.hooks.remove`.
+*/
+const CodexConfigHooksRemoveResponseSchema = z.object({ 
+/**
+* Number of hook entries removed from the config file.
+*/
+removed: z.number() });
+/**
+* Schema record for Codex config management subjects.
+*
+* Pass this record as the `additionalSchemas` argument to
+* {@link createClientNamespace} to register these request/response subjects
+* in the `client:codex.*` namespace.
+*
+* Keys use dotted notation matching the bus subject naming convention:
+* - `config.hooks.list`
+* - `config.hooks.add`
+* - `config.hooks.remove`
+* @example
+* ```typescript
+* import { createClientNamespace } from '@makaio/clients-core';
+* import { CodexConfigSchemas } from './schemas/index.js';
+*
+* const { subjects } = createClientNamespace('codex', CodexConfigSchemas);
+* // subjects.config.hooks.list → 'client:codex.config.hooks.list'
+* ```
+*/
+const CodexConfigSchemas = {
+	/**
+	* List effective hook configuration for a project directory.
+	*
+	* Merges global and project-scoped hooks and returns both the effective list
+	* and the per-scope breakdown.
+	*/
+	"config.hooks.list": {
+		request: CodexConfigHooksListRequestSchema,
+		response: CodexConfigHooksListResponseSchema
+	},
+	/**
+	* Add a new hook entry to a config scope.
+	*/
+	"config.hooks.add": {
+		request: CodexConfigHooksAddRequestSchema,
+		response: CodexConfigHooksAddResponseSchema
+	},
+	/**
+	* Remove hook entries matching an event and command substring from a scope.
+	*/
+	"config.hooks.remove": {
+		request: CodexConfigHooksRemoveRequestSchema,
+		response: CodexConfigHooksRemoveResponseSchema
+	}
+};
+
+//#endregion
+//#region src/schemas/wiring.ts
+/**
+* Schema record for Codex wiring management subjects.
+*
+* Pass this record (spread) as part of the `additionalSchemas` argument to
+* {@link createClientNamespace} to register these request/response subjects
+* in the `client:codex.*` namespace.
+*
+* Keys use dotted notation matching the bus subject naming convention:
+* - `wiring.list`
+* - `wiring.apply`
+* - `wiring.remove`
+* @example
+* ```typescript
+* import { createClientNamespace } from '@makaio/clients-core';
+* import { CodexConfigSchemas } from './schemas/config.js';
+* import { CodexWiringSchemas } from './schemas/wiring.js';
+*
+* const { subjects } = createClientNamespace('codex', {
+*   ...CodexConfigSchemas,
+*   ...CodexWiringSchemas,
+* });
+* // subjects.wiring.list → 'client:codex.wiring.list'
+* ```
+*/
+const CodexWiringSchemas = {
+	/**
+	* List all known wiring entries for the target scope, indicating which are
+	* currently installed in the Codex native config.
+	*
+	* When `projectDir` is absent, only the `global` scope entries are reported.
+	* Callers that need project-scope entries must supply the absolute path to
+	* the project root.
+	*/
+	"wiring.list": {
+		request: z.object({
+			/**
+			* Absolute path of the project directory used to locate project-scope
+			* config files. When absent, only the global scope is consulted.
+			*/
+			projectDir: AbsolutePathSchema.optional(),
+			/**
+			* Makaio shell command to use when building the expected command strings
+			* in the response entries.
+			*/
+			makaioCommand: z.string().min(1)
+		}),
+		response: ClientWiringListResponseSchema
+	},
+	/**
+	* Install all wiring entries into the specified scope.
+	*
+	* Entries already present are skipped (idempotent). The `makaioCommand`
+	* string is written verbatim as the shell command for hook entries.
+	*/
+	"wiring.apply": {
+		request: z.object({
+			/** Scope at which to install the wiring entries. */
+			scope: CodexScopeSchema,
+			/**
+			* Absolute path of the project directory. Required when `scope` is
+			* `'project'`; ignored for `'global'`.
+			*/
+			projectDir: AbsolutePathSchema.optional(),
+			/**
+			* Makaio shell command to write into the native config. Must be
+			* non-empty.
+			*/
+			makaioCommand: z.string().min(1)
+		}).refine((data) => data.scope === "global" || data.projectDir !== void 0, {
+			message: "projectDir is required when scope is project",
+			path: ["projectDir"]
+		}),
+		response: ClientWiringApplyResponseSchema
+	},
+	/**
+	* Uninstall all wiring entries from the specified scope.
+	*
+	* Entries that are not present are silently ignored (idempotent). The
+	* `removed` count in the response reflects only entries that were actually
+	* deleted from the config file.
+	*/
+	"wiring.remove": {
+		request: z.object({
+			/** Scope from which to remove wiring entries. */
+			scope: CodexScopeSchema,
+			/**
+			* Absolute path of the project directory. Required when `scope` is
+			* `'project'`; ignored for `'global'`.
+			*/
+			projectDir: AbsolutePathSchema.optional()
+		}).refine((data) => data.scope === "global" || data.projectDir !== void 0, {
+			message: "projectDir is required when scope is project",
+			path: ["projectDir"]
+		}),
+		response: ClientWiringRemoveResponseSchema
+	}
+};
+
+//#endregion
+//#region src/runtime/settings-paths.ts
+/**
+* Codex client settings path resolution.
+*
+* Provides a pure utility for computing the filesystem paths where Codex
+* stores its `hooks.json` configuration files — one global path under the
+* resolved Codex config directory and an optional project-scoped path.
+*
+* No filesystem I/O is performed; callers are responsible for reading,
+* writing, or watching the returned paths.
+* @packageDocumentation
+*/
+/** Resolved home directory, captured once at module load time. */
+const HOME_DIR = os.homedir();
+/**
+* Resolve the filesystem paths for Codex `hooks.json` configuration files.
+*
+* This is a pure function: it performs no I/O and has no side effects.
+* The returned paths may or may not exist on disk.
+* @param projectDir - Absolute path to the project root directory. When
+*   provided, {@link CodexSettingsPaths.projectHooks} is set to
+*   `{projectDir}/.codex/hooks.json`. When omitted, `projectHooks` is `null`.
+* @param configDir - Optional Codex config root. When omitted, the global
+*   hooks path falls back to `~/.codex/hooks.json`.
+* @returns Resolved paths for the global and optional project-scoped Codex
+*   hooks configuration files.
+*/
+function resolveCodexSettingsPaths(projectDir, configDir) {
+	const globalRoot = configDir ?? path.join(HOME_DIR, ".codex");
+	return {
+		globalHooks: path.join(globalRoot, "hooks.json"),
+		projectHooks: projectDir !== void 0 ? path.join(projectDir, ".codex", "hooks.json") : null
+	};
+}
+
+//#endregion
+//#region src/runtime/client-settings.ts
+/**
+* Codex client settings I/O.
+*
+* Provides filesystem read/write operations for Codex `hooks.json`
+* configuration files. Handles both global and project-scoped config files
+* with atomic writes and per-path write serialization to prevent concurrent
+* modification.
+* @packageDocumentation
+*/
+/** Empty native hooks file used as the baseline for missing files. */
+const EMPTY_HOOKS_FILE = { hooks: {} };
+/**
+* Global per-path write mutex shared across all {@link CodexClientSettings}
+* instances. Module-scoped so that concurrent requests routed to different
+* service-handler instances still serialize writes to the same file.
+*/
+const writeMutex = /* @__PURE__ */ new Map();
+/**
+* Handles reading and writing Codex `hooks.json` configuration files.
+*
+* This is a plain composed component — not a `BaseService` — intended to be
+* instantiated inside `CodexClientSessionService` or a similar host.
+*
+* ## Atomic writes
+* All writes go through a temp-file + `fs.rename()` sequence so that readers
+* never see a partially written file.
+*
+* ## Write serialization
+* A module-scoped per-path mutex ensures that concurrent callers modifying
+* the same file are serialized rather than racing, even across instances.
+*/
+var CodexClientSettings = class {
+	/**
+	* Optional path override used in tests. When `undefined`, paths are
+	* resolved dynamically via {@link resolveCodexSettingsPaths}.
+	*/
+	pathsOverride;
+	/** Optional managed Codex config root for global-scope hooks. */
+	configDir;
+	/**
+	* Creates a new `CodexClientSettings` instance.
+	* @param options - Optional path override or config-root options. Passing
+	*   `{ globalHooks, projectHooks }` remains supported for existing tests.
+	*/
+	constructor(options) {
+		if (options !== void 0 && "globalHooks" in options) {
+			this.pathsOverride = options;
+			this.configDir = void 0;
+			return;
+		}
+		this.pathsOverride = options?.pathsOverride;
+		this.configDir = options?.configDir;
+	}
+	/**
+	* List the effective hook configuration for a project directory.
+	*
+	* Reads both the global and (when available) project-scoped config files,
+	* concatenates their hooks into an effective list, and returns the per-scope
+	* breakdown alongside it.
+	* @param req - Request options. `projectDir` is the optional absolute path to
+	*   the project root (when omitted only the global scope is read).
+	*   `eventName` is an optional event name filter; when omitted all hooks are
+	*   returned.
+	* @returns Effective merged hook list and per-scope breakdown.
+	*/
+	async listHooks(req) {
+		const paths = this.resolvePaths(req.projectDir);
+		const globalPromise = Promise.all([this.readHooksFile(paths.globalHooks), this.isWritable(paths.globalHooks)]);
+		const projectPath = paths.projectHooks;
+		const [globalHooks, globalWritable] = await globalPromise;
+		const perScope = [{
+			scope: "global",
+			path: paths.globalHooks,
+			writable: globalWritable,
+			hooks: globalHooks
+		}];
+		if (projectPath !== null) {
+			const [projectHooks, projectWritable] = await Promise.all([this.readHooksFile(projectPath), this.isWritable(projectPath)]);
+			perScope.push({
+				scope: "project",
+				path: projectPath,
+				writable: projectWritable,
+				hooks: projectHooks
+			});
+		}
+		let effective = perScope.flatMap((record) => record.hooks);
+		if (req.eventName !== void 0) effective = effective.filter((entry) => entry.event === req.eventName);
+		return {
+			effective,
+			perScope
+		};
+	}
+	/**
+	* Add a new hook entry to the specified config scope.
+	*
+	* The operation is idempotent: if a hook with the same `event`, `command`,
+	* and `matcher` already exists in the target file, the file is left
+	* unchanged and `{ added: false }` is returned.
+	* @param req - Hook entry and targeting options. `scope` selects the config
+	*   file; `projectDir` is required when `scope` is `'project'`. `event`,
+	*   `command`, and optional `matcher` / `timeout` form the hook entry.
+	* @returns `{ added: true }` when the hook was appended, `{ added: false }`
+	*   when an identical hook already exists.
+	*/
+	async addHook(req) {
+		const filePath = this.resolvePathForScope(req.scope, req.projectDir);
+		const { result } = await this.modifyHooksFile(filePath, (hooks) => {
+			const eventGroups = hooks.hooks?.[req.event] ?? [];
+			if (eventGroups.some((group) => {
+				if (group.matcher !== req.matcher) return false;
+				return group.hooks.some((handler) => {
+					const parseResult = CodexNativeCommandHookSchema.safeParse(handler);
+					return parseResult.success && parseResult.data.command === req.command;
+				});
+			})) return {
+				hooks,
+				result: { added: false },
+				changed: false
+			};
+			const entry = {
+				type: "command",
+				command: req.command,
+				...req.timeout !== void 0 ? { timeout: req.timeout } : {}
+			};
+			const matchingGroupIndex = eventGroups.findIndex((group) => group.matcher === req.matcher);
+			const updatedGroups = matchingGroupIndex === -1 ? [...eventGroups, {
+				...req.matcher !== void 0 ? { matcher: req.matcher } : {},
+				hooks: [entry]
+			}] : eventGroups.map((group, index) => index === matchingGroupIndex ? {
+				...group,
+				hooks: [...group.hooks, entry]
+			} : group);
+			return {
+				hooks: {
+					...hooks,
+					hooks: {
+						...hooks.hooks ?? {},
+						[req.event]: updatedGroups
+					}
+				},
+				result: { added: true },
+				changed: true
+			};
+		});
+		return result;
+	}
+	/**
+	* Remove hook entries from the specified config scope.
+	*
+	* Removes all hooks where `entry.event === req.event` and
+	* `entry.command.includes(req.match.commandContains)`.
+	* @param req - Removal criteria and targeting options. `scope` selects the
+	*   config file; `projectDir` is required when `scope` is `'project'`.
+	*   `event` is the event name to match. `match.commandContains` is the
+	*   command substring filter — any hook whose command contains this string
+	*   is removed.
+	* @returns `{ removed: n }` where `n` is the count of removed hooks.
+	*/
+	async removeHook(req) {
+		const filePath = this.resolvePathForScope(req.scope, req.projectDir);
+		const { result } = await this.modifyHooksFile(filePath, (hooks) => {
+			const eventGroups = hooks.hooks?.[req.event] ?? [];
+			let removed = 0;
+			const updatedGroups = eventGroups.map((group) => {
+				const remainingHandlers = group.hooks.filter((handler) => {
+					const parseResult = CodexNativeCommandHookSchema.safeParse(handler);
+					const shouldRemove = parseResult.success && parseResult.data.command.includes(req.match.commandContains);
+					if (shouldRemove) removed += 1;
+					return !shouldRemove;
+				});
+				return {
+					...group,
+					hooks: remainingHandlers
+				};
+			}).filter((group) => group.hooks.length > 0);
+			if (removed === 0) return {
+				hooks,
+				result: { removed },
+				changed: false
+			};
+			const updatedHooksByEvent = { ...hooks.hooks ?? {} };
+			if (updatedGroups.length === 0) delete updatedHooksByEvent[req.event];
+			else updatedHooksByEvent[req.event] = updatedGroups;
+			return {
+				hooks: {
+					...hooks,
+					hooks: updatedHooksByEvent
+				},
+				result: { removed },
+				changed: true
+			};
+		});
+		return result;
+	}
+	/**
+	* Resolve config file path for a given scope.
+	*
+	* For `'project'` scope, `projectDir` must be provided. For `'global'`
+	* scope, `projectDir` is ignored.
+	* @param scope - Target config scope.
+	* @param projectDir - Optional absolute path to the project root.
+	* @returns Absolute path to the `hooks.json` file for the given scope.
+	* @throws When `scope === 'project'` and `projectDir` is absent.
+	*/
+	resolvePathForScope(scope, projectDir) {
+		const paths = this.resolvePaths(projectDir);
+		if (scope === "project") {
+			if (!paths.projectHooks) throw new Error("Cannot access project scope: projectDir is required");
+			return paths.projectHooks;
+		}
+		return paths.globalHooks;
+	}
+	/**
+	* Resolve settings paths, applying the optional test override when present.
+	* @param projectDir - Optional project root passed through to
+	*   {@link resolveCodexSettingsPaths} when no override is active.
+	* @returns Resolved settings paths.
+	*/
+	resolvePaths(projectDir) {
+		if (this.pathsOverride !== void 0) return this.pathsOverride;
+		return resolveCodexSettingsPaths(projectDir, this.configDir);
+	}
+	/**
+	* Check whether the current process can write to a path.
+	*
+	* First tests the file itself (when it exists). If that check fails or the
+	* file does not yet exist, walks up from the parent directory until an
+	* existing ancestor is found and checks write permission there. This handles
+	* the fresh-install case where neither the file nor its `.codex/` parent
+	* exist yet — the write helper creates the tree via `mkdir({ recursive })`,
+	* so writability depends on the nearest existing ancestor.
+	* @param filePath - Absolute path to the file to test.
+	* @returns `true` when the process has write access, `false` otherwise.
+	*/
+	async isWritable(filePath) {
+		try {
+			await fs.access(filePath, fs.constants.W_OK);
+			return true;
+		} catch {
+			let candidate = path.dirname(filePath);
+			for (;;) try {
+				await fs.access(candidate, fs.constants.W_OK);
+				return true;
+			} catch (error) {
+				if (error.code !== "ENOENT") return false;
+				const parent = path.dirname(candidate);
+				if (parent === candidate) return false;
+				candidate = parent;
+			}
+		}
+	}
+	/**
+	* Read and parse a Codex `hooks.json` file.
+	*
+	* Returns an empty array when the file does not exist (`ENOENT`) or when no
+	* command hooks are configured. Re-throws `SyntaxError` on corrupt JSON and
+	* permission errors without swallowing. Throws a descriptive `Error` when the
+	* native `hooks` tree fails schema validation.
+	* @param filePath - Absolute path to the `hooks.json` file.
+	* @returns Flattened command hook entries for public bus responses.
+	* @throws When a `hooks` field is present but does not conform to Codex's
+	*   native grouped hook schema.
+	*/
+	async readHooksFile(filePath) {
+		return this.flattenHooksFile(await this.readHooksDocument(filePath));
+	}
+	/**
+	* Read and parse a native Codex `hooks.json` file.
+	*
+	* Missing files resolve to an empty native document. Unknown top-level and
+	* nested fields are preserved by the schema so read-modify-write operations
+	* can update a target hook without dropping newer Codex fields.
+	* @param filePath - Absolute path to the `hooks.json` file.
+	* @returns Parsed native hooks document.
+	* @throws When JSON parsing fails or the `hooks` field is not a native Codex
+	*   event-to-matcher-group map.
+	*/
+	async readHooksDocument(filePath) {
+		let content;
+		try {
+			content = await fs.readFile(filePath, "utf-8");
+		} catch (error) {
+			if (error.code === "ENOENT") return { ...EMPTY_HOOKS_FILE };
+			throw error;
+		}
+		const parsed = JSON.parse(content);
+		const parseResult = CodexNativeHooksFileSchema.safeParse(parsed);
+		if (!parseResult.success) throw new Error(`Invalid hooks file ${filePath}: ${parseResult.error.message}`);
+		return parseResult.data;
+	}
+	/**
+	* Flatten a native Codex hooks document into the public command-hook view.
+	* @param document - Native Codex hooks document.
+	* @returns Flat command-hook entries ordered by event, matcher group, then
+	*   handler order.
+	*/
+	flattenHooksFile(document) {
+		const entries = [];
+		for (const [event, groups] of Object.entries(document.hooks ?? {})) for (const group of groups) for (const rawHandler of group.hooks) {
+			const parseResult = CodexNativeCommandHookSchema.safeParse(rawHandler);
+			if (!parseResult.success) continue;
+			const handler = parseResult.data;
+			entries.push({
+				event,
+				...group.matcher !== void 0 ? { matcher: group.matcher } : {},
+				command: handler.command,
+				...handler.timeout !== void 0 ? { timeout: handler.timeout } : handler.timeoutSec !== void 0 ? { timeout: handler.timeoutSec } : {}
+			});
+		}
+		return entries;
+	}
+	/**
+	* Read, modify, and atomically write a Codex `hooks.json` file.
+	*
+	* Delegates serialization and atomic I/O to {@link atomicModifyFile}.
+	* The parent directory is created automatically when absent.  Write errors
+	* surface to the current caller; the mutex queue continues regardless.
+	* @param filePath - Absolute path to the `hooks.json` file to modify.
+	* @param modifier - Pure function that receives the current native hooks
+	*   document and returns the updated document, whether it changed, and a
+	*   caller-defined result value.
+	* @returns The `result` value produced by the modifier.
+	*/
+	async modifyHooksFile(filePath, modifier) {
+		return { result: await atomicModifyFile(filePath, { ...EMPTY_HOOKS_FILE }, writeMutex, (rawContent) => {
+			const parseResult = CodexNativeHooksFileSchema.safeParse(rawContent);
+			if (!parseResult.success) throw new Error(`Invalid hooks file ${filePath}: ${parseResult.error.message}`);
+			return parseResult.data;
+		}, (hooks) => {
+			const { hooks: updated, result: innerResult, changed } = modifier(hooks);
+			return {
+				content: updated,
+				changed,
+				result: innerResult
+			};
+		}) };
+	}
+};
+
+//#endregion
+//#region src/runtime/config-prime-handler.ts
+/**
+* Codex config-prime handler.
+*
+* Handles the `client:codex.config.prime` delegation subject fired by the
+* framework at three lifecycle phases: `managed-install`, `profile-create`,
+* and `session-create`.
+*
+* The handler ensures that `check_for_update_on_startup = false` is present
+* in the Codex `config.toml` file inside the target directory so that managed
+* Codex processes never attempt to auto-update during a Makaio-controlled
+* session. All other existing config keys are preserved; the key is replaced
+* when it already exists with any value, and appended when absent.
+*
+* Writes are atomic (tmp-file + rename) to prevent readers from observing a
+* partially written file. The operation is idempotent: when the file already
+* contains the correct value the write is skipped entirely.
+* @packageDocumentation
+*/
+/**
+* Prime the Codex `config.toml` in the target config directory.
+*
+* Ensures that `check_for_update_on_startup = false` is set, preserving all
+* other existing key-value pairs. Existing occurrences of the key (with any
+* value) are replaced; the key is appended when absent. Empty lines are
+* stripped to keep the file compact.
+*
+* The write is atomic via a temporary file + `fs.rename()` to prevent readers
+* from observing a partially written file. The operation is idempotent: when
+* the file already contains the correct value the disk is not touched.
+* @param payload - Config prime request containing `clientId`, `configDir`,
+*   and `phase`. Additional optional fields (`binaryVersion`, `adapterName`,
+*   `projectDir`) are accepted but not used by the Codex prime handler.
+* @returns `{ primed: true }` on success.
+*/
+async function handleCodexConfigPrime(payload) {
+	const configPath = path$1.join(payload.configDir, "config.toml");
+	await fs$1.mkdir(payload.configDir, { recursive: true });
+	let current = "";
+	try {
+		current = await fs$1.readFile(configPath, "utf-8");
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	const lines = current.split(/\r?\n/).filter((line) => !line.trimStart().startsWith("check_for_update_on_startup")).filter((line) => line.length > 0);
+	const tableIndex = lines.findIndex((line) => line.trimStart().startsWith("["));
+	if (tableIndex === -1) lines.push("check_for_update_on_startup = false");
+	else lines.splice(tableIndex, 0, "check_for_update_on_startup = false");
+	const updated = `${lines.join("\n")}\n`;
+	if (updated === current) return { primed: true };
+	const tmpPath = path$1.join(payload.configDir, `config.toml.${randomUUID()}.tmp`);
+	await fs$1.writeFile(tmpPath, updated, "utf-8");
+	await fs$1.rename(tmpPath, configPath);
+	return { primed: true };
+}
+
+//#endregion
+//#region src/runtime/hook-normalizer.ts
+/**
+* Pure normalizer for Codex CLI hook events.
+*
+* Maps the Codex-native hook event names emitted on
+* `client:codex.hook.received` to their corresponding
+* `client.session.*` observed-semantics subjects.
+*
+* **Mapping table** (Codex event → global subject):
+*
+* | Codex event name         | Global subject                          |
+* |--------------------------|------------------------------------------|
+* | `SessionStart`           | `client.session.started`                |
+* | `UserPromptSubmit`       | `client.session.userPrompt.submitted`   |
+* | `Stop`                   | `client.session.turn.completed`         |
+* | `PreToolUse`             | `client.session.tool.pre`               |
+* | `PostToolUse`            | `client.session.tool.post`              |
+*
+* All other event names are returned as `null` — they are kept raw only and
+* are never emitted into the global `client.*` namespace.
+*
+* **Source notes:** The Codex CLI hook event names above reflect the OpenAI
+* Codex CLI hook system as documented at the time of authoring. If the binary
+* changes its hook names, update {@link CODEX_EVENT_MAP} accordingly.
+* @packageDocumentation
+*/
+/**
+* Static map from Codex-native hook event name to the matching global subject.
+*
+* Update this map when the Codex CLI exposes new hook names that correspond
+* to global session lifecycle events.
+*/
+const CODEX_EVENT_MAP = new Map([
+	["SessionStart", ClientSubjects.session.started],
+	["UserPromptSubmit", ClientSubjects.session.userPrompt.submitted],
+	["Stop", ClientSubjects.session.turn.completed],
+	["PreToolUse", ClientSubjects.session.tool.pre],
+	["PostToolUse", ClientSubjects.session.tool.post]
+]);
+/**
+* Extract optional session identifier from a raw Codex hook payload.
+*
+* Codex may report the session ID under `session_id` or `thread_id`.
+* Both are checked because early events may use `thread_id` before a
+* canonical session is established.
+* @param payload - Raw hook payload object forwarded by the ingress bridge
+* @returns Resolved adapter session ID string, or `undefined` when absent
+*/
+function extractAdapterSessionId(payload) {
+	return pickNonEmptyString(payload, "session_id") ?? pickNonEmptyString(payload, "thread_id");
+}
+/**
+* Extract optional tool name from a raw Codex hook payload.
+*
+* Codex reports the tool name under `tool_name` for pre/post tool calls.
+* @param payload - Raw hook payload object
+* @returns Tool name string, or `undefined` when absent
+*/
+function extractToolName(payload) {
+	return pickNonEmptyString(payload, "tool_name");
+}
+/**
+* Extract optional tool call correlation ID from a raw Codex hook payload.
+* @param payload - Raw hook payload object
+* @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;
+}
+/**
+* Extract optional prompt text from a raw Codex user-prompt payload.
+* @param payload - Raw hook payload object
+* @returns Non-empty prompt string, or `undefined` when absent
+*/
+function extractPrompt(payload) {
+	return pickNonEmptyString(payload, "prompt");
+}
+/**
+* Normalize a raw Codex hook payload into a `client.session.*` event.
+*
+* Returns `null` for unknown or not-yet-modeled event names so the caller
+* skips global emission and keeps the event raw-only in `client:codex.*`.
+* @param raw - Raw hook payload delivered on `client:codex.hook.received`
+* @returns Normalized event with subject and typed payload, or `null` when
+*   the event name is unknown
+*/
+function normalizeCodexHook(raw) {
+	const subject = CODEX_EVENT_MAP.get(raw.eventName);
+	if (subject === void 0) return null;
+	const base = {
+		clientId: "codex",
+		source: "native-hook",
+		observedAt: raw.receivedAt,
+		adapterSessionId: extractAdapterSessionId(raw.payload),
+		metadata: raw.metadata
+	};
+	switch (subject) {
+		case ClientSubjects.session.started: return {
+			subject,
+			payload: { ...base }
+		};
+		case ClientSubjects.session.userPrompt.submitted: return {
+			subject,
+			payload: {
+				...base,
+				prompt: extractPrompt(raw.payload)
+			}
+		};
+		case ClientSubjects.session.turn.completed: return {
+			subject,
+			payload: { ...base }
+		};
+		case ClientSubjects.session.tool.pre: return {
+			subject,
+			payload: {
+				...base,
+				toolName: extractToolName(raw.payload),
+				toolCallId: extractToolCallId(raw.payload)
+			}
+		};
+		case ClientSubjects.session.tool.post: return {
+			subject,
+			payload: {
+				...base,
+				toolName: extractToolName(raw.payload),
+				toolCallId: extractToolCallId(raw.payload),
+				success: extractSuccess(raw.payload)
+			}
+		};
+		default: return null;
+	}
+}
+
+//#endregion
+//#region src/runtime/namespace.ts
+/**
+* Codex client namespace registration.
+*
+* Registers `client:codex` on the singleton bus using the shared
+* {@link createClientNamespace} factory, which pre-registers the raw catch-all
+* hook ingress subject `hook.received` with the canonical
+* {@link RawClientHookPayloadSchema}.
+*
+* Additional subjects registered here:
+* - `config.hooks.list` — list effective hook configuration
+* - `config.hooks.add` — add a hook entry to a config scope
+* - `config.hooks.remove` — remove hook entries matching a pattern
+* - `config.prime` — blocking config-prime lifecycle hook
+* - `wiring.list` — list all wiring entries with installation status
+* - `wiring.apply` — install wiring entries into the target scope
+* - `wiring.remove` — uninstall wiring entries from the target scope
+* - `sessionConfig.setup` — seed an isolated session config directory
+*
+* **Subject conventions:**
+* - Raw Codex-native events flow in the `client:codex.*` namespace only.
+* - Normalized lifecycle observations flow in the global `client.session.*`
+*   namespace after the {@link CodexHookNormalizer} maps them.
+* @packageDocumentation
+*/
+const { subjects, namespaceDomain } = createClientNamespace("codex", {
+	...CodexConfigSchemas,
+	...CodexWiringSchemas,
+	"config.prime": ClientConfigPrimeSchema,
+	"sessionConfig.setup": {
+		request: SessionConfigSetupRequestSchema,
+		response: SessionConfigSetupResponseSchema
+	}
+});
+/**
+* Typed bus subjects for the Codex client namespace (`client:codex.*`).
+*
+* Exposes the raw hook ingress subject, config management subjects, wiring
+* management subjects, the config-prime lifecycle hook, and the session config
+* setup subject:
+* - `CodexClientSubjects.hook.received` → `client:codex.hook.received`
+* - `CodexClientSubjects.config.hooks.list` → `client:codex.config.hooks.list`
+* - `CodexClientSubjects.config.hooks.add` → `client:codex.config.hooks.add`
+* - `CodexClientSubjects.config.hooks.remove` → `client:codex.config.hooks.remove`
+* - `CodexClientSubjects.config.prime` → `client:codex.config.prime`
+* - `CodexClientSubjects.wiring.list` → `client:codex.wiring.list`
+* - `CodexClientSubjects.wiring.apply` → `client:codex.wiring.apply`
+* - `CodexClientSubjects.wiring.remove` → `client:codex.wiring.remove`
+* - `CodexClientSubjects.sessionConfig.setup` → `client:codex.sessionConfig.setup`
+*/
+const CodexClientSubjects = subjects;
+/**
+* Fully-qualified namespace domain string for the Codex client.
+*
+* Value: `'client:codex'`
+*/
+const CODEX_CLIENT_NAMESPACE = namespaceDomain;
+
+//#endregion
+//#region src/runtime/session-config-handler.ts
+/**
+* Codex session config setup handler.
+*
+* Implements the `client:codex.sessionConfig.setup` delegation request by
+* materializing the Codex config files needed for an isolated session
+* directory.
+*
+* The handler copies `config.toml` and `auth.json` from the base config
+* directory (when present) into the session-scoped directory, then primes the
+* session directory to ensure `check_for_update_on_startup = false` is set.
+*
+* When `sessionDir` and `baseConfigDir` resolve to the same path (the
+* framework passes `sessionDir` as `baseConfigDir` when no profile is
+* configured) the copy step is skipped and only the prime step runs.
+*
+* Returns `{ env: { CODEX_HOME: sessionDir } }` so the spawned Codex process
+* inherits the isolated session directory as its configuration root.
+* @packageDocumentation
+*/
+/**
+* Copy a file if it exists at the source path; silently skip when absent.
+* @param src - Source file path.
+* @param dst - Destination file path.
+*/
+async function copyIfPresent(src, dst) {
+	try {
+		await fs$1.copyFile(src, dst);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+}
+/**
+* Handle `client:codex.sessionConfig.setup` by seeding the session-scoped
+* directory with the appropriate Codex config files.
+*
+* Steps:
+* 1. Create `sessionDir` (recursive, no-op when it already exists).
+* 2. When `sessionDir` and `baseConfigDir` are distinct paths, copy
+* `config.toml` and `auth.json` from `baseConfigDir` into `sessionDir`
+* (each copy is skipped when the source file does not exist).
+* 3. Prime `sessionDir` via {@link handleCodexConfigPrime} to ensure
+* `check_for_update_on_startup = false` is set.
+* @param payload - Session config setup delegation payload. Only `sessionDir`,
+*   `baseConfigDir`, and `projectDir` are used; `platform` and
+*   `configInheritance` are accepted for interface compatibility but are not
+*   required for Codex's simpler config model.
+* @returns Environment variables for the spawned Codex process: `CODEX_HOME`
+*   pointing to `sessionDir`.
+*/
+async function handleCodexSessionConfigSetup(payload) {
+	const { sessionDir, baseConfigDir, projectDir } = payload;
+	await fs$1.mkdir(sessionDir, { recursive: true });
+	if (path$1.resolve(sessionDir) !== path$1.resolve(baseConfigDir)) {
+		await copyIfPresent(path$1.join(baseConfigDir, "config.toml"), path$1.join(sessionDir, "config.toml"));
+		await copyIfPresent(path$1.join(baseConfigDir, "auth.json"), path$1.join(sessionDir, "auth.json"));
+	}
+	await handleCodexConfigPrime({
+		clientId: "codex",
+		configDir: sessionDir,
+		phase: "session-create",
+		...projectDir !== void 0 ? { projectDir } : {}
+	});
+	return { env: { CODEX_HOME: sessionDir } };
+}
+
+//#endregion
+//#region src/runtime/wiring.ts
+/**
+* Substring used to identify Makaio-managed Codex hook commands.
+*
+* The full command for a given event takes the form:
+* `<makaioCommand> hook received codex <EventName>`
+*
+* This sentinel is written verbatim by {@link applyCodexWiring} and used as
+* the `commandContains` filter in {@link removeCodexWiring}.
+*/
+const CODEX_HOOK_COMMAND_SENTINEL = "hook received codex";
+/**
+* Descriptors for all session-events hooks derived from the client definition.
+*
+* Only events with a defined `frameworkSubject` are included — events without
+* one are Codex-internal and do not need framework wiring.
+*/
+const SESSION_EVENTS = deriveSessionEventDescriptors(clientDefinition);
+/**
+* Build the wiring entry list, annotated with installation status, by
+* comparing the expected entries against the currently installed Codex hooks.
+*
+* Reads hooks from the global scope only when `projectDir` is absent; includes
+* project-scope hooks when `projectDir` is provided.
+* @param settings - {@link CodexClientSettings} instance for hook I/O.
+* @param makaioCommand - Base makaio shell command written into the config.
+* @param projectDir - Optional absolute project directory.  When absent only
+*   the global scope is checked.
+* @returns Object containing all wiring entries with `installed` flags.
+*/
+async function buildCodexWiringList(settings, makaioCommand, projectDir) {
+	const { effective } = await settings.listHooks(projectDir !== void 0 ? { projectDir } : {});
+	return { entries: SESSION_EVENTS.map(({ eventName }) => {
+		const sentinel = `${CODEX_HOOK_COMMAND_SENTINEL} ${eventName}`;
+		const command = buildHookCommand(makaioCommand, CODEX_HOOK_COMMAND_SENTINEL, eventName);
+		return {
+			group: "session-events",
+			name: eventName,
+			installed: effective.some((entry) => entry.event === eventName && entry.command.includes(sentinel)),
+			command
+		};
+	}) };
+}
+/**
+* Install all session-event wiring entries into the specified scope.
+*
+* The operation uses replace semantics when `makaioCommand` changes: if a hook
+* for an event already contains the sentinel but with a different command
+* prefix, the old hook is removed before the new one is added.  When the
+* identical command is already present the entry is skipped unchanged.
+* @param settings - {@link CodexClientSettings} instance for hook I/O.
+* @param scope - Target scope (`'global'` or `'project'`).
+* @param makaioCommand - Base makaio shell command written into each hook.
+* @param projectDir - Absolute project directory.  Required when `scope` is
+*   `'project'`; ignored for `'global'`.
+* @returns Counts of applied (newly written or replaced) and skipped (already
+*   present) entries.
+*/
+async function applyCodexWiring(settings, scope, makaioCommand, projectDir) {
+	let applied = 0;
+	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);
+		const existingEntry = scopeHooks.find((entry) => entry.event === eventName && entry.command.includes(sentinel));
+		if (existingEntry !== void 0) {
+			if (existingEntry.command === command) {
+				skipped += 1;
+				continue;
+			}
+			await settings.removeHook({
+				scope,
+				event: eventName,
+				match: { commandContains: sentinel },
+				...projectDir !== void 0 ? { projectDir } : {}
+			});
+		}
+		if ((await settings.addHook({
+			scope,
+			event: eventName,
+			command,
+			...projectDir !== void 0 ? { projectDir } : {}
+		})).added) applied += 1;
+		else skipped += 1;
+	}
+	return {
+		applied,
+		skipped
+	};
+}
+/**
+* Remove all Makaio-managed session-event wiring entries from the specified
+* scope.
+*
+* Entries that are not present are silently ignored — the operation is
+* idempotent.
+* @param settings - {@link CodexClientSettings} instance for hook I/O.
+* @param scope - Target scope (`'global'` or `'project'`).
+* @param projectDir - Absolute project directory.  Required when `scope` is
+*   `'project'`; ignored for `'global'`.
+* @returns Count of entries actually removed from the config file.
+*/
+async function removeCodexWiring(settings, scope, projectDir) {
+	let removed = 0;
+	for (const { eventName } of SESSION_EVENTS) {
+		const result = await settings.removeHook({
+			scope,
+			event: eventName,
+			match: { commandContains: `${CODEX_HOOK_COMMAND_SENTINEL} ${eventName}` },
+			...projectDir !== void 0 ? { projectDir } : {}
+		});
+		removed += result.removed;
+	}
+	return { removed };
+}
+
+//#endregion
+//#region src/runtime/codex-client-session-service.ts
+/** Stable client ID for Codex — used to filter `client.runtime.started` events. */
+const CLIENT_ID = "codex";
+/**
+* Maximum number of adapter-managed session IDs retained in
+* {@link CodexClientSessionService.managedAdapterSessionIds}.
+*
+* Concurrent active Codex sessions are typically single-digit, so this
+* cap is a safety net against unbounded growth in long-lived processes.  When
+* the cap is reached, the oldest recorded ID is evicted (FIFO) before the new
+* one is inserted.
+*/
+const MANAGED_SESSION_CAP = 1e4;
+/**
+* Service that normalizes raw Codex hook events into global
+* `client.session.*` observed-semantics events and handles Codex config
+* management requests on `client:codex.config.hooks.*`.
+*
+* Lifecycle:
+* 1. `init()` — subscribes to `client:codex.hook.received`, subscribes to
+*    `client.runtime.started` for the adapter-managed session gate, and
+*    registers request handlers for `config.hooks.list`, `config.hooks.add`,
+*    `config.hooks.remove`, `config.prime`, `wiring.list`, `wiring.apply`,
+*    `wiring.remove`, and `sessionConfig.setup`.
+* 2. On each incoming raw event, calls {@link normalizeCodexHook}.
+* 3. Emits the normalized subject when the event is recognized; silently
+*    ignores unknown events.  Normalized `client.session.*` events are
+*    suppressed when the `adapterSessionId` is already in the adapter-managed
+*    set.
+* 4. `destroy()` — unsubscribes all handlers automatically via `BaseService`.
+*/
+var CodexClientSessionService = class extends BaseService {
+	/** Optional injected settings I/O delegate for tests. */
+	settingsOverride;
+	/** Cached active config-dir resolution; reset when the active Codex version changes. */
+	cachedConfigDir;
+	/**
+	* Set of `adapterSessionId` values known to be owned by an adapter-managed
+	* Codex runtime.  Populated by {@link handleRuntimeStarted} when a
+	* `client.runtime.started` event arrives with `clientId === CLIENT_ID` and
+	* `source.layer === 'adapter'`.
+	*
+	* Bounded at {@link MANAGED_SESSION_CAP} entries — the oldest ID is evicted
+	* (FIFO) when the cap is reached.
+	*
+	* Used by {@link handleHookReceived} to gate duplicate `client.session.*`
+	* emissions for sessions that the adapter path already covers.
+	*/
+	managedAdapterSessionIds = /* @__PURE__ */ new Set();
+	/**
+	* 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
+	*   that need exact filesystem paths. Production callers should omit it so
+	*   the service can resolve the active managed config dir via the bus.
+	*/
+	constructor(bus = MakaioBus, settings) {
+		super(bus);
+		this.settingsOverride = settings;
+	}
+	/**
+	* Register the raw hook ingress handler, config management request handlers,
+	* wiring management request handlers, the config-prime lifecycle handler,
+	* and the session config setup handler on the bus.
+	*
+	* Also subscribes to `client.runtime.started` to track adapter-managed
+	* sessions for the {@link handleHookReceived} suppression gate.
+	*/
+	onInit() {
+		this.registerHandler(ClientSubjects.runtime.started, ({ payload }) => {
+			this.handleRuntimeStarted(payload);
+		});
+		this.registerHandler(ClientSubjects.version.changed, ({ payload }) => {
+			if (payload.clientId === CLIENT_ID) this.cachedConfigDir = void 0;
+		});
+		this.registerHandler(CodexClientSubjects.hook.received, async ({ payload }) => {
+			await this.handleHookReceived(payload);
+		});
+		this.registerHandler(CodexClientSubjects.config.hooks.list, async (ctx) => {
+			ctx.setResult(await (await this.createSettings()).listHooks(ctx.payload));
+		});
+		this.registerHandler(CodexClientSubjects.config.hooks.add, async (ctx) => {
+			ctx.setResult(await (await this.createSettings()).addHook(ctx.payload));
+		});
+		this.registerHandler(CodexClientSubjects.config.hooks.remove, async (ctx) => {
+			ctx.setResult(await (await this.createSettings()).removeHook(ctx.payload));
+		});
+		this.registerHandler(CodexClientSubjects.wiring.list, async (ctx) => {
+			assertAbsoluteProjectDir(ctx.payload.projectDir);
+			ctx.setResult(await buildCodexWiringList(await this.createSettings(), ctx.payload.makaioCommand, ctx.payload.projectDir));
+		});
+		this.registerHandler(CodexClientSubjects.wiring.apply, async (ctx) => {
+			assertAbsoluteProjectDir(ctx.payload.projectDir);
+			if (ctx.payload.scope === "project" && !ctx.payload.projectDir) throw new Error("projectDir is required when scope is 'project'");
+			ctx.setResult(await applyCodexWiring(await this.createSettings(), ctx.payload.scope, ctx.payload.makaioCommand, ctx.payload.projectDir));
+		});
+		this.registerHandler(CodexClientSubjects.wiring.remove, async (ctx) => {
+			assertAbsoluteProjectDir(ctx.payload.projectDir);
+			if (ctx.payload.scope === "project" && !ctx.payload.projectDir) throw new Error("projectDir is required when scope is 'project'");
+			ctx.setResult(await removeCodexWiring(await this.createSettings(), ctx.payload.scope, ctx.payload.projectDir));
+		});
+		this.registerHandler(CodexClientSubjects.config.prime, async (ctx) => {
+			ctx.setResult(await handleCodexConfigPrime(ctx.payload));
+		});
+		this.registerHandler(CodexClientSubjects.sessionConfig.setup, async (ctx) => {
+			ctx.setResult(await handleCodexSessionConfigSetup(ctx.payload));
+		});
+	}
+	/**
+	* Clear the adapter-managed session ID set on teardown.
+	*/
+	onDestroy() {
+		this.managedAdapterSessionIds.clear();
+		this.cachedConfigDir = void 0;
+	}
+	/**
+	* Create a settings delegate for the active Codex config root.
+	* @returns Settings instance bound to the managed config dir when available.
+	*/
+	async createSettings() {
+		if (this.settingsOverride !== void 0) return this.settingsOverride;
+		const configDir = await this.resolveConfigDir();
+		return new CodexClientSettings(configDir !== void 0 ? { configDir } : void 0);
+	}
+	/**
+	* Return the cached config directory promise, resolving it on first access.
+	*
+	* Missing binary resolution is a graceful fallback so config reads/writes can
+	* still target native Codex config paths in framework-only or global-only
+	* setups.
+	* @returns Absolute managed config dir, or `undefined` to use native paths.
+	*/
+	resolveConfigDir() {
+		if (this.cachedConfigDir === void 0) {
+			const pendingConfigDir = this.doResolveConfigDir().then((configDir) => {
+				if (configDir === void 0 && this.cachedConfigDir === pendingConfigDir) this.cachedConfigDir = void 0;
+				return configDir;
+			}, (error) => {
+				if (this.cachedConfigDir === pendingConfigDir) this.cachedConfigDir = void 0;
+				throw error;
+			});
+			this.cachedConfigDir = pendingConfigDir;
+		}
+		return this.cachedConfigDir;
+	}
+	/**
+	* Resolve the active Codex config dir via `client.resolveBinary`.
+	* @returns Config directory returned by the binary resolver, or `undefined`
+	*   when no resolver/global binary is available.
+	*/
+	async doResolveConfigDir() {
+		let result;
+		try {
+			result = await this.bus.requestOptional(ClientSubjects.resolveBinary, { clientId: CLIENT_ID });
+		} catch (error) {
+			if (isResolveBinaryMissingGlobalBinary(error)) return;
+			throw error;
+		}
+		if (!result.handled) return;
+		return result.data.configDir ?? void 0;
+	}
+	/**
+	* Record a runtime as adapter-managed when the evidence source is an adapter.
+	*
+	* Called for every `client.runtime.started` event.  Only events whose
+	* `clientId` equals `'codex'`, whose `source.layer` is `'adapter'`, and
+	* that carry a non-empty `adapterSessionId` update the managed-sessions gate.
+	* Events from other clients (e.g. `'claude-code'`, `'gemini'`) are ignored
+	* unconditionally — their adapter sessions must not suppress Codex hook
+	* emissions.  Non-adapter sources (e.g. `'supervisor'`, `'statusline'`) are
+	* also ignored to prevent accidental suppression of native hook paths.
+	*
+	* When the set reaches {@link MANAGED_SESSION_CAP}, the oldest entry is
+	* evicted before the new ID is inserted.
+	* @param payload - `client.runtime.started` payload
+	*/
+	handleRuntimeStarted(payload) {
+		if (payload.clientId !== CLIENT_ID) return;
+		if (payload.source.layer === "adapter" && payload.adapterSessionId) {
+			if (this.managedAdapterSessionIds.has(payload.adapterSessionId)) return;
+			if (this.managedAdapterSessionIds.size >= 1e4) {
+				const oldest = this.managedAdapterSessionIds.values().next().value;
+				if (oldest !== void 0) this.managedAdapterSessionIds.delete(oldest);
+			}
+			this.managedAdapterSessionIds.add(payload.adapterSessionId);
+		}
+	}
+	/**
+	* Translate a raw Codex hook event into a normalized `client.session.*` emission.
+	*
+	* Unknown / Codex-specific events produce no emission and are silently
+	* ignored. The raw event remains observable on `client:codex.*` for
+	* consumers that need Codex-native detail.
+	* @param raw - Raw hook payload delivered on `client:codex.hook.received`
+	*/
+	async handleHookReceived(raw) {
+		const normalized = normalizeCodexHook(raw);
+		if (normalized === null) return;
+		if (this.isAdapterManagedSession(normalized.payload.adapterSessionId)) return;
+		switch (normalized.subject) {
+			case ClientSubjects.session.started:
+				await this.bus.emit(ClientSubjects.session.started, normalized.payload);
+				break;
+			case ClientSubjects.session.userPrompt.submitted:
+				await this.bus.emit(ClientSubjects.session.userPrompt.submitted, normalized.payload);
+				break;
+			case ClientSubjects.session.turn.completed:
+				await this.bus.emit(ClientSubjects.session.turn.completed, normalized.payload);
+				break;
+			case ClientSubjects.session.tool.pre:
+				await this.bus.emit(ClientSubjects.session.tool.pre, normalized.payload);
+				break;
+			case ClientSubjects.session.tool.post:
+				await this.bus.emit(ClientSubjects.session.tool.post, normalized.payload);
+				break;
+			default: throwUnhandledNormalizedEvent(normalized);
+		}
+	}
+	/**
+	* Determine whether a normalized native hook belongs to an adapter-managed
+	* session whose global observed-semantics events are already emitted by the
+	* adapter layer.
+	* @param adapterSessionId - Adapter/session identifier from the normalized hook
+	* @returns True when the native hook should remain raw-only
+	*/
+	isAdapterManagedSession(adapterSessionId) {
+		return adapterSessionId !== void 0 && this.managedAdapterSessionIds.has(adapterSessionId);
+	}
+};
+/**
+* Fail fast when the normalizer grows a new subject but service emission has
+* not been updated to preserve the normalized-event contract.
+*
+* The broad parameter type is intentional — the switch operates on
+* `SubjectDefinition` subject strings rather than a discriminated union, so
+* TypeScript cannot narrow `normalized` to `never` in the default branch.
+* Compile-time exhaustiveness is enforced by the normalizer's return type
+* and the matching set of case branches above.
+* @param event - Normalized event whose subject is not emitted above
+*/
+function throwUnhandledNormalizedEvent(event) {
+	const subject = event.subject.subject;
+	throw new Error(`Unhandled normalized Codex hook subject: ${subject}`);
+}
+/**
+* Return true when `client.resolveBinary` only failed because no Codex
+* executable was found. Config and wiring requests can still use Codex's
+* default native settings path in that case; other resolution failures should
+* propagate.
+* @param error - Error thrown by the bus request.
+* @returns True when the error is the global-binary fallback miss.
+*/
+function isResolveBinaryMissingGlobalBinary(error) {
+	if (!(error instanceof RequestError)) return false;
+	return error.subject?.endsWith("resolveBinary") === true && error.cause instanceof BinaryNotFoundError;
+}
+
+//#endregion
+export { CodexNativeHooksFileSchema as _, CodexWiringSchemas as a, clientDefinition as b, CodexConfigHooksAddResponseSchema as c, CodexConfigHooksRemoveRequestSchema as d, CodexConfigHooksRemoveResponseSchema as f, CodexNativeHookMatcherGroupSchema as g, CodexNativeCommandHookSchema as h, normalizeCodexHook as i, CodexConfigHooksListRequestSchema as l, CodexHookEntrySchema as m, CODEX_CLIENT_NAMESPACE as n, AbsolutePathSchema as o, CodexConfigSchemas as p, CodexClientSubjects as r, CodexConfigHooksAddRequestSchema as s, CodexClientSessionService as t, CodexConfigHooksListResponseSchema as u, CodexScopeHookRecordSchema as v, CodexScopeSchema as y };