@shgroup/opencode-serenity-plugin 0.2.0

package/dist/fs/resolve-path.d.ts

@@ -0,0 +1,53 @@
+/**
+ * resolve-path.ts — 宁静号文件系统基础设施
+ *
+ * 核心能力：
+ * - 向上遍历寻找 .serenity 文件（实例根检测）
+ * - 基于实例根做路径解析
+ * - 路径安全校验（确保在根内）
+ *
+ * 供 file-system-tool.ts 消费，也可被其他模块复用。
+ */
+/**
+ * findSerenityRoot — 从 cwd 开始向上遍历，寻找包含 .serenity 文件的目录
+ *
+ * @param cwd 起始目录（通常是 opencode 的 input.directory）
+ * @returns 包含 .serenity 的目录绝对路径
+ * @throws Error 如果未找到宁静号根
+ */
+export declare function findSerenityRoot(cwd: string): string;
+/**
+ * findSerenityRootSafe — 不抛错版本
+ * @returns 根路径或 null（未找到时）
+ */
+export declare function findSerenityRootSafe(cwd: string): string | null;
+/**
+ * readSerenityInstanceName — 从 .serenity 文件读取实例名
+ * @returns 实例名（如 "home-serenity", "tg-serenity"）或 null
+ */
+export declare function readSerenityInstanceName(root: string): string | null;
+/**
+ * resolveRootPath — 将 path 基于宁静号根解析为绝对路径
+ *
+ * @param root 实例根路径
+ * @param path 相对路径（如 "AGENT_SESSIONS/"）或绝对路径
+ * @returns 解析后的绝对路径
+ */
+export declare function resolveRootPath(root: string, path: string): string;
+/**
+ * isPathInsideSerenity — 判断路径是否在宁静号根内
+ *
+ * @param root 实例根路径
+ * @param target 要检查的路径（绝对路径）
+ * @returns true 当 target 在 root 目录内
+ */
+export declare function isPathInsideSerenity(root: string, target: string): boolean;
+/**
+ * serenityPathRelative — 获取 target 相对于宁静号根的路径
+ *
+ * @param root 实例根路径
+ * @param target 绝对路径
+ * @returns 相对路径（如 ".opencode/skills/eap/SKILL.md"）
+ */
+export declare function serenityPathRelative(root: string, target: string): string;
+//# sourceMappingURL=resolve-path.d.ts.map

package/dist/fs/resolve-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-path.d.ts","sourceRoot":"","sources":["../../src/fs/resolve-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBpD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM/D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAMzE"}

package/dist/fs/resolve-path.js

@@ -0,0 +1,100 @@
+/**
+ * resolve-path.ts — 宁静号文件系统基础设施
+ *
+ * 核心能力：
+ * - 向上遍历寻找 .serenity 文件（实例根检测）
+ * - 基于实例根做路径解析
+ * - 路径安全校验（确保在根内）
+ *
+ * 供 file-system-tool.ts 消费，也可被其他模块复用。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, relative, dirname, normalize } from 'node:path';
+/**
+ * findSerenityRoot — 从 cwd 开始向上遍历，寻找包含 .serenity 文件的目录
+ *
+ * @param cwd 起始目录（通常是 opencode 的 input.directory）
+ * @returns 包含 .serenity 的目录绝对路径
+ * @throws Error 如果未找到宁静号根
+ */
+export function findSerenityRoot(cwd) {
+    let current = resolve(cwd);
+    // 向上遍历到根
+    while (true) {
+        const marker = resolve(current, '.serenity');
+        if (existsSync(marker)) {
+            return current;
+        }
+        // 到达根目录
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new Error(`No serenity instance found: no .serenity file found when walking up from "${cwd}"`);
+        }
+        current = parent;
+    }
+}
+/**
+ * findSerenityRootSafe — 不抛错版本
+ * @returns 根路径或 null（未找到时）
+ */
+export function findSerenityRootSafe(cwd) {
+    try {
+        return findSerenityRoot(cwd);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * readSerenityInstanceName — 从 .serenity 文件读取实例名
+ * @returns 实例名（如 "home-serenity", "tg-serenity"）或 null
+ */
+export function readSerenityInstanceName(root) {
+    const marker = resolve(root, '.serenity');
+    try {
+        const content = readFileSync(marker, 'utf8').trim();
+        return content || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * resolveRootPath — 将 path 基于宁静号根解析为绝对路径
+ *
+ * @param root 实例根路径
+ * @param path 相对路径（如 "AGENT_SESSIONS/"）或绝对路径
+ * @returns 解析后的绝对路径
+ */
+export function resolveRootPath(root, path) {
+    if (path.startsWith('/')) {
+        return normalize(path);
+    }
+    return normalize(resolve(root, path));
+}
+/**
+ * isPathInsideSerenity — 判断路径是否在宁静号根内
+ *
+ * @param root 实例根路径
+ * @param target 要检查的路径（绝对路径）
+ * @returns true 当 target 在 root 目录内
+ */
+export function isPathInsideSerenity(root, target) {
+    const rel = relative(root, target);
+    return !rel.startsWith('..');
+}
+/**
+ * serenityPathRelative — 获取 target 相对于宁静号根的路径
+ *
+ * @param root 实例根路径
+ * @param target 绝对路径
+ * @returns 相对路径（如 ".opencode/skills/eap/SKILL.md"）
+ */
+export function serenityPathRelative(root, target) {
+    const rel = relative(root, target);
+    if (rel.startsWith('..')) {
+        throw new Error(`Path "${target}" is outside serenity root "${root}"`);
+    }
+    return rel;
+}
+//# sourceMappingURL=resolve-path.js.map

package/dist/fs/resolve-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-path.js","sourceRoot":"","sources":["../../src/fs/resolve-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,IAAI,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE3B,SAAS;IACT,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC7C,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,QAAQ;QACR,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,6EAA6E,GAAG,GAAG,CACpF,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,CAAC;QACH,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACpD,OAAO,OAAO,IAAI,IAAI,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,MAAc;IAC/D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,MAAc;IAC/D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,SAAS,MAAM,+BAA+B,IAAI,GAAG,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/hooks/compacting.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compacting / System Transform Hook 工厂
+ *
+ * 包含：
+ * 1. experimental.chat.system.transform — 注入 SKILL.md 全文到 system prompt
+ * 2. experimental.session.compacting — 压缩时注入"serenity 关键状态" context
+ *
+ * 设计：
+ * - system.transform 唯一职责：把 state.skillContent 全文 push 到 system prompt
+ * - 同一 session 内 system.transform 可能被多次触发（每次重建 system prompt），
+ *   通过检查 output.system 是否已包含 skillContent 实现 idempotent dedup（无状态）
+ * - compacting 保留：避免 serenity 关键状态被压缩丢失
+ */
+import type { Hooks } from '@opencode-ai/plugin';
+import { type HookConfig } from './util.js';
+/** 工厂：返回 compacting / system transform / tool definition 相关的 hooks 集合
+ *
+ * v1.12: 改用 safeCreateHook（factory pattern）
+ * - safeHook（旧）：禁用时返回 undefined（hook 不注册）
+ * - safeCreateHook（新）：禁用时返回 no-op（hook 注册但不做事）— host 期望 hook 存在
+ */
+export declare function createCompactingHooks(config?: HookConfig): Partial<Hooks>;
+//# sourceMappingURL=compacting.d.ts.map

package/dist/hooks/compacting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compacting.d.ts","sourceRoot":"","sources":["../../src/hooks/compacting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AA8E5D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAsBzE"}

package/dist/hooks/compacting.js

@@ -0,0 +1,90 @@
+/**
+ * Compacting / System Transform Hook 工厂
+ *
+ * 包含：
+ * 1. experimental.chat.system.transform — 注入 SKILL.md 全文到 system prompt
+ * 2. experimental.session.compacting — 压缩时注入"serenity 关键状态" context
+ *
+ * 设计：
+ * - system.transform 唯一职责：把 state.skillContent 全文 push 到 system prompt
+ * - 同一 session 内 system.transform 可能被多次触发（每次重建 system prompt），
+ *   通过检查 output.system 是否已包含 skillContent 实现 idempotent dedup（无状态）
+ * - compacting 保留：避免 serenity 关键状态被压缩丢失
+ */
+import { getState, ensureReady } from '../state.js';
+import { safeCreateHook } from './util.js';
+const systemTransformImpl = async (_input, output) => {
+    try {
+        await ensureReady();
+    }
+    catch {
+        return;
+    }
+    const state = getState();
+    if (!state.skillContent)
+        return; // SKILL.md 读失败或缺失 → 跳过
+    // idempotent dedup：检查 output.system 是否已包含 skillContent
+    if (output.system.includes(state.skillContent))
+        return;
+    output.system.push(state.skillContent);
+};
+const sessionCompactingImpl = async (_input, output) => {
+    try {
+        await ensureReady();
+    }
+    catch {
+        return;
+    }
+    const state = getState();
+    output.context.push(`[serenity-state] cwdRoot=${state.cwdRoot}; instanceName=${state.instanceName}; skillPath=${state.skillPath}`);
+};
+/**
+ * tool.definition — 为 task tool 注入 serenity 精简上下文，
+ * 让 LLM 在创建 subagent 时自动把 context 传入 prompt 参数。
+ *
+ * 只劫持 toolID === 'task'，其他 tool 透传。
+ */
+const toolDefinitionImpl = async (input, output) => {
+    // 只处理 task tool（subagent 创建）
+    if (input.toolID !== 'task')
+        return;
+    try {
+        await ensureReady();
+    }
+    catch {
+        return;
+    }
+    const state = getState();
+    if (!state.activated || !state.instanceName)
+        return;
+    const context = [
+        `=== Serenity System Context ===`,
+        `Instance: ${state.instanceName}`,
+        `Root: ${state.cwdRoot}`,
+        ``,
+        `Available serenity tools for subagents:`,
+        `  - msm_list — discover registered MSM tools with descriptions`,
+        `  - msm_exec — execute an MSM by name with string array args`,
+        `  - file_system — safe file operations within serenity root`,
+        `  - session_tool — session lifecycle management`,
+        ``,
+        `IMPORTANT: Include this serenity context in the 'prompt'`,
+        `parameter so the subagent can use serenity tools.`,
+        `=== End Serenity Context ===`,
+    ].join('\n');
+    output.description = context + '\n\n' + output.description;
+};
+/** 工厂：返回 compacting / system transform / tool definition 相关的 hooks 集合
+ *
+ * v1.12: 改用 safeCreateHook（factory pattern）
+ * - safeHook（旧）：禁用时返回 undefined（hook 不注册）
+ * - safeCreateHook（新）：禁用时返回 no-op（hook 注册但不做事）— host 期望 hook 存在
+ */
+export function createCompactingHooks(config) {
+    const hooks = {};
+    hooks['experimental.chat.system.transform'] = safeCreateHook('experimental.chat.system.transform', () => systemTransformImpl, config);
+    hooks['experimental.session.compacting'] = safeCreateHook('experimental.session.compacting', () => sessionCompactingImpl, config);
+    hooks['tool.definition'] = safeCreateHook('tool.definition', () => toolDefinitionImpl, config);
+    return hooks;
+}
+//# sourceMappingURL=compacting.js.map

package/dist/hooks/compacting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compacting.js","sourceRoot":"","sources":["../../src/hooks/compacting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,cAAc,EAAmB,MAAM,WAAW,CAAC;AAE5D,MAAM,mBAAmB,GAA6D,KAAK,EACzF,MAAM,EACN,MAAM,EACN,EAAE;IACF,IAAI,CAAC;QACH,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,YAAY;QAAE,OAAO,CAAE,uBAAuB;IAEzD,uDAAuD;IACvD,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;QAAE,OAAO;IAEvD,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AACzC,CAAC,CAAC;AAEF,MAAM,qBAAqB,GAA0D,KAAK,EACxF,MAAM,EACN,MAAM,EACN,EAAE;IACF,IAAI,CAAC;QACH,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,CAAC,OAAO,CAAC,IAAI,CACjB,4BAA4B,KAAK,CAAC,OAAO,kBAAkB,KAAK,CAAC,YAAY,eAAe,KAAK,CAAC,SAAS,EAAE,CAC9G,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,kBAAkB,GAA0C,KAAK,EACrE,KAAK,EACL,MAAM,EACN,EAAE;IACF,6BAA6B;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;QAAE,OAAO;IAEpC,IAAI,CAAC;QACH,MAAM,WAAW,EAAE,CAAC;IACtB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,YAAY;QAAE,OAAO;IAEpD,MAAM,OAAO,GAAG;QACd,iCAAiC;QACjC,aAAa,KAAK,CAAC,YAAY,EAAE;QACjC,SAAS,KAAK,CAAC,OAAO,EAAE;QACxB,EAAE;QACF,yCAAyC;QACzC,gEAAgE;QAChE,8DAA8D;QAC9D,6DAA6D;QAC7D,iDAAiD;QACjD,EAAE;QACF,0DAA0D;QAC1D,mDAAmD;QACnD,8BAA8B;KAC/B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,MAAM,CAAC,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC;AAC7D,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,MAAM,KAAK,GAAmB,EAAE,CAAC;IAEjC,KAAK,CAAC,oCAAoC,CAAC,GAAG,cAAc,CAC1D,oCAAoC,EACpC,GAAG,EAAE,CAAC,mBAAmB,EACzB,MAAM,CACP,CAAC;IAEF,KAAK,CAAC,iCAAiC,CAAC,GAAG,cAAc,CACvD,iCAAiC,EACjC,GAAG,EAAE,CAAC,qBAAqB,EAC3B,MAAM,CACP,CAAC;IAEF,KAAK,CAAC,iBAAiB,CAAC,GAAG,cAAc,CACvC,iBAAiB,EACjB,GAAG,EAAE,CAAC,kBAAkB,EACxB,MAAM,CACP,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/hooks/permission-auto-reply.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Permission Auto-Reply Hook（v1.3-v2 → v1.3-v3 → v1.3-v4 演进）
+ *
+ * 监听 opencode permission 事件，**无条件 reply `"always"`**（trust opencode
+ * own `always` list 作为单一真相源）。
+ *
+ * v1.3-v4 决策（基于真实 payload 观测）：
+ * - opencode 1.16+ 在推送 `permission.asked` 事件时，**`always` 字段已包含
+ *   opencode 自己判定 "始终放行" 的 pattern 列表**（per user opencode.json 配置）
+ * - plugin 应**直接 reply "always"**，不需做自己的 pattern/cwdRoot check
+ * - 这就是用户 "装好 agent 就能放开权限" 的最简实现：opencode 自己的
+ *   always 列表 = 单一真相源；plugin 不应重复做权限判定
+ * - 如果用户想要 "cwdRoot 外不弹窗" — 应该改 opencode.json#permission，
+ *   不应由 plugin 拦
+ *
+ * 演进历史：
+ * - v1.3-v2：只听 `permission.updated` 事件，事件名错（plugin 收到 0 事件）→ 不工作
+ * - v1.3-v3：根因修复 — 加听 `permission.asked` / `permission.v2.asked` + 解析
+ *   v1/v2 两种 props schema + 改用 v2 client permission reply API
+ * - v1.3-v4：简化 — 删 "patterns 都在 cwdRoot 内" 的硬约束，改 trust
+ *   opencode `always` 列表（v1.3-v3 已收到事件 + 已能 reply，只是多做了
+ *   无意义的 pattern check）
+ *
+ * 事件名与 props schema 矩阵：
+ * | 事件名                  | type 字段       | pattern 字段            | reply API                                          |
+ * |-------------------------|-----------------|-------------------------|----------------------------------------------------|
+ * | `permission.updated`    | `type`          | `pattern` (string\|[])  | v2 `client.permission.reply({requestID, reply})`   |
+ * | `permission.asked`      | `permission`    | `patterns` (string[])   | 同上（v2 事件 v1 props 兼容）                      |
+ * | `permission.v2.asked`   | `permission`    | `patterns` (string[])   | 同上（v2 事件 v2 props）                            |
+ *
+ * 行为细节：
+ * - 仅在 plugin 激活时生效（state.activated）
+ * - v2 client 初始化失败 / 缺失 → 静默让 opencode 走原始 ask（不阻断）
+ * - reply 失败 → 静默让 opencode 走原始 ask
+ * - reply 成功 → opencode 自身把 pattern 加到 "always" 列表（单 session 永久放行）
+ *
+ * 与 RR5（路径守卫）的协同：
+ * - RR5: tool.execute.before 防御 cwdRoot 外 throw（plugin 层 hard stop）
+ * - 本 hook: 对 opencode 弹窗一律 reply "always"（trust opencode 配置）
+ * - 两者无冲突：RR5 拦的是"已经到达 plugin 的危险调用"，本 hook 处理
+ *   "opencode 想弹窗询问 user 之前"的阶段
+ */
+/** v2 client 简化类型（仅本 hook 用到的部分） */
+type V2Client = {
+    permission: {
+        reply: (params: {
+            requestID: string;
+            directory?: string;
+            workspace?: string;
+            reply?: 'once' | 'always' | 'reject';
+            message?: string;
+        }) => Promise<unknown>;
+        respond: (params: {
+            requestID: string;
+            reply?: 'once' | 'always' | 'reject';
+            message?: string;
+        }) => Promise<unknown>;
+    };
+    session: {
+        permission: {
+            reply: (params: {
+                sessionID: string;
+                requestID: string;
+                reply?: 'once' | 'always' | 'reject';
+                message?: string;
+            }) => Promise<unknown>;
+        };
+    };
+};
+export interface PermissionAutoReplyDeps {
+    /** plugin input.serverUrl（URL 对象）— 用于 v2 createOpencodeClient({baseUrl}） */
+    getServerUrl: () => URL | null;
+    /** 工厂注入点：测试可注入 mock createOpencodeClient（避免真实 HTTP） */
+    createV2Client?: (config: {
+        baseUrl: string;
+    }) => V2Client;
+}
+/** Event union 简化版 */
+type EventLike = {
+    type: string;
+    properties?: unknown;
+};
+/**
+ * event hook 处理器
+ * 收到 opencode event，识别 permission 事件并自动 reply
+ */
+export declare function createPermissionAutoReplyHandler(deps: PermissionAutoReplyDeps): (input: {
+    event: EventLike;
+}) => Promise<void>;
+export {};
+//# sourceMappingURL=permission-auto-reply.d.ts.map

package/dist/hooks/permission-auto-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-auto-reply.d.ts","sourceRoot":"","sources":["../../src/hooks/permission-auto-reply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,oCAAoC;AACpC,KAAK,QAAQ,GAAG;IACd,UAAU,EAAE;QACV,KAAK,EAAE,CAAC,MAAM,EAAE;YACd,SAAS,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;YACrC,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,EAAE,CAAC,MAAM,EAAE;YAChB,SAAS,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;YACrC,OAAO,CAAC,EAAE,MAAM,CAAC;SAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxB,CAAC;IACF,OAAO,EAAE;QACP,UAAU,EAAE;YACV,KAAK,EAAE,CAAC,MAAM,EAAE;gBACd,SAAS,EAAE,MAAM,CAAC;gBAClB,SAAS,EAAE,MAAM,CAAC;gBAClB,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;gBACrC,OAAO,CAAC,EAAE,MAAM,CAAC;aAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;SACxB,CAAC;KACH,CAAC;CACH,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,GAAG,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,QAAQ,CAAC;CAC5D;AAqBD,sBAAsB;AACtB,KAAK,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AASxD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,uBAAuB,GAC5B,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAsGhD"}

package/dist/hooks/permission-auto-reply.js

@@ -0,0 +1,158 @@
+/**
+ * Permission Auto-Reply Hook（v1.3-v2 → v1.3-v3 → v1.3-v4 演进）
+ *
+ * 监听 opencode permission 事件，**无条件 reply `"always"`**（trust opencode
+ * own `always` list 作为单一真相源）。
+ *
+ * v1.3-v4 决策（基于真实 payload 观测）：
+ * - opencode 1.16+ 在推送 `permission.asked` 事件时，**`always` 字段已包含
+ *   opencode 自己判定 "始终放行" 的 pattern 列表**（per user opencode.json 配置）
+ * - plugin 应**直接 reply "always"**，不需做自己的 pattern/cwdRoot check
+ * - 这就是用户 "装好 agent 就能放开权限" 的最简实现：opencode 自己的
+ *   always 列表 = 单一真相源；plugin 不应重复做权限判定
+ * - 如果用户想要 "cwdRoot 外不弹窗" — 应该改 opencode.json#permission，
+ *   不应由 plugin 拦
+ *
+ * 演进历史：
+ * - v1.3-v2：只听 `permission.updated` 事件，事件名错（plugin 收到 0 事件）→ 不工作
+ * - v1.3-v3：根因修复 — 加听 `permission.asked` / `permission.v2.asked` + 解析
+ *   v1/v2 两种 props schema + 改用 v2 client permission reply API
+ * - v1.3-v4：简化 — 删 "patterns 都在 cwdRoot 内" 的硬约束，改 trust
+ *   opencode `always` 列表（v1.3-v3 已收到事件 + 已能 reply，只是多做了
+ *   无意义的 pattern check）
+ *
+ * 事件名与 props schema 矩阵：
+ * | 事件名                  | type 字段       | pattern 字段            | reply API                                          |
+ * |-------------------------|-----------------|-------------------------|----------------------------------------------------|
+ * | `permission.updated`    | `type`          | `pattern` (string\|[])  | v2 `client.permission.reply({requestID, reply})`   |
+ * | `permission.asked`      | `permission`    | `patterns` (string[])   | 同上（v2 事件 v1 props 兼容）                      |
+ * | `permission.v2.asked`   | `permission`    | `patterns` (string[])   | 同上（v2 事件 v2 props）                            |
+ *
+ * 行为细节：
+ * - 仅在 plugin 激活时生效（state.activated）
+ * - v2 client 初始化失败 / 缺失 → 静默让 opencode 走原始 ask（不阻断）
+ * - reply 失败 → 静默让 opencode 走原始 ask
+ * - reply 成功 → opencode 自身把 pattern 加到 "always" 列表（单 session 永久放行）
+ *
+ * 与 RR5（路径守卫）的协同：
+ * - RR5: tool.execute.before 防御 cwdRoot 外 throw（plugin 层 hard stop）
+ * - 本 hook: 对 opencode 弹窗一律 reply "always"（trust opencode 配置）
+ * - 两者无冲突：RR5 拦的是"已经到达 plugin 的危险调用"，本 hook 处理
+ *   "opencode 想弹窗询问 user 之前"的阶段
+ */
+import { createOpencodeClient } from '@opencode-ai/sdk/v2';
+import { log } from '../util/log.js';
+import { getState } from '../state.js';
+/** 三种要监听的事件名 */
+const WATCHED_EVENT_TYPES = new Set([
+    'permission.updated', // v1 事件
+    'permission.asked', // v2 事件（v1 兼容）
+    'permission.v2.asked', // v2 事件（v2 风格）
+]);
+/**
+ * event hook 处理器
+ * 收到 opencode event，识别 permission 事件并自动 reply
+ */
+export function createPermissionAutoReplyHandler(deps) {
+    // 缓存 v2 client（lazy 初始化 + 单例）
+    let v2ClientCache = null;
+    let v2ClientInitFailed = false;
+    function getV2Client() {
+        if (v2ClientCache)
+            return v2ClientCache;
+        if (v2ClientInitFailed)
+            return null;
+        const serverUrl = deps.getServerUrl();
+        if (!serverUrl) {
+            log.warn('perm-reply', 'serverUrl unavailable; v2 client not initialized');
+            v2ClientInitFailed = true;
+            return null;
+        }
+        try {
+            const factory = deps.createV2Client ?? ((config) => createOpencodeClient(config));
+            v2ClientCache = factory({ baseUrl: serverUrl.toString() });
+            log.debug('perm-reply', 'v2 client initialized', { baseUrl: serverUrl.toString() });
+            return v2ClientCache;
+        }
+        catch (err) {
+            log.warn('perm-reply', 'v2 client init failed; auto-reply disabled', { err: String(err) });
+            v2ClientInitFailed = true;
+            return null;
+        }
+    }
+    return async (input) => {
+        const event = input.event;
+        if (!event || !WATCHED_EVENT_TYPES.has(event.type))
+            return;
+        const state = getState();
+        if (!state.activated)
+            return;
+        // 解析事件 props（v1 vs v2 两种 schema）
+        const isV2Event = event.type === 'permission.asked' || event.type === 'permission.v2.asked';
+        let toolName;
+        let patterns;
+        let requestId;
+        let alwaysList = [];
+        if (isV2Event) {
+            const props = event.properties;
+            if (!props || !props.id || !props.sessionID) {
+                log.warn('perm-reply', 'v2 event missing id/sessionID', { type: event.type });
+                return;
+            }
+            toolName = props.permission;
+            patterns = props.patterns;
+            requestId = props.id;
+            alwaysList = props.always ?? [];
+        }
+        else {
+            // v1 event
+            const props = event.properties;
+            if (!props || !props.id) {
+                log.warn('perm-reply', 'v1 event missing id', { type: event.type });
+                return;
+            }
+            toolName = props.type;
+            const pattern = props.pattern;
+            patterns = Array.isArray(pattern) ? pattern : pattern ? [pattern] : [];
+            requestId = props.id;
+        }
+        // v1.3-v4 决策（基于 /tmp/serenity-plugin.log 真实 payload）：
+        // opencode 1.16+ 推送 `always: ["*"]` 时 = opencode 自己已知道 "始终放行" 列表匹配
+        // → plugin 应**直接 reply "always"**，不需做 pattern check
+        // 这是用户"装好 agent 就能放开权限"的最简实现：opencode 自己的 always 列表是单一真相源
+        // 如果用户想要"cwdRoot 外不弹窗"——应该让 opencode 的 permission 配置接管（而不是 plugin 拦）
+        log.info('perm-reply', 'replying always (v1.3-v4: trust opencode always list)', {
+            eventType: event.type,
+            tool: toolName,
+            patterns,
+            always: alwaysList,
+            requestID: requestId,
+        });
+        // 用 v2 client reply "always"
+        const client = getV2Client();
+        if (!client)
+            return;
+        try {
+            // v2 SDK 实际 API：client.permission.reply({requestID, reply}) — 无需 sessionID
+            // （v2 Permission class 旧 `respond({sessionID, permissionID, response})` 已 deprecated）
+            await client.permission.reply({
+                requestID: requestId,
+                reply: 'always',
+            });
+            log.info('perm-reply', 'auto-replied always', {
+                eventType: event.type,
+                tool: toolName,
+                patterns,
+                requestID: requestId,
+            });
+        }
+        catch (err) {
+            log.warn('perm-reply', 'reply failed; falling back to opencode ask', {
+                eventType: event.type,
+                requestID: requestId,
+                err: String(err),
+            });
+        }
+    };
+}
+//# sourceMappingURL=permission-auto-reply.js.map

package/dist/hooks/permission-auto-reply.js.map

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

package/dist/hooks/permission-guards.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Permission Guards Hook 工厂
+ *
+ * 包含：tool.execute.before hook
+ * 职责（RR5 + v1.6 补全）：
+ * 1. read / edit / write 工具的 path 字段强制在 cwdRoot 内（RR5 hard block；v1.6 加 edit/write）
+ * 2. symlink 防御（v1.6 扩展 v1-1 msm-schema 的 realpath 逻辑到 tool.execute.before）
+ *
+ * 注意：bash 禁令于 2026-06-08 移除（旧 RR3），改用运行时开关：
+ *   TUI slash command /serenity-bash-on|off|status 控制，通过文件 IPC 通信，
+ *   在 tool.execute.before 中做静默拒绝。默认 bash 启用。
+ *
+ * 设计：v1.6 RR5 补全 = plugin **接管**权限管理（不再依赖 opencode.json 静态 allow）
+ * - 主仓 opencode.json 已复原 read/edit = "ask"（commit fe19b5e）
+ * - LLM 在 cwdRoot 内时：v1.3-v2 auto-reply 仍处理 "ask" 弹窗
+ * - LLM 在 cwdRoot 外时：plugin hard block 早于 opencode 弹窗生效
+ *
+ * L3 验证：单 hook 抛错会中断整条 Effect 链（plugin/index.ts:286-299），
+ * 所以抛错已被 safeHook 包装为 silent（util.ts）
+ */
+import type { Hooks } from '@opencode-ai/plugin';
+import { type HookConfig } from './util.js';
+type ToolArgs = Record<string, unknown>;
+/**
+ * v1.6 字段名提取：
+ * - 显式列表：command, path, filePath, file, cwd（v0.1-3 已有）
+ * - 启发式后缀：*path* / *file* / *dir* / *Path* / *File* / *Dir*（v1.6 加）
+ *   覆盖：targetPath / sourceFilePath / outputDir / newPath / etc.
+ */
+export declare function extractPathsFromArgs(args: ToolArgs): string[];
+/** 工厂：返回 permission guards 相关的 hooks 集合
+ *
+ * v1.6 关键修正：permission-guards **不**走 safeHook。
+ * 原因：safeHook 的"silent 策略"会吞掉 throw，导致 RR5 hard block 失效。
+ * L3 验证：单 hook 抛错中断整条 Effect 链（plugin/index.ts:286-299）——
+ * 这正是 RR5 hard block 想要的行为，所以应当让它**传播**给 opencode。
+ * 其他 hook（compacting / shell-env）保留 safeHook（throw 不应硬中断）。
+ */
+export declare function createPermissionGuards(config?: HookConfig): Partial<Hooks>;
+export {};
+//# sourceMappingURL=permission-guards.d.ts.map

package/dist/hooks/permission-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-guards.d.ts","sourceRoot":"","sources":["../../src/hooks/permission-guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAKjD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI3D,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAuB7D;AAuFD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAO1E"}