@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/tools/policy.d.ts

@@ -1,20 +1,6 @@
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import type { DecidePolicy } from "./pipeline.js";
 import type { ResolvedTool, ToolPolicy } from "./registry.js";
-/**
- * spec 3.6 R3「有权 ≠ 已确认」固定清单上的工具 key：策略至少为 `ask`，记住的授权也不放行。
- *
- * R3 清单：发布到公共市场、安装连接器、提插件申请、改角色与成员、删除、改共享技能、改自己的指令。
- * M3 的内置工具（`ask_user`、`read_tool_output`、`tool_search`）与连接器工具都不在清单上；M5 T15 加入
- * `skill_write`（改共享技能）。后续实现上述动作的内置工具时把 key 登记在这里。连接器 / 插件工具由
- * `annotations.requiresUserInteraction` 表达同一约束。
- */
-export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
-/**
- * R3 清单里只对共享 agent 生效的 key（窄口子）：R3 的条目是「改共享技能」，私有 agent（`visibility = private`，
- * 只有负责人本人能用）的技能不是共享的，`skill_write` 直接生效、不询问（R4）。其余 R3 条目不论可见性一律固定 ask。
- */
-export declare const R3_SHARED_AGENT_ONLY_TOOL_KEYS: ReadonlySet<string>;
 /** 取更严的策略（`allow < ask < deny`）。 */
 export declare function stricter(a: ToolPolicy, b: ToolPolicy | undefined): ToolPolicy;
 export interface PolicyInput {
@@ -22,22 +8,43 @@ export interface PolicyInput {
     connectorDefault: ToolPolicy;
     /** agent 负责人的收紧（`definition.toolPolicies[key]`）。 */
     agentOverride?: "ask" | "deny";
-    /** R3 清单或 `requiresUserInteraction`。 */
+    /** `requiresUserInteraction`。 */
     fixedAsk: boolean;
     /** 已记住且 specHash 与当前一致的授权。 */
     grant: "session" | "always" | null;
 }
 /**
- * 策略判定（纯函数）：取组织默认、agent 收紧、R3 固定询问三者中最严者；
- * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 R3 / `requiresUserInteraction` 的工具无效。
+ * 策略判定（纯函数）：取组织默认、agent 收紧、固定询问三者中最严者；
+ * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 `requiresUserInteraction` 的工具无效。
  */
 export declare function decide(input: PolicyInput): ToolPolicy;
 /**
- * 是否属于 R3 固定询问（清单或工具声明需要用户交互）。`visibility` 为 agent 当前的可见性：
- * {@link R3_SHARED_AGENT_ONLY_TOOL_KEYS} 里的内置工具在私有 agent 上不算固定询问，
- * 除非 agent 当前版本的 `skills.writePolicy` 为 `ask`（`skillWritePolicy`）；不知道可见性时按共享处理（更严）。
+ * Whether the tool is a fixed ask: its spec declares `requiresUserInteraction`, so its policy is
+ * at least `ask` and remembered grants never let it through.
+ */
+export declare function isFixedAsk(tool: ResolvedTool): boolean;
+/** Which level decided a connector tool's policy ({@link connectorPolicy}). */
+export type ConnectorPolicySource = "org" | "member" | "agent";
+/**
+ * A personal-credential connector tool's policy for one call (maintainer decisions 2026-11-09;
+ * an org-credential connector's tool keeps the org default with the agent's tightening only),
+ * highest first:
+ * 1. the org's default `deny` (a tool the org switched off never gets here: it is unavailable);
+ * 2. the member's own `deny` for calls with their connection (`member`): a floor no agent lifts;
+ * 3. the agent's setting (`agent`, from its tools page): `allow` / `ask` / `deny`;
+ * 4. the member's own `allow` / `ask`;
+ * 5. the org's default (`connector_tools.default_policy`, the annotation default unless an org
+ *    admin changed it: `readOnlyHint: true` allows, anything else asks).
+ * Fixed asks (`requiresUserInteraction`), role escalation and grants apply after this.
  */
-export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" | "org" | "members" | undefined, skillWritePolicy?: "allow" | "ask" | undefined): boolean;
+export declare function connectorPolicy(input: {
+    orgDefault: ToolPolicy;
+    member?: ToolPolicy | undefined;
+    agent?: ToolPolicy | undefined;
+}): {
+    policy: ToolPolicy;
+    source: ConnectorPolicySource;
+};
 /**
  * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
  * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
@@ -47,9 +54,9 @@ export declare function isFixedAsk(tool: ResolvedTool, visibility?: "private" |
  * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
  *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
  *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
- *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   grants are the root conversation's (agent map spec §7); an org agent sub-agent (§5.5): `ctx.agentId` is the
  *   dispatched agent (its current version, its "always" grants) and the parent agent's current
- *   policies apply on top ({@link parentAgentOverride});
+ *   policies apply on top ({@link parentAgentSetting});
  * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
  *   `connector_id` 与工具的来源连接器不一致也无效（删除后用同一 slug 重新安装的连接器不继承旧授权）；
  * - 工具声明了 `requiredRole`（R1）时，发起人在组织中的当前角色：不是成员 → 拒绝；角色不足 → 按角色升级的审批

package/dist/tools/policy.js

@@ -1,29 +1,17 @@
 import { sql } from "kysely";
 import { roleAtLeast } from "../orgs/roles.js";
 import { readOrgSettings } from "../orgs/settings.service.js";
-import { SANDBOX_ASK_TOOL_NAMES } from "./builtins/sandbox/names.js";
-/**
- * spec 3.6 R3「有权 ≠ 已确认」固定清单上的工具 key：策略至少为 `ask`，记住的授权也不放行。
- *
- * R3 清单：发布到公共市场、安装连接器、提插件申请、改角色与成员、删除、改共享技能、改自己的指令。
- * M3 的内置工具（`ask_user`、`read_tool_output`、`tool_search`）与连接器工具都不在清单上；M5 T15 加入
- * `skill_write`（改共享技能）。后续实现上述动作的内置工具时把 key 登记在这里。连接器 / 插件工具由
- * `annotations.requiresUserInteraction` 表达同一约束。
- */
-export const R3_FIXED_ASK_TOOL_KEYS = new Set(["skill_write"]);
-/**
- * R3 清单里只对共享 agent 生效的 key（窄口子）：R3 的条目是「改共享技能」，私有 agent（`visibility = private`，
- * 只有负责人本人能用）的技能不是共享的，`skill_write` 直接生效、不询问（R4）。其余 R3 条目不论可见性一律固定 ask。
- */
-export const R3_SHARED_AGENT_ONLY_TOOL_KEYS = new Set(["skill_write"]);
+import { SANDBOX_ASK_TOOL_NAMES } from "./builtin-names.js";
+import { personalAuth } from "./connector-account-policies.js";
+import { normalizeStoredDefinitionIn } from "./legacy-data.js";
 const RANK = { allow: 0, ask: 1, deny: 2 };
 /** 取更严的策略（`allow < ask < deny`）。 */
 export function stricter(a, b) {
     return b !== undefined && RANK[b] > RANK[a] ? b : a;
 }
 /**
- * 策略判定（纯函数）：取组织默认、agent 收紧、R3 固定询问三者中最严者；
- * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 R3 / `requiresUserInteraction` 的工具无效。
+ * 策略判定（纯函数）：取组织默认、agent 收紧、固定询问三者中最严者；
+ * 记住的授权只能把 `ask` 放行为 `allow`，不能越过 `deny`，对 `requiresUserInteraction` 的工具无效。
  */
 export function decide(input) {
     let p = stricter(input.connectorDefault, input.agentOverride);
@@ -34,20 +22,58 @@ export function decide(input) {
     return p;
 }
 /**
- * 是否属于 R3 固定询问（清单或工具声明需要用户交互）。`visibility` 为 agent 当前的可见性：
- * {@link R3_SHARED_AGENT_ONLY_TOOL_KEYS} 里的内置工具在私有 agent 上不算固定询问，
- * 除非 agent 当前版本的 `skills.writePolicy` 为 `ask`（`skillWritePolicy`）；不知道可见性时按共享处理（更严）。
+ * Whether the tool is a fixed ask: its spec declares `requiresUserInteraction`, so its policy is
+ * at least `ask` and remembered grants never let it through.
+ */
+export function isFixedAsk(tool) {
+    return tool.spec.annotations?.requiresUserInteraction === true;
+}
+const asSetting = (v) => v === "allow" || v === "ask" || v === "deny" ? v : undefined;
+/** The stricter of the settings that are set (none set: undefined). */
+function combine(...xs) {
+    let out;
+    for (const x of xs)
+        if (x !== undefined)
+            out = out === undefined ? x : stricter(out, x);
+    return out;
+}
+/**
+ * An agent's setting for a call: its policy on the tool key and, for a per-call key
+ * (`Platform:<operation>`), on that key, the stricter of the two; undefined when neither is set.
+ * `allow` counts only for a connector tool ({@link connectorPolicy}); elsewhere an agent's policy
+ * can only tighten ({@link tighteningOf}).
  */
-export function isFixedAsk(tool, visibility, skillWritePolicy) {
-    if (tool.spec.annotations?.requiresUserInteraction === true)
-        return true;
-    if (!R3_FIXED_ASK_TOOL_KEYS.has(tool.key))
-        return false;
-    const builtinOnly = tool.source.kind === "builtin" && R3_SHARED_AGENT_ONLY_TOOL_KEYS.has(tool.key);
-    // 私有 agent：缺省 / allow 不问（R4），负责人设为 ask（D10）时与共享 agent 一样固定询问
-    return !(builtinOnly && visibility === "private" && skillWritePolicy !== "ask");
+function settingOf(policies, toolKey, policyKey) {
+    const own = asSetting(policies?.[toolKey]);
+    if (policyKey === toolKey)
+        return own;
+    return combine(own, asSetting(policies?.[policyKey]));
+}
+/** An agent setting as a tightening (`allow` tightens nothing). */
+const tighteningOf = (s) => s === "ask" || s === "deny" ? s : undefined;
+/**
+ * A personal-credential connector tool's policy for one call (maintainer decisions 2026-11-09;
+ * an org-credential connector's tool keeps the org default with the agent's tightening only),
+ * highest first:
+ * 1. the org's default `deny` (a tool the org switched off never gets here: it is unavailable);
+ * 2. the member's own `deny` for calls with their connection (`member`): a floor no agent lifts;
+ * 3. the agent's setting (`agent`, from its tools page): `allow` / `ask` / `deny`;
+ * 4. the member's own `allow` / `ask`;
+ * 5. the org's default (`connector_tools.default_policy`, the annotation default unless an org
+ *    admin changed it: `readOnlyHint: true` allows, anything else asks).
+ * Fixed asks (`requiresUserInteraction`), role escalation and grants apply after this.
+ */
+export function connectorPolicy(input) {
+    if (input.orgDefault === "deny")
+        return { policy: "deny", source: "org" };
+    if (input.member === "deny")
+        return { policy: "deny", source: "member" };
+    if (input.agent !== undefined)
+        return { policy: input.agent, source: "agent" };
+    if (input.member !== undefined)
+        return { policy: input.member, source: "member" };
+    return { policy: input.orgDefault, source: "org" };
 }
-const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
 /**
  * 执行时的策略判定（spec 3.6 R5：在动作执行那一刻判定）。每次调用都实时读取：
  * - 沙箱工具（bash / write / edit / deliver）的组织设置 `sandboxToolPolicy`（为 ask 时组织默认至少 ask）；
@@ -57,9 +83,9 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  * - a sub-agent (template or general-purpose): `agentDef` is its frozen effective definition (the
  *   parent's policies with the template's on top) and `ctx.agentId` is the parent's agent, so the
  *   parent's current version still tightens it (sub-agents spec §5.3, §9); its "this conversation"
- *   grants are the parent conversation's; an org agent sub-agent (§5.5): `ctx.agentId` is the
+ *   grants are the root conversation's (agent map spec §7); an org agent sub-agent (§5.5): `ctx.agentId` is the
  *   dispatched agent (its current version, its "always" grants) and the parent agent's current
- *   policies apply on top ({@link parentAgentOverride});
+ *   policies apply on top ({@link parentAgentSetting});
  * - 授权表（`conversation_tool_grants` / `tool_grants`），`spec_hash` 与当前定义不一致视为无效（D8），
  *   `connector_id` 与工具的来源连接器不一致也无效（删除后用同一 slug 重新安装的连接器不继承旧授权）；
  * - 工具声明了 `requiredRole`（R1）时，发起人在组织中的当前角色：不是成员 → 拒绝；角色不足 → 按角色升级的审批
@@ -69,14 +95,22 @@ const asOverride = (v) => v === "ask" || v === "deny" ? v : undefined;
  */
 export function createDecidePolicy(db) {
     return async (tool, agentDef, ctx) => {
-        let connectorDefault = tool.defaultPolicy;
+        // a per-call policy (Platform tool spec §6.2): its key replaces the tool key for policies,
+        // grants and approvals, and its policy replaces the tool's default
+        const call = ctx.callPolicy ?? null;
+        const policyKey = call?.key ?? tool.key;
+        let connectorDefault = call?.policy ?? tool.defaultPolicy;
         let connectorId = null;
         let hashCurrent = true;
+        /** The member's own setting for a call with their connection (a personal-credential connector). */
+        let memberSetting;
+        /** A personal-credential connector: calls use the acting account's own connection. */
+        let personal = false;
         if (tool.source.kind === "connector") {
             connectorId = tool.source.connectorId;
             const app = await db
                 .selectFrom("connectors")
-                .select(["slug", "status", "deleted_at"])
+                .select(["slug", "status", "deleted_at", "auth"])
                 .where("id", "=", tool.source.connectorId)
                 .where("org_id", "=", ctx.orgId)
                 .executeTakeFirst();
@@ -102,6 +136,19 @@ export function createDecidePolicy(db) {
                 return { unavailable: "Tool is pending review" };
             connectorDefault = row.default_policy;
             hashCurrent = row.spec_hash === tool.specHash;
+            // The call is made with the acting account's own connection (the credential the pipeline
+            // injects for `ctx.accountId`): that account's settings apply, never another's
+            personal = personalAuth(app.auth);
+            if (personal) {
+                const mine = await db
+                    .selectFrom("connector_tool_account_policies")
+                    .select("policy")
+                    .where("connector_id", "=", tool.source.connectorId)
+                    .where("account_id", "=", ctx.accountId)
+                    .where("tool_name", "=", tool.source.name)
+                    .executeTakeFirst();
+                memberSetting = mine?.policy;
+            }
         }
         // 沙箱工具的组织默认（M5 T8）：组织设置 sandboxToolPolicy 为 ask 时，有副作用的沙箱工具至少 ask
         // `orgAsk`: the org setting, not the tool's own default, is what makes it ask
@@ -113,22 +160,47 @@ export function createDecidePolicy(db) {
             }
         }
         // 运行所用版本可能是加 toolPolicies 字段之前保存的：缺省为空
-        const runOverride = asOverride(agentDef.toolPolicies?.[tool.key]);
+        const runSetting = settingOf(agentDef.toolPolicies, tool.key, policyKey);
         const current = await db
             .selectFrom("agents")
             .innerJoin("agent_versions", (j) => j
             .onRef("agent_versions.agent_id", "=", "agents.id")
             .onRef("agent_versions.version", "=", "agents.current_version"))
-            .select(["agent_versions.definition", "agents.visibility"])
+            .select(["agent_versions.definition"])
             .where("agents.id", "=", ctx.agentId)
             .executeTakeFirst();
-        const currentPolicies = current?.definition?.toolPolicies;
-        const currentOverride = asOverride(currentPolicies?.[tool.key]);
-        let strictest = stricter(runOverride ?? "allow", currentOverride);
+        // stored raw: an rc version's keys read as current keys, so its deny keeps applying (§8.3)
+        const currentDef = current === undefined
+            ? undefined
+            : await normalizeStoredDefinitionIn(db, ctx.orgId, current.definition);
+        const currentPolicies = currentDef?.toolPolicies;
+        const currentSetting = settingOf(currentPolicies, tool.key, policyKey);
+        // the run's version, the agent's current version and (a sub-agent) its parent agent's
+        // current version: the stricter of the ones that are set
+        // (an `allow` the owner removed since the run started no longer applies: removing it tightens)
+        const runKept = runSetting === "allow" && current !== undefined && currentSetting === undefined
+            ? undefined
+            : runSetting;
+        let agentSetting = combine(runKept, currentSetting);
         if (ctx.parentConversationId !== undefined && ctx.parentAgentDiffers !== false) {
-            strictest = stricter(strictest, await parentAgentOverride(db, tool.key, ctx));
+            agentSetting = combine(agentSetting, await parentAgentSetting(db, tool.key, policyKey, ctx));
+        }
+        let agentOverride = tighteningOf(agentSetting);
+        // A personal-credential connector's tool: the levels of `connectorPolicy` decide its base
+        // policy (an agent's `allow` counts here, below the org's and the member's deny). A connector
+        // with one org credential has no member level and its calls act as the whole org: there the
+        // agent's setting only tightens the org default, as for every other tool (review 2026-11-09)
+        let decidedBy = null;
+        if (tool.source.kind === "connector" && personal) {
+            const r = connectorPolicy({
+                orgDefault: connectorDefault,
+                member: memberSetting,
+                agent: agentSetting,
+            });
+            connectorDefault = r.policy;
+            decidedBy = r.source;
+            agentOverride = undefined;
         }
-        const agentOverride = strictest === "allow" ? undefined : strictest;
         let escalateTo = null;
         if (tool.requiredRole !== undefined) {
             const m = await db
@@ -142,10 +214,10 @@ export function createDecidePolicy(db) {
             if (!roleAtLeast(m.role, tool.requiredRole))
                 escalateTo = tool.requiredRole;
         }
-        // 可见性实时读（R5）：共享 agent 的 skill_write 固定 ask，私有 agent 不问（见 R3_SHARED_AGENT_ONLY_TOOL_KEYS）
-        // 当前版本的 skills.writePolicy 同样实时读（R5）：运行中改为 ask，下一次调用即生效；固定 ask 时授权不放行
-        const writePolicy = current?.definition?.skills?.writePolicy;
-        const fixedAsk = isFixedAsk(tool, current?.visibility, writePolicy);
+        // `remember: false` on a call that is not a plain allow (an org / platform operation, or a read
+        // an agent tightened to ask): every call asks, grants never apply. A read (`allow`) never asks.
+        const fixedAsk = isFixedAsk(tool) ||
+            (call !== null && !call.remember && (call.policy !== "allow" || agentOverride !== undefined));
         const input = {
             connectorDefault,
             ...(agentOverride !== undefined && { agentOverride }),
@@ -156,7 +228,7 @@ export function createDecidePolicy(db) {
         if (pre === "deny")
             return "deny";
         if (pre === "ask" && !fixedAsk && escalateTo === null && hashCurrent) {
-            input.grant = await findGrant(db, tool, connectorId, ctx);
+            input.grant = await findGrant(db, tool, policyKey, connectorId, ctx);
         }
         const result = decide(input);
         if (result === "allow" && escalateTo === null) {
@@ -164,25 +236,27 @@ export function createDecidePolicy(db) {
             return pre === "ask" && input.grant !== null ? { grant: input.grant } : "allow";
         }
         const ask = {
-            toolKey: tool.key,
+            toolKey: policyKey,
             specHash: tool.specHash,
             connectorId,
             requestedFor: escalateTo === null ? ctx.accountId : null,
             approverRole: escalateTo,
             // the most specific rule that asked: role escalation, the agent's tightening, the connector,
-            // a fixed ask (R3, requiresUserInteraction), the org's sandboxToolPolicy, else the tool's own
+            // a fixed ask (requiresUserInteraction), the org's sandboxToolPolicy, else the tool's own
             // default
             policy: escalateTo !== null
                 ? "role"
-                : agentOverride === "ask"
+                : agentOverride === "ask" || (decidedBy === "agent" && connectorDefault === "ask")
                     ? "agent"
-                    : tool.source.kind === "connector" && connectorDefault === "ask"
-                        ? "connector"
-                        : fixedAsk
-                            ? "fixed"
-                            : orgAsk
-                                ? "org"
-                                : "default",
+                    : decidedBy === "member" && connectorDefault === "ask"
+                        ? "member"
+                        : tool.source.kind === "connector" && connectorDefault === "ask"
+                            ? "connector"
+                            : fixedAsk
+                                ? "fixed"
+                                : orgAsk
+                                    ? "org"
+                                    : "default",
         };
         return { ask };
     };
@@ -193,7 +267,7 @@ export function createDecidePolicy(db) {
  * policy for the same key applies on top, so the parent's owner can tighten a running child too.
  * For a template or general-purpose child the parent conversation has the same agent, already read.
  */
-async function parentAgentOverride(db, toolKey, ctx) {
+async function parentAgentSetting(db, toolKey, policyKey, ctx) {
     const row = await db
         .selectFrom("conversations as c")
         .innerJoin("agents as a", "a.id", "c.agent_id")
@@ -203,22 +277,26 @@ async function parentAgentOverride(db, toolKey, ctx) {
         .executeTakeFirst();
     if (!row || row.id === ctx.agentId)
         return undefined;
-    const policies = row.definition.toolPolicies;
-    return asOverride(policies?.[toolKey]);
+    // stored raw: an rc version's keys read as current keys, so its deny keeps applying (§8.3)
+    const policies = (await normalizeStoredDefinitionIn(db, ctx.orgId, row.definition))
+        .toolPolicies;
+    return settingOf(policies, toolKey, policyKey);
 }
 /**
- * A grant matching the current definition hash and source connector: this conversation's first,
+ * A grant matching the current definition hash and source connector, keyed by the call's policy key
+ * (the tool key, or a per-call key such as `Platform:<operation>`): this conversation's first,
  * then "always". `connectorId` is the tool's source connector (null for plugin and builtin tools,
  * which match only grants without a connector). A sub-agent's "this conversation" grants live on
- * its parent conversation (sub-agents spec §9), so parallel children are approved once.
+ * the root conversation of its tree (agent map spec §7), so the root and every sub-agent at any
+ * depth are approved once.
  */
-async function findGrant(db, tool, connectorId, ctx) {
+async function findGrant(db, tool, policyKey, connectorId, ctx) {
     const sameConnector = sql `connector_id IS NOT DISTINCT FROM ${connectorId}`;
     const session = await db
         .selectFrom("conversation_tool_grants")
         .select("spec_hash")
-        .where("conversation_id", "=", ctx.parentConversationId ?? ctx.conversationId)
-        .where("tool_key", "=", tool.key)
+        .where("conversation_id", "=", ctx.rootConversationId ?? ctx.conversationId)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     if (session?.spec_hash === tool.specHash)
@@ -229,7 +307,7 @@ async function findGrant(db, tool, connectorId, ctx) {
         .where("org_id", "=", ctx.orgId)
         .where("account_id", "=", ctx.accountId)
         .where("agent_id", "=", ctx.agentId)
-        .where("tool_key", "=", tool.key)
+        .where("tool_key", "=", policyKey)
         .where(sameConnector)
         .executeTakeFirst();
     return always?.spec_hash === tool.specHash ? "always" : null;

package/dist/tools/questions.controller.d.ts

@@ -7,7 +7,7 @@ declare const AnswerBody: z.ZodObject<{
     answer: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strict>;
 /**
- * 输入请求（`ask_user`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
+ * 输入请求（`AskUserQuestion`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
  * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
  * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
  */

package/dist/tools/questions.controller.js

@@ -19,7 +19,7 @@ const AnswerBody = z.object({ answer: z.record(z.string().max(200), z.unknown())
 class QuestionAnswerBody extends createZodDto(AnswerBody, "QuestionAnswerBody") {
 }
 /**
- * 输入请求（`ask_user`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
+ * 输入请求（`AskUserQuestion`、插件工具的 `input_required`）：`/api/v1/orgs/:orgId/questions`。
  * 动作用 `approvals.decide`（访客起、仅限用户主体）：回答必须由人做出，agent / 服务令牌不能代答；
  * 具体是否允许由服务判定——只有该运行的发起人能读取与回答，其他成员 403。
  */

package/dist/tools/questions.service.d.ts

@@ -4,8 +4,8 @@ import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
-export type QuestionStatus = "pending" | "answered" | "expired" | "cancelled";
-/** 一条输入请求（`ask_user`、插件工具的 `input_required`、MCP elicitation 共用）。 */
+export type QuestionStatus = "pending" | "answered" | "skipped" | "expired" | "cancelled";
+/** 一条输入请求（`AskUserQuestion`、插件工具的 `input_required`、MCP elicitation 共用）。 */
 export interface QuestionRecord {
     id: string;
     orgId: string;
@@ -75,6 +75,13 @@ export declare class QuestionsService {
      * 传 `orgId` 时还要求输入请求属于该组织（HTTP 接口用）。
      */
     answer(questionId: string, accountId: string, answer: unknown, orgId?: string): Promise<QuestionRecord>;
+    /**
+     * Locks the conversation row of question `questionId` (`SELECT … FOR UPDATE`; re-entrant with the
+     * lock `EventLog.appendIn` takes later). Every write to a question row takes the conversation lock
+     * first, then the question row (reply-while-question spec §8.2, D7), as the message's skip and
+     * the stop of a waiting run do, so no two of them can deadlock. False: no such question (in `orgId`).
+     */
+    private lockConversationOf;
     private answerIn;
     /**
      * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `question_answered{expired}`。
@@ -99,6 +106,20 @@ export declare class QuestionsService {
         records: QuestionRecord[];
         seqs: Map<string, number>;
     }>;
+    /**
+     * Skips, in the caller's transaction (`mandatory`, the message's), every question a message by
+     * `accountId` just written at `messageSeq` closes (reply-while-question spec §4.2, §8.1): pending,
+     * not yet due, asked in `conversationId` (a sub-agent's question lives in the child conversation)
+     * by a run of it that is `running` or `waiting` and was started by `accountId`. The caller holds
+     * the conversation row lock (its `appendIn`), so only questions logged before the message are
+     * seen. Each becomes `skipped` with `question_answered { outcome: "skipped", skippedBySeq }`.
+     * Returns the records and the highest seq written (null: none); the caller notifies and emits
+     * `question.answered` after the commit.
+     */
+    skipPendingIn(conversationId: string, accountId: string, messageSeq: number): Promise<{
+        records: QuestionRecord[];
+        toSeq: number | null;
+    }>;
     /** `question_answered` in the current transaction; returns its seq. */
     private answeredEvent;
 }

package/dist/tools/questions.service.js

@@ -169,13 +169,38 @@ let QuestionsService = class QuestionsService {
             orgId: record.orgId,
             conversationId: record.conversationId,
             runId: record.runId,
+            outcome: "answered",
         });
         return record;
     }
+    /**
+     * Locks the conversation row of question `questionId` (`SELECT … FOR UPDATE`; re-entrant with the
+     * lock `EventLog.appendIn` takes later). Every write to a question row takes the conversation lock
+     * first, then the question row (reply-while-question spec §8.2, D7), as the message's skip and
+     * the stop of a waiting run do, so no two of them can deadlock. False: no such question (in `orgId`).
+     */
+    async lockConversationOf(questionId, orgId) {
+        const t = this.db.db;
+        let q = t.selectFrom("questions").select("conversation_id").where("id", "=", questionId);
+        if (orgId !== undefined)
+            q = q.where("org_id", "=", orgId);
+        const row = await q.executeTakeFirst();
+        if (!row)
+            return false;
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", row.conversation_id)
+            .forUpdate()
+            .executeTakeFirst();
+        return true;
+    }
     // its own transaction (as the legacy one was): `question.answered` is emitted only after the
     // answer committed, even when a caller has a transaction open
     async answerIn(questionId, accountId, answer, orgId) {
         const t = this.db.db;
+        if (!(await this.lockConversationOf(questionId, orgId)))
+            throw notFound();
         let q = t
             .selectFrom("questions")
             .selectAll()
@@ -194,6 +219,9 @@ let QuestionsService = class QuestionsService {
         if (run?.trigger_account_id !== accountId)
             throw notInitiator();
         const before = toRecord(locked);
+        if (before.status === "skipped") {
+            throw new ApiError("question.already_answered", "Question was skipped: the user sent a message instead");
+        }
         if (before.status !== "pending") {
             throw new ApiError("question.already_answered", "Question has already been answered");
         }
@@ -233,6 +261,8 @@ let QuestionsService = class QuestionsService {
     }
     async expireIn(questionId) {
         const t = this.db.db;
+        if (!(await this.lockConversationOf(questionId)))
+            return { outcome: "settled" };
         const locked = await t
             .selectFrom("questions")
             .selectAll()
@@ -291,10 +321,33 @@ let QuestionsService = class QuestionsService {
      */
     async cancelPendingFor(orgId, accountId) {
         const t = this.db.db;
+        // the conversations first, in id order (lock order D7: conversation, then question rows)
+        const convs = await t
+            .selectFrom("questions")
+            .select("conversation_id")
+            .distinct()
+            .where("org_id", "=", orgId)
+            .where("status", "=", "pending")
+            .where("run_id", "in", (eb) => eb.selectFrom("runs").select("id").where("trigger_account_id", "=", accountId))
+            .execute();
+        if (convs.length > 0) {
+            await t
+                .selectFrom("conversations")
+                .select("id")
+                .where("id", "in", convs.map((c) => c.conversation_id))
+                .orderBy("id")
+                .forUpdate()
+                .execute();
+        }
+        // only the conversations locked above: a question asked meanwhile in another one waits for
+        // the run's stop (offboarding aborts it) or the sweep, so no conversation is locked after a row
+        if (convs.length === 0)
+            return { records: [], seqs: new Map() };
         const rows = await t
             .selectFrom("questions")
             .selectAll()
             .where("org_id", "=", orgId)
+            .where("conversation_id", "in", convs.map((c) => c.conversation_id))
             .where("status", "=", "pending")
             .where("run_id", "in", (eb) => eb.selectFrom("runs").select("id").where("trigger_account_id", "=", accountId))
             .orderBy("created_at")
@@ -315,14 +368,60 @@ let QuestionsService = class QuestionsService {
         }
         return { records, seqs };
     }
+    /**
+     * Skips, in the caller's transaction (`mandatory`, the message's), every question a message by
+     * `accountId` just written at `messageSeq` closes (reply-while-question spec §4.2, §8.1): pending,
+     * not yet due, asked in `conversationId` (a sub-agent's question lives in the child conversation)
+     * by a run of it that is `running` or `waiting` and was started by `accountId`. The caller holds
+     * the conversation row lock (its `appendIn`), so only questions logged before the message are
+     * seen. Each becomes `skipped` with `question_answered { outcome: "skipped", skippedBySeq }`.
+     * Returns the records and the highest seq written (null: none); the caller notifies and emits
+     * `question.answered` after the commit.
+     */
+    async skipPendingIn(conversationId, accountId, messageSeq) {
+        const t = this.db.db;
+        const rows = await t
+            .selectFrom("questions as q")
+            .innerJoin("runs as r", "r.id", "q.run_id")
+            .selectAll("q")
+            .where("q.conversation_id", "=", conversationId)
+            .where("q.status", "=", "pending")
+            .where(sql `q.expires_at > now()`)
+            .where("r.status", "in", ["running", "waiting"])
+            .where("r.trigger_account_id", "=", accountId)
+            .orderBy("q.created_at")
+            .orderBy("q.id")
+            .forUpdate("q")
+            .execute();
+        const records = [];
+        let toSeq = null;
+        for (const row of rows) {
+            const updated = await t
+                .updateTable("questions")
+                .set({ status: "skipped", answered_by: accountId, answered_at: sql `now()` })
+                .where("id", "=", row.id)
+                .returningAll()
+                .executeTakeFirstOrThrow();
+            toSeq = await this.answeredEvent(toRecord(row), null, accountId, "skipped", messageSeq);
+            records.push(toRecord(updated));
+        }
+        return { records, toSeq };
+    }
     /** `question_answered` in the current transaction; returns its seq. */
-    async answeredEvent(q, answer, byAccountId, outcome) {
+    async answeredEvent(q, answer, byAccountId, outcome, skippedBySeq) {
         const written = await this.eventLog.appendIn(q.conversationId, [
             {
                 type: "question_answered",
                 runId: q.runId,
                 idemKey: `question_answered:${q.id}`,
-                payload: { questionId: q.id, callId: q.callId, answer, byAccountId, outcome },
+                payload: {
+                    questionId: q.id,
+                    callId: q.callId,
+                    answer,
+                    byAccountId,
+                    outcome,
+                    ...(skippedBySeq !== undefined && { skippedBySeq }),
+                },
             },
         ]);
         return Math.max(...written.map((e) => e.seq));
@@ -343,6 +442,9 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], QuestionsService.prototype, "cancelPendingFor", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], QuestionsService.prototype, "skipPendingIn", null);
 QuestionsService = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),