@principles/codex-adapter 0.1.0

package/dist/codec/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Codec barrel — input decoder + output encoder for Codex CLI.
+ */
+export { decodeCodexInput, CodexDecoderError, CODEX_EVENT_PRE_TOOL_USE, CODEX_EVENT_POST_TOOL_USE, CODEX_EVENT_USER_PROMPT_SUBMIT, CODEX_EVENT_SESSION_START, CODEX_EVENT_SESSION_END, } from './input-decoder.js';
+export { encodeCodexOutput, codexOutputFieldsAreWhitelisted, CodexEncoderError, } from './output-encoder.js';
+export type { CodexPreToolUseOutput, CodexPostToolUseOutput, CodexUserPromptSubmitOutput, CodexSessionStartOutput, CodexHookOutput, } from './output-encoder.js';

package/dist/codec/index.js

@@ -0,0 +1,5 @@
+/**
+ * Codec barrel — input decoder + output encoder for Codex CLI.
+ */
+export { decodeCodexInput, CodexDecoderError, CODEX_EVENT_PRE_TOOL_USE, CODEX_EVENT_POST_TOOL_USE, CODEX_EVENT_USER_PROMPT_SUBMIT, CODEX_EVENT_SESSION_START, CODEX_EVENT_SESSION_END, } from './input-decoder.js';
+export { encodeCodexOutput, codexOutputFieldsAreWhitelisted, CodexEncoderError, } from './output-encoder.js';

package/dist/codec/input-decoder.d.ts

@@ -0,0 +1,12 @@
+import type { HostEvent } from '@principles/core/host';
+export declare const CODEX_EVENT_PRE_TOOL_USE = "PreToolUse";
+export declare const CODEX_EVENT_POST_TOOL_USE = "PostToolUse";
+export declare const CODEX_EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
+export declare const CODEX_EVENT_SESSION_START = "SessionStart";
+export declare const CODEX_EVENT_SESSION_END = "SessionEnd";
+export declare class CodexDecoderError extends Error {
+    readonly reason: string;
+    readonly nextAction: string;
+    constructor(reason: string, nextAction: string);
+}
+export declare function decodeCodexInput(raw: unknown): HostEvent;

package/dist/codec/input-decoder.js

@@ -0,0 +1,84 @@
+export const CODEX_EVENT_PRE_TOOL_USE = 'PreToolUse';
+export const CODEX_EVENT_POST_TOOL_USE = 'PostToolUse';
+export const CODEX_EVENT_USER_PROMPT_SUBMIT = 'UserPromptSubmit';
+export const CODEX_EVENT_SESSION_START = 'SessionStart';
+export const CODEX_EVENT_SESSION_END = 'SessionEnd';
+const EVENT_KINDS = new Map([
+    [CODEX_EVENT_PRE_TOOL_USE, 'before_tool_call'],
+    [CODEX_EVENT_POST_TOOL_USE, 'after_tool_call'],
+    [CODEX_EVENT_USER_PROMPT_SUBMIT, 'before_prompt_build'],
+    [CODEX_EVENT_SESSION_START, 'session_start'],
+]);
+export class CodexDecoderError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(`Codex input decode failed: ${reason}`);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'CodexDecoderError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+function requiredString(value, key) {
+    const candidate = own(value, key);
+    if (typeof candidate !== 'string' || candidate.trim().length === 0) {
+        throw new CodexDecoderError(`missing or malformed required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+    }
+    return candidate;
+}
+function requiredNullableString(value, key) {
+    if (!Object.hasOwn(value, key))
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+    const candidate = own(value, key);
+    if (candidate !== null && typeof candidate !== 'string') {
+        throw new CodexDecoderError(`malformed required field "${key}"`, `${key} must be a string or null.`);
+    }
+    return candidate;
+}
+function requiredUnknown(value, key) {
+    if (!Object.hasOwn(value, key))
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli 0.147.0 ${key} field.`);
+    return own(value, key);
+}
+function validateCommon(raw, needsTurn) {
+    const sessionId = requiredString(raw, 'session_id');
+    requiredNullableString(raw, 'transcript_path');
+    const workspaceDir = requiredString(raw, 'cwd');
+    requiredString(raw, 'model');
+    requiredString(raw, 'permission_mode');
+    const turnId = needsTurn ? requiredString(raw, 'turn_id') : undefined;
+    return { workspaceDir, sessionId, ...(turnId ? { turnId } : {}) };
+}
+export function decodeCodexInput(raw) {
+    if (!isRecord(raw))
+        throw new CodexDecoderError('stdin payload is not a JSON object', 'Run this executable only as a Codex command hook.');
+    const eventName = requiredString(raw, 'hook_event_name');
+    const kind = EVENT_KINDS.get(eventName);
+    if (!kind)
+        throw new CodexDecoderError(`unknown hook_event_name "${eventName}"`, 'Configure only PreToolUse, PostToolUse, UserPromptSubmit, or SessionStart.');
+    const common = validateCommon(raw, kind !== 'session_start');
+    let context;
+    let rawPayload = raw;
+    if (kind === 'before_tool_call' || kind === 'after_tool_call') {
+        const toolName = requiredString(raw, 'tool_name');
+        const toolInput = requiredUnknown(raw, 'tool_input');
+        requiredString(raw, 'tool_use_id');
+        const toolOutput = kind === 'after_tool_call' ? requiredUnknown(raw, 'tool_response') : undefined;
+        context = { ...common, toolName, toolInput, ...(kind === 'after_tool_call' ? { toolOutput } : {}) };
+        rawPayload = { toolInput: { toolName, params: toolInput } };
+    }
+    else if (kind === 'before_prompt_build') {
+        context = { ...common, promptContent: requiredString(raw, 'prompt') };
+    }
+    else {
+        context = { ...common, source: requiredString(raw, 'source') };
+    }
+    const source = `codex:${eventName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}`;
+    return { kind, context, rawPayload, source };
+}

package/dist/codec/output-encoder.d.ts

@@ -0,0 +1,32 @@
+import type { HostEventResult } from '@principles/core/host';
+type HookName = 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'SessionStart';
+interface HookSpecificOutput {
+    hookEventName: HookName;
+    permissionDecision?: 'deny';
+    permissionDecisionReason?: string;
+    additionalContext?: string;
+}
+export interface CodexPreToolUseOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexPostToolUseOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexUserPromptSubmitOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexSessionStartOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export type CodexHookOutput = CodexPreToolUseOutput | CodexPostToolUseOutput | CodexUserPromptSubmitOutput | CodexSessionStartOutput;
+export declare class CodexEncoderError extends Error {
+    readonly reason: string;
+    readonly nextAction: string;
+    constructor(reason: string, nextAction: string);
+}
+export declare function encodeCodexOutput(result: HostEventResult, kind: string): CodexHookOutput;
+export declare function codexOutputFieldsAreWhitelisted(output: unknown): {
+    ok: boolean;
+    violators: string[];
+};
+export {};

package/dist/codec/output-encoder.js

@@ -0,0 +1,51 @@
+export class CodexEncoderError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(`Codex output encode failed: ${reason}`);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'CodexEncoderError';
+    }
+}
+function nonEmpty(value) { return typeof value === 'string' && value.trim().length > 0; }
+export function encodeCodexOutput(result, kind) {
+    if (result.modifiedInput !== undefined)
+        throw new CodexEncoderError('modifiedInput is unsupported by the PD Codex adapter', 'Deny or allow the original input.');
+    if (result.additionalContext !== undefined && !nonEmpty(result.additionalContext))
+        throw new CodexEncoderError('additionalContext must be non-empty', 'Drop or populate additionalContext.');
+    const names = new Map([['before_tool_call', 'PreToolUse'], ['after_tool_call', 'PostToolUse'], ['before_prompt_build', 'UserPromptSubmit'], ['session_start', 'SessionStart']]);
+    const hookEventName = names.get(kind);
+    if (!hookEventName)
+        throw new CodexEncoderError(`unknown event kind "${kind}"`, 'Encode only a supported Codex hook event.');
+    if (result.decision === 'deny' && kind !== 'before_tool_call')
+        throw new CodexEncoderError(`deny is unsupported for ${kind}`, 'Return the route-compatible host result.');
+    const hookSpecificOutput = { hookEventName };
+    if (result.decision === 'deny') {
+        if (!nonEmpty(result.reason))
+            throw new CodexEncoderError('deny requires a non-empty reason', 'Supply an operator-readable reason.');
+        hookSpecificOutput.permissionDecision = 'deny';
+        hookSpecificOutput.permissionDecisionReason = result.reason.trim();
+    }
+    else if (result.reason !== undefined) {
+        throw new CodexEncoderError('reason without deny is unsupported', 'Drop reason for a non-deny decision.');
+    }
+    if (result.additionalContext !== undefined)
+        hookSpecificOutput.additionalContext = result.additionalContext;
+    return { hookSpecificOutput };
+}
+const TOP_LEVEL = new Set(['hookSpecificOutput']);
+const NESTED = new Set(['hookEventName', 'permissionDecision', 'permissionDecisionReason', 'additionalContext']);
+export function codexOutputFieldsAreWhitelisted(output) {
+    if (typeof output !== 'object' || output === null || Array.isArray(output))
+        return { ok: false, violators: ['<not-an-object>'] };
+    const top = Object.keys(output).filter((key) => !TOP_LEVEL.has(key));
+    const descriptor = Object.getOwnPropertyDescriptor(output, 'hookSpecificOutput')?.value;
+    if (typeof descriptor !== 'object' || descriptor === null || Array.isArray(descriptor))
+        return { ok: false, violators: [...top, 'hookSpecificOutput'] };
+    const nested = Object.keys(descriptor).filter((key) => !NESTED.has(key)).map((key) => `hookSpecificOutput.${key}`);
+    const name = Object.getOwnPropertyDescriptor(descriptor, 'hookEventName')?.value;
+    if (!['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart'].includes(String(name)))
+        nested.push('hookSpecificOutput.hookEventName');
+    return { ok: top.length + nested.length === 0, violators: [...top, ...nested] };
+}

package/dist/host-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CodexHooksHostAdapter — implements HostAdapter for OpenAI Codex CLI (ADR-0020 §2.5)
+ *
+ * Codex CLI spawns `pd-hook.js` as a subprocess for each hook event, writes
+ * the event payload as JSON on stdin, and reads the output as JSON on stdout.
+ * This adapter owns:
+ *   1. Decoding the raw stdin JSON into a unified HostEvent (via codec/input-decoder).
+ *   2. Encoding a unified HostEventResult into Codex's camelCase stdout JSON
+ *      (via codec/output-encoder).
+ *
+ * The adapter does NOT own hook business logic (pain detection, principle
+ * injection, gate enforcement). Those run in the openclaw-plugin/core code and
+ * are invoked by `pd-hook.js` after decodeEvent() and before encodeOutput().
+ *
+ * MVP scope (ADR-0014 / ADR-0020):
+ * - Subscribes to 4 events: before_tool_call, after_tool_call, before_prompt_build, session_start.
+ * - session_end is deferred (observe-only, no MVP-Core activation path uses it).
+ * - hostKind = 'subprocess' (Codex spawns pd-hook.js; OpenClaw is 'inprocess').
+ *
+ * Feature flag: when `host.codex.enabled = false` (default), `pd-hook.js`
+ * short-circuits to `{} + exit 0` before invoking this adapter (rc-9).
+ */
+import type { HostAdapter, HostEvent, HostEventKind, HostEventResult } from '@principles/core/host';
+export declare class CodexHooksHostAdapter implements HostAdapter {
+    readonly hostId = "codex";
+    readonly hostKind: 'subprocess';
+    subscribedEvents(): readonly HostEventKind[];
+    decodeEvent(raw: unknown): HostEvent;
+    encodeOutput(result: HostEventResult, kind: HostEventKind): unknown;
+}

package/dist/host-adapter.js

@@ -0,0 +1,24 @@
+import { decodeCodexInput, encodeCodexOutput } from './codec/index.js';
+const SUBSCRIBED_EVENTS = [
+    'before_tool_call',
+    'after_tool_call',
+    'before_prompt_build',
+    'session_start',
+    // 'session_end' deferred to post-MVP
+];
+export class CodexHooksHostAdapter {
+    hostId = 'codex';
+    hostKind = 'subprocess';
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    subscribedEvents() {
+        return SUBSCRIBED_EVENTS;
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    decodeEvent(raw) {
+        return decodeCodexInput(raw);
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    encodeOutput(result, kind) {
+        return encodeCodexOutput(result, kind);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @principles/codex-adapter — Codex CLI Host Adapter (ADR-0020)
+ *
+ * Implements HostAdapter for OpenAI Codex CLI's stdin/stdout JSON hook model.
+ * This package is INDEPENDENT of `packages/openclaw-plugin/` — the two hosts
+ * have different extension models (Codex: subprocess; OpenClaw: in-process).
+ */
+export { CodexHooksHostAdapter } from './host-adapter.js';
+export { processHookInvocation } from './pd-hook.js';
+export type { PdHookResult } from './pd-hook.js';
+export * from './codec/index.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @principles/codex-adapter — Codex CLI Host Adapter (ADR-0020)
+ *
+ * Implements HostAdapter for OpenAI Codex CLI's stdin/stdout JSON hook model.
+ * This package is INDEPENDENT of `packages/openclaw-plugin/` — the two hosts
+ * have different extension models (Codex: subprocess; OpenClaw: in-process).
+ */
+export { CodexHooksHostAdapter } from './host-adapter.js';
+export { processHookInvocation } from './pd-hook.js';
+export * from './codec/index.js';

package/dist/pd-hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+type EnvMap = Record<string, string | undefined>;
+export interface PdHookResult {
+    stdout: unknown;
+    exitCode: number;
+    stderr: string[];
+}
+export declare function processHookInvocation(rawStdin: string, _env?: EnvMap, cwd?: string): Promise<PdHookResult>;
+export {};

package/dist/pd-hook.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { createProductionHostRuntime, loadPdConfigForPlugin, resolveNearestPdWorkspace } from '@principles/host-runtime';
+import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
+import { CodexHooksHostAdapter } from './host-adapter.js';
+import { CodexDecoderError, CodexEncoderError } from './codec/index.js';
+const MAX_DIAGNOSTIC = 500;
+function diagnostic(reason, nextAction) {
+    const boundedReason = reason.replace(/\s+/g, ' ').trim().slice(0, MAX_DIAGNOSTIC);
+    const boundedNextAction = nextAction.replace(/\s+/g, ' ').trim().slice(0, MAX_DIAGNOSTIC);
+    return `[PD] status=degraded reason=${boundedReason} nextAction=${boundedNextAction}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message.slice(0, MAX_DIAGNOSTIC) : 'unknown_error';
+}
+export async function processHookInvocation(rawStdin, _env = process.env, cwd = process.cwd()) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawStdin);
+    }
+    catch (error) {
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(`stdin_json_invalid:${errorMessage(error)}`, 'Verify Codex invokes the PD hook with one JSON object.')] };
+    }
+    const adapter = new CodexHooksHostAdapter();
+    let event;
+    try {
+        event = adapter.decodeEvent(parsed);
+    }
+    catch (error) {
+        const reason = error instanceof CodexDecoderError ? error.reason : `decode_threw:${errorMessage(error)}`;
+        const nextAction = error instanceof CodexDecoderError ? error.nextAction : 'Inspect the Codex 0.147 hook payload.';
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(reason, nextAction)] };
+    }
+    // Codex 0.147 supplies the invocation cwd. It is the authoritative starting
+    // point; a process-global environment variable can otherwise route one
+    // Workspace's hook into another Workspace's business state.
+    const requestedCwd = event.context.workspaceDir || cwd;
+    const resolution = resolveNearestPdWorkspace(requestedCwd);
+    if (!resolution.ok)
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(resolution.reason, resolution.nextAction)] };
+    event = { ...event, context: { ...event.context, workspaceDir: resolution.workspaceDir } };
+    const config = loadPdConfigForPlugin(resolution.workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(first?.reason ?? 'pd_config_invalid', first?.nextAction ?? 'Repair .pd/config.yaml.')] };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.codex']?.enabled !== true) {
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic('host.codex_disabled', 'Set features.host.codex.enabled=true in the selected Workspace to enable PD.')] };
+    }
+    try {
+        if (event.kind === 'session_start') {
+            const health = await createProductionHostRuntime().health(resolution.workspaceDir);
+            if (!health.ok)
+                return { stdout: {}, exitCode: 0, stderr: [diagnostic(health.reason ?? 'runtime_unhealthy', health.nextAction ?? 'Inspect the Workspace runtime.')] };
+            return { stdout: adapter.encodeOutput({ decision: 'allow', source: event.source }, 'session_start'), exitCode: 0, stderr: [] };
+        }
+        const result = await createProductionHostRuntime().dispatch(event);
+        const stderr = (result.warnings ?? []).slice(0, 16).map((warning) => diagnostic(warning, 'Inspect PD Workspace state and retry; the hook failed open.'));
+        return { stdout: adapter.encodeOutput(result, event.kind), exitCode: 0, stderr };
+    }
+    catch (error) {
+        const reason = error instanceof CodexEncoderError ? error.reason : `runtime_failed:${errorMessage(error)}`;
+        const nextAction = error instanceof CodexEncoderError ? error.nextAction : 'Inspect PD Workspace state and retry; the hook failed open.';
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(reason, nextAction)] };
+    }
+}
+async function main() {
+    let raw;
+    try {
+        raw = readFileSync(0, 'utf8');
+    }
+    catch (error) {
+        process.stderr.write(`${diagnostic(`stdin_read_failed:${errorMessage(error)}`, 'Run the hook from Codex with JSON stdin.')}\n`);
+        process.stdout.write('{}\n');
+        return;
+    }
+    let result;
+    try {
+        result = await processHookInvocation(raw);
+    }
+    catch (error) {
+        // Fail-open belt for an unexpected pre-dispatch throw (e.g. a workspace
+        // resolution race): Codex must still receive exactly one JSON object on
+        // stdout and a bounded diagnostic on stderr — never a bare crash.
+        process.stderr.write(`${diagnostic(`hook_pipeline_unexpected:${errorMessage(error)}`, 'Retry the tool call; if it repeats, inspect PD stderr and the Workspace .pd/config.yaml state.')}\n`);
+        result = { stdout: {}, exitCode: 0, stderr: [] };
+    }
+    for (const line of result.stderr)
+        process.stderr.write(`${line}\n`);
+    process.stdout.write(`${JSON.stringify(result.stdout)}\n`);
+    process.exitCode = result.exitCode;
+}
+const [, entry] = process.argv;
+if (entry && import.meta.url === pathToFileURL(entry).href)
+    void main();

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@principles/codex-adapter",
+  "version": "0.1.0",
+  "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./pd-hook": {
+      "types": "./dist/pd-hook.d.ts",
+      "default": "./dist/pd-hook.js"
+    },
+    "./host-adapter": {
+      "types": "./dist/host-adapter.d.ts",
+      "default": "./dist/host-adapter.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@principles/core": "^1.74.1",
+    "@principles/host-runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csuzngjh/principles.git",
+    "directory": "packages/codex-adapter"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}