@aexol/spectral 0.9.21 → 0.9.25

package/dist/agent/agents.d.ts

@@ -6,6 +6,7 @@
  *   ---
  *   name: my-agent
  *   description: What this agent does
+ *   mode: subagent          # or "primary" to inject into the main system prompt
  *   tools: read, grep, find, ls
  *   model: claude-haiku-4-5
  *   ---
@@ -16,9 +17,11 @@
  *   .spectral/agents/*.md             — Project-level (opt-in via agentScope)
  */
 export type AgentScope = "user" | "project" | "both";
+export type AgentMode = "primary" | "subagent";
 export interface AgentConfig {
     name: string;
     description: string;
+    mode: AgentMode;
     tools?: string[];
     model?: string;
     systemPrompt: string;
@@ -29,7 +32,20 @@ export interface AgentDiscoveryResult {
     agents: AgentConfig[];
     projectAgentsDir: string | null;
 }
-export declare function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult;
+export declare function discoverAgents(cwd: string, scope: AgentScope, agentDir?: string): AgentDiscoveryResult;
+export declare function discoverPrimaryAgent(cwd: string, scope?: AgentScope, agentDir?: string): AgentConfig | null;
+/**
+ * Prepend the primary agent's system prompt above the base system prompt.
+ *
+ * Used by the per-turn `before_agent_start` hook so the primary-agent
+ * toggle takes effect mid-session (on the next user message) rather than
+ * only at session start.
+ *
+ * - Returns the base unchanged when no primary agent is provided.
+ * - Idempotent: if the base already starts with the primary agent header,
+ *   the base is returned unchanged (guards against double-injection).
+ */
+export declare function injectPrimaryAgentPrompt(base: string | undefined, primaryAgent: Pick<AgentConfig, "name" | "description" | "systemPrompt"> | null): string | undefined;
 export declare function formatAgentList(agents: AgentConfig[], maxItems: number): {
     text: string;
     remaining: number;

package/dist/agent/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAyED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,oBAAoB,CAoBnF;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EAAE,EACrB,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAQrC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/agent/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AACrD,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AA2ED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EACjB,QAAQ,CAAC,EAAE,MAAM,GAChB,oBAAoB,CAoBtB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,KAAK,GAAE,UAAmB,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,WAAW,GAAG,IAAI,CAgBpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,YAAY,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,CAAC,GAAG,IAAI,GAC9E,MAAM,GAAG,SAAS,CAOpB;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EAAE,EACrB,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAQrC"}

package/dist/agent/agents.js

@@ -6,6 +6,7 @@
  *   ---
  *   name: my-agent
  *   description: What this agent does
+ *   mode: subagent          # or "primary" to inject into the main system prompt
  *   tools: read, grep, find, ls
  *   model: claude-haiku-4-5
  *   ---
@@ -17,6 +18,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import chalk from "chalk";
 import { getAgentDir, parseFrontmatter } from "../sdk/coding-agent/index.js";
 function loadAgentsFromDir(dir, source) {
     const agents = [];
@@ -51,9 +53,11 @@ function loadAgentsFromDir(dir, source) {
             ?.split(",")
             .map((t) => t.trim())
             .filter(Boolean);
+        const mode = frontmatter.mode === "primary" ? "primary" : "subagent";
         agents.push({
             name: frontmatter.name,
             description: frontmatter.description,
+            mode,
             tools: tools && tools.length > 0 ? tools : undefined,
             model: frontmatter.model,
             systemPrompt: body,
@@ -83,8 +87,8 @@ function findNearestProjectAgentsDir(cwd) {
         currentDir = parentDir;
     }
 }
-export function discoverAgents(cwd, scope) {
-    const userDir = path.join(getAgentDir(), "agents");
+export function discoverAgents(cwd, scope, agentDir) {
+    const userDir = path.join(agentDir ?? getAgentDir(), "agents");
     const projectAgentsDir = findNearestProjectAgentsDir(cwd);
     const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
     const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
@@ -105,6 +109,42 @@ export function discoverAgents(cwd, scope) {
     }
     return { agents: Array.from(agentMap.values()), projectAgentsDir };
 }
+export function discoverPrimaryAgent(cwd, scope = "both", agentDir) {
+    const { agents } = discoverAgents(cwd, scope, agentDir);
+    const primaries = agents.filter((a) => a.mode === "primary");
+    if (primaries.length === 0)
+        return null;
+    if (primaries.length > 1) {
+        // User-level primary wins over project-level primary; otherwise first wins.
+        const userPrimary = primaries.find((a) => a.source === "user");
+        const chosen = userPrimary ?? primaries[0];
+        console.warn(chalk.yellow(`Multiple primary agents found (${primaries.map((a) => a.name).join(", ")}). Using "${chosen.name}".`));
+        return chosen;
+    }
+    return primaries[0];
+}
+/**
+ * Prepend the primary agent's system prompt above the base system prompt.
+ *
+ * Used by the per-turn `before_agent_start` hook so the primary-agent
+ * toggle takes effect mid-session (on the next user message) rather than
+ * only at session start.
+ *
+ * - Returns the base unchanged when no primary agent is provided.
+ * - Idempotent: if the base already starts with the primary agent header,
+ *   the base is returned unchanged (guards against double-injection).
+ */
+export function injectPrimaryAgentPrompt(base, primaryAgent) {
+    if (!primaryAgent)
+        return base;
+    const header = `# Primary Agent: ${primaryAgent.name}\n\n${primaryAgent.description}`;
+    const block = `${header}\n\n${primaryAgent.systemPrompt}`;
+    if (!base)
+        return block;
+    if (base.startsWith(header))
+        return base;
+    return `${block}\n\n---\n\n${base}`;
+}
 export function formatAgentList(agents, maxItems) {
     if (agents.length === 0)
         return { text: "none", remaining: 0 };

package/dist/agent/index.d.ts

@@ -25,5 +25,7 @@
  *   - Access to observational memory via the recall tool
  */
 import { type ExtensionAPI } from "../sdk/coding-agent/index.js";
-export default function subagentExtension(ext: ExtensionAPI): void;
+export default function subagentExtension(ext: ExtensionAPI, opts?: {
+    disabledAgents?: string[];
+}): void;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,OAAO,EACN,KAAK,YAAY,EAEjB,MAAM,8BAA8B,CAAC;AAqetC,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAqTjE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAWH,OAAO,EACN,KAAK,YAAY,EAEjB,MAAM,8BAA8B,CAAC;AAuetC,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CA+UvG"}

package/dist/agent/index.js

@@ -28,6 +28,7 @@ import { agentLoop } from "../sdk/agent-core/index.js";
 import { StringEnum } from "../sdk/ai/index.js";
 import { Type } from "typebox";
 import { discoverAgents } from "./agents.js";
+import { loadAgentSettings } from "../server/handlers/agent-settings.js";
 // ---------------------------------------------------------------------------
 // Built-in tool resolution (no spawn needed — tools are registered in-process)
 // ---------------------------------------------------------------------------
@@ -175,7 +176,8 @@ async function mapWithConcurrencyLimit(items, concurrency, fn) {
 // Core — run a single subagent in-process via agentLoop
 // ---------------------------------------------------------------------------
 async function runSingleAgent(defaultCwd, agents, agentName, task, cwd, step, signal, onUpdate, makeDetails, ext, ctx) {
-    const agent = agents.find((a) => a.name === agentName);
+    const normalizedAgentName = agentName.replace(/^@/, "");
+    const agent = agents.find((a) => a.name === normalizedAgentName);
     if (!agent) {
         const available = agents.map((a) => `"${a.name}"`).join(", ") || "none";
         return {
@@ -355,8 +357,8 @@ const ChainItem = Type.Object({
     cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 });
 const AgentScopeSchema = StringEnum(["user", "project", "both"], {
-    description: 'Which agent directories to use. Default: "user". Use "both" to include project-local agents.',
-    default: "user",
+    description: 'Which agent directories to use. Default: "both" (user + project agents).',
+    default: "both",
 });
 const SubagentParams = Type.Object({
     agent: Type.Optional(Type.String({ description: "Name of the agent to invoke (for single mode)" })),
@@ -379,15 +381,15 @@ const SubagentParams = Type.Object({
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
-export default function subagentExtension(ext) {
+export default function subagentExtension(ext, opts) {
     ext.registerTool({
         name: "subagent",
         label: "Subagent",
         description: [
             "Delegate tasks to specialized subagents with isolated context.",
             "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder).",
-            'Default agent scope is "user" (from ~/.spectral/agent/agents).',
-            'To enable project-local agents in .spectral/agents, set agentScope: "both" (or "project").',
+            'Default agent scope is "both" (user agents from ~/.spectral/agent/agents + project agents from .spectral/agents).',
+            'Set agentScope: "user" or "project" to limit scope.'
         ].join(" "),
         promptSnippet: "Run a subagent to investigate, plan, review, or implement code changes",
         promptGuidelines: [
@@ -395,10 +397,36 @@ export default function subagentExtension(ext) {
         ],
         parameters: SubagentParams,
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
-            const agentScope = params.agentScope ?? "user";
+            // Re-load agent settings from disk on every call so that UI toggles
+            // (subagentsEnabled / disabledSubagents) take effect immediately on
+            // running sessions, not just on the next session start.
+            const liveSettings = loadAgentSettings(ctx.cwd);
+            if (!liveSettings.subagentsEnabled) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Subagents are disabled in agent settings. Enable subagents via the agent settings panel to delegate tasks.",
+                        },
+                    ],
+                    details: {
+                        mode: "single",
+                        agentScope: (params.agentScope ?? "both"),
+                        projectAgentsDir: null,
+                        results: [],
+                    },
+                };
+            }
+            const agentScope = params.agentScope ?? "both";
             const discovery = discoverAgents(ctx.cwd, agentScope);
-            const agents = discovery.agents;
-            const confirmProjectAgents = params.confirmProjectAgents ?? true;
+            // Merge registration-time disabled list (from session start) with the
+            // live disabled list (just read from disk) so both are honored.
+            const disabledSet = new Set([
+                ...(opts?.disabledAgents ?? []),
+                ...(liveSettings.disabledSubagents ?? []),
+            ]);
+            const agents = discovery.agents.filter((a) => !disabledSet.has(a.name));
+            const confirmProjectAgents = params.confirmProjectAgents ?? false;
             const hasChain = (params.chain?.length ?? 0) > 0;
             const hasTasks = (params.tasks?.length ?? 0) > 0;
             const hasSingle = Boolean(params.agent && params.task);
@@ -430,12 +458,12 @@ export default function subagentExtension(ext) {
                 const requestedAgentNames = new Set();
                 if (params.chain)
                     for (const step of params.chain)
-                        requestedAgentNames.add(step.agent);
+                        requestedAgentNames.add(step.agent.replace(/^@/, ""));
                 if (params.tasks)
                     for (const t of params.tasks)
-                        requestedAgentNames.add(t.agent);
+                        requestedAgentNames.add(t.agent.replace(/^@/, ""));
                 if (params.agent)
-                    requestedAgentNames.add(params.agent);
+                    requestedAgentNames.add(params.agent.replace(/^@/, ""));
                 const projectAgentsRequested = Array.from(requestedAgentNames)
                     .map((name) => agents.find((a) => a.name === name))
                     .filter((a) => a?.source === "project");

package/dist/cli.js

@@ -18,9 +18,15 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // ---- Read our own version ----------------------------------------------------
-const pkgPath = resolve(__dirname, "..", "package.json");
-const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-const VERSION = pkg.version;
+let VERSION = process.env.npm_package_version ?? "0.0.0";
+try {
+    const pkgPath = resolve(__dirname, "..", "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    VERSION = pkg.version;
+}
+catch {
+    // Standalone Bun binaries do not carry the source package.json.
+}
 const TAGLINE = "Coding agent that never sleeps";
 // ---- Branded helpers ---------------------------------------------------------
 function printVersion() {

package/dist/commands/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAsBH,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AASlE,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,OAAO,EAAmB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAerE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAazD;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6B9D;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,WAAW,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqWlF;AAiED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAa5E"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAsBH,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AASlE,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAGnE,OAAO,EAAmB,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAsBrE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAazD;AAED,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CA6B9D;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uCAAuC;IACvC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,qBAAqB,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IACpB,wDAAwD;IACxD,OAAO,EAAE,oBAAoB,CAAC;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,WAAW,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAsB,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsWlF;AAiED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAa5E"}

package/dist/commands/serve.js

@@ -28,7 +28,7 @@
  * in-process fake backend.
  */
 import { readFileSync } from "node:fs";
-import { homedir, hostname } from "node:os";
+import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getConfigDir } from "../config.js";
@@ -49,9 +49,17 @@ const DEFAULT_BACKEND_URL = "https://api.aexol.ai";
 function readPackageVersion() {
     // dist/commands/serve.js  →  ../../package.json
     // src/commands/serve.ts → ../../package.json (tsx / vitest)
-    const pkgPath = resolve(__dirname, "..", "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-    return pkg.version;
+    // In a Bun standalone binary the source tree is not present, so the
+    // package.json lookup below fails. Return a fallback version instead of
+    // crashing the serve process.
+    try {
+        const pkgPath = resolve(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version;
+    }
+    catch {
+        return process.env.npm_package_version ?? "0.0.0";
+    }
 }
 /**
  * Translate a backend HTTP(S) base URL to the relay WS(S) URL.
@@ -118,7 +126,7 @@ export function parseServeArgs(args) {
 }
 export async function runServe(opts = {}) {
     const cfg = await requireLogin();
-    const cwd = opts.cwd ?? homedir();
+    const cwd = opts.cwd ?? process.cwd();
     const version = readPackageVersion();
     const installSignalHandlers = opts.installSignalHandlers ?? true;
     const silent = opts.silent ?? false;
@@ -227,6 +235,7 @@ export async function runServe(opts = {}) {
                     store,
                     manager,
                     cwd,
+                    agentDir: getAgentDir(),
                     publishMetaEvent: deferredPublishMetaEvent,
                     mcpState: getLiveMcpState() ?? undefined,
                 }).then((response) => {

package/dist/relay/dispatcher.d.ts

@@ -48,7 +48,7 @@ import type { RelayClient } from "./client.js";
  * `id` is populated when the route had an `:id` placeholder.
  */
 interface RouteMatch {
-    route: "list_projects" | "create_project" | "update_project" | "delete_project" | "bind_studio" | "get_project_observations" | "list_project_sessions" | "create_session" | "get_session" | "update_session" | "delete_session" | "get_session_memory" | "get_session_memory_details" | "compact_session" | "remember_and_delete_session" | "fork_session" | "list_path_autocomplete" | "pick_directory" | "search_project_files" | "enqueue_prompt" | "get_prompt_queue" | "remove_prompt" | "clear_prompt_queue" | "list_mcp_status" | "get_settings" | "put_settings";
+    route: "list_projects" | "create_project" | "update_project" | "delete_project" | "bind_studio" | "get_project_observations" | "list_project_sessions" | "create_session" | "get_session" | "update_session" | "delete_session" | "get_session_memory" | "get_session_memory_details" | "compact_session" | "remember_and_delete_session" | "fork_session" | "list_path_autocomplete" | "pick_directory" | "search_project_files" | "enqueue_prompt" | "get_prompt_queue" | "remove_prompt" | "clear_prompt_queue" | "list_mcp_status" | "get_settings" | "put_settings" | "get_agent_settings" | "put_agent_settings" | "list_agents";
     id?: string;
     /** Parsed query params, if the path carried a `?...` suffix. */
     query?: URLSearchParams;
@@ -79,6 +79,8 @@ export interface RestRequestDeps {
     manager: SessionStreamManager;
     /** Working directory for this machine. Used by settings persistence. Defaults to homedir. */
     cwd?: string;
+    /** Agent config dir (`~/.spectral/agent` by default). Passed through to agent-settings persistence. */
+    agentDir?: string;
     /** Optional logger for unexpected errors. Defaults to console.error. */
     logger?: {
         error: (...args: unknown[]) => void;

package/dist/relay/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/relay/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,uBAAuB,CAAC;AAI/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAuCzD,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACX,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAO/C;;;GAGG;AACH,UAAU,UAAU;IAClB,KAAK,EACD,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,GAChB,aAAa,GACb,0BAA0B,GAC1B,uBAAuB,GACvB,gBAAgB,GAChB,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,oBAAoB,GACpB,4BAA4B,GAC5B,iBAAiB,GACjB,6BAA6B,GAC7B,cAAc,GACd,wBAAwB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,gBAAgB,GAChB,kBAAkB,GAClB,eAAe,GACf,oBAAoB,GACpB,iBAAiB,GACjB,cAAc,GACd,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,aAAa,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,IAAI,CAoJnB;AAMD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,6FAA6F;IAC7F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;IACjD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAiD5B;AA6TD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,2DAA2D;IAC3D,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;;;OASG;IACH,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,yEAAyE;IACzE,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AA8BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAsIN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAuDN;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,GACxF,IAAI,CAEN;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,oBAAoB,EAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,GACnC,IAAI,CASN;AAMD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IACjC,sDAAsD;IACtD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,IAAI,CAQN"}

package/dist/relay/dispatcher.js

@@ -47,6 +47,7 @@ import { handleSearchProjectFiles } from "../server/handlers/files-search.js";
 import { handleBindStudioProject, handleCreateProject, handleDeleteProject, handleGetProjectObservations, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
 import { handleCompactSession, handleCreateSession, handleDeleteSession, handleForkSession, handleRememberAndDeleteSession, handleGetSessionDetail, handleGetSessionMemoryDetails, handleGetSessionMemoryStatus, handleUpdateSession, } from "../server/handlers/sessions.js";
 import { handleClearPromptQueue, handleEnqueuePrompt, handleGetPromptQueue, handleRemovePrompt, } from "../server/handlers/queue.js";
+import { handleGetAgentSettings, handleListAgents, handlePutAgentSettings, } from "../server/handlers/agent-settings.js";
 import { handleGetSettings, handlePutSettings, } from "../server/handlers/settings.js";
 import { shutdownState } from "../server/shutdown.js";
 import { handleAutoResearch } from "./auto-research.js";
@@ -76,6 +77,20 @@ export function matchRoute(method, path) {
             return { route: "put_settings" };
         return null;
     }
+    // /api/agent-settings
+    if (cleanPath === "/api/agent-settings") {
+        if (method === "GET")
+            return { route: "get_agent_settings" };
+        if (method === "PUT")
+            return { route: "put_agent_settings" };
+        return null;
+    }
+    // /api/agents
+    if (cleanPath === "/api/agents") {
+        if (method === "GET")
+            return { route: "list_agents", query };
+        return null;
+    }
     // /api/paths/autocomplete
     if (cleanPath === "/api/paths/autocomplete") {
         if (method === "GET")
@@ -451,6 +466,14 @@ async function dispatchRoute(match, body, deps) {
             return handleGetSettings(deps.cwd ?? homedir());
         case "put_settings":
             return handlePutSettings(deps.cwd ?? homedir(), asObject(body));
+        case "get_agent_settings":
+            return handleGetAgentSettings(deps.cwd ?? homedir(), deps.agentDir);
+        case "put_agent_settings":
+            return handlePutAgentSettings(deps.cwd ?? homedir(), asObject(body), deps.agentDir);
+        case "list_agents": {
+            const agentCwd = match.query?.get("cwd") || deps.cwd || homedir();
+            return handleListAgents(agentCwd, deps.agentDir);
+        }
     }
 }
 /**

package/dist/sdk/coding-agent/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/sdk/coding-agent/config.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,UAAU,qBAAqB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;CAChC;AAsBD,wBAAgB,mBAAmB,IAAI,aAAa,CAcnD;AAyKD,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,iBAAiB,SAAc,GAC7B,iBAAiB,GAAG,SAAS,CAO/B;AAED,wBAAgB,mCAAmC,CAClD,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,iBAAiB,SAAc,GAC7B,MAAM,CAUR;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAOhE;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAiBtC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED;;;;+BAI+B;AAC/B,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,4BAA4B;AAC5B,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,iCAAiC;AACjC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,qCAAqC;AACrC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,+BAA+B;AAC/B,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAoBD,eAAO,MAAM,YAAY,EAAE,MAA+B,CAAC;AAC3D,eAAO,MAAM,QAAQ,EAAE,MAAyC,CAAC;AACjE,eAAO,MAAM,SAAS,EAAE,MAAmD,CAAC;AAC5E,eAAO,MAAM,eAAe,EAAE,MAAqD,CAAC;AACpF,eAAO,MAAM,OAAO,EAAE,MAA+B,CAAC;AAGtD,eAAO,MAAM,aAAa,QAA+C,CAAC;AAC1E,eAAO,MAAM,eAAe,QAAuD,CAAC;AAEpF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAID,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGxD;AAMD,gEAAgE;AAChE,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,8BAA8B;AAC9B,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,4BAA4B;AAC5B,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gCAAgC;AAChC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,kCAAkC;AAClC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,sDAAsD;AACtD,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,qCAAqC;AACrC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iCAAiC;AACjC,wBAAgB,eAAe,IAAI,MAAM,CAExC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/sdk/coding-agent/config.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhE,UAAU,qBAAqB;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAkB,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,qBAAqB,EAAE,CAAC;CAChC;AAsBD,wBAAgB,mBAAmB,IAAI,aAAa,CAcnD;AAyKD,wBAAgB,oBAAoB,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,iBAAiB,SAAc,GAC7B,iBAAiB,GAAG,SAAS,CAO/B;AAED,wBAAgB,mCAAmC,CAClD,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,iBAAiB,SAAc,GAC7B,MAAM,CAUR;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAOhE;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAiBtC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAKrC;AAED;;;;+BAI+B;AAC/B,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,4BAA4B;AAC5B,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,iCAAiC;AACjC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,qCAAqC;AACrC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,+BAA+B;AAC/B,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AA4BD,eAAO,MAAM,YAAY,EAAE,MAA+B,CAAC;AAC3D,eAAO,MAAM,QAAQ,EAAE,MAAyC,CAAC;AACjE,eAAO,MAAM,SAAS,EAAE,MAAmD,CAAC;AAC5E,eAAO,MAAM,eAAe,EAAE,MAAqD,CAAC;AACpF,eAAO,MAAM,OAAO,EAAE,MAA+B,CAAC;AAGtD,eAAO,MAAM,aAAa,QAA+C,CAAC;AAC1E,eAAO,MAAM,eAAe,QAAuD,CAAC;AAEpF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAID,6CAA6C;AAC7C,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGxD;AAMD,gEAAgE;AAChE,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,iDAAiD;AACjD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,8BAA8B;AAC9B,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,4BAA4B;AAC5B,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,gCAAgC;AAChC,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,kCAAkC;AAClC,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,sDAAsD;AACtD,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,qCAAqC;AACrC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,iCAAiC;AACjC,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/sdk/coding-agent/config.js

@@ -268,7 +268,16 @@ export function getExamplesPath() {
 export function getChangelogPath() {
     return resolve(join(getPackageDir(), "CHANGELOG.md"));
 }
-const pkg = JSON.parse(readFileSync(getPackageJsonPath(), "utf-8"));
+function readPackageJson() {
+    try {
+        return JSON.parse(readFileSync(getPackageJsonPath(), "utf-8"));
+    }
+    catch {
+        // Standalone Bun binaries do not carry the source package.json.
+        return {};
+    }
+}
+const pkg = readPackageJson();
 const spectralConfigName = pkg.spectralConfig?.name;
 export const PACKAGE_NAME = pkg.name || "index.ts";
 export const APP_NAME = spectralConfigName || "spectral";

package/dist/server/agent-bridge.d.ts

@@ -49,6 +49,7 @@
  *  instance is reused across `prompt()` calls).
  */
 import { type AgentSessionEvent } from "../sdk/coding-agent/index.js";
+import { type AgentSettings } from "./handlers/agent-settings.js";
 import { fetchAllowedModels as defaultFetchAllowedModels } from "../relay/models-fetch.js";
 import type { SessionMemorySnapshot } from "./storage.js";
 import type { ImageAttachment, ServerEvent, WireMessage } from "./wire.js";
@@ -116,6 +117,13 @@ export interface AgentBridgeOptions {
      * can run without a live backend.
      */
     fetchAllowedModels?: FetchAllowedModelsFn;
+    /**
+     * Agent-behavior toggles (primary-agent injection, subagent tool).
+     * When omitted, settings are loaded from `settings.json` at `start()`
+     * time. Changes take effect on the next session/bridge — a running
+     * session is not hot-reloaded.
+     */
+    agentSettings?: AgentSettings;
 }
 export declare class AgentBridge {
     private session?;

package/dist/server/agent-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/agent-bridge.js

@@ -55,6 +55,8 @@ import { existsSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import aexolMcpExtension from "../extensions/aexol-mcp.js";
+import { discoverPrimaryAgent, injectPrimaryAgentPrompt } from "../agent/agents.js";
+import { loadAgentSettings } from "./handlers/agent-settings.js";
 import kanbanBridgeExtension from "../extensions/kanban-bridge.js";
 import spectralVisionExtension from "../extensions/spectral-vision-fallback.js";
 import subagentExt from "../agent/index.js";
@@ -417,7 +419,30 @@ export class AgentBridge {
     async start() {
         if (this.disposed)
             throw new Error("AgentBridge already disposed");
-        const extensionFactories = [aexolMcpExtension, kanbanBridgeExtension, async (ext) => { spectralVisionExtension(ext); }, async (ext) => { subagentExt(ext); }, async (ext) => { designerExtension(ext); }, async (ext) => { observationalMemory(ext); }];
+        const extensionFactories = [
+            // Primary-agent prompt is injected per-turn via before_agent_start so the
+            // primaryAgentEnabled toggle takes effect mid-session (next user message).
+            async (ext) => {
+                ext.on("before_agent_start", (event) => {
+                    const settings = loadAgentSettings(this.opts.cwd, this.opts.agentDir);
+                    if (!settings.primaryAgentEnabled)
+                        return;
+                    const primaryAgent = discoverPrimaryAgent(this.opts.cwd, "both", this.opts.agentDir);
+                    const injected = injectPrimaryAgentPrompt(event.systemPrompt, primaryAgent);
+                    if (injected === event.systemPrompt)
+                        return;
+                    return { systemPrompt: injected };
+                });
+            },
+            aexolMcpExtension, kanbanBridgeExtension, async (ext) => { spectralVisionExtension(ext); }, async (ext) => { designerExtension(ext); }, async (ext) => { observationalMemory(ext); }
+        ];
+        // Agent-behavior toggles. Loaded once at bridge construction so changes
+        // take effect on the next session (not mid-turn).
+        const agentSettings = this.opts.agentSettings ?? loadAgentSettings(this.opts.cwd, this.opts.agentDir);
+        // Only register the subagent tool when the toggle is enabled.
+        if (agentSettings.subagentsEnabled) {
+            extensionFactories.splice(4, 0, async (ext) => { subagentExt(ext, { disabledAgents: agentSettings.disabledSubagents }); });
+        }
         // Load spectral-mcp-adapter via jiti so tsc never crawls its .ts files in
         // node_modules. The static `import` was causing tsc to type-check
         // spectral-mcp-adapter's source and fail the build on its type errors.
@@ -448,6 +473,9 @@ export class AgentBridge {
         // .opencode/skills and .aexol/skills so OpenCode/Codex/Aexol skills
         // work out of the box.
         const extraSkillPaths = collectAncestorSkillDirs(this.opts.cwd, [".opencode/skills", ".aexol/skills"]);
+        // Primary-agent prompt injection happens per-turn via the before_agent_start
+        // extension registered above, so the primaryAgentEnabled toggle takes effect
+        // mid-session (on the next user message) rather than only at session start.
         const resourceLoader = new DefaultResourceLoader({
             cwd: this.opts.cwd,
             agentDir: this.opts.agentDir ?? `${process.env.HOME ?? ""}/.spectral/agent`,

package/dist/server/handlers/agent-settings.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent-behavior toggles stored under the `agent` namespace in
+ * `settings.json`. These control whether the primary-agent system prompt
+ * is injected and whether the `subagent` tool is registered.
+ *
+ * Both default to `true` so existing behaviour is preserved when the
+ * namespace is absent.
+ */
+export interface AgentSettings {
+    primaryAgentEnabled: boolean;
+    subagentsEnabled: boolean;
+    /** Names of individual subagents that have been explicitly disabled. */
+    disabledSubagents: string[];
+}
+export declare const AGENT_SETTINGS_DEFAULTS: AgentSettings;
+export interface PutAgentSettingsInput {
+    primaryAgentEnabled?: unknown;
+    subagentsEnabled?: unknown;
+    disabledSubagents?: unknown;
+}
+export interface PutAgentSettingsOutput extends AgentSettings {
+    ok: true;
+}
+/**
+ * Load agent settings by merging defaults ← global ← project overrides.
+ * Mirrors the precedence pattern used by `loadConfig` for observational
+ * memory config.
+ */
+export declare function loadAgentSettings(cwd: string, agentDir?: string): AgentSettings;
+export declare function handleGetAgentSettings(cwd: string, agentDir?: string): AgentSettings;
+/**
+ * Persist a partial update to the `agent` namespace in the **global**
+ * `settings.json` (per-machine, matching the existing memory-settings
+ * behaviour). Project-level overrides are read-only from the REST API.
+ *
+ * Only boolean values are accepted for the two known keys; anything else
+ * is a `400 BadRequestError`.
+ */
+export declare function handlePutAgentSettings(cwd: string, body: PutAgentSettingsInput, agentDir?: string): PutAgentSettingsOutput;
+export interface AgentInfo {
+    name: string;
+    description: string;
+    mode: string;
+    source: string;
+}
+export declare function handleListAgents(cwd: string, agentDir?: string): {
+    agents: AgentInfo[];
+};
+//# sourceMappingURL=agent-settings.d.ts.map

package/dist/server/handlers/agent-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/agent-settings.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,eAAO,MAAM,uBAAuB,EAAE,aAIrC,CAAC;AAKF,MAAM,WAAW,qBAAqB;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,EAAE,EAAE,IAAI,CAAC;CACV;AA+BD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAQf;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAEf;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,CAAC,EAAE,MAAM,GAChB,sBAAsB,CAuCxB;AAMD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAUzB"}

package/dist/server/handlers/agent-settings.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "../../sdk/coding-agent/index.js";
+import { discoverAgents } from "../../agent/agents.js";
+import { BadRequestError } from "./errors.js";
+import { withSettingsLock } from "./settings-lock.js";
+export const AGENT_SETTINGS_DEFAULTS = {
+    primaryAgentEnabled: true,
+    subagentsEnabled: true,
+    disabledSubagents: [],
+};
+const AGENT_NAMESPACE = "agent";
+const ALLOWED_KEYS = new Set(["primaryAgentEnabled", "subagentsEnabled", "disabledSubagents"]);
+/**
+ * Read the `agent` namespace from a single `settings.json` file.
+ * Returns `{}` when the file or namespace is absent or unparseable.
+ */
+function readAgentNamespace(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf-8"));
+        const ns = raw[AGENT_NAMESPACE];
+        if (!ns || typeof ns !== "object")
+            return {};
+        const obj = ns;
+        const result = {};
+        if (typeof obj.primaryAgentEnabled === "boolean") {
+            result.primaryAgentEnabled = obj.primaryAgentEnabled;
+        }
+        if (typeof obj.subagentsEnabled === "boolean") {
+            result.subagentsEnabled = obj.subagentsEnabled;
+        }
+        if (Array.isArray(obj.disabledSubagents)) {
+            result.disabledSubagents = obj.disabledSubagents.filter((s) => typeof s === "string");
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Load agent settings by merging defaults ← global ← project overrides.
+ * Mirrors the precedence pattern used by `loadConfig` for observational
+ * memory config.
+ */
+export function loadAgentSettings(cwd, agentDir) {
+    const globalPath = join(agentDir ?? getAgentDir(), "settings.json");
+    const projectPath = join(cwd, ".spectral", "settings.json");
+    return {
+        ...AGENT_SETTINGS_DEFAULTS,
+        ...readAgentNamespace(globalPath),
+        ...readAgentNamespace(projectPath),
+    };
+}
+export function handleGetAgentSettings(cwd, agentDir) {
+    return loadAgentSettings(cwd, agentDir);
+}
+/**
+ * Persist a partial update to the `agent` namespace in the **global**
+ * `settings.json` (per-machine, matching the existing memory-settings
+ * behaviour). Project-level overrides are read-only from the REST API.
+ *
+ * Only boolean values are accepted for the two known keys; anything else
+ * is a `400 BadRequestError`.
+ */
+export function handlePutAgentSettings(cwd, body, agentDir) {
+    const patch = {};
+    for (const key of ["primaryAgentEnabled", "subagentsEnabled"]) {
+        if (body[key] !== undefined) {
+            if (typeof body[key] !== "boolean") {
+                throw new BadRequestError(`agent setting "${key}" must be a boolean, got ${typeof body[key]}`);
+            }
+            patch[key] = body[key];
+        }
+    }
+    // disabledSubagents is a full-replacement string array
+    if (body.disabledSubagents !== undefined) {
+        if (!Array.isArray(body.disabledSubagents) ||
+            !body.disabledSubagents.every((s) => typeof s === "string")) {
+            throw new BadRequestError(`agent setting "disabledSubagents" must be a string array`);
+        }
+        patch.disabledSubagents = body.disabledSubagents;
+    }
+    if (Object.keys(patch).length === 0) {
+        throw new BadRequestError(`agent settings body must include at least one of: ${[...ALLOWED_KEYS].join(", ")}`);
+    }
+    // Persist to the global file only. The lock is shared with the
+    // observational-memory handler so concurrent writes cannot corrupt
+    // each other's namespace.
+    withSettingsLock({ agentDir, namespace: AGENT_NAMESPACE }, (current) => {
+        return { ...current, ...patch };
+    });
+    // Return the fully resolved settings (global + project merge) so the
+    // caller sees the effective state, not just what we wrote.
+    return { ok: true, ...loadAgentSettings(cwd, agentDir) };
+}
+export function handleListAgents(cwd, agentDir) {
+    const { agents } = discoverAgents(cwd, "both", agentDir);
+    return {
+        agents: agents.map((a) => ({
+            name: a.name,
+            description: a.description,
+            mode: a.mode,
+            source: a.source,
+        })),
+    };
+}

package/dist/server/handlers/settings-lock.d.ts

@@ -0,0 +1,36 @@
+import { BadRequestError } from "./errors.js";
+/**
+ * Acquire a synchronous file lock with bounded retries on `ELOCKED`.
+ *
+ * Shared by all settings handlers that persist to `settings.json` so
+ * concurrent writes from different namespaces (observational-memory,
+ * agent) cannot interleave and corrupt the file.
+ */
+export declare function acquireLockSyncWithRetry(path: string): () => void;
+/**
+ * Resolve the `settings.json` path for a given agent directory.
+ * Falls back to the default agent dir (`~/.spectral/agent`) when
+ * `agentDir` is omitted.
+ */
+export declare function settingsFilePath(agentDir?: string): string;
+/**
+ * Read-persist cycle for a single namespace inside `settings.json`,
+ * guarded by a file-level lock so concurrent writes across namespaces
+ * are serialized.
+ *
+ * - Reads the **entire** file (preserving all top-level keys).
+ * - Extracts `parsed[namespace]` (or `{}` if absent).
+ * - Passes the current namespace object to `fn`. If `fn` returns
+ *   `undefined`, no write occurs. Otherwise the returned object
+ *   replaces the namespace and the full file is written back.
+ *
+ * The lock is acquired **before** writing (and also before reading if
+ * the file already exists) so we never observe a half-written file.
+ */
+export declare function withSettingsLock(opts: {
+    agentDir?: string;
+    namespace: string;
+}, fn: (current: Record<string, unknown>) => Record<string, unknown> | undefined): void;
+/** Re-exported for handler convenience. */
+export { BadRequestError };
+//# sourceMappingURL=settings-lock.d.ts.map

package/dist/server/handlers/settings-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-lock.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings-lock.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAsBjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAC9C,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5E,IAAI,CA4BN;AAED,2CAA2C;AAC3C,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/server/handlers/settings-lock.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import lockfile from "proper-lockfile";
+import { getAgentDir } from "../../sdk/coding-agent/index.js";
+import { BadRequestError } from "./errors.js";
+/**
+ * Acquire a synchronous file lock with bounded retries on `ELOCKED`.
+ *
+ * Shared by all settings handlers that persist to `settings.json` so
+ * concurrent writes from different namespaces (observational-memory,
+ * agent) cannot interleave and corrupt the file.
+ */
+export function acquireLockSyncWithRetry(path) {
+    const maxAttempts = 10;
+    const delayMs = 20;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return lockfile.lockSync(path, { realpath: false });
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null && "code" in error
+                ? String(error.code)
+                : undefined;
+            if (code !== "ELOCKED" || attempt === maxAttempts) {
+                throw error;
+            }
+            lastError = error;
+            const start = Date.now();
+            while (Date.now() - start < delayMs) {
+            }
+        }
+    }
+    throw lastError ?? new Error("Failed to acquire settings lock");
+}
+/**
+ * Resolve the `settings.json` path for a given agent directory.
+ * Falls back to the default agent dir (`~/.spectral/agent`) when
+ * `agentDir` is omitted.
+ */
+export function settingsFilePath(agentDir) {
+    return join(agentDir ?? getAgentDir(), "settings.json");
+}
+/**
+ * Read-persist cycle for a single namespace inside `settings.json`,
+ * guarded by a file-level lock so concurrent writes across namespaces
+ * are serialized.
+ *
+ * - Reads the **entire** file (preserving all top-level keys).
+ * - Extracts `parsed[namespace]` (or `{}` if absent).
+ * - Passes the current namespace object to `fn`. If `fn` returns
+ *   `undefined`, no write occurs. Otherwise the returned object
+ *   replaces the namespace and the full file is written back.
+ *
+ * The lock is acquired **before** writing (and also before reading if
+ * the file already exists) so we never observe a half-written file.
+ */
+export function withSettingsLock(opts, fn) {
+    const path = settingsFilePath(opts.agentDir);
+    const dir = dirname(path);
+    let release;
+    try {
+        const fileExists = existsSync(path);
+        if (fileExists) {
+            release = acquireLockSyncWithRetry(path);
+        }
+        const raw = fileExists ? readFileSync(path, "utf-8") : "{}";
+        const parsed = JSON.parse(raw);
+        const ns = (parsed[opts.namespace] ?? {});
+        const next = fn(ns);
+        if (next !== undefined) {
+            parsed[opts.namespace] = { ...ns, ...next };
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            if (!release) {
+                release = acquireLockSyncWithRetry(path);
+            }
+            writeFileSync(path, JSON.stringify(parsed, null, 2), "utf-8");
+        }
+    }
+    finally {
+        if (release) {
+            release();
+        }
+    }
+}
+/** Re-exported for handler convenience. */
+export { BadRequestError };

package/dist/server/handlers/settings.d.ts

@@ -1,14 +1,3 @@
-/**
- * Pure REST handler for `GET /api/settings` and `PUT /api/settings`.
- *
- * Settings are stored in the machine's global `settings.json` under the
- * `"observational-memory"` namespace (see `src/memory/config.ts`).
- *
- * GET  /api/settings                        → returns full observational-memory config
- * PUT  /api/settings                        → updates a single key via `{ key, value }` body
- *
- * All paths are machine-level — no session context needed.
- */
 export interface PutSettingsInput {
     key?: unknown;
     value?: unknown;

package/dist/server/handlers/settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAsFD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAShE;AAMD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,iBAAiB,CA0BnB"}
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../../src/server/handlers/settings.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AACD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,iBAAiB;IAChC,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAgBD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAShE;AACD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,GACrB,iBAAiB,CAoBnB"}

package/dist/server/handlers/settings.js

@@ -1,93 +1,19 @@
-/**
- * Pure REST handler for `GET /api/settings` and `PUT /api/settings`.
- *
- * Settings are stored in the machine's global `settings.json` under the
- * `"observational-memory"` namespace (see `src/memory/config.ts`).
- *
- * GET  /api/settings                        → returns full observational-memory config
- * PUT  /api/settings                        → updates a single key via `{ key, value }` body
- *
- * All paths are machine-level — no session context needed.
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import lockfile from "proper-lockfile";
-import { getAgentDir } from "../../sdk/coding-agent/index.js";
 import { loadConfig } from "../../memory/config.js";
 import { BadRequestError } from "./errors.js";
-/** Recognised setting keys (dot-separated path within the config object). */
+import { withSettingsLock } from "./settings-lock.js";
 const ALLOWED_KEYS = new Set([
     "observationThresholdTokens",
     "compactionThresholdTokens",
     "reflectionThresholdTokens",
 ]);
-/** Sane bounds for token thresholds. */
 const MIN_TOKENS = 1_000;
 const MAX_TOKENS = 1_000_000;
-// ---------------------------------------------------------------------------
-// File helpers (inlined to avoid pulling in the full SettingsManager)
-// ---------------------------------------------------------------------------
-function acquireLockSyncWithRetry(path) {
-    const maxAttempts = 10;
-    const delayMs = 20;
-    let lastError;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            return lockfile.lockSync(path, { realpath: false });
-        }
-        catch (error) {
-            const code = typeof error === "object" && error !== null && "code" in error
-                ? String(error.code)
-                : undefined;
-            if (code !== "ELOCKED" || attempt === maxAttempts) {
-                throw error;
-            }
-            lastError = error;
-            const start = Date.now();
-            while (Date.now() - start < delayMs) {
-                // busy-wait; synchronous by design
-            }
-        }
-    }
-    throw lastError ?? new Error("Failed to acquire settings lock");
-}
-/**
- * Atomically read-modify-write the global `settings.json` under the
- * `"observational-memory"` namespace.
- */
 function withObservationalMemoryLock(fn) {
-    const path = join(getAgentDir(), "settings.json");
-    const dir = dirname(path);
-    let release;
-    try {
-        const fileExists = existsSync(path);
-        if (fileExists) {
-            release = acquireLockSyncWithRetry(path);
-        }
-        const raw = fileExists ? readFileSync(path, "utf-8") : "{}";
-        const parsed = JSON.parse(raw);
-        const ns = (parsed["observational-memory"] ?? {});
-        const next = fn(ns);
-        if (next !== undefined) {
-            parsed["observational-memory"] = { ...ns, ...next };
-            if (!existsSync(dir)) {
-                mkdirSync(dir, { recursive: true });
-            }
-            if (!release) {
-                release = acquireLockSyncWithRetry(path);
-            }
-            writeFileSync(path, JSON.stringify(parsed, null, 2), "utf-8");
-        }
-    }
-    finally {
-        if (release) {
-            release();
-        }
-    }
+    withSettingsLock({ namespace: "observational-memory" }, (current) => {
+        const next = fn(current);
+        return next;
+    });
 }
-// ---------------------------------------------------------------------------
-// GET handler
-// ---------------------------------------------------------------------------
 export function handleGetSettings(cwd) {
     const config = loadConfig(cwd);
     return {
@@ -98,16 +24,11 @@ export function handleGetSettings(cwd) {
         debugLog: config.debugLog,
     };
 }
-// ---------------------------------------------------------------------------
-// PUT handler
-// ---------------------------------------------------------------------------
 export function handlePutSettings(cwd, body) {
-    // Validate key
     if (typeof body.key !== "string" || !ALLOWED_KEYS.has(body.key)) {
         throw new BadRequestError(`settings key must be one of: ${[...ALLOWED_KEYS].join(", ")}`);
     }
     const key = body.key;
-    // Validate value
     if (typeof body.value !== "number" || !Number.isInteger(body.value)) {
         throw new BadRequestError("settings value must be an integer");
     }
@@ -115,7 +36,6 @@ export function handlePutSettings(cwd, body) {
         throw new BadRequestError(`token threshold must be between ${MIN_TOKENS.toLocaleString()} and ${MAX_TOKENS.toLocaleString()}`);
     }
     const value = body.value;
-    // Persist
     withObservationalMemoryLock((current) => {
         return { ...current, [key]: value };
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.21",
+  "version": "0.9.25",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,