dsh-hooks 0.6.0 → 0.8.0

package/README.md

@@ -119,9 +119,21 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | aggregated cache-read tokens, when reported |
 | `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | aggregated cache-write tokens, when reported |
 | `DSH_HOOK_USAGE_REASONING_TOKENS` | aggregated reasoning tokens, when reported |
+| `DSH_HOOK_RUNNING_SUBAGENTS` | live subagents still running under this session (turn/end; `0` = none — lets a hook tell "work handed off to background subagents" apart from "the turn finished for real") |
 | `DSH_HOOK_TIMESTAMP` | ISO timestamp |
 
 - `{{var}}` placeholders inside `run` are substituted from the same context, e.g. `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`.
+- `turn/end` hooks are dispatched after the running-subagent count resolves, i.e. one async hop later than other events — an immediately following event from the same session (e.g. the next `turn/start`) may dispatch first.
+
+A common use for `DSH_HOOK_RUNNING_SUBAGENTS` is suppressing the end-of-turn notification while background subagents are still working and only notifying once a turn settles with nothing left running. Note the parent session emits `turn/end` exactly once (with the count > 0); the "everything settled" signal arrives as `turn/end` on the last child session, whose count is `0`:
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # anchor the regex: bare '0' also matches '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+Settled-but-idle continuable children do not count as running, so they don't keep suppressing the notification.
 
 ## Generic webhook example
 
@@ -189,7 +201,7 @@ CLI/headless environments are unaffected: the browser half loads only in the web
 
 ## Web profile HTTP routes
 
-In the web profile (when the shared webServer service exists) dsh-hooks registers loopback-only `/dsh-hooks/*` routes — CLI/headless environments never see them:
+In the web profile (when the shared webServer service exists) dsh-hooks registers `/dsh-hooks/*` routes, restricted to loopback by default and configurable through the environment variable below — CLI/headless environments never see them:
 
 | Route | Method | Purpose |
 | --- | --- | --- |
@@ -205,7 +217,77 @@ In the web profile (when the shared webServer service exists) dsh-hooks register
 | `/dsh-hooks/feishu/test` | POST | send a test card with the stored credentials |
 | `/dsh-hooks/feishu/disconnect` | POST | disconnect: delete the credential file; `removeHooks: true` also drops the hooks referencing notify-feishu.mjs (with a backup) |
 
-Security matches dsh-aionui-panel: loopback-only, POSTs require `application/json` (blocks cross-site form CSRF). The web profile also gets a systemPrompt section announcing the plugin to agents.
+POSTs require `application/json` in every access mode (blocks cross-site form CSRF). The web profile also gets a systemPrompt section announcing the plugin to agents.
+
+### Configure HTTP source IP access
+
+Set `DSH_HOOKS_ALLOWED_IPS` in the **environment of the process running `dsh web`**. This is not a `cordis.patch.yml` field and does not require changing your hooks configuration.
+
+| Environment variable value | Behavior |
+| --- | --- |
+| Unset, empty, or whitespace-only | Allows only `127.0.0.1`, `::1`, and `::ffff:127.0.0.1`, preserving the default behavior |
+| `*` | Disables source IP filtering |
+| `192.168.1.100,10.0.0.2` | Allows only IPs in the comma-separated list |
+
+Leading and trailing whitespace is removed. `local` and `all` are not special values: anything other than a blank value or a standalone `*` is matched as an IP list. Allowlist mode **does not implicitly allow loopback connections**; include `127.0.0.1,::1` explicitly if you need local access.
+
+Matching ignores surrounding whitespace, letter case, and the `::ffff:` prefix on each address, so `192.168.1.100` matches `::ffff:192.168.1.100`. Hostnames, ports, CIDR ranges, and wildcards within a list are not supported. Invalid entries do not trigger a fallback to loopback-only or unrestricted access. IPv6 matching compares strings after this normalization, without expanding or compressing IPv6 notation; use the representation observed by the server.
+
+#### Direct startup
+
+PowerShell: choose one setting and start the service in the **same terminal**.
+
+```powershell
+# Loopback only (leaving the variable unset also works)
+$env:DSH_HOOKS_ALLOWED_IPS = ''
+
+# Alternatively: allow a client and retain local access
+# $env:DSH_HOOKS_ALLOWED_IPS = '192.168.1.100,127.0.0.1,::1'
+
+# Alternatively: allow any source IP (secure external access first)
+# $env:DSH_HOOKS_ALLOWED_IPS = '*'
+
+dsh web
+```
+
+Linux/macOS shell: choose one of these commands.
+
+```sh
+DSH_HOOKS_ALLOWED_IPS='' dsh web
+DSH_HOOKS_ALLOWED_IPS='192.168.1.100,127.0.0.1,::1' dsh web
+DSH_HOOKS_ALLOWED_IPS='*' dsh web
+```
+
+Restart the corresponding `dsh web` process after changing its terminal or service-manager environment; a running process does not inherit subsequent changes. Writing the variable to `.env` alone does not pass it to the process; your launcher or container configuration must load it explicitly.
+
+#### Docker Compose
+
+Add the variable to `environment` on the **service running DSH**, preserving its existing image, ports, volumes, and other settings. Replace the example service name `dsh` with your actual service name:
+
+```yaml
+services:
+  dsh:
+    environment:
+      DSH_HOOKS_ALLOWED_IPS: "192.168.1.100,127.0.0.1,::1"
+      # Use "" for loopback only or "*" for unrestricted IPs (quote the asterisk).
+```
+
+Recreate the service container to apply the new environment, for example with `docker compose up -d --force-recreate dsh`. Restarting an existing container alone does not update its environment configuration. If using a Compose `.env` file, also reference the variable through the service's `environment` or pass it through `env_file`.
+
+#### Proxies, security, and verification
+
+- The check uses `req.socket.remoteAddress`, ignoring `X-Forwarded-For`, `X-Real-IP`, and `Forwarded`. Behind Docker/NAT/reverse proxies, this may be a gateway or proxy IP instead of the browser machine's IP.
+- Allowlisting a proxy IP allows all clients forwarded by that proxy. A local proxy can also forward external requests as loopback connections. Enforce client restrictions at the proxy. Loopback-only refers to the server's (or container's) loopback connections, not exclusively to browsers on that machine.
+- `*` removes the source IP restriction from sensitive operations including history access, configuration changes, and hook execution. An IP allowlist is not authentication: protect these endpoints with a trusted network or external authentication, and do not expose them directly to untrusted networks.
+- This variable affects only `/dsh-hooks/*`; it does not change listen addresses, ports, firewall rules, or other plugins' permissions.
+
+Request `GET /dsh-hooks/status` from both allowed and denied clients using your actual host and port. Requests passing this plugin's check receive the normal status JSON; requests rejected by this plugin receive HTTP 403:
+
+```json
+{"ok":false,"error":{"code":"forbidden","message":"IP not allowed"}}
+```
+
+If an allowlisted client still receives this error, confirm the variable reached the actual service process, then check whether the server sees the client IP or a proxy/gateway IP. For connection timeouts or refused connections, also check listen addresses, port mappings, and network rules.
 
 ## Feishu notification example
 

package/README.zh.md

@@ -119,9 +119,21 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
 | `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 本回合缓存写 token（有上报时） |
 | `DSH_HOOK_USAGE_REASONING_TOKENS` | 本回合思考 token（有上报时） |
+| `DSH_HOOK_RUNNING_SUBAGENTS` | 本会话下仍在运行的存活子代理数（turn/end；`0` = 无——让 hook 能区分「工作已交给后台子代理」与「回合真正结束」） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
+- `turn/end` 的 hook 在运行中子代理计数解析完成后才派发，比其他事件晚一个异步跳——同会话紧随其后的事件（如下一轮 `turn/start`）可能先执行。
+
+`DSH_HOOK_RUNNING_SUBAGENTS` 的典型用法：后台子代理还在运行时抑制回合结束通知，只在本会话回合真正落定时才通知。注意父会话只会收到一次 `turn/end`（此时计数 > 0）；「全部落定」的信号由最后一个子会话自己的 `turn/end`（计数为 `0`）送达：
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # 正则要锚定：裸 '0' 也会匹配 '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。
 
 ## 执行历史
 
@@ -171,7 +183,7 @@ CLI/headless 环境完全不受影响：浏览器半只在 web 加载，核心
 
 ## Web profile HTTP 路由
 
-web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 loopback-only 的 `/dsh-hooks/*` 路由——CLI/headless 环境完全无感：
+web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 `/dsh-hooks/*` 路由，默认仅允许本地回环地址，可通过下述环境变量调整——CLI/headless 环境完全无感：
 
 | 路由 | 方法 | 用途 |
 | --- | --- | --- |
@@ -187,7 +199,77 @@ web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 loop
 | `/dsh-hooks/feishu/test` | POST | 用已存凭据发送测试卡片 |
 | `/dsh-hooks/feishu/disconnect` | POST | 断开连接：删除凭据文件，`removeHooks: true` 时一并移除 patch 中引用 notify-feishu.mjs 的 hooks（带备份） |
 
-安全约定与 dsh-aionui-panel 一致：仅回环地址可达、POST 必须 `application/json`（防跨站表单 CSRF）。同时 web profile 下会向 agent 注入一段 systemPrompt 公告，说明插件存在与协作方式。
+所有访问模式下，POST 仍必须使用 `application/json`（防跨站表单 CSRF）。同时 web profile 下会向 agent 注入一段 systemPrompt 公告，说明插件存在与协作方式。
+
+### 配置 HTTP 来源 IP 限制
+
+在**运行 `dsh web` 的进程环境**中设置 `DSH_HOOKS_ALLOWED_IPS`。这不是 `cordis.patch.yml` 的配置字段，不需要修改 hooks 配置。
+
+| 环境变量值 | 行为 |
+| --- | --- |
+| 未设置、空字符串或只有空白 | 仅允许 `127.0.0.1`、`::1`、`::ffff:127.0.0.1`，保持默认行为 |
+| `*` | 不限制来源 IP |
+| `192.168.1.100,10.0.0.2` | 只允许逗号分隔列表中的 IP |
+
+变量值首尾空白会被去除。`local`、`all` 不是特殊值；除空值和单独的 `*` 外，其他值都作为 IP 列表匹配。白名单模式**不会额外放行本地连接**，如需保留本地访问，请显式加入 `127.0.0.1,::1`。
+
+匹配时会忽略每项首尾空白、字母大小写及 `::ffff:` 前缀，例如 `192.168.1.100` 可以匹配 `::ffff:192.168.1.100`。不支持域名、端口、CIDR 网段或列表内通配符；无效条目不会自动回退到仅本地或不限制模式。IPv6 采用上述规则处理后的字符串比较，不会统一展开/压缩写法，请使用与服务端所见地址一致的写法。
+
+#### 直接启动
+
+PowerShell：选择一种设置，在**同一终端**启动服务。
+
+```powershell
+# 仅本地（不设置该变量也可以）
+$env:DSH_HOOKS_ALLOWED_IPS = ''
+
+# 或：允许指定客户端，并保留本地访问
+# $env:DSH_HOOKS_ALLOWED_IPS = '192.168.1.100,127.0.0.1,::1'
+
+# 或：不限制来源 IP（请先确保外部访问控制可靠）
+# $env:DSH_HOOKS_ALLOWED_IPS = '*'
+
+dsh web
+```
+
+Linux/macOS shell：以下命令三选一。
+
+```sh
+DSH_HOOKS_ALLOWED_IPS='' dsh web
+DSH_HOOKS_ALLOWED_IPS='192.168.1.100,127.0.0.1,::1' dsh web
+DSH_HOOKS_ALLOWED_IPS='*' dsh web
+```
+
+修改终端或服务管理器中的环境变量后，需要重新启动对应的 `dsh web` 进程；已运行的进程不会自动继承新值。单独把变量写入 `.env` 不代表已经传入进程，需要由启动器或容器配置明确加载。
+
+#### Docker Compose
+
+将变量加入**实际运行 DSH 的服务**的 `environment`，保留原有镜像、端口、卷等配置。以下 `dsh` 为示例服务名，请替换成自己的服务名：
+
+```yaml
+services:
+  dsh:
+    environment:
+      DSH_HOOKS_ALLOWED_IPS: "192.168.1.100,127.0.0.1,::1"
+      # 仅本地用 ""；不限制用 "*"（星号必须加引号）
+```
+
+修改后重新创建该服务的容器以应用新环境变量，例如 `docker compose up -d --force-recreate dsh`；仅重启已有容器不会更新容器环境配置。若使用 Compose 的 `.env` 文件，也需要在服务中通过 `environment` 引用变量或通过 `env_file` 传入。
+
+#### 代理、安全与验证
+
+- 检查的是 `req.socket.remoteAddress`，不读取 `X-Forwarded-For`、`X-Real-IP` 或 `Forwarded`。Docker/NAT/反向代理下，该地址可能是网关或代理 IP，而不是浏览器所在机器的 IP。
+- 放行代理 IP 会放行经该代理转发的所有客户端；本机代理也可能将外部请求转发为回环连接。因此，代理后的客户端限制应在代理层执行。“仅本地”指服务端（或容器内）的回环连接，不等于只允许本机浏览器。
+- `*` 会放开读取历史、修改配置、执行 hook 等敏感接口的来源 IP 限制；IP 白名单不是身份认证，请用可信网络或外部认证保护这些接口，不要直接暴露到不可信网络。
+- 此变量只影响 `/dsh-hooks/*`，不会改变服务监听地址、端口、防火墙规则或其他插件的权限。
+
+可从允许及不允许的客户端分别请求 `GET /dsh-hooks/status`（主机和端口替换为实际地址）。通过本插件的检查时返回正常状态 JSON；被本插件拒绝时返回 HTTP 403：
+
+```json
+{"ok":false,"error":{"code":"forbidden","message":"IP not allowed"}}
+```
+
+若白名单配置后仍收到该错误，先确认变量已传入实际服务进程，再检查服务端看到的是客户端 IP 还是代理/网关 IP。若连接超时或被拒绝连接，则还需检查监听地址、端口映射和网络规则。
 
 ## 通用 webhook 示例
 

package/lib/context.d.ts

@@ -36,6 +36,12 @@ export interface HookContext {
     usageCacheReadTokens?: number;
     usageCacheWriteTokens?: number;
     usageReasoningTokens?: number;
+    /**
+     * Number of live subagents still running under this session at `turn/end`
+     * (0 = none). Always present on `turn/end`; the plugin fills the real count
+     * from the agents/subagents services when they are available.
+     */
+    runningSubagents?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -45,6 +45,8 @@ export function toEnv(ctx) {
         env.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS = String(ctx.usageCacheWriteTokens);
     if (ctx.usageReasoningTokens !== undefined)
         env.DSH_HOOK_USAGE_REASONING_TOKENS = String(ctx.usageReasoningTokens);
+    if (ctx.runningSubagents !== undefined)
+        env.DSH_HOOK_RUNNING_SUBAGENTS = String(ctx.runningSubagents);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/events.js

@@ -185,6 +185,9 @@ export function turnEndContext(session, turn, reason) {
         usageCacheReadTokens: usage?.cacheReadTokens,
         usageCacheWriteTokens: usage?.cacheWriteTokens,
         usageReasoningTokens: usage?.reasoningTokens,
+        // Default until index.ts fills the live count from the agents/subagents
+        // services (0 = no subagent running under this session).
+        runningSubagents: 0,
     };
 }
 export function turnStartContext(session, turn) {

package/lib/index.d.ts

@@ -3,6 +3,42 @@ import './types.js';
 import { Config } from './config.js';
 import { clearTurnTracking } from './events.js';
 export declare const name = "dsh-hooks";
+/** Minimal structural contract of the optional `agents` service. */
+interface AgentsLike {
+    get(id: string): {
+        id: string;
+        status: string;
+    } | undefined;
+    list(): Array<{
+        id: string;
+        status: string;
+    }>;
+    isOwnedBy(id: string, owner: {
+        id: string;
+    }): boolean;
+}
+/** Minimal structural contract of the optional `subagents` service. */
+interface SubagentsLike {
+    listDescendants(rootSessionId: string): Promise<Array<{
+        id?: string;
+    }>>;
+}
+/**
+ * Count live agents still running in one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count — a settled/idle
+ * continuable child no longer suppresses the turn/end notification. Returns 0
+ * when the session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export declare function countRunningSubagents(agents: AgentsLike, subagents: SubagentsLike | undefined, sessionId: string | undefined): Promise<number>;
 export declare const inject: readonly ['sessions'];
 export { Config };
 export { hookMatches, matchFilters } from './events.js';
@@ -15,4 +51,5 @@ export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ho
 export declare function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;
+    countRunningSubagents: typeof countRunningSubagents;
 };

package/lib/index.js

@@ -8,6 +8,54 @@ import { createHistorySink } from './history.js';
 import { createFeishuSetupManager } from './feishu-session.js';
 import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
+/**
+ * Count live agents still running in one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count — a settled/idle
+ * continuable child no longer suppresses the turn/end notification. Returns 0
+ * when the session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export async function countRunningSubagents(agents, subagents, sessionId) {
+    if (sessionId === undefined || agents.get(sessionId) === undefined)
+        return 0;
+    let ids = [];
+    let listed = false;
+    if (subagents !== undefined) {
+        try {
+            ids = (await subagents.listDescendants(sessionId))
+                .map((row) => row.id)
+                .filter((id) => typeof id === 'string' && id !== sessionId);
+            listed = true;
+        }
+        catch {
+            // listing unavailable — fall back to the live-registry child scan below
+        }
+    }
+    if (!listed) {
+        const owner = agents.get(sessionId);
+        if (owner === undefined)
+            return 0;
+        ids = agents
+            .list()
+            .filter((candidate) => candidate !== owner && agents.isOwnedBy(candidate.id, owner))
+            .map((candidate) => candidate.id);
+    }
+    let count = 0;
+    for (const id of ids) {
+        const agent = agents.get(id);
+        if (agent !== undefined && agent.status === 'running')
+            count++;
+    }
+    return count;
+}
 // Dependency on the session service: `session/event` only exists once a
 // SessionStore is composed, and this plugin consumes the durable firehose.
 export const inject = ['sessions'];
@@ -59,6 +107,32 @@ export function apply(ctx, config = {}) {
             console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
         }
     };
+    // turn/end: fill the live running-subagent count before dispatching hooks,
+    // so a hook can tell "work handed off to still-running subagents" apart from
+    // "the turn finished for real". The services are read lazily at event time —
+    // at plugin apply time the agents/subagents rows may not be composed yet.
+    let warnedAgentsUnavailable = false;
+    const matchAfterSubagentCount = async (ctxValue, reasonKind) => {
+        const agents = ctx.get('agents', false);
+        if (agents === undefined) {
+            // Warn once, not on every turn/end: profiles without the agents service
+            // would otherwise spam the log on each turn boundary.
+            if (!warnedAgentsUnavailable) {
+                warnedAgentsUnavailable = true;
+                ctx.logger?.warn?.('[dsh-hooks] agents service unavailable at turn/end — runningSubagents stays 0');
+            }
+        }
+        else {
+            const subagents = ctx.get('subagents', false);
+            try {
+                ctxValue.runningSubagents = await countRunningSubagents(agents, subagents, ctxValue.sessionId);
+            }
+            catch (error) {
+                ctx.logger?.warn?.('[dsh-hooks] failed to count running subagents: %s', String(error));
+            }
+        }
+        runMatching(ctxValue, reasonKind);
+    };
     // Durable session firehose: turn boundaries, steps, tool calls, messages,
     // titles, and approval requests.
     ctx.on('session/event', (session, event) => {
@@ -66,7 +140,16 @@ export function apply(ctx, config = {}) {
         if (classified === undefined)
             return;
         const reasonKind = extractReasonKind(event);
-        runMatching(classified, reasonKind);
+        if (classified.event !== 'turn/end') {
+            runMatching(classified, reasonKind);
+            return;
+        }
+        // Dispatch is deferred past the async count; guard the fire-and-forget
+        // promise so a synchronous throw inside dispatch surfaces as a log line
+        // instead of an unhandled rejection.
+        void matchAfterSubagentCount(classified, reasonKind).catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] turn/end dispatch failed: %s', String(error));
+        });
     });
     // Session lifecycle (published by the session store, not the firehose).
     ctx.on('session/created', (session) => {
@@ -101,6 +184,6 @@ function extractReasonKind(event) {
         return undefined;
     return typeof e.data?.reason?.kind === 'string' ? e.data.reason.kind : undefined;
 }
-// Referenced only for tree-shaking clarity of the module contract; clearTurnTracking
-// is exported for tests that need deterministic duration bookkeeping.
-export const _internals = { clearTurnTracking };
+// Referenced only for tree-shaking clarity of the module contract; exported
+// for tests that need deterministic bookkeeping.
+export const _internals = { clearTurnTracking, countRunningSubagents };

package/lib/server.d.ts

@@ -5,7 +5,7 @@
  * to the profile's cordis.patch.yml with a backup), and the Feishu connect
  * flow (QR setup / cancel / config / test card / disconnect). Registered
  * only when the shared webserver service exists (web profile) — CLI/headless
- * environments never see them. Loopback-only with JSON envelopes; POSTs
+ * environments never see them. Loopback-only by default, with JSON envelopes; POSTs
  * require an explicit application/json content-type (CSRF hardening, same
  * posture as dsh-aionui-panel).
  */
@@ -25,7 +25,7 @@ export interface WebServerLike {
 }
 /** Plugin version, read from package.json (this package ships its own). */
 export declare function pluginVersion(): string;
-/** Loopback fence: never let a LAN client reach /dsh-hooks operations. */
+/** DSH_HOOKS_ALLOWED_IPS: unset/empty = loopback; * = any; otherwise comma-separated IPs. */
 export declare function isLoopbackRequest(req: IncomingMessage): boolean;
 export interface FeishuRouteDeps {
     /** QR-scan session manager (one in-flight flow at a time). */

package/lib/server.js

@@ -22,9 +22,17 @@ function json(res, envelope, status = 200) {
     res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
     res.end(JSON.stringify(envelope));
 }
-/** Loopback fence: never let a LAN client reach /dsh-hooks operations. */
+/** DSH_HOOKS_ALLOWED_IPS: unset/empty = loopback; * = any; otherwise comma-separated IPs. */
 export function isLoopbackRequest(req) {
+    const allowedIps = process.env.DSH_HOOKS_ALLOWED_IPS?.trim() ?? '';
+    if (allowedIps === '*')
+        return true;
+    // Check the direct peer only; never trust forwarded headers.
     const address = req.socket.remoteAddress ?? '';
+    if (allowedIps !== '') {
+        const normalize = (ip) => ip.trim().toLowerCase().replace(/^::ffff:/, '');
+        return address !== '' && allowedIps.split(',').some((ip) => normalize(ip) === normalize(address));
+    }
     return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
 }
 async function readJsonBody(req) {
@@ -78,7 +86,7 @@ export function createHookHandler(options) {
     const resolvePatch = options.resolvePatchFile ?? patchFilePath;
     return async (req, res) => {
         if (!isLoopbackRequest(req)) {
-            json(res, FAIL('forbidden', 'loopback-only'), 403);
+            json(res, FAIL('forbidden', 'IP not allowed'), 403);
             return;
         }
         const url = new URL(req.url ?? '/', 'http://x');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "packageManager": "pnpm@11.21.0",
   "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required. Includes a Hooks section in the Web GUI settings (history timeline + manual tester + notify tests + hook editor + Feishu connect).",
   "author": "PeterBon",
@@ -73,20 +73,20 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@tsdown/css": "^0.22.14",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "tsdown": "^0.22.2",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "dependencies": {
     "@larksuiteoapi/node-sdk": "^1.73.0",