@makaio/client-codex 1.0.0-dev-1786014320559 → 1.0.0-dev-1789609124644

package/dist/{codex-client-session-service-epcEX-w5.mjs → codex-client-session-service-CsIoRrhH.mjs}

@@ -4,14 +4,14 @@ import { AbsolutePathSchema, BinaryNotFoundError, ClientSubjects, ClientWiringAp
 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 fs, { open } from "node:fs/promises";
 import * as path$1 from "node:path";
 import path from "node:path";
 import * as os$1 from "node:os";
 import os from "node:os";
 import { createHash, randomUUID } from "node:crypto";
+import { CLIENT_SESSION_COMPACTION_TRIGGERS, ClientConfigPrimeSchema, SessionConfigSetupRequestSchema, SessionConfigSetupResponseSchema, SessionConfigTeardownRequestSchema, SessionConfigTeardownResponseSchema } from "@makaio/framework/contracts/client";
 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";
 
@@ -135,7 +135,22 @@ const clientDefinition = createClientDefinition({
 				name: "Stop",
 				frameworkSubject: "client.session.turn.completed",
 				responseCapabilities: [CODEX_HOOK_RESPONSE_CAPABILITIES.block]
-			}
+			},
+			{
+				name: "SubagentStart",
+				frameworkSubject: "client.session.subagent.started",
+				responseCapabilities: ["context.append"]
+			},
+			{
+				name: "SubagentStop",
+				frameworkSubject: "client.session.subagent.completed"
+			},
+			{
+				name: "PreCompact",
+				frameworkSubject: "client.session.compaction.pre"
+			},
+			{ name: "PostCompact" },
+			{ name: "PermissionRequest" }
 		]
 	}
 });
@@ -942,6 +957,191 @@ async function handleCodexConfigPrime(payload) {
 	return { primed: true };
 }
 
+//#endregion
+//#region src/runtime/fork-sniff.ts
+/**
+* Fork lineage sniff for Codex rollout files.
+*
+* Codex records every thread as a JSONL *rollout* file. The first line is the
+* thread's own `session_meta` record; when the thread was created by forking
+* another thread, that record carries `forked_from_id` — the parent thread id.
+* Codex then copies the parent's persisted rollout items verbatim into the
+* child file, so the parent's own `session_meta` line appears *later* in the
+* same file.
+*
+* ## Why a sniff is needed
+*
+* The `SessionStart` hook payload has no lineage field at all: it carries
+* `session_id`, `transcript_path`, `cwd`, `hook_event_name`, `model`,
+* `permission_mode` and `source` — nothing else. A fork also reports
+* `source: 'startup'`, exactly like a brand-new thread, so the hook alone
+* cannot distinguish the two. `transcript_path` points at the rollout file
+* the CLI has just materialized for the starting thread, which makes the
+* rollout head the only lineage source available at session-start time.
+*
+* ## Detection invariant
+*
+* The **first** `session_meta` record in the file is the file's own. Any later
+* `session_meta` record was copied from an ancestor and must be ignored, so the
+* scan stops at the first one it can parse:
+*
+* - `forked_from_id` present and different from the starting thread's own id
+*   → fork child; that id is the direct parent.
+* - `forked_from_id` absent (or equal to the own id, which would be a
+*   self-reference and is never a usable parent) → no fork signal.
+* - No parseable `session_meta` inside the window → inconclusive; return
+*   `undefined`. Fork registration is fill-once on the ingestion side, so a
+*   guessed parent would be permanently wrong while deferring is safe.
+*
+* Anchoring the window at the start of the file is what makes the rule sound
+* under a byte cap: the decisive record is the first one, so no earlier record
+* can exist outside the window.
+*
+* ## Design principles
+*
+* - **Pure detection core**: {@link sniffRolloutForkLineage} operates on raw
+*   JSONL lines. No I/O, no bus, no dependencies beyond the language runtime.
+* - **Bounded I/O wrapper**: {@link sniffRolloutFork} reads at most
+*   {@link SNIFF_MAX_BYTES} from the rollout head, so the hook path never
+*   blocks on a large rollout file.
+* - **Fail-open**: any I/O or parse error yields `undefined` (no fork signal);
+*   hook processing is never blocked by a sniff failure.
+* @packageDocumentation
+*/
+/**
+* Maximum number of bytes to read from the rollout head for fork detection.
+*
+* The decisive record is the first line, but that line embeds the thread's
+* `base_instructions`, which can run to several kilobytes. 128 KiB leaves ample
+* headroom for it while keeping the blocking window small. A `session_meta`
+* line longer than the window yields a truncated, unparseable JSON fragment and
+* therefore no signal — the fail-open outcome, not a wrong parent.
+*/
+const SNIFF_MAX_BYTES = 128 * 1024;
+/** Rollout item discriminator for the thread metadata record. */
+const SESSION_META_TYPE = "session_meta";
+/**
+* Read `forked_from_id` from a parsed rollout line when it is the file's own
+* `session_meta` record.
+*
+* Codex serializes its rollout items with an externally tagged representation,
+* so the record on disk has a `type` discriminator and a `payload` body; the
+* metadata record flattens the thread metadata into that `payload`.
+* @param parsed - Parsed JSONL record from the rollout head
+* @returns The parent thread id, `undefined` when the record names no parent,
+*   or `null` when the record is not a `session_meta` record at all
+*/
+function readForkParent(parsed) {
+	if (parsed["type"] !== SESSION_META_TYPE) return null;
+	const payload = parsed["payload"];
+	if (typeof payload !== "object" || payload === null) return void 0;
+	const forkedFromId = payload["forked_from_id"];
+	return typeof forkedFromId === "string" && forkedFromId.length > 0 ? forkedFromId : void 0;
+}
+/**
+* Detect fork lineage from raw rollout JSONL lines.
+*
+* Scans the provided window **forward** from the first line. The window must be
+* anchored at the start of the rollout file (see {@link sniffRolloutFork});
+* under that anchoring, the first `session_meta` record found is the file's own
+* and decides the outcome. Later `session_meta` records belong to ancestors
+* copied into the fork and are never consulted.
+* @param lines - Raw JSONL lines from the rollout head (may include empty
+*   strings, partial lines, or non-JSON data)
+* @param hookSessionId - Session id reported by the hook payload (the starting
+*   thread's own id)
+* @returns Fork sniff result when the own `session_meta` names a foreign
+*   parent, or `undefined` for a plain start / no signal / inconclusive window
+*/
+function sniffRolloutForkLineage(lines, hookSessionId) {
+	for (const raw of lines) {
+		const line = raw.trim();
+		if (line.length === 0) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (typeof parsed !== "object" || parsed === null) continue;
+		const forkParent = readForkParent(parsed);
+		if (forkParent === null) continue;
+		if (forkParent === void 0 || forkParent === hookSessionId) return void 0;
+		return { parentAdapterSessionId: forkParent };
+	}
+}
+/**
+* Read at most {@link SNIFF_MAX_BYTES} from the head of the rollout file.
+*
+* The final element is dropped when the file is larger than the window: it is a
+* partial line whose parse would fail anyway, and dropping it keeps the caller
+* from treating truncated JSON as data.
+* @param rolloutPath - Absolute path to the rollout JSONL file
+* @returns Raw lines from the file head, or `undefined` on any I/O error
+*/
+async function readRolloutHead(rolloutPath) {
+	let fh;
+	try {
+		fh = await open(rolloutPath, "r");
+		const { size } = await fh.stat();
+		const readLength = Math.min(size, SNIFF_MAX_BYTES);
+		const buf = Buffer.alloc(readLength);
+		const { bytesRead } = await fh.read(buf, 0, readLength, 0);
+		const lines = buf.toString("utf8", 0, bytesRead).split("\n");
+		if (size > 131072) lines.pop();
+		return lines;
+	} catch {
+		return;
+	} finally {
+		await fh?.close();
+	}
+}
+/**
+* Sniff the rollout file at session-start time to detect fork lineage.
+*
+* Combines the bounded head read with the pure forward-scanning detection core.
+* Because the window is anchored at the start of the file, a byte cap can never
+* produce a wrong parent: the decisive record — the file's own `session_meta` —
+* is either inside the window or the sniff returns `undefined`. Returns
+* `undefined` (no fork signal) on any error; hook processing must never be
+* blocked by a sniff failure.
+* @param rolloutPath - Absolute path to the rollout JSONL file, as reported by
+*   the hook payload's `transcript_path`
+* @param hookSessionId - Session id reported by the hook payload
+* @returns Fork sniff result, or `undefined` when no fork is detected or the
+*   sniff cannot be performed
+*/
+async function sniffRolloutFork(rolloutPath, hookSessionId) {
+	try {
+		const lines = await readRolloutHead(rolloutPath);
+		if (lines === void 0) return void 0;
+		return sniffRolloutForkLineage(lines, hookSessionId);
+	} catch {
+		return;
+	}
+}
+
+//#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.
+*
+* Event names are verified against pinned source `rust-v0.144.1`
+* (`codex-rs/hooks/src/lib.rs`).
+*/
+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";
+const CODEX_HOOK_SUBAGENT_START = "SubagentStart";
+const CODEX_HOOK_SUBAGENT_STOP = "SubagentStop";
+const CODEX_HOOK_PRE_COMPACT = "PreCompact";
+
 //#endregion
 //#region src/runtime/hook-normalizer.ts
 /**
@@ -951,37 +1151,88 @@ async function handleCodexConfigPrime(payload) {
 * `client:codex.hook.received` to their corresponding
 * `client.session.*` observed-semantics subjects.
 *
-* **Mapping table** (Codex event → global subject):
+* **Mapping table** (Codex event → global subject(s)):
 *
-* | 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`              |
+* | Codex event name | Global subject(s)                                       |
+* |------------------|----------------------------------------------------------|
+* | `SessionStart`   | `client.session.started`                               |
+* | `UserPromptSubmit` | `client.session.turn.started`, then `client.session.userPrompt.submitted` |
+* | `Stop`           | `client.session.turn.completed`                        |
+* | `PreToolUse`     | `client.session.tool.pre`                              |
+* | `PostToolUse`    | `client.session.tool.post`                             |
+* | `SubagentStart`  | `client.session.subagent.started`                      |
+* | `SubagentStop`   | `client.session.subagent.completed`                    |
+* | `PreCompact`     | `client.session.compaction.pre`                        |
+* | `PostCompact`    | _(raw-only — no global subject)_                       |
 *
-* All other event names are returned as `null` — they are kept raw only and
+* All other event names return an empty array — 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.
+* **Source notes:** Event names are verified against the pinned
+* `rust-v0.144.1` Codex source (`codex-rs/hooks/src/lib.rs`). Update this
+* normalizer when a new binary version changes or adds hook names.
+*
+* **Subagent hooks:** On both `SubagentStart` and `SubagentStop`, the raw
+* `session_id` is the PARENT session id. `adapterSessionId` on the base carries
+* it directly (no stripping). `agentId` identifies the subagent. `turnId` is
+* populated from `turn_id` when the Codex CLI includes it.
 * @packageDocumentation
 */
+/** Client ID used in all normalized payloads emitted by this normalizer. */
+const CLIENT_ID$1 = "codex";
+/** Source tag carried on all normalized observations. */
+const SOURCE = "native-hook";
 /**
-* Static map from Codex-native hook event name to the matching global subject.
+* Known compaction trigger values reported by Codex.
 *
-* Update this map when the Codex CLI exposes new hook names that correspond
-* to global session lifecycle events.
+* Derived from the contracts constant so it stays in sync without a separate
+* local enumeration that could drift.
 */
-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]
-]);
+const COMPACTION_TRIGGERS = new Set(CLIENT_SESSION_COMPACTION_TRIGGERS);
+/**
+* Map from the Codex CLI `SessionStart.source` union to the
+* framework-level {@link ClientSessionStartMode}.
+*
+* - `'startup'` → `'fresh'` (brand-new thread — **and a fork child**, see
+*   below; the owning service upgrades the fork case to `'fork'`)
+* - `'resume'`  → `'resume'` (thread continued from its own rollout file)
+* - `'clear'`   → `'clear'` (conversation cleared, new thread id)
+* - `'compact'` → `'compact'` (context compacted, same thread id)
+*
+* The vendor union has exactly these four values in the pinned `rust-v0.144.1`
+* source (`codex-rs/hooks/src/events/session_start.rs`, `SessionStartSource`);
+* there is no `'fork'` value. In `codex-rs/core/src/session/session.rs` a fork
+* is classified next to a brand-new thread — the match arm that maps
+* `InitialHistory::New` to `SessionStartSource::Startup` also covers
+* `InitialHistory::Forked` — which is why `'startup'`, not `'resume'`, is the
+* mode that may still turn out to be a fork.
+* Lineage is recovered from the rollout file instead; see the fork sniff in
+* `fork-sniff.ts` and its caller in `codex-client-session-service.ts`.
+*
+* Vendor values not in this map yield `undefined`, leaving `startMode`
+* absent from the normalized payload — safe for forward compatibility when
+* Codex adds new source values.
+*/
+const VENDOR_SOURCE_TO_START_MODE = {
+	startup: "fresh",
+	resume: "resume",
+	clear: "clear",
+	compact: "compact"
+};
+/**
+* Extract the `source` field from a `SessionStart` hook payload and map it
+* to a {@link ClientSessionStartMode}.
+*
+* Returns `undefined` when the field is absent, non-string, or not a
+* recognized value — keeping the normalizer tolerant of future CLI additions.
+* @param payload - Raw `SessionStart` hook payload
+* @returns Mapped start mode, or `undefined` when the source is unknown
+*/
+function resolveStartMode(payload) {
+	const source = payload["source"];
+	if (typeof source !== "string") return void 0;
+	return VENDOR_SOURCE_TO_START_MODE[source];
+}
 /**
 * Extract optional session identifier from a raw Codex hook payload.
 *
@@ -1021,87 +1272,241 @@ function extractPrompt(payload) {
 	return pickNonEmptyString(payload, "prompt");
 }
 /**
-* Normalize a raw Codex hook payload into a `client.session.*` event.
+* Extract the subagent identity from a subagent hook payload.
+*
+* Codex reports the agent identity under `agent_id` on both `SubagentStart`
+* and `SubagentStop` hook payloads.
+* @param payload - Raw subagent hook payload
+* @returns Agent ID string, or `undefined` when absent or empty
+*/
+function extractAgentId(payload) {
+	return pickNonEmptyString(payload, "agent_id");
+}
+/**
+* Extract the subagent type label from a subagent hook payload.
 *
-* 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.*`.
+* Codex reports the agent type under `agent_type` on subagent hooks.
+* @param payload - Raw subagent hook payload
+* @returns Agent type string, or `undefined` when absent or empty
+*/
+function extractAgentType(payload) {
+	return pickNonEmptyString(payload, "agent_type");
+}
+/**
+* Extract the subagent transcript path from a `SubagentStop` payload.
+*
+* Codex may report the agent's own transcript path under
+* `agent_transcript_path` at subagent stop time.
+* @param payload - Raw `SubagentStop` hook payload
+* @returns Absolute transcript path, or `undefined` when absent or empty
+*/
+function extractAgentTranscriptPath(payload) {
+	return pickNonEmptyString(payload, "agent_transcript_path");
+}
+/**
+* Extract the turn correlation id from a subagent hook payload.
+*
+* Codex subagent hooks carry `turn_id` to correlate the hook event with the
+* parent turn that spawned the subagent.
+* @param payload - Raw subagent hook payload
+* @returns Turn id string, or `undefined` when absent or empty
+*/
+function extractTurnId(payload) {
+	return pickNonEmptyString(payload, "turn_id");
+}
+/**
+* Extract and map the compaction trigger from a `PreCompact` payload.
+*
+* Codex reports the trigger under `trigger` with values `'manual'` or
+* `'auto'`. Unknown values are dropped for forward compatibility.
+* @param payload - Raw `PreCompact` hook payload
+* @returns Mapped compaction trigger, or `undefined` when absent or unknown
+*/
+function extractCompactionTrigger(payload) {
+	const trigger = payload["trigger"];
+	if (typeof trigger !== "string") return void 0;
+	return COMPACTION_TRIGGERS.has(trigger) ? trigger : void 0;
+}
+/**
+* Extract the transcript path from a raw Codex hook payload.
+*
+* Codex includes `transcript_path` on `SessionStart` and on the compaction
+* hooks; it is the absolute path of the thread's rollout JSONL file and is
+* serialized as `null` when no rollout has been materialized.
+* @param payload - Raw hook payload object
+* @returns Transcript path string, or `undefined` when absent or empty
+*/
+function extractTranscriptPath(payload) {
+	return pickNonEmptyString(payload, "transcript_path");
+}
+/**
+* Normalize a `SubagentStart` hook payload into the subagent-started event.
+*
+* SubagentStart/Stop: the raw `session_id` is the PARENT session id.
+* `adapterSessionId` on the base carries it directly — it is the parent
+* session id, not a subagent own session id. `agentId` identifies the
+* subagent. `turnId` is populated from `turn_id` when present.
+* @param base - Full hook base (includes `adapterSessionId` = parent session id)
+* @param payload - Raw `SubagentStart` hook payload body
+* @returns Normalized event array, empty when `agentId` is absent
+*/
+function normalizeSubagentStart(base, payload) {
+	const agentId = extractAgentId(payload);
+	if (agentId === void 0) return [];
+	const agentType = extractAgentType(payload);
+	const turnId = extractTurnId(payload);
+	return [{
+		subject: ClientSubjects.session.subagent.started,
+		payload: {
+			...base,
+			agentId,
+			...agentType !== void 0 && { agentType },
+			...turnId !== void 0 && { turnId }
+		}
+	}];
+}
+/**
+* Normalize a `SubagentStop` hook payload into the subagent-completed event.
+*
+* See {@link normalizeSubagentStart} for the `adapterSessionId` = parent
+* session id convention and `turnId` extraction.
+* @param base - Full hook base (includes `adapterSessionId` = parent session id)
+* @param payload - Raw `SubagentStop` hook payload body
+* @returns Normalized event array, empty when `agentId` is absent
+*/
+function normalizeSubagentStop(base, payload) {
+	const agentId = extractAgentId(payload);
+	if (agentId === void 0) return [];
+	const agentType = extractAgentType(payload);
+	const turnId = extractTurnId(payload);
+	const agentTranscriptPath = extractAgentTranscriptPath(payload);
+	return [{
+		subject: ClientSubjects.session.subagent.completed,
+		payload: {
+			...base,
+			agentId,
+			...agentType !== void 0 && { agentType },
+			...turnId !== void 0 && { turnId },
+			...agentTranscriptPath !== void 0 && { agentTranscriptPath }
+		}
+	}];
+}
+/**
+* Normalize a `PreCompact` hook payload into the compaction-pre event.
+* @param base - Full hook base (includes `adapterSessionId`)
+* @param payload - Raw `PreCompact` hook payload body
+* @returns Single-element normalized event array
+*/
+function normalizePreCompact(base, payload) {
+	const trigger = extractCompactionTrigger(payload);
+	const transcriptPath = extractTranscriptPath(payload);
+	return [{
+		subject: ClientSubjects.session.compaction.pre,
+		payload: {
+			...base,
+			...trigger !== void 0 && { trigger },
+			...transcriptPath !== void 0 && { transcriptPath }
+		}
+	}];
+}
+/**
+* Normalize a raw Codex hook payload into `client.session.*` events.
+*
+* Returns an empty array for unknown or not-yet-modeled event names so the
+* caller skips global emission and keeps the event raw-only in
+* `client:codex.*`. A single hook may map to more than one normalized event:
+* `UserPromptSubmit` yields `turn.started` followed by `userPrompt.submitted`.
+* Emission order within the array is significant and must be preserved by the
+* caller.
+*
+* The `receivedAt` timestamp from the raw hook payload is used as `observedAt`
+* to preserve the original wall-clock time of the observation.
 * @param raw - Raw hook payload delivered on `client:codex.hook.received`
 * @param machineId - Stable runtime identity of the observing machine,
 *   caller-supplied by the owning client runtime. Stamped onto
 *   `client.session.started` so downstream storage receives the owning
 *   machine's identity without deriving it from the writer process.
-* @returns Normalized event with subject and typed payload, or `null` when
-*   the event name is unknown
+* @returns Normalized events with subject and typed payload, in emission
+*   order; empty when the event name is unknown (raw-only)
 */
 function normalizeCodexHook(raw, machineId) {
-	const subject = CODEX_EVENT_MAP.get(raw.eventName);
-	if (subject === void 0) return null;
 	const base = {
-		clientId: "codex",
-		source: "native-hook",
+		clientId: CLIENT_ID$1,
+		source: SOURCE,
 		observedAt: raw.receivedAt,
 		adapterSessionId: extractAdapterSessionId(raw.payload),
 		metadata: raw.metadata
 	};
-	switch (subject) {
-		case ClientSubjects.session.started: return {
-			subject,
-			payload: {
-				...base,
-				...machineId !== void 0 && { machineId }
-			}
-		};
-		case ClientSubjects.session.userPrompt.submitted: return {
-			subject,
+	switch (raw.eventName) {
+		case CODEX_HOOK_SESSION_START: {
+			const startMode = resolveStartMode(raw.payload);
+			const transcriptPath = extractTranscriptPath(raw.payload);
+			return [{
+				subject: ClientSubjects.session.started,
+				payload: {
+					...base,
+					...machineId !== void 0 && { machineId },
+					...startMode !== void 0 && { startMode },
+					...transcriptPath !== void 0 && { transcriptPath }
+				}
+			}];
+		}
+		case CODEX_HOOK_USER_PROMPT_SUBMIT: return [{
+			subject: ClientSubjects.session.turn.started,
+			payload: { ...base }
+		}, {
+			subject: ClientSubjects.session.userPrompt.submitted,
 			payload: {
 				...base,
 				prompt: extractPrompt(raw.payload)
 			}
-		};
-		case ClientSubjects.session.turn.completed: return {
-			subject,
-			payload: { ...base }
-		};
-		case ClientSubjects.session.tool.pre: return {
-			subject,
+		}];
+		case CODEX_HOOK_PRE_TOOL_USE: return [{
+			subject: ClientSubjects.session.tool.pre,
 			payload: {
 				...base,
 				toolName: extractToolName(raw.payload),
 				toolCallId: extractToolCallId(raw.payload)
 			}
-		};
-		case ClientSubjects.session.tool.post: return {
-			subject,
+		}];
+		case CODEX_HOOK_POST_TOOL_USE: return [{
+			subject: ClientSubjects.session.tool.post,
 			payload: {
 				...base,
 				toolName: extractToolName(raw.payload),
 				toolCallId: extractToolCallId(raw.payload)
 			}
-		};
-		default: return null;
+		}];
+		case CODEX_HOOK_STOP: return [{
+			subject: ClientSubjects.session.turn.completed,
+			payload: { ...base }
+		}];
+		case CODEX_HOOK_SUBAGENT_START: return normalizeSubagentStart(base, raw.payload);
+		case CODEX_HOOK_SUBAGENT_STOP: return normalizeSubagentStop(base, raw.payload);
+		case CODEX_HOOK_PRE_COMPACT: return normalizePreCompact(base, raw.payload);
+		default: return [];
 	}
 }
 
-//#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";
+/**
+* Semantic version of the Codex hook-response contract.
+*
+* Pinned to the proven capabilities of Codex CLI 0.144.1. Bump this version
+* when a future CLI release expands the native response surface.
+*
+* `1.2.0` adds `SubagentStart` as a request-capable, non-blockable interaction
+* carrying canonical `context.append`. The appended context lands in the
+* *subagent's* context window, not the parent's — proven live, see
+* `runtime/__tests__/fixtures/hook-contracts/probe/subagent-start-context-append.json`.
+* Subagent creation cannot be refused (`continue: false` is parsed for
+* compatibility but does not stop the subagent), so the interaction is
+* non-blockable. Purely additive: every `1.1.0` contributor remains valid.
+*/
+const CODEX_CONTRACT_VERSION = "1.2.0";
 /**
 * Build a frozen Codex provider envelope.
 * @param effects - Provider-native effect record.
@@ -1235,6 +1640,7 @@ const CODEX_SUPPORTED_INTERACTIONS = Object.freeze([
 	CODEX_HOOK_PRE_TOOL_USE,
 	CODEX_HOOK_POST_TOOL_USE,
 	CODEX_HOOK_STOP,
+	CODEX_HOOK_SUBAGENT_START,
 	...CODEX_RESPONSE_CAPABILITIES
 ]);
 const CODEX_INTERACTION_BLOCKABILITY = Object.freeze(CODEX_SUPPORTED_INTERACTIONS.map((interaction) => Object.freeze({
@@ -1267,7 +1673,8 @@ const EVENT_EFFECTS = Object.freeze({
 		"update"
 	]),
 	[CODEX_HOOK_POST_TOOL_USE]: new Set(["context", "block"]),
-	[CODEX_HOOK_STOP]: new Set(["block"])
+	[CODEX_HOOK_STOP]: new Set(["block"]),
+	[CODEX_HOOK_SUBAGENT_START]: new Set(["context"])
 });
 /**
 * Classify an exact provider-native Codex effects record.
@@ -2578,10 +2985,21 @@ 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.
+* Timeout for request-mode hooks on context-only (non-blockable) interactions.
+*
+* `hook handle` has no `--debounce-failure`, so a down server would stall every
+* prompt and subagent spawn for the full timeout; context-only hooks fail fast.
+* Blockable interactions retain {@link DEFAULT_HOOK_HANDLE_TIMEOUT_MS} because
+* those must complete before the native client can proceed.
+*/
+const CONTEXT_ONLY_HOOK_HANDLE_TIMEOUT_MS = 1e3;
+/**
+* Descriptors for all hook events 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.
+* Includes every event declared in the definition's `hookEvents` array,
+* regardless of whether it carries a `frameworkSubject`.  Events without a
+* framework mapping (e.g. `PostCompact`) are still wired so that the raw
+* ingress reaches the bus for Codex-specific consumers.
 */
 const SESSION_EVENTS = deriveSessionEventDescriptors(clientDefinition);
 /**
@@ -2684,19 +3102,27 @@ async function removeCodexWiring(settings, scope, projectDir) {
 }
 /**
 * Build the managed command for one capability-derived hook mode.
+*
+* For request-mode hooks the timeout is derived from the event's blockability:
+* blockable interactions get {@link DEFAULT_HOOK_HANDLE_TIMEOUT_MS} (5 s);
+* non-blockable, context-only interactions get
+* {@link CONTEXT_ONLY_HOOK_HANDLE_TIMEOUT_MS} (1 s) so a down server does not
+* stall every prompt or subagent spawn for the full duration.
 * @param makaioCommand - Makaio CLI executable.
-* @param eventName - Native Codex event name.
+* @param eventName - Native Codex event name (used to look up blockability).
 * @param mode - Capability-derived transport mode.
 * @returns Shell-safe managed hook command.
 */
 function buildModeCommand(makaioCommand, eventName, mode) {
-	return mode === "request" ? buildClientCommand(makaioCommand, [
+	if (mode !== "request") return buildHookCommand(makaioCommand, CODEX_HOOK_COMMAND_SENTINEL, eventName, void 0, ["--debounce-failure"]);
+	const timeoutMs = CODEX_INTERACTION_BLOCKABILITY.some((entry) => entry.interaction === eventName && entry.blockable) ? DEFAULT_HOOK_HANDLE_TIMEOUT_MS : CONTEXT_ONLY_HOOK_HANDLE_TIMEOUT_MS;
+	return 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"]);
+		String(timeoutMs)
+	]);
 }
 
 //#endregion
@@ -2714,6 +3140,37 @@ const CLIENT_ID = "codex";
 */
 const MANAGED_SESSION_CAP = 1e4;
 /**
+* Set of `client.session.*` subjects that the `codex-app-server` adapter
+* emits for adapter-managed sessions.
+*
+* Derived from
+* `adapters/implementations/codex-app-server/src/agent.ts`
+* (lines 178, 186, 195, 217, 338, 383, 411, 438, 473, 495).
+*
+* When both the native-hook ingress and the adapter path are active for the
+* same session, only these subjects are suppressed by
+* {@link CodexClientSessionService.handleHookReceived} — the adapter already
+* owns their canonical emission.  Hook-only subjects that have no adapter
+* equivalent (`subagent.started`, `subagent.completed`, `compaction.pre`)
+* are NOT in this set and must always be forwarded even for managed sessions.
+*
+* `client.session.started` is in this set (the adapter emits it once at thread
+* start), but the gate exempts it when `startMode` is `'compact'` or `'clear'`.
+* The reason: the adapter emits `session.started` only once — at thread start,
+* without a `startMode` — and never again for compaction or clear restarts.
+* Those transitions happen inside the running thread, so the hook-derived
+* `session.started{startMode:'compact'|'clear'}` is the sole signal for them
+* and must always be forwarded even for adapter-managed sessions.
+*/
+const ADAPTER_EMITTED_SUBJECTS = new Set([
+	ClientSubjects.session.started,
+	ClientSubjects.session.turn.started,
+	ClientSubjects.session.turn.completed,
+	ClientSubjects.session.userPrompt.submitted,
+	ClientSubjects.session.tool.pre,
+	ClientSubjects.session.tool.post
+]);
+/**
 * 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.*`.
@@ -2963,35 +3420,68 @@ var CodexClientSessionService = class extends BaseService {
 		}
 	}
 	/**
-	* Translate a raw Codex hook event into a normalized `client.session.*` emission.
+	* Translate a raw Codex hook event into normalized `client.session.*` emissions.
 	*
 	* 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.
+	*
+	* One raw hook may produce multiple normalized events (e.g. `UserPromptSubmit`
+	* yields `turn.started` then `userPrompt.submitted`). Events are emitted in
+	* the order returned by the normalizer.
 	* @param raw - Raw hook payload delivered on `client:codex.hook.received`
 	*/
 	async handleHookReceived(raw) {
-		const normalized = normalizeCodexHook(raw, this.machineId);
-		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);
+		const events = normalizeCodexHook(raw, this.machineId);
+		if (events.length === 0 && (raw.eventName === "SubagentStart" || raw.eventName === "SubagentStop")) console.warn(`[CodexClientSessionService] ${raw.eventName} hook produced no normalized events — agent_id is likely absent. The hook remains raw-only on client:codex.*.`);
+		const sharedAdapterSessionId = events[0]?.payload.adapterSessionId;
+		const isManagedSession = this.isAdapterManagedSession(sharedAdapterSessionId);
+		let firstError;
+		for (const normalized of events) {
+			if (this.shouldSuppressForManagedSession(normalized, isManagedSession)) continue;
+			try {
+				switch (normalized.subject) {
+					case ClientSubjects.session.started:
+						await this.bus.emit(ClientSubjects.session.started, await this.enrichForkLineage(normalized.payload));
+						break;
+					case ClientSubjects.session.userPrompt.submitted:
+						await this.bus.emit(ClientSubjects.session.userPrompt.submitted, normalized.payload);
+						break;
+					case ClientSubjects.session.turn.started:
+						await this.bus.emit(ClientSubjects.session.turn.started, 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;
+					case ClientSubjects.session.subagent.started: {
+						const { payload: subagentStartedPayload } = normalized;
+						await this.bus.emit(ClientSubjects.session.subagent.started, subagentStartedPayload);
+						break;
+					}
+					case ClientSubjects.session.subagent.completed: {
+						const { payload: subagentCompletedPayload } = normalized;
+						await this.bus.emit(ClientSubjects.session.subagent.completed, subagentCompletedPayload);
+						break;
+					}
+					case ClientSubjects.session.compaction.pre: {
+						const { payload: compactionPrePayload } = normalized;
+						await this.bus.emit(ClientSubjects.session.compaction.pre, compactionPrePayload);
+						break;
+					}
+					default: throwUnhandledNormalizedEvent(normalized);
+				}
+			} catch (error) {
+				console.warn("[CodexClientSessionService] Subscriber threw during emission of", normalized.subject.subject, "— continuing with next event.", error);
+				if (firstError === void 0) firstError = error;
+			}
 		}
+		if (firstError !== void 0) throw firstError;
 	}
 	/**
 	* Determine whether a normalized native hook belongs to an adapter-managed
@@ -3003,17 +3493,69 @@ var CodexClientSessionService = class extends BaseService {
 	isAdapterManagedSession(adapterSessionId) {
 		return adapterSessionId !== void 0 && this.managedAdapterSessionIds.has(adapterSessionId);
 	}
+	/**
+	* Returns true when a normalized event should be suppressed by the
+	* adapter-managed gate — that is, when the session is adapter-managed AND the
+	* subject is one the adapter emits AND the event is not a compaction or clear
+	* restart start (which have no adapter counterpart and must always be forwarded).
+	* @param normalized - Normalized hook event to evaluate
+	* @param isManagedSession - Whether the originating session is adapter-managed
+	* @returns True when the event should be dropped from the native-hook path
+	*/
+	shouldSuppressForManagedSession(normalized, isManagedSession) {
+		if (!isManagedSession || !ADAPTER_EMITTED_SUBJECTS.has(normalized.subject)) return false;
+		if (normalized.subject !== ClientSubjects.session.started) return true;
+		const { startMode } = normalized.payload;
+		return startMode !== "compact" && startMode !== "clear";
+	}
+	/**
+	* Enrich a `client.session.started` payload with fork lineage when the
+	* normalizer reported `startMode: 'fresh'` and a rollout path is available.
+	*
+	* Codex classifies a fork child next to a brand-new thread: both fire
+	* `SessionStart` with `source: 'startup'`, and the payload carries no
+	* lineage field. The child's rollout file, however, opens with its own
+	* `session_meta` record, and that record names `forked_from_id` — the parent
+	* thread id. This method performs a bounded read of the rollout head to
+	* recover it, upgrading `startMode` from `'fresh'` to `'fork'` and
+	* populating `parentAdapterSessionId`.
+	*
+	* Only `'fresh'` is sniffed. A resume appends to the *existing* rollout file,
+	* so a resumed fork child would still show its original `forked_from_id`;
+	* upgrading it to `'fork'` would re-register an already known session instead
+	* of letting ingestion rebind it by adapter session id.
+	*
+	* Runs **after** the managed-session suppression gate (so adapter-managed
+	* sessions are already filtered out) and **before** bus emission.
+	*
+	* On any sniff error the payload is returned unchanged — hook processing must
+	* never be blocked by a sniff failure.
+	* @param payload - Normalized `client.session.started` payload
+	* @returns The payload, potentially enriched with fork lineage fields
+	*/
+	async enrichForkLineage(payload) {
+		if (payload.startMode !== "fresh" || payload.transcriptPath === void 0 || payload.adapterSessionId === void 0) return payload;
+		const sniffResult = await sniffRolloutFork(payload.transcriptPath, payload.adapterSessionId);
+		if (sniffResult === void 0) return payload;
+		return {
+			...payload,
+			startMode: "fork",
+			parentAdapterSessionId: sniffResult.parentAdapterSessionId
+		};
+	}
 };
 /**
 * 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
+* `SubjectDefinition` object references rather than a discriminated string
+* literal union, so TypeScript cannot narrow `normalized` to `never` in the
+* default branch.  Exhaustiveness is therefore enforced at runtime by this
+* throw, not at compile time.  When adding a new arm to the switch in
+* {@link CodexClientSessionService.handleHookReceived}, verify that the new
+* subject is also covered here by running the test suite.
+* @param event - Normalized event whose subject is not handled above
 */
 function throwUnhandledNormalizedEvent(event) {
 	const subject = event.subject.subject;