ocsmarttools 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to `ocsmarttools` are documented here.
 
+## [0.1.5] - 2026-02-22
+
+### Added
+- Plugin-native strict routing mode (`strictRouting`) for fully self-managed routing behavior.
+- New strict commands in chat and CLI:
+  - `/ocsmarttools strict <on|off|status>`
+  - `openclaw ocsmarttools strict <on|off>`
+- Strict/non-strict auto-managed routing policy variants in `AGENTS.md`.
+
+### Changed
+- `strictRouting=true` now forces `autoInjectRoutingGuide=true`.
+- Routing sync now applies the strict policy variant automatically when strict mode is enabled.
+
+## [0.1.4] - 2026-02-22
+
+### Changed
+- Broadened peer compatibility range to `openclaw >=2026.2.19` for easier installs across existing instances.
+
+### Fixed
+- Routing policy sync is now fail-safe on restricted/read-only environments (never breaks plugin startup).
+- Setup/config flows now return clear messages when routing sync is skipped due to filesystem permissions/path issues.
+
 ## [0.1.3] - 2026-02-22
 
 ### Added

package/README.md

@@ -23,6 +23,10 @@ flowchart LR
 
 ## Install
 
+Compatibility:
+- OpenClaw: `>=2026.2.19`
+- Works with existing installed instances (no core patch required)
+
 ### npm
 
 ```bash
@@ -44,7 +48,13 @@ openclaw gateway restart
 1. Install + enable + restart.
 2. Done. The plugin auto-bootstraps and starts working in background.
 3. It also auto-manages an OCSmartTools routing block in `AGENTS.md` (unless disabled).
-4. Optional check:
+4. Enable strict plugin-managed routing (optional):
+
+```text
+/ocsmarttools strict on
+```
+
+5. Optional check:
 
 ```text
 /ocsmarttools status
@@ -67,6 +77,7 @@ Model note:
 | `/ocsmarttools stats reset` | Resets the stats window |
 | `/ocsmarttools setup [safe\|standard]` | Applies recommended defaults for the selected mode |
 | `/ocsmarttools mode <safe\|standard>` | Changes mode only |
+| `/ocsmarttools strict <on\|off\|status>` | Enables/disables strict plugin-managed routing |
 | `/ocsmarttools sync` | Re-applies the auto-managed routing policy block in `AGENTS.md` |
 | `/ocsmarttools config` | Shows effective plugin config |
 | `/ocsmarttools config keys` | Lists editable config keys |
@@ -84,6 +95,7 @@ Model note:
 | `openclaw ocsmarttools stats reset` | Resets the stats window |
 | `openclaw ocsmarttools setup [safe\|standard]` | Applies recommended defaults for the selected mode |
 | `openclaw ocsmarttools mode <safe\|standard>` | Changes mode only |
+| `openclaw ocsmarttools strict <on\|off>` | Enables/disables strict plugin-managed routing |
 | `openclaw ocsmarttools sync` | Re-applies the auto-managed routing policy block in `AGENTS.md` |
 | `openclaw ocsmarttools config` | Shows effective plugin config |
 | `openclaw ocsmarttools config keys` | Lists editable config keys |
@@ -99,6 +111,7 @@ Model note:
 /ocsmarttools config set storeLargeResults true
 /ocsmarttools config set toolSearch.useLiveRegistry true
 /ocsmarttools config set toolSearch.liveTimeoutMs 1500
+/ocsmarttools config set strictRouting true
 /ocsmarttools config set autoInjectRoutingGuide true
 /ocsmarttools config set autoInjectRoutingGuide false
 /ocsmarttools config reset maxResultChars
@@ -112,6 +125,7 @@ Config path:
 
 - `standard` (default): zero-touch mode, no sandbox requirement, control-plane dispatch still blocked
 - `safe`: requires sandboxed execution and blocks control-plane dispatch (`gateway`, `cron`)
+- `strictRouting=true`: strict plugin-managed routing policy is auto-synced with no manual workspace edits.
 
 Setup default:
 - `/ocsmarttools setup` and `openclaw ocsmarttools setup` default to `standard`.
@@ -149,6 +163,7 @@ If your instance uses strict `tools.allow`, include:
 
 - `ocsmarttools` does not bypass OpenClaw tool policy.
 - Routing policy is auto-injected into `AGENTS.md` with managed markers; it can be re-synced via `/ocsmarttools sync`.
+- `strictRouting=true` forces `autoInjectRoutingGuide=true`.
 - `tool_batch` is intentionally bounded (`maxSteps`, `maxForEach`).
 - Large-result handles are in-memory and expire by TTL.
 - `tool_result_get` works only while handle is still valid.

package/openclaw.plugin.json

@@ -8,6 +8,7 @@
     "properties": {
       "enabled": { "type": "boolean" },
       "mode": { "type": "string", "enum": ["safe", "standard"] },
+      "strictRouting": { "type": "boolean" },
       "autoInjectRoutingGuide": { "type": "boolean" },
       "maxSteps": { "type": "integer", "minimum": 1, "maximum": 200 },
       "maxForEach": { "type": "integer", "minimum": 1, "maximum": 200 },
@@ -32,6 +33,7 @@
   },
   "uiHints": {
     "mode": { "label": "Mode" },
+    "strictRouting": { "label": "Strict Routing" },
     "autoInjectRoutingGuide": { "label": "Auto Inject Routing Guide" },
     "maxSteps": { "label": "Max Steps", "advanced": true },
     "maxForEach": { "label": "Max ForEach", "advanced": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocsmarttools",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Provider-agnostic advanced tool orchestration plugin for OpenClaw with search, dispatch, and batching",
   "type": "module",
   "scripts": {
@@ -24,7 +24,7 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "openclaw": ">=2026.2.21"
+    "openclaw": ">=2026.2.19"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

package/src/commands/chat.ts

@@ -13,6 +13,7 @@ import {
   resetConfig,
   setConfigKey,
   syncManagedRouting,
+  updateStrictRouting,
   updateMode,
 } from "./operations.js";
 import type { AdvToolsMode } from "../lib/plugin-config.js";
@@ -73,6 +74,20 @@ export function registerChatCommands(api: OpenClawPluginApi, metrics: MetricsSto
           return { text: await updateMode(api, mode) };
         }
 
+        if (cmd === "strict") {
+          const arg = (parts[1] ?? "status").toLowerCase();
+          if (arg === "status") {
+            return { text: renderStatus(api) };
+          }
+          if (arg === "on" || arg === "true" || arg === "enable") {
+            return { text: await updateStrictRouting(api, true) };
+          }
+          if (arg === "off" || arg === "false" || arg === "disable") {
+            return { text: await updateStrictRouting(api, false) };
+          }
+          return { text: "Usage: /ocsmarttools strict <on|off|status>" };
+        }
+
         if (cmd === "sync") {
           return { text: await syncManagedRouting(api) };
         }
@@ -112,6 +127,7 @@ export function registerChatCommands(api: OpenClawPluginApi, metrics: MetricsSto
               "/ocsmarttools config set <key> <value>",
               "/ocsmarttools config reset [key]",
               "/ocsmarttools sync",
+              "/ocsmarttools strict <on|off|status>",
             ].join("\n"),
           };
         }

package/src/commands/cli.ts

@@ -11,6 +11,7 @@ import {
   resetConfig,
   setConfigKey,
   syncManagedRouting,
+  updateStrictRouting,
   updateMode,
 } from "./operations.js";
 import type { AdvToolsMode } from "../lib/plugin-config.js";
@@ -98,6 +99,24 @@ export function registerCliCommands(api: OpenClawPluginApi, metrics: MetricsStor
           console.log(text);
         });
 
+      adv
+        .command("strict <state>")
+        .description("Set strict routing on/off (state: on|off)")
+        .action(async (stateRaw: string) => {
+          const state = stateRaw.trim().toLowerCase();
+          if (["on", "true", "enable"].includes(state)) {
+            // eslint-disable-next-line no-console
+            console.log(await updateStrictRouting(api, true));
+            return;
+          }
+          if (["off", "false", "disable"].includes(state)) {
+            // eslint-disable-next-line no-console
+            console.log(await updateStrictRouting(api, false));
+            return;
+          }
+          throw new Error("strict state must be one of: on, off");
+        });
+
       adv
         .command("config")
         .description("Show effective plugin config")

package/src/commands/operations.ts

@@ -21,6 +21,7 @@ type ConfigSpec =
 const CONFIG_SPECS: Record<string, ConfigSpec> = {
   enabled: { kind: "boolean" },
   mode: { kind: "enum", values: ["safe", "standard"] },
+  strictRouting: { kind: "boolean" },
   autoInjectRoutingGuide: { kind: "boolean" },
   maxSteps: { kind: "integer", min: 1, max: 200 },
   maxForEach: { kind: "integer", min: 1, max: 200 },
@@ -40,6 +41,7 @@ const CONFIG_SPECS: Record<string, ConfigSpec> = {
 const DEFAULT_BY_KEY: Record<string, boolean | number | string> = {
   enabled: DEFAULT_SETTINGS.enabled,
   mode: DEFAULT_SETTINGS.mode,
+  strictRouting: DEFAULT_SETTINGS.strictRouting,
   autoInjectRoutingGuide: DEFAULT_SETTINGS.autoInjectRoutingGuide,
   maxSteps: DEFAULT_SETTINGS.maxSteps,
   maxForEach: DEFAULT_SETTINGS.maxForEach,
@@ -143,6 +145,7 @@ export function renderStatus(api: OpenClawPluginApi): string {
     "OCSmartTools Status",
     `- plugin: ${api.id}`,
     `- mode: ${s.mode}`,
+    `- strictRouting: ${s.strictRouting}`,
     `- autoInjectRoutingGuide: ${s.autoInjectRoutingGuide}`,
     `- tool_search enabled: ${s.toolSearch.enabled}`,
     `- maxSteps: ${s.maxSteps}`,
@@ -169,6 +172,7 @@ export function renderHelp(): string {
     "- /ocsmarttools stats reset: Reset metrics window",
     "- /ocsmarttools setup [safe|standard]: Apply recommended defaults (default: standard)",
     "- /ocsmarttools mode <safe|standard>: Switch only the operating mode",
+    "- /ocsmarttools strict [on|off|status]: Toggle strict routing behavior",
     "- /ocsmarttools sync: Re-apply auto-managed routing policy to AGENTS.md",
     "- /ocsmarttools config: Show effective plugin config",
     "- /ocsmarttools config keys: List editable config keys",
@@ -177,6 +181,7 @@ export function renderHelp(): string {
     "",
     "Examples:",
     "- /ocsmarttools config set maxResultChars 120000",
+    "- /ocsmarttools strict on",
     "- /ocsmarttools config set storeLargeResults true",
     "- /ocsmarttools config reset maxResultChars",
   ].join("\n");
@@ -234,6 +239,7 @@ export function renderConfig(api: OpenClawPluginApi): string {
     "OCSmartTools Config",
     `- enabled: ${s.enabled}`,
     `- mode: ${s.mode}`,
+    `- strictRouting: ${s.strictRouting}`,
     `- autoInjectRoutingGuide: ${s.autoInjectRoutingGuide}`,
     `- maxSteps: ${s.maxSteps}`,
     `- maxForEach: ${s.maxForEach}`,
@@ -277,10 +283,21 @@ export async function setConfigKey(
   entryObj.config = pluginCfg;
 
   setValueAtPath(pluginCfg, key, parsed.value);
+  if (key === "strictRouting" && parsed.value === true) {
+    setValueAtPath(pluginCfg, "autoInjectRoutingGuide", true);
+  }
   await writeConfig(api, next);
 
-  if (key === "autoInjectRoutingGuide" && parsed.value === true) {
-    await syncRoutingGuide(api, next);
+  if (key === "autoInjectRoutingGuide" || key === "strictRouting") {
+    const strictRouting = resolveSettings(api, next).strictRouting;
+    const shouldSync = resolveSettings(api, next).autoInjectRoutingGuide;
+    if (!shouldSync) {
+      return `Config updated: ${key}=${JSON.stringify(parsed.value)}.`;
+    }
+    const sync = await syncRoutingGuide(api, next, { strictRouting });
+    if (sync.error) {
+      return `Config updated: ${key}=${JSON.stringify(parsed.value)} (routing sync skipped: ${sync.error}).`;
+    }
   }
 
   return `Config updated: ${key}=${JSON.stringify(parsed.value)}.`;
@@ -297,9 +314,17 @@ export async function resetConfig(api: OpenClawPluginApi, key?: string): Promise
     for (const cfgKey of sortedKeys()) {
       setValueAtPath(pluginCfg, cfgKey, DEFAULT_BY_KEY[cfgKey]);
     }
+    if (DEFAULT_SETTINGS.strictRouting) {
+      setValueAtPath(pluginCfg, "autoInjectRoutingGuide", true);
+    }
     await writeConfig(api, next);
-    if (DEFAULT_SETTINGS.autoInjectRoutingGuide) {
-      await syncRoutingGuide(api, next);
+    if (resolveSettings(api, next).autoInjectRoutingGuide) {
+      const sync = await syncRoutingGuide(api, next, {
+        strictRouting: resolveSettings(api, next).strictRouting,
+      });
+      if (sync.error) {
+        return `Config reset to plugin defaults (routing sync skipped: ${sync.error}).`;
+      }
     }
     return "Config reset to plugin defaults.";
   }
@@ -309,9 +334,20 @@ export async function resetConfig(api: OpenClawPluginApi, key?: string): Promise
   }
 
   setValueAtPath(pluginCfg, key, DEFAULT_BY_KEY[key]);
+  if (key === "strictRouting" && DEFAULT_BY_KEY[key] === true) {
+    setValueAtPath(pluginCfg, "autoInjectRoutingGuide", true);
+  }
   await writeConfig(api, next);
-  if (key === "autoInjectRoutingGuide" && DEFAULT_BY_KEY[key] === true) {
-    await syncRoutingGuide(api, next);
+  if (key === "autoInjectRoutingGuide" || key === "strictRouting") {
+    const strictRouting = resolveSettings(api, next).strictRouting;
+    const shouldSync = resolveSettings(api, next).autoInjectRoutingGuide;
+    if (!shouldSync) {
+      return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])}.`;
+    }
+    const sync = await syncRoutingGuide(api, next, { strictRouting });
+    if (sync.error) {
+      return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])} (routing sync skipped: ${sync.error}).`;
+    }
   }
   return `Config key reset: ${key}=${JSON.stringify(DEFAULT_BY_KEY[key])}.`;
 }
@@ -336,6 +372,7 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
 
   pluginCfg.enabled = true;
   pluginCfg.mode = mode;
+  pluginCfg.strictRouting = false;
   pluginCfg.autoInjectRoutingGuide = true;
   pluginCfg.maxSteps = DEFAULT_SETTINGS.maxSteps;
   pluginCfg.maxForEach = DEFAULT_SETTINGS.maxForEach;
@@ -361,12 +398,16 @@ export async function applySetup(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   );
 
   await writeConfig(api, next);
-  await syncRoutingGuide(api, next);
+  const sync = await syncRoutingGuide(api, next, { strictRouting: false });
+  const syncLine = sync.error
+    ? `- routing guide sync skipped: ${sync.error}`
+    : `- routing guide ${sync.changed ? "synced" : "already up to date"} (${sync.filePath ?? "AGENTS.md"})`;
 
   return [
     "OCSmartTools setup applied.",
     `- mode: ${mode}`,
     "- autoInjectRoutingGuide: true",
+    syncLine,
     `- ensured tools.allow includes: ${ADVTOOLS_TOOL_NAMES.join(", ")}`,
     "- config written via runtime config writer",
     "If your gateway does not hot-apply this change, run: openclaw gateway restart",
@@ -388,13 +429,38 @@ export async function updateMode(api: OpenClawPluginApi, mode: AdvToolsMode): Pr
   return `Mode updated to ${mode}.`;
 }
 
+export async function updateStrictRouting(api: OpenClawPluginApi, enabled: boolean): Promise<string> {
+  const next = deepCloneConfig(api.runtime.config.loadConfig());
+  const { entryObj } = ensurePluginEntry(next, api.id);
+  entryObj.enabled = true;
+
+  const pluginCfg = asObj(entryObj.config);
+  entryObj.config = pluginCfg;
+  pluginCfg.strictRouting = enabled;
+  if (enabled) {
+    pluginCfg.autoInjectRoutingGuide = true;
+  }
+
+  await writeConfig(api, next);
+  if (resolveSettings(api, next).autoInjectRoutingGuide) {
+    const sync = await syncRoutingGuide(api, next, { strictRouting: enabled });
+    if (sync.error) {
+      return `Strict routing ${enabled ? "enabled" : "disabled"} (routing sync skipped: ${sync.error}).`;
+    }
+  }
+  return `Strict routing ${enabled ? "enabled" : "disabled"}.`;
+}
+
 export async function syncManagedRouting(api: OpenClawPluginApi): Promise<string> {
   const loaded = api.runtime.config.loadConfig();
   const settings = resolveSettings(api, loaded);
   if (!settings.autoInjectRoutingGuide) {
     return "Routing guide sync skipped: autoInjectRoutingGuide=false.";
   }
-  const result = await syncRoutingGuide(api, loaded);
+  const result = await syncRoutingGuide(api, loaded, { strictRouting: settings.strictRouting });
+  if (result.error) {
+    return `Routing guide sync skipped: ${result.error}`;
+  }
   if (!result.changed) {
     return `Routing guide already up to date (${result.filePath ?? "AGENTS.md"}).`;
   }

package/src/lib/bootstrap.ts

@@ -46,6 +46,7 @@ export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed:
 
   setDefault("enabled", true);
   setDefault("mode", DEFAULT_SETTINGS.mode);
+  setDefault("strictRouting", DEFAULT_SETTINGS.strictRouting);
   setDefault("autoInjectRoutingGuide", DEFAULT_SETTINGS.autoInjectRoutingGuide);
   setDefault("maxSteps", DEFAULT_SETTINGS.maxSteps);
   setDefault("maxForEach", DEFAULT_SETTINGS.maxForEach);
@@ -113,13 +114,24 @@ export async function autoBootstrap(api: OpenClawPluginApi): Promise<{ changed:
     await writeConfig(api, next);
   }
 
+  const strictRouting =
+    typeof pluginCfg.strictRouting === "boolean" ? pluginCfg.strictRouting : DEFAULT_SETTINGS.strictRouting;
+  if (strictRouting && pluginCfg.autoInjectRoutingGuide !== true) {
+    pluginCfg.autoInjectRoutingGuide = true;
+    changed = true;
+    notes.push("forced autoInjectRoutingGuide=true for strictRouting");
+    await writeConfig(api, next);
+  }
+
   const routingGuideEnabled =
     typeof pluginCfg.autoInjectRoutingGuide === "boolean"
       ? pluginCfg.autoInjectRoutingGuide
       : DEFAULT_SETTINGS.autoInjectRoutingGuide;
   if (routingGuideEnabled) {
-    const sync = await syncRoutingGuide(api, next);
-    if (sync.changed) {
+    const sync = await syncRoutingGuide(api, next, { strictRouting });
+    if (sync.error) {
+      notes.push(`routing guide skipped: ${sync.error}`);
+    } else if (sync.changed) {
       notes.push(`synced routing guide (${sync.filePath ?? "AGENTS.md"})`);
     }
   }

package/src/lib/plugin-config.ts

@@ -5,6 +5,7 @@ export type AdvToolsMode = "safe" | "standard";
 export type AdvToolsSettings = {
   enabled: boolean;
   mode: AdvToolsMode;
+  strictRouting: boolean;
   autoInjectRoutingGuide: boolean;
   maxSteps: number;
   maxForEach: number;
@@ -26,6 +27,7 @@ export type AdvToolsSettings = {
 export const DEFAULT_SETTINGS: AdvToolsSettings = {
   enabled: true,
   mode: "standard",
+  strictRouting: false,
   autoInjectRoutingGuide: true,
   maxSteps: 25,
   maxForEach: 20,
@@ -72,13 +74,16 @@ export function resolveSettings(api: OpenClawPluginApi, cfg: OpenClawConfig = ap
   const pluginCfg = asObj(entry.config ?? api.pluginConfig);
   const ts = asObj(pluginCfg.toolSearch);
 
+  const strictRouting = asBool(pluginCfg.strictRouting, DEFAULT_SETTINGS.strictRouting);
+  const autoInjectRoutingGuide = strictRouting
+    ? true
+    : asBool(pluginCfg.autoInjectRoutingGuide, DEFAULT_SETTINGS.autoInjectRoutingGuide);
+
   return {
     enabled: asBool(pluginCfg.enabled, DEFAULT_SETTINGS.enabled),
     mode: asMode(pluginCfg.mode, DEFAULT_SETTINGS.mode),
-    autoInjectRoutingGuide: asBool(
-      pluginCfg.autoInjectRoutingGuide,
-      DEFAULT_SETTINGS.autoInjectRoutingGuide,
-    ),
+    strictRouting,
+    autoInjectRoutingGuide,
     maxSteps: asInt(pluginCfg.maxSteps, DEFAULT_SETTINGS.maxSteps, 1, 200),
     maxForEach: asInt(pluginCfg.maxForEach, DEFAULT_SETTINGS.maxForEach, 1, 200),
     maxResultChars: asInt(pluginCfg.maxResultChars, DEFAULT_SETTINGS.maxResultChars, 500, 500000),

package/src/lib/routing-guide.ts

@@ -6,7 +6,60 @@ import type { OpenClawConfig, OpenClawPluginApi } from "openclaw/plugin-sdk";
 const BLOCK_START = "<!-- OCSMARTTOOLS_ROUTING_START -->";
 const BLOCK_END = "<!-- OCSMARTTOOLS_ROUTING_END -->";
 
-const ROUTING_BLOCK = `${BLOCK_START}
+function buildRoutingBlock(strictRouting: boolean): string {
+  const body = strictRouting
+    ? [
+        "## OCSmartTools Routing Policy (Auto-Managed, Strict)",
+        "",
+        "Default objective: preserve answer quality while reducing token and latency cost.",
+        "",
+        "Mandatory rules in strict mode:",
+        "1. Route tool usage through `tool_dispatch` or `tool_batch`.",
+        "2. Use `tool_batch` for 2+ related calls, iterative steps, or map-style tasks.",
+        "3. Use `tool_search` only when tool choice is unclear.",
+        "4. Use `tool_result_get` only when a stored handle needs more detail.",
+        "5. Avoid direct native tool calls unless routing tools are unavailable due to runtime/tool-policy constraints.",
+        "",
+        "Common large/noisy tools: `web_fetch`, `read` (large files), `exec`, `process`, `browser`, `nodes`.",
+      ].join("\n")
+    : [
+        "## OCSmartTools Routing Policy (Auto-Managed)",
+        "",
+        "Default objective: preserve answer quality while reducing token and latency cost.",
+        "",
+        "1. If tool usage is needed and result size is uncertain, use `tool_dispatch`.",
+        "2. If the task needs 2+ related tool calls, use `tool_batch`.",
+        "3. Use `tool_search` only when tool choice is unclear.",
+        "4. Prefer compact/tool-shaped outputs; use `tool_result_get` only when more detail is required.",
+        "5. Use direct native tool calls only for simple one-shot small-output actions.",
+        "",
+        "Common large/noisy tools: `web_fetch`, `read` (large files), `exec`, `process`, `browser`, `nodes`.",
+      ].join("\n");
+
+  return `${BLOCK_START}
+${body}
+${BLOCK_END}
+`;
+}
+
+const DEFAULT_BASE_CONTENT = "# AGENTS.md - Workspace Directives\n\nAdd local operating preferences below.\n";
+
+function upsertRoutingBlock(raw: string, strictRouting: boolean): string {
+  const routingBlock = buildRoutingBlock(strictRouting);
+  const source = raw.trim() ? raw : DEFAULT_BASE_CONTENT;
+
+  const start = source.indexOf(BLOCK_START);
+  const end = source.indexOf(BLOCK_END);
+  if (start >= 0 && end > start) {
+    const before = source.slice(0, start).replace(/\s*$/, "");
+    const after = source.slice(end + BLOCK_END.length).replace(/^\s*/, "");
+    return `${before}\n\n${routingBlock}\n${after}`.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  }
+  const joined = `${source.replace(/\s*$/, "")}\n\n${routingBlock}\n`;
+  return joined.replace(/\n{3,}/g, "\n\n");
+}
+
+const LEGACY_ROUTING_BLOCK = `${BLOCK_START}
 ## OCSmartTools Routing Policy (Auto-Managed)
 
 Default objective: preserve answer quality while reducing token and latency cost.
@@ -41,25 +94,14 @@ function resolveWorkspaceDir(cfg: OpenClawConfig): string {
   return path.join(os.homedir(), ".openclaw", "workspace");
 }
 
-function upsertRoutingBlock(raw: string): string {
-  const source = raw.trim()
-    ? raw
-    : "# AGENTS.md - Workspace Directives\n\nAdd local operating preferences below.\n";
-
-  const start = source.indexOf(BLOCK_START);
-  const end = source.indexOf(BLOCK_END);
-  if (start >= 0 && end > start) {
-    const before = source.slice(0, start).replace(/\s*$/, "");
-    const after = source.slice(end + BLOCK_END.length).replace(/^\s*/, "");
-    return `${before}\n\n${ROUTING_BLOCK}\n${after}`.replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-  }
-  const joined = `${source.replace(/\s*$/, "")}\n\n${ROUTING_BLOCK}\n`;
-  return joined.replace(/\n{3,}/g, "\n\n");
-}
-
-export async function syncRoutingGuide(api: OpenClawPluginApi, cfg: OpenClawConfig): Promise<{
+export async function syncRoutingGuide(
+  api: OpenClawPluginApi,
+  cfg: OpenClawConfig,
+  options?: { strictRouting?: boolean },
+): Promise<{
   changed: boolean;
   filePath?: string;
+  error?: string;
 }> {
   const workspaceDir = resolveWorkspaceDir(cfg);
   const filePath = path.join(workspaceDir, "AGENTS.md");
@@ -68,17 +110,34 @@ export async function syncRoutingGuide(api: OpenClawPluginApi, cfg: OpenClawConf
     current = await fs.readFile(filePath, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
-      throw error;
+      return {
+        changed: false,
+        filePath,
+        error: `read failed: ${error instanceof Error ? error.message : String(error)}`,
+      };
     }
   }
 
-  const next = upsertRoutingBlock(current);
-  if (next === current) {
+  const strictRouting = options?.strictRouting === true;
+  // If a legacy block exists, treat it as managed content and replace it with the latest variant.
+  const normalizedCurrent = current.includes(LEGACY_ROUTING_BLOCK)
+    ? current.replace(LEGACY_ROUTING_BLOCK, buildRoutingBlock(false))
+    : current;
+  const next = upsertRoutingBlock(normalizedCurrent, strictRouting);
+  if (next === current || next === normalizedCurrent) {
     return { changed: false, filePath };
   }
 
-  await fs.mkdir(workspaceDir, { recursive: true });
-  await fs.writeFile(filePath, next, "utf8");
+  try {
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await fs.writeFile(filePath, next, "utf8");
+  } catch (error) {
+    return {
+      changed: false,
+      filePath,
+      error: `write failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
   api.logger.info(`[ocsmarttools] routing policy synced: ${filePath}`);
   return { changed: true, filePath };
 }