@kontextmind/kxm 0.7.168 → 0.7.169

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.168",
+      "version": "0.7.169",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/CHANGELOG.md

@@ -181,6 +181,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **Tool policy is enforced at load and before dispatch.**
+  `coordinator` and `read-only` select the read-only one-shot profile.
+  `workspace-writer` and `tests-writer` select the edit profile. Dispatch
+  uses the narrowest of the role `permission`, that preset profile, and the
+  step's repository access. An agent preset wider than its role is
+  `tool_preset_exceeds_role` at load, and `step_unsupported` before a
+  producer starts if those files were already loaded. A write step whose
+  resolved profile is read-only is the same handoff. The detail names the
+  role permission and the step access. `tools.allow` and `tools.deny` stay
+  on the MCP surface through `enforceToolPolicy`. See
+  [agent files](docs/reference/config-reference.md#kxmagentsidyaml-kxmagentv1).
+
 - **The checked-in price catalog and model inventory match the live OpenRouter and Nous feeds.**
   `.kxm/prices.yaml` is dated 2026-09-28. It adds `xai/grok-4.7` (alias
   `x-ai/grok-4.7`) at $1.60 input and $4.80 output per 1M tokens, with cache

package/docs/reference/config-reference.md

@@ -337,7 +337,7 @@ with `retired_agent_routing_fields`.
 | `skills` | Unique identifiers, at most 64 | Optional | Skill names granted to the agent |
 | `instructions` | String, at most 16,000 characters | Optional | Not read by any code path yet. Step `instructions` are what reach the prompt. |
 | `executor` | `local`, `ssh`, or `exe-dev` | Optional | Loader (`executor_unknown`); recorded in the executor-policy revision; no dispatch path selects an executor from it yet |
-| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`): the preset must be registered. An agent `tools.preset` may only narrow the role preset. Enforcement of that rule is pending (P3). |
+| `tools.preset` | `coordinator`, `read-only`, `workspace-writer`, or `tests-writer` | Optional | Loader (`tool_preset_unknown`): the preset must be registered. `coordinator` and `read-only` select the read-only one-shot profile. `workspace-writer` and `tests-writer` select the edit profile. An agent preset may only narrow the role. A wider preset is `tool_preset_exceeds_role` at load. |
 | `tools.allow`, `tools.deny` | Unique identifiers, at most 128 each | Optional | A tool in both lists is `tool_policy_contradiction`; steps may only narrow the ceiling |
 | `defaultRepositoryAccess` | `none`, `read`, or `write` | Optional; the ceiling is `none` when absent | Loader: access ceiling for repositories not listed in `repositories` |
 | `repositories` | Map of repository ID to `none`, `read`, or `write`; at most 64 | Optional | Loader: per-repository access ceiling; IDs must be declared (`repository_unknown`) |
@@ -349,18 +349,30 @@ with `retired_agent_routing_fields`.
 | `session.reuse` | `compatible-run-scope` | Optional | Not read by any code path yet |
 | `session.maxIdleMs` | Integer, 0 to 31,536,000,000 | Optional | Not read by any code path yet |
 
-Tool presets are names checked against a registered list. The live one-shot
-producer launches the harness named by the selected model file, with a fixed
-argument set, and does not translate `tools` into harness flags. A read-only
-step uses the read-only set (`READ_ONLY_ONESHOT_ARGS` in
-`plugins/kxm/src/harness.ts`). A step with `write` access uses the audited
-writer set (`WRITER_ONESHOT_ARGS`), which exists only for `pi` (`-a` with
-extensions, skills, prompt templates and sessions off) and `grok`
-(`--always-approve` with subagents and web search off). Both approve every
-tool call, shell commands included, and neither confines the process to the
-checkout. A live write step on any other harness is handed off; see
+Tool presets are names checked against a registered list, then mapped onto
+the harness one-shot profiles in `plugins/kxm/src/harness.ts`. `coordinator`
+and `read-only` use the read-only argument set (`READ_ONLY_ONESHOT_ARGS`).
+`workspace-writer` and `tests-writer` use the audited writer set
+(`WRITER_ONESHOT_ARGS`), which exists only for `pi` (`-a` with extensions,
+skills, prompt templates and sessions off) and `grok` (`--always-approve`
+with subagents and web search off). Both approve every tool call, shell
+commands included, and neither confines the process to the checkout.
+
+Dispatch permission is the narrowest of the role `permission`, the preset
+profile (the role preset, then the agent preset), and the step's repository
+access (`write` is edit; `read` and `none` are read-only). A preset cannot
+widen a role. An agent preset that is wider fails load with
+`tool_preset_exceeds_role`, and dispatch refuses that file again with
+`step_unsupported` (field `tools.preset`) when the process already loaded
+it. A write step whose resolved profile is read-only is `step_unsupported`
+(field `permission`) before the producer starts. The detail names the role
+permission and the step access. A live write that does resolve to edit
+still hands off on a harness with no audited writer set; see
 [Steps the Runtime does not execute yet](#steps-the-runtime-does-not-execute-yet).
 
+`tools.allow` and `tools.deny` apply to the MCP surface through
+`enforceToolPolicy` in `plugins/kxm/src/commands.ts`.
+
 Example (the shape `kxm init` writes for `writer`):
 
 ```yaml
@@ -394,7 +406,7 @@ Runtime cannot reach the `antigravity` Pi provider yet. `kxm run` and the
 Runtime read the agents. `kxm trust` diffs them.
 
 Error codes: `retired_agent_routing_fields`, `executor_unknown`,
-`tool_preset_unknown`, `tool_policy_contradiction`, `repository_unknown`, and
+`tool_preset_unknown`, `tool_preset_exceeds_role`, `tool_policy_contradiction`, `repository_unknown`, and
 the path codes under
 [Rules shared by the project bundle](#rules-shared-by-the-project-bundle).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.168",
+  "version": "0.7.169",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.168",
+  "version": "0.7.169",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",

package/plugins/kxm/dist/cli.js

@@ -20122,6 +20122,21 @@ import { pathToFileURL } from "node:url";
 function defaultKxmSchemaDir() {
   return join9(findKxmRepoRoot(import.meta.url), "schemas");
 }
+function toolPresetProfile(preset) {
+  if (!Object.hasOwn(TOOL_PRESET_PROFILES, preset)) return void 0;
+  return TOOL_PRESET_PROFILES[preset];
+}
+function toolPresetExceedsRoleMessage(preset, roleId, rolePermission, rolePreset) {
+  const profile = toolPresetProfile(preset);
+  if (profile !== "edit") return void 0;
+  if (rolePermission === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} permission read-only`;
+  }
+  if (rolePreset !== void 0 && toolPresetProfile(rolePreset) === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} preset ${rolePreset}`;
+  }
+  return void 0;
+}
 function compareCodeUnits4(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -20407,6 +20422,15 @@ function objectValue(value) {
 function stringValue(value) {
   return typeof value === "string" ? value : void 0;
 }
+function roleById(roles, roleId) {
+  const direct = roles.get(roleId);
+  if (direct) return direct;
+  const folded = roleId.toLocaleLowerCase("en-US");
+  for (const role of roles.values()) {
+    if ((role.id ?? "").toLocaleLowerCase("en-US") === folded) return role;
+  }
+  return void 0;
+}
 function numberValue(value, fallback) {
   return typeof value === "number" ? value : fallback;
 }
@@ -20917,10 +20941,29 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
     if (executor && !executors.has(executor)) issues.push(issue3("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue3("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
+    const roleId = stringValue(agent.value.role);
+    const role = roleId ? roleById(roles, roleId) : void 0;
+    const rolePermission = stringValue(role?.value.permission);
+    if (preset && role && (rolePermission === "edit" || rolePermission === "read-only")) {
+      const message = toolPresetExceedsRoleMessage(
+        preset,
+        role.id ?? roleId ?? "role",
+        rolePermission,
+        stringValue(objectValue(role.value.tools)?.preset)
+      );
+      if (message) issues.push(issue3("semantic", "tool_preset_exceeds_role", agent.logicalPath, message));
+    }
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue3("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
   }
+  for (const role of roles.values()) {
+    const permission = stringValue(role.value.permission);
+    const rolePreset = stringValue(objectValue(role.value.tools)?.preset);
+    if (permission === "read-only" && rolePreset && toolPresetProfile(rolePreset) === "edit") {
+      issues.push(issue3("semantic", "tool_preset_exceeds_role", role.logicalPath, `tools.preset ${rolePreset} exceeds permission read-only`));
+    }
+  }
   validateModelReferences(models, issues);
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
   if (!lookupKxmResource(workflows.values(), defaultWorkflow, "workflow")) issues.push(issue3("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
@@ -21398,7 +21441,7 @@ function planKxmInitialization(start = process.cwd(), options = {}) {
   }
   return { mode: "create", inspectedFrom, projectRoot: candidateRoot, changesRequired: true, issues: [], legacyInputs: [] };
 }
-var import__, KxmConfigError, DEFAULT_SCHEMA_DIR, RESOURCE_SCHEMA, IDENTIFIER2, WINDOWS_RESERVED, BUILTIN_EXECUTORS, BUILTIN_TOOL_PRESETS, SECRET_VALUE_PATTERNS, KxmSchemaRegistry, cachedRunEventRegistry, GATE_STEP_OUTCOMES, LEGACY_CONFIG_FILES;
+var import__, KxmConfigError, DEFAULT_SCHEMA_DIR, RESOURCE_SCHEMA, IDENTIFIER2, WINDOWS_RESERVED, BUILTIN_EXECUTORS, TOOL_PRESET_PROFILES, BUILTIN_TOOL_PRESETS, SECRET_VALUE_PATTERNS, KxmSchemaRegistry, cachedRunEventRegistry, GATE_STEP_OUTCOMES, LEGACY_CONFIG_FILES;
 var init_project_config = __esm({
   "plugins/kxm/src/project-config.ts"() {
     "use strict";
@@ -21432,7 +21475,13 @@ var init_project_config = __esm({
     IDENTIFIER2 = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
     WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$|clock\$)$/i;
     BUILTIN_EXECUTORS = ["local", "ssh", "exe-dev"];
-    BUILTIN_TOOL_PRESETS = ["coordinator", "read-only", "workspace-writer", "tests-writer"];
+    TOOL_PRESET_PROFILES = Object.freeze({
+      coordinator: "read-only",
+      "read-only": "read-only",
+      "workspace-writer": "edit",
+      "tests-writer": "edit"
+    });
+    BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
     SECRET_VALUE_PATTERNS = [
       /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/,
       /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/,
@@ -27709,6 +27758,68 @@ function unsupportedAgentStepTimeout(step, limitMs) {
     detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs"
   };
 }
+function narrowerPermission(left, right) {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+function stepRepositoryPermission(step) {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+function stepAccessDetail(step) {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries.map(([id, access]) => `${id} ${access}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0).join(", ");
+}
+function yamlToolsPreset(doc) {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return void 0;
+  const preset = tools.preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : void 0;
+}
+function resolveToolDispatch(projectRoot, step, agentId) {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join19(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join19(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join19(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : void 0;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : void 0;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`
+      }
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : void 0;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`
+      }
+    };
+  }
+  return { permission };
+}
 function kxmLiveRunPrerequisites(bundle, workflowId, projectRoot) {
   const workflow = lookupKxmResource(bundle.workflows.values(), workflowId, "workflow");
   if (!workflow) throw runtimeError("run_workflow_unknown", workflowId, `workflow ${workflowId} does not exist in this project`);
@@ -27736,6 +27847,11 @@ function kxmLiveRunPrerequisites(bundle, workflowId, projectRoot) {
     if (step.kind !== "agent" && step.kind !== "moa") continue;
     const agentIds = step.assignments.allowedAgents.length > 0 ? step.assignments.allowedAgents : [step.agent];
     for (const agentId of agentIds) {
+      const toolDispatch = resolveToolDispatch(projectRoot, step, agentId);
+      if ("error" in toolDispatch) {
+        prerequisites.push({ ...toolDispatch.error, stepId });
+        continue;
+      }
       const route = resolveProducerRoute(projectRoot, step, agentId);
       if ("error" in route) {
         const detail = route.error.detail === "producer_route_unsupported: agent step model is not honored" ? `${agentId}: agent step model is not honored; remove model from the step` : `${agentId}: ${route.error.detail}; set role in .kxm/agents/${agentId}.yaml and admit the route model with kxm routes admit --model <provider/model>`;
@@ -27743,7 +27859,7 @@ function kxmLiveRunPrerequisites(bundle, workflowId, projectRoot) {
         continue;
       }
       const harness = route.harness;
-      const permission = Object.values(step.repositories).includes("write") ? "edit" : "read-only";
+      const permission = toolDispatch.permission;
       if (!BUILTIN_HARNESSES.some((entry) => entry.id === harness && entry.oneShot) || !oneShotPermissionArgs(harness, permission)) {
         prerequisites.push({ reason: "step_unsupported", stepId, field: "harness", detail: `${agentId}: ${harness} has no audited ${permission} one-shot profile; use a supported workflow or execute this work directly in ${harness}, without substituting another harness` });
         continue;

package/plugins/kxm/dist/mcp-server.js

@@ -25438,7 +25438,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.168";
+var VERSION = "0.7.169";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/runtime-supervisor.js

@@ -17261,7 +17261,28 @@ var RESOURCE_SCHEMA = Object.freeze({
 var IDENTIFIER2 = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 var WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$|clock\$)$/i;
 var BUILTIN_EXECUTORS = ["local", "ssh", "exe-dev"];
-var BUILTIN_TOOL_PRESETS = ["coordinator", "read-only", "workspace-writer", "tests-writer"];
+var TOOL_PRESET_PROFILES = Object.freeze({
+  coordinator: "read-only",
+  "read-only": "read-only",
+  "workspace-writer": "edit",
+  "tests-writer": "edit"
+});
+var BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
+function toolPresetProfile(preset) {
+  if (!Object.hasOwn(TOOL_PRESET_PROFILES, preset)) return void 0;
+  return TOOL_PRESET_PROFILES[preset];
+}
+function toolPresetExceedsRoleMessage(preset, roleId, rolePermission, rolePreset) {
+  const profile = toolPresetProfile(preset);
+  if (profile !== "edit") return void 0;
+  if (rolePermission === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} permission read-only`;
+  }
+  if (rolePreset !== void 0 && toolPresetProfile(rolePreset) === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} preset ${rolePreset}`;
+  }
+  return void 0;
+}
 var SECRET_VALUE_PATTERNS = [
   /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/,
   /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/,
@@ -17661,6 +17682,15 @@ function objectValue(value) {
 function stringValue(value) {
   return typeof value === "string" ? value : void 0;
 }
+function roleById(roles, roleId) {
+  const direct = roles.get(roleId);
+  if (direct) return direct;
+  const folded = roleId.toLocaleLowerCase("en-US");
+  for (const role of roles.values()) {
+    if ((role.id ?? "").toLocaleLowerCase("en-US") === folded) return role;
+  }
+  return void 0;
+}
 function numberValue(value, fallback) {
   return typeof value === "number" ? value : fallback;
 }
@@ -18175,10 +18205,29 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
     if (executor && !executors.has(executor)) issues.push(issue3("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue3("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
+    const roleId = stringValue(agent.value.role);
+    const role = roleId ? roleById(roles, roleId) : void 0;
+    const rolePermission = stringValue(role?.value.permission);
+    if (preset && role && (rolePermission === "edit" || rolePermission === "read-only")) {
+      const message = toolPresetExceedsRoleMessage(
+        preset,
+        role.id ?? roleId ?? "role",
+        rolePermission,
+        stringValue(objectValue(role.value.tools)?.preset)
+      );
+      if (message) issues.push(issue3("semantic", "tool_preset_exceeds_role", agent.logicalPath, message));
+    }
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue3("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
   }
+  for (const role of roles.values()) {
+    const permission = stringValue(role.value.permission);
+    const rolePreset = stringValue(objectValue(role.value.tools)?.preset);
+    if (permission === "read-only" && rolePreset && toolPresetProfile(rolePreset) === "edit") {
+      issues.push(issue3("semantic", "tool_preset_exceeds_role", role.logicalPath, `tools.preset ${rolePreset} exceeds permission read-only`));
+    }
+  }
   validateModelReferences(models, issues);
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
   if (!lookupKxmResource(workflows.values(), defaultWorkflow, "workflow")) issues.push(issue3("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
@@ -29377,6 +29426,68 @@ function unsupportedAgentStepTimeout(step, limitMs) {
     detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs"
   };
 }
+function narrowerPermission(left, right) {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+function stepRepositoryPermission(step) {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+function stepAccessDetail(step) {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries.map(([id, access]) => `${id} ${access}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0).join(", ");
+}
+function yamlToolsPreset(doc) {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return void 0;
+  const preset = tools.preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : void 0;
+}
+function resolveToolDispatch(projectRoot, step, agentId) {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join18(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join18(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join18(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : void 0;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : void 0;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`
+      }
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : void 0;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`
+      }
+    };
+  }
+  return { permission };
+}
 function executingSingletonAttempt(plan, state) {
   const current = state.currentStep;
   if (!current || current.panel.order.length !== 1) return void 0;
@@ -29569,10 +29680,17 @@ function prepareDispatch(context, runId, producerId, dispatchSources) {
   if (unsupported) return { kind: "return", state, handoff: { ...unsupported, stepId } };
   const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
   if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
+  const firstListed = step.assignments.allowedAgents[0];
+  const firstAgentId = step.kind === "agent" || step.kind === "moa" ? firstListed ? firstListed : step.agent : void 0;
+  if (firstAgentId) {
+    const toolDispatch = resolveToolDispatch(context.projectRoot, step, firstAgentId);
+    if ("error" in toolDispatch) {
+      return { kind: "return", state, handoff: { ...toolDispatch.error, stepId } };
+    }
+  }
   let resolvedRoute;
   if (producerId !== "driver-simulated") {
-    const allowed = step.assignments.allowedAgents;
-    const agentId = allowed && allowed.length > 0 && allowed[0] ? allowed[0] : step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator";
+    const agentId = firstAgentId ?? (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
     const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
     if ("error" in routeResult) {
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
@@ -29692,6 +29810,10 @@ function birthMember(context, input) {
   const born = folded.currentStep?.panel.order.length ?? 0;
   const allowed = input.step.assignments.allowedAgents;
   const agentId = allowed && allowed.length > born && allowed[born] ? allowed[born] : input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator";
+  const toolDispatch = resolveToolDispatch(context.projectRoot, input.step, agentId);
+  if ("error" in toolDispatch) {
+    return { handoff: { ...toolDispatch.error, stepId: input.stepId } };
+  }
   let resolvedRoute = input.resolvedRoute;
   if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
     const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
@@ -29781,7 +29903,7 @@ function birthMember(context, input) {
       stepAttempt: input.stepAttempt,
       objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only"
+      permissionCeiling: toolDispatch.permission
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -29826,7 +29948,7 @@ function birthMember(context, input) {
       prompt: input.step.instructions ? `${input.step.instructions}
 
 ${generatedPrompt}` : generatedPrompt,
-      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permission: toolDispatch.permission,
       ...(input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== void 0 ? { timeoutMs: input.step.timeoutMs } : {},
       contextPacket,
       ...resolvedRoute?.effort !== void 0 ? { thinking: resolvedRoute.effort } : {},

package/plugins/kxm/dist/runtime.js

@@ -17431,7 +17431,28 @@ var RESOURCE_SCHEMA = Object.freeze({
 var IDENTIFIER2 = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 var WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$|clock\$)$/i;
 var BUILTIN_EXECUTORS = ["local", "ssh", "exe-dev"];
-var BUILTIN_TOOL_PRESETS = ["coordinator", "read-only", "workspace-writer", "tests-writer"];
+var TOOL_PRESET_PROFILES = Object.freeze({
+  coordinator: "read-only",
+  "read-only": "read-only",
+  "workspace-writer": "edit",
+  "tests-writer": "edit"
+});
+var BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
+function toolPresetProfile(preset) {
+  if (!Object.hasOwn(TOOL_PRESET_PROFILES, preset)) return void 0;
+  return TOOL_PRESET_PROFILES[preset];
+}
+function toolPresetExceedsRoleMessage(preset, roleId, rolePermission, rolePreset) {
+  const profile = toolPresetProfile(preset);
+  if (profile !== "edit") return void 0;
+  if (rolePermission === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} permission read-only`;
+  }
+  if (rolePreset !== void 0 && toolPresetProfile(rolePreset) === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} preset ${rolePreset}`;
+  }
+  return void 0;
+}
 var SECRET_VALUE_PATTERNS = [
   /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/,
   /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/,
@@ -17831,6 +17852,15 @@ function objectValue(value) {
 function stringValue(value) {
   return typeof value === "string" ? value : void 0;
 }
+function roleById(roles, roleId) {
+  const direct = roles.get(roleId);
+  if (direct) return direct;
+  const folded = roleId.toLocaleLowerCase("en-US");
+  for (const role of roles.values()) {
+    if ((role.id ?? "").toLocaleLowerCase("en-US") === folded) return role;
+  }
+  return void 0;
+}
 function numberValue(value, fallback) {
   return typeof value === "number" ? value : fallback;
 }
@@ -18345,10 +18375,29 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
     if (executor && !executors.has(executor)) issues.push(issue3("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue3("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
+    const roleId = stringValue(agent.value.role);
+    const role = roleId ? roleById(roles, roleId) : void 0;
+    const rolePermission = stringValue(role?.value.permission);
+    if (preset && role && (rolePermission === "edit" || rolePermission === "read-only")) {
+      const message = toolPresetExceedsRoleMessage(
+        preset,
+        role.id ?? roleId ?? "role",
+        rolePermission,
+        stringValue(objectValue(role.value.tools)?.preset)
+      );
+      if (message) issues.push(issue3("semantic", "tool_preset_exceeds_role", agent.logicalPath, message));
+    }
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue3("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
   }
+  for (const role of roles.values()) {
+    const permission = stringValue(role.value.permission);
+    const rolePreset = stringValue(objectValue(role.value.tools)?.preset);
+    if (permission === "read-only" && rolePreset && toolPresetProfile(rolePreset) === "edit") {
+      issues.push(issue3("semantic", "tool_preset_exceeds_role", role.logicalPath, `tools.preset ${rolePreset} exceeds permission read-only`));
+    }
+  }
   validateModelReferences(models, issues);
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
   if (!lookupKxmResource(workflows.values(), defaultWorkflow, "workflow")) issues.push(issue3("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
@@ -30125,6 +30174,68 @@ function unsupportedAgentStepTimeout(step, limitMs) {
     detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs"
   };
 }
+function narrowerPermission(left, right) {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+function stepRepositoryPermission(step) {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+function stepAccessDetail(step) {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries.map(([id, access]) => `${id} ${access}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0).join(", ");
+}
+function yamlToolsPreset(doc) {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return void 0;
+  const preset = tools.preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : void 0;
+}
+function resolveToolDispatch(projectRoot, step, agentId) {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join18(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join18(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join18(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : void 0;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : void 0;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`
+      }
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : void 0;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`
+      }
+    };
+  }
+  return { permission };
+}
 function executingSingletonAttempt(plan, state) {
   const current = state.currentStep;
   if (!current || current.panel.order.length !== 1) return void 0;
@@ -30317,10 +30428,17 @@ function prepareDispatch(context, runId, producerId, dispatchSources) {
   if (unsupported) return { kind: "return", state, handoff: { ...unsupported, stepId } };
   const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
   if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
+  const firstListed = step.assignments.allowedAgents[0];
+  const firstAgentId = step.kind === "agent" || step.kind === "moa" ? firstListed ? firstListed : step.agent : void 0;
+  if (firstAgentId) {
+    const toolDispatch = resolveToolDispatch(context.projectRoot, step, firstAgentId);
+    if ("error" in toolDispatch) {
+      return { kind: "return", state, handoff: { ...toolDispatch.error, stepId } };
+    }
+  }
   let resolvedRoute;
   if (producerId !== "driver-simulated") {
-    const allowed = step.assignments.allowedAgents;
-    const agentId = allowed && allowed.length > 0 && allowed[0] ? allowed[0] : step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator";
+    const agentId = firstAgentId ?? (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
     const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
     if ("error" in routeResult) {
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
@@ -30440,6 +30558,10 @@ function birthMember(context, input) {
   const born = folded.currentStep?.panel.order.length ?? 0;
   const allowed = input.step.assignments.allowedAgents;
   const agentId = allowed && allowed.length > born && allowed[born] ? allowed[born] : input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator";
+  const toolDispatch = resolveToolDispatch(context.projectRoot, input.step, agentId);
+  if ("error" in toolDispatch) {
+    return { handoff: { ...toolDispatch.error, stepId: input.stepId } };
+  }
   let resolvedRoute = input.resolvedRoute;
   if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
     const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
@@ -30529,7 +30651,7 @@ function birthMember(context, input) {
       stepAttempt: input.stepAttempt,
       objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only"
+      permissionCeiling: toolDispatch.permission
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -30574,7 +30696,7 @@ function birthMember(context, input) {
       prompt: input.step.instructions ? `${input.step.instructions}
 
 ${generatedPrompt}` : generatedPrompt,
-      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permission: toolDispatch.permission,
       ...(input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== void 0 ? { timeoutMs: input.step.timeoutMs } : {},
       contextPacket,
       ...resolvedRoute?.effort !== void 0 ? { thinking: resolvedRoute.effort } : {},

package/plugins/kxm/dist/server.js

@@ -15542,6 +15542,13 @@ var RESOURCE_SCHEMA = Object.freeze({
   workflow: { identity: "kxm.workflow.v1", file: "workflow.schema.json" },
   "gate-registry": { identity: "kxm.gate-registry.v1", file: "gate-registry.schema.json" }
 });
+var TOOL_PRESET_PROFILES = Object.freeze({
+  coordinator: "read-only",
+  "read-only": "read-only",
+  "workspace-writer": "edit",
+  "tests-writer": "edit"
+});
+var BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
 function compareCodeUnits(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
 }

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.168",
+  "version": "0.7.169",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-definitions/SKILL.md

@@ -12,8 +12,9 @@ or permission to execute an assignment.
 
 Dispatch reads `.kxm/roles/*.yaml` and `.kxm/models/*.yaml`. An agent binds
 a role with `role:` and does not pin `harness` or `model`. An agent
-`tools.preset` must be a registered preset. Narrowing that preset against
-the role preset is not validated yet (P3). `kxm routes` prints
+`tools.preset` must be a registered preset and may only narrow the role.
+A wider preset is refused at load (`tool_preset_exceeds_role`) and again
+at dispatch (`step_unsupported`). `kxm routes` prints
 admission from `.kxm/routes.yaml` and membership from the role files.
 The developer runner builds its policy object from those same files at
 `refs/remotes/origin/main`.

package/plugins/kxm/src/engine.ts

@@ -113,7 +113,7 @@ import {
   type KxmRunRecord,
   type KxmRunStatus,
 } from "./runtime-store.ts";
-import { KxmConfigError, kxmCanonicalJson, lookupKxmResource, type JsonValue, type KxmProjectBundle } from "./project-config.ts";
+import { KxmConfigError, kxmCanonicalJson, lookupKxmResource, toolPresetExceedsRoleMessage, toolPresetProfile, type JsonValue, type KxmProjectBundle } from "./project-config.ts";
 import { evaluateArtifactsGate } from "./engine-artifacts.ts";
 import { createCommandObserver } from "./engine-command.ts";
 import {
@@ -1726,6 +1726,85 @@ function unsupportedAgentStepTimeout(step: KxmCompiledStep, limitMs: number): Om
   };
 }
 
+function narrowerPermission(left: "read-only" | "edit", right: "read-only" | "edit"): "read-only" | "edit" {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+
+function stepRepositoryPermission(step: KxmCompiledStep): "read-only" | "edit" {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+
+function stepAccessDetail(step: KxmCompiledStep): string {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries
+    .map(([id, access]) => `${id} ${access}`)
+    .sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))
+    .join(", ");
+}
+
+function yamlToolsPreset(doc: Record<string, unknown> | undefined): string | undefined {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return undefined;
+  const preset = (tools as { preset?: unknown }).preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : undefined;
+}
+
+/**
+ * Dispatch permission is the narrowest of the role permission, the preset
+ * profile, and the step repository access. A wider agent preset, or a write
+ * step on a read-only chain, is step_unsupported.
+ */
+function resolveToolDispatch(
+  projectRoot: string,
+  step: KxmCompiledStep,
+  agentId: string,
+): { permission: "read-only" | "edit" } | { error: Omit<KxmRunHandoff, "stepId"> } {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission: "edit" | "read-only" | undefined = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : undefined;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : undefined;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`,
+      },
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain: "read-only" | "edit" = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : undefined;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`,
+      },
+    };
+  }
+  return { permission };
+}
+
 function executingSingletonAttempt(
   plan: KxmCompiledPlan,
   state: KxmRunState,
@@ -1944,12 +2023,21 @@ function prepareDispatch(
   const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
   if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
 
+  const firstListed = step.assignments.allowedAgents[0];
+  const firstAgentId = (step.kind === "agent" || step.kind === "moa")
+    ? (firstListed ? firstListed : step.agent)
+    : undefined;
+  if (firstAgentId) {
+    const toolDispatch = resolveToolDispatch(context.projectRoot, step, firstAgentId);
+    if ("error" in toolDispatch) {
+      return { kind: "return", state, handoff: { ...toolDispatch.error, stepId } };
+    }
+  }
+
   let resolvedRoute: ResolvedProducerRoute | undefined;
   if (producerId !== "driver-simulated") {
-    const allowed = step.assignments.allowedAgents;
-    const agentId = (allowed && allowed.length > 0 && allowed[0])
-      ? allowed[0]!
-      : (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
+    const agentId = firstAgentId
+      ?? ((step.kind === "agent" || step.kind === "moa") ? step.agent : "coordinator");
     const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
     if ("error" in routeResult) {
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
@@ -2092,6 +2180,10 @@ function birthMember(
   const agentId = (allowed && allowed.length > born && allowed[born])
     ? allowed[born]!
     : (input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator");
+  const toolDispatch = resolveToolDispatch(context.projectRoot, input.step, agentId);
+  if ("error" in toolDispatch) {
+    return { handoff: { ...toolDispatch.error, stepId: input.stepId } };
+  }
   let resolvedRoute = input.resolvedRoute;
   if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
     const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
@@ -2183,7 +2275,7 @@ function birthMember(
       stepAttempt: input.stepAttempt,
       objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permissionCeiling: toolDispatch.permission,
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -2227,7 +2319,7 @@ function birthMember(
       allowedOutcomes: input.step.outcomes,
       signal: controller.signal,
       prompt: input.step.instructions ? `${input.step.instructions}\n\n${generatedPrompt}` : generatedPrompt,
-      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permission: toolDispatch.permission,
       ...((input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== undefined
         ? { timeoutMs: input.step.timeoutMs }
         : {}),
@@ -3144,6 +3236,11 @@ export function kxmLiveRunPrerequisites(
     if (step.kind !== "agent" && step.kind !== "moa") continue;
     const agentIds = step.assignments.allowedAgents.length > 0 ? step.assignments.allowedAgents : [step.agent];
     for (const agentId of agentIds) {
+      const toolDispatch = resolveToolDispatch(projectRoot, step, agentId);
+      if ("error" in toolDispatch) {
+        prerequisites.push({ ...toolDispatch.error, stepId });
+        continue;
+      }
       const route = resolveProducerRoute(projectRoot, step, agentId);
       if ("error" in route) {
         const detail = route.error.detail === "producer_route_unsupported: agent step model is not honored"
@@ -3153,7 +3250,7 @@ export function kxmLiveRunPrerequisites(
         continue;
       }
       const harness = route.harness;
-      const permission = Object.values(step.repositories).includes("write") ? "edit" : "read-only";
+      const permission = toolDispatch.permission;
       if (!BUILTIN_HARNESSES.some((entry) => entry.id === harness && entry.oneShot) || !oneShotPermissionArgs(harness, permission)) {
         prerequisites.push({ reason: "step_unsupported", stepId, field: "harness", detail: `${agentId}: ${harness} has no audited ${permission} one-shot profile; use a supported workflow or execute this work directly in ${harness}, without substituting another harness` });
         continue;

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.168";
+const VERSION = "0.7.169";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/project-config.ts

@@ -104,7 +104,40 @@ const RESOURCE_SCHEMA: Readonly<Record<KxmResourceKind, { identity: string; file
 const IDENTIFIER = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$|clock\$)$/i;
 const BUILTIN_EXECUTORS = ["local", "ssh", "exe-dev"];
-const BUILTIN_TOOL_PRESETS = ["coordinator", "read-only", "workspace-writer", "tests-writer"];
+/** Builtin preset to the harness one-shot profile. An agent preset may only narrow. */
+export const TOOL_PRESET_PROFILES = Object.freeze({
+  coordinator: "read-only",
+  "read-only": "read-only",
+  "workspace-writer": "edit",
+  "tests-writer": "edit",
+} as const);
+const BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
+
+export function toolPresetProfile(preset: string): "read-only" | "edit" | undefined {
+  if (!Object.hasOwn(TOOL_PRESET_PROFILES, preset)) return undefined;
+  return TOOL_PRESET_PROFILES[preset as keyof typeof TOOL_PRESET_PROFILES];
+}
+
+/**
+ * Set when `preset` is wider than the role permission, or wider than a
+ * registered role preset. Same text at load and at dispatch.
+ */
+export function toolPresetExceedsRoleMessage(
+  preset: string,
+  roleId: string,
+  rolePermission: "edit" | "read-only",
+  rolePreset: string | undefined,
+): string | undefined {
+  const profile = toolPresetProfile(preset);
+  if (profile !== "edit") return undefined;
+  if (rolePermission === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} permission read-only`;
+  }
+  if (rolePreset !== undefined && toolPresetProfile(rolePreset) === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} preset ${rolePreset}`;
+  }
+  return undefined;
+}
 const SECRET_VALUE_PATTERNS: readonly RegExp[] = [
   /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/,
   /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/,
@@ -583,6 +616,16 @@ function stringValue(value: JsonValue | undefined): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
+function roleById(roles: ReadonlyMap<string, KxmResource>, roleId: string): KxmResource | undefined {
+  const direct = roles.get(roleId);
+  if (direct) return direct;
+  const folded = roleId.toLocaleLowerCase("en-US");
+  for (const role of roles.values()) {
+    if ((role.id ?? "").toLocaleLowerCase("en-US") === folded) return role;
+  }
+  return undefined;
+}
+
 function numberValue(value: JsonValue | undefined, fallback: number): number {
   return typeof value === "number" ? value : fallback;
 }
@@ -1224,10 +1267,29 @@ function validateBundle(
     if (executor && !executors.has(executor)) issues.push(issue("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
+    const roleId = stringValue(agent.value.role);
+    const role = roleId ? roleById(roles, roleId) : undefined;
+    const rolePermission = stringValue(role?.value.permission);
+    if (preset && role && (rolePermission === "edit" || rolePermission === "read-only")) {
+      const message = toolPresetExceedsRoleMessage(
+        preset,
+        role.id ?? roleId ?? "role",
+        rolePermission,
+        stringValue(objectValue(role.value.tools)?.preset),
+      );
+      if (message) issues.push(issue("semantic", "tool_preset_exceeds_role", agent.logicalPath, message));
+    }
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
   }
+  for (const role of roles.values()) {
+    const permission = stringValue(role.value.permission);
+    const rolePreset = stringValue(objectValue(role.value.tools)?.preset);
+    if (permission === "read-only" && rolePreset && toolPresetProfile(rolePreset) === "edit") {
+      issues.push(issue("semantic", "tool_preset_exceeds_role", role.logicalPath, `tools.preset ${rolePreset} exceeds permission read-only`));
+    }
+  }
   validateModelReferences(models, issues);
 
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";