@hydraharness/harness-hooks-codex 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @hydraharness/harness-hooks-codex
+
+A cordis plugin that runs the supported subset of a user's existing **Codex** hook config on the harness's canonical interception points. The **Codex dialect** half of the hooks subsystem. The dialect-agnostic primitives come from [`@hydraharness/harness-hook-protocol`](../hook-protocol/README.md); this bridge owns the Codex-shaped payloads, matcher mode, and decision mapping.
+
+This bridge implements a deliberate subset of Codex's current hook protocol:
+
+- **Seven hook points with Hydra seams:** `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `SubagentStart`, and `SubagentStop`.
+- **Regex-only matchers** (no literal fast path; the matcher is always an unanchored regex).
+- **snake_case stdin payloads** with `turn_id`/`model` extras, written **without** a trailing newline.
+- **No config-time placeholder substitution** (the command still receives the executor's environment and runs through its shell; a host may add trusted plugin variables).
+- **No pre-tool approval or rewrite path** — a hook can block, but the bridge does not pre-approve or replace tool input.
+
+A native cordis plugin could do everything this bridge does, more powerfully; the bridge exists only as a compatibility path for the mapped Codex subset (see [the interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md)).
+
+## Config
+
+```ts
+import type { Config } from '@hydraharness/harness-hooks-codex'
+const config: Config = {
+  configPath: '/path/to/.codex/hooks.json', // required
+  model: 'deepseek-v4',                      // optional: stamped on every payload (Codex includes `model`)
+  defaultTimeoutMs: 600_000,                 // optional: per-hook timeout when a hook sets none
+  stderrSummaryMaxChars: 500,                // optional: char cap on the hook/result event's persisted stderr summary
+}
+```
+
+In a `cordis.yml`:
+
+```yaml
+- hydra-hooks-codex:
+    configPath: ./.codex/hooks.json
+    model: deepseek-v4
+```
+
+The config is parsed **once** at load. `configPath` is **process-level** — a relative path resolves against the process launch cwd at load time, not per-session (`TODO(per-session-hook-config)`). A read/parse failure is contained (logs + registers nothing); an invalid regex matcher on an event that consumes matchers is one such failure and reports its pattern and event. Only sync `type: 'command'` hooks run — a non-command or `async: true` hook is parsed-and-skipped with a warning. A hook accepts `timeout` or the `timeoutSec` alias; one that sets neither runs under the protocol's reference default (`DEFAULT_HOOK_TIMEOUT_MS` from `@hydraharness/harness-hook-protocol`, 10 minutes). Events outside the seven bridge-supported points are dropped at parse.
+
+The hooks themselves run in the agent's session workspace: for the agent-scoped points the bridge passes the session's `cwd` as the hook process's working directory, so a hook operates in the user's project tree, not the server launch dir.
+
+## Hook points → typed Decisions
+
+| Codex hook | Harness point | Mapping |
+|---|---|---|
+| `SessionStart` | `agent/session-start` (emit) | a plain-stdout hook's output → additionalContext → `agent.inject()` |
+| `UserPromptSubmit` | `agent/pre-step` (waterfall) | `block` (exit 2) → `PreStepDecision.reject`; additionalContext-only → delegate via `next()` then append a separately sourced message to a downstream `enter` decision |
+| `PreToolUse` | `tools/pre-execute` (waterfall) | `block` → `PreToolDecision.deny` (no `allow`/`ask`) |
+| `PostToolUse` | `tools/post-execute` (waterfall) | `block` → `block` with feedback; additionalContext-only → delegate via `next()` then prepend a separately sourced context to the downstream decision; Code Mode defers sub-call contexts until the outer `run_code` result |
+| `Stop` | `agent/turn-stopping` (serial) | a blocking Stop hook feeds its reason through `steer()`, forcing another step |
+| `SubagentStart` | `subagent/start` (detached) | additionalContext → `agent.inject()` when the local child is available |
+| `SubagentStop` | `subagent/end` (detached) | observe-only |
+
+A tool call's payload carries the real `tool_name` (the same value the matcher tests) and Codex's `tool_input: { command }` shape (the `command` arg when present, else `''`). The matcher subject is the tool name (`PreToolUse`/`PostToolUse`), the session source (`SessionStart`), or the subagent type (`SubagentStart`/`SubagentStop`); `UserPromptSubmit`/`Stop` ignore matchers.
+
+Every agent-scoped stdin payload carries `session_id` and `transcript_path`. The bridge resolves the latter through `ctx.sessionPersistence.locate(session.header)` when available and otherwise sends `null`, preserving the Codex `string | null` shape. Lookup does not create or flush the artifact, so a path can be absent before the first turn-end checkpoint or omit the current open turn.
+
+`SessionStart` — the one emit point — runs detached; each run chain is tracked, and disposing the bridge aborts a still-running hook process, then drains the continuation before the dispose resolves (`createDetachedRuns` in `@hydraharness/harness-hook-protocol`).
+
+## Context source
+
+Injected context carries an explicit `{ kind: 'plugin', plugin: 'hooks-codex' }` source so the durable message is never mistaken for a user prompt.
+
+## Model Experience
+
+### Hook-provided context
+
+#### What the model sees
+
+`SessionStart`, accepted prompt, and post-tool hooks can add source-attributed context messages; a blocking `Stop` hook adds its reason as next-step steering.
+
+#### Token effect
+
+No cost when hooks return no context. Hook text is data-dependent, logged, and resent until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Blocked prompt or tool outcome
+
+#### What the model sees
+
+Provider-supplied reasons pass through verbatim. When absent, a blocked prompt uses exactly `blocked by UserPromptSubmit hook`, a denied tool becomes `Error: blocked by PreToolUse hook`, blocked post-tool feedback is exactly `blocked by PostToolUse hook`, and a blocking stop adds steering exactly `continue: blocked by Stop hook`. Codex `systemMessage` is not surfaced.
+
+#### Token effect
+
+Blocking a prompt removes its request tokens; denial or feedback adds the retained fallback or provider text; forced continuation pays another full request.
+
+#### KV Cache effect
+
+A blocked prompt sends no request and invalidates nothing. Denial, feedback, and forced-continuation context append after the reusable prefix without rewriting it.
+
+## Known Limitations and Deferred Work
+
+- **Unsupported hook events:** `PermissionRequest`, `PreCompact`, `PostCompact`, `Interrupt`, and `SessionEnd` have no matching Hydra extension point and are dropped during parsing. `SubagentStart` and `SubagentStop` are supported through the shared subagent lifecycle seam. The comparison baseline is Codex's [official hook reference](https://learn.chatgpt.com/docs/hooks).
+- **`SessionStart` is partial:** plain stdout and JSON `additionalContext` work, but the hook runs detached, so context can miss the first request (`TODO(session-start-gating)`).
+- **`UserPromptSubmit` is partial:** blocking plus plain-stdout or JSON context work, but the common `systemMessage` and `{"continue": false}` controls are not enforced.
+- **`PreToolUse` is partial:** blocking works, but `additionalContext`, `permissionDecision: "allow"`, and `updatedInput` are ignored. Every tool is represented as `tool_input: { command }`, so non-shell tool arguments are not faithfully exposed to the hook.
+- **`PostToolUse` is partial:** blocking feedback and JSON `additionalContext` work, but `{"continue": false}` is not enforced, non-shell tool arguments are reduced to `{ command }`, and structured tool output is flattened to text in `tool_response`.
+- **`Stop` is partial:** blocking forces another model turn, but `stop_hook_active` is always `false`, `last_assistant_message` is always `null`, and `{"continue": false}` is not enforced. An unconditionally blocking hook therefore force-continues every step unless it self-limits (`TODO(stop-loop-guard)`).
+- **Common payload and output fields are partial:** every mapped event reports the statically configured `model` and `permission_mode: "default"` instead of current Codex runtime values. `systemMessage` is logged + warned but not surfaced, and `{"continue": false}` is recorded but does not apply Codex's event-specific stop behavior (`TODO(hook-continue-false)`).
+- **Config loading and execution are partial:** one process-level `configPath` is parsed at load; Codex's active user, project, session, system/managed, and plugin layers, trust controls, and inline `config.toml` hook form are not implemented (`TODO(per-session-hook-config)`). Only synchronous `command` handlers run, current metadata such as `statusMessage` and `commandWindows` is ignored, and matching handlers run serially rather than with Codex's concurrent launch semantics. Plugin-bundled commands run with the session cwd; use `PLUGIN_ROOT` or `CLAUDE_PLUGIN_ROOT` for paths inside the installed bundle.

package/lib/index.js

@@ -0,0 +1,392 @@
+import { readFileSync } from "node:fs";
+import z from "@hydraharness/schemastery";
+import { createUserMessage } from "@hydraharness/harness-llm";
+import { DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_STDERR_SUMMARY_MAX_CHARS, appendHookInvoked, appendHookResult, createDetachedRuns, matcherDiagnostic, matchesMatcher, mergeHookOutputs, runHook } from "@hydraharness/harness-hook-protocol";
+//#region lib/types/config.js
+/**
+* Parse Codex's seven-event hook subset into shared {@link MatcherGroup}s. Only synchronous command
+* hooks run; other types and `async: true` commands are recorded as skipped. Codex performs no
+* command substitution.
+* @module @hydraharness/harness-hooks-codex/config
+*/
+/** The seven Codex hook points that have matching Hydra extension points. */
+const CODEX_EVENTS = [
+	"PreToolUse",
+	"PostToolUse",
+	"SessionStart",
+	"UserPromptSubmit",
+	"Stop",
+	"SubagentStart",
+	"SubagentStop"
+];
+function asObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/**
+* Parse a wrapped or bare Codex event map. Unknown events and malformed entries are ignored rather
+* than failing boot; unsupported or asynchronous hooks are returned in `skipped`. Matcher fields on
+* UserPromptSubmit and Stop are discarded because those events have no matcher subject in the bridge. A
+* matcher-bearing runnable group with an invalid regex throws a `SyntaxError`, allowing the bridge
+* to reject the complete config before listener registration.
+* @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
+* @returns the runnable per-event groups plus the skipped hooks with their reasons.
+*/
+function parseCodexConfig(raw) {
+	const config = {};
+	const skipped = [];
+	const root = asObject(raw);
+	const hooksMap = root ? asObject(root.hooks) ?? root : void 0;
+	if (!hooksMap) return {
+		config,
+		skipped
+	};
+	for (const event of CODEX_EVENTS) {
+		const rawGroups = hooksMap[event];
+		if (!Array.isArray(rawGroups)) continue;
+		const groups = [];
+		for (const rawGroup of rawGroups) {
+			const group = asObject(rawGroup);
+			if (!group || !Array.isArray(group.hooks)) continue;
+			const commands = [];
+			for (const rawHook of group.hooks) {
+				const hook = asObject(rawHook);
+				if (!hook) continue;
+				const type = typeof hook.type === "string" ? hook.type : "command";
+				if (type !== "command") {
+					skipped.push({
+						event,
+						reason: `unsupported "${type}" hook`
+					});
+					continue;
+				}
+				if (hook.async === true) {
+					skipped.push({
+						event,
+						reason: "async hook"
+					});
+					continue;
+				}
+				if (typeof hook.command !== "string") continue;
+				const timeout = typeof hook.timeout === "number" ? hook.timeout : typeof hook.timeoutSec === "number" ? hook.timeoutSec : void 0;
+				commands.push({
+					command: hook.command,
+					...timeout !== void 0 ? { timeoutSec: timeout } : {}
+				});
+			}
+			if (commands.length === 0) continue;
+			const matcher = event === "UserPromptSubmit" || event === "Stop" ? void 0 : typeof group.matcher === "string" ? group.matcher : void 0;
+			const diagnostic = matcherDiagnostic(matcher, "codex");
+			if (diagnostic !== void 0) throw new SyntaxError(`${diagnostic} on event ${JSON.stringify(event)}`);
+			groups.push({
+				...matcher !== void 0 ? { matcher } : {},
+				hooks: commands
+			});
+		}
+		if (groups.length > 0) config[event] = groups;
+	}
+	return {
+		config,
+		skipped
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Bridge for unmodified Codex command hooks on harness interception points. It
+* supports seven points (SessionStart, prompt/tool pre/post, Stop, and
+* subagent start/stop), regex-only
+* matchers, snake_case payloads without a trailing newline, no config-time
+* command substitution, and no pre-tool approval or rewrite path; only
+* blocking decisions are honored. Shared execution and parsing live in
+* `@hydraharness/harness-hook-protocol`; see the
+* [hook-bridges Agent Note](../../../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md).
+* @module @hydraharness/harness-hooks-codex
+*/
+const name = "hooks-codex";
+const inject = ["shell"];
+const Config = z.object({
+	configPath: z.string().required(),
+	model: z.string().default(""),
+	defaultTimeoutMs: z.number().default(DEFAULT_HOOK_TIMEOUT_MS),
+	stderrSummaryMaxChars: z.number().default(DEFAULT_STDERR_SUMMARY_MAX_CHARS),
+	env: z.dict(String).default({})
+});
+let handlerCounter = 0;
+function nextHandlerId(point) {
+	return `codex:${point}:${++handlerCounter}`;
+}
+const PLUGIN_SOURCE = {
+	kind: "plugin",
+	plugin: "hooks-codex"
+};
+/** The summary cap bounds a persisted event field — a positive integer or the slice misbehaves silently. */
+function assertPositiveInteger(name, value) {
+	if (!Number.isInteger(value) || value < 1) throw new Error(`hooks-codex: ${name} must be a positive integer`);
+}
+function apply(ctx, config) {
+	const stderrSummaryMaxChars = config.stderrSummaryMaxChars ?? DEFAULT_STDERR_SUMMARY_MAX_CHARS;
+	assertPositiveInteger("stderrSummaryMaxChars", stderrSummaryMaxChars);
+	const defaultTimeoutMs = config.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+	let parsed = {};
+	try {
+		const result = parseCodexConfig(JSON.parse(readFileSync(config.configPath, "utf8")));
+		parsed = result.config;
+		for (const s of result.skipped) ctx.logger.warn(`hooks-codex: skipping ${s.reason} on ${s.event} (only sync command hooks run)`);
+	} catch (error) {
+		ctx.logger.warn(`hooks-codex: could not load hook config "${config.configPath}": ${String(error)} — no hooks registered`);
+		return;
+	}
+	const model = config.model ?? "";
+	const lifecycle = new AbortController();
+	ctx.effect(() => () => {
+		lifecycle.abort(/* @__PURE__ */ new Error("hooks-codex unloaded"));
+	}, "hooks-codex lifecycle");
+	const detached = createDetachedRuns();
+	ctx.effect(() => () => detached.drain(), "hooks-codex: drain detached hook runs");
+	const subagentChildren = /* @__PURE__ */ new Map();
+	/**
+	* Run and fold one configured Codex hook point.
+	*
+	* A supplied turn records the hook invocation/result pair inside that open turn.
+	* Detached lifecycle points omit it.
+	*/
+	async function runPoint(point, matchQuery, payload, opts) {
+		const groups = parsed[point] ?? [];
+		const outputs = [];
+		const workdir = opts.agent?.session.header.cwd;
+		for (const group of groups) {
+			if (!matchesMatcher(group.matcher, matchQuery, "codex")) continue;
+			for (const hook of group.hooks) {
+				const handlerId = nextHandlerId(point);
+				const session = opts.agent?.session;
+				if (session && opts.turn !== void 0) appendHookInvoked(session, {
+					turn: opts.turn,
+					point,
+					dialect: "codex",
+					handlerId,
+					...group.matcher !== void 0 ? { matcher: group.matcher } : {}
+				});
+				const { output, durationMs } = await runHook(ctx.shell, hook, {
+					payload,
+					defaultTimeoutMs,
+					...workdir !== void 0 ? { cwd: workdir } : {},
+					signal: AbortSignal.any([opts.signal, lifecycle.signal]),
+					trailingNewline: false,
+					...config.env === void 0 ? {} : { env: config.env },
+					expectedEventName: point
+				}, () => performance.now());
+				if (opts.plainStdoutAsContext === true && output.exitCode === 0 && output.additionalContext === void 0 && output.stdout.length > 0 && !output.stdout.startsWith("{")) output.additionalContext = output.stdout;
+				outputs.push(output);
+				if (output.systemMessage !== void 0) ctx.logger.warn(`hooks-codex: ${point} hook emitted a systemMessage, which is not yet surfaced (ignored)`);
+				if (session && opts.turn !== void 0) appendHookResult(session, {
+					turn: opts.turn,
+					point,
+					handlerId,
+					output,
+					stderrSummaryMaxChars,
+					durationMs
+				});
+			}
+		}
+		return mergeHookOutputs(outputs);
+	}
+	function contextFrom(merged) {
+		if (merged.additionalContext.length === 0) return void 0;
+		return createUserMessage({
+			content: merged.additionalContext.map((text) => ({
+				type: "text",
+				text
+			})),
+			source: PLUGIN_SOURCE
+		});
+	}
+	/** Prepend one context without flattening source fields or other downstream metadata. */
+	function prependContext(ours, theirs) {
+		return [ours, ...theirs ?? []];
+	}
+	ctx.on("agent/session-start", ({ agent, source }) => {
+		detached.track(runPoint("SessionStart", source, {
+			...base(ctx, agent, "SessionStart", model),
+			source
+		}, {
+			agent,
+			plainStdoutAsContext: true,
+			signal: detached.signal
+		}).then((merged) => {
+			const context = contextFrom(merged);
+			if (context) agent.inject(context);
+		}).catch((error) => {
+			ctx.logger.warn(`hooks-codex: SessionStart hook failed: ${String(error)}`);
+		}));
+	});
+	ctx.on("agent/pre-step", async ({ agent, messages, turn, signal }, next) => {
+		if (messages.length === 0) return next();
+		const merged = await runPoint("UserPromptSubmit", "", {
+			...base(ctx, agent, "UserPromptSubmit", model),
+			turn_id: String(turn),
+			prompt: blocksToText(messages.flatMap((message) => message.content))
+		}, {
+			agent,
+			turn,
+			plainStdoutAsContext: true,
+			signal
+		});
+		if (merged.decision === "deny") return { kind: "reject" };
+		const downstream = await next();
+		const ours = contextFrom(merged);
+		if (!ours || downstream.kind !== "enter") return downstream;
+		return {
+			kind: "enter",
+			messages: [...downstream.messages, ours]
+		};
+	});
+	ctx.on("tools/pre-execute", async (exec, next) => {
+		const turn = lastTurn(exec.agent);
+		const merged = await runPoint("PreToolUse", exec.name, preToolPayload(ctx, exec, model), {
+			...exec.agent ? { agent: exec.agent } : {},
+			turn,
+			signal: exec.signal
+		});
+		if (merged.decision === "deny") return {
+			kind: "deny",
+			reason: merged.reason ?? "blocked by PreToolUse hook"
+		};
+		return next();
+	});
+	ctx.on("tools/post-execute", async (exec, result, next) => {
+		const turn = lastTurn(exec.agent);
+		const merged = await runPoint("PostToolUse", exec.name, postToolPayload(ctx, exec, result, model), {
+			...exec.agent ? { agent: exec.agent } : {},
+			turn,
+			signal: exec.signal
+		});
+		const context = contextFrom(merged);
+		if (merged.decision === "deny") return {
+			kind: "block",
+			feedback: [{
+				type: "text",
+				text: merged.reason ?? "blocked by PostToolUse hook"
+			}],
+			...context ? { additionalContexts: [context] } : {}
+		};
+		const downstream = await next();
+		if (!context) return downstream;
+		if (downstream.kind === "block") return {
+			...downstream,
+			additionalContexts: prependContext(context, downstream.additionalContexts)
+		};
+		return {
+			...downstream,
+			additionalContexts: prependContext(context, downstream.additionalContexts)
+		};
+	});
+	ctx.on("agent/turn-stopping", async ({ agent, turn, signal }) => {
+		const merged = await runPoint("Stop", "", {
+			...turnBase(ctx, agent, "Stop", model),
+			stop_hook_active: false,
+			last_assistant_message: null
+		}, {
+			agent,
+			turn,
+			signal
+		});
+		if (merged.decision === "deny") {
+			const text = merged.reason ?? "continue: blocked by Stop hook";
+			agent.steer(createUserMessage({
+				content: [{
+					type: "text",
+					text
+				}],
+				source: PLUGIN_SOURCE
+			}));
+		}
+	});
+	ctx.on("subagent/start", (info) => {
+		const child = ctx.get("agents")?.get(info.id);
+		if (child !== void 0) subagentChildren.set(info.runId, child);
+		detached.track(runPoint("SubagentStart", SUBAGENT_TYPE, subagentPayload(ctx, "SubagentStart", info, child, model), {
+			...child ? { agent: child } : {},
+			signal: detached.signal
+		}).then((merged) => {
+			const context = contextFrom(merged);
+			if (context && child) child.inject(context);
+		}).catch((error) => {
+			ctx.logger.warn(`hooks-codex: SubagentStart hook failed: ${String(error)}`);
+		}));
+	});
+	ctx.on("subagent/end", (info) => {
+		const child = subagentChildren.get(info.runId) ?? ctx.get("agents")?.get(info.id);
+		subagentChildren.delete(info.runId);
+		detached.track(runPoint("SubagentStop", SUBAGENT_TYPE, subagentPayload(ctx, "SubagentStop", info, child, model), {
+			...child ? { agent: child } : {},
+			signal: detached.signal
+		}).catch((error) => {
+			ctx.logger.warn(`hooks-codex: SubagentStop hook failed: ${String(error)}`);
+		}));
+	});
+}
+/** The default matcher subject used for Codex subagent lifecycle hooks. */
+const SUBAGENT_TYPE = "general-purpose";
+function lastTurn(agent) {
+	if (!agent) return 0;
+	const last = [...agent.session.events].findLast((e) => e.type === "turn/start");
+	/* v8 ignore next -- agent-present turnBase callers are tool/stop extension points inside an open turn. */
+	return last?.type === "turn/start" ? last.data.turn : 0;
+}
+function blocksToText(content) {
+	return content.filter((b) => b.type === "text").map((b) => b.text).join("");
+}
+/** Base fields on every Codex payload (no turn_id). */
+function base(ctx, agent, event, model) {
+	return {
+		session_id: agent?.session.header.id ?? "",
+		transcript_path: agent === void 0 ? null : ctx.get("sessionPersistence")?.locate(agent.session.header)?.path ?? null,
+		cwd: agent?.session.header.cwd ?? process.cwd(),
+		hook_event_name: event,
+		model,
+		permission_mode: "default"
+	};
+}
+/** Base + turn_id, for the turn-scoped events (PreToolUse/PostToolUse/UserPromptSubmit/Stop). */
+function turnBase(ctx, agent, event, model) {
+	return {
+		...base(ctx, agent, event, model),
+		turn_id: String(lastTurn(agent))
+	};
+}
+/** Extract a `command` string from a tool call's parsed arguments, else ''. */
+function commandOf(args) {
+	if (typeof args === "object" && args !== null && "command" in args) {
+		const command = args.command;
+		if (typeof command === "string") return command;
+	}
+	return "";
+}
+function preToolPayload(ctx, exec, model) {
+	return {
+		...turnBase(ctx, exec.agent, "PreToolUse", model),
+		tool_name: exec.name,
+		tool_input: { command: commandOf(exec.arguments) },
+		tool_use_id: exec.callId
+	};
+}
+function postToolPayload(ctx, exec, result, model) {
+	return {
+		...turnBase(ctx, exec.agent, "PostToolUse", model),
+		tool_name: exec.name,
+		tool_input: { command: commandOf(exec.arguments) },
+		tool_use_id: exec.callId,
+		tool_response: blocksToText(result.content)
+	};
+}
+/** Build the Codex-shaped lifecycle payload for a subagent event. */
+function subagentPayload(ctx, event, info, child, model) {
+	return {
+		...base(ctx, child, event, model),
+		agent_id: info.id,
+		agent_type: SUBAGENT_TYPE,
+		...event === "SubagentStop" ? { stop_hook_active: false } : {}
+	};
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-hooks-codex`.
+* @module @hydraharness/harness-hooks-codex/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-hooks-codex";
+/** Cordis companion plugin name. */
+const name = "hooks-codex-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
+* which invocation event each result cites.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Parse Codex's seven-event hook subset into shared {@link MatcherGroup}s. Only synchronous command
+ * hooks run; other types and `async: true` commands are recorded as skipped. Codex performs no
+ * command substitution.
+ * @module @hydraharness/harness-hooks-codex/config
+ */
+import { type MatcherGroup } from '@hydraharness/harness-hook-protocol';
+/** The seven Codex hook points that have matching Hydra extension points. */
+export declare const CODEX_EVENTS: readonly ["PreToolUse", "PostToolUse", "SessionStart", "UserPromptSubmit", "Stop", "SubagentStart", "SubagentStop"];
+/** A parsed Codex config: event name → its matcher groups (command hooks only). */
+export type CodexHookConfig = Record<string, MatcherGroup[]>;
+/** A skipped non-command (or async) hook, surfaced so the bridge can warn. */
+export interface SkippedHook {
+    event: string;
+    reason: string;
+}
+/** The outcome of parsing one Codex config file. */
+export interface ParsedCodexConfig {
+    config: CodexHookConfig;
+    skipped: SkippedHook[];
+}
+/**
+ * Parse a wrapped or bare Codex event map. Unknown events and malformed entries are ignored rather
+ * than failing boot; unsupported or asynchronous hooks are returned in `skipped`. Matcher fields on
+ * UserPromptSubmit and Stop are discarded because those events have no matcher subject in the bridge. A
+ * matcher-bearing runnable group with an invalid regex throws a `SyntaxError`, allowing the bridge
+ * to reject the complete config before listener registration.
+ * @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
+ * @returns the runnable per-event groups plus the skipped hooks with their reasons.
+ */
+export declare function parseCodexConfig(raw: unknown): ParsedCodexConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/config.js

@@ -0,0 +1,82 @@
+/**
+ * Parse Codex's seven-event hook subset into shared {@link MatcherGroup}s. Only synchronous command
+ * hooks run; other types and `async: true` commands are recorded as skipped. Codex performs no
+ * command substitution.
+ * @module @hydraharness/harness-hooks-codex/config
+ */
+import { matcherDiagnostic } from '@hydraharness/harness-hook-protocol';
+/** The seven Codex hook points that have matching Hydra extension points. */
+export const CODEX_EVENTS = [
+    'PreToolUse', 'PostToolUse', 'SessionStart', 'UserPromptSubmit', 'Stop', 'SubagentStart', 'SubagentStop',
+];
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Parse a wrapped or bare Codex event map. Unknown events and malformed entries are ignored rather
+ * than failing boot; unsupported or asynchronous hooks are returned in `skipped`. Matcher fields on
+ * UserPromptSubmit and Stop are discarded because those events have no matcher subject in the bridge. A
+ * matcher-bearing runnable group with an invalid regex throws a `SyntaxError`, allowing the bridge
+ * to reject the complete config before listener registration.
+ * @param raw - the parsed JSON config: a `{ hooks: … }` wrapper or the bare event map.
+ * @returns the runnable per-event groups plus the skipped hooks with their reasons.
+ */
+export function parseCodexConfig(raw) {
+    const config = {};
+    const skipped = [];
+    const root = asObject(raw);
+    const hooksMap = root ? asObject(root.hooks) ?? root : undefined;
+    if (!hooksMap)
+        return { config, skipped };
+    for (const event of CODEX_EVENTS) {
+        const rawGroups = hooksMap[event];
+        // Matcher-group parsing remains dialect-local because the supported hook
+        // shapes and skip reasons differ from Claude Code's.
+        /* jscpd:ignore-start */
+        if (!Array.isArray(rawGroups))
+            continue;
+        const groups = [];
+        for (const rawGroup of rawGroups) {
+            const group = asObject(rawGroup);
+            if (!group || !Array.isArray(group.hooks))
+                continue;
+            const commands = [];
+            for (const rawHook of group.hooks) {
+                const hook = asObject(rawHook);
+                if (!hook)
+                    continue;
+                const type = typeof hook.type === 'string' ? hook.type : 'command';
+                if (type !== 'command') {
+                    skipped.push({ event, reason: `unsupported "${type}" hook` });
+                    continue;
+                }
+                /* jscpd:ignore-end */
+                if (hook.async === true) {
+                    skipped.push({ event, reason: 'async hook' });
+                    continue;
+                }
+                if (typeof hook.command !== 'string')
+                    continue;
+                // Codex accepts `timeout` or the `timeoutSec` alias.
+                const timeout = typeof hook.timeout === 'number' ? hook.timeout
+                    : typeof hook.timeoutSec === 'number' ? hook.timeoutSec : undefined;
+                commands.push({ command: hook.command, ...timeout !== undefined ? { timeoutSec: timeout } : {} });
+            }
+            if (commands.length === 0)
+                continue;
+            const matcher = event === 'UserPromptSubmit' || event === 'Stop'
+                ? undefined
+                : typeof group.matcher === 'string' ? group.matcher : undefined;
+            const diagnostic = matcherDiagnostic(matcher, 'codex');
+            if (diagnostic !== undefined)
+                throw new SyntaxError(`${diagnostic} on event ${JSON.stringify(event)}`);
+            groups.push({ ...matcher !== undefined ? { matcher } : {}, hooks: commands });
+        }
+        if (groups.length > 0)
+            config[event] = groups;
+    }
+    return { config, skipped };
+}
+//# sourceMappingURL=config.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bridge for unmodified Codex command hooks on harness interception points. It
+ * supports seven points (SessionStart, prompt/tool pre/post, Stop, and
+ * subagent start/stop), regex-only
+ * matchers, snake_case payloads without a trailing newline, no config-time
+ * command substitution, and no pre-tool approval or rewrite path; only
+ * blocking decisions are honored. Shared execution and parsing live in
+ * `@hydraharness/harness-hook-protocol`; see the
+ * [hook-bridges Agent Note](../../../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md).
+ * @module @hydraharness/harness-hooks-codex
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+export declare const name = "hooks-codex";
+export declare const inject: string[];
+/** Plugin config: where the Codex hooks.json lives + the model name for payloads. */
+export interface Config {
+    /**
+     * Path to a Codex `hooks.json`. Process-level: read once at load, a relative
+     * path resolves against the process launch cwd.
+     * TODO(per-session-hook-config): per-session project-local discovery from each
+     * `session/new.cwd`.
+     */
+    configPath: string;
+    /** The model name stamped on every payload (Codex includes `model` on each event). */
+    model?: string;
+    /** Default per-hook timeout in ms when a hook sets none (Codex default: 600000). */
+    defaultTimeoutMs?: number;
+    /** Character cap for the `hook/result` event's persisted stderr summary. */
+    stderrSummaryMaxChars?: number;
+    /** Extra trusted environment values supplied by a host-managed plugin runtime. */
+    env?: Record<string, string>;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,309 @@
+/**
+ * Bridge for unmodified Codex command hooks on harness interception points. It
+ * supports seven points (SessionStart, prompt/tool pre/post, Stop, and
+ * subagent start/stop), regex-only
+ * matchers, snake_case payloads without a trailing newline, no config-time
+ * command substitution, and no pre-tool approval or rewrite path; only
+ * blocking decisions are honored. Shared execution and parsing live in
+ * `@hydraharness/harness-hook-protocol`; see the
+ * [hook-bridges Agent Note](../../../../.agents/notes/implemented/feature/2026-06-30-hook-bridges.md).
+ * @module @hydraharness/harness-hooks-codex
+ */
+// Each dialect bridge keeps its complete dependency list visible at the entry
+// point; a cross-package facade for imports alone would add indirection.
+/* jscpd:ignore-start */
+import { readFileSync } from 'node:fs';
+import z from '@hydraharness/schemastery';
+import { createUserMessage } from '@hydraharness/harness-llm';
+import { appendHookInvoked, appendHookResult, createDetachedRuns, DEFAULT_HOOK_TIMEOUT_MS, DEFAULT_STDERR_SUMMARY_MAX_CHARS, matchesMatcher, mergeHookOutputs, runHook, } from '@hydraharness/harness-hook-protocol';
+import { parseCodexConfig } from "./config.js";
+/* jscpd:ignore-end */
+export const name = 'hooks-codex';
+export const inject = ['shell'];
+export const Config = z.object({
+    configPath: z.string().required(),
+    model: z.string().default(''),
+    defaultTimeoutMs: z.number().default(DEFAULT_HOOK_TIMEOUT_MS),
+    stderrSummaryMaxChars: z.number().default(DEFAULT_STDERR_SUMMARY_MAX_CHARS),
+    env: z.dict(String).default({}),
+});
+let handlerCounter = 0;
+function nextHandlerId(point) {
+    return `codex:${point}:${++handlerCounter}`;
+}
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: 'hooks-codex' };
+/** The summary cap bounds a persisted event field — a positive integer or the slice misbehaves silently. */
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`hooks-codex: ${name} must be a positive integer`);
+    }
+}
+export function apply(ctx, config) {
+    // Validate before config parsing so a bad value cannot be hidden by its early return.
+    const stderrSummaryMaxChars = config.stderrSummaryMaxChars ?? DEFAULT_STDERR_SUMMARY_MAX_CHARS;
+    assertPositiveInteger('stderrSummaryMaxChars', stderrSummaryMaxChars);
+    const defaultTimeoutMs = config.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    let parsed = {};
+    try {
+        const raw = JSON.parse(readFileSync(config.configPath, 'utf8'));
+        const result = parseCodexConfig(raw);
+        parsed = result.config;
+        for (const s of result.skipped) {
+            ctx.logger.warn(`hooks-codex: skipping ${s.reason} on ${s.event} (only sync command hooks run)`);
+        }
+    }
+    catch (error) {
+        ctx.logger.warn(`hooks-codex: could not load hook config "${config.configPath}": ${String(error)} — no hooks registered`);
+        return;
+    }
+    const model = config.model ?? '';
+    const lifecycle = new AbortController();
+    ctx.effect(() => () => {
+        lifecycle.abort(new Error('hooks-codex unloaded'));
+    }, 'hooks-codex lifecycle');
+    // SessionStart is the one emit-shaped (detached) point Codex has: track its
+    // run chains so disposal aborts a still-running hook process and drains the
+    // continuation (docs/defensive-patterns.md: dispose must reach quiescence).
+    const detached = createDetachedRuns();
+    ctx.effect(() => () => detached.drain(), 'hooks-codex: drain detached hook runs');
+    const subagentChildren = new Map();
+    /**
+     * Run and fold one configured Codex hook point.
+     *
+     * A supplied turn records the hook invocation/result pair inside that open turn.
+     * Detached lifecycle points omit it.
+     */
+    async function runPoint(point, matchQuery, payload, opts) {
+        const groups = parsed[point] ?? [];
+        const outputs = [];
+        // Run hooks in the agent's session workspace so relative paths address the
+        // user's project rather than the server launch directory.
+        const workdir = opts.agent?.session.header.cwd;
+        for (const group of groups) {
+            // Codex always interprets matchers as regexes; it has no literal fast path.
+            if (!matchesMatcher(group.matcher, matchQuery, 'codex'))
+                continue;
+            for (const hook of group.hooks) {
+                const handlerId = nextHandlerId(point);
+                const session = opts.agent?.session;
+                if (session && opts.turn !== undefined) {
+                    appendHookInvoked(session, {
+                        turn: opts.turn, point, dialect: 'codex', handlerId,
+                        ...group.matcher !== undefined ? { matcher: group.matcher } : {},
+                    });
+                }
+                const { output, durationMs } = await runHook(ctx.shell, hook, {
+                    payload,
+                    defaultTimeoutMs,
+                    ...workdir !== undefined ? { cwd: workdir } : {},
+                    signal: AbortSignal.any([opts.signal, lifecycle.signal]),
+                    trailingNewline: false, // Codex writes stdin without a trailing newline.
+                    ...config.env === undefined ? {} : { env: config.env },
+                    // Discard a `hookSpecificOutput` block naming a different event.
+                    expectedEventName: point,
+                }, () => performance.now());
+                // Clean plain stdout becomes context only when no structured context
+                // exists; nonzero output and raw JSON never leak as prose.
+                if (opts.plainStdoutAsContext === true && output.exitCode === 0
+                    && output.additionalContext === undefined
+                    && output.stdout.length > 0 && !output.stdout.startsWith('{')) {
+                    output.additionalContext = output.stdout;
+                }
+                outputs.push(output);
+                // Execution and decision mapping remain in each bridge so dialect
+                // differences stay explicit at their owning extension point.
+                /* jscpd:ignore-start */
+                if (output.systemMessage !== undefined) {
+                    ctx.logger.warn(`hooks-codex: ${point} hook emitted a systemMessage, which is not yet surfaced (ignored)`);
+                }
+                if (session && opts.turn !== undefined) {
+                    appendHookResult(session, { turn: opts.turn, point, handlerId, output, stderrSummaryMaxChars, durationMs });
+                }
+            }
+        }
+        return mergeHookOutputs(outputs);
+    }
+    // TODO(hook-continue-false): `merged.stop` is logged but needs a run-level halt mechanism.
+    function contextFrom(merged) {
+        if (merged.additionalContext.length === 0)
+            return undefined;
+        const content = merged.additionalContext.map(text => ({ type: 'text', text }));
+        return createUserMessage({ content, source: PLUGIN_SOURCE });
+    }
+    /** Prepend one context without flattening source fields or other downstream metadata. */
+    function prependContext(ours, theirs) {
+        return [ours, ...theirs ?? []];
+    }
+    // SessionStart injects plain stdout when its detached hook resolves; a slow
+    // hook may miss the first request.
+    // TODO(session-start-gating): add a startup gate before promising first-turn delivery.
+    ctx.on('agent/session-start', ({ agent, source }) => {
+        detached.track(runPoint('SessionStart', source, { ...base(ctx, agent, 'SessionStart', model), source }, { agent, plainStdoutAsContext: true, signal: detached.signal })
+            .then((merged) => {
+            const context = contextFrom(merged);
+            if (context)
+                agent.inject(context);
+        })
+            .catch((error) => { ctx.logger.warn(`hooks-codex: SessionStart hook failed: ${String(error)}`); }));
+        /* jscpd:ignore-end */
+    });
+    // UserPromptSubmit → PreStepDecision. Codex supports reject, not rewrite or ask.
+    ctx.on('agent/pre-step', async ({ agent, messages, turn, signal }, next) => {
+        if (messages.length === 0)
+            return next();
+        const payload = {
+            ...base(ctx, agent, 'UserPromptSubmit', model),
+            turn_id: String(turn),
+            prompt: blocksToText(messages.flatMap(message => message.content)),
+        };
+        const merged = await runPoint('UserPromptSubmit', '', payload, {
+            agent, turn, plainStdoutAsContext: true, signal,
+        });
+        /* jscpd:ignore-start */
+        if (merged.decision === 'deny') {
+            return { kind: 'reject' };
+        }
+        // Context alone is not a veto: DELEGATE so a later pre-step listener can
+        // still reject/rewrite, then fold our context onto its decision.
+        const downstream = await next();
+        const ours = contextFrom(merged);
+        if (!ours || downstream.kind !== 'enter')
+            return downstream;
+        return {
+            kind: 'enter',
+            messages: [...downstream.messages, ours],
+        };
+    });
+    // PreToolUse → PreToolDecision. Codex blocks only (no allow/ask honored).
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        const turn = lastTurn(exec.agent);
+        const merged = await runPoint('PreToolUse', exec.name, preToolPayload(ctx, exec, model), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal });
+        /* jscpd:ignore-end */
+        if (merged.decision === 'deny')
+            return { kind: 'deny', reason: merged.reason ?? 'blocked by PreToolUse hook' };
+        return next();
+    });
+    // PostToolUse → PostToolDecision (block with feedback, or attach context).
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+        const turn = lastTurn(exec.agent);
+        /* jscpd:ignore-start */
+        const merged = await runPoint('PostToolUse', exec.name, postToolPayload(ctx, exec, result, model), { ...exec.agent ? { agent: exec.agent } : {}, turn, signal: exec.signal });
+        const context = contextFrom(merged);
+        if (merged.decision === 'deny') {
+            return { kind: 'block', feedback: [{ type: 'text', text: merged.reason ?? 'blocked by PostToolUse hook' }], ...context ? { additionalContexts: [context] } : {} };
+        }
+        // Context alone is not a veto: DELEGATE, then fold our context onto the
+        // downstream decision (a downstream block carries it too).
+        const downstream = await next();
+        if (!context)
+            return downstream;
+        if (downstream.kind === 'block') {
+            return { ...downstream, additionalContexts: prependContext(context, downstream.additionalContexts) };
+        }
+        return {
+            ...downstream,
+            additionalContexts: prependContext(context, downstream.additionalContexts),
+        };
+    });
+    // A blocking Stop hook steers at the stopping boundary, which makes the
+    // machine observe pending input and run another step.
+    // TODO(stop-loop-guard): Codex supplies `stop_hook_active` so a Stop hook can
+    // avoid continuing the same turn indefinitely. It is always false here, so an
+    // unconditionally blocking hook force-continues every step until it self-limits.
+    ctx.on('agent/turn-stopping', async ({ agent, turn, signal }) => {
+        const merged = await runPoint('Stop', '', { ...turnBase(ctx, agent, 'Stop', model), stop_hook_active: false, last_assistant_message: null }, { agent, turn, signal });
+        /* jscpd:ignore-end */
+        if (merged.decision === 'deny') {
+            // A blocking Stop hook forces continuation; a block with no reason (exit 2,
+            // empty stderr) still forces it — fall back to a generic steering line
+            // rather than letting the turn stop.
+            const text = merged.reason ?? 'continue: blocked by Stop hook';
+            agent.steer(createUserMessage({ content: [{ type: 'text', text }], source: PLUGIN_SOURCE }));
+        }
+    });
+    // SubagentStart may inject child context; SubagentStop is observe-only. The
+    // generic subagent seam carries no agent-type label, so both use a stable
+    // default matcher subject.
+    ctx.on('subagent/start', (info) => {
+        const child = ctx.get('agents')?.get(info.id);
+        if (child !== undefined)
+            subagentChildren.set(info.runId, child);
+        detached.track(runPoint('SubagentStart', SUBAGENT_TYPE, subagentPayload(ctx, 'SubagentStart', info, child, model), { ...child ? { agent: child } : {}, signal: detached.signal })
+            .then((merged) => {
+            const context = contextFrom(merged);
+            if (context && child)
+                child.inject(context);
+        })
+            .catch((error) => { ctx.logger.warn(`hooks-codex: SubagentStart hook failed: ${String(error)}`); }));
+    });
+    ctx.on('subagent/end', (info) => {
+        const child = subagentChildren.get(info.runId) ?? ctx.get('agents')?.get(info.id);
+        subagentChildren.delete(info.runId);
+        detached.track(runPoint('SubagentStop', SUBAGENT_TYPE, subagentPayload(ctx, 'SubagentStop', info, child, model), { ...child ? { agent: child } : {}, signal: detached.signal })
+            .catch((error) => { ctx.logger.warn(`hooks-codex: SubagentStop hook failed: ${String(error)}`); }));
+    });
+}
+/** The default matcher subject used for Codex subagent lifecycle hooks. */
+const SUBAGENT_TYPE = 'general-purpose';
+// --- Codex DIALECT payloads: snake_case, model on every event, turn_id on
+// turn-scoped events. ---
+// These small payload helpers intentionally remain next to the dialect shape;
+// sharing them would pull bridge-only agent/LLM dependencies into hook-protocol.
+/* jscpd:ignore-start */
+function lastTurn(agent) {
+    if (!agent)
+        return 0;
+    const last = [...agent.session.events].findLast(e => e.type === 'turn/start');
+    /* v8 ignore next -- agent-present turnBase callers are tool/stop extension points inside an open turn. */
+    return last?.type === 'turn/start' ? last.data.turn : 0;
+}
+function blocksToText(content) {
+    return content.filter((b) => b.type === 'text').map(b => b.text).join('');
+}
+/* jscpd:ignore-end */
+/** Base fields on every Codex payload (no turn_id). */
+function base(ctx, agent, event, model) {
+    return {
+        session_id: agent?.session.header.id ?? '',
+        transcript_path: agent === undefined
+            ? null
+            : ctx.get('sessionPersistence')?.locate(agent.session.header)?.path ?? null,
+        cwd: agent?.session.header.cwd ?? process.cwd(),
+        hook_event_name: event,
+        model,
+        permission_mode: 'default',
+    };
+}
+/** Base + turn_id, for the turn-scoped events (PreToolUse/PostToolUse/UserPromptSubmit/Stop). */
+function turnBase(ctx, agent, event, model) {
+    return { ...base(ctx, agent, event, model), turn_id: String(lastTurn(agent)) };
+}
+/** Extract a `command` string from a tool call's parsed arguments, else ''. */
+function commandOf(args) {
+    if (typeof args === 'object' && args !== null && 'command' in args) {
+        const command = args.command;
+        if (typeof command === 'string')
+            return command;
+    }
+    return '';
+}
+function preToolPayload(ctx, exec, model) {
+    // `tool_name` is the REAL tool name (matching the `exec.name` matcher subject);
+    // a hardcoded constant would disagree with what the matcher tests and make a
+    // config's tool matcher never fire. `tool_input` keeps Codex's `{ command }`
+    // shape (its shell payload), derived from the call's `command` arg when present.
+    return { ...turnBase(ctx, exec.agent, 'PreToolUse', model), tool_name: exec.name, tool_input: { command: commandOf(exec.arguments) }, tool_use_id: exec.callId };
+}
+function postToolPayload(ctx, exec, result, model) {
+    return { ...turnBase(ctx, exec.agent, 'PostToolUse', model), tool_name: exec.name, tool_input: { command: commandOf(exec.arguments) }, tool_use_id: exec.callId, tool_response: blocksToText(result.content) };
+}
+/** Build the Codex-shaped lifecycle payload for a subagent event. */
+function subagentPayload(ctx, event, info, child, model) {
+    return {
+        ...base(ctx, child, event, model),
+        agent_id: info.id,
+        agent_type: SUBAGENT_TYPE,
+        ...event === 'SubagentStop' ? { stop_hook_active: false } : {},
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-codex`.
+ * @module @hydraharness/harness-hooks-codex/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "hooks-codex-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-codex`.
+ * @module @hydraharness/harness-hooks-codex/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-hooks-codex';
+/** Cordis companion plugin name. */
+export const name = 'hooks-codex-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
+ * which invocation event each result cites.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@hydraharness/harness-hooks-codex",
+  "description": "Bridge plugin: run a Codex hooks.json hook config on the Hydra harness interception seams",
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/hooks/hooks-codex"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./config": {
+      "types": "./lib/types/config.d.ts",
+      "default": "./lib/types/config.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-hook-protocol": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.5",
+    "@hydraharness/harness-shell": "^0.1.1-rc.5",
+    "@hydraharness/harness-bash-local": "^0.1.1-rc.5",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.5",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.5",
+    "@hydraharness/harness-subprocess-local": "^0.1.1-rc.5",
+    "@hydraharness/harness-hook-protocol": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-llm": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence": "^0.1.1-rc.5",
+    "@hydraharness/harness-session-persistence-jsonl": "^0.1.1-rc.5",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.5",
+    "@hydraharness/harness-tools": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}