@rse/ase 0.9.31 → 0.9.32

package/dst/ase-artifact.js

@@ -10,6 +10,7 @@ import { isScalar } from "yaml";
 import { z } from "zod";
 import { Config, configSchema } from "./ase-config.js";
 import { Task } from "./ase-task.js";
+import { writeStdout } from "./ase-stdout.js";
 /*  the recognized artifact kinds, in descending precedence order;
     "othr" is the implicit catch-all and is always resolved last  */
 export const artifactKinds = ["spec", "arch", "code", "docs", "infr", "othr"];
@@ -223,17 +224,16 @@ export default class ArtifactCommand {
             .description("Resolve one or more artifact kinds to project-relative file paths")
             .option("--kind <kinds>", "comma-separated list of artifact kinds " +
             `(${artifactKinds.join("|")})`, artifactKinds.join(","))
-            .action((opts) => {
+            .action(async (opts) => {
             const kinds = opts.kind.split(",").map((k) => Artifact.validateKind(k.trim()));
             const result = Artifact.list(this.log, kinds);
             const single = result.length === 1;
             for (const { kind, files } of result) {
                 if (!single)
-                    process.stdout.write(`# ${kind}:\n`);
+                    await writeStdout(`# ${kind}:\n`);
                 for (const file of files)
-                    process.stdout.write(`- ${file}\n`);
+                    await writeStdout(`- ${file}\n`);
             }
-            process.exit(0);
         });
         /*  register CLI sub-command "ase artifact name"  */
         artifact
@@ -242,10 +242,9 @@ export default class ArtifactCommand {
             .argument("<filename>", "base-relative filename within the kind's basedir")
             .option("--kind <kind>", "artifact kind " +
             `(${configuredKinds.join("|")})`, "code")
-            .action((filename, opts) => {
+            .action(async (filename, opts) => {
             const kind = Artifact.validateKind(opts.kind.trim());
-            process.stdout.write(`${Artifact.name(this.log, kind, filename)}\n`);
-            process.exit(0);
+            await writeStdout(`${Artifact.name(this.log, kind, filename)}\n`);
         });
     }
 }

package/dst/ase-hook.js

@@ -12,6 +12,7 @@ import getStdin from "get-stdin";
 import * as v from "valibot";
 import Version from "./ase-version.js";
 import { Config, configSchema, parseScope } from "./ase-config.js";
+import { writeStdout } from "./ase-stdout.js";
 const addonMcpServers = [
     "chat-alibaba-qwen",
     "chat-deepseek",
@@ -87,18 +88,6 @@ export default class HookCommand {
     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
@@ -145,9 +134,9 @@ export default class HookCommand {
             return this.expandReferences(content, path.dirname(abs), next);
         });
     }
-    /*  handler for "ase hook session-start" (all tools)  */
-    async doSessionStart(tool) {
-        /*  determine plugin root (env var name differs per tool)  */
+    /*  determine the plugin root directory (the environment variable
+        carrying it differs per tool), throwing if it cannot be found  */
+    pluginRoot(tool) {
         let pluginRootVars;
         if (tool === "copilot")
             pluginRootVars = ["COPILOT_PLUGIN_ROOT"];
@@ -163,6 +152,23 @@ export default class HookCommand {
             }
         if (pluginRoot === "")
             throw new Error(`${pluginRootVars.join("/")} environment variable is not set`);
+        return pluginRoot;
+    }
+    /*  determine the plugin root directory like "pluginRoot", but return
+        an empty string instead of throwing, so callers on the hot path of
+        a tool-approval decision can silently decline to auto-approve  */
+    pluginRootSafe(tool) {
+        try {
+            return this.pluginRoot(tool);
+        }
+        catch (_e) {
+            return "";
+        }
+    }
+    /*  handler for "ase hook session-start" (all tools)  */
+    async doSessionStart(tool) {
+        /*  determine plugin root (env var name differs per tool)  */
+        const pluginRoot = this.pluginRoot(tool);
         /*  determine path to external files  */
         const filePkg = path.join(pluginRoot, ".claude-plugin", "plugin.json");
         const fileMd = path.join(pluginRoot, "meta", "ase-constitution.md");
@@ -251,6 +257,7 @@ export default class HookCommand {
         const envFile = tool === "claude" ? (process.env.CLAUDE_ENV_FILE ?? "") : "";
         if (envFile !== "") {
             const script = `export ASE_VERSION=${quote([versionCurrentPlugin])}\n` +
+                `export ASE_PLUGIN_ROOT=${quote([pluginRoot])}\n` +
                 `export ASE_USER_ID=${quote([userId])}\n` +
                 `export ASE_PROJECT_ID=${quote([projectId])}\n` +
                 `export ASE_TASK_ID=${quote([taskId])}\n` +
@@ -263,6 +270,7 @@ export default class HookCommand {
         md =
             `<ase-version>${versionCurrentPlugin}</ase-version>\n` +
                 `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
+                `<ase-plugin-root>${pluginRoot}</ase-plugin-root>\n` +
                 `<ase-persona-style>${persona}</ase-persona-style>\n` +
                 `<ase-user-id>${userId}</ase-user-id>\n` +
                 `<ase-project-id>${projectId}</ase-project-id>\n` +
@@ -299,7 +307,7 @@ export default class HookCommand {
             running headless -- mirroring the constitution box condition)  */
         if ((tool === "claude" || tool === "codex") && headless !== "true")
             payload.systemMessage = banner;
-        await this.writeStdout(JSON.stringify(payload));
+        await writeStdout(JSON.stringify(payload));
         return 0;
     }
     /*  publish the agent activity marker to tmux as a per-pane user
@@ -379,6 +387,23 @@ export default class HookCommand {
             return "";
         }
     }
+    /*  determine whether a "Read" target "filePath" resolves to a
+        location inside the plugin root, so the recurring loads of ASE
+        skill include files (e.g. "@${CLAUDE_SKILL_DIR}/../../meta/...")
+        can be auto-approved instead of prompting the user on every skill
+        invocation. The path is normalized and compared with a trailing
+        separator to prevent a sibling directory sharing the root's name
+        prefix (or a "../" escape) from being mistaken for a descendant.  */
+    isUnderPluginRoot(tool, filePath) {
+        if (filePath === "")
+            return false;
+        const pluginRoot = this.pluginRootSafe(tool);
+        if (pluginRoot === "")
+            return false;
+        const root = path.resolve(pluginRoot) + path.sep;
+        const abs = path.resolve(filePath);
+        return (abs + path.sep).startsWith(root);
+    }
     /*  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"];
@@ -387,7 +412,7 @@ export default class HookCommand {
         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) {
+    decideApproval(tool, spec, input) {
         const toolName = typeof input[spec.toolNameField] === "string" ?
             input[spec.toolNameField] : "";
         let toolInput = {};
@@ -395,7 +420,8 @@ export default class HookCommand {
         if (spec.toolInputIsString && typeof rawInput === "string")
             toolInput = this.parseJSON(rawInput, v.object({
                 command: v.optional(v.string()),
-                skill: v.optional(v.string())
+                skill: v.optional(v.string()),
+                file_path: v.optional(v.string())
             }));
         else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null)
             toolInput = rawInput;
@@ -407,6 +433,8 @@ export default class HookCommand {
             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 === "Read" && this.isUnderPluginRoot(tool, toolInput.file_path ?? ""))
+            return { approve: true, reason: "ASE plugin file read auto-approved" };
         else if (toolName === "Edit") {
             const sessionId = this.pickSessionId(input);
             const activeSkill = this.readActiveSkill(sessionId);
@@ -435,7 +463,7 @@ export default class HookCommand {
         if (spec.approvalEvent !== "PreToolUse")
             return 0;
         /*  determine whether to auto-approve the tool invocation  */
-        const { approve, reason } = this.decideApproval(spec, input);
+        const { approve, reason } = this.decideApproval(tool, 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.  */
@@ -450,7 +478,7 @@ export default class HookCommand {
                 "permissionDecision": "allow",
                 "permissionDecisionReason": reason
             };
-            await this.writeStdout(JSON.stringify(payload));
+            await writeStdout(JSON.stringify(payload));
         }
         return 0;
     }
@@ -469,7 +497,7 @@ export default class HookCommand {
             sessionId: v.optional(v.string())
         }));
         /*  determine whether to auto-approve the tool invocation  */
-        const { approve } = this.decideApproval(spec, input);
+        const { approve } = this.decideApproval(tool, spec, input);
         /*  emit the Codex "PermissionRequest" approval decision  */
         if (approve) {
             const payload = {
@@ -478,7 +506,7 @@ export default class HookCommand {
                     "decision": { "behavior": "allow" }
                 }
             };
-            await this.writeStdout(JSON.stringify(payload));
+            await writeStdout(JSON.stringify(payload));
         }
         return 0;
     }

package/dst/ase-meta.js

@@ -0,0 +1,65 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import { writeStdout } from "./ase-stdout.js";
+/*  reusable functionality: resolve and read plugin "meta/" files  */
+export class Meta {
+    /*  determine the plugin "meta/" directory; the build process copies
+        the sibling "plugin/" tree into the tool package (see the "copy
+        plugin directory into package for bundling" build step), so a
+        bundled "<pkgdir>/plugin/meta/" is always available right next to
+        the compiled tool, independent of any environment variables  */
+    static dir() {
+        const pkgdir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+        return path.join(pkgdir, "plugin", "meta");
+    }
+    /*  resolve a single requested meta name to an absolute path within
+        the "meta/" directory; the name is reduced to its basename to
+        reject path traversal and absolute paths, then expanded into the
+        canonical "ase-<name>.md" file name (the "ase-" prefix and ".md"
+        extension are added when not already present)  */
+    static resolve(name) {
+        let base = path.basename(name.replace(/\\/g, "/"));
+        if (base === "" || base === "." || base === "..")
+            throw new Error(`meta: invalid file name "${name}"`);
+        if (path.extname(base) === "")
+            base = `${base}.md`;
+        if (!base.startsWith("ase-"))
+            base = `ase-${base}`;
+        return path.join(Meta.dir(), base);
+    }
+    /*  read the contents of a single requested meta file  */
+    static read(name) {
+        const abs = Meta.resolve(name);
+        try {
+            return fs.readFileSync(abs, "utf8");
+        }
+        catch (_e) {
+            throw new Error(`meta: failed to read file: ${abs}`);
+        }
+    }
+}
+/*  CLI command "ase meta"  */
+export default class MetaCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register command  */
+    register(program) {
+        program
+            .command("meta")
+            .description("Output the contents of one or more plugin meta files")
+            .argument("<name...>", "meta file name(s) (\"ase-\" prefix and \".md\" extension optional)")
+            .action(async (names) => {
+            this.log.write("debug", `meta: reading ${names.length} file(s)`);
+            for (const name of names)
+                await writeStdout(Meta.read(name));
+        });
+    }
+}

package/dst/ase-stdout.js

@@ -0,0 +1,18 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+/*  write a string to stdout, awaiting the write callback which only
+    fires once the data has been flushed to the underlying pipe, so a
+    subsequent "process.exit" cannot truncate the output  */
+export const writeStdout = (text) => {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(text, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+};

package/dst/ase-task.js

@@ -12,6 +12,7 @@ import { isScalar } from "yaml";
 import { z } from "zod";
 import { Config, configSchema, parseScope } from "./ase-config.js";
 import { Markdown } from "./ase-markdown.js";
+import { writeStdout } from "./ase-stdout.js";
 /*  reusable functionality: persisted task plans under
     <project>/<basedir>/TASK-<id>.md (driven by the
     "project.artifact.task.{basedir,files}" configuration)  */
@@ -269,25 +270,23 @@ export default class TaskCommand {
             .command("list")
             .description("List all persisted task ids, one per line")
             .option("-v, --verbose", "also show the task file modification time as (YYYY-MM-DD HH:MM)")
-            .action((opts) => {
+            .action(async (opts) => {
             const items = Task.list(this.log, opts.verbose ?? false);
             for (const item of items) {
                 if (opts.verbose)
-                    process.stdout.write(`${item.id}\t(${item.mtime})\n`);
+                    await writeStdout(`${item.id}\t(${item.mtime})\n`);
                 else
-                    process.stdout.write(`${item.id}\n`);
+                    await writeStdout(`${item.id}\n`);
             }
-            process.exit(0);
         });
         /*  register CLI sub-command "ase task load"  */
         task
             .command("load")
             .description("Load a task by id and write it to stdout")
             .argument("<id>", "Task identifier")
-            .action((id) => {
+            .action(async (id) => {
             const text = Task.load(this.log, id);
-            process.stdout.write(text);
-            process.exit(0);
+            await writeStdout(text);
         });
         /*  register CLI sub-command "ase task edit"  */
         task

package/dst/ase.js

@@ -15,6 +15,7 @@ import SetupCommand from "./ase-setup.js";
 import StatuslineCommand from "./ase-statusline.js";
 import TaskCommand from "./ase-task.js";
 import ArtifactCommand from "./ase-artifact.js";
+import MetaCommand from "./ase-meta.js";
 import CompatCommand from "./ase-compat.js";
 import pkg from "../package.json" with { type: "json" };
 /*  globally initialize logger  */
@@ -52,6 +53,7 @@ const main = async () => {
     new StatuslineCommand(log).register(program);
     new TaskCommand(log).register(program);
     new ArtifactCommand(log).register(program);
+    new MetaCommand(log).register(program);
     new CompatCommand().register(program);
     new DiagramCommand(log).register(program);
     /*  parse program arguments  */

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.31",
+    "version":                              "0.9.32",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.31",
+    "version":     "0.9.32",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.31",
+    "version":     "0.9.32",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.31",
+    "version":     "0.9.32",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.31",
+    "version":                              "0.9.32",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",