@ory/codex 0.1.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "ory-codex",
+  "version": "0.1.0",
+  "description": "Ory authentication and authorization for Codex CLI — session auth, tool permissions, and audit logging",
+  "author": {
+    "name": "Ory",
+    "url": "https://ory.com"
+  },
+  "homepage": "https://ory.com"
+}

package/README.md

@@ -0,0 +1,90 @@
+# Ory Agent Plugin: Codex
+
+[Ory](https://ory.com) bundled into [Codex](https://github.com/openai/codex): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Codex runs.
+
+## Install
+
+Codex loads hooks from its config. Install and register in one step, with no prior `npm install` required:
+
+```bash
+npx @ory/codex install            # current project
+npx @ory/codex install --global   # all Codex projects
+npx @ory/codex uninstall
+```
+
+`install` wires the Ory hooks into your Codex config non-destructively (existing hooks are preserved), registers the Ory MCP server, and drops the Ory skill catalog into `.codex/skills/`. If the installer can't locate your Codex config, `npx ory-codex-setup` writes it directly.
+
+## Developer experience
+
+This plugin is a productivity layer for Ory itself. You don't need a real Ory project, an account, or any prior Ory experience to start using it.
+
+### Skills for scaffolding Ory into your application
+
+Codex surfaces the skill catalog in `/skills` and auto-invokes by description. Ask Codex to add Ory auth to your codebase, or invoke a skill directly:
+
+- **`ory-auth-setup`**: full project setup. Install the Ory CLI, create an Ory Network project, add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
+- **`ory-login-flow`**: login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
+- **`ory-social-login`**: Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
+- **`ory-local-dev`**: drive the local Ory stack (below) from within Codex to prototype and test against without a remote project.
+
+Skills are versioned with the plugin so guidance stays in sync as Ory APIs evolve.
+
+### Ory MCP server
+
+Bundled and registered automatically. It exposes the Ory CLI and the Ory Network REST API as MCP tools so Codex can manage identities, OAuth2 clients, projects, permission tuples, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
+
+### Local Ory stack in one command
+
+From Codex's `/skills` picker:
+
+```
+ory-local-up      # start a local Ory instance in Docker
+ory-local-down    # tear it all down
+```
+
+Or via the CLI: `npx ory-codex local up | down`.
+
+`local up` runs a local Ory instance in Docker, covering everything the plugin and your scaffolded application need. It also brings up a login UI on `:3000` and Jaeger on `:16686`, all reachable through `http://localhost:4000`. A test user identity is seeded and the credentials are printed for you. Use it to:
+
+- **Learn Ory hands-on** without signing up for a hosted project.
+- **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend in your local dev loop.
+- **Test** an auth integration end-to-end before pushing anything to a real environment.
+- **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
+
+Point `ORY_PROJECT_URL` at `http://localhost:4000` (or run `npx ory-codex configure`) and the security features below run against the local stack.
+
+## Configure
+
+```bash
+npx ory-codex configure --project-url https://<id>.projects.oryapis.com --api-key ory_pat_...
+```
+
+Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine. Without it the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked.
+
+## Agent security (Argus)
+
+Once the plugin is pointed at an Ory project (local or hosted), Codex's session and every tool call are governed by Ory.
+
+- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1`. The Codex process (the **agent**) gets its own OAuth2 identity, self-registered via Dynamic Client Registration on first run.
+- **Authorization.** Before any tool runs, the plugin checks Ory Permissions against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
+- **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user-to-agent delegation is written to Ory as a Zanzibar tuple so "agent X acting on behalf of user Y" stays queryable after tokens expire.
+
+The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your tuples; grant explicit `invoke` relations for the tools each user should be able to run.
+
+## CLI
+
+```
+npx ory-codex install | uninstall                 [--global]
+npx ory-codex configure                            [--project-url <url>] [--api-key <key>] [--audit-only]
+npx ory-codex agent <status|unregister>            Manage the agent's OAuth2 identity
+npx ory-codex local <up|down|status|seed|logs|env|configure|reset>
+npx ory-codex status
+```
+
+## Links
+
+- [ory.com](https://ory.com)
+
+## License
+
+Apache-2.0

package/dist/cli/main.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Main CLI for @ory/codex.
+ *
+ * Usage:
+ *   npx ory-codex install [--global]     Install hooks into Codex config
+ *   npx ory-codex uninstall              Remove hooks from Codex config
+ *   npx ory-codex configure              Set or view Ory project URL and API key
+ *   npx ory-codex setup [--global]       Write hooks to config directly (fallback)
+ *   npx ory-codex status                 Show plugin status
+ */
+export {};

package/dist/cli/main.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Main CLI for @ory/codex.
+ *
+ * Usage:
+ *   npx ory-codex install [--global]     Install hooks into Codex config
+ *   npx ory-codex uninstall              Remove hooks from Codex config
+ *   npx ory-codex configure              Set or view Ory project URL and API key
+ *   npx ory-codex setup [--global]       Write hooks to config directly (fallback)
+ *   npx ory-codex status                 Show plugin status
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const argus_1 = require("@ory/argus");
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+function main() {
+    const [command, ...args] = process.argv.slice(2);
+    switch (command) {
+        case "install":
+            install(args);
+            break;
+        case "uninstall":
+            uninstall(args);
+            break;
+        case "configure":
+            (0, argus_1.runConfigureCommand)("ory-codex", args);
+            break;
+        case "agent":
+            (0, argus_1.runAgentCommand)("ory-codex", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "setup":
+            require("./setup.js");
+            break;
+        case "status":
+            status();
+            break;
+        case "local":
+            (0, argus_1.runLocalCommand)("ory-codex", args).catch((err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            help();
+            process.exit(1);
+    }
+}
+function install(args) {
+    const isGlobal = args.includes("--global");
+    console.log(`Installing Ory hooks for Codex (scope: ${isGlobal ? "global" : "project"})...`);
+    manualSetup(isGlobal);
+}
+function uninstall(args) {
+    const setupArgs = ["--uninstall", ...args];
+    process.argv = ["node", "setup.js", ...setupArgs];
+    require("./setup.js");
+}
+function manualSetup(isGlobal) {
+    const setupArgs = isGlobal ? ["--global"] : [];
+    process.argv = ["node", "setup.js", ...setupArgs];
+    require("./setup.js");
+}
+function status() {
+    console.log("Ory Agent Plugin Status (Codex)");
+    console.log("================================");
+    console.log("");
+    (0, argus_1.printOryConfig)();
+    (0, argus_1.printEnvironment)();
+    // Plugin-specific status
+    console.log("");
+    console.log("Plugin:");
+    console.log(`  Directory: ${PACKAGE_ROOT}`);
+    console.log(`  Hook script: ${fs.existsSync(path.join(PACKAGE_ROOT, "dist", "hook.js")) ? "built" : "NOT BUILT (run pnpm build)"}`);
+    (0, argus_1.printLogTail)();
+}
+function help() {
+    console.log(`
+ory-codex — Ory plugin for Codex
+
+Usage:
+  npx ory-codex <command> [options]
+
+Commands:
+  install [--global]   Install the Ory hooks into Codex configuration
+  uninstall            Remove the Ory hooks from Codex configuration
+  configure            Set or view Ory project URL and API key
+  setup [--global]     Write hooks directly to config (fallback)
+  status               Show plugin status and configuration
+  local <cmd>          Manage local Ory dev environment (up, down, status, seed, ...)
+
+Examples:
+  npx ory-codex install            # Install for current project
+  npx ory-codex install --global   # Install globally
+  npx ory-codex configure --project-url https://your-project.projects.oryapis.com --api-key ory_pat_...
+  npx ory-codex status             # Check configuration
+  npx ory-codex uninstall          # Remove hooks
+`);
+}
+main();

package/dist/cli/setup.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Setup CLI for the Ory Codex plugin.
+ *
+ * Writes hooks to `.codex/hooks.json` and enables the codex_hooks feature
+ * flag in `.codex/config.toml`. Codex does not read `.codex/config.json`
+ * for hooks; that path is intentionally not used.
+ *
+ * Usage:
+ *   npx ory-codex-setup              # Auto-detect and configure
+ *   npx ory-codex-setup --project-dir /path/to/repo
+ *   npx ory-codex-setup --global     # Install to ~/.codex/
+ *   npx ory-codex-setup --print      # Print config to stdout without writing
+ *   npx ory-codex-setup --uninstall  # Remove Ory hooks from config
+ */
+export {};

package/dist/cli/setup.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Setup CLI for the Ory Codex plugin.
+ *
+ * Writes hooks to `.codex/hooks.json` and enables the codex_hooks feature
+ * flag in `.codex/config.toml`. Codex does not read `.codex/config.json`
+ * for hooks; that path is intentionally not used.
+ *
+ * Usage:
+ *   npx ory-codex-setup              # Auto-detect and configure
+ *   npx ory-codex-setup --project-dir /path/to/repo
+ *   npx ory-codex-setup --global     # Install to ~/.codex/
+ *   npx ory-codex-setup --print      # Print config to stdout without writing
+ *   npx ory-codex-setup --uninstall  # Remove Ory hooks from config
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+const BIN_NAME = "ory-codex-hook";
+const PACKAGE_NAME = "@ory/codex";
+const RENDER_OPTS = {
+    binName: "ory-codex",
+    packageName: "@ory/codex",
+};
+function getCodexDir(args) {
+    if (args.global) {
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? "~";
+        return path.join(home, ".codex");
+    }
+    return path.join(args.projectDir, ".codex");
+}
+function generateHooksConfig() {
+    const cmd = (0, argus_1.resolveHookCommand)(PACKAGE_NAME, BIN_NAME);
+    return {
+        SessionStart: (0, argus_1.flatHookEntry)(cmd),
+        PreToolUse: (0, argus_1.flatHookEntry)(cmd),
+        PostToolUse: (0, argus_1.flatHookEntry)(cmd),
+        PermissionRequest: (0, argus_1.flatHookEntry)(cmd),
+        UserPromptSubmit: (0, argus_1.flatHookEntry)(cmd),
+        Stop: (0, argus_1.flatHookEntry)(cmd),
+    };
+}
+/**
+ * Ensure `[features] codex_hooks = true` is present in config.toml.
+ * Hand-rolled TOML editing — we only manage one line; full TOML parsing
+ * is not warranted. Idempotent.
+ */
+function ensureCodexHooksFeature(configTomlPath) {
+    let contents = "";
+    if (fs.existsSync(configTomlPath)) {
+        contents = fs.readFileSync(configTomlPath, "utf-8");
+    }
+    if (/^codex_hooks\s*=\s*true\b/m.test(contents)) {
+        return;
+    }
+    if (/^\[features\]\s*$/m.test(contents)) {
+        contents = contents.replace(/^\[features\]\s*$/m, (m) => `${m}\ncodex_hooks = true`);
+    }
+    else {
+        const sep = contents.endsWith("\n") || contents.length === 0 ? "" : "\n";
+        contents += `${sep}\n[features]\ncodex_hooks = true\n`;
+    }
+    fs.mkdirSync(path.dirname(configTomlPath), { recursive: true });
+    fs.writeFileSync(configTomlPath, contents);
+}
+/**
+ * Materialize the Ory skill catalog (4 guide skills + 2 user-invocable
+ * command-skills for local-up/local-down) into Codex's skills tree. Codex
+ * surfaces them in the `/skills` picker and the model auto-invokes them
+ * based on the SKILL.md descriptions.
+ *
+ * Codex's documented skill location is `~/.codex/skills/`; the `--global`
+ * flag routes the install there. Project-scope installs land in
+ * `<projectDir>/.codex/skills/` for parity with the hooks layout.
+ */
+function installOrySkills(codexDir) {
+    const skillsDir = path.join(codexDir, "skills");
+    const guideSkills = (0, argus_1.renderOrySkills)("codex", RENDER_OPTS);
+    const commandSkills = (0, argus_1.renderOryCommands)("codex", RENDER_OPTS).map(argus_1.commandToSkill);
+    (0, argus_1.writeSkillTree)(skillsDir, [...guideSkills, ...commandSkills]);
+}
+/** Remove every skill this plugin installed; tidy the dir if it ends up empty. */
+function uninstallOrySkills(codexDir) {
+    const skillsDir = path.join(codexDir, "skills");
+    if (!fs.existsSync(skillsDir))
+        return;
+    (0, argus_1.removeSkillDirs)(skillsDir, [...argus_1.ORY_SKILL_NAMES, ...argus_1.ORY_COMMAND_SKILL_NAMES]);
+    try {
+        if (fs.readdirSync(skillsDir).length === 0) {
+            fs.rmdirSync(skillsDir);
+        }
+    }
+    catch {
+        /* ignore — directory still in use is fine. */
+    }
+}
+/** Remove `codex_hooks = true` from `[features]`. Leaves other entries alone. */
+function removeCodexHooksFeature(configTomlPath) {
+    if (!fs.existsSync(configTomlPath))
+        return;
+    const original = fs.readFileSync(configTomlPath, "utf-8");
+    const updated = original.replace(/^codex_hooks\s*=\s*true\s*\n?/m, "");
+    if (updated !== original) {
+        fs.writeFileSync(configTomlPath, updated);
+    }
+}
+function main() {
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        (0, argus_1.printSetupHelp)("ory-codex-setup", "Codex", {
+            supportsGlobal: true,
+            globalPath: "~/.codex/hooks.json",
+        });
+        process.exit(0);
+    }
+    const args = (0, argus_1.parseSetupArgs)({ supportsGlobal: true });
+    const hooksConfig = generateHooksConfig();
+    if (args.print) {
+        console.log(JSON.stringify({ hooks: hooksConfig }, null, 2));
+        return;
+    }
+    const codexDir = getCodexDir(args);
+    const hooksPath = path.join(codexDir, "hooks.json");
+    const configTomlPath = path.join(codexDir, "config.toml");
+    const existing = (0, argus_1.readJsonFile)(hooksPath);
+    if (args.uninstall) {
+        if (!fs.existsSync(codexDir)) {
+            console.log("No Codex config directory found. Nothing to uninstall.");
+            return;
+        }
+        let updated = (0, argus_1.removeFlatHooks)(existing, BIN_NAME);
+        updated = (0, argus_1.removeMcpServer)(updated);
+        (0, argus_1.writeJsonFile)(hooksPath, updated);
+        removeCodexHooksFeature(configTomlPath);
+        uninstallOrySkills(codexDir);
+        console.log(`Removed Ory hooks and MCP server from ${hooksPath}`);
+        console.log(`Removed codex_hooks feature flag from ${configTomlPath}`);
+        console.log(`Removed Ory skills from ${path.join(codexDir, "skills")}`);
+        return;
+    }
+    let merged = (0, argus_1.mergeFlatHooks)(existing, hooksConfig, BIN_NAME);
+    merged = (0, argus_1.mergeMcpServer)(merged);
+    (0, argus_1.writeJsonFile)(hooksPath, merged);
+    ensureCodexHooksFeature(configTomlPath);
+    installOrySkills(codexDir);
+    console.log(`Ory hooks and MCP server installed to ${hooksPath}`);
+    console.log(`Enabled [features] codex_hooks = true in ${configTomlPath}`);
+    console.log(`Ory skills installed to ${path.join(codexDir, "skills")}`);
+    if (!args.global) {
+        console.log("  Tip: re-run with --global if Codex only discovers skills from ~/.codex/skills.");
+    }
+    (0, argus_1.printNextSteps)("Codex", "npx ory-codex-setup --uninstall");
+}
+main();

package/dist/handlers.d.ts

@@ -0,0 +1,16 @@
+import { OryAgentClient, ensureUserAuthenticated, ensureAgentIdentity } from "@ory/argus";
+import type { CodexHookInput, CodexHookOutput } from "./types.js";
+export interface HandleHookEventDeps {
+    /** Test injection point for the user auth gate. */
+    authGate?: typeof ensureUserAuthenticated;
+    /** Test injection point for the agent identity gate. */
+    agentGate?: typeof ensureAgentIdentity;
+}
+/**
+ * Route a Codex hook event to the appropriate Ory integration.
+ *
+ * Codex events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
+ * UserPromptSubmit, Stop. Hooks must be enabled via
+ * `[features] codex_hooks = true` in `~/.codex/config.toml`.
+ */
+export declare function handleHookEvent(input: CodexHookInput, client: OryAgentClient, deps?: HandleHookEventDeps): Promise<CodexHookOutput>;

package/dist/handlers.js

@@ -0,0 +1,370 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = handleHookEvent;
+const argus_1 = require("@ory/argus");
+/**
+ * Route a Codex hook event to the appropriate Ory integration.
+ *
+ * Codex events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
+ * UserPromptSubmit, Stop. Hooks must be enabled via
+ * `[features] codex_hooks = true` in `~/.codex/config.toml`.
+ */
+async function handleHookEvent(input, client, deps = {}) {
+    const event = input.hook_event_name;
+    client.logger.debug("hook.received", {
+        event,
+        sessionId: input.session_id,
+        toolName: input.tool_name,
+        turnId: input.turn_id,
+    });
+    // Set trace context so all spans within this hook invocation correlate
+    client.tracer.setContext({
+        traceId: (0, argus_1.deriveTraceId)(input.session_id),
+        sessionId: input.session_id,
+    });
+    try {
+        switch (event) {
+            case "SessionStart":
+                return await handleSessionStart(input, client, deps);
+            case "PreToolUse":
+                return await handlePreToolUse(input, client);
+            case "PostToolUse":
+                return await handlePostToolUse(input, client);
+            case "PermissionRequest":
+                return await handlePermissionRequest(input, client);
+            case "UserPromptSubmit":
+                return await handleUserPromptSubmit(input, client);
+            case "Stop":
+                return await handleStop(input, client);
+            default:
+                client.logger.debug("hook.passthrough", { event });
+                client.tracer.record("hook.passthrough", "skipped", {
+                    attributes: { event },
+                });
+                return {};
+        }
+    }
+    finally {
+        client.tracer.clearContext();
+    }
+}
+// ─── SessionStart ───────────────────────────────────────────────────
+async function handleSessionStart(input, client, deps) {
+    client.logger.info("lifecycle.session_start", {
+        sessionId: input.session_id,
+        model: input.model,
+        cwd: input.cwd,
+    });
+    client.tracer.record("session.start", "ok", {
+        attributes: { model: input.model },
+    });
+    const userGate = deps.authGate ?? argus_1.ensureUserAuthenticated;
+    const decision = await userGate(client, {
+        binName: "ory-codex",
+        harness: "codex",
+        allowBlock: true,
+    });
+    // Resolve the agent identity (machine credentials). Never blocks;
+    // attaches the agent's bearer token to outgoing Ory API calls.
+    const agentGate = deps.agentGate ?? argus_1.ensureAgentIdentity;
+    await agentGate(client, { projectUrl: (0, argus_1.resolveConfig)().projectUrl, harness: "codex" });
+    if (!decision.proceed) {
+        return { decision: "block", reason: decision.reason };
+    }
+    if (decision.mode !== "disabled") {
+        return {};
+    }
+    const resolved = (0, argus_1.resolveConfig)();
+    if (resolved.auditOnly) {
+        client.logger.info("config.audit_only", {
+            message: "Audit-only mode enabled. Auth and permission checks are disabled.",
+        });
+        return {};
+    }
+    if (!resolved.projectUrl) {
+        client.logger.warn("config.not_configured", {
+            message: "Ory plugin is not configured. Auth and permission checks are disabled. " +
+                "Run 'npx ory-codex configure' to connect to an Ory project.",
+        });
+        return {};
+    }
+    // Try session token first, then OAuth2 token
+    const sessionToken = process.env.ORY_SESSION_TOKEN;
+    const oauth2Token = process.env.ORY_OAUTH2_TOKEN;
+    if (sessionToken) {
+        await verifySessionToken(sessionToken, client);
+        return {};
+    }
+    if (oauth2Token) {
+        await verifyOAuth2Token(oauth2Token, client);
+        return {};
+    }
+    client.logger.warn("session.no_credentials", {
+        message: "Neither ORY_SESSION_TOKEN nor ORY_OAUTH2_TOKEN is set. " +
+            "Skipping authentication.",
+    });
+    return {};
+}
+async function verifySessionToken(token, client) {
+    try {
+        const session = await client.verifySession(token);
+        if (!session.active) {
+            client.logger.warn("session.inactive", {
+                message: "Ory session is not active. Re-authenticate to enable auth checks.",
+            });
+        }
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("session.verify_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+async function verifyOAuth2Token(token, client) {
+    try {
+        const tokenInfo = await client.introspectToken(token);
+        if (!tokenInfo.active) {
+            client.logger.warn("oauth2.token_inactive", {
+                message: "Ory OAuth2 token is not active. Obtain a new token to enable auth checks.",
+            });
+            return;
+        }
+        client.logger.info("oauth2.session_authenticated", {
+            clientId: tokenInfo.clientId,
+            subject: tokenInfo.subject,
+            scope: tokenInfo.scope,
+        });
+    }
+    catch (err) {
+        const oryErr = err;
+        client.logger.warn("oauth2.introspect_failed", {
+            code: oryErr.code,
+            message: oryErr.message,
+        });
+    }
+}
+// ─── PreToolUse ─────────────────────────────────────────────────────
+async function handlePreToolUse(input, client) {
+    // No default. Codex always sets `tool_name` to the canonical value
+    // (`Bash`, `apply_patch`, or `mcp__<server>__<tool>`). Defaulting to
+    // `"Bash"` here would silently mislabel apply_patch and MCP calls.
+    const toolName = input.tool_name;
+    if (!toolName) {
+        client.logger.warn("pre_tool_use.missing_tool_name", {
+            sessionId: input.session_id,
+            message: "PreToolUse event missing tool_name; allowing through.",
+        });
+        return {};
+    }
+    client.logger.info("lifecycle.pre_tool_use", {
+        sessionId: input.session_id,
+        toolName,
+        toolInput: input.tool_input,
+    });
+    const inputSummary = (0, argus_1.summarizeToolInput)(toolName, input.tool_input);
+    // In audit-only mode, log the invocation but skip permission checks
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary },
+        });
+        return {};
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    const mcpTool = (0, argus_1.parseMcpToolGeneric)(toolName);
+    try {
+        if (mcpTool) {
+            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
+                subject,
+                spanAttributes: { toolName },
+            });
+            if (!mcpResult.allowed) {
+                client.tracer.record("tool.block", "denied", {
+                    attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary, ...(0, argus_1.alertAttributes)(true) },
+                });
+                return {
+                    decision: "block",
+                    reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
+                };
+            }
+            client.tracer.record("tool.invoke", "ok", {
+                attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary },
+            });
+            return {};
+        }
+        const namespace = resolveNamespace();
+        const result = await client.checkPermission({
+            namespace,
+            object: toolName,
+            relation: "use",
+            ...subject,
+        }, { spanAttributes: { toolName } });
+        if (!result.allowed) {
+            client.tracer.record("tool.block", "denied", {
+                attributes: { toolName, ...inputSummary, allowed: result.allowed, ...(0, argus_1.alertAttributes)(true) },
+            });
+            return {
+                decision: "block",
+                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
+            };
+        }
+        client.tracer.record("tool.invoke", "ok", {
+            attributes: { toolName, ...inputSummary, allowed: result.allowed },
+        });
+        return {};
+    }
+    catch (err) {
+        return handlePermissionError(err, toolName, client);
+    }
+}
+// ─── PostToolUse ────────────────────────────────────────────────────
+async function handlePostToolUse(input, client) {
+    const toolName = input.tool_name;
+    if (!toolName) {
+        client.logger.warn("post_tool_use.missing_tool_name", {
+            sessionId: input.session_id,
+        });
+        return {};
+    }
+    client.logger.info("lifecycle.post_tool_use", {
+        sessionId: input.session_id,
+        toolName,
+        turnId: input.turn_id,
+        toolUseId: input.tool_use_id,
+    });
+    client.tracer.record("tool.complete", "ok", {
+        attributes: {
+            toolName,
+            turnId: input.turn_id,
+            toolUseId: input.tool_use_id,
+            ...(0, argus_1.summarizeToolInput)(toolName, input.tool_input),
+            ...(0, argus_1.summarizeToolOutput)(toolName, input.tool_response),
+        },
+    });
+    return {};
+}
+// ─── PermissionRequest ──────────────────────────────────────────────
+async function handlePermissionRequest(input, client) {
+    const toolName = input.tool_name;
+    if (!toolName) {
+        client.logger.warn("permission_request.missing_tool_name", {
+            sessionId: input.session_id,
+        });
+        return {};
+    }
+    client.logger.info("lifecycle.permission_request", {
+        sessionId: input.session_id,
+        toolName,
+        turnId: input.turn_id,
+    });
+    if ((0, argus_1.resolveConfig)().auditOnly) {
+        return permissionRequestFallback("Audit-only mode — deferring to user");
+    }
+    const subject = (0, argus_1.resolveUserSubject)(client, `session:${input.session_id}`);
+    const subjectId = (0, argus_1.subjectLabel)(subject);
+    const mcpTool = (0, argus_1.parseMcpToolGeneric)(toolName);
+    try {
+        if (mcpTool) {
+            const mcpResult = await (0, argus_1.checkMcpPermission)(client, mcpTool, {
+                subject,
+                spanAttributes: { toolName },
+            });
+            return permissionRequestDecision(mcpResult.allowed ? "allow" : "deny", mcpResult.allowed
+                ? "Ory MCP server permission granted"
+                : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }));
+        }
+        const namespace = resolveNamespace();
+        const result = await client.checkPermission({
+            namespace,
+            object: toolName,
+            relation: "use",
+            ...subject,
+        }, { spanAttributes: { toolName } });
+        return permissionRequestDecision(result.allowed ? "allow" : "deny", result.allowed
+            ? "Ory permission granted"
+            : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }));
+    }
+    catch (err) {
+        const oryErr = err;
+        const reason = oryErr.code === "network_error" || oryErr.code === "rate_limited"
+            ? `Ory unavailable (${oryErr.code}), falling back to user prompt`
+            : `Ory permission check failed: ${oryErr.message}`;
+        return permissionRequestFallback(reason);
+    }
+}
+function permissionRequestDecision(behavior, message) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: { behavior, message },
+        },
+    };
+}
+function permissionRequestFallback(message) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            message,
+        },
+    };
+}
+// ─── UserPromptSubmit ───────────────────────────────────────────────
+async function handleUserPromptSubmit(input, client) {
+    client.logger.info("lifecycle.user_prompt_submit", {
+        sessionId: input.session_id,
+        turnId: input.turn_id,
+        promptLen: input.prompt?.length,
+    });
+    client.tracer.record("user.prompt", "ok", {
+        attributes: {
+            turnId: input.turn_id,
+            promptLen: input.prompt?.length,
+        },
+    });
+    return {};
+}
+// ─── Stop ───────────────────────────────────────────────────────────
+async function handleStop(input, client) {
+    client.logger.info("lifecycle.stop", {
+        sessionId: input.session_id,
+        turnId: input.turn_id,
+        stopHookActive: input.stop_hook_active,
+    });
+    client.tracer.record("turn.stop", "ok", {
+        attributes: {
+            turnId: input.turn_id,
+            stopHookActive: input.stop_hook_active,
+            messageLen: input.last_assistant_message?.length,
+        },
+    });
+    return {};
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+function handlePermissionError(oryErr, toolName, client) {
+    if (oryErr.code === "network_error") {
+        client.logger.warn("permission.network_error", {
+            toolName,
+            message: "Ory unreachable, failing open",
+        });
+        return {};
+    }
+    if (oryErr.code === "rate_limited") {
+        client.logger.warn("permission.rate_limited", {
+            toolName,
+            message: "Ory rate limited, failing open",
+        });
+        return {};
+    }
+    // For other errors, also fail open but log prominently
+    client.logger.error("permission.check.error", {
+        toolName,
+        code: oryErr.code,
+        message: oryErr.message,
+    });
+    return {};
+}

package/dist/hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Codex hook entry point.
+ * This script is invoked by Codex for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action (reason written to stderr)
+ */
+export {};

package/dist/hook.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Codex hook entry point.
+ * This script is invoked by Codex for each hook event.
+ * Input: JSON on stdin
+ * Output: JSON on stdout
+ * Exit code 2 = block the action (reason written to stderr)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const argus_1 = require("@ory/argus");
+const handlers_js_1 = require("./handlers.js");
+/**
+ * Read all of stdin as a string.
+ *
+ * Uses event listeners instead of `for await` so that we don't depend on the
+ * parent process closing stdin (sending EOF). If no EOF arrives, we resolve
+ * after a short idle gap once data has been received.
+ */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let resolved = false;
+        function done() {
+            if (!resolved) {
+                resolved = true;
+                resolve(Buffer.concat(chunks).toString("utf-8"));
+            }
+        }
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(done, 100);
+        });
+        process.stdin.on("end", done);
+        process.stdin.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                reject(err);
+            }
+        });
+        let idleTimer;
+    });
+}
+async function main() {
+    const client = argus_1.OryAgentClient.fromEnv("codex");
+    const raw = await readStdin();
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        client.logger.error("hook.stdin.parse_failed", { raw: raw.slice(0, 200) });
+        await client.tracer.shutdown();
+        process.exit(0); // Don't block on parse errors
+    }
+    const output = await (0, handlers_js_1.handleHookEvent)(input, client);
+    if (output.decision === "block") {
+        // Codex reads the block reason from stderr
+        process.stderr.write(output.reason ?? "Blocked by Ory agent plugin");
+        process.stdout.write(JSON.stringify(output));
+        await client.tracer.shutdown();
+        process.exit(2);
+    }
+    if (output.oryConfigRequired || output.message) {
+        process.stdout.write(JSON.stringify(output));
+    }
+    await client.tracer.shutdown();
+    process.exit(0);
+}
+main().catch((err) => {
+    process.stderr.write(`[ory-agent] fatal: ${err}\n`);
+    process.exit(0); // Fail open
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { handleHookEvent } from "./handlers.js";
+export { generateSettings } from "./settings.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSettings = exports.handleHookEvent = void 0;
+var handlers_js_1 = require("./handlers.js");
+Object.defineProperty(exports, "handleHookEvent", { enumerable: true, get: function () { return handlers_js_1.handleHookEvent; } });
+var settings_js_1 = require("./settings.js");
+Object.defineProperty(exports, "generateSettings", { enumerable: true, get: function () { return settings_js_1.generateSettings; } });

package/dist/settings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generate the hooks config that configures Ory hooks for Codex.
+ *
+ * Codex supports two hook events:
+ *   - SessionStart: fired when the agent session begins
+ *   - PreToolUse:   fired before each tool call (Bash only)
+ */
+export declare function generateSettings(hookScriptPath: string): object;
+/**
+ * Generate settings assuming the plugin is installed via npm/pnpm.
+ */
+export declare function generateInstalledSettings(): object;
+/**
+ * Generate settings pointing to a local dev build.
+ */
+export declare function generateDevSettings(packageDir: string): object;

package/dist/settings.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSettings = generateSettings;
+exports.generateInstalledSettings = generateInstalledSettings;
+exports.generateDevSettings = generateDevSettings;
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+/**
+ * Generate the hooks config that configures Ory hooks for Codex.
+ *
+ * Codex supports two hook events:
+ *   - SessionStart: fired when the agent session begins
+ *   - PreToolUse:   fired before each tool call (Bash only)
+ */
+function generateSettings(hookScriptPath) {
+    const cmd = `node ${hookScriptPath}`;
+    return {
+        hooks: {
+            SessionStart: (0, argus_1.flatHookEntry)(cmd),
+            PreToolUse: (0, argus_1.flatHookEntry)(cmd),
+        },
+    };
+}
+/**
+ * Generate settings assuming the plugin is installed via npm/pnpm.
+ */
+function generateInstalledSettings() {
+    return generateSettings("ory-codex-hook");
+}
+/**
+ * Generate settings pointing to a local dev build.
+ */
+function generateDevSettings(packageDir) {
+    const hookPath = path.resolve(packageDir, "dist", "hook.js");
+    return generateSettings(hookPath);
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Codex hook event payload delivered on stdin.
+ *
+ * Codex uses a subprocess hook model (JSON stdin/stdout). Hooks are
+ * feature-gated behind `[features] codex_hooks = true` in config.toml.
+ *
+ * Canonical `tool_name` values:
+ *   - `"Bash"`
+ *   - `"apply_patch"` — canonical name for file edits. `Write`/`Edit` are
+ *     matcher aliases only; the serialized name is always `apply_patch`.
+ *   - `"mcp__<server>__<tool>"` for MCP tools.
+ *
+ * Supported events: SessionStart, PreToolUse, PostToolUse, PermissionRequest,
+ * UserPromptSubmit, Stop.
+ */
+export interface CodexHookInput {
+    hook_event_name: string;
+    session_id: string;
+    cwd: string;
+    transcript_path?: string;
+    turn_id?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_use_id?: string;
+    tool_response?: Record<string, unknown>;
+    source?: "startup" | "resume" | "clear";
+    model?: string;
+    permission_mode?: "default" | "acceptEdits" | "plan" | "dontAsk" | "bypassPermissions";
+    prompt?: string;
+    last_assistant_message?: string;
+    stop_hook_active?: boolean;
+}
+/**
+ * Codex hook output written to stdout.
+ *
+ * Allow is implicit (omit `decision`); only `"block"` is valid at the top
+ * level. PermissionRequest uses the structured `hookSpecificOutput.decision`
+ * shape — its top-level `decision` field is ignored.
+ *
+ * `additionalContext` is supported on SessionStart and UserPromptSubmit.
+ */
+export interface CodexHookOutput {
+    continue?: boolean;
+    decision?: "block";
+    reason?: string;
+    systemMessage?: string;
+    suppressOutput?: boolean;
+    stopReason?: string;
+    hookSpecificOutput?: CodexHookSpecificOutput;
+    /** Set when the plugin needs the agent to prompt the user for config. */
+    oryConfigRequired?: boolean;
+    message?: string;
+}
+export interface CodexHookSpecificOutput {
+    hookEventName?: string;
+    permissionDecision?: "allow" | "deny" | "ask";
+    permissionDecisionReason?: string;
+    decision?: {
+        behavior: "allow" | "deny";
+        message?: string;
+    };
+    additionalContext?: string;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@ory/codex",
+  "version": "0.1.0",
+  "description": "Ory plugin for Codex: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
+  "license": "Apache-2.0",
+  "homepage": "https://ory.com",
+  "keywords": [
+    "ory",
+    "codex",
+    "openai",
+    "hooks",
+    "plugin",
+    "identity",
+    "identity-management",
+    "iam",
+    "authentication",
+    "authorization",
+    "access-control",
+    "permissions",
+    "rbac",
+    "zanzibar",
+    "oauth",
+    "oauth2",
+    "openid-connect",
+    "oidc",
+    "session",
+    "mfa",
+    "sso",
+    "audit",
+    "audit-log",
+    "compliance",
+    "agent",
+    "ai-agent",
+    "agent-security",
+    "guardrails",
+    "llm",
+    "tracing",
+    "distributed-tracing",
+    "observability",
+    "kratos",
+    "keto",
+    "hydra"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "codex": "dist/cli/main.js",
+    "ory-codex": "dist/cli/main.js",
+    "ory-codex-hook": "dist/hook.js",
+    "ory-codex-setup": "dist/cli/setup.js"
+  },
+  "files": [
+    "dist",
+    "!dist/dev",
+    "!dist/**/*.tsbuildinfo",
+    ".codex-plugin"
+  ],
+  "dependencies": {
+    "@ory/argus": "0.1.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "dev": "node dist/dev/launcher.js"
+  }
+}