@happycastle/oh-my-openclaw 0.14.2 → 0.15.1

package/agents/atlas.md

@@ -94,17 +94,20 @@ Every `task()` prompt MUST include ALL 6 sections:
 **If your prompt is under 30 lines, it's TOO SHORT.**
 </delegation_system>
 
+<task_setup>
+## BEFORE ANY WORK (NON-NEGOTIABLE)
+
+1. Call `omoc_todo_create` to plan all orchestration steps (one todo per step)
+2. Call `omoc_todo_list` to review the plan before starting
+3. Call `omoc_todo_update` to mark todos `in_progress` before starting, `completed` immediately after
+
+The `agent_end` hook warns about incomplete todos when the session ends.
+</task_setup>
+
 <workflow>
 ## Step 0: Register Tracking
 
-```
-TodoWrite([{
-  id: "orchestrate-plan",
-  content: "Complete ALL tasks in work plan",
-  status: "in_progress",
-  priority: "high"
-}])
-```
+Use `omoc_todo_create` to create todos for each orchestration step, then proceed.
 
 ## Step 1: Analyze Plan
 

package/agents/frontend.md

@@ -13,6 +13,12 @@ You are **Frontend**, the visual engineering specialist in the oh-my-openclaw sy
 - **Philosophy**: Design is how it works, not just how it looks. Ship pixel-perfect, accessible, performant interfaces.
 - **Strength**: Bridging design intent with production code
 
+## Task Setup (BEFORE ANY WORK)
+
+1. If new work with 2+ steps: call `omoc_todo_create` to plan all steps FIRST
+2. Track progress via `omoc_todo_update` (in_progress → completed per step)
+3. Call `omoc_todo_list` to review before starting — mark completed IMMEDIATELY after each step, NEVER batch
+
 ## Core Protocol
 
 ### Task Reception

package/agents/hephaestus.md

@@ -214,37 +214,33 @@ STOP searching when:
 
 ---
 
-## Todo Discipline (NON-NEGOTIABLE)
+## Task Setup (NON-NEGOTIABLE)
 
-**Track ALL multi-step work with todos. This is your execution backbone.**
+**BEFORE ANY WORK, set up task tracking. This is your execution backbone.**
 
-### When to Create Todos (MANDATORY)
+### First Action on Every Task (MANDATORY)
 
-- **2+ step task** — `todowrite` FIRST, atomic breakdown
-- **Uncertain scope** — `todowrite` to clarify thinking
-- **Complex single task** — Break down into trackable steps
-
-### Workflow (STRICT)
-
-1. **On task start**: `todowrite` with atomic steps—no announcements, just create
-2. **Before each step**: Mark `in_progress` (ONE at a time)
-3. **After each step**: Mark `completed` IMMEDIATELY (NEVER batch)
-4. **Scope changes**: Update todos BEFORE proceeding
+1. Call `omoc_todo_list` — check for incomplete todos
+2. If incomplete todos exist: resume them before starting new work
+3. If new work with 2+ steps: call `omoc_todo_create` for each step FIRST
+4. Before each step: `omoc_todo_update` → status `in_progress` (ONE at a time)
+5. After each step: `omoc_todo_update` → status `completed` IMMEDIATELY (NEVER batch)
+6. Scope changes: create new todos or update existing BEFORE proceeding
 
 ### Why This Matters
 
 - **Execution anchor**: Todos prevent drift from original request
 - **Recovery**: If interrupted, todos enable seamless continuation
-- **Accountability**: Each todo = explicit commitment to deliver
+- **Visibility**: `agent_end` warns about incomplete todos
 
 ### Anti-Patterns (BLOCKING)
 
-- **Skipping todos on multi-step work** — Steps get forgotten, user has no visibility
+- **Skipping `omoc_todo_list` at start** — You miss incomplete todos
+- **Starting work without `omoc_todo_create`** — Steps get forgotten, no visibility
 - **Batch-completing multiple todos** — Defeats real-time tracking purpose
 - **Proceeding without `in_progress`** — No indication of current work
-- **Finishing without completing todos** — Task appears incomplete
 
-**NO TODOS ON MULTI-STEP WORK = INCOMPLETE WORK.**
+**NO TODO SETUP ON MULTI-STEP WORK = INCOMPLETE WORK.**
 
 ---
 

package/agents/sisyphus-junior.md

@@ -8,15 +8,17 @@ Sisyphus-Junior - Focused executor from OhMyOpenCode.
 Execute tasks directly.
 </Role>
 
-<Todo_Discipline>
-TODO OBSESSION (NON-NEGOTIABLE):
-- 2+ steps → todowrite FIRST, atomic breakdown
-- Mark in_progress before starting (ONE at a time)
-- Mark completed IMMEDIATELY after each step
-- NEVER batch completions
+<Task_Setup>
+BEFORE ANY WORK (NON-NEGOTIABLE):
+1. Call `omoc_todo_list` to check existing incomplete todos
+2. If resuming: pick up where you left off
+3. If new work with 2+ steps: call `omoc_todo_create` for each step FIRST
+4. Mark in_progress before starting (ONE at a time via `omoc_todo_update`)
+5. Mark completed IMMEDIATELY after each step
+6. NEVER batch completions
 
-No todos on multi-step work = INCOMPLETE WORK.
-</Todo_Discipline>
+No todo setup on multi-step work = INCOMPLETE WORK.
+</Task_Setup>
 
 <Verification>
 Task NOT complete without:

package/dist/__tests__/helpers/mock-factory.js

@@ -15,6 +15,11 @@ export function createMockApi(overrides) {
             warn: vi.fn(),
             error: vi.fn(),
         },
+        runtime: {
+            system: {
+                enqueueSystemEvent: vi.fn(),
+            },
+        },
         registerHook: vi.fn(),
         registerTool: vi.fn(),
         registerCommand: vi.fn(),

package/dist/agents/agent-ids.d.ts

@@ -9,6 +9,6 @@ export declare const WORKER_IDS: Set<string>;
 /** Maps agent ID to markdown persona filename (without extension) */
 export declare const AGENT_MD_MAP: Record<string, string>;
 /** Maps agent ID to model tier for provider preset selection */
-export declare const AGENT_TIER_MAP: Record<string, 'strategic' | 'reasoning' | 'analysis' | 'worker' | 'deep-worker' | 'search' | 'research' | 'visual'>;
+export declare const AGENT_TIER_MAP: Record<string, 'planner' | 'orchestrator' | 'reasoning' | 'analysis' | 'worker' | 'deep-worker' | 'search' | 'research' | 'visual'>;
 /** All agent IDs (orchestrators + workers + read-only specialists) */
 export declare const ALL_AGENT_IDS: string[];

package/dist/agents/agent-ids.js

@@ -29,8 +29,8 @@ export const AGENT_MD_MAP = {
 };
 /** Maps agent ID to model tier for provider preset selection */
 export const AGENT_TIER_MAP = {
-    omoc_prometheus: 'strategic',
-    omoc_atlas: 'strategic',
+    omoc_prometheus: 'planner',
+    omoc_atlas: 'orchestrator',
     omoc_oracle: 'reasoning',
     omoc_metis: 'analysis',
     omoc_momus: 'analysis',

package/dist/cli/mcporter-setup.d.ts

@@ -0,0 +1,47 @@
+type McpServerEntry = {
+    url: string;
+    description: string;
+};
+/** Core MCP servers — always included in setup */
+export declare const CORE_MCP_SERVERS: Record<string, McpServerEntry>;
+/** Optional MCP servers — user can toggle during setup */
+export declare const OPTIONAL_MCP_SERVERS: Record<string, McpServerEntry>;
+/** All MCP servers (core + optional) — backward-compatible union */
+export declare const OMOC_MCP_SERVERS: Record<string, McpServerEntry>;
+type McporterConfig = {
+    mcpServers: Record<string, {
+        url?: string;
+        baseUrl?: string;
+        type?: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+};
+/**
+ * Resolve mcporter config path.
+ * Priority: ~/.openclaw/workspace/config/mcporter.json > ~/.config/mcporter/mcporter.json
+ */
+export declare function resolveMcporterConfigPath(): string;
+export declare function readMcporterConfig(configPath: string): McporterConfig;
+export declare function writeMcporterConfig(configPath: string, config: McporterConfig): void;
+export interface McporterMergeResult {
+    added: string[];
+    skipped: string[];
+}
+export declare function mergeMcpServers(existing: McporterConfig, servers: Record<string, McpServerEntry>): {
+    config: McporterConfig;
+    result: McporterMergeResult;
+};
+type Logger = {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+};
+export interface McporterSetupOptions {
+    configPath?: string;
+    excludeServers?: string[];
+    dryRun?: boolean;
+    logger: Logger;
+}
+export declare function runMcporterSetup(options: McporterSetupOptions): McporterMergeResult;
+export {};

package/dist/cli/mcporter-setup.js

@@ -0,0 +1,118 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/** Core MCP servers — always included in setup */
+export const CORE_MCP_SERVERS = {
+    exa: {
+        url: 'https://mcp.exa.ai/mcp?tools=web_search_exa',
+        description: 'Semantic web search (Exa)',
+    },
+    context7: {
+        url: 'https://mcp.context7.com/mcp',
+        description: 'Library/framework documentation search',
+    },
+    grep_app: {
+        url: 'https://mcp.grep.app',
+        description: 'Open-source code search on GitHub',
+    },
+};
+/** Optional MCP servers — user can toggle during setup */
+export const OPTIONAL_MCP_SERVERS = {
+    'web-search-prime': {
+        url: 'https://api.z.ai/api/mcp/web_search_prime/mcp',
+        description: 'Keyword-based web search (news, blogs, general)',
+    },
+    'web-reader': {
+        url: 'https://api.z.ai/api/mcp/web_reader/mcp',
+        description: 'Clean full-page content extraction',
+    },
+    zread: {
+        url: 'https://api.z.ai/api/mcp/zread/mcp',
+        description: 'Direct GitHub repository exploration',
+    },
+};
+/** All MCP servers (core + optional) — backward-compatible union */
+export const OMOC_MCP_SERVERS = {
+    ...CORE_MCP_SERVERS,
+    ...OPTIONAL_MCP_SERVERS,
+};
+/**
+ * Resolve mcporter config path.
+ * Priority: ~/.openclaw/workspace/config/mcporter.json > ~/.config/mcporter/mcporter.json
+ */
+export function resolveMcporterConfigPath() {
+    const homeDir = process.env['HOME'] ?? process.env['USERPROFILE'] ?? '';
+    const openclawPath = path.join(homeDir, '.openclaw', 'workspace', 'config', 'mcporter.json');
+    if (fs.existsSync(openclawPath)) {
+        return openclawPath;
+    }
+    const mcporterHomePath = path.join(homeDir, '.config', 'mcporter', 'mcporter.json');
+    if (fs.existsSync(mcporterHomePath)) {
+        return mcporterHomePath;
+    }
+    return openclawPath;
+}
+export function readMcporterConfig(configPath) {
+    if (!fs.existsSync(configPath)) {
+        return { mcpServers: {} };
+    }
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object') {
+        parsed.mcpServers = {};
+    }
+    return parsed;
+}
+export function writeMcporterConfig(configPath, config) {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+export function mergeMcpServers(existing, servers) {
+    const result = { added: [], skipped: [] };
+    const merged = { ...existing, mcpServers: { ...existing.mcpServers } };
+    for (const [name, entry] of Object.entries(servers)) {
+        if (merged.mcpServers[name]) {
+            result.skipped.push(name);
+        }
+        else {
+            merged.mcpServers[name] = { url: entry.url };
+            result.added.push(name);
+        }
+    }
+    return { config: merged, result };
+}
+export function runMcporterSetup(options) {
+    const { logger, dryRun = false, excludeServers = [] } = options;
+    const configPath = options.configPath ?? resolveMcporterConfigPath();
+    logger.info(`mcporter config: ${configPath}`);
+    const excludeSet = new Set(excludeServers);
+    const servers = {};
+    for (const [name, entry] of Object.entries(OMOC_MCP_SERVERS)) {
+        if (!excludeSet.has(name)) {
+            servers[name] = entry;
+        }
+    }
+    const existing = readMcporterConfig(configPath);
+    const { config: merged, result } = mergeMcpServers(existing, servers);
+    if (result.added.length === 0) {
+        logger.info('No changes needed — all MCP servers already configured.');
+        return result;
+    }
+    if (dryRun) {
+        logger.info(`[dry-run] Would add ${result.added.length} MCP server(s): ${result.added.join(', ')}`);
+        return result;
+    }
+    if (fs.existsSync(configPath)) {
+        const backupPath = configPath + '.bak';
+        fs.copyFileSync(configPath, backupPath);
+        logger.info(`Backup created: ${backupPath}`);
+    }
+    writeMcporterConfig(configPath, merged);
+    logger.info(`Added ${result.added.length} MCP server(s): ${result.added.join(', ')}`);
+    if (result.skipped.length > 0) {
+        logger.info(`Skipped ${result.skipped.length} existing server(s): ${result.skipped.join(', ')}`);
+    }
+    return result;
+}

package/dist/cli/model-presets.d.ts

@@ -1,5 +1,5 @@
 import { AGENT_TIER_MAP } from '../agents/agent-ids.js';
-export type ModelTier = 'strategic' | 'reasoning' | 'analysis' | 'worker' | 'deep-worker' | 'search' | 'research' | 'visual';
+export type ModelTier = 'planner' | 'orchestrator' | 'reasoning' | 'analysis' | 'worker' | 'deep-worker' | 'search' | 'research' | 'visual';
 export type ModelConfig = {
     primary: string;
     fallbacks: string[];

package/dist/cli/model-presets.js

@@ -1,7 +1,8 @@
 import { AGENT_TIER_MAP } from '../agents/agent-ids.js';
 export const PROVIDER_PRESETS = {
     anthropic: {
-        strategic: { primary: 'anthropic/claude-opus-4-6', fallbacks: ['openai/gpt-5.3-codex'] },
+        planner: { primary: 'anthropic/claude-opus-4-6', fallbacks: ['openai/gpt-5.3-codex'] },
+        orchestrator: { primary: 'anthropic/claude-sonnet-4-6', fallbacks: ['openai/gpt-4.1'] },
         reasoning: { primary: 'anthropic/claude-opus-4-6', fallbacks: ['openai/gpt-5.3-codex'] },
         analysis: { primary: 'anthropic/claude-sonnet-4-6', fallbacks: ['openai/gpt-4.1'] },
         worker: { primary: 'anthropic/claude-opus-4-6', fallbacks: ['openai/gpt-5.3-codex'] },
@@ -11,7 +12,8 @@ export const PROVIDER_PRESETS = {
         visual: { primary: 'google/gemini-3.1-pro', fallbacks: ['anthropic/claude-sonnet-4-6'] },
     },
     openai: {
-        strategic: { primary: 'openai/gpt-5.3-codex', fallbacks: ['anthropic/claude-opus-4-6'] },
+        planner: { primary: 'openai/gpt-5.3-codex', fallbacks: ['anthropic/claude-opus-4-6'] },
+        orchestrator: { primary: 'openai/gpt-4.1', fallbacks: ['anthropic/claude-sonnet-4-6'] },
         reasoning: { primary: 'openai/gpt-5.3-codex', fallbacks: ['anthropic/claude-opus-4-6'] },
         analysis: { primary: 'openai/gpt-4.1', fallbacks: ['anthropic/claude-sonnet-4-6'] },
         worker: { primary: 'openai/gpt-5.3-codex', fallbacks: ['anthropic/claude-opus-4-6'] },
@@ -21,7 +23,8 @@ export const PROVIDER_PRESETS = {
         visual: { primary: 'google/gemini-3.1-pro', fallbacks: ['openai/gpt-4.1'] },
     },
     google: {
-        strategic: { primary: 'google/gemini-3.1-pro', fallbacks: ['anthropic/claude-opus-4-6'] },
+        planner: { primary: 'google/gemini-3.1-pro', fallbacks: ['anthropic/claude-opus-4-6'] },
+        orchestrator: { primary: 'google/gemini-3-flash', fallbacks: ['anthropic/claude-sonnet-4-6'] },
         reasoning: { primary: 'google/gemini-3.1-pro', fallbacks: ['anthropic/claude-opus-4-6'] },
         analysis: { primary: 'google/gemini-3-flash', fallbacks: ['anthropic/claude-sonnet-4-6'] },
         worker: { primary: 'google/gemini-3.1-pro', fallbacks: ['anthropic/claude-opus-4-6'] },
@@ -38,7 +41,7 @@ export const PROVIDER_LABELS = {
     google: 'Google (Gemini)',
     custom: 'Custom (enter model IDs manually)',
 };
-export const MODEL_TIERS = ['strategic', 'reasoning', 'analysis', 'worker', 'deep-worker', 'search', 'research', 'visual'];
+export const MODEL_TIERS = ['planner', 'orchestrator', 'reasoning', 'analysis', 'worker', 'deep-worker', 'search', 'research', 'visual'];
 export function buildCustomPreset(tierModels) {
     const preset = {};
     for (const tier of MODEL_TIERS) {

package/dist/cli/setup.d.ts

@@ -27,6 +27,8 @@ export interface MergeResult {
     added: string[];
     skipped: string[];
     updated: string[];
+    mcporterAdded?: string[];
+    mcporterSkipped?: string[];
 }
 export declare function mergeAgentConfigs(existing: Array<{
     id: string;
@@ -39,18 +41,36 @@ export declare function mergeAgentConfigs(existing: Array<{
     result: MergeResult;
 };
 export declare function applyProviderToConfigs(configs: OmocAgentConfig[], provider: string): OmocAgentConfig[];
-export declare function runInteractiveSetup(logger: Logger): Promise<{
+export interface InteractiveSetupResult {
     provider: string;
-}>;
+    setupMcporter: boolean;
+    excludeServers: string[];
+    enableTodoEnforcer: boolean;
+    enablePlannerGuard: boolean;
+}
+export declare function runInteractiveSetup(logger: Logger): Promise<InteractiveSetupResult>;
 export interface SetupOptions {
     configPath?: string;
     workspaceDir?: string;
     force?: boolean;
     dryRun?: boolean;
     provider?: string;
+    setupMcporter?: boolean;
+    mcporterConfigPath?: string;
+    excludeServers?: string[];
+    enableTodoEnforcer?: boolean;
+    enablePlannerGuard?: boolean;
     interactive?: boolean;
     logger: Logger;
 }
+export declare function applyPlannerGuard(agentList: Array<{
+    id: string;
+    tools?: {
+        deny?: string[];
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}>): void;
 export declare function runSetup(options: SetupOptions): MergeResult;
 export declare function registerSetupCli(ctx: {
     program: {

package/dist/cli/setup.js

@@ -4,6 +4,8 @@ import * as readline from 'node:readline';
 import JSON5 from 'json5';
 import { OMOC_AGENT_CONFIGS } from '../agents/agent-configs.js';
 import { PROVIDER_PRESETS, PROVIDER_LABELS, AGENT_TIER_MAP, MODEL_TIERS, applyProviderPreset, getProviderNames, buildCustomPreset, registerCustomPreset, } from './model-presets.js';
+import { CORE_MCP_SERVERS, OPTIONAL_MCP_SERVERS, runMcporterSetup } from './mcporter-setup.js';
+import { PLANNER_DENY } from '../constants.js';
 const CONFIG_FILENAMES = [
     'openclaw.json5',
     'openclaw.json',
@@ -122,7 +124,8 @@ function askQuestion(rl, question) {
     });
 }
 const TIER_LABELS = {
-    strategic: 'Strategic Planning (prometheus, atlas)',
+    planner: 'Strategic Planning (prometheus)',
+    orchestrator: 'Orchestration (atlas)',
     reasoning: 'Deep Reasoning (oracle)',
     analysis: 'Analysis/Review (metis, momus)',
     worker: 'Implementation (sisyphus)',
@@ -148,8 +151,7 @@ function printPreview(logger, provider) {
 }
 async function runCustomProviderFlow(rl, logger) {
     logger.info('');
-    logger.info('  Enter model IDs for each tier.');
-    logger.info('  Format: provider/model (e.g., cliproxy/claude-opus-4-6, z.ai/gpt-5.3-codex)');
+    logger.info('Step 1/3: Select your AI provider');
     logger.info('');
     const tierModels = {};
     for (const tier of MODEL_TIERS) {
@@ -177,15 +179,23 @@ export async function runInteractiveSetup(logger) {
         input: process.stdin,
         output: process.stdout,
     });
+    const emptyResult = {
+        provider: '',
+        setupMcporter: false,
+        excludeServers: [],
+        enableTodoEnforcer: false,
+        enablePlannerGuard: false,
+    };
     try {
         logger.info('');
-        logger.info('🗺️  Oh-My-OpenClaw Agent Setup');
-        logger.info('─'.repeat(40));
+        logger.info('Oh-My-OpenClaw Agent Setup');
+        logger.info('-'.repeat(40));
         logger.info('');
+        // Step 1/4: Provider selection
         const presetProviders = getProviderNames();
         const choices = [...presetProviders, 'custom'];
         const choiceCount = choices.length;
-        logger.info('Step 1/2: Select your AI provider');
+        logger.info('Step 1/4: Select your AI provider');
         logger.info('');
         choices.forEach((p, i) => {
             logger.info(`  ${i + 1}. ${PROVIDER_LABELS[p] ?? p}`);
@@ -209,24 +219,63 @@ export async function runInteractiveSetup(logger) {
             provider = await runCustomProviderFlow(rl, logger);
         }
         logger.info('');
-        logger.info(`  ✓ Selected: ${PROVIDER_LABELS[provider] ?? 'Custom'}`);
+        logger.info(`  Selected: ${PROVIDER_LABELS[provider] ?? 'Custom'}`);
         logger.info('');
-        logger.info('Step 2/2: Model configuration preview');
+        // Step 2/4: Model preview + confirm
+        logger.info('Step 2/4: Model configuration preview');
         logger.info('');
         printPreview(logger, provider);
         logger.info('');
         const confirm = await askQuestion(rl, '  Apply this configuration? (Y/n): ');
         if (confirm.toLowerCase() === 'n' || confirm.toLowerCase() === 'no') {
             logger.info('  Setup cancelled.');
-            return { provider: '' };
+            return emptyResult;
         }
+        // Step 3/4: MCP servers
         logger.info('');
-        return { provider };
+        logger.info('Step 3/4: MCP servers');
+        logger.info('');
+        logger.info('  Core servers (always included):');
+        for (const [name, entry] of Object.entries(CORE_MCP_SERVERS)) {
+            logger.info(`    ${name}: ${entry.description}`);
+        }
+        logger.info('');
+        logger.info('  Optional servers:');
+        const excludeServers = [];
+        for (const [name, entry] of Object.entries(OPTIONAL_MCP_SERVERS)) {
+            const answer = await askQuestion(rl, `    Enable ${name} (${entry.description})? (Y/n): `);
+            if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+                excludeServers.push(name);
+            }
+        }
+        logger.info('');
+        const setupMcporter = true;
+        // Step 4/4: Plugin features
+        logger.info('Step 4/4: Plugin features');
+        logger.info('');
+        const todoAnswer = await askQuestion(rl, '  Enable todo enforcer (forces task tracking)? (Y/n): ');
+        const enableTodoEnforcer = todoAnswer.toLowerCase() !== 'n' && todoAnswer.toLowerCase() !== 'no';
+        const guardAnswer = await askQuestion(rl, '  Enable planner guard (prevents prometheus from editing code)? (Y/n): ');
+        const enablePlannerGuard = guardAnswer.toLowerCase() !== 'n' && guardAnswer.toLowerCase() !== 'no';
+        logger.info('');
+        return { provider, setupMcporter, excludeServers, enableTodoEnforcer, enablePlannerGuard };
     }
     finally {
         rl.close();
     }
 }
+export function applyPlannerGuard(agentList) {
+    for (const agent of agentList) {
+        if (agent.id === 'omoc_prometheus') {
+            if (!agent.tools) {
+                agent.tools = {};
+            }
+            const existingDeny = agent.tools.deny ?? [];
+            const merged = new Set([...existingDeny, ...PLANNER_DENY]);
+            agent.tools.deny = [...merged];
+        }
+    }
+}
 export function runSetup(options) {
     const { logger, force = false, dryRun = false, provider } = options;
     const configPath = options.configPath ?? findConfigPath(options.workspaceDir);
@@ -281,6 +330,37 @@ export function runSetup(options) {
     if (result.added.length === 0 && result.updated.length === 0) {
         logger.info('No changes needed — all OmOC agents already present.');
     }
+    if (options.enablePlannerGuard) {
+        applyPlannerGuard(config.agents.list);
+        if (!dryRun) {
+            fs.writeFileSync(configPath, serializeConfig(config), 'utf-8');
+        }
+        logger.info('Planner guard enabled: prometheus restricted from code editing');
+    }
+    if (options.enableTodoEnforcer !== undefined) {
+        const pluginSettings = (config.pluginSettings ?? {});
+        if (!pluginSettings['oh-my-openclaw']) {
+            pluginSettings['oh-my-openclaw'] = {};
+        }
+        pluginSettings['oh-my-openclaw']['todo_enforcer_enabled'] = options.enableTodoEnforcer;
+        config.pluginSettings = pluginSettings;
+        if (!dryRun) {
+            fs.writeFileSync(configPath, serializeConfig(config), 'utf-8');
+        }
+        logger.info(`Todo enforcer: ${options.enableTodoEnforcer ? 'enabled' : 'disabled'}`);
+    }
+    if (options.setupMcporter) {
+        logger.info('');
+        logger.info('Setting up mcporter MCP servers...');
+        const mcpResult = runMcporterSetup({
+            configPath: options.mcporterConfigPath,
+            excludeServers: options.excludeServers,
+            dryRun,
+            logger,
+        });
+        result.mcporterAdded = mcpResult.added;
+        result.mcporterSkipped = mcpResult.skipped;
+    }
     return result;
 }
 export function registerSetupCli(ctx) {
@@ -299,11 +379,19 @@ export function registerSetupCli(ctx) {
                 const valid = getProviderNames().join(', ');
                 throw new Error(`Unknown provider "${provider}". Valid: ${valid}`);
             }
+            let setupMcporter = false;
+            let excludeServers = [];
+            let enableTodoEnforcer;
+            let enablePlannerGuard;
             if (!provider && process.stdin.isTTY) {
                 const result = await runInteractiveSetup(ctx.logger);
                 if (!result.provider)
                     return;
                 provider = result.provider;
+                setupMcporter = result.setupMcporter;
+                excludeServers = result.excludeServers;
+                enableTodoEnforcer = result.enableTodoEnforcer;
+                enablePlannerGuard = result.enablePlannerGuard;
             }
             runSetup({
                 configPath: opts.config,
@@ -311,6 +399,10 @@ export function registerSetupCli(ctx) {
                 force: provider ? true : opts.force,
                 dryRun: opts.dryRun,
                 provider,
+                setupMcporter,
+                excludeServers,
+                enableTodoEnforcer,
+                enablePlannerGuard,
                 logger: ctx.logger,
             });
             ctx.logger.info('');

package/dist/constants.d.ts

@@ -3,5 +3,6 @@ export declare const TOOL_PREFIX = "omoc_";
 export declare const ABSOLUTE_MAX_RALPH_ITERATIONS = 100;
 export declare const LOG_PREFIX = "[omoc]";
 export declare const READ_ONLY_DENY: string[];
+export declare const PLANNER_DENY: string[];
 export declare const CATEGORIES: readonly ["quick", "deep", "ultrabrain", "visual-engineering", "multimodal", "artistry", "unspecified-low", "unspecified-high", "writing"];
 export type Category = (typeof CATEGORIES)[number];

package/dist/constants.js

@@ -4,6 +4,7 @@ export const TOOL_PREFIX = 'omoc_';
 export const ABSOLUTE_MAX_RALPH_ITERATIONS = 100;
 export const LOG_PREFIX = '[omoc]';
 export const READ_ONLY_DENY = ['write', 'edit', 'apply_patch', 'sessions_spawn'];
+export const PLANNER_DENY = ['write', 'edit', 'apply_patch'];
 // Category definitions
 export const CATEGORIES = [
     'quick',

package/dist/hooks/session-sync.js

@@ -7,7 +7,7 @@ export function registerSessionSync(api) {
     api.on('session_start', async (_event, ctx) => {
         try {
             const wsDir = ctx.workspaceDir;
-            const activePersona = await getActivePersona(wsDir);
+            const activePersona = await getActivePersona(wsDir, ctx.agentId);
             if (!activePersona)
                 return;
             const personaContent = readPersonaPromptSync(activePersona);

package/dist/hooks/spawn-guard.js

@@ -11,7 +11,7 @@ export function registerSpawnGuard(api) {
         }
         let activePersona;
         try {
-            activePersona = await getActivePersona(ctx.workspaceDir);
+            activePersona = await getActivePersona(ctx.workspaceDir, ctx.agentId);
         }
         catch {
             return;

package/dist/hooks/todo-reminder.d.ts

@@ -0,0 +1,7 @@
+import { OmocPluginApi } from '../types.js';
+declare const sessionCounters: Map<string, number>;
+export declare function registerTodoReminder(api: OmocPluginApi): void;
+export declare function registerAgentEndReminder(api: OmocPluginApi): void;
+export declare function registerSessionCleanup(api: OmocPluginApi): void;
+export declare function resetTodoReminderCounters(): void;
+export { sessionCounters as _sessionCounters };

package/dist/hooks/todo-reminder.js

@@ -0,0 +1,93 @@
+import { TOOL_PREFIX, LOG_PREFIX } from '../constants.js';
+import { getIncompleteTodos, resetStore } from '../tools/todo/store.js';
+const TODO_TOOL_NAMES = new Set([
+    `${TOOL_PREFIX}todo_create`,
+    `${TOOL_PREFIX}todo_list`,
+    `${TOOL_PREFIX}todo_update`,
+]);
+const TURN_THRESHOLD = 10;
+const REMINDER_MESSAGE = `
+
+---
+⚠️ [OMOC Todo Reminder] You have used ${TURN_THRESHOLD}+ tool calls without checking your todo list.
+
+**Action required:** Call \`${TOOL_PREFIX}todo_list\` to review pending todos before continuing.
+Ensure you are not drifting from the plan. Mark completed todos, update in-progress ones.`;
+const sessionCounters = new Map();
+function getSessionKey(payload) {
+    const sessionId = payload.sessionId;
+    return typeof sessionId === 'string' ? sessionId : '__default__';
+}
+export function registerTodoReminder(api) {
+    api.registerHook('tool_result_persist', (payload) => {
+        const toolName = payload.tool;
+        if (!toolName)
+            return undefined;
+        const sessionKey = getSessionKey(payload);
+        if (TODO_TOOL_NAMES.has(toolName)) {
+            sessionCounters.set(sessionKey, 0);
+            return undefined;
+        }
+        const current = sessionCounters.get(sessionKey) ?? 0;
+        const next = current + 1;
+        sessionCounters.set(sessionKey, next);
+        if (next >= TURN_THRESHOLD && next % TURN_THRESHOLD === 0) {
+            const content = typeof payload.content === 'string' ? payload.content : '';
+            return {
+                ...payload,
+                content: content + REMINDER_MESSAGE,
+            };
+        }
+        return undefined;
+    }, {
+        name: 'oh-my-openclaw.todo-reminder',
+        description: 'Reminds agent to check todo list after prolonged non-todo tool usage',
+    });
+}
+export function registerAgentEndReminder(api) {
+    api.on('agent_end', async (_event, ctx) => {
+        try {
+            const sessionKey = ctx.sessionKey ?? ctx.sessionId;
+            const incomplete = getIncompleteTodos(sessionKey);
+            if (incomplete.length === 0)
+                return;
+            const summary = incomplete
+                .map((t) => `  - [${t.status}] ${t.id}: ${t.content}`)
+                .join('\n');
+            const warning = `⚠️ [OMOC] ${incomplete.length} incomplete todo(s):\n${summary}\n\n` +
+                `Call \`${TOOL_PREFIX}todo_list\` to review and resume work.`;
+            if (sessionKey) {
+                api.runtime.system.enqueueSystemEvent(warning, { sessionKey });
+            }
+            api.logger.warn(`${LOG_PREFIX} Agent ended with ${incomplete.length} incomplete todo(s)`);
+        }
+        catch {
+            // graceful degradation
+        }
+    }, { priority: 50 });
+}
+function clearSession(sessionKey, api, reason) {
+    resetStore(sessionKey);
+    sessionCounters.delete(sessionKey);
+    api.logger.info(`${LOG_PREFIX} Todo store cleared (${reason}, session=${sessionKey})`);
+}
+export function registerSessionCleanup(api) {
+    api.on('session_start', async (event, ctx) => {
+        if (event.resumedFrom)
+            return;
+        const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? event.sessionId;
+        if (!sessionKey)
+            return;
+        clearSession(sessionKey, api, 'new session');
+    }, { priority: 190 });
+    api.on('session_end', async (event, ctx) => {
+        const sessionKey = ctx.sessionId ?? event.sessionId;
+        if (!sessionKey)
+            return;
+        clearSession(sessionKey, api, 'session_end');
+    }, { priority: 50 });
+}
+export function resetTodoReminderCounters() {
+    sessionCounters.clear();
+}
+export { sessionCounters as _sessionCounters };

package/dist/index.js

@@ -18,6 +18,8 @@ import { registerContextInjector } from './hooks/context-injector.js';
 import { registerSessionSync } from './hooks/session-sync.js';
 import { registerSpawnGuard } from './hooks/spawn-guard.js';
 import { registerKeywordDetector } from './hooks/keyword-detector/hook.js';
+import { registerTodoReminder, registerAgentEndReminder, registerSessionCleanup } from './hooks/todo-reminder.js';
+import { registerTodoTools } from './tools/todo/index.js';
 import { registerSetupCli } from './cli/setup.js';
 /**
  * Generation counter for multi-registration handling.
@@ -99,6 +101,26 @@ export default function register(api) {
         registry.hooks.push('spawn-guard');
         api.logger.info(`[${PLUGIN_ID}] Spawn guard hook registered (before_tool_call)`);
     });
+    safeRegister(api, 'todo-reminder', 'hook', () => {
+        registerTodoReminder(guarded);
+        registry.hooks.push('todo-reminder');
+        api.logger.info(`[${PLUGIN_ID}] Todo reminder hook registered (tool_result_persist)`);
+    });
+    safeRegister(api, 'agent-end-reminder', 'hook', () => {
+        registerAgentEndReminder(api);
+        registry.hooks.push('agent-end-reminder');
+        api.logger.info(`[${PLUGIN_ID}] Agent-end reminder hook registered (agent_end)`);
+    });
+    safeRegister(api, 'session-cleanup', 'hook', () => {
+        registerSessionCleanup(api);
+        registry.hooks.push('session-cleanup');
+        api.logger.info(`[${PLUGIN_ID}] Session cleanup hooks registered (session_start, session_end)`);
+    });
+    safeRegister(api, 'todo-tools', 'tool', () => {
+        registerTodoTools(api);
+        registry.tools.push('omoc_todo_create', 'omoc_todo_list', 'omoc_todo_update');
+        api.logger.info(`[${PLUGIN_ID}] Todo tools registered (3 tools)`);
+    });
     safeRegister(api, 'ralph-loop', 'service', () => {
         registerRalphLoop(api);
         registry.services.push('ralph-loop');

package/dist/tools/todo/index.d.ts

@@ -0,0 +1,2 @@
+import { OmocPluginApi } from '../../types.js';
+export declare function registerTodoTools(api: OmocPluginApi): void;

package/dist/tools/todo/index.js

@@ -0,0 +1,8 @@
+import { registerTodoCreateTool } from './todo-create.js';
+import { registerTodoListTool } from './todo-list.js';
+import { registerTodoUpdateTool } from './todo-update.js';
+export function registerTodoTools(api) {
+    registerTodoCreateTool(api);
+    registerTodoListTool(api);
+    registerTodoUpdateTool(api);
+}

package/dist/tools/todo/session-key.d.ts

@@ -0,0 +1 @@
+export declare function extractSessionKey(options?: unknown): string | undefined;

package/dist/tools/todo/session-key.js

@@ -0,0 +1,10 @@
+export function extractSessionKey(options) {
+    if (typeof options === 'object' && options !== null) {
+        const opts = options;
+        if (typeof opts.sessionKey === 'string')
+            return opts.sessionKey;
+        if (typeof opts.sessionId === 'string')
+            return opts.sessionId;
+    }
+    return undefined;
+}

package/dist/tools/todo/store.d.ts

@@ -0,0 +1,23 @@
+export type TodoStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled';
+export type TodoPriority = 'high' | 'medium' | 'low';
+export interface TodoItem {
+    id: string;
+    content: string;
+    status: TodoStatus;
+    priority: TodoPriority;
+    createdAt: string;
+}
+interface SessionStore {
+    todos: TodoItem[];
+    nextId: number;
+}
+declare const DEFAULT_SESSION = "__default__";
+declare const sessions: Map<string, SessionStore>;
+export declare function createTodo(content: string, priority?: TodoPriority, status?: TodoStatus, sessionKey?: string): TodoItem;
+export declare function listTodos(statusFilter?: TodoStatus, sessionKey?: string): ReadonlyArray<TodoItem>;
+export declare function findTodo(id: string, sessionKey?: string): TodoItem | undefined;
+export declare function updateTodo(id: string, updates: Partial<Pick<TodoItem, 'status' | 'priority' | 'content'>>, sessionKey?: string): TodoItem | null;
+export declare function getIncompleteTodos(sessionKey?: string): ReadonlyArray<TodoItem>;
+export declare function resetStore(sessionKey?: string): void;
+/** Exposed for testing only */
+export { sessions as _sessions, DEFAULT_SESSION };

package/dist/tools/todo/store.js

@@ -0,0 +1,60 @@
+const DEFAULT_SESSION = '__default__';
+const sessions = new Map();
+function getSession(sessionKey) {
+    const key = sessionKey ?? DEFAULT_SESSION;
+    let store = sessions.get(key);
+    if (!store) {
+        store = { todos: [], nextId: 1 };
+        sessions.set(key, store);
+    }
+    return store;
+}
+export function createTodo(content, priority = 'medium', status = 'pending', sessionKey) {
+    const store = getSession(sessionKey);
+    const item = {
+        id: `todo-${store.nextId++}`,
+        content,
+        status,
+        priority,
+        createdAt: new Date().toISOString(),
+    };
+    store.todos.push(item);
+    return item;
+}
+export function listTodos(statusFilter, sessionKey) {
+    const store = getSession(sessionKey);
+    if (statusFilter)
+        return store.todos.filter((t) => t.status === statusFilter);
+    return store.todos;
+}
+export function findTodo(id, sessionKey) {
+    const store = getSession(sessionKey);
+    return store.todos.find((t) => t.id === id);
+}
+export function updateTodo(id, updates, sessionKey) {
+    const store = getSession(sessionKey);
+    const item = store.todos.find((t) => t.id === id);
+    if (!item)
+        return null;
+    if (updates.status !== undefined)
+        item.status = updates.status;
+    if (updates.priority !== undefined)
+        item.priority = updates.priority;
+    if (updates.content !== undefined)
+        item.content = updates.content;
+    return item;
+}
+export function getIncompleteTodos(sessionKey) {
+    const store = getSession(sessionKey);
+    return store.todos.filter((t) => t.status === 'pending' || t.status === 'in_progress');
+}
+export function resetStore(sessionKey) {
+    if (sessionKey) {
+        sessions.delete(sessionKey);
+    }
+    else {
+        sessions.clear();
+    }
+}
+/** Exposed for testing only */
+export { sessions as _sessions, DEFAULT_SESSION };

package/dist/tools/todo/todo-create.d.ts

@@ -0,0 +1,2 @@
+import { OmocPluginApi } from '../../types.js';
+export declare function registerTodoCreateTool(api: OmocPluginApi): void;

package/dist/tools/todo/todo-create.js

@@ -0,0 +1,35 @@
+import { Type } from '@sinclair/typebox';
+import { toolResponse, toolError } from '../../utils/helpers.js';
+import { TOOL_PREFIX } from '../../constants.js';
+import { createTodo } from './store.js';
+import { extractSessionKey } from './session-key.js';
+const TodoCreateParamsSchema = Type.Object({
+    content: Type.String({ description: 'What needs to be done' }),
+    priority: Type.Optional(Type.Unsafe({
+        type: 'string',
+        enum: ['high', 'medium', 'low'],
+        description: 'Priority level (default: medium)',
+    })),
+    status: Type.Optional(Type.Unsafe({
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+        description: 'Initial status (default: pending)',
+    })),
+});
+export function registerTodoCreateTool(api) {
+    api.registerTool({
+        name: `${TOOL_PREFIX}todo_create`,
+        description: 'Create a new todo item. Use this to plan work steps before starting. ' +
+            'For multi-step tasks, create ALL todos first, then work through them one at a time.',
+        parameters: TodoCreateParamsSchema,
+        optional: true,
+        execute: async (_callId, params, options) => {
+            const content = params.content?.trim();
+            if (!content)
+                return toolError('content is required');
+            const sessionKey = extractSessionKey(options);
+            const item = createTodo(content, params.priority, params.status, sessionKey);
+            return toolResponse(JSON.stringify({ todo: item }, null, 2));
+        },
+    });
+}

package/dist/tools/todo/todo-list.d.ts

@@ -0,0 +1,2 @@
+import { OmocPluginApi } from '../../types.js';
+export declare function registerTodoListTool(api: OmocPluginApi): void;

package/dist/tools/todo/todo-list.js

@@ -0,0 +1,26 @@
+import { Type } from '@sinclair/typebox';
+import { toolResponse } from '../../utils/helpers.js';
+import { TOOL_PREFIX } from '../../constants.js';
+import { listTodos } from './store.js';
+import { extractSessionKey } from './session-key.js';
+const TodoListParamsSchema = Type.Object({
+    status: Type.Optional(Type.Unsafe({
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+        description: 'Filter by status (omit for all)',
+    })),
+});
+export function registerTodoListTool(api) {
+    api.registerTool({
+        name: `${TOOL_PREFIX}todo_list`,
+        description: 'List todo items. Call this FIRST to check existing todos before starting work. ' +
+            'Shows all active todos by default, or filter by status.',
+        parameters: TodoListParamsSchema,
+        optional: true,
+        execute: async (_callId, params, options) => {
+            const sessionKey = extractSessionKey(options);
+            const items = listTodos(params.status, sessionKey);
+            return toolResponse(JSON.stringify({ todos: items, count: items.length }, null, 2));
+        },
+    });
+}

package/dist/tools/todo/todo-update.d.ts

@@ -0,0 +1,2 @@
+import { OmocPluginApi } from '../../types.js';
+export declare function registerTodoUpdateTool(api: OmocPluginApi): void;

package/dist/tools/todo/todo-update.js

@@ -0,0 +1,45 @@
+import { Type } from '@sinclair/typebox';
+import { toolResponse, toolError } from '../../utils/helpers.js';
+import { TOOL_PREFIX } from '../../constants.js';
+import { updateTodo } from './store.js';
+import { extractSessionKey } from './session-key.js';
+const TodoUpdateParamsSchema = Type.Object({
+    id: Type.String({ description: 'Todo ID (e.g. todo-1)' }),
+    status: Type.Optional(Type.Unsafe({
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed', 'cancelled'],
+        description: 'New status',
+    })),
+    priority: Type.Optional(Type.Unsafe({
+        type: 'string',
+        enum: ['high', 'medium', 'low'],
+        description: 'New priority',
+    })),
+    content: Type.Optional(Type.String({ description: 'Updated content text' })),
+});
+export function registerTodoUpdateTool(api) {
+    api.registerTool({
+        name: `${TOOL_PREFIX}todo_update`,
+        description: 'Update a todo item status, priority, or content. ' +
+            'Mark in_progress before starting a step, completed immediately after finishing.',
+        parameters: TodoUpdateParamsSchema,
+        optional: true,
+        execute: async (_callId, params, options) => {
+            const id = params.id?.trim();
+            if (!id)
+                return toolError('id is required');
+            if (!params.status && !params.priority && !params.content) {
+                return toolError('At least one of status, priority, or content must be provided');
+            }
+            const sessionKey = extractSessionKey(options);
+            const updated = updateTodo(id, {
+                status: params.status,
+                priority: params.priority,
+                content: params.content,
+            }, sessionKey);
+            if (!updated)
+                return toolResponse(JSON.stringify({ error: 'todo_not_found', id }));
+            return toolResponse(JSON.stringify({ todo: updated }, null, 2));
+        },
+    });
+}

package/dist/types.d.ts

@@ -85,6 +85,14 @@ export interface OmocPluginApi {
         warn: (...args: unknown[]) => void;
         error: (...args: unknown[]) => void;
     };
+    runtime: {
+        system: {
+            enqueueSystemEvent: (text: string, options: {
+                sessionKey: string;
+                contextKey?: string | null;
+            }) => void;
+        };
+    };
     registerHook: <TEvent>(event: string, handler: (event: TEvent) => TEvent | void | undefined, meta?: HookMeta) => void;
     registerTool: <TParams>(config: ToolRegistration<TParams>) => void;
     registerCommand: <TCtx = {

package/dist/utils/persona-state.d.ts

@@ -2,7 +2,7 @@ import type { OmocPluginApi } from '../types.js';
 export declare function initPersonaState(_api: OmocPluginApi): Promise<void>;
 export declare function setActivePersonaId(id: string | null): Promise<void>;
 export declare function setActivePersona(id: string | null): Promise<void>;
-export declare function getActivePersona(workspaceDir?: string): Promise<string | null>;
+export declare function getActivePersona(workspaceDir?: string, agentId?: string): Promise<string | null>;
 export declare function resetPersonaState(): Promise<void>;
 export declare const OFF_MARKER = "__OFF__";
 export declare function resolveAgentsMdPath(workspaceDir?: string): string;

package/dist/utils/persona-state.js

@@ -1,6 +1,8 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { dirname, join } from 'path';
 import { resolveOpenClawWorkspaceDir } from './paths.js';
+import { ALL_AGENT_IDS } from '../agents/agent-ids.js';
+const KNOWN_AGENT_IDS = new Set(ALL_AGENT_IDS);
 let activePersonaId = null;
 let loaded = false;
 function resolveStateDir(workspaceDir) {
@@ -26,10 +28,16 @@ export async function setActivePersonaId(id) {
 export async function setActivePersona(id) {
     await setActivePersonaId(id);
 }
-export async function getActivePersona(workspaceDir) {
+export async function getActivePersona(workspaceDir, agentId) {
     if (!loaded)
         await loadFromDisk(workspaceDir);
-    return activePersonaId;
+    if (activePersonaId)
+        return activePersonaId;
+    if (agentId && KNOWN_AGENT_IDS.has(agentId)) {
+        await setActivePersonaId(agentId);
+        return agentId;
+    }
+    return null;
 }
 export async function resetPersonaState() {
     activePersonaId = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happycastle/oh-my-openclaw",
-  "version": "0.14.2",
+  "version": "0.15.1",
   "description": "Oh-My-OpenClaw plugin — multi-agent orchestration, todo enforcer, ralph loop, and custom tools for OpenClaw",
   "type": "module",
   "main": "dist/index.js",