@dexto/agent-management 1.5.7 → 1.6.0

package/dist/plugins/validate-plugin.cjs

@@ -39,29 +39,14 @@ function validatePluginDirectory(pluginPath) {
   const errors = [];
   const warnings = [];
   let manifest;
-  let format;
   const absolutePath = path.isAbsolute(pluginPath) ? pluginPath : path.resolve(pluginPath);
   if (!(0, import_fs.existsSync)(absolutePath)) {
     errors.push(`Directory does not exist: ${absolutePath}`);
     return { valid: false, errors, warnings };
   }
-  const dextoPluginDir = path.join(absolutePath, ".dexto-plugin");
-  const claudePluginDir = path.join(absolutePath, ".claude-plugin");
-  let manifestPath;
-  if ((0, import_fs.existsSync)(dextoPluginDir)) {
-    manifestPath = path.join(dextoPluginDir, "plugin.json");
-    format = "dexto";
-  } else if ((0, import_fs.existsSync)(claudePluginDir)) {
-    manifestPath = path.join(claudePluginDir, "plugin.json");
-    format = "claude-code";
-  } else {
-    errors.push("Missing .dexto-plugin or .claude-plugin directory");
-    return { valid: false, errors, warnings };
-  }
+  const manifestPath = path.join(absolutePath, ".claude-plugin", "plugin.json");
   if (!(0, import_fs.existsSync)(manifestPath)) {
-    errors.push(
-      `Missing ${format === "dexto" ? ".dexto-plugin" : ".claude-plugin"}/plugin.json`
-    );
+    errors.push("Missing .claude-plugin/plugin.json");
     return { valid: false, errors, warnings };
   }
   try {
@@ -75,8 +60,7 @@ function validatePluginDirectory(pluginPath) {
       );
       return { valid: false, errors, warnings };
     }
-    const schema = format === "dexto" ? import_schemas.DextoPluginManifestSchema : import_schemas.PluginManifestSchema;
-    const result = schema.safeParse(parsed);
+    const result = import_schemas.PluginManifestSchema.safeParse(parsed);
     if (!result.success) {
       const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
       errors.push(`Schema validation failed: ${issues.join("; ")}`);
@@ -112,7 +96,6 @@ function validatePluginDirectory(pluginPath) {
   return {
     valid: errors.length === 0,
     manifest,
-    format,
     errors,
     warnings
   };
@@ -143,31 +126,18 @@ function checkDirectoryHasSkills(skillsDir) {
     return false;
   }
 }
-function tryLoadManifest(pluginPath, returnFormat) {
-  const dextoManifestPath = path.join(pluginPath, ".dexto-plugin", "plugin.json");
-  const claudeManifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
-  let manifestPath;
-  let format;
-  if ((0, import_fs.existsSync)(dextoManifestPath)) {
-    manifestPath = dextoManifestPath;
-    format = "dexto";
-  } else if ((0, import_fs.existsSync)(claudeManifestPath)) {
-    manifestPath = claudeManifestPath;
-    format = "claude-code";
-  } else {
+function tryLoadManifest(pluginPath) {
+  const manifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
+  if (!(0, import_fs.existsSync)(manifestPath)) {
     return null;
   }
   try {
     const content = (0, import_fs.readFileSync)(manifestPath, "utf-8");
     const parsed = JSON.parse(content);
-    const schema = format === "dexto" ? import_schemas.DextoPluginManifestSchema : import_schemas.PluginManifestSchema;
-    const result = schema.safeParse(parsed);
+    const result = import_schemas.PluginManifestSchema.safeParse(parsed);
     if (!result.success) {
       return null;
     }
-    if (returnFormat) {
-      return { manifest: result.data, format };
-    }
     return result.data;
   } catch {
     return null;

package/dist/plugins/validate-plugin.d.ts

@@ -4,24 +4,16 @@
  * Validates plugin directory structure and manifest.
  * Checks for required files, valid JSON, and schema compliance.
  *
- * Supports two plugin formats:
- * - .claude-plugin/plugin.json: Claude Code compatible format
- * - .dexto-plugin/plugin.json: Dexto-native format with extended features (preferred)
+ * Supports Claude Code compatible plugins:
+ * - .claude-plugin/plugin.json
  */
-import type { PluginValidationResult, PluginManifest, DextoPluginManifest, PluginFormat } from './types.js';
-/**
- * Extended validation result with plugin format
- */
-export interface ExtendedPluginValidationResult extends PluginValidationResult {
-    /** Plugin format detected */
-    format?: PluginFormat;
-}
+import type { PluginValidationResult, PluginManifest } from './types.js';
 /**
  * Validates a plugin directory structure and manifest.
  *
  * Checks:
  * 1. Directory exists
- * 2. .dexto-plugin/plugin.json OR .claude-plugin/plugin.json exists (Dexto format preferred)
+ * 2. .claude-plugin/plugin.json exists
  * 3. plugin.json is valid JSON
  * 4. plugin.json matches schema (name is required)
  * 5. At least one command or skill exists (warning if none)
@@ -29,25 +21,15 @@ export interface ExtendedPluginValidationResult extends PluginValidationResult {
  * @param pluginPath Absolute or relative path to plugin directory
  * @returns Validation result with manifest (if valid), errors, and warnings
  */
-export declare function validatePluginDirectory(pluginPath: string): ExtendedPluginValidationResult;
-/**
- * Result of manifest loading with format information
- */
-export interface LoadedManifestResult {
-    manifest: PluginManifest | DextoPluginManifest;
-    format: PluginFormat;
-}
+export declare function validatePluginDirectory(pluginPath: string): PluginValidationResult;
 /**
  * Attempts to load and validate a plugin manifest from a directory.
  * Returns null if the manifest doesn't exist, is invalid JSON, or fails schema validation.
  *
- * Checks for .dexto-plugin first (preferred), then falls back to .claude-plugin.
- *
  * This is a shared utility used by discover-plugins, list-plugins, and import-plugin.
  *
  * @param pluginPath Absolute path to the plugin directory
- * @returns Validated manifest with format or null if not a valid plugin
+ * @returns Validated manifest or null if not a valid plugin
  */
 export declare function tryLoadManifest(pluginPath: string): PluginManifest | null;
-export declare function tryLoadManifest(pluginPath: string, returnFormat: true): LoadedManifestResult | null;
 //# sourceMappingURL=validate-plugin.d.ts.map

package/dist/plugins/validate-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/validate-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EACR,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,YAAY,EACf,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,sBAAsB;IAC1E,6BAA6B;IAC7B,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,8BAA8B,CAyG1F;AAuCD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,EAAE,cAAc,GAAG,mBAAmB,CAAC;IAC/C,MAAM,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;AAC3E,wBAAgB,eAAe,CAC3B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,IAAI,GACnB,oBAAoB,GAAG,IAAI,CAAC"}
+{"version":3,"file":"validate-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/validate-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,sBAAsB,CAsFlF;AAuCD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAmBzE"}

package/dist/plugins/validate-plugin.js

@@ -1,33 +1,18 @@
 import * as path from "path";
 import { existsSync, readFileSync, readdirSync } from "fs";
-import { PluginManifestSchema, DextoPluginManifestSchema } from "./schemas.js";
+import { PluginManifestSchema } from "./schemas.js";
 function validatePluginDirectory(pluginPath) {
   const errors = [];
   const warnings = [];
   let manifest;
-  let format;
   const absolutePath = path.isAbsolute(pluginPath) ? pluginPath : path.resolve(pluginPath);
   if (!existsSync(absolutePath)) {
     errors.push(`Directory does not exist: ${absolutePath}`);
     return { valid: false, errors, warnings };
   }
-  const dextoPluginDir = path.join(absolutePath, ".dexto-plugin");
-  const claudePluginDir = path.join(absolutePath, ".claude-plugin");
-  let manifestPath;
-  if (existsSync(dextoPluginDir)) {
-    manifestPath = path.join(dextoPluginDir, "plugin.json");
-    format = "dexto";
-  } else if (existsSync(claudePluginDir)) {
-    manifestPath = path.join(claudePluginDir, "plugin.json");
-    format = "claude-code";
-  } else {
-    errors.push("Missing .dexto-plugin or .claude-plugin directory");
-    return { valid: false, errors, warnings };
-  }
+  const manifestPath = path.join(absolutePath, ".claude-plugin", "plugin.json");
   if (!existsSync(manifestPath)) {
-    errors.push(
-      `Missing ${format === "dexto" ? ".dexto-plugin" : ".claude-plugin"}/plugin.json`
-    );
+    errors.push("Missing .claude-plugin/plugin.json");
     return { valid: false, errors, warnings };
   }
   try {
@@ -41,8 +26,7 @@ function validatePluginDirectory(pluginPath) {
       );
       return { valid: false, errors, warnings };
     }
-    const schema = format === "dexto" ? DextoPluginManifestSchema : PluginManifestSchema;
-    const result = schema.safeParse(parsed);
+    const result = PluginManifestSchema.safeParse(parsed);
     if (!result.success) {
       const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
       errors.push(`Schema validation failed: ${issues.join("; ")}`);
@@ -78,7 +62,6 @@ function validatePluginDirectory(pluginPath) {
   return {
     valid: errors.length === 0,
     manifest,
-    format,
     errors,
     warnings
   };
@@ -109,31 +92,18 @@ function checkDirectoryHasSkills(skillsDir) {
     return false;
   }
 }
-function tryLoadManifest(pluginPath, returnFormat) {
-  const dextoManifestPath = path.join(pluginPath, ".dexto-plugin", "plugin.json");
-  const claudeManifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
-  let manifestPath;
-  let format;
-  if (existsSync(dextoManifestPath)) {
-    manifestPath = dextoManifestPath;
-    format = "dexto";
-  } else if (existsSync(claudeManifestPath)) {
-    manifestPath = claudeManifestPath;
-    format = "claude-code";
-  } else {
+function tryLoadManifest(pluginPath) {
+  const manifestPath = path.join(pluginPath, ".claude-plugin", "plugin.json");
+  if (!existsSync(manifestPath)) {
     return null;
   }
   try {
     const content = readFileSync(manifestPath, "utf-8");
     const parsed = JSON.parse(content);
-    const schema = format === "dexto" ? DextoPluginManifestSchema : PluginManifestSchema;
-    const result = schema.safeParse(parsed);
+    const result = PluginManifestSchema.safeParse(parsed);
     if (!result.success) {
       return null;
     }
-    if (returnFormat) {
-      return { manifest: result.data, format };
-    }
     return result.data;
   } catch {
     return null;

package/dist/preferences/errors.cjs

@@ -66,6 +66,17 @@ class PreferenceError {
     }));
     return new import_core.DextoValidationError(issues);
   }
+  static invalidAgentId(agentId) {
+    return new import_core.DextoValidationError([
+      {
+        code: import_error_codes.PreferenceErrorCode.INVALID_PREFERENCE_VALUE,
+        message: `agentId is invalid: ${agentId}`,
+        scope: "preference",
+        type: import_core.ErrorType.USER,
+        severity: "error"
+      }
+    ]);
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/preferences/errors.d.ts

@@ -14,5 +14,6 @@ export declare class PreferenceError {
         cause: string;
     }>;
     static validationFailed(zodError: ZodError): DextoValidationError;
+    static invalidAgentId(agentId: string): DextoValidationError;
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/preferences/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/preferences/errors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAa,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,KAAK,CAAC;AAGpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,eAAe;IACxB,MAAM,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM;;;IAW3C,MAAM,CAAC,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;IAW3D,MAAM,CAAC,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;IAW5D,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ;CAW7C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/preferences/errors.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAa,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,KAAK,CAAC;AAGpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,qBAAa,eAAe;IACxB,MAAM,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM;;;IAW3C,MAAM,CAAC,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;IAW3D,MAAM,CAAC,cAAc,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;IAW5D,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ;IAY1C,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM;CAWxC"}

package/dist/preferences/errors.js

@@ -42,6 +42,17 @@ class PreferenceError {
     }));
     return new DextoValidationError(issues);
   }
+  static invalidAgentId(agentId) {
+    return new DextoValidationError([
+      {
+        code: PreferenceErrorCode.INVALID_PREFERENCE_VALUE,
+        message: `agentId is invalid: ${agentId}`,
+        scope: "preference",
+        type: ErrorType.USER,
+        severity: "error"
+      }
+    ]);
+  }
 }
 export {
   PreferenceError,

package/dist/preferences/loader.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,28 +17,42 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var loader_exports = {};
 __export(loader_exports, {
+  agentPreferencesExist: () => agentPreferencesExist,
   createInitialPreferences: () => createInitialPreferences,
+  getAgentPreferencesPath: () => getAgentPreferencesPath,
   getGlobalPreferencesPath: () => getGlobalPreferencesPath,
   globalPreferencesExist: () => globalPreferencesExist,
+  loadAgentPreferences: () => loadAgentPreferences,
   loadGlobalPreferences: () => loadGlobalPreferences,
+  saveAgentPreferences: () => saveAgentPreferences,
   saveGlobalPreferences: () => saveGlobalPreferences,
+  updateAgentPreferences: () => updateAgentPreferences,
   updateGlobalPreferences: () => updateGlobalPreferences
 });
 module.exports = __toCommonJS(loader_exports);
 var import_fs = require("fs");
 var import_fs2 = require("fs");
 var import_yaml = require("yaml");
-var import_path = require("../utils/path.js");
+var import_path = __toESM(require("path"), 1);
+var import_path2 = require("../utils/path.js");
 var import_core = require("@dexto/core");
 var import_core2 = require("@dexto/core");
 var import_schemas = require("./schemas.js");
 var import_constants = require("./constants.js");
 var import_errors = require("./errors.js");
 async function loadGlobalPreferences() {
-  const preferencesPath = (0, import_path.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
+  const preferencesPath = (0, import_path2.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
   if (!(0, import_fs.existsSync)(preferencesPath)) {
     throw import_errors.PreferenceError.fileNotFound(preferencesPath);
   }
@@ -70,15 +86,107 @@ const PREFERENCES_FILE_HEADER = `# Dexto Global Preferences
 #   Set sounds.enabled: false to disable all sounds.
 
 `;
+const AGENT_PREFERENCES_FILE_HEADER = `# Dexto Agent Preferences
+# Stored per-agent to customize runtime behavior without changing base config.
+# Tool control:
+#   tools.disabled: list of tool names to exclude from LLM context.
+
+`;
+function getAgentPreferencesPath(agentId) {
+  if (!agentId || typeof agentId !== "string") {
+    throw import_errors.PreferenceError.invalidAgentId(String(agentId));
+  }
+  const trimmedId = agentId.trim();
+  if (!trimmedId) {
+    throw import_errors.PreferenceError.invalidAgentId(agentId);
+  }
+  const hasSeparators = trimmedId.includes("/") || trimmedId.includes("\\");
+  if (hasSeparators || trimmedId !== import_path.default.basename(trimmedId)) {
+    throw import_errors.PreferenceError.invalidAgentId(agentId);
+  }
+  const allowedPattern = /^[a-zA-Z0-9_-]+$/;
+  if (!allowedPattern.test(trimmedId)) {
+    throw import_errors.PreferenceError.invalidAgentId(agentId);
+  }
+  const filename = `${trimmedId}.preferences.yml`;
+  return (0, import_path2.getDextoGlobalPath)(import_path.default.join("agents", filename));
+}
+async function loadAgentPreferences(agentId) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  if (!(0, import_fs.existsSync)(preferencesPath)) {
+    throw import_errors.PreferenceError.fileNotFound(preferencesPath);
+  }
+  try {
+    const fileContent = await import_fs2.promises.readFile(preferencesPath, "utf-8");
+    const rawPreferences = (0, import_yaml.parse)(fileContent);
+    const validation = import_schemas.AgentPreferencesSchema.safeParse(rawPreferences);
+    if (!validation.success) {
+      throw import_errors.PreferenceError.validationFailed(validation.error);
+    }
+    import_core.logger.debug(`Loaded agent preferences from: ${preferencesPath}`);
+    return validation.data;
+  } catch (error) {
+    if (error instanceof import_core2.DextoValidationError || error instanceof import_core2.DextoRuntimeError) {
+      throw error;
+    }
+    throw import_errors.PreferenceError.fileReadError(
+      preferencesPath,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+async function saveAgentPreferences(agentId, preferences) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  const validation = import_schemas.AgentPreferencesSchema.safeParse(preferences);
+  if (!validation.success) {
+    throw import_errors.PreferenceError.validationFailed(validation.error);
+  }
+  try {
+    import_core.logger.debug(`Saving agent preferences to: ${preferencesPath}`);
+    await import_fs2.promises.mkdir(import_path.default.dirname(preferencesPath), { recursive: true });
+    const yamlContent = (0, import_yaml.stringify)(preferences, {
+      indent: 2,
+      lineWidth: 100,
+      minContentWidth: 20
+    });
+    await import_fs2.promises.writeFile(preferencesPath, AGENT_PREFERENCES_FILE_HEADER + yamlContent, "utf-8");
+    import_core.logger.debug(
+      `\u2713 Saved agent preferences ${JSON.stringify(preferences)} to: ${preferencesPath}`
+    );
+  } catch (error) {
+    throw import_errors.PreferenceError.fileWriteError(
+      preferencesPath,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+function agentPreferencesExist(agentId) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  return (0, import_fs.existsSync)(preferencesPath);
+}
+async function updateAgentPreferences(agentId, updates) {
+  const existing = await loadAgentPreferences(agentId);
+  const merged = {
+    ...existing,
+    ...updates,
+    tools: updates.tools ? { ...existing.tools, ...updates.tools } : existing.tools
+  };
+  const validation = import_schemas.AgentPreferencesSchema.safeParse(merged);
+  if (!validation.success) {
+    throw import_errors.PreferenceError.validationFailed(validation.error);
+  }
+  await saveAgentPreferences(agentId, validation.data);
+  return validation.data;
+}
 async function saveGlobalPreferences(preferences) {
-  const preferencesPath = (0, import_path.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
+  const preferencesPath = (0, import_path2.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
   const validation = import_schemas.GlobalPreferencesSchema.safeParse(preferences);
   if (!validation.success) {
     throw import_errors.PreferenceError.validationFailed(validation.error);
   }
   try {
     import_core.logger.debug(`Saving global preferences to: ${preferencesPath}`);
-    const dextoDir = (0, import_path.getDextoGlobalPath)("");
+    const dextoDir = (0, import_path2.getDextoGlobalPath)("");
     await import_fs2.promises.mkdir(dextoDir, { recursive: true });
     const yamlContent = (0, import_yaml.stringify)(preferences, {
       indent: 2,
@@ -97,11 +205,11 @@ async function saveGlobalPreferences(preferences) {
   }
 }
 function globalPreferencesExist() {
-  const preferencesPath = (0, import_path.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
+  const preferencesPath = (0, import_path2.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
   return (0, import_fs.existsSync)(preferencesPath);
 }
 function getGlobalPreferencesPath() {
-  return (0, import_path.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
+  return (0, import_path2.getDextoGlobalPath)(import_constants.PREFERENCES_FILE);
 }
 function createInitialPreferences(options) {
   const llmConfig = {
@@ -156,10 +264,15 @@ async function updateGlobalPreferences(updates) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  agentPreferencesExist,
   createInitialPreferences,
+  getAgentPreferencesPath,
   getGlobalPreferencesPath,
   globalPreferencesExist,
+  loadAgentPreferences,
   loadGlobalPreferences,
+  saveAgentPreferences,
   saveGlobalPreferences,
+  updateAgentPreferences,
   updateGlobalPreferences
 });

package/dist/preferences/loader.d.ts

@@ -1,5 +1,5 @@
 import type { LLMProvider } from '@dexto/core';
-import { type GlobalPreferences } from './schemas.js';
+import { type AgentPreferences, type GlobalPreferences } from './schemas.js';
 /**
  * Load global preferences from ~/.dexto/preferences.yml
  * @returns Global preferences object
@@ -7,6 +7,26 @@ import { type GlobalPreferences } from './schemas.js';
  * @throws DextoValidationError if preferences are invalid
  */
 export declare function loadGlobalPreferences(): Promise<GlobalPreferences>;
+/**
+ * Resolve the agent preferences file path for an agent ID.
+ */
+export declare function getAgentPreferencesPath(agentId: string): string;
+/**
+ * Load agent preferences from ~/.dexto/agents/<agentId>.preferences.yml
+ */
+export declare function loadAgentPreferences(agentId: string): Promise<AgentPreferences>;
+/**
+ * Save agent preferences to ~/.dexto/agents/<agentId>.preferences.yml
+ */
+export declare function saveAgentPreferences(agentId: string, preferences: AgentPreferences): Promise<void>;
+/**
+ * Check if agent preferences exist (for first-time detection)
+ */
+export declare function agentPreferencesExist(agentId: string): boolean;
+/**
+ * Update agent preferences with partial updates
+ */
+export declare function updateAgentPreferences(agentId: string, updates: Partial<AgentPreferences>): Promise<AgentPreferences>;
 /**
  * Save global preferences to ~/.dexto/preferences.yml
  * @param preferences Validated preferences object

package/dist/preferences/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/preferences/loader.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAI/E;;;;;GAKG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CA+BxE;AAiBD;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCzF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qCAAqC;IACrC,MAAM,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACL;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAsC7F;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,GAAG,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,wBAAwB,GAClC,OAAO,CAAC,iBAAiB,CAAC,CA4B5B"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/preferences/loader.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAGH,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACzB,MAAM,cAAc,CAAC;AAItB;;;;;GAKG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,CAAC,CA+BxE;AA2BD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAsB/D;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA4BrF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,gBAAgB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA8Bf;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CACxC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACnC,OAAO,CAAC,gBAAgB,CAAC,CAgB3B;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCzF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAGhD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACrC,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,qCAAqC;IACrC,MAAM,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACL;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAsC7F;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,GAAG,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;IAClD,KAAK,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;CACjD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,wBAAwB,GAClC,OAAO,CAAC,iBAAiB,CAAC,CA4B5B"}

package/dist/preferences/loader.js

@@ -1,10 +1,14 @@
 import { existsSync } from "fs";
 import { promises as fs } from "fs";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import path from "path";
 import { getDextoGlobalPath } from "../utils/path.js";
 import { logger } from "@dexto/core";
 import { DextoValidationError, DextoRuntimeError } from "@dexto/core";
-import { GlobalPreferencesSchema } from "./schemas.js";
+import {
+  AgentPreferencesSchema,
+  GlobalPreferencesSchema
+} from "./schemas.js";
 import { PREFERENCES_FILE } from "./constants.js";
 import { PreferenceError } from "./errors.js";
 async function loadGlobalPreferences() {
@@ -42,6 +46,98 @@ const PREFERENCES_FILE_HEADER = `# Dexto Global Preferences
 #   Set sounds.enabled: false to disable all sounds.
 
 `;
+const AGENT_PREFERENCES_FILE_HEADER = `# Dexto Agent Preferences
+# Stored per-agent to customize runtime behavior without changing base config.
+# Tool control:
+#   tools.disabled: list of tool names to exclude from LLM context.
+
+`;
+function getAgentPreferencesPath(agentId) {
+  if (!agentId || typeof agentId !== "string") {
+    throw PreferenceError.invalidAgentId(String(agentId));
+  }
+  const trimmedId = agentId.trim();
+  if (!trimmedId) {
+    throw PreferenceError.invalidAgentId(agentId);
+  }
+  const hasSeparators = trimmedId.includes("/") || trimmedId.includes("\\");
+  if (hasSeparators || trimmedId !== path.basename(trimmedId)) {
+    throw PreferenceError.invalidAgentId(agentId);
+  }
+  const allowedPattern = /^[a-zA-Z0-9_-]+$/;
+  if (!allowedPattern.test(trimmedId)) {
+    throw PreferenceError.invalidAgentId(agentId);
+  }
+  const filename = `${trimmedId}.preferences.yml`;
+  return getDextoGlobalPath(path.join("agents", filename));
+}
+async function loadAgentPreferences(agentId) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  if (!existsSync(preferencesPath)) {
+    throw PreferenceError.fileNotFound(preferencesPath);
+  }
+  try {
+    const fileContent = await fs.readFile(preferencesPath, "utf-8");
+    const rawPreferences = parseYaml(fileContent);
+    const validation = AgentPreferencesSchema.safeParse(rawPreferences);
+    if (!validation.success) {
+      throw PreferenceError.validationFailed(validation.error);
+    }
+    logger.debug(`Loaded agent preferences from: ${preferencesPath}`);
+    return validation.data;
+  } catch (error) {
+    if (error instanceof DextoValidationError || error instanceof DextoRuntimeError) {
+      throw error;
+    }
+    throw PreferenceError.fileReadError(
+      preferencesPath,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+async function saveAgentPreferences(agentId, preferences) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  const validation = AgentPreferencesSchema.safeParse(preferences);
+  if (!validation.success) {
+    throw PreferenceError.validationFailed(validation.error);
+  }
+  try {
+    logger.debug(`Saving agent preferences to: ${preferencesPath}`);
+    await fs.mkdir(path.dirname(preferencesPath), { recursive: true });
+    const yamlContent = stringifyYaml(preferences, {
+      indent: 2,
+      lineWidth: 100,
+      minContentWidth: 20
+    });
+    await fs.writeFile(preferencesPath, AGENT_PREFERENCES_FILE_HEADER + yamlContent, "utf-8");
+    logger.debug(
+      `\u2713 Saved agent preferences ${JSON.stringify(preferences)} to: ${preferencesPath}`
+    );
+  } catch (error) {
+    throw PreferenceError.fileWriteError(
+      preferencesPath,
+      error instanceof Error ? error.message : String(error)
+    );
+  }
+}
+function agentPreferencesExist(agentId) {
+  const preferencesPath = getAgentPreferencesPath(agentId);
+  return existsSync(preferencesPath);
+}
+async function updateAgentPreferences(agentId, updates) {
+  const existing = await loadAgentPreferences(agentId);
+  const merged = {
+    ...existing,
+    ...updates,
+    tools: updates.tools ? { ...existing.tools, ...updates.tools } : existing.tools
+  };
+  const validation = AgentPreferencesSchema.safeParse(merged);
+  if (!validation.success) {
+    throw PreferenceError.validationFailed(validation.error);
+  }
+  await saveAgentPreferences(agentId, validation.data);
+  return validation.data;
+}
 async function saveGlobalPreferences(preferences) {
   const preferencesPath = getDextoGlobalPath(PREFERENCES_FILE);
   const validation = GlobalPreferencesSchema.safeParse(preferences);
@@ -127,10 +223,15 @@ async function updateGlobalPreferences(updates) {
   return validation.data;
 }
 export {
+  agentPreferencesExist,
   createInitialPreferences,
+  getAgentPreferencesPath,
   getGlobalPreferencesPath,
   globalPreferencesExist,
+  loadAgentPreferences,
   loadGlobalPreferences,
+  saveAgentPreferences,
   saveGlobalPreferences,
+  updateAgentPreferences,
   updateGlobalPreferences
 };