agim-cli 1.2.130 → 1.2.131

package/CHANGELOG.md

@@ -4,6 +4,61 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.2.131] - 2026-06-01
+
+### Added (Claude-Code 风格的 Plan Mode 退出握手 — P0)
+
+之前 native 的 PlanMode 是单向开关：用户 `/plan on` 进，模型只能输出 plan 文本，
+然后用户手动 `/plan off` 才能让模型动手。Claude Code 的对应体验更自然：模型
+"自己说我想好了 → 用户审批 → 一键放行 + 立即继续"。本版补齐这个握手。
+
+#### 新工具 `native_exit_plan_mode`
+- 仅当所在线程的 PlanMode 已开启时才出现在工具集合中（其他场景模型看不到）
+- 模型调用时传 `{ plan: '<markdown>' }`（≤ 4000 字）
+- agim 通过 `approvalBus.registerSyntheticPending` 把 plan 推给 IM 端，渲染为审批卡
+- **用户点 Approve** → 立即 `setPlanModeForThread(false)`，写 plan_history 审计行，
+  返回 "Plan approved — proceed" 给模型，模型下一轮就有完整写权限
+- **用户点 Deny + 给原因** → 写 plan_history(outcome=rejected, detail=reason)，
+  返回 "Plan REJECTED. Revise based on: <reason>" 给模型，PlanMode 保持开启
+- 拒绝场景下模型会自动迭代再次调用 `native_exit_plan_mode`
+
+#### 新增 plan_history 审计表
+- `~/.agim/plan-history.db`（路径可由 `IMHUB_PLAN_HISTORY_DB` 覆盖）
+- 每次握手写一条不可变记录：thread_key / plan_md / outcome (approved|rejected|edited|expired)
+  / detail / pending_ms / resolved_at
+- 为后续 v1.2.133 的 `/tasks/plans` admin 列表查询打底（本版不做 UI）
+
+#### system prompt 改造
+plan mode banner 之前结尾写"操作员清掉 IMHUB_NATIVE_PLAN_MODE 你才能动手"。
+现在改为：
+
+> Exit handshake (v1.2.131): when the plan is ready, call
+>   `native_exit_plan_mode({ plan: '<markdown of the steps>' })`
+> The user will see an Approve/Reject card. On approve you regain full
+> write access and proceed immediately. On reject you stay in Plan Mode
+> with the user's feedback in the tool result — revise and call again.
+
+#### 安全 / 边界
+- 工具自带审批闸口；同时 native 默认 auto-allow 列表加入 `native_exit_plan_mode`，
+  避免双弹卡（policy gate 一张 + 内部 plan 卡一张）
+- CLI / 无 notifier 环境调用 → 直接返回错误结果 + 写 rejected 审计行，不挂起
+- 4000 字符上限防止 plan 把 approval-bus 卡撑爆
+- bun 运行下 better-sqlite3 不可用，helper 走 fail-soft 路径：插入返回 null、
+  读取返回 []，行为可观察但不会抛错（与已有 plan-mode-state / todo-dispatcher 一致）
+
+### 文件
+- 新增 `src/core/plan-history.ts`（~125 行 — sqlite 表 + insert + list）
+- 新增 `src/core/llm/plan-exit-dispatcher.ts`（~210 行 — 工具定义 + 握手逻辑）
+- 新增 `test/unit/plan-history.test.ts`（5 case — 输入校验 + fail-soft）
+- 新增 `test/unit/plan-exit-dispatcher.test.ts`（8 case — 工具定义 + 6 个 gate）
+- 修改 `src/plugins/agents/native/index.ts`：import + 接入 combineDispatchers +
+  按 PlanMode 状态条件性 advertise 工具 + 默认 auto-allow + system prompt
+  banner 换文案
+
+### v1.2.132 预告（P1）
+`/plan` 命令打通 claude-code / codex / cursor / opencode 4 个 CLI adapter，
+让"切 Plan Mode"在不同 agent 下都做对的事。下一版本。
+
 ## [1.2.130] - 2026-06-01
 
 ### Fixed (blank-retry 推空 assistant → openai-compat 400)

package/dist/core/llm/plan-exit-dispatcher.d.ts

@@ -0,0 +1,27 @@
+import type { ToolDef } from './provider-base.js';
+import type { ToolDispatcher } from './tool-dispatcher.js';
+export declare const PLAN_EXIT_TOOL_NAME = "native_exit_plan_mode";
+export declare function isPlanExitToolName(name: string): boolean;
+export interface PlanExitCtx {
+    /** Composite thread key (same one PlanMode + Todo use). */
+    threadKey: string;
+    /** agent-loop run identifier — required by approvalBus.registerRun. */
+    runId: string;
+    /** RunContext fields. approvalBus needs these to address the IM card
+     *  back to the right thread. When platform/channelId/threadId are
+     *  empty, the approval-bus has no way to surface the prompt; we fall
+     *  back to a synthetic "auto-approve only if running as loopback CLI"
+     *  hint and degrade to immediate rejection so model isn't stuck. */
+    platform?: string;
+    channelId?: string;
+    threadId?: string;
+    userId?: string;
+}
+/** Tool definitions to advertise — emitted ONLY when the thread is in
+ *  plan mode. The native agent strips it from the roster otherwise so
+ *  the model can't accidentally call it from a normal turn. */
+export declare function getPlanExitTools(): ToolDef[];
+/** Build a per-thread dispatcher. Each agent-loop run gets one; the
+ *  closure captures threadKey + runId + IM context. */
+export declare function buildPlanExitDispatcher(ctx: PlanExitCtx): ToolDispatcher;
+//# sourceMappingURL=plan-exit-dispatcher.d.ts.map

package/dist/core/llm/plan-exit-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-exit-dispatcher.d.ts","sourceRoot":"","sources":["../../../src/core/llm/plan-exit-dispatcher.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,KAAK,EAAoB,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAK5E,eAAO,MAAM,mBAAmB,0BAA0B,CAAA;AAE1D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb;;;;wEAIoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;+DAE+D;AAC/D,wBAAgB,gBAAgB,IAAI,OAAO,EAAE,CAmC5C;AAED;uDACuD;AACvD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,WAAW,GAAG,cAAc,CAgJxE"}

package/dist/core/llm/plan-exit-dispatcher.js

@@ -0,0 +1,210 @@
+// plan-exit-dispatcher — native_exit_plan_mode tool (v1.2.131 P0b).
+//
+// Mirrors Claude Code's ExitPlanMode handshake:
+//   1. Model is in PlanMode (write tools denied at policy gate).
+//   2. Model thinks through the plan, then calls `native_exit_plan_mode`
+//      with the plan markdown.
+//   3. Dispatcher routes the call through the approval-bus so the user
+//      sees an IM approval card carrying the plan content.
+//   4. On approve: clear per-thread PlanMode, record history,
+//      return "approved — proceed" so the model picks up with full
+//      write access on the next iteration.
+//   5. On reject: record history with reason, return rejection text so
+//      the model revises the plan (PlanMode stays ON).
+//
+// Why a dedicated dispatcher instead of relying on the existing
+// PolicyApprovalGate ("askUser" path):
+//   * That gate decides allow/deny on an ARBITRARY tool call; here the
+//     tool call IS the request — its only payload is markdown.
+//   * The outcome's side effect (flipping PlanMode off) needs to happen
+//     server-side at dispatch time, not via prompt-instruction to the
+//     model.
+//   * The plan_history audit row is specific to this tool.
+//
+// Tool is only advertised when isPlanModeOn(threadKey) is true; the
+// roster shrinks back when plan mode flips off.
+import { logger as rootLogger } from '../logger.js';
+import { approvalBus } from '../approval-bus.js';
+import { recordPlanHistory } from '../plan-history.js';
+import { effectivePlanModeOn, setPlanModeForThread, } from '../plan-mode-state.js';
+import { randomUUID } from 'node:crypto';
+const log = rootLogger.child({ component: 'plan-exit-dispatcher' });
+export const PLAN_EXIT_TOOL_NAME = 'native_exit_plan_mode';
+export function isPlanExitToolName(name) {
+    return name === PLAN_EXIT_TOOL_NAME;
+}
+/** Tool definitions to advertise — emitted ONLY when the thread is in
+ *  plan mode. The native agent strips it from the roster otherwise so
+ *  the model can't accidentally call it from a normal turn. */
+export function getPlanExitTools() {
+    return [
+        {
+            name: PLAN_EXIT_TOOL_NAME,
+            description: 'Call this when your plan is ready for the user to approve. ' +
+                'You MUST already be in Plan Mode (write/exec tools are blocked). ' +
+                'Pass a single `plan` argument: a concise markdown description of ' +
+                'EXACTLY the steps you will take after approval — one bullet per ' +
+                'concrete action. The user will see this in an approval card with ' +
+                'Approve / Reject buttons. On approve you regain full write access ' +
+                'and should immediately proceed; on reject you stay in Plan Mode ' +
+                'and revise the plan based on the user feedback.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    plan: {
+                        type: 'string',
+                        description: 'Markdown plan, ≤ 4000 chars. Use - bullets or numbered steps. ' +
+                            'Each step should be a single concrete action (read a file, edit X, ' +
+                            'run command Y). Avoid hand-wavy "review and refactor" — be specific.',
+                    },
+                },
+                required: ['plan'],
+                additionalProperties: false,
+            },
+            // The approval handshake can take a while — user might be away.
+            // 10 minutes is generous enough for any reasonable round-trip
+            // and short enough that a forgotten card doesn't pin a session
+            // indefinitely (the approval-bus default timeout still applies
+            // independently).
+            timeoutMs: 10 * 60 * 1000,
+        },
+    ];
+}
+/** Build a per-thread dispatcher. Each agent-loop run gets one; the
+ *  closure captures threadKey + runId + IM context. */
+export function buildPlanExitDispatcher(ctx) {
+    return async (call, _signal, _ctxDispatcher) => {
+        if (call.name !== PLAN_EXIT_TOOL_NAME) {
+            return { text: `not handled: ${call.name}`, isError: true, source: 'unknown' };
+        }
+        // 1. Validate plan mode IS on. If the model calls this from a
+        //    non-plan turn, refuse — the tool only makes sense as the
+        //    exit handshake from plan mode.
+        if (!ctx.threadKey || !effectivePlanModeOn(ctx.threadKey)) {
+            return {
+                text: 'native_exit_plan_mode can only be called while Plan Mode is active. ' +
+                    'This thread is not in Plan Mode — proceed with normal tool calls.',
+                isError: true,
+                source: 'plan-exit',
+            };
+        }
+        // 2. Validate + cap the plan markdown. Bigger plans don't help — IM
+        //    approval cards are short; force the model to be concise.
+        const raw = call.arguments?.plan;
+        if (typeof raw !== 'string') {
+            return { text: '`plan` must be a string', isError: true, source: 'plan-exit' };
+        }
+        const planMd = raw.trim();
+        if (!planMd) {
+            return { text: '`plan` is empty', isError: true, source: 'plan-exit' };
+        }
+        if (planMd.length > 4000) {
+            return {
+                text: `\`plan\` too long (${planMd.length} > 4000 chars). Tighten it.`,
+                isError: true, source: 'plan-exit',
+            };
+        }
+        // 3. Need a real IM thread to surface the approval card. CLI smoke
+        //    and tests run without a notifier; in that case we degrade
+        //    deterministically with a "no UI to ask" message and stay in
+        //    plan mode so the model can recover.
+        if (!ctx.platform || !ctx.threadId || !approvalBus.hasNotifier()) {
+            recordPlanHistory({
+                threadKey: ctx.threadKey,
+                planMd,
+                outcome: 'rejected',
+                detail: 'no IM notifier available — cannot surface approval card',
+            });
+            return {
+                text: 'No interactive UI is available to confirm this plan ' +
+                    '(headless / CLI mode). Cannot exit Plan Mode automatically. ' +
+                    'Ask the operator to run `/plan off` from an IM session.',
+                isError: true,
+                source: 'plan-exit',
+            };
+        }
+        // 4. Hand off to approval-bus. Same shape as the buildNativeAskUser
+        //    flow — we register a synthetic pending and resolve when the
+        //    user clicks. Capture wall time so the audit row reports how
+        //    long the user took.
+        const reqId = randomUUID();
+        const t0 = Date.now();
+        const decision = await new Promise((resolve, reject) => {
+            void approvalBus.registerSyntheticPending({
+                runId: ctx.runId,
+                reqId,
+                toolName: PLAN_EXIT_TOOL_NAME,
+                input: { plan: planMd },
+                ctx: {
+                    platform: ctx.platform,
+                    channelId: ctx.channelId ?? 'default',
+                    threadId: ctx.threadId,
+                    userId: ctx.userId ?? 'unknown',
+                    callerAgent: 'native',
+                },
+                // `message` is only present on the deny branch (Decision is a
+                // discriminated union); we narrow defensively so the approve
+                // branch's lack of `message` doesn't trip the type checker.
+                dispatch: (d) => resolve({
+                    behavior: d.behavior,
+                    reason: d.behavior === 'deny' ? d.message : undefined,
+                }),
+            }).catch((err) => reject(err));
+        });
+        const pendingMs = Date.now() - t0;
+        if (decision.behavior === 'allow') {
+            // 5a. Flip plan mode OFF for the thread + record audit row.
+            //     Use setPlanModeForThread(false) — explicit "this thread is
+            //     out", which beats the env default even if env says ON.
+            setPlanModeForThread(ctx.threadKey, false);
+            recordPlanHistory({
+                threadKey: ctx.threadKey,
+                planMd,
+                outcome: 'approved',
+                detail: decision.reason ?? null,
+                pendingMs,
+            });
+            log.info({
+                event: 'plan-exit.approved',
+                threadKey: ctx.threadKey,
+                planLen: planMd.length,
+                pendingMs,
+            });
+            return {
+                text: 'Plan approved by user. You are now OUT of Plan Mode and have full ' +
+                    'write/exec access for the rest of this conversation. Proceed with ' +
+                    'the plan exactly as agreed.',
+                isError: false,
+                source: 'plan-exit',
+            };
+        }
+        // 5b. Reject — keep plan mode on, record audit, give model the
+        //     rejection reason so it can revise. Surfaces the reason
+        //     directly in tool result so it lands in the next turn's
+        //     context window.
+        recordPlanHistory({
+            threadKey: ctx.threadKey,
+            planMd,
+            outcome: 'rejected',
+            detail: decision.reason ?? null,
+            pendingMs,
+        });
+        log.info({
+            event: 'plan-exit.rejected',
+            threadKey: ctx.threadKey,
+            planLen: planMd.length,
+            pendingMs,
+            reason: decision.reason,
+        });
+        const reason = decision.reason?.trim();
+        return {
+            text: 'Plan REJECTED by user. You remain in Plan Mode. Revise the plan to ' +
+                'address this feedback:\n\n' +
+                (reason ? `> ${reason}` : '> (no reason provided)') +
+                '\n\nWhen ready, call native_exit_plan_mode again with the revised plan.',
+            isError: true,
+            source: 'plan-exit',
+        };
+    };
+}
+//# sourceMappingURL=plan-exit-dispatcher.js.map

package/dist/core/llm/plan-exit-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-exit-dispatcher.js","sourceRoot":"","sources":["../../../src/core/llm/plan-exit-dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/core/plan-history.d.ts

@@ -0,0 +1,34 @@
+/** Outcome strings written into the row. `expired` is reserved for the
+ *  later approval-timeout path (v1.2.131 P0b only writes the first
+ *  three). */
+export type PlanOutcome = 'approved' | 'rejected' | 'edited' | 'expired';
+/** What the audit callers pass in. `pendingMs` is optional because
+ *  callers may not have measured it (e.g. test paths); the column
+ *  stays NULL in that case. */
+export interface RecordPlanInput {
+    threadKey: string;
+    planMd: string;
+    outcome: PlanOutcome;
+    detail?: string | null;
+    pendingMs?: number | null;
+}
+/** Insert a new immutable row. Returns the auto-id or null on failure. */
+export declare function recordPlanHistory(input: RecordPlanInput): number | null;
+export interface PlanHistoryRow {
+    id: number;
+    threadKey: string;
+    planMd: string;
+    outcome: PlanOutcome;
+    detail: string | null;
+    resolvedAt: string;
+    pendingMs: number | null;
+}
+/** Recent entries — admin UI uses this. `threadKey` filter is optional;
+ *  omit to see global history. */
+export declare function listPlanHistory(opts?: {
+    threadKey?: string;
+    limit?: number;
+}): PlanHistoryRow[];
+/** Test-only: close the db handle so a tmp file can be unlinked. */
+export declare function closePlanHistoryDb(): void;
+//# sourceMappingURL=plan-history.d.ts.map

package/dist/core/plan-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-history.d.ts","sourceRoot":"","sources":["../../src/core/plan-history.ts"],"names":[],"mappings":"AAoBA;;cAEc;AACd,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAA;AAiCxE;;+BAE+B;AAC/B,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAsBvE;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,WAAW,CAAA;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED;kCACkC;AAClC,wBAAgB,eAAe,CAAC,IAAI,GAAE;IACpC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACV,GAAG,cAAc,EAAE,CAmBxB;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/core/plan-history.js

@@ -0,0 +1,89 @@
+// plan-history.ts — audit log for native_exit_plan_mode handshakes
+// (v1.2.131 P0a).
+//
+// Why a separate sqlite table from plan-mode.db:
+//   plan-mode.db holds the CURRENT state per thread (PK = thread_key,
+//   one row max). plan-history records EACH transition — many rows
+//   per thread over time — so operators can see "what did the model
+//   propose 3 turns ago, did the user accept, why was it rejected".
+//
+// Schema is intentionally small + write-once. We never UPDATE rows;
+// each entry is immutable for audit integrity. Retention is the
+// operator's problem (vacuum-on-rotation could be added later).
+import { join } from 'node:path';
+import { logger as rootLogger } from './logger.js';
+import { createSqliteHelper } from './sqlite-helper.js';
+import { AGIM_HOME } from './agim-paths.js';
+const log = rootLogger.child({ component: 'plan-history' });
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS plan_history (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  thread_key TEXT NOT NULL,
+  plan_md    TEXT NOT NULL,
+  outcome    TEXT NOT NULL,
+  /** Free-form text — rejection reason, edit diff summary, etc. */
+  detail     TEXT,
+  /** ISO timestamp at the moment of resolution. */
+  resolved_at TEXT NOT NULL DEFAULT (datetime('now')),
+  /** Wall-clock seconds spent waiting for the user. */
+  pending_ms INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_plan_history_thread
+  ON plan_history(thread_key, resolved_at DESC);
+CREATE INDEX IF NOT EXISTS idx_plan_history_resolved
+  ON plan_history(resolved_at DESC);
+`;
+const DB_PATH_FROM_ENV = process.env.IMHUB_PLAN_HISTORY_DB;
+const dbPath = DB_PATH_FROM_ENV && DB_PATH_FROM_ENV.length > 0
+    ? DB_PATH_FROM_ENV
+    : join(AGIM_HOME, 'plan-history.db');
+const helper = createSqliteHelper({
+    file: dbPath,
+    schema: SCHEMA,
+    logger: rootLogger,
+    component: 'plan-history-db',
+});
+/** Insert a new immutable row. Returns the auto-id or null on failure. */
+export function recordPlanHistory(input) {
+    if (!input.threadKey || !input.planMd || !input.outcome)
+        return null;
+    return helper.safe((d) => {
+        const res = d.prepare(`INSERT INTO plan_history (thread_key, plan_md, outcome, detail, pending_ms)
+       VALUES (?, ?, ?, ?, ?)`).run(input.threadKey, input.planMd, input.outcome, input.detail ?? null, input.pendingMs ?? null);
+        log.info({
+            event: 'plan-history.recorded',
+            threadKey: input.threadKey,
+            outcome: input.outcome,
+            planLen: input.planMd.length,
+            id: res.lastInsertRowid,
+        });
+        return Number(res.lastInsertRowid);
+    }, null);
+}
+/** Recent entries — admin UI uses this. `threadKey` filter is optional;
+ *  omit to see global history. */
+export function listPlanHistory(opts = {}) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 500));
+    return helper.safe((d) => {
+        const sql = opts.threadKey
+            ? `SELECT id, thread_key as threadKey, plan_md as planMd, outcome,
+                detail, resolved_at as resolvedAt, pending_ms as pendingMs
+         FROM plan_history WHERE thread_key = ?
+         ORDER BY resolved_at DESC, id DESC
+         LIMIT ?`
+            : `SELECT id, thread_key as threadKey, plan_md as planMd, outcome,
+                detail, resolved_at as resolvedAt, pending_ms as pendingMs
+         FROM plan_history
+         ORDER BY resolved_at DESC, id DESC
+         LIMIT ?`;
+        const rows = opts.threadKey
+            ? d.prepare(sql).all(opts.threadKey, limit)
+            : d.prepare(sql).all(limit);
+        return rows;
+    }, []);
+}
+/** Test-only: close the db handle so a tmp file can be unlinked. */
+export function closePlanHistoryDb() {
+    helper.close();
+}
+//# sourceMappingURL=plan-history.js.map

package/dist/core/plan-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-history.js","sourceRoot":"","sources":["../../src/core/plan-history.ts"],"names":[],"mappings":"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"}

package/dist/plugins/agents/native/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/plugins/agents/native/index.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,4BAA4B,CAAA;AAKnC,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,2CAA2C,CAAA;AAoClD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CAwKR;AAED;;;;;;;+DAO+D;AAC/D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBpD;AAwPD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAyD1E;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AA8ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCvF;AAglBD,eAAO,MAAM,kBAAkB,EAAE,YAAuC,CAAA;AAExE;;cAEc;AACd,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/plugins/agents/native/index.ts"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,wBAAwB,CAAA;AAG/B,OAAO,EAOL,KAAK,WAAW,EAEjB,MAAM,4BAA4B,CAAA;AAKnC,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,2CAA2C,CAAA;AAyClD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,CA0KR;AAED;;;;;;;+DAO+D;AAC/D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBpD;AAwPD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,wBAAwB,CAgE1E;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAExD;AA8ED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCvF;AAmmBD,eAAO,MAAM,kBAAkB,EAAE,YAAuC,CAAA;AAExE;;cAEc;AACd,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C"}

package/dist/plugins/agents/native/index.js

@@ -48,6 +48,7 @@ import { buildFsDispatcher, getFsTools, } from '../../../core/llm/fs-dispatcher.
 import { buildWebDispatcher, getWebTools, } from '../../../core/llm/web-dispatcher.js';
 import { buildExecDispatcher, getExecTools, } from '../../../core/llm/exec-dispatcher.js';
 import { buildTodoDispatcher, getTodoTools, } from '../../../core/llm/todo-dispatcher.js';
+import { buildPlanExitDispatcher, getPlanExitTools, } from '../../../core/llm/plan-exit-dispatcher.js';
 import { listSkills } from '../../../core/skills/loader.js';
 import { describeRegistry as describeMcpRegistry } from '../../../core/llm/mcp-registry.js';
 import { resolveAgentCwd, defaultAgentCwd } from '../../../core/agent-cwd.js';
@@ -105,7 +106,7 @@ export function buildSystemPrompt(provider, role, cwd, threadKey) {
     // the policy gate gives a bare "tool call denied" message and the
     // model wastes iterations trying alternative write paths.
     if (isPlanModeOn(threadKey)) {
-        lines.push(`⚠ Plan mode is ACTIVE (IMHUB_NATIVE_PLAN_MODE=1)`, `  - You MUST produce a read-only plan; native_write_file and native_exec are HARD-BLOCKED.`, `  - Use read tools freely: native_read_file / native_list_dir / native_glob / native_grep / native_web_fetch / native_web_search.`, `  - Output: present a concrete written plan with steps, files to change, commands to run, and risks. End the turn after writing the plan — do NOT attempt the changes.`, `  - The operator clears IMHUB_NATIVE_PLAN_MODE when they're ready to let you act.`, ``);
+        lines.push(`⚠ Plan mode is ACTIVE`, `  - You MUST produce a read-only plan; native_write_file and native_exec are HARD-BLOCKED.`, `  - Use read tools freely: native_read_file / native_list_dir / native_glob / native_grep / native_web_fetch / native_web_search.`, `  - Exit handshake (v1.2.131): when the plan is ready, call`, `      native_exit_plan_mode({ plan: '<markdown of the steps>' })`, `    The user will see an Approve/Reject card. On approve you regain full write access and proceed immediately. On reject you stay in Plan Mode with the user's feedback in the tool result — revise and call again.`, `  - DO NOT just describe the plan in prose and stop — the user expects the exit handshake. Skip it only if the user explicitly asks for "no exit" / "just brainstorm".`, ``);
     }
     lines.push(`Tools available beyond the four native built-ins (echo / now / sleep / random_uuid):`, `  - agim built-in MCP tools (mcp__imhub__*): read_skill, list_skills, save_memo, search_memos, update_memo, delete_memo, push_message, ask_user, call_agent, long_task, complete_goal`, `  - native filesystem tools: native_read_file, native_write_file, native_list_dir, native_glob, native_grep — constrained to your workspace cwd unless IMHUB_NATIVE_FS_RESTRICT=0`, `  - native web tools: native_web_fetch (r.jina.ai reader by default), native_web_search (duckduckgo → metaso fallback). Private IPs blocked.`, `  - native_exec(command, timeout_ms?, cwd?): run shell commands. Always approval-gated; bwrap sandbox when IMHUB_EXEC_SANDBOX=bwrap.`, `  - External MCP servers configured by the operator:`, externalMcp, ``, `Available skill cards (call mcp__imhub__read_skill('<name>') for the full body):`, skillsBlock, ``, `Guidance:`, `  - Be terse; avoid filler. Prefer tool use over guessing.`, `  - When uncertain, call mcp__imhub__ask_user(question, choices[]) instead of free-form back-and-forth.`, `  - When the user references something they told the bot before, search memos via mcp__imhub__search_memos.`, ``, `Tool selection priority (HARD RULE — v1.2.59):`, `  - For "read this file / list this dir / search this content / fetch this URL", you MUST FIRST try`, `    your own native tools: native_read_file, native_list_dir, native_glob, native_grep,`, `    native_web_fetch (if available). Do NOT delegate these to call_agent.`, `  - call_agent is reserved for tasks that genuinely need a CLI agent's specialised capabilities`, `    (writing/editing source code in a real repo → claude-code; long-running plans → codex; etc).`, `  - You have a per-turn call_agent cap (default 2). Burning it on file reads will leave you`, `    unable to delegate later when you actually need to.`, ``, `Web tool routing (HARD RULE — v1.2.64):`, `  - If the user provided a SPECIFIC URL (http://… or https://…) → native_web_fetch.`, `  - If the user wants to FIND / DISCOVER something by keywords ("查找最新 X" / "search for Y" /`, `    "find docs on Z" / "今天 / 最近的 W") → native_web_search FIRST. Don't guess a URL.`, `  - Common pattern: native_web_search(query) → pick a result → native_web_fetch(that.url).`, `  - NEVER call native_web_fetch with a URL you fabricated from the user's keywords.`, ``, `Short-input rule:`, `  - If the user's message is ONLY a slash command alias for an agent name (e.g. "/native", "/llm",`, `    "/na", "/cc", "/oc") and you are already that agent, respond with ONE short line confirming`, `    your identity (e.g. "我是 native，正在听。"). Do NOT call any tool. The slash router handles`, `    actual agent switching; if it didn't switch, the user is already on this agent.`, ``, `Plan tracking (v1.2.124 — native_todo_write):`, `  - When the user gives you a task with ≥ 3 distinct steps, FIRST call native_todo_write({items}) to`, `    write out your plan, then update statuses as you complete each step.`, `    Status values: pending | in_progress | completed. Keep exactly one item in_progress at a time.`, `  - The tool result is a rendered markdown checklist; the user sees your progress.`, `  - Don't call native_todo_write for trivial one-step tasks — overhead.`, `  - Example sequence:`, `    1) native_todo_write([{c:"Fetch market data",s:"in_progress"}, {c:"Analyse",s:"pending"}, {c:"Reply",s:"pending"}])`, `    2) … do fetch via native_web_fetch …`, `    3) native_todo_write([{c:"Fetch market data",s:"completed"}, {c:"Analyse",s:"in_progress"}, {c:"Reply",s:"pending"}])`, `    4) … analysis …`, `    5) write final answer to user`, ``, `Closure rule (v1.2.94 — HARD RULE):`, `  - When you finish a tool chain (read_file / web_fetch / native_exec / search_memos / etc.) you`, `    MUST write a short Chinese summary BEFORE stopping. The tool output by itself is not a`, `    user-facing answer — the user can't see the raw JSON / shell stdout. Always close with at`, `    least one sentence stating the finding / conclusion.`, `  - Do NOT end a turn with empty assistant text when you've just called tools. If you genuinely`, `    have nothing to add, say so explicitly ("已查完，未发现 X").`, ``, `Proactive memory rule (v1.2.96 — borrowed from Hermes Agent's "agent-curated memory"):`, `  - Before ending a substantive turn, scan the conversation for facts that should outlive the`, `    current chat. Persist them yourself via mcp__imhub__save_memo — don't wait for the user to`, `    ask you to remember.`, `  - Worth saving (call save_memo for each):`, `      · personal preferences ("我不喝咖啡" / "我用 vim"),`, `      · holdings or portfolio codes ("我持有 600519"),`, `      · recurring people / places ("我家在朝阳" / "爸爸生日 5月8日"),`, `      · stable identifiers (账号 / 邮箱 / API base / 配置路径),`, `      · explicit "记一下" / "remember this" instructions.`, `  - NOT worth saving: one-off questions, transient debugging context, tool outputs that are`, `    already cached elsewhere (memos point AT data, they're not a cache of data).`, `  - Each save_memo call is cheap. Two short memos beat one long one — small atomic facts`, `    search better. Add a 1-line user-facing acknowledgement so the user knows you remembered`, `    (e.g. "已记下 600519 是你的持仓").`, ``, `Long-task SOP (v1.2.93 — for any work you estimate will run > 10 minutes):`, `  - You CANNOT keep a long synchronous turn alive: the IM bridge times out around 30 min, and`, `    most useful work past the 10-min mark loses intermediate state if it crashes mid-flight.`, `  - Instead, use native_exec to invoke the agim bgjob wrapper, which spawns a detached worker`, `    that survives independent of this conversation:`, `      native_exec("/root/.claude/scripts/bgjob start <slug> -- /usr/bin/python3 /path/to/script.py [args]")`, `    Substitute python3 for the runtime you actually need. The wrapper returns a job_id; relay it`, `    to the user verbatim and tell them how to check back: \`bgjob status <id>\` / \`bgjob tail <id> -f\`.`, `  - When the user follows up asking about the job, native_exec calls like \`bgjob status <id>\` or`, `    \`bgjob tail <id> -n 100\` give you the current state + recent log lines.`, `  - The bwrap sandbox (when configured) is bypassed for this specific wrapper path so the`, `    setsid-detached worker actually survives. Any OTHER native_exec command remains sandboxed.`, `  - DO NOT use \`nohup ... &\` or backgrounded shell pipelines for long work — those die with the`, `    parent shell. bgjob is the only correct path on this platform.`, ``, `Python-RPC bridge (v1.2.97 — when a task means MANY similar tool calls):`, `  - When you would otherwise call mcp__imhub__* dozens of times in this chat turn (saving 30`, `    facts, fetching 50 stocks, scoring 100 candidates), DO NOT do it inline — that wastes the`, `    iteration budget and is likely to trip the stuck-loop detector. Write ONE Python script,`, `    run it in bgjob, and let it loop locally while calling back to agim's tool surface via the`, `    local RPC bridge agim sets up automatically for every native_exec child.`, `  - The Python sidecar lives at \`<npm install dir>/bin/agim_rpc.py\` (typically`, `    /usr/local/lib/node_modules/agim-cli/bin/agim_rpc.py — find it with`, `    \`node -e "console.log(require.resolve('agim-cli'))"\`). Import it and instantiate the client:`, `      from agim_rpc import client`, `      rpc = client()                                 # reads env, validates token, no args needed`, `      memos = rpc.search_memos(query="茅台", k=10)`, `      for m in memos.get("rows", []):`, `          ...`, `      rpc.push_message(text="后台跑完了，结果是 X")`, `  - Available tools through the bridge (whitelist): search_memos, save_memo, read_skill,`, `    list_skills, push_message. Everything else (native_exec, fs writes, call_agent, long_task,`, `    ask_user) is NOT exposed — the worker already has a shell + filesystem.`, `  - The token is automatically injected via env (IMHUB_RPC_SOCKET + IMHUB_RPC_TOKEN), bound`, `    to THIS IM thread, valid for 24 h. The worker can only drive this thread; it cannot`, `    push_message into someone else's chat.`, `  - End the worker with rpc.push_message(text="…done…") so the user sees the result come back`, `    asynchronously. Don't expect the user to poll \`bgjob tail\` themselves.`);
     return lines.join('\n');
@@ -435,6 +436,13 @@ export function resolvePolicy(threadKey) {
         // per-thread; zero side effects beyond the model's own state. Safe
         // to default-allow; never asks the user.
         'native_todo_write',
+        // v1.2.131 — Plan-mode exit handshake. The tool's OWN dispatcher
+        // raises the user-facing approval card (with the plan markdown
+        // payload); auto-allowing here just keeps the policy gate from
+        // double-prompting. Without this entry an operator using allow-list
+        // mode would see two cards back-to-back ("native_exit_plan_mode
+        // ok?" then "approve plan?").
+        'native_exit_plan_mode',
     ];
     const effectiveAllow = mode === 'allow-list'
         ? Array.from(new Set([...autoAllow, ...defaultBuiltins]))
@@ -776,7 +784,18 @@ class NativeAgentAdapter {
         // before imhub so a stray tool name collision (none today) would
         // be caught early. Uses the same composite thread key the PlanMode
         // resolver does so users can find their list in audit.
-        buildTodoDispatcher(planThreadKey ?? `native:${sessionId}`), buildImhubDispatcher(imhubCtx), buildMcpDispatcher());
+        buildTodoDispatcher(planThreadKey ?? `native:${sessionId}`), 
+        // v1.2.131 — ExitPlanMode handshake. Always wired; the dispatcher
+        // itself refuses calls when the thread is NOT in plan mode, so
+        // the model can't accidentally exit something it didn't enter.
+        buildPlanExitDispatcher({
+            threadKey: planThreadKey ?? `native:${sessionId}`,
+            runId: sessionId,
+            platform: opts.platform,
+            channelId: opts.channelId,
+            threadId: opts.threadId,
+            userId: opts.userId,
+        }), buildImhubDispatcher(imhubCtx), buildMcpDispatcher());
         // Compose tool list the same way (built-in → fs → web → exec → todo → imhub → external MCP).
         // Provider tool roster wins on duplicate names via "later
         // definition wins" semantics inside the provider, but our naming
@@ -791,6 +810,14 @@ class NativeAgentAdapter {
             ...getImhubTools(),
             ...getAllMcpTools(),
         ];
+        // v1.2.131 — when this thread is in Plan Mode, advertise the
+        // dedicated exit tool so the model knows the handshake exists. We
+        // don't always advertise it: a model in normal mode shouldn't be
+        // tempted to call it (the dispatcher would refuse anyway, but
+        // keeping the roster honest is cleaner).
+        if (planThreadKey && effectivePlanModeOn(planThreadKey)) {
+            tools.push(...getPlanExitTools());
+        }
         const policy = resolvePolicy(planThreadKey);
         // v1.2.60 — when the policy would silently deny a tool call,
         // escalate to the user via an IM approval card instead. Only