@oxagen/cli 0.6.0 → 0.6.1

package/dist/settings/__tests__/runtime.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applySettingsToEnv } from "../runtime.js";
+import { getScopePaths, clearSettingsCache } from "../resolve.js";
+let dir;
+let userPath;
+const TOUCHED = ["OXAGEN_MODEL", "OXAGEN_API_URL", "OXAGEN_RT_TEST_A", "OXAGEN_RT_TEST_B"];
+const saved = {};
+function writeProject(body) {
+    const path = getScopePaths({ cwd: dir, userSettingsPath: userPath }).project;
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, JSON.stringify(body), "utf8");
+}
+function apply() {
+    return applySettingsToEnv({ cwd: dir, userSettingsPath: userPath, noCache: true });
+}
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "oxagen-runtime-"));
+    userPath = join(dir, "user-settings.json");
+    for (const k of TOUCHED) {
+        saved[k] = process.env[k];
+        delete process.env[k];
+    }
+    clearSettingsCache();
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    for (const k of TOUCHED) {
+        if (saved[k] === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = saved[k];
+    }
+    clearSettingsCache();
+});
+describe("applySettingsToEnv", () => {
+    it("fills unset env vars from settings.env", () => {
+        writeProject({ env: { OXAGEN_RT_TEST_A: "from-settings" } });
+        const applied = apply();
+        expect(process.env["OXAGEN_RT_TEST_A"]).toBe("from-settings");
+        expect(applied.envKeys).toContain("OXAGEN_RT_TEST_A");
+    });
+    it("does not override an env var the shell already set", () => {
+        process.env["OXAGEN_RT_TEST_B"] = "from-shell";
+        writeProject({ env: { OXAGEN_RT_TEST_B: "from-settings" } });
+        const applied = apply();
+        expect(process.env["OXAGEN_RT_TEST_B"]).toBe("from-shell");
+        expect(applied.envKeys).not.toContain("OXAGEN_RT_TEST_B");
+    });
+    it("projects apiUrl and model into OXAGEN_API_URL / OXAGEN_MODEL when unset", () => {
+        writeProject({ model: "vendor/model", apiUrl: "https://api.example.com" });
+        const applied = apply();
+        expect(process.env["OXAGEN_MODEL"]).toBe("vendor/model");
+        expect(process.env["OXAGEN_API_URL"]).toBe("https://api.example.com");
+        expect(applied.model).toBe(true);
+        expect(applied.apiUrl).toBe(true);
+    });
+    it("leaves a shell-set OXAGEN_MODEL untouched", () => {
+        process.env["OXAGEN_MODEL"] = "shell/model";
+        writeProject({ model: "settings/model" });
+        const applied = apply();
+        expect(process.env["OXAGEN_MODEL"]).toBe("shell/model");
+        expect(applied.model).toBe(false);
+    });
+    it("is a no-op when there are no settings", () => {
+        const applied = apply();
+        expect(applied).toEqual({ envKeys: [], apiUrl: false, model: false });
+    });
+});
+//# sourceMappingURL=runtime.test.js.map

package/dist/settings/__tests__/runtime.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.test.js","sourceRoot":"","sources":["../../../src/settings/__tests__/runtime.test.ts"],"names":[],"mappings":"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"}

package/dist/settings/__tests__/schema.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema.test.d.ts.map

package/dist/settings/__tests__/schema.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.test.d.ts","sourceRoot":"","sources":["../../../src/settings/__tests__/schema.test.ts"],"names":[],"mappings":""}

package/dist/settings/__tests__/schema.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { oxagenSettingsSchema, permissionsSchema, hooksSchema } from "../schema.js";
+describe("oxagenSettingsSchema", () => {
+    it("parses a full settings document", () => {
+        const parsed = oxagenSettingsSchema.parse({
+            model: "anthropic/claude-sonnet-4.6",
+            apiUrl: "https://api.oxagen.sh",
+            env: { FOO: "bar" },
+            permissions: { defaultMode: "default", deny: ["Bash(rm -rf*)"], allow: ["Bash(git*)"] },
+            hooks: { PreToolUse: [{ matcher: "bash", hooks: [{ type: "command", command: "echo hi" }] }] },
+            mcpServers: {
+                github: { transport: "stdio", command: "npx", args: ["-y", "server-github"] },
+            },
+            toolVisibility: { github: { include: ["create_*"] } },
+        });
+        expect(parsed.model).toBe("anthropic/claude-sonnet-4.6");
+        expect(parsed.permissions?.deny).toContain("Bash(rm -rf*)");
+        expect(parsed.mcpServers?.github?.transport).toBe("stdio");
+    });
+    it("defaults a hook action's type to 'command'", () => {
+        const parsed = hooksSchema.parse({
+            PreToolUse: [{ hooks: [{ command: "echo hi" }] }],
+        });
+        expect(parsed.PreToolUse?.[0]?.hooks[0]?.type).toBe("command");
+    });
+    it("rejects an invalid apiUrl", () => {
+        expect(() => oxagenSettingsSchema.parse({ apiUrl: "not-a-url" })).toThrow();
+    });
+    it("rejects an unknown permission mode", () => {
+        expect(() => permissionsSchema.parse({ defaultMode: "yolo" })).toThrow();
+    });
+    it("rejects a hook matcher with no actions", () => {
+        expect(() => hooksSchema.parse({ PreToolUse: [{ matcher: "*", hooks: [] }] })).toThrow();
+    });
+    it("passes through forward-compat sections (commands/skills)", () => {
+        const parsed = oxagenSettingsSchema.parse({
+            model: "x/y",
+            commands: ["./.oxagen/commands"],
+            skills: ["./.oxagen/skills"],
+        });
+        expect(parsed["commands"]).toEqual(["./.oxagen/commands"]);
+        expect(parsed["skills"]).toEqual(["./.oxagen/skills"]);
+    });
+    it("validates inline agent definitions (prompt required)", () => {
+        const parsed = oxagenSettingsSchema.parse({
+            agents: { reviewer: { description: "d", prompt: "You review.", tools: ["Read"], model: "z" } },
+        });
+        expect(parsed.agents?.reviewer?.prompt).toBe("You review.");
+        expect(() => oxagenSettingsSchema.parse({ agents: { bad: { model: "z" } } })).toThrow();
+    });
+    it("accepts an empty document", () => {
+        expect(oxagenSettingsSchema.parse({})).toEqual({});
+    });
+});
+//# sourceMappingURL=schema.test.js.map

package/dist/settings/__tests__/schema.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.test.js","sourceRoot":"","sources":["../../../src/settings/__tests__/schema.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEpF,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC;YACxC,KAAK,EAAE,6BAA6B;YACpC,MAAM,EAAE,uBAAuB;YAC/B,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE;YACnB,WAAW,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,YAAY,CAAC,EAAE;YACvF,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE;YAC9F,UAAU,EAAE;gBACV,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,EAAE;aAC9E;YACD,cAAc,EAAE,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE;SACtD,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;QACzD,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;QAC5D,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC;YAC/B,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;SAClD,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,GAAG,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC;YACxC,KAAK,EAAE,KAAK;YACZ,QAAQ,EAAE,CAAC,oBAAoB,CAAC;YAChC,MAAM,EAAE,CAAC,kBAAkB,CAAC;SAC7B,CAA4B,CAAC;QAC9B,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,CAAC;YACxC,MAAM,EAAE,EAAE,QAAQ,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;SAC/F,CAAC,CAAC;QACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC5D,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IAC1F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/settings/__tests__/write.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=write.test.d.ts.map

package/dist/settings/__tests__/write.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.test.d.ts","sourceRoot":"","sources":["../../../src/settings/__tests__/write.test.ts"],"names":[],"mappings":""}

package/dist/settings/__tests__/write.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeSettingsValue, writeStarterSettings } from "../write.js";
+import { loadSettings, getScopePaths, clearSettingsCache } from "../resolve.js";
+let dir;
+let userPath;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "oxagen-write-"));
+    userPath = join(dir, "user-settings.json");
+    clearSettingsCache();
+});
+afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    clearSettingsCache();
+});
+describe("writeSettingsValue", () => {
+    it("writes a scalar into the project scope and round-trips through loadSettings", () => {
+        const path = writeSettingsValue({ scope: "project", key: "model", value: "a/b", cwd: dir });
+        expect(existsSync(path)).toBe(true);
+        expect(path).toBe(getScopePaths({ cwd: dir }).project);
+        const reread = loadSettings({ cwd: dir, userSettingsPath: userPath, noCache: true }).settings;
+        expect(reread.model).toBe("a/b");
+    });
+    it("writes an env var via the env.NAME form", () => {
+        writeSettingsValue({ scope: "local", key: "env.MY_TOKEN", value: "sek", cwd: dir });
+        const reread = loadSettings({ cwd: dir, userSettingsPath: userPath, noCache: true }).settings;
+        expect(reread.env?.MY_TOKEN).toBe("sek");
+    });
+    it("merges into an existing file rather than clobbering it", () => {
+        writeSettingsValue({ scope: "project", key: "model", value: "a/b", cwd: dir });
+        writeSettingsValue({ scope: "project", key: "env.K", value: "v", cwd: dir });
+        const reread = loadSettings({ cwd: dir, userSettingsPath: userPath, noCache: true }).settings;
+        expect(reread.model).toBe("a/b");
+        expect(reread.env?.K).toBe("v");
+    });
+    it("rejects an unsupported key", () => {
+        expect(() => writeSettingsValue({ scope: "project", key: "permissions", value: "x", cwd: dir })).toThrow(/cannot set/);
+    });
+    it("rejects an empty env name", () => {
+        expect(() => writeSettingsValue({ scope: "project", key: "env.", value: "x", cwd: dir })).toThrow();
+    });
+});
+describe("writeStarterSettings", () => {
+    it("creates a valid starter file and is idempotent", () => {
+        const first = writeStarterSettings({ scope: "project", cwd: dir });
+        expect(first.created).toBe(true);
+        const doc = JSON.parse(readFileSync(first.path, "utf8"));
+        expect(doc["$schema"]).toBeTruthy();
+        expect(doc["permissions"]).toBeTruthy();
+        const second = writeStarterSettings({ scope: "project", cwd: dir });
+        expect(second.created).toBe(false);
+    });
+    it("starter file passes validation via loadSettings", () => {
+        writeStarterSettings({ scope: "project", cwd: dir });
+        const resolved = loadSettings({ cwd: dir, userSettingsPath: userPath, noCache: true });
+        expect(resolved.scopes.find((s) => s.scope === "project")?.error).toBeUndefined();
+    });
+});
+//# sourceMappingURL=write.test.js.map

package/dist/settings/__tests__/write.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.test.js","sourceRoot":"","sources":["../../../src/settings/__tests__/write.test.ts"],"names":[],"mappings":"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"}

package/dist/settings/gate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * gate.ts — Wraps the agent's local tools with the settings-driven permission
+ * gate and PreToolUse/PostToolUse hooks.
+ *
+ * This is the single chokepoint where `settings.json` becomes load-bearing for
+ * tool execution: every tool's `execute` is intercepted to (1) evaluate the
+ * permission rules and (2) fire hooks. A denied call or a blocking PreToolUse
+ * hook returns a plain string the model reads instead of running the tool — the
+ * loop continues, the side effect never happens.
+ */
+import type { ToolSet } from "ai";
+import type { Hooks, Permissions } from "./schema.js";
+export interface ToolGateContext {
+    cwd: string;
+    permissions?: Permissions;
+    hooks?: Hooks;
+    /** Aborts in-flight hook commands when the turn is cancelled. */
+    signal?: AbortSignal;
+    /** Notified whenever a tool call is blocked (for surfacing in the UI/logs). */
+    onBlocked?: (toolName: string, reason: string) => void;
+    /**
+     * Map from a permission deny entry (e.g. `Edit(migrations/**)`) to a human
+     * message. When a workspace rule's guard produces the deny, the agent sees the
+     * rule text instead of the raw glob, so it self-corrects. (See the rules
+     * module / adherence loop.)
+     */
+    denyReasons?: Record<string, string>;
+}
+/**
+ * Return a copy of `tools` whose executes are gated. Tools without an `execute`
+ * (none today, but the type allows it) pass through untouched.
+ */
+export declare function wrapToolsWithGate(tools: ToolSet, ctx: ToolGateContext): ToolSet;
+//# sourceMappingURL=gate.d.ts.map

package/dist/settings/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/settings/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAwD/E"}

package/dist/settings/gate.js

@@ -0,0 +1,50 @@
+import { runHooks } from "./hooks.js";
+import { evaluateLocalPermission } from "./permissions-gate.js";
+/**
+ * Return a copy of `tools` whose executes are gated. Tools without an `execute`
+ * (none today, but the type allows it) pass through untouched.
+ */
+export function wrapToolsWithGate(tools, ctx) {
+    // Nothing to enforce → hand back the original set (zero overhead).
+    if (!ctx.permissions && !ctx.hooks)
+        return tools;
+    const out = {};
+    for (const [name, original] of Object.entries(tools)) {
+        const exec = original.execute;
+        if (!exec) {
+            out[name] = original;
+            continue;
+        }
+        const gated = async (input, options) => {
+            const perm = evaluateLocalPermission(name, input, ctx.permissions);
+            if (perm.decision === "deny") {
+                const ruleMessage = perm.rule ? ctx.denyReasons?.[perm.rule] : undefined;
+                const reason = ruleMessage
+                    ? `Blocked by ${ruleMessage}`
+                    : `Permission denied: \`${name}\` ${perm.reason}.`;
+                ctx.onBlocked?.(name, ruleMessage ?? perm.reason);
+                return `⛔ ${reason}`;
+            }
+            const pre = await runHooks(ctx.hooks, { event: "PreToolUse", cwd: ctx.cwd, tool: { name, input } }, ctx.signal);
+            if (pre.blocked) {
+                const reason = pre.reason ?? "blocked by PreToolUse hook";
+                ctx.onBlocked?.(name, reason);
+                return `⛔ Blocked by PreToolUse hook: ${reason}`;
+            }
+            // The AI SDK types a generic tool's output as `any`; narrow to `unknown`
+            // so we handle it safely (and never re-leak `any` to callers).
+            const result = await exec(input, options);
+            // PostToolUse is observational — its exit code never blocks.
+            await runHooks(ctx.hooks, {
+                event: "PostToolUse",
+                cwd: ctx.cwd,
+                tool: { name, input },
+                toolResult: typeof result === "string" ? result.slice(0, 2000) : undefined,
+            }, ctx.signal);
+            return result;
+        };
+        out[name] = { ...original, execute: gated };
+    }
+    return out;
+}
+//# sourceMappingURL=gate.js.map

package/dist/settings/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/settings/gate.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAsBhE;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,GAAoB;IACpE,mEAAmE;IACnE,IAAI,CAAC,GAAG,CAAC,WAAW,IAAI,CAAC,GAAG,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEjD,MAAM,GAAG,GAAY,EAAE,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAkC,CAAC;QACzD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;YACrB,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAgB,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YAClD,MAAM,IAAI,GAAG,uBAAuB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;YACnE,IAAI,IAAI,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;gBAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBACzE,MAAM,MAAM,GAAG,WAAW;oBACxB,CAAC,CAAC,cAAc,WAAW,EAAE;oBAC7B,CAAC,CAAC,wBAAwB,IAAI,MAAM,IAAI,CAAC,MAAM,GAAG,CAAC;gBACrD,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;gBAClD,OAAO,KAAK,MAAM,EAAE,CAAC;YACvB,CAAC;YAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CACxB,GAAG,CAAC,KAAK,EACT,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAC5D,GAAG,CAAC,MAAM,CACX,CAAC;YACF,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;gBAChB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,4BAA4B,CAAC;gBAC1D,GAAG,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAC9B,OAAO,iCAAiC,MAAM,EAAE,CAAC;YACnD,CAAC;YAED,yEAAyE;YACzE,+DAA+D;YAC/D,MAAM,MAAM,GAAY,MAAM,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAEnD,6DAA6D;YAC7D,MAAM,QAAQ,CACZ,GAAG,CAAC,KAAK,EACT;gBACE,KAAK,EAAE,aAAa;gBACpB,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE;gBACrB,UAAU,EAAE,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;aAC3E,EACD,GAAG,CAAC,MAAM,CACX,CAAC;YAEF,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;QAEF,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/settings/hooks.d.ts

@@ -0,0 +1,26 @@
+import type { HookEvent, Hooks } from "./schema.js";
+export interface HookPayload {
+    event: HookEvent;
+    cwd: string;
+    /** Present for PreToolUse / PostToolUse. */
+    tool?: {
+        name: string;
+        input: unknown;
+    };
+    /** Present for PostToolUse: the (clipped) result string the tool returned. */
+    toolResult?: string;
+}
+export interface HookRunOutcome {
+    /** PreToolUse only: a hook blocked the tool (non-zero exit). */
+    blocked: boolean;
+    /** Human-readable reason when blocked (hook stderr/stdout). */
+    reason?: string;
+    /** Concatenated stdout of all hooks that ran (used for SessionStart context). */
+    output: string;
+}
+/**
+ * Run all hooks registered for an event. Returns whether the action should be
+ * blocked (PreToolUse) and any captured stdout (SessionStart context).
+ */
+export declare function runHooks(hooks: Hooks | undefined, payload: HookPayload, signal?: AbortSignal): Promise<HookRunOutcome>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/settings/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/settings/hooks.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAc,SAAS,EAAe,KAAK,EAAE,MAAM,aAAa,CAAC;AAI7E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IACxC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;CAChB;AA4ED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,WAAW,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,cAAc,CAAC,CA6BzB"}

package/dist/settings/hooks.js

@@ -0,0 +1,115 @@
+/**
+ * hooks.ts — The lifecycle hook engine for the CLI agent loop.
+ *
+ * Hooks are shell commands declared in `settings.json` that fire on agent
+ * lifecycle events. They receive the event payload as JSON on stdin (Claude Code
+ * parity), so a hook can inspect what the agent is about to do.
+ *
+ * Three events are wired today, each with distinct, load-bearing behavior:
+ *
+ *   - SessionStart  runs once before the turn. Anything a hook prints to stdout
+ *                   is appended to the system prompt as additional context
+ *                   (e.g. inject the current sprint, on-call notes, a changelog).
+ *   - PreToolUse    runs before a tool executes. A non-zero exit BLOCKS the tool
+ *                   — the model receives the hook's message instead of running it
+ *                   (e.g. forbid `git push`, gate writes to protected paths).
+ *   - PostToolUse   runs after a tool executes (side effects only — auto-format a
+ *                   file after write_file, emit a notification). Never blocks.
+ *
+ * Matchers are globs over the tool name (PreToolUse / PostToolUse). SessionStart
+ * ignores the matcher and runs every action.
+ */
+import { spawn } from "node:child_process";
+import { matchGlob } from "@oxagen/mcp-config/permissions";
+const DEFAULT_HOOK_TIMEOUT_MS = 60_000;
+/** Run one hook command, feeding the payload JSON on stdin. Never throws. */
+function execHook(action, payloadJson, cwd, signal) {
+    return new Promise((resolvePromise) => {
+        const child = spawn("/bin/bash", ["-c", action.command], {
+            cwd,
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolvePromise(result);
+        };
+        const timeoutMs = Math.min(action.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS, 600_000);
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish({ code: 124, stdout, stderr: stderr + `\n[hook timed out after ${timeoutMs}ms]` });
+        }, timeoutMs);
+        const onAbort = () => {
+            child.kill("SIGKILL");
+            finish({ code: 130, stdout, stderr: stderr + "\n[hook aborted]" });
+        };
+        if (signal) {
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        child.on("error", (err) => finish({ code: 1, stdout, stderr: stderr + String(err) }));
+        child.on("close", (code) => finish({ code: code ?? 0, stdout, stderr }));
+        // A hook that exits before reading stdin makes the write below emit EPIPE
+        // asynchronously on the stdin stream. Swallow it — the exit code is what
+        // matters, and an unhandled stream error would otherwise crash the process.
+        child.stdin.on("error", () => { });
+        try {
+            child.stdin.write(payloadJson);
+            child.stdin.end();
+        }
+        catch {
+            /* stdin may already be closed if the command exits immediately */
+        }
+    });
+}
+/** Which matchers apply for this event + tool. SessionStart ignores the matcher. */
+function selectMatchers(event, matchers, toolName) {
+    if (event === "SessionStart")
+        return matchers;
+    if (!toolName)
+        return [];
+    return matchers.filter((m) => matchGlob(m.matcher ?? "*", toolName));
+}
+/**
+ * Run all hooks registered for an event. Returns whether the action should be
+ * blocked (PreToolUse) and any captured stdout (SessionStart context).
+ */
+export async function runHooks(hooks, payload, signal) {
+    const none = { blocked: false, output: "" };
+    if (!hooks)
+        return none;
+    const matchers = hooks[payload.event];
+    if (!matchers || matchers.length === 0)
+        return none;
+    const selected = selectMatchers(payload.event, matchers, payload.tool?.name);
+    if (selected.length === 0)
+        return none;
+    const payloadJson = JSON.stringify(payload);
+    const outputs = [];
+    for (const matcher of selected) {
+        for (const action of matcher.hooks) {
+            const result = await execHook(action, payloadJson, payload.cwd, signal);
+            if (result.stdout.trim())
+                outputs.push(result.stdout.trim());
+            // PreToolUse is the only blocking event: a non-zero exit vetoes the tool.
+            if (payload.event === "PreToolUse" && result.code !== 0) {
+                const reason = result.stderr.trim() ||
+                    result.stdout.trim() ||
+                    `hook \`${action.command}\` exited ${result.code}`;
+                return { blocked: true, reason, output: outputs.join("\n") };
+            }
+        }
+    }
+    return { blocked: false, output: outputs.join("\n") };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/settings/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/settings/hooks.ts"],"names":[],"mappings":"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"}

package/dist/settings/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module settings — The unified `settings.json` driver for the Oxagen CLI.
+ *
+ * One hierarchical settings file (user → project → local) configures the CLI's
+ * model, environment, platform URL, tool permissions, and lifecycle hooks —
+ * the spine the MCP-client, agents, commands, and skills subsystems plug into.
+ *
+ * Public surface:
+ *   - loadSettings / getScopePaths / clearSettingsCache  — resolution
+ *   - applySettingsToEnv                                 — startup projection
+ *   - wrapToolsWithGate                                  — permission + hook gate
+ *   - runHooks                                           — lifecycle hook engine
+ *   - writeSettingsValue / writeStarterSettings          — `oxagen settings` writes
+ */
+export { oxagenSettingsSchema, permissionsSchema, hooksSchema, HOOK_EVENTS, type OxagenSettings, type Permissions, type PermissionMode, type Hooks, type HookMatcher, type HookAction, type HookEvent, } from "./schema.js";
+export { loadSettings, getScopePaths, clearSettingsCache, type ResolvedSettings, type ResolvedScopeFile, type ResolveSettingsOptions, type SettingsScope, } from "./resolve.js";
+export { applySettingsToEnv, type AppliedSettingsEnv } from "./runtime.js";
+export { wrapToolsWithGate, type ToolGateContext } from "./gate.js";
+export { runHooks, type HookPayload, type HookRunOutcome } from "./hooks.js";
+export { evaluateLocalPermission, parseRule, type LocalPermissionResult, } from "./permissions-gate.js";
+export { writeSettingsValue, writeStarterSettings, readScopeDoc, writeScopeDoc, SETTABLE_KEYS, type WriteValueOptions, type InitOptions, } from "./write.js";
+export { writeMcpServer, removeMcpServer, setMcpServerDisabled, findServerScope, type WriteMcpServerOptions, type McpMutateOptions, } from "./mcp-write.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/settings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/settings/index.js

@@ -0,0 +1,23 @@
+/**
+ * @module settings — The unified `settings.json` driver for the Oxagen CLI.
+ *
+ * One hierarchical settings file (user → project → local) configures the CLI's
+ * model, environment, platform URL, tool permissions, and lifecycle hooks —
+ * the spine the MCP-client, agents, commands, and skills subsystems plug into.
+ *
+ * Public surface:
+ *   - loadSettings / getScopePaths / clearSettingsCache  — resolution
+ *   - applySettingsToEnv                                 — startup projection
+ *   - wrapToolsWithGate                                  — permission + hook gate
+ *   - runHooks                                           — lifecycle hook engine
+ *   - writeSettingsValue / writeStarterSettings          — `oxagen settings` writes
+ */
+export { oxagenSettingsSchema, permissionsSchema, hooksSchema, HOOK_EVENTS, } from "./schema.js";
+export { loadSettings, getScopePaths, clearSettingsCache, } from "./resolve.js";
+export { applySettingsToEnv } from "./runtime.js";
+export { wrapToolsWithGate } from "./gate.js";
+export { runHooks } from "./hooks.js";
+export { evaluateLocalPermission, parseRule, } from "./permissions-gate.js";
+export { writeSettingsValue, writeStarterSettings, readScopeDoc, writeScopeDoc, SETTABLE_KEYS, } from "./write.js";
+export { writeMcpServer, removeMcpServer, setMcpServerDisabled, findServerScope, } from "./mcp-write.js";
+//# sourceMappingURL=index.js.map

package/dist/settings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,WAAW,EACX,WAAW,GAQZ,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,GAKnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,kBAAkB,EAA2B,MAAM,cAAc,CAAC;AAE3E,OAAO,EAAE,iBAAiB,EAAwB,MAAM,WAAW,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAyC,MAAM,YAAY,CAAC;AAE7E,OAAO,EACL,uBAAuB,EACvB,SAAS,GAEV,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,aAAa,GAGd,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,eAAe,GAGhB,MAAM,gBAAgB,CAAC"}

package/dist/settings/mcp-write.d.ts

@@ -0,0 +1,41 @@
+/**
+ * mcp-write.ts — Writers for `oxagen mcp add/remove/enable/disable`.
+ *
+ * MCP servers live in the `mcpServers` map of a single scope file. `add` writes
+ * to a chosen scope (default project); `remove`/`enable`/`disable` auto-detect
+ * which scope defines the server (highest precedence first) unless a scope is
+ * given. Every write validates the whole document against the schema first.
+ */
+import type { McpServerConfig } from "@oxagen/mcp-config/schema";
+import { type SettingsScope, type ResolveSettingsOptions } from "./resolve.js";
+type Ctx = Pick<ResolveSettingsOptions, "cwd" | "userSettingsPath" | "projectDirName">;
+/** Find the highest-precedence scope that defines a server, if any. */
+export declare function findServerScope(name: string, ctx?: Ctx): {
+    scope: SettingsScope;
+    path: string;
+} | null;
+export interface WriteMcpServerOptions extends Ctx {
+    scope?: SettingsScope;
+    name: string;
+    config: McpServerConfig;
+}
+/** Add or replace an MCP server in a scope file (default: project). */
+export declare function writeMcpServer(opts: WriteMcpServerOptions): string;
+export interface McpMutateOptions extends Ctx {
+    scope?: SettingsScope;
+    name: string;
+}
+/** Remove a server. Returns the path touched and whether it existed. */
+export declare function removeMcpServer(opts: McpMutateOptions): {
+    path: string;
+    found: boolean;
+};
+/** Toggle a server's `disabled` flag. Returns the path and whether it existed. */
+export declare function setMcpServerDisabled(opts: McpMutateOptions & {
+    disabled: boolean;
+}): {
+    path: string;
+    found: boolean;
+};
+export {};
+//# sourceMappingURL=mcp-write.d.ts.map

package/dist/settings/mcp-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-write.d.ts","sourceRoot":"","sources":["../../src/settings/mcp-write.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAiB,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAI9F,KAAK,GAAG,GAAG,IAAI,CAAC,sBAAsB,EAAE,KAAK,GAAG,kBAAkB,GAAG,gBAAgB,CAAC,CAAC;AAQvF,uEAAuE;AACvE,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,GAAG,GAAE,GAAQ,GACZ;IAAE,KAAK,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAO/C;AAED,MAAM,WAAW,qBAAsB,SAAQ,GAAG;IAChD,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CASlE;AAED,MAAM,WAAW,gBAAiB,SAAQ,GAAG;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAYxF;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAalC"}