@happycastle/oh-my-openclaw 0.15.3 → 0.16.1

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

@@ -49,6 +49,11 @@ export function createMockConfig(overrides) {
         checkpoint_dir: 'workspace/checkpoints',
         tmux_socket: '/tmp/openclaw-tmux-sockets/openclaw.sock',
         model_routing: undefined,
+        webhook_bridge_enabled: false,
+        gateway_url: 'http://127.0.0.1:18789',
+        hooks_token: '',
+        webhook_reminder_interval_ms: 300000,
+        webhook_subagent_stale_threshold_ms: 600000,
         ...overrides,
     };
 }

package/dist/cli/setup.d.ts

@@ -41,12 +41,16 @@ export declare function mergeAgentConfigs(existing: Array<{
     result: MergeResult;
 };
 export declare function applyProviderToConfigs(configs: OmocAgentConfig[], provider: string): OmocAgentConfig[];
+export declare function readExistingHooksToken(configPath: string): string | undefined;
+export declare function generateHooksToken(): string;
 export interface InteractiveSetupResult {
     provider: string;
     setupMcporter: boolean;
     excludeServers: string[];
     enableTodoEnforcer: boolean;
     enablePlannerGuard: boolean;
+    enableWebhookBridge: boolean;
+    webhookHooksToken: string;
 }
 export declare function runInteractiveSetup(logger: Logger): Promise<InteractiveSetupResult>;
 export interface SetupOptions {
@@ -60,6 +64,8 @@ export interface SetupOptions {
     excludeServers?: string[];
     enableTodoEnforcer?: boolean;
     enablePlannerGuard?: boolean;
+    enableWebhookBridge?: boolean;
+    webhookHooksToken?: string;
     interactive?: boolean;
     logger: Logger;
 }

package/dist/cli/setup.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import * as readline from 'node:readline';
@@ -174,6 +175,20 @@ async function runCustomProviderFlow(rl, logger) {
     registerCustomPreset(customName, customPreset);
     return customName;
 }
+export function readExistingHooksToken(configPath) {
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        const config = JSON5.parse(raw);
+        const hooks = config.hooks;
+        return hooks?.token && typeof hooks.token === 'string' ? hooks.token : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function generateHooksToken() {
+    return crypto.randomBytes(32).toString('hex');
+}
 export async function runInteractiveSetup(logger) {
     const rl = readline.createInterface({
         input: process.stdin,
@@ -185,6 +200,8 @@ export async function runInteractiveSetup(logger) {
         excludeServers: [],
         enableTodoEnforcer: false,
         enablePlannerGuard: false,
+        enableWebhookBridge: false,
+        webhookHooksToken: '',
     };
     try {
         logger.info('');
@@ -257,8 +274,26 @@ export async function runInteractiveSetup(logger) {
         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';
+        const webhookAnswer = await askQuestion(rl, '  Enable webhook bridge (proactive agent reminders via hooks/wake)? (Y/n): ');
+        const enableWebhookBridge = webhookAnswer.toLowerCase() !== 'n' && webhookAnswer.toLowerCase() !== 'no';
+        let webhookHooksToken = '';
+        if (enableWebhookBridge) {
+            const configPath = findConfigPath();
+            const existingToken = configPath ? readExistingHooksToken(configPath) : undefined;
+            if (existingToken) {
+                logger.info(`  Found existing hooks.token in config`);
+                const reuseAnswer = await askQuestion(rl, '  Reuse existing hooks token? (Y/n): ');
+                if (reuseAnswer.toLowerCase() !== 'n' && reuseAnswer.toLowerCase() !== 'no') {
+                    webhookHooksToken = existingToken;
+                }
+            }
+            if (!webhookHooksToken) {
+                webhookHooksToken = generateHooksToken();
+                logger.info(`  Generated new hooks token`);
+            }
+        }
         logger.info('');
-        return { provider, setupMcporter, excludeServers, enableTodoEnforcer, enablePlannerGuard };
+        return { provider, setupMcporter, excludeServers, enableTodoEnforcer, enablePlannerGuard, enableWebhookBridge, webhookHooksToken };
     }
     finally {
         rl.close();
@@ -349,6 +384,25 @@ export function runSetup(options) {
         }
         logger.info(`Todo enforcer: ${options.enableTodoEnforcer ? 'enabled' : 'disabled'}`);
     }
+    if (options.enableWebhookBridge && options.webhookHooksToken) {
+        const pluginSettings = (config.pluginSettings ?? {});
+        if (!pluginSettings['oh-my-openclaw']) {
+            pluginSettings['oh-my-openclaw'] = {};
+        }
+        pluginSettings['oh-my-openclaw']['webhook_bridge_enabled'] = true;
+        pluginSettings['oh-my-openclaw']['hooks_token'] = options.webhookHooksToken;
+        config.pluginSettings = pluginSettings;
+        const hooksSection = (config.hooks ?? {});
+        hooksSection.enabled = true;
+        if (!hooksSection.token) {
+            hooksSection.token = options.webhookHooksToken;
+        }
+        config.hooks = hooksSection;
+        if (!dryRun) {
+            fs.writeFileSync(configPath, serializeConfig(config), 'utf-8');
+        }
+        logger.info('Webhook bridge enabled with hooks token configured');
+    }
     if (options.setupMcporter) {
         logger.info('');
         logger.info('Setting up mcporter MCP servers...');
@@ -383,6 +437,8 @@ export function registerSetupCli(ctx) {
             let excludeServers = [];
             let enableTodoEnforcer;
             let enablePlannerGuard;
+            let enableWebhookBridge;
+            let webhookHooksToken;
             if (!provider && process.stdin.isTTY) {
                 const result = await runInteractiveSetup(ctx.logger);
                 if (!result.provider)
@@ -392,6 +448,8 @@ export function registerSetupCli(ctx) {
                 excludeServers = result.excludeServers;
                 enableTodoEnforcer = result.enableTodoEnforcer;
                 enablePlannerGuard = result.enablePlannerGuard;
+                enableWebhookBridge = result.enableWebhookBridge;
+                webhookHooksToken = result.webhookHooksToken;
             }
             runSetup({
                 configPath: opts.config,
@@ -403,6 +461,8 @@ export function registerSetupCli(ctx) {
                 excludeServers,
                 enableTodoEnforcer,
                 enablePlannerGuard,
+                enableWebhookBridge,
+                webhookHooksToken,
                 logger: ctx.logger,
             });
             ctx.logger.info('');

package/dist/hooks/subagent-tracker.d.ts

@@ -0,0 +1,8 @@
+import { OmocPluginApi } from '../types.js';
+declare function extractSpawnResult(content: string): {
+    runId: string;
+    childSessionKey: string;
+    task: string;
+} | null;
+export declare function registerSubagentTracker(api: OmocPluginApi): void;
+export { extractSpawnResult };

package/dist/hooks/subagent-tracker.js

@@ -0,0 +1,62 @@
+import { LOG_PREFIX } from '../constants.js';
+import { trackSubagentSpawn, clearSubagentTracking } from '../services/webhook-bridge.js';
+const SPAWN_TOOL_NAME = 'sessions_spawn';
+function extractSpawnResult(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed.status === 'accepted' && parsed.runId && parsed.childSessionKey) {
+            return {
+                runId: parsed.runId,
+                childSessionKey: parsed.childSessionKey,
+                task: parsed.task ?? '',
+            };
+        }
+    }
+    catch {
+        const runIdMatch = content.match(/runId["\s:]+["']?([a-zA-Z0-9_-]+)/);
+        const sessionKeyMatch = content.match(/childSessionKey["\s:]+["']?([a-zA-Z0-9:_-]+)/);
+        if (runIdMatch && sessionKeyMatch) {
+            return {
+                runId: runIdMatch[1],
+                childSessionKey: sessionKeyMatch[1],
+                task: '',
+            };
+        }
+    }
+    return null;
+}
+export function registerSubagentTracker(api) {
+    api.registerHook('tool_result_persist', (payload) => {
+        if (payload.tool !== SPAWN_TOOL_NAME)
+            return undefined;
+        const content = typeof payload.content === 'string' ? payload.content : '';
+        const spawnResult = extractSpawnResult(content);
+        if (spawnResult) {
+            trackSubagentSpawn({
+                ...spawnResult,
+                spawnedAt: Date.now(),
+            });
+            api.logger.info(`${LOG_PREFIX} Tracking sub-agent spawn: runId=${spawnResult.runId}`);
+        }
+        return undefined;
+    }, {
+        name: 'oh-my-openclaw.subagent-tracker',
+        description: 'Tracks sessions_spawn results for stale sub-agent detection',
+    });
+    api.registerHook('message:received', (context) => {
+        const content = context?.content ?? '';
+        if (!content.includes('Sub-agent') && !content.includes('subagent') && !content.includes('announce')) {
+            return undefined;
+        }
+        const runIdMatch = content.match(/runId["\s:=]+["']?([a-zA-Z0-9_-]+)/);
+        if (runIdMatch) {
+            clearSubagentTracking(runIdMatch[1]);
+            api.logger.info(`${LOG_PREFIX} Cleared sub-agent tracking: runId=${runIdMatch[1]} (announce received)`);
+        }
+        return undefined;
+    }, {
+        name: 'oh-my-openclaw.subagent-announce-detector',
+        description: 'Detects sub-agent announce messages and clears stale tracking',
+    });
+}
+export { extractSpawnResult };

package/dist/hooks/todo-reminder.js

@@ -1,5 +1,7 @@
 import { TOOL_PREFIX, LOG_PREFIX } from '../constants.js';
 import { getIncompleteTodos, resetStore } from '../tools/todo/store.js';
+import { getConfig } from '../utils/config.js';
+import { callHooksWake } from '../utils/webhook-client.js';
 const TODO_TOOL_NAMES = new Set([
     `${TOOL_PREFIX}todo_create`,
     `${TOOL_PREFIX}todo_list`,
@@ -59,6 +61,10 @@ export function registerAgentEndReminder(api) {
             if (sessionKey) {
                 api.runtime.system.enqueueSystemEvent(warning, { sessionKey });
             }
+            const config = getConfig(api);
+            if (config.webhook_bridge_enabled && config.hooks_token) {
+                callHooksWake(`⚠️ Agent ended with ${incomplete.length} incomplete todo(s). Resume work.`, { gateway_url: config.gateway_url, hooks_token: config.hooks_token }, api.logger).catch(() => { });
+            }
             api.logger.warn(`${LOG_PREFIX} Agent ended with ${incomplete.length} incomplete todo(s)`);
         }
         catch {

package/dist/index.js

@@ -7,7 +7,10 @@ import { registerCommentChecker } from './hooks/comment-checker.js';
 import { registerMessageMonitor } from './hooks/message-monitor.js';
 import { registerStartupHook } from './hooks/startup.js';
 import { registerRalphLoop } from './services/ralph-loop.js';
+import { registerWebhookBridge } from './services/webhook-bridge.js';
+import { registerSubagentTracker } from './hooks/subagent-tracker.js';
 import { registerDelegateTool } from './tools/task-delegation.js';
+import { registerOmoDelegateTool } from './tools/omo-delegation.js';
 import { registerLookAtTool } from './tools/look-at.js';
 import { registerCheckpointTool } from './tools/checkpoint.js';
 import { registerWebSearchTool } from './tools/web-search.js';
@@ -127,11 +130,26 @@ export default function register(api) {
         registry.services.push('ralph-loop');
         api.logger.info(`[${PLUGIN_ID}] Ralph Loop service registered`);
     });
+    safeRegister(api, 'webhook-bridge', 'service', () => {
+        registerWebhookBridge(api);
+        registry.services.push('webhook-bridge');
+        api.logger.info(`[${PLUGIN_ID}] Webhook Bridge service registered (enabled: ${config.webhook_bridge_enabled})`);
+    });
+    safeRegister(api, 'subagent-tracker', 'hook', () => {
+        registerSubagentTracker(guarded);
+        registry.hooks.push('subagent-tracker', 'subagent-announce-detector');
+        api.logger.info(`[${PLUGIN_ID}] Sub-agent tracker hooks registered`);
+    });
     safeRegister(api, 'omoc_delegate', 'tool', () => {
         registerDelegateTool(api);
         registry.tools.push('omoc_delegate');
         api.logger.info(`[${PLUGIN_ID}] Delegate tool registered`);
     });
+    safeRegister(api, 'omo_delegate', 'tool', () => {
+        registerOmoDelegateTool(api);
+        registry.tools.push('omo_delegate');
+        api.logger.info(`[${PLUGIN_ID}] OmO Delegate tool registered (ACP)`);
+    });
     safeRegister(api, 'omoc_look_at', 'tool', () => {
         registerLookAtTool(api);
         registry.tools.push('omoc_look_at');

package/dist/services/webhook-bridge.d.ts

@@ -0,0 +1,13 @@
+import { OmocPluginApi } from '../types.js';
+interface TrackedSubagent {
+    runId: string;
+    childSessionKey: string;
+    task: string;
+    spawnedAt: number;
+}
+export declare function trackSubagentSpawn(entry: TrackedSubagent): void;
+export declare function clearSubagentTracking(runId: string): void;
+export declare function getTrackedSubagents(): ReadonlyMap<string, TrackedSubagent>;
+export declare function resetWebhookBridgeState(): void;
+export declare function registerWebhookBridge(api: OmocPluginApi): void;
+export {};

package/dist/services/webhook-bridge.js

@@ -0,0 +1,121 @@
+import { LOG_PREFIX, TOOL_PREFIX } from '../constants.js';
+import { getConfig } from '../utils/config.js';
+import { getIncompleteTodos } from '../tools/todo/store.js';
+import { callHooksAgent, callHooksWake } from '../utils/webhook-client.js';
+const trackedSubagents = new Map();
+let reminderTimer = null;
+export function trackSubagentSpawn(entry) {
+    trackedSubagents.set(entry.runId, entry);
+}
+export function clearSubagentTracking(runId) {
+    trackedSubagents.delete(runId);
+}
+export function getTrackedSubagents() {
+    return trackedSubagents;
+}
+export function resetWebhookBridgeState() {
+    trackedSubagents.clear();
+    if (reminderTimer) {
+        clearInterval(reminderTimer);
+        reminderTimer = null;
+    }
+}
+function buildWebhookConfig(api) {
+    const config = getConfig(api);
+    return {
+        gateway_url: config.gateway_url,
+        hooks_token: config.hooks_token,
+    };
+}
+async function checkIncompleteTodos(api) {
+    const webhookConfig = buildWebhookConfig(api);
+    const config = getConfig(api);
+    const allSessionKeys = ['__default__', 'agent:main:main'];
+    let totalIncomplete = 0;
+    const summaryParts = [];
+    for (const sessionKey of allSessionKeys) {
+        const incomplete = getIncompleteTodos(sessionKey);
+        if (incomplete.length > 0) {
+            totalIncomplete += incomplete.length;
+            const items = incomplete.map((t) => `  - [${t.status}] ${t.content}`).join('\n');
+            summaryParts.push(items);
+        }
+    }
+    if (totalIncomplete === 0)
+        return;
+    const summary = summaryParts.join('\n');
+    const message = `[OmOC Periodic Reminder] You have ${totalIncomplete} incomplete todo(s):\n${summary}\n\n` +
+        `Review with \`${TOOL_PREFIX}todo_list\` and resume work. ` +
+        `If blocked, update todo status. If all done, mark them complete.`;
+    const result = await callHooksAgent(message, webhookConfig, {
+        name: 'OmOC-TodoReminder',
+        deliver: false,
+    }, api.logger);
+    if (result.ok) {
+        api.logger.info(`${LOG_PREFIX} Periodic todo reminder sent via hooks/agent (${totalIncomplete} incomplete)`);
+    }
+}
+async function checkStaleSubagents(api) {
+    const webhookConfig = buildWebhookConfig(api);
+    const config = getConfig(api);
+    const threshold = config.webhook_subagent_stale_threshold_ms;
+    const now = Date.now();
+    const stale = [];
+    for (const entry of trackedSubagents.values()) {
+        if (now - entry.spawnedAt > threshold) {
+            stale.push(entry);
+        }
+    }
+    if (stale.length === 0)
+        return;
+    const details = stale
+        .map((s) => `  - runId=${s.runId} task="${s.task.substring(0, 80)}" (${Math.round((now - s.spawnedAt) / 60000)}m ago)`)
+        .join('\n');
+    const message = `[OmOC Sub-agent Alert] ${stale.length} sub-agent(s) may have completed without announce:\n${details}\n\n` +
+        `Check sub-agent status with \`/subagents list\` or \`/subagents info <id>\`. ` +
+        `If completed, collect results and proceed. If still running, wait.`;
+    const result = await callHooksWake(message, webhookConfig, api.logger);
+    if (result.ok) {
+        api.logger.info(`${LOG_PREFIX} Stale sub-agent alert sent via hooks/wake (${stale.length} stale)`);
+        for (const s of stale) {
+            trackedSubagents.delete(s.runId);
+        }
+    }
+}
+export function registerWebhookBridge(api) {
+    const config = getConfig(api);
+    api.registerService({
+        id: 'omoc-webhook-bridge',
+        name: 'Webhook Bridge Service',
+        description: 'Proactive agent messaging via Gateway webhook hooks',
+        start: async () => {
+            if (!config.webhook_bridge_enabled) {
+                api.logger.info(`${LOG_PREFIX} Webhook bridge disabled (set webhook_bridge_enabled: true to enable)`);
+                return;
+            }
+            if (!config.hooks_token) {
+                api.logger.warn(`${LOG_PREFIX} Webhook bridge enabled but hooks_token is empty — skipping`);
+                return;
+            }
+            const intervalMs = Math.max(config.webhook_reminder_interval_ms, 30_000);
+            reminderTimer = setInterval(async () => {
+                try {
+                    await checkIncompleteTodos(api);
+                    await checkStaleSubagents(api);
+                }
+                catch (err) {
+                    api.logger.warn(`${LOG_PREFIX} Webhook bridge tick error:`, err);
+                }
+            }, intervalMs);
+            api.logger.info(`${LOG_PREFIX} Webhook bridge started (interval=${intervalMs}ms, stale_threshold=${config.webhook_subagent_stale_threshold_ms}ms)`);
+        },
+        stop: async () => {
+            if (reminderTimer) {
+                clearInterval(reminderTimer);
+                reminderTimer = null;
+            }
+            trackedSubagents.clear();
+            api.logger.info(`${LOG_PREFIX} Webhook bridge stopped`);
+        },
+    });
+}

package/dist/tools/omo-delegation.d.ts

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

package/dist/tools/omo-delegation.js

@@ -0,0 +1,63 @@
+import { Type } from '@sinclair/typebox';
+import { TOOL_PREFIX } from '../types.js';
+import { LOG_PREFIX } from '../constants.js';
+import { toolResponse, toolError } from '../utils/helpers.js';
+const VALID_ACP_AGENTS = ['opencode', 'codex', 'claude', 'gemini', 'pi'];
+const OmoDelegateParamsSchema = Type.Object({
+    task: Type.String({ description: 'What OmO (OpenCode) should do — the coding task description. Use @agentname prefix to invoke OpenCode subagents (e.g., "@explore find auth files").' }),
+    agent: Type.Optional(Type.String({ description: 'ACP harness agent ID (default: "opencode"). Valid: opencode, codex, claude, gemini, pi' })),
+    opencode_agent: Type.Optional(Type.String({ description: 'OpenCode internal agent mode (e.g., "build", "plan", or custom agent name). Only applies when agent is "opencode". Defaults to OpenCode\'s configured primary agent. Uses ACP session mode switching.' })),
+    model: Type.Optional(Type.String({ description: 'Override model — only when you need a specific model. Leave empty to use OpenCode\'s own configured default.' })),
+    thread: Type.Optional(Type.Boolean({ description: 'Bind to a thread for persistent multi-turn session (default: false)', default: false })),
+    label: Type.Optional(Type.String({ description: 'Label for easy identification in /subagents list and /acp sessions' })),
+    cwd: Type.Optional(Type.String({ description: 'Working directory for the ACP session' })),
+});
+export function registerOmoDelegateTool(api) {
+    api.registerTool({
+        name: `${TOOL_PREFIX.replace('omoc_', 'omo_')}delegate`,
+        description: 'Delegate a coding task to OmO (OpenCode) via ACP session. Use this for coding work — implementation, bug fixes, refactoring, testing.',
+        parameters: OmoDelegateParamsSchema,
+        execute: async (_toolCallId, params) => {
+            if (!params.task?.trim()) {
+                return toolError('Task is required and cannot be empty');
+            }
+            if (params.task.length > 10000) {
+                return toolError('Task too long (max 10000 chars)');
+            }
+            const agent = params.agent || 'opencode';
+            if (!VALID_ACP_AGENTS.includes(agent)) {
+                return toolError(`Invalid ACP agent: ${agent}. Valid: ${VALID_ACP_AGENTS.join(', ')}`);
+            }
+            const sessionMode = params.thread ? 'session' : 'run';
+            api.logger.info(`${LOG_PREFIX} OmO delegation:`, { agent, opencode_agent: params.opencode_agent, model: params.model, thread: params.thread });
+            const instruction = [
+                `OmO Delegation → ACP runtime → harness "${agent}"`,
+                '',
+                '⚡ NOW CALL sessions_spawn with these parameters:',
+                `  task: "${params.task}"`,
+                `  runtime: "acp"`,
+                `  agentId: "${agent}"`,
+                `  mode: "${sessionMode}"`,
+                params.model ? `  model: "${params.model}"` : '',
+                params.thread ? '  thread: true' : '',
+                params.label ? `  label: "${params.label}"` : '',
+                params.cwd ? `  cwd: "${params.cwd}"` : '',
+                '',
+                'Do NOT just return this metadata. Actually call sessions_spawn NOW.',
+                params.opencode_agent ? [
+                    '',
+                    `🔀 AFTER session is created, switch OpenCode agent mode to "${params.opencode_agent}":`,
+                    `  Use ACP session mode switching (setSessionMode) to select "${params.opencode_agent}"`,
+                    '  Available modes are returned in the session creation response',
+                ].join('\n') : '',
+                '',
+                '⚠️ AFTER the ACP session completes:',
+                '  1. Check the announce result immediately',
+                '  2. Verify with git status/diff',
+                '  3. Proceed to next task — do NOT stop',
+            ].filter(Boolean).join('\n');
+            return toolResponse(instruction);
+        },
+        optional: true,
+    });
+}

package/dist/tools/task-delegation.js

@@ -45,7 +45,7 @@ function getModelForCategory(category, api) {
 export function registerDelegateTool(api) {
     api.registerTool({
         name: `${TOOL_PREFIX}delegate`,
-        description: 'Delegate a task to a sub-agent with category-based model routing',
+        description: 'Delegate a task to an OpenClaw-native sub-agent with category-based model routing',
         parameters: DelegateParamsSchema,
         execute: async (_toolCallId, params) => {
             const validCategories = Object.keys(DEFAULT_CATEGORY_MODELS);

package/dist/types.d.ts

@@ -13,6 +13,11 @@ export interface PluginConfig {
         model: string;
         alternatives?: string[];
     }>>;
+    webhook_bridge_enabled: boolean;
+    gateway_url: string;
+    hooks_token: string;
+    webhook_reminder_interval_ms: number;
+    webhook_subagent_stale_threshold_ms: number;
 }
 export interface RalphLoopState {
     active: boolean;

package/dist/utils/config.js

@@ -14,6 +14,11 @@ export function getConfig(api) {
         checkpoint_dir: join(wsDir, 'checkpoints'),
         tmux_socket: '/tmp/openclaw-tmux-sockets/openclaw.sock',
         model_routing: undefined,
+        webhook_bridge_enabled: false,
+        gateway_url: process.env.OPENCLAW_GATEWAY_URL ?? 'http://127.0.0.1:18789',
+        hooks_token: process.env.OPENCLAW_HOOKS_TOKEN ?? '',
+        webhook_reminder_interval_ms: 5 * 60 * 1000, // 5 minutes
+        webhook_subagent_stale_threshold_ms: 10 * 60 * 1000, // 10 minutes
     };
     const config = { ...defaults, ...(api.pluginConfig ?? api.config) };
     const validation = validateConfig(config);

package/dist/utils/webhook-client.d.ts

@@ -0,0 +1,21 @@
+export interface WebhookConfig {
+    gateway_url: string;
+    hooks_token: string;
+}
+export interface HooksAgentOptions {
+    name?: string;
+    agentId?: string;
+    sessionKey?: string;
+    deliver?: boolean;
+}
+export interface WebhookResult {
+    ok: boolean;
+    status?: number;
+    error?: string;
+}
+export declare function callHooksWake(text: string, config: WebhookConfig, logger?: {
+    warn: (...args: unknown[]) => void;
+}): Promise<WebhookResult>;
+export declare function callHooksAgent(message: string, config: WebhookConfig, options?: HooksAgentOptions, logger?: {
+    warn: (...args: unknown[]) => void;
+}): Promise<WebhookResult>;

package/dist/utils/webhook-client.js

@@ -0,0 +1,48 @@
+import { LOG_PREFIX } from '../constants.js';
+export async function callHooksWake(text, config, logger) {
+    if (!config.hooks_token) {
+        return { ok: false, error: 'hooks_token not configured' };
+    }
+    try {
+        const res = await fetch(`${config.gateway_url}/hooks/wake`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${config.hooks_token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ text, mode: 'now' }),
+        });
+        return { ok: res.ok, status: res.status };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger?.warn(`${LOG_PREFIX} hooks/wake failed: ${msg}`);
+        return { ok: false, error: msg };
+    }
+}
+export async function callHooksAgent(message, config, options, logger) {
+    if (!config.hooks_token) {
+        return { ok: false, error: 'hooks_token not configured' };
+    }
+    try {
+        const payload = {
+            message,
+            wakeMode: 'now',
+            ...options,
+        };
+        const res = await fetch(`${config.gateway_url}/hooks/agent`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${config.hooks_token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+        return { ok: res.ok, status: res.status };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger?.warn(`${LOG_PREFIX} hooks/agent failed: ${msg}`);
+        return { ok: false, error: msg };
+    }
+}

package/package.json

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

package/skills/opencode-controller.md

@@ -1,125 +1,145 @@
 ---
 name: opencode-controller
-description: Control OpenCode sessions via tmux. Includes session management, model selection, agent switching (Plan/Build), and OmO delegation patterns.
+description: Control OpenCode sessions via ACP (Agent Client Protocol). Includes session management, model selection, and OmO delegation patterns.
 ---
 
-# opencode-controller — OpenCode Session Control
+# opencode-controller — OpenCode Session Control (ACP)
 
-OpenClaw is not a direct code executor, but an orchestrator that delegates work to OpenCode, collects results, and verifies them.
+OpenClaw is not a direct code executor, but an orchestrator that delegates work to OpenCode via ACP, collects results, and verifies them.
 
 ## Core Principles
 
 - OpenClaw does not write code directly
-- Coding tasks are delegated to the tmux `opencode` session
+- Coding tasks are delegated to OpenCode via ACP sessions (`runtime: "acp"`, `agentId: "opencode"`)
 - OpenClaw is responsible for task decomposition, instruction, monitoring, and result verification
 
 ## Pre-flight Checklist
 
-### 1) Provider/Model Selection
+### 1) ACP Backend Check
 
-- Select OpenCode model based on task difficulty (quick/deep/ultrabrain)
-- Prioritize high-performance models for high-difficulty tasks
+Verify ACP is enabled and the opencode harness is available:
 
-### 2) Authentication Status
-
-- OpenCode CLI provider authentication must be completed
-- If authentication expires, re-login within the session and retry
+```text
+/acp doctor
+```
 
-### 3) tmux Session Check
+If ACP backend is not configured, install it:
 
 ```bash
-SOCKET="/tmp/openclaw-tmux-sockets/openclaw.sock"
-tmux -S "$SOCKET" has-session -t opencode
+openclaw plugins install @openclaw/acpx
+openclaw config set plugins.entries.acpx.enabled true
 ```
 
-## Session Management
+### 2) OpenCode Authentication
 
-```bash
-SOCKET="/tmp/openclaw-tmux-sockets/openclaw.sock"
-
-# Create session
-tmux -S "$SOCKET" new -d -s opencode -n main
+- OpenCode CLI provider authentication must be completed
+- If authentication expires, re-authenticate and retry
 
-# Session status
-tmux -S "$SOCKET" list-sessions
+### 3) ACP Session Status
 
-# Check session output
-tmux -S "$SOCKET" capture-pane -p -J -t opencode:0.0 -S -200
+```text
+/acp status
+/acp sessions
 ```
 
-## Agent Control
+## OmO Delegation Pattern
 
-OpenCode agent switching is performed via Tab.
+### 1) One-Shot Delegation (Default)
 
-| Agent | Purpose | Switch |
-|----------|------|------|
-| Sisyphus | Default implementation/fixes | Default state |
-| Hephaestus | Deep implementation/refactoring | Tab 1x |
-| Prometheus | Planning/strategy | Tab 2x |
+For single tasks that run to completion:
 
-```bash
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Tab
-sleep 1
-tmux -S "$SOCKET" capture-pane -p -J -t opencode:0.0 -S -20
+```json
+sessions_spawn({
+  "task": "ultrawork fix payment failure bug. Include reproduction, root cause analysis, test addition, and regression prevention.",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run"
+})
 ```
 
-## Model Selection Guide
+- `sessions_spawn` returns immediately with `{ status: "accepted", runId, childSessionKey }`
+- OpenCode works autonomously on the task
+- On completion, result is announced back to the requester chat channel
+- Use `/subagents info <id>` or `/subagents log <id>` to inspect details
 
-- Quick fixes: Speed-first model
-- Complex refactoring/design: Deep reasoning model
-- Planning-only phase: Highest reasoning model first
+### 2) Persistent Session (Thread-Bound)
 
-Follow project standard routing (quick/deep/ultrabrain) at execution time.
+For multi-turn interactive work in a thread:
 
-## Plan -> Build Workflow
+```json
+sessions_spawn({
+  "task": "Set up for auth module refactoring. Start by analyzing the current structure.",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "session",
+  "thread": true
+})
+```
 
-1) Establish plan with Prometheus
-2) Approve/refine plan
-3) Switch to Sisyphus or Hephaestus for implementation
-4) Run tests/build/verification
-5) OpenClaw collects results and reports final summary
+- Thread binding routes follow-up messages to the same OpenCode session
+- Use `/acp steer <instruction>` to nudge without replacing context
+- Use `/unfocus` to detach from the thread when done
 
-```bash
-# Plan phase
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Tab
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Tab
-sleep 0.2
-tmux -S "$SOCKET" send-keys -t opencode:0.0 -l -- 'Plan: write scope/risk/verification strategy for auth module refactoring'
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Enter
+### 3) Model Override (Use Sparingly)
+
+Override only when you need a specific model. By default, OpenCode uses its own configured model — leave `model` empty to use that default.
 
-# Build phase switch (e.g., return to Sisyphus for implementation)
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Escape
-tmux -S "$SOCKET" send-keys -t opencode:0.0 -l -- 'ultrawork implement based on above plan, complete through testing'
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Enter
+```json
+sessions_spawn({
+  "task": "Plan: write scope/risk/verification strategy for auth module refactoring",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run",
+  "model": "claude-opus-4-6-thinking"
+})
 ```
 
-## OmO Delegation Pattern
+### 4) OpenCode Agent Mode Selection
 
-### 1) Validate tmux Session
+OpenCode has internal agents (Build, Plan, custom agents from `.opencode/agents/`). Select which agent handles the task via ACP session mode switching:
 
-```bash
-SOCKET="/tmp/openclaw-tmux-sockets/openclaw.sock"
-tmux -S "$SOCKET" has-session -t opencode
+```json
+// Use Plan agent (read-only, restricted tools) for planning tasks
+sessions_spawn({
+  "task": "Analyze the auth module structure and propose refactoring strategy",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run"
+})
+// After session creation, switch mode: setSessionMode("plan")
 ```
 
-### 2) Agent Selection Table
+**How it works:**
+- ACP session creation returns available `modes` (primary agents only — not subagents, not hidden)
+- Call `setSessionMode(modeId)` to switch the active OpenCode agent
+- Default mode is OpenCode's configured primary agent (usually "build")
+- Available modes: `build` (full tools), `plan` (restricted), plus any custom primary agents
 
-| Purpose | Agent | Switch |
-|------|----------|------|
-| Default execution | Sisyphus | Default |
-| Deep implementation | Hephaestus | Tab 1x |
-| Planning | Prometheus | Tab 2x |
+### 5) Subagent Invocation via @mention
 
-### 3) Send Work (`send-keys -l` + separate Enter)
+OpenCode subagents (Explore, custom subagents from `.opencode/agents/`) are invoked via `@mention` in the task text:
 
-```bash
-TASK='ultrawork fix payment failure bug. Include reproduction, root cause analysis, test addition, and regression prevention.'
-tmux -S "$SOCKET" send-keys -t opencode:0.0 -l -- "$TASK"
-sleep 0.1
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Enter
+```json
+sessions_spawn({
+  "task": "@explore find all authentication-related files and report their structure",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run"
+})
 ```
 
-### 4) Work Templates
+**Note:** Subagents are NOT available as session modes. They are invoked within the agent's conversation via `@agentname` prefix.
+
+## Model Selection Guide
+
+- **Default behavior**: Leave `model` empty — OpenCode uses its own configured model
+- Quick fixes: Speed-first model (only override if OpenCode default is too slow)
+- Complex refactoring/design: Deep reasoning model
+- Planning-only phase: Use `opencode_agent: "plan"` mode instead of model override
+
+Follow project standard routing (quick/deep/ultrabrain) at execution time.
+
+## Work Templates
 
 Feature implementation:
 ```text
@@ -155,17 +175,70 @@ Read [/path/to/research.md] first,
 then ultrawork implement [feature] based on research findings.
 ```
 
-### 5) Progress Monitoring (`capture-pane`)
+## Progress Monitoring
 
-```bash
-tmux -S "$SOCKET" capture-pane -p -J -t opencode:0.0 -S -200
+### Check Active Sessions
+
+```text
+/acp sessions
+/subagents list
+```
+
+### Inspect Session Output
+
+```text
+/subagents log <id>
+/subagents info <id>
+```
+
+### Steer Active Session
+
+Nudge a running session without replacing context:
+
+```text
+/acp steer focus on the failing test case first
 ```
 
-Recommendations:
-- Check progress logs every 10-30 seconds
-- Intervene immediately on signs of blockage (repeated identical output, prompt waiting)
+### Session History
 
-### 6) Collect Results (`git status`/`git diff`)
+After completion, review the full transcript:
+
+```text
+/subagents log <id> 50
+```
+
+## Parallel Delegation
+
+Run multiple OpenCode sessions in parallel:
+
+```json
+// Session 1: Fix auth bug
+sessions_spawn({
+  "task": "ultrawork fix auth bug in src/auth/login.ts",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run",
+  "label": "auth-fix"
+})
+
+// Session 2: Enhance payment tests
+sessions_spawn({
+  "task": "ultrawork enhance payment module tests",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run",
+  "label": "payment-tests"
+})
+```
+
+- Each session runs independently with its own context
+- Results announce back separately on completion
+- Use `/subagents list` to monitor all active sessions
+- Concurrency is governed by `agents.defaults.subagents.maxConcurrent` (default: 8)
+
+## Collect Results
+
+After announce arrives:
 
 ```bash
 git status
@@ -173,25 +246,48 @@ git diff --stat
 git diff
 ```
 
-OpenClaw summarizes changed files/test results/risks and reports to user.
+OpenClaw summarizes changed files, test results, and risks before reporting to user.
 
-### 7) Error Recovery
+## Error Recovery
 
-```bash
-# Stop current operation
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Escape
+```text
+# Cancel in-flight session
+/acp cancel <session-key>
+
+# Close and unbind thread
+/acp close
+
+# Kill specific sub-agent
+/subagents kill <id>
+
+# Retry with new session
+sessions_spawn({
+  "task": "First solve only the test failure cause from the previous step.",
+  "runtime": "acp",
+  "agentId": "opencode",
+  "mode": "run"
+})
+```
 
-# Resend fix instruction
-tmux -S "$SOCKET" send-keys -t opencode:0.0 -l -- 'First solve only the test failure cause from the previous step.'
-tmux -S "$SOCKET" send-keys -t opencode:0.0 Enter
+## Session Lifecycle
 
-# Restart session
-tmux -S "$SOCKET" kill-session -t opencode
-tmux -S "$SOCKET" new -d -s opencode -n main
-```
+| Action | Command |
+|--------|---------|
+| Spawn one-shot | `sessions_spawn` with `mode: "run"` |
+| Spawn persistent | `sessions_spawn` with `mode: "session"`, `thread: true` |
+| Check status | `/acp status`, `/subagents list` |
+| Inspect output | `/subagents log <id>`, `/subagents info <id>` |
+| Steer mid-run | `/acp steer <instruction>` |
+| Cancel turn | `/acp cancel` |
+| Close session | `/acp close` |
+| Kill sub-agent | `/subagents kill <id>` |
 
 ## Operation Checklist
 
-- Verify session alive → select agent → send work → monitor → collect results
-- Always use `send-keys -l` + separate Enter
+- Verify ACP health (`/acp doctor`) -> delegate via `sessions_spawn` -> monitor (`/subagents list`) -> collect results (`git diff`) -> report
+- Always use `runtime: "acp"` and `agentId: "opencode"` for OmO delegation
+- `model` is override-only — leave empty to use OpenCode's own configured default
+- Use `opencode_agent` to select OpenCode's internal agent mode (build, plan, custom)
+- Use `@agentname` prefix in task text to invoke OpenCode subagents
+- Use `label` parameter for easy identification of parallel sessions
 - Validate changes with `git status`/`git diff` before reporting results