@rse/ase 0.9.10 → 0.9.12

package/dst/ase-compat.js

@@ -0,0 +1,68 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+/*  the canonical expected values for every ase-meta-compat probe,
+    keyed by "<category>/<probe-name>" as used in the skill  */
+const EXPECTED = {
+    /*  xml-placeholders  */
+    "xml-placeholders/get-and-set": "42",
+    "xml-placeholders/self-ref": "pre_42",
+    "xml-placeholders/overwrite": "99",
+    "xml-placeholders/indexed": "+1,-1",
+    "xml-placeholders/nested-attr": "20",
+    "xml-placeholders/entity": "○",
+    /*  control-flow  */
+    "control-flow/branch": "mid",
+    "control-flow/while-sum": "15",
+    "control-flow/for-order": "-x-y-z",
+    "control-flow/while-break": "4",
+    "control-flow/step-skip": "X",
+    "control-flow/expand-subst": "[K:V]",
+    /*  regex  */
+    "regex/getopt-dash": "yes",
+    "regex/getopt-nodash": "no",
+    "regex/anchored-int": "yes,no",
+    "regex/alternation": "yes",
+    "regex/capture": "foo",
+    "regex/whitespace": "yes",
+    "regex/complex": "yes",
+    /*  arithmetic  */
+    "arithmetic/increment": "9",
+    "arithmetic/product-sum": "5.00",
+    "arithmetic/percentage": "0.43",
+    "arithmetic/bar-width": "54",
+    "arithmetic/threshold": "yes",
+    "arithmetic/round-half": "3"
+};
+/*  format the expected values as "<id>: <value>\n" lines  */
+const formatExpected = () => Object.entries(EXPECTED).map(([id, value]) => `${id}: ${value}`).join("\n") + "\n";
+/*  CLI command "ase compat"  */
+export default class CompatCommand {
+    register(program) {
+        program
+            .command("compat")
+            .description("Output expected probe values for the ase-meta-compat self-test skill")
+            .action(() => {
+            process.stdout.write(formatExpected());
+        });
+    }
+}
+/*  MCP tool "ase_compat" — lets the skill call this without a Bash tool  */
+export class CompatMCP {
+    register(mcp) {
+        mcp.registerTool("ase_compat", {
+            title: "ASE compat expected values",
+            description: "Return the canonical expected probe values for the ase-meta-compat " +
+                "self-test skill as \"<id>: <value>\" lines, one per probe. " +
+                "Call this AFTER recording all actual probe results so the LLM " +
+                "cannot see the expected values before running the probes.",
+            inputSchema: {}
+        }, async () => {
+            return {
+                content: [{ type: "text", text: formatExpected() }]
+            };
+        });
+    }
+}

package/dst/ase-hook.js

@@ -8,6 +8,7 @@ import fs from "node:fs";
 import os from "node:os";
 import { execaSync } from "execa";
 import { quote } from "shell-quote";
+import getStdin from "get-stdin";
 import * as v from "valibot";
 import Version from "./ase-version.js";
 import { Config, configSchema, parseScope } from "./ase-config.js";
@@ -41,7 +42,8 @@ const toolSpecs = {
         mcpToolNamePattern: /^mcp__plugin_ase_ase__.+/,
         addonMcpToolNamePattern: addonMcpToolNamePattern("mcp__", "__.+"),
         preToolUseWrapped: true,
-        preToolUseEvent: "PreToolUse"
+        preToolUseEvent: "PreToolUse",
+        approvalEvent: "PreToolUse"
     },
     "copilot": {
         toolNameField: "toolName",
@@ -51,7 +53,19 @@ const toolSpecs = {
         mcpToolNamePattern: /^ase-.+/,
         addonMcpToolNamePattern: addonMcpToolNamePattern("", "-.+"),
         preToolUseWrapped: false,
-        preToolUseEvent: "preToolUse"
+        preToolUseEvent: "preToolUse",
+        approvalEvent: "PreToolUse"
+    },
+    "codex": {
+        toolNameField: "tool_name",
+        toolInputField: "tool_input",
+        toolInputIsString: false,
+        bashToolName: "Bash",
+        mcpToolNamePattern: /^mcp__ase__.+/,
+        addonMcpToolNamePattern: addonMcpToolNamePattern("mcp__", "__.+"),
+        preToolUseWrapped: true,
+        preToolUseEvent: "PreToolUse",
+        approvalEvent: "PermissionRequest"
     }
 };
 /*  CLI command "ase hook"  */
@@ -64,6 +78,27 @@ export default class HookCommand {
     isValidSessionId(id) {
         return /^[A-Za-z0-9._-]+$/.test(id);
     }
+    /*  read the entire stdin payload asynchronously  */
+    readStdin() {
+        /*  best-effort: treat an unreadable/closed stdin as empty  */
+        return getStdin().catch(() => "");
+    }
+    /*  drain and discard the stdin event payload  */
+    async drainStdin() {
+        await this.readStdin();
+    }
+    /*  write to stdout and resolve only once it has been fully
+        flushed to the underlying file descriptor  */
+    writeStdout(text) {
+        return new Promise((resolve, reject) => {
+            process.stdout.write(text, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
     /*  best-effort JSON parse with valibot schema validation: returns
         an empty object on blank input, malformed JSON, or schema
         mismatch, so callers can treat the result uniformly. Extra
@@ -110,13 +145,24 @@ export default class HookCommand {
             return this.expandReferences(content, path.dirname(abs), next);
         });
     }
-    /*  handler for "ase hook session-start" (both tools)  */
+    /*  handler for "ase hook session-start" (all tools)  */
     async doSessionStart(tool) {
         /*  determine plugin root (env var name differs per tool)  */
-        const pluginRootVar = tool === "copilot" ? "COPILOT_PLUGIN_ROOT" : "CLAUDE_PLUGIN_ROOT";
-        const pluginRoot = process.env[pluginRootVar] ?? "";
+        let pluginRootVars;
+        if (tool === "copilot")
+            pluginRootVars = ["COPILOT_PLUGIN_ROOT"];
+        else if (tool === "codex")
+            pluginRootVars = ["PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
+        else
+            pluginRootVars = ["CLAUDE_PLUGIN_ROOT"];
+        let pluginRoot = "";
+        for (const pluginRootVar of pluginRootVars)
+            if ((process.env[pluginRootVar] ?? "") !== "") {
+                pluginRoot = process.env[pluginRootVar];
+                break;
+            }
         if (pluginRoot === "")
-            throw new Error(`${pluginRootVar} environment variable is not set`);
+            throw new Error(`${pluginRootVars.join("/")} environment variable is not set`);
         /*  determine path to external files  */
         const filePkg = path.join(pluginRoot, ".claude-plugin", "plugin.json");
         const fileMd = path.join(pluginRoot, "meta", "ase-constitution.md");
@@ -152,7 +198,7 @@ export default class HookCommand {
         const versionHint = versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
         /*  read session information (Claude Code uses snake_case fields,
             Copilot CLI uses camelCase fields)  */
-        const stdin = fs.readFileSync(0, "utf8");
+        const stdin = await this.readStdin();
         const input = this.parseJSON(stdin, v.object({
             session_id: v.optional(v.string()),
             sessionId: v.optional(v.string()),
@@ -228,9 +274,10 @@ export default class HookCommand {
         /*  expand all @<file> references manually  */
         md = this.expandReferences(md, path.dirname(fileMd));
         /*  inject markdown into session context.
-            Claude Code expects the context nested in "hookSpecificOutput";
-            Copilot CLI expects a flat top-level "additionalContext" field.  */
-        const payload = tool === "claude" ? {
+            Claude Code and OpenAI Codex CLI expect the context nested in
+            "hookSpecificOutput"; Copilot CLI expects a flat top-level
+            "additionalContext" field.  */
+        const payload = tool !== "copilot" ? {
             "hookSpecificOutput": {
                 "hookEventName": "SessionStart",
                 "additionalContext": md
@@ -238,7 +285,7 @@ export default class HookCommand {
         } : {
             "additionalContext": md
         };
-        process.stdout.write(JSON.stringify(payload));
+        await this.writeStdout(JSON.stringify(payload));
         return 0;
     }
     /*  publish the agent activity marker to tmux as a per-pane user
@@ -258,19 +305,21 @@ export default class HookCommand {
         }
     }
     /*  handler for "ase hook user-prompt-submit" (both tools)  */
-    doUserPromptSubmit(_tool) {
+    async doUserPromptSubmit(_tool) {
+        await this.drainStdin();
         this.writeAgentStatus("busy");
         return 0;
     }
     /*  handler for "ase hook stop" (both tools)  */
-    doStop(_tool) {
+    async doStop(_tool) {
+        await this.drainStdin();
         this.writeAgentStatus("ready");
         return 0;
     }
     /*  handler for "ase hook session-end" (both tools)  */
-    doSessionEnd(_tool) {
+    async doSessionEnd(_tool) {
         /*  determine session id  */
-        const sessionId = this.readSessionIdFromStdin();
+        const sessionId = await this.readSessionIdFromStdin();
         /*  remove the session directory ~/.ase/session/<id> (only for a valid sessionId)  */
         if (this.isValidSessionId(sessionId)) {
             const dir = path.join(os.homedir(), ".ase", "session", sessionId);
@@ -289,8 +338,8 @@ export default class HookCommand {
         return input.session_id ?? input.sessionId ?? "";
     }
     /*  read session id from stdin JSON payload  */
-    readSessionIdFromStdin() {
-        const stdin = fs.readFileSync(0, "utf8");
+    async readSessionIdFromStdin() {
+        const stdin = await this.readStdin();
         const input = this.parseJSON(stdin, v.object({
             session_id: v.optional(v.string()),
             sessionId: v.optional(v.string())
@@ -319,17 +368,12 @@ export default class HookCommand {
     /*  the edit-capable skills whose active state lets the pre-tool-use
         hook auto-approve subsequent "Edit" invocations  */
     editCapableSkills = ["ase-code-lint", "ase-docs-proofread"];
-    /*  handler for "ase hook pre-tool-use" (both tools)  */
-    doPreToolUse(tool) {
-        const spec = toolSpecs[tool];
-        /*  read tool invocation information  */
-        const stdin = fs.readFileSync(0, "utf8");
-        const input = this.parseJSON(stdin, v.looseObject({
-            session_id: v.optional(v.string()),
-            sessionId: v.optional(v.string())
-        }));
-        /*  determine whether to auto-approve the tool invocation
-            (field names and value shapes differ between tools)  */
+    /*  determine whether an ASE tool invocation described by the parsed
+        hook input should be auto-approved, and (if so) the human-readable
+        reason. The input field names and value shapes differ between
+        tools, but the decision logic is shared by the "pre-tool-use" and
+        "permission-request" handlers.  */
+    decideApproval(spec, input) {
         const toolName = typeof input[spec.toolNameField] === "string" ?
             input[spec.toolNameField] : "";
         let toolInput = {};
@@ -341,32 +385,43 @@ export default class HookCommand {
             }));
         else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null)
             toolInput = rawInput;
-        let approve = false;
-        let reason = "";
-        if (toolName === spec.bashToolName && /^ase(\s|$)/.test(toolInput.command ?? "")) {
-            approve = true;
-            reason = "ASE CLI invocation auto-approved";
-        }
-        else if (toolName === "Skill" && /^(?:ase:)?ase-.+/.test(toolInput.skill ?? "")) {
-            approve = true;
-            reason = "ASE skill invocation auto-approved";
-        }
-        else if (spec.mcpToolNamePattern.test(toolName)) {
-            approve = true;
-            reason = "ASE MCP tool invocation auto-approved";
-        }
-        else if (spec.addonMcpToolNamePattern.test(toolName)) {
-            approve = true;
-            reason = "ASE addon MCP tool invocation auto-approved";
-        }
+        if (toolName === spec.bashToolName && /^ase(\s|$)/.test(toolInput.command ?? ""))
+            return { approve: true, reason: "ASE CLI invocation auto-approved" };
+        else if (toolName === "Skill" && /^(?:ase:)?ase-.+/.test(toolInput.skill ?? ""))
+            return { approve: true, reason: "ASE skill invocation auto-approved" };
+        else if (spec.mcpToolNamePattern.test(toolName))
+            return { approve: true, reason: "ASE MCP tool invocation auto-approved" };
+        else if (spec.addonMcpToolNamePattern.test(toolName))
+            return { approve: true, reason: "ASE addon MCP tool invocation auto-approved" };
         else if (toolName === "Edit") {
             const sessionId = this.pickSessionId(input);
             const activeSkill = this.readActiveSkill(sessionId);
-            if (this.editCapableSkills.includes(activeSkill)) {
-                approve = true;
-                reason = `${activeSkill}: edit auto-approved for active edit-capable skill`;
-            }
+            if (this.editCapableSkills.includes(activeSkill))
+                return { approve: true, reason: `${activeSkill}: edit auto-approved for active edit-capable skill` };
         }
+        return { approve: false, reason: "" };
+    }
+    /*  handler for "ase hook pre-tool-use" (all tools).
+        For Claude Code and Copilot CLI this is where ASE tool
+        invocations are auto-approved (via "permissionDecision: allow").
+        OpenAI Codex CLI rejects that mechanism in "PreToolUse", so for
+        Codex this handler stays silent and approval is granted in the
+        separate "permission-request" handler instead -- the handler must
+        still drain stdin, as Codex treats a non-draining hook as a hard
+        error.  */
+    async doPreToolUse(tool) {
+        const spec = toolSpecs[tool];
+        /*  read tool invocation information  */
+        const stdin = await this.readStdin();
+        const input = this.parseJSON(stdin, v.looseObject({
+            session_id: v.optional(v.string()),
+            sessionId: v.optional(v.string())
+        }));
+        /*  Codex auto-approves through "PermissionRequest", not here  */
+        if (spec.approvalEvent !== "PreToolUse")
+            return 0;
+        /*  determine whether to auto-approve the tool invocation  */
+        const { approve, reason } = this.decideApproval(spec, input);
         /*  emit permission decision (or stay silent to defer to default flow).
             Claude Code expects the decision nested in "hookSpecificOutput";
             Copilot CLI expects flat top-level fields.  */
@@ -381,14 +436,42 @@ export default class HookCommand {
                 "permissionDecision": "allow",
                 "permissionDecisionReason": reason
             };
-            process.stdout.write(JSON.stringify(payload));
+            await this.writeStdout(JSON.stringify(payload));
+        }
+        return 0;
+    }
+    /*  handler for "ase hook permission-request" (OpenAI Codex CLI only).
+        Codex fires this event only when a tool invocation would otherwise
+        require interactive user approval, and -- unlike "PreToolUse" --
+        honors an auto-approval here through "decision.behavior: allow".
+        Staying silent (or returning a non-approval) defers to Codex's
+        normal approval flow.  */
+    async doPermissionRequest(tool) {
+        const spec = toolSpecs[tool];
+        /*  read tool invocation information  */
+        const stdin = await this.readStdin();
+        const input = this.parseJSON(stdin, v.looseObject({
+            session_id: v.optional(v.string()),
+            sessionId: v.optional(v.string())
+        }));
+        /*  determine whether to auto-approve the tool invocation  */
+        const { approve } = this.decideApproval(spec, input);
+        /*  emit the Codex "PermissionRequest" approval decision  */
+        if (approve) {
+            const payload = {
+                "hookSpecificOutput": {
+                    "hookEventName": "PermissionRequest",
+                    "decision": { "behavior": "allow" }
+                }
+            };
+            await this.writeStdout(JSON.stringify(payload));
         }
         return 0;
     }
     /*  parse and validate the --tool option  */
     parseTool(value) {
-        if (value !== "claude" && value !== "copilot")
-            throw new Error(`invalid --tool value: "${value}" (expected "claude" or "copilot")`);
+        if (value !== "claude" && value !== "copilot" && value !== "codex")
+            throw new Error(`invalid --tool value: "${value}" (expected "claude", "copilot", or "codex")`);
         return value;
     }
     /*  register commands  */
@@ -408,41 +491,49 @@ export default class HookCommand {
         hookCmd
             .command("session-start")
             .description("handle SessionStart hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (opts) => {
-            process.exit(await this.doSessionStart(this.parseTool(opts.tool)));
+            process.exitCode = await this.doSessionStart(this.parseTool(opts.tool));
         });
         /*  register CLI sub-command "ase hook session-end"  */
         hookCmd
             .command("session-end")
             .description("handle SessionEnd hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
-            .action((opts) => {
-            process.exit(this.doSessionEnd(this.parseTool(opts.tool)));
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exitCode = await this.doSessionEnd(this.parseTool(opts.tool));
         });
         /*  register CLI sub-command "ase hook pre-tool-use"  */
         hookCmd
             .command("pre-tool-use")
             .description("handle tool PreToolUse hook event")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
-            .action((opts) => {
-            process.exit(this.doPreToolUse(this.parseTool(opts.tool)));
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exitCode = await this.doPreToolUse(this.parseTool(opts.tool));
+        });
+        /*  register CLI sub-command "ase hook permission-request"  */
+        hookCmd
+            .command("permission-request")
+            .description("handle tool PermissionRequest hook event (Codex CLI)")
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exitCode = await this.doPermissionRequest(this.parseTool(opts.tool));
         });
         /*  register CLI sub-command "ase hook user-prompt-submit"  */
         hookCmd
             .command("user-prompt-submit")
             .description("handle UserPromptSubmit hook event (mark agent as busy)")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
-            .action((opts) => {
-            process.exit(this.doUserPromptSubmit(this.parseTool(opts.tool)));
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exitCode = await this.doUserPromptSubmit(this.parseTool(opts.tool));
         });
         /*  register CLI sub-command "ase hook stop"  */
         hookCmd
             .command("stop")
             .description("handle Stop hook event (mark agent as ready)")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
-            .action((opts) => {
-            process.exit(this.doStop(this.parseTool(opts.tool)));
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
+            .action(async (opts) => {
+            process.exitCode = await this.doStop(this.parseTool(opts.tool));
         });
     }
 }

package/dst/ase-service.js

@@ -16,6 +16,7 @@ import * as v from "valibot";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Config, configSchema, ConfigMCP } from "./ase-config.js";
+import { CompatMCP } from "./ase-compat.js";
 import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
 import { MarkdownMCP } from "./ase-markdown.js";
@@ -236,6 +237,7 @@ export default class ServiceCommand {
         const buildMcpServer = () => {
             const mcp = new McpServer({ name: "ase", version: pkg.version });
             new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
+            new CompatMCP().register(mcp);
             new DiagramMCP().register(mcp);
             new TaskMCP(this.log).register(mcp);
             new MarkdownMCP().register(mcp);

package/dst/ase-setup.js

@@ -13,8 +13,9 @@ import Table from "cli-table3";
 import chalk from "chalk";
 import Version from "./ase-version.js";
 const toolSpecs = {
-    "claude": { cli: "claude", label: "Claude Code" },
-    "copilot": { cli: "copilot", label: "Copilot CLI" }
+    "claude": { cli: "claude", label: "Claude Code", pInstall: "install", pRemove: "uninstall", pUpdate: "update" },
+    "copilot": { cli: "copilot", label: "Copilot CLI", pInstall: "install", pRemove: "uninstall", pUpdate: "update" },
+    "codex": { cli: "codex", label: "OpenAI Codex CLI", pInstall: "add", pRemove: "remove", pUpdate: "upgrade" }
 };
 /*  CLI command "ase setup"  */
 export default class SetupCommand {
@@ -162,7 +163,7 @@ export default class SetupCommand {
         const pkgdir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
         const source = dev ? path.resolve(pkgdir, "..") : pkgdir;
         await this.run(spec.cli, ["plugin", "marketplace", "add", source]);
-        await this.run(spec.cli, ["plugin", "install", "ase@ase"], { retries: 3 });
+        await this.run(spec.cli, ["plugin", spec.pInstall, "ase@ase"], { retries: 3 });
         return 0;
     }
     /*  handler for "ase setup update" (both tools)  */
@@ -185,8 +186,8 @@ export default class SetupCommand {
                 but there is no version change in the plugin manifest,
                 so just re-install the plugin to let the tool update its copy  */
             this.log.write("info", `setup: update[dev]: re-install ASE ${spec.label} plugin (origin: local)`);
-            await this.run(spec.cli, ["plugin", "uninstall", "ase@ase"], { ignoreError: `ASE ${spec.label} plugin not installed` });
-            await this.run(spec.cli, ["plugin", "install", "ase@ase"], { retries: 3 });
+            await this.run(spec.cli, ["plugin", spec.pRemove, "ase@ase"], { ignoreError: `ASE ${spec.label} plugin not installed` });
+            await this.run(spec.cli, ["plugin", spec.pInstall, "ase@ase"], { retries: 3 });
         }
         else {
             /*  perform NPM version check  */
@@ -201,10 +202,17 @@ export default class SetupCommand {
             this.log.write("info", `setup: update: updating ASE CLI tool: ${current} -> ${latest}`);
             const updateCmd = await this.npmCmd(["update", "-g", "@rse/ase"], true);
             await this.run(updateCmd.cmd, updateCmd.args);
-            /*  update ASE plugin  */
+            /*  update ASE plugin (refresh the marketplace snapshot, then
+                update the plugin itself; the OpenAI Codex CLI has no
+                "plugin update" subcommand, so re-install it instead)  */
             this.log.write("info", `setup: update: updating ASE ${spec.label} plugin`);
-            await this.run(spec.cli, ["plugin", "marketplace", "update", "ase"]);
-            await this.run(spec.cli, ["plugin", "update", "ase@ase"]);
+            await this.run(spec.cli, ["plugin", "marketplace", spec.pUpdate, "ase"]);
+            if (tool !== "codex")
+                await this.run(spec.cli, ["plugin", "update", "ase@ase"]);
+            else {
+                await this.run(spec.cli, ["plugin", spec.pRemove, "ase@ase"], { ignoreError: `ASE ${spec.label} plugin not installed` });
+                await this.run(spec.cli, ["plugin", spec.pInstall, "ase@ase"], { retries: 3 });
+            }
         }
         return 0;
     }
@@ -213,9 +221,11 @@ export default class SetupCommand {
         const spec = toolSpecs[tool];
         await this.ensureTool(spec.cli);
         this.log.write("info", `setup: enable: enabling ASE ${spec.label} plugin`);
+        /*  the GitHub Copilot CLI and OpenAI Codex CLI have no "plugin
+            enable" subcommand, so (re-)install the plugin instead  */
         const args = tool === "claude" ?
             ["plugin", "enable", "ase@ase"] :
-            ["plugin", "install", "ase@ase"];
+            ["plugin", spec.pInstall, "ase@ase"];
         await this.run(spec.cli, args, { retries: tool === "claude" ? 1 : 3 });
         return 0;
     }
@@ -224,9 +234,11 @@ export default class SetupCommand {
         const spec = toolSpecs[tool];
         await this.ensureTool(spec.cli);
         this.log.write("info", `setup: disable: disabling ASE ${spec.label} plugin`);
+        /*  the GitHub Copilot CLI and OpenAI Codex CLI have no "plugin
+            disable" subcommand, so uninstall the plugin instead  */
         const args = tool === "claude" ?
             ["plugin", "disable", "ase@ase"] :
-            ["plugin", "uninstall", "ase@ase"];
+            ["plugin", spec.pRemove, "ase@ase"];
         await this.run(spec.cli, args, { retries: tool === "claude" ? 1 : 3 });
         return 0;
     }
@@ -242,7 +254,7 @@ export default class SetupCommand {
         /*  uninstall ASE plugin  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             `uninstalling ASE ${spec.label} plugin (origin: ${dev ? "local" : "remote/bundled"})`);
-        await this.run(spec.cli, ["plugin", "uninstall", "ase@ase"], { ignoreError: `ASE ${spec.label} plugin not installed` });
+        await this.run(spec.cli, ["plugin", spec.pRemove, "ase@ase"], { ignoreError: `ASE ${spec.label} plugin not installed` });
         await this.run(spec.cli, ["plugin", "marketplace", "remove", "ase"], { ignoreError: `ASE ${spec.label} plugin marketplace not registered` });
         /*  uninstall ASE CLI tool (non-development only)  */
         if (!dev) {
@@ -349,7 +361,7 @@ export default class SetupCommand {
     /*  register an MCP server with the tool, supporting both the "stdio"
         (a local subprocess command) and "http" (a remote URL, optionally
         with HTTP headers) transports; the per-tool command line differs
-        between Claude Code and GitHub Copilot CLI  */
+        between Claude Code, GitHub Copilot CLI, and OpenAI Codex CLI  */
     async mcpAdd(tool, name, env, transport) {
         const args = ["mcp", "add"];
         if (tool === "claude") {
@@ -366,7 +378,7 @@ export default class SetupCommand {
                 args.push(name, transport.url);
             }
         }
-        else {
+        else if (tool === "copilot") {
             /*  GitHub Copilot CLI implies the stdio transport when the
                 command is provided after "--"; only "http"/"sse" servers
                 need an explicit "--transport" flag and take the URL as a
@@ -384,10 +396,27 @@ export default class SetupCommand {
                 args.push(name, transport.url);
             }
         }
+        else {
+            /*  OpenAI Codex CLI takes the server name as the first
+                positional argument and implies the stdio transport when the
+                command is provided after "--"; "http" servers take the URL
+                via the "--url" option (with optional "--header" flags)  */
+            if (transport.type === "stdio") {
+                args.push(name);
+                for (const [key, val] of Object.entries(env))
+                    args.push("--env", `${key}=${val}`);
+                args.push("--", ...transport.command);
+            }
+            else {
+                for (const [key, val] of Object.entries(transport.headers ?? {}))
+                    args.push("--header", `${key}: ${val}`);
+                args.push(name, "--url", transport.url);
+            }
+        }
         await this.run(toolSpecs[tool].cli, args);
     }
     /*  unregister an MCP server from the tool; the per-tool command line
-        differs between Claude Code and GitHub Copilot CLI  */
+        differs between Claude Code, GitHub Copilot CLI, and OpenAI Codex CLI  */
     async mcpRemove(tool, name) {
         const args = tool === "claude" ?
             ["mcp", "remove", "--scope", "user", name] :
@@ -527,8 +556,8 @@ export default class SetupCommand {
     ];
     /*  parse and validate the --tool option  */
     parseTool(value) {
-        if (value !== "claude" && value !== "copilot")
-            throw new Error(`invalid --tool value: "${value}" (expected "claude" or "copilot")`);
+        if (value !== "claude" && value !== "copilot" && value !== "codex")
+            throw new Error(`invalid --tool value: "${value}" (expected "claude", "copilot", or "codex")`);
         return value;
     }
     /*  register commands  */
@@ -551,7 +580,7 @@ export default class SetupCommand {
         setupCmd
             .command("install")
             .description("install the ASE plugin for a tool")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .option("-d, --dev", "use local working copy instead of remote/bundled repository", devDflt)
             .action(async (opts) => {
             process.exit(await this.doInstall(this.parseTool(opts.tool), opts.dev));
@@ -560,7 +589,7 @@ export default class SetupCommand {
         setupCmd
             .command("update")
             .description("update the ASE tool and the ASE plugin for a tool")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .option("-f, --force", "always perform the update, even if already at latest version", false)
             .option("-d, --dev", "use local working copy instead of remote/bundled repository", devDflt)
             .action(async (opts) => {
@@ -570,7 +599,7 @@ export default class SetupCommand {
         setupCmd
             .command("uninstall")
             .description("uninstall the ASE plugin for a tool and the ASE tool")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .option("-d, --dev", "use local working copy instead of remote/bundled repository", devDflt)
             .action(async (opts) => {
             process.exit(await this.doUninstall(this.parseTool(opts.tool), opts.dev));
@@ -579,7 +608,7 @@ export default class SetupCommand {
         setupCmd
             .command("enable")
             .description("enable the ASE plugin for a tool")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (opts) => {
             process.exit(await this.doEnable(this.parseTool(opts.tool)));
         });
@@ -587,7 +616,7 @@ export default class SetupCommand {
         setupCmd
             .command("disable")
             .description("disable the ASE plugin for a tool")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (opts) => {
             process.exit(await this.doDisable(this.parseTool(opts.tool)));
         });
@@ -610,7 +639,7 @@ export default class SetupCommand {
         mcpCmd
             .command("activate [servers]")
             .description("activate pre-defined MCP servers (comma-separated list, or \"all\")")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (servers, opts) => {
             process.exit(await this.doMcp("activate", this.parseTool(opts.tool), servers ?? "all"));
         });
@@ -618,7 +647,7 @@ export default class SetupCommand {
         mcpCmd
             .command("deactivate [servers]")
             .description("deactivate pre-defined MCP servers (comma-separated list, or \"all\")")
-            .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\")", toolDflt)
+            .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
             .action(async (servers, opts) => {
             process.exit(await this.doMcp("deactivate", this.parseTool(opts.tool), servers ?? "all"));
         });