@oxagen/cli 0.5.0 → 0.6.1

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"}

package/dist/settings/mcp-write.js

@@ -0,0 +1,61 @@
+import { getScopePaths } from "./resolve.js";
+import { readScopeDoc, writeScopeDoc } from "./write.js";
+const SCOPE_ORDER = ["local", "project", "user"];
+function serversOf(doc) {
+    return doc["mcpServers"] ?? {};
+}
+/** Find the highest-precedence scope that defines a server, if any. */
+export function findServerScope(name, ctx = {}) {
+    const paths = getScopePaths(ctx);
+    for (const scope of SCOPE_ORDER) {
+        const path = paths[scope];
+        if (name in serversOf(readScopeDoc(path)))
+            return { scope, path };
+    }
+    return null;
+}
+/** Add or replace an MCP server in a scope file (default: project). */
+export function writeMcpServer(opts) {
+    const scope = opts.scope ?? "project";
+    const path = getScopePaths(opts)[scope];
+    const doc = readScopeDoc(path);
+    const servers = serversOf(doc);
+    servers[opts.name] = opts.config;
+    doc["mcpServers"] = servers;
+    writeScopeDoc(path, doc);
+    return path;
+}
+/** Remove a server. Returns the path touched and whether it existed. */
+export function removeMcpServer(opts) {
+    const target = opts.scope
+        ? { scope: opts.scope, path: getScopePaths(opts)[opts.scope] }
+        : findServerScope(opts.name, opts);
+    if (!target)
+        return { path: getScopePaths(opts).project, found: false };
+    const doc = readScopeDoc(target.path);
+    const servers = serversOf(doc);
+    if (!(opts.name in servers))
+        return { path: target.path, found: false };
+    delete servers[opts.name];
+    doc["mcpServers"] = servers;
+    writeScopeDoc(target.path, doc);
+    return { path: target.path, found: true };
+}
+/** Toggle a server's `disabled` flag. Returns the path and whether it existed. */
+export function setMcpServerDisabled(opts) {
+    const target = opts.scope
+        ? { scope: opts.scope, path: getScopePaths(opts)[opts.scope] }
+        : findServerScope(opts.name, opts);
+    if (!target)
+        return { path: getScopePaths(opts).project, found: false };
+    const doc = readScopeDoc(target.path);
+    const servers = serversOf(doc);
+    const existing = servers[opts.name];
+    if (!existing)
+        return { path: target.path, found: false };
+    servers[opts.name] = { ...existing, disabled: opts.disabled };
+    doc["mcpServers"] = servers;
+    writeScopeDoc(target.path, doc);
+    return { path: target.path, found: true };
+}
+//# sourceMappingURL=mcp-write.js.map

package/dist/settings/mcp-write.js.map

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

package/dist/settings/permissions-gate.d.ts

@@ -0,0 +1,19 @@
+import type { Permissions } from "./schema.js";
+export interface LocalPermissionResult {
+    decision: "allow" | "deny";
+    reason: string;
+    /** The rule string that produced an explicit allow/deny, if any. */
+    rule?: string;
+}
+/** The canonical permission name for a tool (e.g. read_file → Read; mcp tools unchanged). */
+export declare function canonicalToolName(toolName: string): string;
+interface ParsedRule {
+    tool: string;
+    pattern?: string;
+}
+/** Parse "Bash(git*)" → { tool: "Bash", pattern: "git*" }; "Edit" → { tool: "Edit" }. */
+export declare function parseRule(rule: string): ParsedRule;
+/** Evaluate whether a local tool call is permitted under the resolved permissions. */
+export declare function evaluateLocalPermission(toolName: string, input: unknown, permissions: Permissions | undefined): LocalPermissionResult;
+export {};
+//# sourceMappingURL=permissions-gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"permissions-gate.d.ts","sourceRoot":"","sources":["../../src/settings/permissions-gate.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA0BD,6FAA6F;AAC7F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D;AASD,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAKlD;AAYD,sFAAsF;AACtF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,WAAW,GAAG,SAAS,GACnC,qBAAqB,CAyBvB"}

package/dist/settings/permissions-gate.js

@@ -0,0 +1,103 @@
+/**
+ * permissions-gate.ts — Evaluates `settings.permissions` for the agent's local
+ * tools (read_file/write_file/edit_file/bash/…).
+ *
+ * Rules use Claude Code's syntax: a canonical tool name, optionally narrowed by
+ * a glob over the call's "subject" (the command for Bash, the path for a write,
+ * the pattern for a search):
+ *
+ *   "Bash"             any shell command
+ *   "Bash(git push*)"  shell commands starting with "git push"
+ *   "Write(.env*)"     writes whose path matches ".env*"
+ *   "Edit"             any surgical edit
+ *
+ * Decision order (deny always wins, matching the MCP gate and Claude Code):
+ *   1. a `deny` rule matches            → deny
+ *   2. an `allow` rule matches          → allow
+ *   3. defaultMode "bypassPermissions"  → allow
+ *   4. defaultMode "deny"               → deny  (deny-by-default; only allow-listed pass)
+ *   5. otherwise (default/acceptEdits)  → allow
+ *
+ * When no `permissions` block is configured, every call is allowed — this
+ * preserves the CLI's historical "runs against your own repo" behavior until a
+ * user opts into gating.
+ */
+import { matchGlob } from "@oxagen/mcp-config/permissions";
+/** Local tool id → canonical permission name used in rule strings. */
+const CANONICAL = {
+    read_file: "Read",
+    list_dir: "Read",
+    glob: "Read",
+    grep: "Read",
+    code_graph: "Read",
+    write_file: "Write",
+    edit_file: "Edit",
+    bash: "Bash",
+};
+/** Local tool id → the input field used as the rule "subject". */
+const SUBJECT_FIELD = {
+    read_file: "path",
+    list_dir: "path",
+    glob: "pattern",
+    grep: "pattern",
+    code_graph: "query",
+    write_file: "path",
+    edit_file: "path",
+    bash: "command",
+};
+/** The canonical permission name for a tool (e.g. read_file → Read; mcp tools unchanged). */
+export function canonicalToolName(toolName) {
+    return CANONICAL[toolName] ?? toolName;
+}
+function subjectOf(toolName, input) {
+    const field = SUBJECT_FIELD[toolName];
+    if (!field || input === null || typeof input !== "object")
+        return "";
+    const value = input[field];
+    return typeof value === "string" ? value : "";
+}
+/** Parse "Bash(git*)" → { tool: "Bash", pattern: "git*" }; "Edit" → { tool: "Edit" }. */
+export function parseRule(rule) {
+    const trimmed = rule.trim();
+    const open = trimmed.indexOf("(");
+    if (open === -1 || !trimmed.endsWith(")"))
+        return { tool: trimmed };
+    return { tool: trimmed.slice(0, open).trim(), pattern: trimmed.slice(open + 1, -1).trim() };
+}
+function ruleMatches(rule, canonical, subject) {
+    const parsed = parseRule(rule);
+    // The tool token is glob-matched against the canonical name. For local tools
+    // this is an exact compare ("Bash" === "Bash"); for MCP tools it lets a rule
+    // like `mcp__github__*` match `mcp__github__create_issue`.
+    if (!matchGlob(parsed.tool, canonical))
+        return false;
+    if (parsed.pattern === undefined || parsed.pattern === "")
+        return true;
+    return matchGlob(parsed.pattern, subject);
+}
+/** Evaluate whether a local tool call is permitted under the resolved permissions. */
+export function evaluateLocalPermission(toolName, input, permissions) {
+    if (!permissions)
+        return { decision: "allow", reason: "no permissions configured" };
+    const canonical = CANONICAL[toolName] ?? toolName;
+    const subject = subjectOf(toolName, input);
+    for (const rule of permissions.deny ?? []) {
+        if (ruleMatches(rule, canonical, subject)) {
+            return { decision: "deny", reason: `denied by rule "${rule}"`, rule };
+        }
+    }
+    for (const rule of permissions.allow ?? []) {
+        if (ruleMatches(rule, canonical, subject)) {
+            return { decision: "allow", reason: `allowed by rule "${rule}"`, rule };
+        }
+    }
+    const mode = permissions.defaultMode ?? "default";
+    if (mode === "bypassPermissions") {
+        return { decision: "allow", reason: "defaultMode: bypassPermissions" };
+    }
+    if (mode === "deny") {
+        return { decision: "deny", reason: "defaultMode: deny (no allow rule matched)" };
+    }
+    return { decision: "allow", reason: `defaultMode: ${mode}` };
+}
+//# sourceMappingURL=permissions-gate.js.map

package/dist/settings/permissions-gate.js.map

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