@rse/ase 2.0.1 → 2.0.3

package/dst/ase-agent-definition-core.js

@@ -47,7 +47,7 @@ export const discoverKinds = (log, reserved) => {
         }
         const seen = new Set();
         const rank = (entry) => definitionExts.indexOf(path.extname(entry).toLowerCase());
-        for (const entry of entries.filter((entry) => rank(entry) >= 0).sort((a, b) => rank(a) - rank(b))) {
+        for (const entry of entries.filter((e) => rank(e) >= 0).sort((a, b) => rank(a) - rank(b))) {
             const kind = path.basename(entry, path.extname(entry));
             const file = path.join(dir, entry);
             if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(kind) || kind.length > 64)
@@ -403,11 +403,11 @@ const loadDefinition = async (spec, chain = []) => {
     if (spec.startsWith("builtin:")) {
         const where = `agent: option "--definition": definition "${spec}"`;
         const m = /^builtin:([a-z]+)(?:-([a-z]+))?$/.exec(spec);
-        const kind = builtinKinds.find((kind) => kind.kind === m?.[1]);
+        const kind = builtinKinds.find((k) => k.kind === m?.[1]);
         const mode = m?.[2] ?? kind?.mode ?? "";
         if (m === null || kind === undefined || !Object.hasOwn(kind.modes, mode))
             throw new Error(`${where}: unknown built-in definition (expected ` +
-                builtinKinds.flatMap((kind) => Object.keys(kind.modes).map((mode) => `"builtin:${kind.kind}-${mode}"`)).join(", ") + ")");
+                builtinKinds.flatMap((k) => Object.keys(k.modes).map((n) => `"builtin:${k.kind}-${n}"`)).join(", ") + ")");
         id = `builtin:${kind.kind}-${mode}`;
         loaded = definitionValues(kind.modes[mode], where, "");
     }
@@ -576,6 +576,106 @@ const resolveStates = (str, list, has, type, unclaimed) => {
     }
     return { incoming, activity, success, failure, phase, passed, verdicts, lifecycles };
 };
+/*  resolve the prompt of the processing type <type> through the option accessors <str>
+    and <has>: the skill (if any) and the parsed template of its arguments, of the prompt
+    text, or of the prompt file, with the declared parameters <params>  */
+const resolvePrompt = (str, has, type, params) => {
+    const fail = failOption;
+    const prompts = ["prompt-skill", "prompt-text", "prompt-file"].filter((key) => has(key));
+    if (prompts.length !== 1)
+        fail(prompts[1] ?? "prompt-skill", "exactly one of \"--prompt-skill\", \"--prompt-text\", or \"--prompt-file\" is required");
+    if (has("prompt-args") && !has("prompt-skill"))
+        fail("prompt-args", "allowed with \"--prompt-skill\" only");
+    const skill = str("prompt-skill");
+    if (has("prompt-skill") && !/^(?:[A-Za-z0-9_.-]+:)?[A-Za-z0-9_.-]+$/.test(skill))
+        fail("prompt-skill", `invalid skill name "${skill}"`);
+    let template;
+    if (has("prompt-skill"))
+        template = parseTemplate(str("prompt-args", type === "phase" ? "{id}" : "{id}: {prompt}"), "prompt-args", type, params);
+    else if (has("prompt-text"))
+        template = parseTemplate(str("prompt-text"), "prompt-text", type, params);
+    else {
+        let text = "";
+        try {
+            text = fs.readFileSync(path.resolve(str("prompt-file")), "utf8");
+        }
+        catch (err) {
+            fail("prompt-file", `cannot read prompt file: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        template = parseTemplate(text, "prompt-file", type, params);
+    }
+    return { skill, template };
+};
+/*  resolve the success criteria, the output line matches, and the accepted verdicts of the
+    processing type <type> through the option accessors <list> and <has>, validated against
+    the determination of a verdict <verdicting> and the target states per verdict <verdicts>  */
+const resolveSuccess = (list, has, type, unclaimed, verdicting, verdicts) => {
+    const fail = failOption;
+    const criteria = has("success-criterion") ? [...new Set(list("success-criterion"))] :
+        (type === "phase" ? ["exit", "clean"] : ["clean", "changed"]);
+    for (const criterion of criteria) {
+        if (!definitionCriteria.includes(criterion))
+            fail("success-criterion", `invalid criterion "${criterion}" ` +
+                `(expected ${definitionCriteria.map((c) => `"${c}"`).join(", ")})`);
+        else if (criterion === "changed" && type !== "request")
+            fail("success-criterion", "criterion \"changed\" is for \"--type request\" only");
+        else if (criterion === "status" && type !== "phase")
+            fail("success-criterion", "criterion \"status\" is for \"--type phase\" only");
+        else if (criterion === "status" && unclaimed)
+            fail("success-criterion", "criterion \"status\" is not for \"--unclaimed\" (as an unclaimed task has no phase success state)");
+        else if (criterion === "verdict" && !verdicting)
+            fail("success-criterion", "criterion \"verdict\" requires \"--verdict-label\" (or the hook \"verdict\")");
+        else if (criterion === "attachment" && !has("attach-expect"))
+            fail("success-criterion", "criterion \"attachment\" requires \"--attach-expect\"");
+    }
+    const match = list("success-match").map((spec) => {
+        try {
+            return new RegExp(spec);
+        }
+        catch (err) {
+            return fail("success-match", `invalid regular expression "${spec}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    if ((Object.keys(verdicts).length > 0 || has("verdict-allow")) && !verdicting)
+        fail(Object.keys(verdicts).length > 0 ? "state-verdict" : "verdict-allow", "requires \"--verdict-label\" (or the hook \"verdict\")");
+    const allow = has("verdict-allow") ? list("verdict-allow") : Object.keys(verdicts);
+    for (const verdict of allow)
+        if (!/^[A-Z]+$/.test(verdict))
+            fail("verdict-allow", `invalid verdict "${verdict}" (expected an upper-case word)`);
+    for (const verdict of Object.keys(verdicts))
+        if (!allow.includes(verdict))
+            fail("state-verdict", `verdict "${verdict}" is not accepted by "--verdict-allow"`);
+    return { criteria: criteria, match, allow };
+};
+/*  resolve the attachments through the option accessors <str> and <has>: the expected
+    attachment and the attachment leaving a task unclaimed, validated together with the
+    kinds of the output and change set attachments  */
+const resolveAttach = (str, has) => {
+    const fail = failOption;
+    const kindRe = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
+    const attachSpec = (key) => {
+        if (!has(key))
+            return null;
+        const spec = str(key);
+        const i = spec.indexOf(";");
+        const mime = i < 0 ? "" : spec.slice(0, i).trim().toLowerCase();
+        const kind = i < 0 ? spec.trim() : spec.slice(i + 1).trim();
+        if (!kindRe.test(kind) || (i >= 0 && !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(mime)))
+            fail(key, `invalid attachment "${spec}" (expected "[<mime-type>;]<kind>")`);
+        return { mime, kind };
+    };
+    if (has("attach-output") && !kindRe.test(str("attach-output")))
+        fail("attach-output", `invalid kind "${str("attach-output")}"`);
+    else if (str("attach-output") === "agent")
+        fail("attach-output", "kind \"agent\" is reserved for the processing log");
+    if (has("attach-changeset") && !kindRe.test(str("attach-changeset")))
+        fail("attach-changeset", `invalid kind "${str("attach-changeset")}"`);
+    const expect = attachSpec("attach-expect");
+    if (expect !== null && has("attach-output")
+        && attachMatches(expect, `text/plain; kind="${str("attach-output")}"`))
+        fail("attach-expect", `attachment "${str("attach-expect")}" is always met by the output attachment of "--attach-output"`);
+    return { expect, skip: attachSpec("attach-skip") };
+};
 /*  resolve the definition of the agent named <name> from its (camel-cased) command-line
     options <opts>: the defaults, overridden by the definition of "--definition" (if any),
     overridden by the given options, validated against the task lifecycle models  */
@@ -707,88 +807,12 @@ export const resolveDefinition = async (opts, name) => {
     /*  the parameters (see "resolveParams")  */
     const decls = loaded.params;
     const params = resolveParams(decls, list("params"));
-    /*  the prompt  */
-    const prompts = ["prompt-skill", "prompt-text", "prompt-file"].filter((key) => has(key));
-    if (prompts.length !== 1)
-        fail(prompts[1] ?? "prompt-skill", "exactly one of \"--prompt-skill\", \"--prompt-text\", or \"--prompt-file\" is required");
-    if (has("prompt-args") && !has("prompt-skill"))
-        fail("prompt-args", "allowed with \"--prompt-skill\" only");
-    const skill = str("prompt-skill");
-    if (has("prompt-skill") && !/^(?:[A-Za-z0-9_.-]+:)?[A-Za-z0-9_.-]+$/.test(skill))
-        fail("prompt-skill", `invalid skill name "${skill}"`);
-    let template;
-    if (has("prompt-skill"))
-        template = parseTemplate(str("prompt-args", type === "phase" ? "{id}" : "{id}: {prompt}"), "prompt-args", type, Object.keys(decls));
-    else if (has("prompt-text"))
-        template = parseTemplate(str("prompt-text"), "prompt-text", type, Object.keys(decls));
-    else {
-        let text = "";
-        try {
-            text = fs.readFileSync(path.resolve(str("prompt-file")), "utf8");
-        }
-        catch (err) {
-            fail("prompt-file", `cannot read prompt file: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        template = parseTemplate(text, "prompt-file", type, Object.keys(decls));
-    }
-    /*  the success criteria and the verdict  */
-    const criteria = has("success-criterion") ? [...new Set(list("success-criterion"))] :
-        (type === "phase" ? ["exit", "clean"] : ["clean", "changed"]);
-    for (const criterion of criteria) {
-        if (!definitionCriteria.includes(criterion))
-            fail("success-criterion", `invalid criterion "${criterion}" ` +
-                `(expected ${definitionCriteria.map((c) => `"${c}"`).join(", ")})`);
-        else if (criterion === "changed" && type !== "request")
-            fail("success-criterion", "criterion \"changed\" is for \"--type request\" only");
-        else if (criterion === "status" && type !== "phase")
-            fail("success-criterion", "criterion \"status\" is for \"--type phase\" only");
-        else if (criterion === "status" && unclaimed)
-            fail("success-criterion", "criterion \"status\" is not for \"--unclaimed\" (as an unclaimed task has no phase success state)");
-        else if (criterion === "verdict" && !verdicting)
-            fail("success-criterion", "criterion \"verdict\" requires \"--verdict-label\" (or the hook \"verdict\")");
-        else if (criterion === "attachment" && !has("attach-expect"))
-            fail("success-criterion", "criterion \"attachment\" requires \"--attach-expect\"");
-    }
-    const match = list("success-match").map((spec) => {
-        try {
-            return new RegExp(spec);
-        }
-        catch (err) {
-            return fail("success-match", `invalid regular expression "${spec}": ${err instanceof Error ? err.message : String(err)}`);
-        }
-    });
-    if ((Object.keys(verdicts).length > 0 || has("verdict-allow")) && !verdicting)
-        fail(Object.keys(verdicts).length > 0 ? "state-verdict" : "verdict-allow", "requires \"--verdict-label\" (or the hook \"verdict\")");
-    const allow = has("verdict-allow") ? list("verdict-allow") : Object.keys(verdicts);
-    for (const verdict of allow)
-        if (!/^[A-Z]+$/.test(verdict))
-            fail("verdict-allow", `invalid verdict "${verdict}" (expected an upper-case word)`);
-    for (const verdict of Object.keys(verdicts))
-        if (!allow.includes(verdict))
-            fail("state-verdict", `verdict "${verdict}" is not accepted by "--verdict-allow"`);
-    /*  the attachments  */
-    const kindRe = /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/;
-    const attachSpec = (key) => {
-        if (!has(key))
-            return null;
-        const spec = str(key);
-        const i = spec.indexOf(";");
-        const mime = i < 0 ? "" : spec.slice(0, i).trim().toLowerCase();
-        const kind = i < 0 ? spec.trim() : spec.slice(i + 1).trim();
-        if (!kindRe.test(kind) || (i >= 0 && !/^[a-z0-9.+-]+\/[a-z0-9.+-]+$/.test(mime)))
-            fail(key, `invalid attachment "${spec}" (expected "[<mime-type>;]<kind>")`);
-        return { mime, kind };
-    };
-    if (has("attach-output") && !kindRe.test(str("attach-output")))
-        fail("attach-output", `invalid kind "${str("attach-output")}"`);
-    else if (str("attach-output") === "agent")
-        fail("attach-output", "kind \"agent\" is reserved for the processing log");
-    if (has("attach-changeset") && !kindRe.test(str("attach-changeset")))
-        fail("attach-changeset", `invalid kind "${str("attach-changeset")}"`);
-    const attachExpect = attachSpec("attach-expect");
-    if (attachExpect !== null && has("attach-output")
-        && attachMatches(attachExpect, `text/plain; kind="${str("attach-output")}"`))
-        fail("attach-expect", `attachment "${str("attach-expect")}" is always met by the output attachment of "--attach-output"`);
+    /*  the prompt (see "resolvePrompt")  */
+    const { skill, template } = resolvePrompt(str, has, type, Object.keys(decls));
+    /*  the success criteria and the verdict (see "resolveSuccess")  */
+    const { criteria, match, allow } = resolveSuccess(list, has, type, unclaimed, verdicting, verdicts);
+    /*  the attachments (see "resolveAttach")  */
+    const { expect: attachExpect, skip: attachSkip } = resolveAttach(str, has);
     for (const key of ["prepare-run", "finish-success", "finish-failure"])
         if ((has(key) && str(key, "-") === "") || list(key).some((cmd) => cmd.trim() === ""))
             fail(key, "empty shell command");
@@ -814,10 +838,10 @@ export const resolveDefinition = async (opts, name) => {
         request: { name: requestName, done: str("request-done", "processed"), prompt: consumes },
         prompt: { skill, template },
         prepare: list("prepare-run"),
-        success: { criteria: criteria, match },
+        success: { criteria, match },
         verdict: { label: str("verdict-label"), allow },
         attach: {
-            output: str("attach-output"), expect: attachExpect, skip: attachSpec("attach-skip"),
+            output: str("attach-output"), expect: attachExpect, skip: attachSkip,
             changeset: str("attach-changeset")
         },
         finish: { commit: flag("finish-commit"), success: str("finish-success"), failure: str("finish-failure") },

package/dst/ase-agent-fleet.js

@@ -335,7 +335,7 @@ export default class AgentFleetCommand extends DaemonCommand {
             const { kind = name, ...options } = section(name);
             if (typeof kind !== "string" || !this.kinds.has(kind))
                 throw new Error(`fleet: section "${name}": unknown agent kind "${String(kind)}" ` +
-                    `(expected ${kinds.map((name) => `"${name}"`).join(", ")})`);
+                    `(expected ${kinds.map((k) => `"${k}"`).join(", ")})`);
             validateName(name, kind, kinds);
             /*  the options of the definition of an agent can be nested by group, and the
                 definition file of an ad-hoc agent (but not a built-in definition) is

package/dst/ase-agent-runtime-claim.js

@@ -51,7 +51,9 @@ export class AgentRun {
     record(run) {
         try {
             const data = JSON.parse(fs.readFileSync(this.file(run, ".json"), "utf8"));
-            return { pid: Number(data.pid ?? 0), start: String(data.start ?? ""), claims: data.claims ?? {} };
+            const claims = data.claims !== null && typeof data.claims === "object" && !Array.isArray(data.claims) ?
+                data.claims : {};
+            return { pid: Number(data.pid ?? 0), start: String(data.start ?? ""), claims };
         }
         catch (_err) {
             return { pid: 0, start: "", claims: {} };
@@ -112,12 +114,12 @@ export class AgentRun {
                 .filter((entry) => /\.(?:lock|json)$/.test(entry))
                 .map((entry) => entry.replace(/\.(?:lock|json)$/, "")))];
     }
-    /*  the terminated runs of the agent kind for the task store, with their recorded claims  */
+    /*  the terminated runs of the agent kind for the task store  */
     async dead() {
         const dead = [];
         for (const run of this.runs())
             if (!(await this.alive(run)))
-                dead.push({ run, claims: this.record(run).claims });
+                dead.push(run);
         return dead;
     }
     /*  seize a terminated run for its recovery, by taking over its (stale or removed) run lock,

package/dst/ase-agent-runtime-engine.js

@@ -412,7 +412,7 @@ class DefinedCore {
             };
         }
         catch (err) {
-            await work.cleanup?.(log).catch((err2) => log("warning", err2 instanceof Error ? err2.message : String(err2)));
+            await work.cleanup?.(log).catch((err2) => log("warning", reason(err2)));
             throw err;
         }
     }

package/dst/ase-agent-runtime-phase.js

@@ -515,7 +515,7 @@ export class PhaseAgent extends Agent {
         is removed once all its tasks are recovered  */
     async recover() {
         const { incoming, success } = this.states;
-        for (const { run } of await this.runLock.dead()) {
+        for (const run of await this.runLock.dead()) {
             const claims = await this.runLock.seize(run);
             if (claims === null)
                 continue;

package/dst/ase-agent-runtime-request.js

@@ -100,7 +100,7 @@ export class RequestAgent extends Agent {
             });
             await this.write("warning", this.name, `task "${item.id}": ${this.requests.name} request of terminated ${this.role} marked as failed`);
         }
-        for (const { run } of runs)
+        for (const run of runs)
             await this.runLock.purge(run);
     }
     /*  select every task with a request (except one whose finalization is still retried),

package/dst/ase-agent-runtime.js

@@ -840,9 +840,7 @@ export class Agent {
         const cli = toolSpecs[tool].cli;
         const cmd = job.cmd ?? "";
         const i = cmd.indexOf(" ");
-        const args = toolArgs[tool](job.prompt ?? skillPrompt(tool, i < 0 ? cmd : cmd.slice(0, i), i < 0 ? "" : cmd.slice(i + 1)), (job.dirs ?? [])
-            .filter((dir, i, dirs) => dir !== cwd && dirs.indexOf(dir) === i)
-            .flatMap((dir) => ["--add-dir", dir]));
+        const args = toolArgs[tool](job.prompt ?? skillPrompt(tool, i < 0 ? cmd : cmd.slice(0, i), i < 0 ? "" : cmd.slice(i + 1)), [...new Set(job.dirs ?? [])].filter((dir) => dir !== cwd).flatMap((dir) => ["--add-dir", dir]));
         await log("info", `running: ${cli} ${args.map((arg) => arg.includes(" ") ? `"${arg}"` : arg).join(" ")}`);
         const started = Date.now();
         const costs = { costToken: null, costUSD: null, cread: 0, cwrite: 0, input: 0, apiMs: null };
@@ -1041,8 +1039,8 @@ export class Agent {
             ...Object.fromEntries(Object.entries(own).filter((entry) => entry[1] !== undefined))
         };
         this._name = opts.name ?? "";
-        if (this._name !== "" && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(this._name))
-            throw new Error(`agent: invalid name "${this._name}" (expected letters, digits, "_", ".", or "-")`);
+        if (this._name !== "" && !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(this._name))
+            throw new Error(`agent: invalid name "${this._name}" (expected up to 64 letters, digits, "_", ".", or "-")`);
         this.relay = relay;
         this.tool = parseTool(opts.tool);
         for (const cli of [toolSpecs[this.tool].cli, ...(this.worktree ? ["git"] : [])])

package/dst/ase-artifact.js

@@ -149,7 +149,7 @@ export class Artifact {
     /*  resolve a base-relative "filename" within a kind's "basedir" to a
         project-root-relative POSIX path; the implicit "othr" catch-all
         has no configured "basedir" and is therefore rejected  */
-    static name(log, kind, filename) {
+    static resolveName(log, kind, filename) {
         if (kind === "othr")
             throw new Error("artifact: kind \"othr\" has no configured basedir");
         const file = filename.replace(/\\/g, "/").replace(/^\/+/, "");
@@ -216,7 +216,7 @@ export default class ArtifactCommand {
             `(${configuredKinds.join("|")})`, "code")
             .action(async (filename, opts) => {
             const kind = Artifact.validateKind(opts.kind.trim());
-            await writeStdout(`${Artifact.name(this.log, kind, filename)}\n`);
+            await writeStdout(`${Artifact.resolveName(this.log, kind, filename)}\n`);
         });
     }
 }
@@ -285,7 +285,7 @@ export class ArtifactMCP {
         }, async (args) => {
             try {
                 const kind = Artifact.validateKind(args.kind ?? "code");
-                const result = { name: Artifact.name(this.log, kind, args.filename) };
+                const result = { name: Artifact.resolveName(this.log, kind, args.filename) };
                 return {
                     structuredContent: result,
                     content: [{ type: "text", text: JSON.stringify(result) }]

package/dst/ase-config-core.js

@@ -427,15 +427,8 @@ export class Config {
                 next.setIn(prefix, next.createNode({}));
         }
         next.setIn(segments, value);
-        const saved = td.doc;
+        this.validateDoc(next, td.filename, "strict");
         td.doc = next;
-        try {
-            this.validateDoc(td.doc, td.filename, "strict");
-        }
-        catch (err) {
-            td.doc = saved;
-            throw err;
-        }
     }
     /*  delete a value at a dotted key from the target scope  */
     delete(key) {
@@ -445,15 +438,8 @@ export class Config {
             return;
         const next = td.doc.clone();
         next.deleteIn(this.resolveKey(key).split("."));
-        const saved = td.doc;
+        this.validateDoc(next, td.filename, "strict");
         td.doc = next;
-        try {
-            this.validateDoc(td.doc, td.filename, "strict");
-        }
-        catch (err) {
-            td.doc = saved;
-            throw err;
-        }
     }
 }
 /*  access the internal "state.yaml" of a session, which, unlike the

package/dst/ase-config-schema.js

@@ -5,9 +5,7 @@
 */
 import * as v from "valibot";
 import { foregroundColorNames } from "chalk";
-import { checkIdScheme } from "./ase-task-format.js";
-import { parseEffortScale } from "./ase-task-format.js";
-import { EFFORT_SCALE } from "./ase-task-format.js";
+import { checkIdScheme, parseEffortScale, EFFORT_SCALE } from "./ase-task-format.js";
 /*  classification taxonomy  */
 export const projectClassification = {
     boxing: ["white", "grey", "black"],

package/dst/ase-config.js

@@ -191,7 +191,10 @@ export class ConfigMCP {
                 const cfg = new Config("config", configSchema, this.log, scope);
                 cfg.read();
                 const val = cfg.get(args.key);
-                const text = val === undefined ? "" : JSON.stringify(val);
+                if (isMap(val))
+                    throw new Error(`key "${args.key}" is not a leaf key`);
+                const text = val === undefined ? "" :
+                    JSON.stringify(configSecretKeys.includes(cfg.resolveKey(args.key)) ? "***" : val);
                 return { content: [{ type: "text", text }] };
             }
             catch (err) {

package/dst/ase-hook.js

@@ -16,6 +16,8 @@ import { parseScope, userStateDir } from "./ase-config-scope.js";
 import { readStdin, writeStdout } from "./ase-lib-stdio.js";
 import { Task } from "./ase-task.js";
 import * as TaskFormat from "./ase-task-format.js";
+import { parseTool } from "./ase-setup-common.js";
+/*  the addon MCP servers whose tools get auto-approved  */
 const addonMcpServers = [
     "chat-alibaba-qwen",
     "chat-deepseek",
@@ -37,6 +39,7 @@ const addonMcpToolNamePattern = (prefix, suffix) => {
         .join("|");
     return new RegExp(`^${prefix}(?:${alternatives})${suffix}`);
 };
+/*  the per-tool dispatch table of the hook integrations  */
 const toolSpecs = {
     "claude": {
         toolNameField: "tool_name",
@@ -88,7 +91,7 @@ export default class HookCommand {
     }
     /*  validate a session id against the accepted character set  */
     isValidSessionId(id) {
-        return /^[A-Za-z0-9._-]+$/.test(id);
+        return /^[A-Za-z0-9._-]+$/.test(id) && id !== "." && id !== "..";
     }
     /*  resolve the base directory holding all per-session state  */
     sessionBaseDir() {
@@ -105,7 +108,7 @@ export default class HookCommand {
         try {
             entries = fs.readdirSync(base, { withFileTypes: true });
         }
-        catch (_e) {
+        catch {
             /*  best-effort: no base directory yet, or unreadable  */
             return;
         }
@@ -120,7 +123,7 @@ export default class HookCommand {
                 fs.rmSync(dir, { recursive: true, force: true });
                 this.log.write("debug", `hook: pruned stale session directory: ${dir}`);
             }
-            catch (_e) {
+            catch {
                 /*  best-effort: ignore vanished or undeletable directories  */
             }
         }
@@ -142,7 +145,7 @@ export default class HookCommand {
         try {
             raw = JSON.parse(text);
         }
-        catch (_e) {
+        catch {
             /*  best-effort: return empty object on malformed JSON  */
             return empty;
         }
@@ -167,7 +170,7 @@ export default class HookCommand {
             try {
                 content = fs.readFileSync(abs, "utf8");
             }
-            catch (_e) {
+            catch {
                 return match;
             }
             const next = new Set(visited);
@@ -199,7 +202,7 @@ export default class HookCommand {
         try {
             return this.pluginRoot(tool);
         }
-        catch (_e) {
+        catch {
             return "";
         }
     }
@@ -428,7 +431,7 @@ export default class HookCommand {
             ASE_HEADLESS: headless,
             ASE_AGENT_TOOL: tool
         });
-        /*  prepend ASE information to constitution markdown  */
+        /*  prepend ASE information to the constitution markdown (with its @<file> references expanded)  */
         let context = `<ase-version>${version}</ase-version>\n` +
             `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
             `<ase-plugin-root>${pluginRoot}</ase-plugin-root>\n` +
@@ -447,9 +450,7 @@ export default class HookCommand {
             `<ase-session-id>${sessionId}</ase-session-id>\n` +
             `<ase-headless>${headless}</ase-headless>\n` +
             `<ase-agent-tool>${tool}</ase-agent-tool>\n` +
-            "\n" + md;
-        /*  expand all @<file> references manually  */
-        context = this.expandReferences(context, mdDir);
+            "\n" + this.expandReferences(md, mdDir);
         /*  append the output style to the constitution markdown (GitHub
             Copilot CLI and OpenAI Codex CLI only -- Anthropic Claude Code CLI
             applies the plugin output style natively), stripping the
@@ -530,7 +531,7 @@ export default class HookCommand {
             try {
                 fs.rmSync(dir, { recursive: true, force: true });
             }
-            catch (_e) {
+            catch {
                 /*  best-effort: ignore failures  */
             }
             /*  detach the session from its AI usage window (if any), which closes
@@ -577,7 +578,7 @@ export default class HookCommand {
             });
             return val;
         }
-        catch (_e) {
+        catch {
             return "";
         }
     }
@@ -706,12 +707,6 @@ export default class HookCommand {
         }
         return 0;
     }
-    /*  parse and validate the --tool option  */
-    parseTool(value) {
-        if (value !== "claude" && value !== "copilot" && value !== "codex")
-            throw new Error(`invalid --tool value: "${value}" (expected "claude", "copilot", or "codex")`);
-        return value;
-    }
     /*  register commands  */
     register(program) {
         /*  default for --tool derived from ASE_TOOL environment variable
@@ -743,7 +738,7 @@ export default class HookCommand {
                 .description(desc)
                 .option("-t, --tool <tool>", "target tool (\"claude\", \"copilot\", or \"codex\")", toolDflt)
                 .action(async (opts) => {
-                process.exitCode = await handler(this.parseTool(opts.tool));
+                process.exitCode = await handler(parseTool(opts.tool));
             });
     }
 }