fix(evolution): add policy evolution instructions to init templates and shorten denial message

- Add mandatory "Policy Evolution" section to all three governance
  templates (Cursor, OpenClaw, Claude Code) so agents present
  suggestion IDs to the user and call policy_evolution_approve with
  the user's decision; explicitly require agents not to ignore
  suggestion IDs.
- Shorten McpEvolutionHandler denial message to a single actionable
  line to reduce verbosity in tool responses.
- Bump version to 0.4.2 and document in RELEASE_NOTES.md.

Author: elliot35

RELEASE_NOTES.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-02-12
+
+### Fixed
+
+- **Policy evolution agent instructions** — Init governance templates (Cursor, OpenClaw, Claude Code) now include mandatory "Policy Evolution" instructions so agents present suggestion IDs to the user and call `policy_evolution_approve` with the user's decision; the MCP denial message was shortened to a single actionable line to avoid verbosity in tool responses.
+
+---
+
 ## [0.4.1] - 2026-02-12
 
 ### Fixed

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@det-acp/core",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Agent Governance Gateway — bounded, auditable, session-aware control for AI agents with MCP proxy, shell proxy, and HTTP API",
   "type": "module",
   "main": "dist/index.js",

src/cli/index.ts

@@ -33,7 +33,7 @@ const program = new Command();
 program
   .name('det-acp')
   .description('Deterministic Agent Control Protocol — Agent Governance Gateway')
-  .version('0.4.0');
+  .version('0.4.2');
 
 // ---------------------------------------------------------------------------
 // validate

src/cli/templates.ts

@@ -114,9 +114,21 @@ Instead of your built-in tools, you MUST use these governed equivalents:
 4. **ALWAYS** route file edits through \`governed-filesystem\` → \`edit_file\`.
 5. **ALWAYS** route directory listings through \`governed-filesystem\` → \`list_directory\`.
 6. **ALWAYS** route file searches through \`governed-filesystem\` → \`search_files\`.
-7. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback. Report the denial to the user instead.
+7. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback.
 8. If you need a tool that is not available through the governed MCP server, ask the user for permission before proceeding.
 
+## Policy Evolution — MANDATORY
+
+When a governed tool call is **denied** and the response contains a \`Suggestion ID\`, you **MUST** follow this workflow:
+
+1. **STOP** what you are doing. Do NOT skip the suggestion or continue with other tasks.
+2. **PRESENT** the suggested policy change to the user clearly, e.g.: *"The tool \`directory_tree\` was denied because it has no policy. Would you like to add it? Options: add to policy permanently, allow once for this session, or deny."*
+3. **WAIT** for the user to respond with their choice.
+4. **CALL** \`governed-filesystem\` → \`policy_evolution_approve\` with the \`suggestion_id\` from the denial and the user's \`decision\` (\`"add-to-policy"\`, \`"allow-once"\`, or \`"deny"\`).
+5. If the user chose "add-to-policy" or "allow-once", **RETRY** the original tool call that was denied.
+
+**You MUST NOT ignore a Suggestion ID. You MUST NOT continue without asking the user.**
+
 ## Why
 
 All file and system operations must go through the Deterministic Agent Control Protocol governance layer for policy enforcement and audit logging. Using built-in tools would bypass security policies, forbidden path protections, and the tamper-evident evidence ledger.
@@ -153,9 +165,21 @@ Instead of your built-in file tools, you MUST use these governed equivalents:
 4. **ALWAYS** route file edits through \`governed-filesystem\` → \`edit_file\`.
 5. **ALWAYS** route directory listings through \`governed-filesystem\` → \`list_directory\`.
 6. **ALWAYS** route file searches through \`governed-filesystem\` → \`search_files\`.
-7. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback. Report the denial to the user instead.
+7. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback.
 8. If you need a tool that is not available through the governed MCP server, ask the user for permission before proceeding.
 
+## Policy Evolution — MANDATORY
+
+When a governed tool call is **denied** and the response contains a \`Suggestion ID\`, you **MUST** follow this workflow:
+
+1. **STOP** what you are doing. Do NOT skip the suggestion or continue with other tasks.
+2. **PRESENT** the suggested policy change to the user clearly, e.g.: *"The tool \`directory_tree\` was denied because it has no policy. Would you like to add it? Options: add to policy permanently, allow once for this session, or deny."*
+3. **WAIT** for the user to respond with their choice.
+4. **CALL** \`governed-filesystem\` → \`policy_evolution_approve\` with the \`suggestion_id\` from the denial and the user's \`decision\` (\`"add-to-policy"\`, \`"allow-once"\`, or \`"deny"\`).
+5. If the user chose "add-to-policy" or "allow-once", **RETRY** the original tool call that was denied.
+
+**You MUST NOT ignore a Suggestion ID. You MUST NOT continue without asking the user.**
+
 ## Why
 
 All file and system operations must go through the Deterministic Agent Control Protocol governance layer for policy enforcement and audit logging. Using built-in tools would bypass security policies, forbidden path protections, and the tamper-evident evidence ledger.
@@ -188,9 +212,21 @@ Instead of your built-in file tools, you MUST use these governed equivalents:
 
 1. **NEVER** use built-in file read/write/edit tools for any file operation when the governed MCP tools are available.
 2. **ALWAYS** route file operations through the \`governed-filesystem\` MCP server.
-3. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback. Report the denial to the user instead.
+3. If a governed tool call is **denied by policy**, you MUST respect the denial. Do NOT attempt to use a built-in tool as a fallback.
 4. If you need a tool that is not available through the governed MCP server, ask the user for permission before proceeding.
 
+## Policy Evolution — MANDATORY
+
+When a governed tool call is **denied** and the response contains a \`Suggestion ID\`, you **MUST** follow this workflow:
+
+1. **STOP** what you are doing. Do NOT skip the suggestion or continue with other tasks.
+2. **PRESENT** the suggested policy change to the user clearly, e.g.: *"The tool \`directory_tree\` was denied because it has no policy. Would you like to add it? Options: add to policy permanently, allow once for this session, or deny."*
+3. **WAIT** for the user to respond with their choice.
+4. **CALL** \`governed-filesystem\` → \`policy_evolution_approve\` with the \`suggestion_id\` from the denial and the user's \`decision\` (\`"add-to-policy"\`, \`"allow-once"\`, or \`"deny"\`).
+5. If the user chose "add-to-policy" or "allow-once", **RETRY** the original tool call that was denied.
+
+**You MUST NOT ignore a Suggestion ID. You MUST NOT continue without asking the user.**
+
 ## Why
 
 All file and system operations must go through the Deterministic Agent Control Protocol governance layer for policy enforcement and audit logging. Using built-in tools would bypass security policies, forbidden path protections, and the tamper-evident evidence ledger.

src/evolution/mcp-handler.ts

@@ -124,12 +124,7 @@ export class McpEvolutionHandler {
       `[Policy Evolution] Suggested change: ${suggestion.description}`,
       `Suggestion ID: ${suggestionId}`,
       '',
-      'Present this suggestion to the user and ask for their decision:',
-      '  - "add-to-policy" — permanently add to the policy file',
-      '  - "allow-once" — allow for this session only',
-      '  - "deny" — keep the restriction',
-      '',
-      `Then call the "${TOOL_NAME}" tool with the suggestion_id and their decision.`,
+      'ACTION REQUIRED: Ask the user whether to "add-to-policy", "allow-once", or "deny", then call policy_evolution_approve with the suggestion_id and their decision. If approved, retry the original tool call.',
     ].join('\n');
 
     return {