@qilin-agent/user-approval 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,88 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/interaction/user-approval/README.md
+/:
+  en: 515e991a5671711d
+  zh: 194d48a8da9b51b0
+/qilin-agent-user-approval:
+  en: e82b16eb4321d7b6
+  zh: 662bf61284ab31a8
+/qilin-agent-user-approval/summary:
+  en: 9b438f002e664c9e
+  zh: 1f1adf3db6a56ddc
+/qilin-agent-user-approval/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-user-approval/use-this-package:
+  en: dd034141bc1a7634
+  zh: a44f1f90dac2a444
+/qilin-agent-user-approval/use-this-package/composing-answerers:
+  en: 3618ddc3386e65f0
+  zh: d6c0ac91aae122bb
+/qilin-agent-user-approval/use-this-package/setting-the-policy:
+  en: 3e70aa2dad4aab95
+  zh: dc2b44b6d2f2459e
+/qilin-agent-user-approval/use-this-package/requesting-a-decision:
+  en: add08f0d0dace4c8
+  zh: e45268e0f0ed2e95
+/qilin-agent-user-approval/use-this-package/what-the-model-and-user-see:
+  en: 016bf3cd1891d3d7
+  zh: 33e7e5ffaf95f5e7
+/qilin-agent-user-approval/understand-the-implementation:
+  en: d07be7ba08baf010
+  zh: 665e68e9188e5d60
+/qilin-agent-user-approval/understand-the-implementation/source-map:
+  en: ac27642b3a91082f
+  zh: 769a56eaad4218f7
+/qilin-agent-user-approval/understand-the-implementation/dispatch:
+  en: 38c3646e45d3dddd
+  zh: 3363dde8c786d6b2
+/qilin-agent-user-approval/understand-the-implementation/policy-and-the-runtime-context-snapshot:
+  en: a8df8823aa0b015d
+  zh: ed0906f11645e7fd
+/qilin-agent-user-approval/understand-the-implementation/audit:
+  en: 145530678bac5912
+  zh: a464effa3a29fce0
+/qilin-agent-user-approval/further-exploration:
+  en: f605b73345732588
+  zh: ac9a76e77dbed4a7
+/qilin-agent-user-approval/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-user-approval/model-experience/current-approval-policy-context:
+  en: d23980f003b42fbb
+  zh: 532f0174de5d87b5
+/qilin-agent-user-approval/model-experience/current-approval-policy-context/what-the-model-sees:
+  en: a38775858ccd61f3
+  zh: c19c76827be7aabf
+/qilin-agent-user-approval/model-experience/current-approval-policy-context/what-the-model-sees/ask-policy-contribution:
+  en: b9f1262c97ec7568
+  zh: 8a6613695f896f70
+/qilin-agent-user-approval/model-experience/current-approval-policy-context/what-the-model-sees/never-policy-contribution:
+  en: f13f09fc2466513b
+  zh: 4a755a682551c481
+/qilin-agent-user-approval/model-experience/current-approval-policy-context/token-effect:
+  en: e96807422bdce44d
+  zh: 9fdcfafcc96bd004
+/qilin-agent-user-approval/model-experience/current-approval-policy-context/kv-cache-effect:
+  en: b4bac06588fdd1c3
+  zh: 60271562fdd52f72
+/qilin-agent-user-approval/model-experience/tool-outcome:
+  en: 54c140b4a1b4a5bc
+  zh: 8573891441963be4
+/qilin-agent-user-approval/model-experience/tool-outcome/what-the-model-sees:
+  en: fd0c40c0a6b4c967
+  zh: c7e18063e11080e9
+/qilin-agent-user-approval/model-experience/tool-outcome/token-effect:
+  en: 972a63ca590fecde
+  zh: 217b63d98365dbdb
+/qilin-agent-user-approval/model-experience/tool-outcome/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: 4db81881ebdcfcc4
+/qilin-agent-user-approval/known-limitations-and-deferred-work:
+  en: c6928515ff91ee7e
+  zh: c23bd844b4907f12
+/qilin-agent-user-approval/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+---
+description: "Channel-neutral one-shot approval seam for users and maintainers composing answerers, setting policy, or debugging fail-closed permission decisions."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/user-approval
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this package to require a one-shot decision before a sensitive tool action proceeds. The `ask` policy sends each request to the deployment's human or machine answerers; `never` rejects it without prompting. Missing or failed answerers return `unavailable`, so the action fails closed, and an approval applies only to that request. Every request and outcome is recorded in the requesting session's audit log. The model sees the resulting tool outcome and current policy, but not the human permission UI or audit events.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Compose this service when sensitive tool actions should pause for a human or machine decision instead of running unconditionally. The tools pipeline and the sandboxed bash tool route their `ask` decisions through this seam and fail closed when it is absent, so interactive deployments mount it with at least one answerer.
+
+### Composing answerers
+
+Answerers are `approval/request` waterfall listeners: return an outcome to answer for an owned agent, or call `next()` to delegate. Agent-scoped listeners receive only that agent's requests, and a deployment composes one terminal answerer — sibling listener order is not a policy-priority mechanism. Without a terminal answerer, requests resolve `unavailable` and fail closed; the service itself never prompts a human.
+
+### Setting the policy
+
+The effective policy is the one set for the session, falling back to the configured default. `ask` (the default) delegates to the composed answerers; `never` rejects every request deterministically before interactive dispatch — the strict headless stance for CI and unattended runs.
+
+```yaml
+- name: '@qilin-agent/user-approval'
+  config:
+    policy: ask
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `policy` | `ask` | Default for sessions without an `approval/policy` override |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agentuser-approval) is the exhaustive source for every accepted field and its JSDoc. `setPolicy(agent, policy)` switches a live agent and queues a "changed by the user" message for its next model step; `setApprovalPolicy(session, policy)` is the direct durable write path used by session initialization.
+
+### Requesting a decision
+
+`request(req)` names the agent, tool, optional call id and reason, and an abort signal. It requires an open turn: an idle or between-turn caller throws before auditing anything. Aborting withdraws the question — the request settles `cancelled` and a late answer is discarded. A failure that prevents either audit append from committing rejects instead of returning an unlogged decision.
+
+### What the model and user see
+
+The model sees only the asking consumer's eventual tool outcome — allowed, rejected, cancelled, or unavailable — plus the current policy in the runtime-context snapshot; the audit events and the human permission UI are not model context. A `never` switch is announced to the model by a sourced user message, and both policies contribute their complete current meaning to the snapshot.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The observable behavior is covered in [Use this package](#use-this-package); this section explains dispatch, policy enforcement, and the audit path.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `ApprovalService`: request dispatch, policy fold and write path, runtime-context contribution |
+| [`src/types.ts`](src/types.ts) | `ApprovalRequestId` brand and outcome types |
+
+### Dispatch
+
+`decide()` races the answerer waterfall against the request signal and contains every answerer failure: a throwing listener fails the question closed to `unavailable`, and a rogue non-vocabulary return is normalized to `unavailable`. The `never` policy is enforced inside the service before waterfall dispatch, so a listener registered later with `prepend` cannot bypass the deterministic rejection. The request must be turn-enclosed because the turn is the durable log's commit/replay boundary — a bare event between turns is indistinguishable from a crash tail.
+
+### Policy and the runtime-context snapshot
+
+The system-prompt contribution `approval:policy` states the complete current meaning of the effective policy — `ask` with its fail-closed consequence, or `never` with its non-escalation consequence — after retained history, so switching policy appends a new full snapshot instead of rewriting the stable request header. `setPolicy()` also injects a sourced user message announcing the change for the next step.
+
+### Audit
+
+`request()` appends `approval/asked` with the request identity and tool, then `approval/decided` with the closed outcome; the exact appended fields live in [`src/index.ts`](src/index.ts). Both are log-only.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the approval vocabulary to the consumers and the design rationale.
+
+- [Approval subsystem reference](../../../docs/subsystems/approval.md) — the shared request/outcome vocabulary and the `ctx.approval` Cordis surface.
+- [Approval seam Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-approval-seam.md) — design rationale for the seam.
+- [Sandbox Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) — how the sandboxed bash tool consumes approvals for escalated retries.
+- [Interaction group map](../README.md) — adjacent permission preset and question packages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Current approval policy context
+
+#### What the model sees
+
+The first request and each effective policy change append a full runtime-context snapshot after retained history. Under `ask`, the approval contribution states that configured answerers may be consulted and absence fails closed. Under `never`, it states the deterministic rejection and non-escalation consequence. Unchanged requests retain the earlier snapshot without adding another message.
+
+##### Ask-policy contribution
+
+```markdown
+Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.
+```
+
+##### Never-policy contribution
+
+```markdown
+Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
+```
+
+#### Token effect
+
+One concise context message on the first request and on an effective change; unchanged requests add no duplicate policy tokens.
+
+#### KV Cache effect
+
+Append-only after retained history. An `ask`/`never` switch preserves the stable system and conversation prefix instead of rewriting the first wire message.
+
+### Tool outcome
+
+#### What the model sees
+
+`approval/asked` and `approval/decided` are log-only. The model sees only the asking consumer's eventual allowed, rejected, cancelled, or unavailable tool outcome; the human permission UI is not context.
+
+#### Token effect
+
+Zero duplicate audit tokens. A rejection may replace a normal tool result with a small retained error, while an allowance leaves the consumer's ordinary result.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the seam is a poor fit or needs special composition care. They are current package constraints, not a general permission comparison.
+
+- **Requests are valid only inside an open turn** — an idle or between-turn caller throws before auditing; a durable out-of-turn approval workflow is deferred.
+- **Only one-shot grants exist** — the outcome vocabulary has `allowed-once` but no `allow-always`, remembered rule, revocation, or grant store; session policy is only `ask` / `never`.
+- **The request carries no tool arguments** — an answerer sees the tool name, reason, and optional call id; the ACP machine channel requires a call id and delegates requests without one.
+- **No built-in answerer** — headless or incompletely composed deployments resolve `unavailable` and fail closed; the service itself never prompts a human.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,166 @@
+---
+description: "与通道无关的一次性审批 seam；供组合应答者、设置策略或排查以拒绝方式关闭的权限决定的用户与维护者阅读。"
+kind: "package-reference"
+---
+
+# @qilin-agent/user-approval
+
+[English](README.md) | 中文
+
+## 概述
+
+使用本包可要求敏感工具操作在继续前取得一次性决定。`ask` 策略将每个请求发送给部署中的人类或机器应答者；`never` 则直接拒绝，不发出提示。应答者缺失或失败时返回 `unavailable`，使操作以拒绝方式关闭；每项批准也只适用于对应请求。每个请求与结果都会记录在发起请求的会话审计日志中。模型会看到最终工具结果与当前策略，但不会看到人类权限 UI 或审计事件。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当敏感工具操作应当暂停等待人或机器的决定、而非无条件执行时，组合此服务。工具流水线与沙箱 bash 工具会通过此 seam 路由 `ask` 决定，并在该 seam 缺失时以拒绝方式关闭，因此交互式部署至少应组合一个应答者。
+
+### 组合应答者
+
+应答者是 `approval/request` waterfall（瀑布式事件）监听器：返回一个结果即为所负责的 agent（智能体）作答，否则调用 `next()` 委托。限定到 agent 的监听器只接收该 agent 的请求，且每项部署应组合一个最终应答者——同级监听器的顺序不是策略优先级机制。没有最终应答者时，请求解析为 `unavailable` 并以拒绝方式关闭；服务自身绝不会提示人类。
+
+### 设置策略
+
+有效策略取会话中已设置的策略，并回退到配置的默认值。`ask`（默认）委托给已组合的应答者；`never` 在交互式分发之前确定性地拒绝每个请求——这是 CI 与无人值守运行采用的严格无头模式。
+
+```yaml
+- name: '@qilin-agent/user-approval'
+  config:
+    policy: ask
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `policy` | `ask` | 没有 `approval/policy` 覆盖的会话的默认策略 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#qilin-agentuser-approval)是每个受支持字段及其 JSDoc 的穷尽式真源。`setPolicy(agent, policy)` 切换运行中的 agent 的策略，并为它的下一个模型步骤排队一条「由用户更改」消息；`setApprovalPolicy(session, policy)` 是会话初始化使用的直接持久写入路径。
+
+### 请求决定
+
+`request(req)` 指名 agent、工具、原因、可选的调用 id，以及一个中止信号。它要求当前处于尚未结束的轮次中：空闲或在轮次之间调用会在审计前抛出异常。中止会撤回问题——请求以 `cancelled` 结算，迟到的回答被丢弃。若任一审计事件在提交前失败，请求会被拒绝，而不会返回一项未记录的决定。
+
+### 模型与用户看到什么
+
+模型只会看到发起请求的消费方最终给出的工具结果——允许、拒绝、取消或不可用——以及运行时上下文快照中的当前策略；审计事件与面向人类的权限 UI 不属于模型上下文。`never` 切换会以一条带来源的用户消息告知模型，两种策略都会把各自的完整当前含义贡献给快照。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+可观察行为已在[使用本包](#use-this-package)中说明；本节解释分发、策略执行与审计路径。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | `ApprovalService`：请求分发、策略折叠与写入路径、运行时上下文贡献 |
+| [`src/types.ts`](src/types.ts) | `ApprovalRequestId` brand 与结果类型 |
+
+### 分发
+
+`decide()` 让应答者 waterfall 与请求信号赛跑，并隔离所有应答者故障：抛出异常的监听器会使问题以 `unavailable` 关闭，不属于结果词汇的异常返回值也会规范化为 `unavailable`。`never` 策略在服务内部、waterfall 分发之前执行，因此之后以 `prepend` 注册的监听器也无法绕过确定性的拒绝。请求必须处于未结束的轮次内，因为轮次是持久日志的提交／回放边界——轮次之间的裸事件与崩溃尾部无法区分。
+
+### 策略与运行时上下文快照
+
+系统提示词贡献 `approval:policy` 在保留历史之后陈述有效策略的完整当前含义——`ask` 及其以拒绝方式关闭的后果，或 `never` 及其非升权后果——因此切换策略会追加一份新的完整快照，而不会改写稳定的请求头。`setPolicy()` 还会注入一条带来源的用户消息，为下一步宣布变更。
+
+### 审计
+
+`request()` 先追加携带请求身份与工具的 `approval/asked`，再追加携带最终结果的 `approval/decided`；确切追加字段见 [`src/index.ts`](src/index.ts)。两者都只写入日志。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从审批词汇逐步进入消费方与设计依据。
+
+- [审批子系统参考](../../../docs/subsystems/approval.zh.md)——共享的请求／结果词汇与 `ctx.approval` 的 Cordis 接口面。
+- [审批 seam Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-approval-seam.zh.md)——该 seam 的设计依据。
+- [沙箱 Agent Note](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.zh.md)——沙箱 bash 工具如何为升权重试消费审批。
+- [交互组映射](../README.zh.md)——相邻的权限预设与问答包。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 当前审批策略上下文
+
+#### 模型看到的内容
+
+首次请求与有效策略每次变化时，都会在保留的历史后追加一份完整运行时上下文快照。在 `ask` 下，审批上下文内容会说明系统可以咨询已配置的应答者，缺少可用应答者时则以拒绝方式关闭。在 `never` 下，它会说明确定性的拒绝与非升权后果。未变化的请求会保留先前快照，不增加另一条消息。
+
+##### Ask 策略贡献
+
+```markdown
+Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.
+```
+
+##### Never 策略贡献
+
+```markdown
+Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
+```
+
+#### Token 影响
+
+首次请求和策略实际变化时增加一条简洁的上下文消息；未变化的请求不增加重复的策略 token。
+
+#### KV Cache 影响
+
+在保留的历史之后仅追加。`ask`／`never` 切换会保留稳定的系统与对话前缀，而不会改写第一条 wire 消息。
+
+### 工具结果
+
+#### 模型看到的内容
+
+`approval/asked` 和 `approval/decided` 只写入日志。模型只会看到发起请求的消费方最终给出的允许、拒绝、取消或不可用工具结果；面向人类的权限 UI 不属于上下文。
+
+#### Token 影响
+
+不会产生重复的审计 token。拒绝可能以一条简短且会保留的错误信息替换正常工具结果，而允许会保留消费方的普通结果。
+
+#### KV Cache 影响
+
+仅追加；新出现的可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明该 seam 不适用的场景，以及组合时需要特别注意的场景。它们是当前包约束，不是通用权限对比。
+
+- **请求只在尚未结束的轮次内有效**：在空闲时或轮次之间发起调用，会在审计前抛出异常；持久化的轮次外审批工作流仍属延期工作。
+- **仅存在一次性授权**：结果词汇包含 `allowed-once`，但不含 `allow-always`、已记住的规则、撤销或授权存储；会话策略只有 `ask`／`never`。
+- **请求不携带工具参数**：应答者会看到工具名称、原因和可选调用 id；ACP（Agent Client Protocol）机器通道要求调用 id，并会委托不含 id 的请求。
+- **没有内置应答者**：无头或组合不完整的部署会返回 `unavailable` 并以拒绝方式关闭；服务自身绝不会提示人类。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,192 @@
+import { randomUUID } from "node:crypto";
+import { Service } from "@qilin-agent/kylin";
+import z from "@qilin-agent/schemastery";
+import { createUserMessage } from "@qilin-agent/llm";
+import { scopeTarget } from "@qilin-agent/scope";
+import { SessionSeq } from "@qilin-agent/session";
+//#region lib/types/types.js
+/**
+* Wire-safe approval identifiers and outcome vocabulary, free of
+* cordis/service imports so browser type chains can
+* consume them without loading this package's Context augmentation.
+* @module @qilin-agent/user-approval/types
+*/
+/**
+* Brand a string as an {@link ApprovalRequestId}.
+* @param id - the raw id string to brand.
+* @returns the same string carrying the brand.
+*/
+function ApprovalRequestId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing
+* answerers fail closed; grants apply only to the requested action.
+* @module @qilin-agent/user-approval
+*/
+/** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */
+const OUTCOMES = [
+	"allowed-once",
+	"rejected",
+	"cancelled",
+	"unavailable"
+];
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+const APPROVAL_POLICIES = ["ask", "never"];
+/** Model-facing statement for the deterministic `'never'` policy. */
+const NEVER_SENTENCE = "Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).";
+/** Model-facing statement for an interactive policy that may still fail closed. */
+const ASK_SENTENCE = "Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.";
+/**
+* Whether the log currently sits inside an open turn (a `turn/start` not yet
+* closed by a `turn/end`) — the {@link ApprovalService.request} precondition.
+* The audit pair must be turn-enclosed: the turn is the durable log's
+* commit/replay boundary, so a bare event appended between turns is
+* indistinguishable from a crash tail and silently dropped on reload.
+*/
+function hasOpenTurn(session) {
+	for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+		const type = session.eventAt(SessionSeq(seq))?.type;
+		if (type === "turn/start") return true;
+		if (type === "turn/end") return false;
+	}
+	return false;
+}
+/**
+* Append the sole durable representation of a session policy override. Invalid
+* values throw before the log changes; consumers fold the new value on each read.
+* @param session - the session the override belongs to.
+* @param policy - the policy in effect until the next switch.
+*/
+function setApprovalPolicy(session, policy) {
+	if (!APPROVAL_POLICIES.includes(policy)) throw new TypeError("approval policy must be one of \"ask\" or \"never\"");
+	session.append("approval/policy", { policy });
+}
+/**
+* Approval service that applies session policy before answerers and logs every
+* ask/outcome pair to the requesting session. It exposes deterministic policy
+* changes to the model through the runtime-context snapshot and switch notices.
+*/
+var ApprovalService = class extends Service {
+	config;
+	static Config = z.object({ policy: z.union(["ask", "never"]).default("ask") });
+	constructor(ctx, config) {
+		super(ctx, "approval");
+		this.config = config;
+		const effective = (agent) => this.effectivePolicy(agent.session);
+		ctx.inject(["systemPrompt"], (scope) => {
+			scope.systemPrompt.context({
+				name: "approval:policy",
+				order: scope.systemPrompt.getContextOrder("APPROVAL_POLICY"),
+				text: (context) => {
+					const agent = context.agent;
+					if (agent === void 0) return "";
+					return effective(agent) === "never" ? NEVER_SENTENCE : ASK_SENTENCE;
+				}
+			});
+		});
+	}
+	/**
+	* Switch one live agent's policy and queue the transition for its next model
+	* step. Session initialization uses {@link setApprovalPolicy} directly
+	* because there is no previously visible policy to change.
+	* @param agent - the live agent whose policy is changing.
+	* @param policy - the new effective policy.
+	*/
+	setPolicy(agent, policy) {
+		const previous = this.effectivePolicy(agent.session);
+		if (previous === policy) return;
+		setApprovalPolicy(agent.session, policy);
+		agent.inject(createUserMessage({
+			content: [{
+				type: "text",
+				text: `The approval policy changed from "${previous}" to "${policy}" (changed by the user).`
+			}],
+			source: { kind: "user-approval" }
+		}));
+	}
+	/**
+	* Ask the composed answerers to decide one readonly same-process request.
+	* The service borrows the request, agent, session, and live signal directly.
+	* The request requires an open turn because the audit pair must be enclosed
+	* by the durable log's commit/replay boundary; an idle ask rejects before
+	* appending anything. The answerer phase always produces an outcome: an
+	* aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+	* `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+	* normalized to `'unavailable'`. A failure that prevents either audit append
+	* from committing still rejects because returning an unlogged decision would
+	* violate the pair. Session contains post-commit observer failures, so an
+	* authoritative append cannot reject the request or suppress its matching
+	* audit event.
+	* @param req - the pending decision (agent, tool identity, reason, signal).
+	* @returns the closed outcome; `'allowed-once'` is the only grant.
+	* @throws when no turn is open or either audit event fails before the session
+	*   append commit point.
+	*/
+	async request(req) {
+		const session = req.agent.session;
+		if (!hasOpenTurn(session)) throw new Error("approval.request() outside an open turn: the approval/asked + approval/decided audit pair must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). Ask from inside the turn that needs the decision.");
+		const id = ApprovalRequestId(randomUUID());
+		session.append("approval/asked", {
+			id,
+			toolName: req.toolName,
+			...req.callId !== void 0 ? { callId: req.callId } : {},
+			...req.reason !== void 0 ? { reason: req.reason } : {}
+		});
+		const outcome = await this.decide(req, session);
+		session.append("approval/decided", {
+			id,
+			outcome
+		});
+		return outcome;
+	}
+	/**
+	* The session's effective policy: its own `approval/policy` fold, else the
+	* configured default (the schema already defaulted an omitted policy to
+	* `'ask'`; the `??` only narrows the optional-input TYPE).
+	* @param session - the exact accepted session whose policy applies.
+	* @returns the policy every ask for this session resolves under right now.
+	*/
+	effectivePolicy(session) {
+		return this.overrideOf(session) ?? this.config.policy ?? "ask";
+	}
+	/**
+	* Read the session override without applying the configured default.
+	* @param session - session whose log supplies the override.
+	* @returns the last logged policy, or `undefined` without one.
+	*/
+	overrideOf(session) {
+		for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+			const event = session.eventAt(SessionSeq(seq));
+			if (event?.type === "approval/policy") return event.data.policy;
+		}
+	}
+	/**
+	* Dispatch the waterfall, contained and raced against the request signal.
+	* @param req - the borrowed public request.
+	* @param session - the request agent's session used for policy lookup.
+	* @returns the normalized closed outcome.
+	*/
+	async decide(req, session) {
+		const signal = req.signal;
+		if (signal?.aborted) return "cancelled";
+		if (this.effectivePolicy(session) === "never") return "rejected";
+		const answer = Promise.resolve().then(() => this.ctx.waterfall(scopeTarget(req.agent, req.agent), "approval/request", req, () => Promise.resolve("unavailable"))).then((outcome) => OUTCOMES.includes(outcome) ? outcome : "unavailable", () => "unavailable");
+		if (signal === void 0) return answer;
+		return await new Promise((resolve) => {
+			const onAbort = () => {
+				signal.removeEventListener("abort", onAbort);
+				resolve("cancelled");
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			answer.then((outcome) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(outcome);
+			});
+		});
+	}
+};
+//#endregion
+export { APPROVAL_POLICIES, ApprovalRequestId, ApprovalService, ApprovalService as default, setApprovalPolicy };

package/lib/types/index.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing
+ * answerers fail closed; grants apply only to the requested action.
+ * @module @qilin-agent/user-approval
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import type { Agent } from '@qilin-agent/agent';
+import { type ToolCallId } from '@qilin-agent/llm';
+import type { ContextFormed } from '@qilin-agent/llm';
+declare module '@qilin-agent/llm' {
+    interface MessageSourceMap {
+        'user-approval': {
+            kind: 'user-approval';
+        } & ContextFormed;
+    }
+}
+import type { Session } from '@qilin-agent/session';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        approval: ApprovalService;
+    }
+}
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /**
+         * The session's approval policy was switched — log-only, durable,
+         * replayable, never in the model transcript (the model learns the policy
+         * from the runtime-context snapshot and live switch notices). The LAST
+         * such event is the session's override.
+         * `source: 'delegation'` marks an override seeded into a child; an absent
+         * source is a runtime switch.
+         */
+        'approval/policy': {
+            policy: ApprovalPolicy;
+            /** Marks an override seeded into a child at delegation. */
+            source?: 'delegation';
+        };
+    }
+}
+import type { ApprovalOutcome, ApprovalRequestEvent } from './types.ts';
+export { ApprovalRequestId } from './types.ts';
+export type { ApprovalOutcome } from './types.ts';
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the policy whose outcome is knowable without asking.
+ */
+export type ApprovalPolicy = 'ask' | 'never';
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+export declare const APPROVAL_POLICIES: readonly ApprovalPolicy[];
+/**
+ * Append the sole durable representation of a session policy override. Invalid
+ * values throw before the log changes; consumers fold the new value on each read.
+ * @param session - the session the override belongs to.
+ * @param policy - the policy in effect until the next switch.
+ */
+export declare function setApprovalPolicy(session: Session, policy: ApprovalPolicy): void;
+/**
+ * Readonly same-process permission question. `callId` links to an already
+ * presented tool call, so arguments are not duplicated here.
+ */
+export interface ApprovalRequest extends ApprovalRequestEvent {
+    /**
+     * The agent on whose behalf the question is asked. Routes the question (a
+     * UI answerer only answers for agents it owns) and receives the audit
+     * events on its session log.
+     */
+    readonly agent: Agent;
+    /** The tool the question is about (presentation and audit). */
+    readonly toolName: string;
+    /**
+     * The exact tool call being decided, when the asker has one — lets a UI
+     * attach the prompt to the tool call it already streamed.
+     */
+    readonly callId?: ToolCallId;
+    /** The asker's human-readable explanation of WHY it is asking. */
+    readonly reason?: string;
+    /**
+     * Aborting withdraws the question: the request settles `'cancelled'`
+     * immediately and a late answer from a still-pending answerer is discarded.
+     */
+    readonly signal?: AbortSignal;
+}
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+    /**
+     * The deployment's default {@link ApprovalPolicy} for sessions without an
+     * `approval/policy` override — `'ask'` delegates to the composed answerers
+     * (fail-closed with none); `'never'` auto-rejects every ask without
+     * prompting (the deterministic CI/unattended stance).
+     */
+    readonly policy?: ApprovalPolicy;
+}
+/**
+ * Approval service that applies session policy before answerers and logs every
+ * ask/outcome pair to the requesting session. It exposes deterministic policy
+ * changes to the model through the runtime-context snapshot and switch notices.
+ */
+export declare class ApprovalService extends Service {
+    config: Config;
+    static Config: z<Config>;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Switch one live agent's policy and queue the transition for its next model
+     * step. Session initialization uses {@link setApprovalPolicy} directly
+     * because there is no previously visible policy to change.
+     * @param agent - the live agent whose policy is changing.
+     * @param policy - the new effective policy.
+     */
+    setPolicy(agent: Agent, policy: ApprovalPolicy): void;
+    /**
+     * Ask the composed answerers to decide one readonly same-process request.
+     * The service borrows the request, agent, session, and live signal directly.
+     * The request requires an open turn because the audit pair must be enclosed
+     * by the durable log's commit/replay boundary; an idle ask rejects before
+     * appending anything. The answerer phase always produces an outcome: an
+     * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+     * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+     * normalized to `'unavailable'`. A failure that prevents either audit append
+     * from committing still rejects because returning an unlogged decision would
+     * violate the pair. Session contains post-commit observer failures, so an
+     * authoritative append cannot reject the request or suppress its matching
+     * audit event.
+     * @param req - the pending decision (agent, tool identity, reason, signal).
+     * @returns the closed outcome; `'allowed-once'` is the only grant.
+     * @throws when no turn is open or either audit event fails before the session
+     *   append commit point.
+     */
+    request(req: ApprovalRequest): Promise<ApprovalOutcome>;
+    /**
+     * The session's effective policy: its own `approval/policy` fold, else the
+     * configured default (the schema already defaulted an omitted policy to
+     * `'ask'`; the `??` only narrows the optional-input TYPE).
+     * @param session - the exact accepted session whose policy applies.
+     * @returns the policy every ask for this session resolves under right now.
+     */
+    private effectivePolicy;
+    /**
+     * Read the session override without applying the configured default.
+     * @param session - session whose log supplies the override.
+     * @returns the last logged policy, or `undefined` without one.
+     */
+    overrideOf(session: Session): ApprovalPolicy | undefined;
+    /**
+     * Dispatch the waterfall, contained and raced against the request signal.
+     * @param req - the borrowed public request.
+     * @param session - the request agent's session used for policy lookup.
+     * @returns the normalized closed outcome.
+     */
+    private decide;
+}
+export default ApprovalService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,209 @@
+/**
+ * Service Definition for the approval capability seam, covering requests, cancellation, audit, and per-session policy. Missing
+ * answerers fail closed; grants apply only to the requested action.
+ * @module @qilin-agent/user-approval
+ */
+import { randomUUID } from 'node:crypto';
+import { Service } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import { createUserMessage } from '@qilin-agent/llm';
+import { scopeTarget } from '@qilin-agent/scope';
+import { SessionSeq } from '@qilin-agent/session';
+import { ApprovalRequestId } from "./types.js";
+export { ApprovalRequestId } from "./types.js";
+/** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */
+const OUTCOMES = ['allowed-once', 'rejected', 'cancelled', 'unavailable'];
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+export const APPROVAL_POLICIES = ['ask', 'never'];
+/** Model-facing statement for the deterministic `'never'` policy. */
+const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).';
+/** Model-facing statement for an interactive policy that may still fail closed. */
+const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.';
+/**
+ * Whether the log currently sits inside an open turn (a `turn/start` not yet
+ * closed by a `turn/end`) — the {@link ApprovalService.request} precondition.
+ * The audit pair must be turn-enclosed: the turn is the durable log's
+ * commit/replay boundary, so a bare event appended between turns is
+ * indistinguishable from a crash tail and silently dropped on reload.
+ */
+function hasOpenTurn(session) {
+    for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+        const type = session.eventAt(SessionSeq(seq))?.type;
+        if (type === 'turn/start')
+            return true;
+        if (type === 'turn/end')
+            return false;
+    }
+    return false;
+}
+/**
+ * Append the sole durable representation of a session policy override. Invalid
+ * values throw before the log changes; consumers fold the new value on each read.
+ * @param session - the session the override belongs to.
+ * @param policy - the policy in effect until the next switch.
+ */
+export function setApprovalPolicy(session, policy) {
+    if (!APPROVAL_POLICIES.includes(policy)) {
+        throw new TypeError('approval policy must be one of "ask" or "never"');
+    }
+    session.append('approval/policy', { policy });
+}
+/**
+ * Approval service that applies session policy before answerers and logs every
+ * ask/outcome pair to the requesting session. It exposes deterministic policy
+ * changes to the model through the runtime-context snapshot and switch notices.
+ */
+export class ApprovalService extends Service {
+    config;
+    static Config = z.object({
+        policy: z.union(['ask', 'never']).default('ask'),
+    });
+    constructor(ctx, config) {
+        super(ctx, 'approval');
+        this.config = config;
+        const effective = (agent) => this.effectivePolicy(agent.session);
+        // The complete current value travels after retained history, so switching
+        // policy does not rewrite the stable system-prompt cache prefix.
+        ctx.inject(['systemPrompt'], (scope) => {
+            scope.systemPrompt.context({
+                name: 'approval:policy',
+                order: scope.systemPrompt.getContextOrder('APPROVAL_POLICY'),
+                text: (context) => {
+                    const agent = context.agent;
+                    // A bare assemble() (tests, diagnostics) has no session to state.
+                    if (agent === undefined)
+                        return '';
+                    const policy = effective(agent);
+                    return policy === 'never' ? NEVER_SENTENCE : ASK_SENTENCE;
+                },
+            });
+        });
+    }
+    /**
+     * Switch one live agent's policy and queue the transition for its next model
+     * step. Session initialization uses {@link setApprovalPolicy} directly
+     * because there is no previously visible policy to change.
+     * @param agent - the live agent whose policy is changing.
+     * @param policy - the new effective policy.
+     */
+    setPolicy(agent, policy) {
+        const previous = this.effectivePolicy(agent.session);
+        if (previous === policy)
+            return;
+        setApprovalPolicy(agent.session, policy);
+        agent.inject(createUserMessage({
+            content: [{
+                    type: 'text',
+                    text: `The approval policy changed from "${previous}" to "${policy}" (changed by the user).`,
+                }],
+            source: { kind: 'user-approval' },
+        }));
+    }
+    /**
+     * Ask the composed answerers to decide one readonly same-process request.
+     * The service borrows the request, agent, session, and live signal directly.
+     * The request requires an open turn because the audit pair must be enclosed
+     * by the durable log's commit/replay boundary; an idle ask rejects before
+     * appending anything. The answerer phase always produces an outcome: an
+     * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+     * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+     * normalized to `'unavailable'`. A failure that prevents either audit append
+     * from committing still rejects because returning an unlogged decision would
+     * violate the pair. Session contains post-commit observer failures, so an
+     * authoritative append cannot reject the request or suppress its matching
+     * audit event.
+     * @param req - the pending decision (agent, tool identity, reason, signal).
+     * @returns the closed outcome; `'allowed-once'` is the only grant.
+     * @throws when no turn is open or either audit event fails before the session
+     *   append commit point.
+     */
+    async request(req) {
+        const session = req.agent.session;
+        if (!hasOpenTurn(session)) {
+            throw new Error('approval.request() outside an open turn: the approval/asked + approval/decided audit pair '
+                + 'must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). '
+                + 'Ask from inside the turn that needs the decision.');
+        }
+        const id = ApprovalRequestId(randomUUID());
+        session.append('approval/asked', {
+            id,
+            toolName: req.toolName,
+            ...req.callId !== undefined ? { callId: req.callId } : {},
+            ...req.reason !== undefined ? { reason: req.reason } : {},
+        });
+        const outcome = await this.decide(req, session);
+        session.append('approval/decided', { id, outcome });
+        return outcome;
+    }
+    /**
+     * The session's effective policy: its own `approval/policy` fold, else the
+     * configured default (the schema already defaulted an omitted policy to
+     * `'ask'`; the `??` only narrows the optional-input TYPE).
+     * @param session - the exact accepted session whose policy applies.
+     * @returns the policy every ask for this session resolves under right now.
+     */
+    effectivePolicy(session) {
+        return this.overrideOf(session) ?? this.config.policy ?? 'ask';
+    }
+    /**
+     * Read the session override without applying the configured default.
+     * @param session - session whose log supplies the override.
+     * @returns the last logged policy, or `undefined` without one.
+     */
+    overrideOf(session) {
+        for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+            // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+            const event = session.eventAt(SessionSeq(seq));
+            if (event?.type === 'approval/policy')
+                return event.data.policy;
+        }
+        return undefined;
+    }
+    /**
+     * Dispatch the waterfall, contained and raced against the request signal.
+     * @param req - the borrowed public request.
+     * @param session - the request agent's session used for policy lookup.
+     * @returns the normalized closed outcome.
+     */
+    async decide(req, session) {
+        const signal = req.signal;
+        if (signal?.aborted)
+            return 'cancelled';
+        // The 'never' policy is decided HERE, before any dispatch: a listener
+        // registered with `prepend: true` after this service mounts would sit
+        // ahead of any gate LISTENER, so a listener-shaped gate cannot keep the
+        // documented promise that 'never' rejects deterministically regardless
+        // of registration order — only the service's own request path can.
+        if (this.effectivePolicy(session) === 'never')
+            return 'rejected';
+        // Enter the promise chain BEFORE dispatching: a listener that throws
+        // SYNCHRONOUSLY (before its first await) must land in the same rejection
+        // path as an async one — `Promise.resolve(call())` would let it escape
+        // the containment into the caller.
+        const answer = Promise.resolve().then(() => this.ctx.waterfall(scopeTarget(req.agent, req.agent), 'approval/request', req, () => Promise.resolve('unavailable'))).then(
+        // Normalize a rogue (non-vocabulary) answerer return to the fail-closed
+        // outcome instead of leaking it into callers' closed-union switches.
+        outcome => OUTCOMES.includes(outcome) ? outcome : 'unavailable', 
+        // A throwing answerer must fail the QUESTION closed, not the caller's
+        // tool call open — the seam contains its callbacks.
+        () => 'unavailable');
+        if (signal === undefined)
+            return answer;
+        return await new Promise((resolve) => {
+            const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                resolve('cancelled');
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            void answer.then((outcome) => {
+                signal.removeEventListener('abort', onAbort);
+                // After an abort won the race this resolve is a settled-promise no-op:
+                // the late answer is discarded by construction.
+                resolve(outcome);
+            });
+        });
+    }
+}
+export default ApprovalService;
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Wire-safe approval identifiers and outcome vocabulary, free of
+ * cordis/service imports so browser type chains can
+ * consume them without loading this package's Context augmentation.
+ * @module @qilin-agent/user-approval/types
+ */
+import type { Branded } from '@qilin-agent/brand';
+import type { Scoped } from '@qilin-agent/scope';
+import type { Agent } from '@qilin-agent/agent/types';
+import type { ToolCallId } from '@qilin-agent/llm/brand';
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
+export type ApprovalRequestId = Branded<'ApprovalRequestId'>;
+/**
+ * Brand a string as an {@link ApprovalRequestId}.
+ * @param id - the raw id string to brand.
+ * @returns the same string carrying the brand.
+ */
+export declare function ApprovalRequestId(id: string): ApprovalRequestId;
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+declare module '@qilin-agent/session/types' {
+    interface SessionEventMap {
+        /**
+         * An approval question was put to the answerer chain — log-only audit
+         * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs
+         * it with the `approval/decided` that always follows; `toolName` is the
+         * tool the question is about, `callId` the exact tool call when the asker
+         * had one, `reason` the asker's human-readable explanation (e.g. a hook's
+         * permission-decision reason).
+         */
+        'approval/asked': {
+            id: ApprovalRequestId;
+            toolName: string;
+            callId?: ToolCallId;
+            reason?: string;
+        };
+        /**
+         * The outcome of a prior `approval/asked` (same `id`) — log-only audit.
+         * Exactly one per ask, appended when the outcome is known: a decision, a
+         * cancellation, or the fail-closed `'unavailable'`.
+         */
+        'approval/decided': {
+            id: ApprovalRequestId;
+            outcome: ApprovalOutcome;
+        };
+    }
+}
+/** Client-safe payload declared for the approval answerer waterfall. */
+export interface ApprovalRequestEvent {
+    /** Agent identity projected to the corresponding Client Context in transit. */
+    readonly agent: Agent;
+    /** Tool whose operation requires a decision. */
+    readonly toolName: string;
+    /** Exact tool call being decided, when available. */
+    readonly callId?: ToolCallId;
+    /** Human-readable reason supplied by the asker. */
+    readonly reason?: string;
+    /** Localized presentation only; never persisted in approval audit events. */
+    readonly displayReason?: {
+        readonly en: string;
+        readonly [locale: string]: string;
+    };
+    /** Cancellation lifetime of the pending request. */
+    readonly signal?: AbortSignal;
+}
+declare module '@qilin-agent/kylin' {
+    interface Events {
+        /**
+         * Ask composed answerers for one decision. Return an outcome to claim the
+         * request or call `next()` to delegate. Scope-filtered dispatch
+         * (`@qilin-agent/scope`): agent-scoped listeners receive only that agent.
+         * @param req - pending approval request.
+         * @mode waterfall
+         */
+        'approval/request'(this: Scoped<Agent>, req: ApprovalRequestEvent, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,15 @@
+/**
+ * Wire-safe approval identifiers and outcome vocabulary, free of
+ * cordis/service imports so browser type chains can
+ * consume them without loading this package's Context augmentation.
+ * @module @qilin-agent/user-approval/types
+ */
+/**
+ * Brand a string as an {@link ApprovalRequestId}.
+ * @param id - the raw id string to brand.
+ * @returns the same string carrying the brand.
+ */
+export function ApprovalRequestId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@qilin-agent/user-approval",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "User-approval seam (ctx.approval) for the QiLin: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/interaction/user-approval"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/system-prompt": "3.1.4"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/system-prompt": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  }
 }