@rse/ase 0.9.11 → 0.9.13

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-diagram.js

@@ -117,12 +117,15 @@ export class Diagram {
     /*  detect terminal color capability  */
     static detectColorMode() {
         let mode = "none";
+        let explicit = false;
         /*  attempt 1: query environment variable (explicitly)  */
         if (process.env.ASE_TERM_COLORS !== undefined)
-            if (/^(?:none|ansi16|ansi256)$/.test(process.env.ASE_TERM_COLORS))
+            if (/^(?:none|ansi16|ansi256)$/.test(process.env.ASE_TERM_COLORS)) {
                 mode = process.env.ASE_TERM_COLORS;
+                explicit = true;
+            }
         /*  attempt 2: query stdout  */
-        if (mode === "none" && process.stdout.isTTY) {
+        if (!explicit && process.stdout.isTTY) {
             const depth = process.stdout.getColorDepth();
             if (depth >= 8)
                 mode = "ansi256";

package/dst/ase-getopt.js

@@ -108,7 +108,8 @@ export class GetoptMCP {
                 if (listOpts.length > 0) {
                     const opts = cmd.opts();
                     for (const { long, choices } of listOpts) {
-                        const v = opts[long];
+                        const key = long.replace(/-(.)/g, (_, c) => c.toUpperCase());
+                        const v = opts[key];
                         if (typeof v !== "string")
                             continue;
                         const items = v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);

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-mcp.js

@@ -133,6 +133,8 @@ export default class MCPCommand {
         };
         /*  trigger a reconnect chain (idempotent while one is active)  */
         const triggerReconnect = (reason) => {
+            if (reconnecting)
+                return;
             reconnecting = true;
             this.log.write("warning", `mcp: ${reason} — reconnecting`);
             reconnect(0).catch(() => { });

package/dst/ase-persona.js

@@ -21,7 +21,10 @@ export class Persona {
         const val = cfg.get("agent.persona");
         if (val === undefined)
             return "engineer";
-        return String(isScalar(val) ? val.value : val);
+        const style = String(isScalar(val) ? val.value : val);
+        if (!Persona.styles.includes(style))
+            return "engineer";
+        return style;
     }
     /*  set the persona style on the strongest scope of an optional session  */
     static set(log, style, session) {

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);