@andares/pi-toolkits 0.9.8 → 0.10.0

package/README.md

@@ -69,7 +69,7 @@ After installing, verify in any pi session:
 | Feature | Entry point | One-line description |
 | --- | --- | --- |
 | 🛡️ **ask** read-only consult mode | `/ask` | enter consult mode: `write`/`edit`/`powershell` hard-disabled, `bash` runs in a read-only sandbox, `grep`/`find`/`ls` activated, and `scratchpad` allowed to write throwaway notes into the session's temp directory |
-| 🔐 **permission** session-scoped boundary checks | `/ask-perm` | four in/out × read/write modes, off by default and never persisted; outside writes ask, credentials are denied, destructive commands always ask; composes with `/ask` |
+| 🔐 **permission** session-scoped boundary checks | `/ask-perm` | four in/out × read/write modes, off by default and never persisted; outside writes ask, credentials are denied, destructive commands always ask; composes with `/ask`; a capped JSONL approval log feeds later rule mining |
 | ⭐ **favorites** model favorites | `ctrl+A` / `ctrl+J` inside `/model` | favorite the models you use most (marked in bold bright yellow), `ctrl+p` cycles only among favorites |
 | 📥 **stash** prompt stash | `ctrl+alt+y` | a stash slot for one prompt: press to swap, press twice to stash and clear the input box |
 | 🔎 **review** third-party code review | `/third-review` | summon the configured review model to check + fix the task just finished, focusing on "is this round's requirement implemented / is anything missing / is anything wrong" |
@@ -104,7 +104,7 @@ Enter with `/ask` (press it again to exit). Meant for the case where you only wa
 
 <a name="permission"></a>
 
-`/ask-perm` turns on boundary checks for the **current session only**. Every piece of state — the on/off flag, the four modes, the session grants — lives in the extension's memory. Nothing is written to disk, the feature is off by default, and it leaves no status behind when disabled. Toggling it on can never silently follow you into the next session.
+`/ask-perm` turns on boundary checks for the **current session only**. Every piece of state — the on/off flag, the four modes, the session grants — lives in the extension's memory and is never persisted: the feature is off by default and leaves no status behind when disabled. Toggling it on can never silently follow you into the next session. Separately, decisions worth keeping are appended to a capped local **approval log** for later rule mining (see below); it is write-only telemetry and is never consulted while deciding.
 
 **Enable**
 
@@ -137,9 +137,36 @@ Repeating the argument form with the modes already in force is a **no-op**: no s
 - **credentials are denied in every mode** — `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.pi/agent/auth*.json`, `.env` files (templates excepted). Without this, `out read = allow` would hand out `~/.ssh/id_rsa`.
 - **destructive commands always ask** — `rm` of `/`, the home directory, or the working directory; `git reset --hard`; `git clean -f`; `git push --force`; package `publish`; `dd` to a raw device; `mkfs*`; shutdown/reboot; `chmod -R 777`; anything through `sudo`. Scope alone cannot express "destructive".
 
+**Approval log** (write-only telemetry, on by default)
+
+Every decision worth keeping becomes one JSON object per line (JSONL) in `~/.pi/agent/approval-log/audit-NNNNNN.jsonl`. The policy never reads the log: deleting it or making the directory read-only changes no verdict.
+
+- **Scope**: blocks from `/ask` mode are approval decisions too, so they are recorded as well (with the gate name and the model-facing reason).
+- **What is recorded**: interactive asks (the exact dialog lines, the bash decomposition, the chosen answer, the grant and its latency), automatic denials and blocks, session-grant allows, `/ask-perm` mode changes, and one `session` summary with call/ask/block counters. Plain mode-allowed `read`/`grep` calls are skipped by default so the ring buffer is not buried in noise; `PI_APPROVAL_LOG=all` also logs plain mode-allowed calls, `PI_APPROVAL_LOG=off` disables the log.
+- **Rotation**: 1000 records **or** 8 MiB per file, at most 10 files; creating an 11th deletes the lowest-numbered one. Typical retention is 15–30 MB (hard ceiling 80 MB) and roughly the last 10,000 records.
+- **Fidelity**: the four modes, session roots, tool call, every command unit (including `opaque` units and parser notes), each target's canonical path / effect / in-or-out scope, the deciding rule layer, the dialog lines, the answer and the resulting grant. `write`/`edit` file **contents are never logged** (only path and byte count); bearer tokens, `token=`/`password=`, URL credentials and known key prefixes are redacted.
+- **Failure and privacy**: directory `0700`, files `0600`, local only, safe to delete at any time. A logging failure is reported once and swallowed — the verdict path never fails because the log is unavailable. `PI_APPROVAL_LOG_DIR` relocates the directory.
+
+```bash
+# focus on the prompts that became session grants
+jq -r 'select(.event=="ask" and .answer.choice=="allow-session")
+       | [.ts,.tool,.verdict.target,.input.command] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl
+
+# target roots × answers — the shortest path to a "safe temp dir" rule
+jq -r 'select(.event=="ask") | [.verdict.grantRoot,.answer.choice] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl | sort | uniq -c | sort -rn
+
+# parser gaps (opaque units) worth teaching units.ts
+jq -r 'select(.event=="ask") | .units[] | select(.opaque) | [.command,.note] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl | sort | uniq -c | sort -rn
+```
+
+See the repository's `pnpm approval-report` for a read-only summary (answer mix, target roots, rule candidates, opaque gaps, playwright patterns).
+
 **Composition with `/ask`**: the two features are independent gates on one bus. Each answers only its own question — ask: "does this mutate?", permission: "does this cross the boundary?" — and either can block. Ask mode still denies credential reads, and permission still applies while the read-only sandbox is active. Neither feature needs to know the other exists. The one exception is ask's `scratchpad`: that tool is self-jailed (relative names only, one temp directory), so ask marks it while active and permission skips the boundary dialog that would otherwise fire for an "outside write" on every note.
 
-**Enable it for every session** (the state itself is never persisted — this is the opt-in):
+**Enable it for every session** (the state itself is never persisted — this is the opt-in; the audit log is independent and on by default):
 
 ```toml
 # <project>/.pi/autostart.toml, or <agent-dir>/autostart.toml for all projects
@@ -147,7 +174,7 @@ Repeating the argument form with the modes already in force is a **no-op**: no s
 run = ["/ask-perm allow allow allow ask"]
 ```
 
-> **Implementation notes**: a new session resets the state on `session_start` (a repeated emission for the same session keeps it); the footer shows `perm i:A/A o:A/ask` while on (`A` allow, `a` ask, `D` deny). Subagent sessions start with their own state and do not inherit the parent's mode — when child sessions must be gated too, enable it through the project's autostart file. POSIX hosts (Linux / macOS / WSL) are the tested target; native Windows Git-Bash path spellings are approximated, not verified. bash decomposition uses `shell-quote`; unknown variables expand to a sentinel that makes the unit ask instead of silently becoming an empty path. Added directories are read from pi-add-dir's session entry (`add-dir:state`). Heuristic, not a sandbox: project-internal destructive commands are covered by the fixed table, not by a sandbox. One known blind spot: a *read* command's bare filename operand (`cat notes.txt`) is not collected as a target, so with `out read = ask` only absolute-path-shaped read operands are questioned — reads never write, so the four modes' write side is unaffected.
+> **Implementation notes**: a new session resets the state on `session_start` (a repeated emission for the same session keeps it); the footer shows `perm i:A/A o:A/ask` while on (`A` allow, `a` ask, `D` deny). Subagent sessions start with their own state and do not inherit the parent's mode — when child sessions must be gated too, enable it through the project's autostart file. The approval log is appended by the gate bus (asks/blocks/session summaries) and by the permission gate (mode changes and session-grant allows); the writer is lazy, keeps no state across processes, and never participates in a decision. POSIX hosts (Linux / macOS / WSL) are the tested target; native Windows Git-Bash path spellings are approximated, not verified. bash decomposition uses `shell-quote`; unknown variables expand to a sentinel that makes the unit ask instead of silently becoming an empty path. Added directories are read from pi-add-dir's session entry (`add-dir:state`). Heuristic, not a sandbox: project-internal destructive commands are covered by the fixed table, not by a sandbox. One known blind spot: a *read* command's bare filename operand (`cat notes.txt`) is not collected as a target, so with `out read = ask` only absolute-path-shaped read operands are questioned — reads never write, so the four modes' write side is unaffected.
 
 ---
 
@@ -353,6 +380,7 @@ pnpm test         # vitest (all feature unit tests)
 
 pnpm check:keybindings   # audit this plugin's keys against the host's own dispatch table
 pnpm check:compat        # mandatory 4-line window + backward probe (4 more lines) → public floor
+pnpm approval-report     # summarize the local approval log (answer mix, targets, rule candidates)
 ```
 
 ### Project structure
@@ -363,6 +391,7 @@ src/
 ├── lib/                  # shared infrastructure (tool-set snapshot/restore,
 │                         # gate bus composing tool_call policies, jailed-tool
 │                         # registry the boundary gate consults,
+│                         # rolling JSONL approval log,
 │                         # model-key resolution shared by review & compact)
 └── features/             # feature modules — one directory per feature
     ├── ask/              # ask mode: command + state machine, bash sandbox,
@@ -377,7 +406,7 @@ src/
     │                     #           persisted store, tests
     ├── permission/       # session-scoped boundary permission: modes, panel,
     │                     #           bash units, policy, session grants, prompt,
-    │                     #           tests
+    │                     #           audit payload, tests
     ├── review/           # third-party review: input/command triggers,
     │                     #           review-model config store, prompt, tests
     └── stash/            # prompt stash: hotkey state machine + tests

package/README.zh-CN.md

@@ -69,7 +69,7 @@ pi -e ./src/index.ts
 | 功能 | 入口 | 一句话说明 |
 | --- | --- | --- |
 | 🛡️ **ask** 只读咨询模式 | `/ask` | 进入咨询模式:`write`/`edit`/`powershell` 硬禁用,`bash` 只读沙箱,临时启用 `grep`/`find`/`ls`,并开放 `scratchpad` 把草稿写进会话临时目录 |
-| 🔐 **permission** 会话级边界权限 | `/ask-perm` | 项目内/外 × 读/写四格模式,默认关闭且从不落盘;项目外写询问、凭据路径硬拒、破坏性命令必问;与 `/ask` 并行组合 |
+| 🔐 **permission** 会话级边界权限 | `/ask-perm` | 项目内/外 × 读/写四格模式,默认关闭且从不落盘;项目外写询问、凭据路径硬拒、破坏性命令必问;与 `/ask` 并行组合;另有滚动 JSONL 审批日志供事后挖规则 |
 | ⭐ **favorites** 模型收藏 | `/model` 内 `ctrl+A` / `ctrl+J` | 收藏常用模型(加粗亮黄标记),`ctrl+p` 仅在收藏间循环 |
 | 📥 **stash** 提示词暂存 | `ctrl+alt+y` | 一段提示词的暂存槽,按键交换 / 连按两次暂存并清空输入框 |
 | 🔎 **review** 第三方代码评审 | `/third-review` | 召唤配置的评审模型,对刚完成的任务做查+修,重点检查「本轮需求实现 / 是否有遗漏 / 是否有错误」 |
@@ -104,7 +104,7 @@ pi -e ./src/index.ts
 
 <a name="permission"></a>
 
-`/ask-perm` 只在**当前会话**开启边界检查。开关状态、四项模式、会话授权全部只存在扩展内存里:不落盘、默认关闭、关闭后不留任何状态。开启一次不会悄悄跟到下一个会话。
+`/ask-perm` 只在**当前会话**开启边界检查。开关状态、四项模式、会话授权全部只存在扩展内存里:权限**状态**不落盘、默认关闭、关闭后不留任何状态。开启一次不会悄悄跟到下一个会话。另外,值得留档的判定会追加到本地**审批日志**(见下),供事后挖规则用;它是只写的遥测数据,判定时永远不会被读取。
 
 **开启**
 
@@ -137,9 +137,36 @@ pi -e ./src/index.ts
 - **凭据路径任何模式都拒绝** —— `~/.ssh`、`~/.gnupg`、`~/.aws`、`~/.pi/agent/auth*.json`、`.env` 文件(模板除外)。没有这一条,默认的「项目外读放行」就等于把 `~/.ssh/id_rsa` 交出去
 - **破坏性命令永远询问** —— 对 `/`、家目录或工作目录的 `rm`;`git reset --hard`;`git clean -f`;`git push --force`;包 `publish`;`dd` 写裸设备;`mkfs*`;关机/重启;`chmod -R 777`;任何经 `sudo` 的命令。作用域本身表达不了「破坏性」
 
+**审批日志**(只写遥测,默认开启)
+
+每个值得留档的判定都会写成一行 JSON(JSONL),落在 `~/.pi/agent/approval-log/audit-NNNNNN.jsonl`。策略层从不读它:删掉日志或把目录改成只读,不会改变任何判定结果。
+
+- **范围**:`/ask` 模式的拦截同样算审批决定,也会记录(带闸门名与模型可见理由)。
+- **记录什么**:交互弹窗(用户看到的原始行、bash 拆解结果、答复、授权与决策耗时)、自动拒绝/拦截、会话授权放行、`/ask-perm` 模式切换,以及每个会话一条 `session` 摘要(调用/弹窗/拦截计数)。普通自动放行的 `read`/`grep` 默认不记,避免把环形缓冲淹在噪声里;`PI_APPROVAL_LOG=all` 连普通自动放行也记,`PI_APPROVAL_LOG=off` 关闭日志。
+- **滚动**:每文件 1000 条**或** 8 MiB,最多 10 个文件;创建第 11 个时删掉序号最小的那个。典型体积 15–30 MB(硬上限 80 MB),约保留最近 1 万条判定。
+- **保真度**:四格模式、会话根目录、工具调用、每个命令单元(含 `opaque` 单元与解析器备注)、每个目标规范化后的路径/读或写/项目内或外、命中哪条规则层、弹窗原文、答复与产生的授权。`write`/`edit` 的文件**正文永不记录**(只记路径与字节数);bearer token、`token=`/`password=`、URL 内嵌凭据与已知密钥前缀会脱敏。
+- **失败与隐私**:目录 `0700`、文件 `0600`,只在本机,可随时删除。日志故障只警告一次并被吞掉——判定链路不会因为日志不可用而失败。`PI_APPROVAL_LOG_DIR` 可改目录。
+
+```bash
+# 只看"本会话允许"的弹窗
+jq -r 'select(.event=="ask" and .answer.choice=="allow-session")
+       | [.ts,.tool,.verdict.target,.input.command] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl
+
+# 目标根目录 × 答复 —— 找「临时目录直接放行」规则的最短路径
+jq -r 'select(.event=="ask") | [.verdict.grantRoot,.answer.choice] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl | sort | uniq -c | sort -rn
+
+# 解析不了的单元:定位 units.ts 的缺口
+jq -r 'select(.event=="ask") | .units[] | select(.opaque) | [.command,.note] | @tsv' \
+  ~/.pi/agent/approval-log/*.jsonl | sort | uniq -c | sort -rn
+```
+
+仓库内可用 `pnpm approval-report` 生成只读汇总(答复分布、目标根目录、候选规则、opaque 缺口、playwright 模式)。
+
 **与 `/ask` 的组合**:两者是同一总线上的独立闸门,各自只回答自己的问题 —— ask 回答「会不会产生变更」,permission 回答「有没有越过边界」,任一拦截都生效。所以 ask 模式下凭据仍然读不到,permission 在只读沙箱下也照常工作;两个功能互不需要知道对方存在。
 
-**每个会话自动开启**(状态本身不落盘,这就是持久化的替身):
+**每个会话自动开启**(状态本身不落盘,这就是持久化的替身;审批日志独立于它、默认开启):
 
 ```toml
 # <项目>/.pi/autostart.toml;想对所有项目生效则用 <agent-dir>/autostart.toml
@@ -147,7 +174,7 @@ pi -e ./src/index.ts
 run = ["/ask-perm allow allow allow ask"]
 ```
 
-> **实现说明**:新会话在 `session_start` 重置状态(同一会话的重复 emission 保持状态);开启时 footer 显示 `perm i:A/A o:A/ask`(`A` allow、`a` ask、`D` deny)。子代理会话有自己的状态、不继承父会话的模式;需要子会话也受控时,通过项目 autostart 再开启一次。实测目标是 POSIX 宿主(Linux/macOS/WSL);原生 Windows Git-Bash 的路径拼写只做了近似,未验证。bash 拆解使用 `shell-quote`;未知变量会展开成哨兵而不是空字符串,使该命令转为询问而不是被悄悄当成空路径。add-dir 目录从 pi-add-dir 的会话条目 `add-dir:state` 读取。启发式,不是沙箱:项目内的破坏性操作由固定表兜底,而不是靠沙箱。已知盲区一处:**读命令的裸文件名参数**(`cat notes.txt`)不被收集为目标,所以把 `out read` 调成 `ask` 时只有绝对路径形状的读目标会被问——读本身不会写,四格模式的写侧不受影响。
+> **实现说明**:新会话在 `session_start` 重置状态(同一会话的重复 emission 保持状态);开启时 footer 显示 `perm i:A/A o:A/ask`(`A` allow、`a` ask、`D` deny)。子代理会话有自己的状态、不继承父会话的模式;需要子会话也受控时,通过项目 autostart 再开启一次。审批日志由闸门总线(弹窗/拦截/会话摘要)与 permission 闸门(模式切换、会话授权放行)追加;写入器懒初始化、不跨进程保存状态,也从不参与判定。实测目标是 POSIX 宿主(Linux/macOS/WSL);原生 Windows Git-Bash 的路径拼写只做了近似,未验证。bash 拆解使用 `shell-quote`;未知变量会展开成哨兵而不是空字符串,使该命令转为询问而不是被悄悄当成空路径。add-dir 目录从 pi-add-dir 的会话条目 `add-dir:state` 读取。启发式,不是沙箱:项目内的破坏性操作由固定表兜底,而不是靠沙箱。已知盲区一处:**读命令的裸文件名参数**(`cat notes.txt`)不被收集为目标,所以把 `out read` 调成 `ask` 时只有绝对路径形状的读目标会被问——读本身不会写,四格模式的写侧不受影响。
 
 ---
 
@@ -353,6 +380,7 @@ pnpm test         # vitest(全部功能单元测试)
 
 pnpm check:keybindings   # 用宿主自己的分发表审计本插件的按键
 pnpm check:compat        # 校验声明的 pi 下限:强制 4 条线窗口 + 向后 4 条线探针 → public floor
+pnpm approval-report     # 汇总本地审批日志(答复分布、目标目录、候选规则)
 ```
 
 ### 项目结构
@@ -363,6 +391,7 @@ src/
 ├── lib/                  # 共享基础设施(工具集快照/恢复、
 │                         # 组合 tool_call 策略的闸门总线、
 │                         # 边界闸门会查询的自封闭工具登记表、
+│                         # 滚动 JSONL 审批日志、
 │                         # review 与 compact 共用的模型 key 解析)
 └── features/             # 功能模块 —— 一个功能一个目录
     ├── ask/              # ask 模式:命令 + 状态机、bash 沙箱、
@@ -375,7 +404,8 @@ src/
     ├── favorites/        # 模型收藏:选择器与循环 patch、
     │                     #           持久化存储、测试
     ├── permission/       # 会话级边界权限:模式、面板、bash 拆解、
-    │                     #           策略、会话授权、确认对话框、测试
+    │                     #           策略、会话授权、确认对话框、
+    │                     #           审计 payload、测试
     ├── review/           # 第三方评审:输入/指令触发、
     │                     #           评审模型配置存储、提示词、测试
     └── stash/            # 提示词暂存:热键状态机 + 测试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andares/pi-toolkits",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "Integrated toolkit extension for pi — ask mode (read-only Q&A), session-scoped permission checks, model favorites, prompt stash, third-party code review, session autostart, and a dedicated compaction model",
   "type": "module",
   "license": "MIT",
@@ -61,6 +61,7 @@
     "test": "vitest run",
     "check:keybindings": "node ./scripts/check-keybindings.mjs",
     "check:compat": "node ./scripts/check-compat.mjs",
+    "approval-report": "node ./scripts/approval-report.mjs",
     "release:github": "node ./scripts/release-github.mjs",
     "release": "node ./scripts/publish.mjs",
     "tag-current": "node ./scripts/tag-current.mjs"

package/src/features/permission/audit.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Permission audit payload: the decomposition, the scope/effect of every
+ * target, and the machine-readable rule layer must survive into the log.
+ */
+import { mkdtempSync, realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { buildPermissionAudit, commandDigest } from "./audit.js";
+import { DEFAULT_MODES, type PermissionModes } from "./constants.js";
+import { canonicalize } from "./paths.js";
+import {
+	decideProgram,
+	decideUnit,
+	type PolicyContext,
+} from "./policy.js";
+import { SessionRules } from "./session-rules.js";
+import { parseCommandUnits } from "./units.js";
+
+function project(): string {
+	return realpathSync(mkdtempSync(join(tmpdir(), "pi-perm-audit-")));
+}
+
+function makeContext(
+	cwd: string,
+	modes: PermissionModes = DEFAULT_MODES,
+	rules = new SessionRules(),
+): PolicyContext {
+	return { modes, roots: [canonicalize(cwd)], rules };
+}
+
+function audit(command: string, ctx: PolicyContext, prompt?: readonly string[]) {
+	const units = parseCommandUnits(command, ctx.roots[0] ?? "/");
+	return buildPermissionAudit({
+		cwd: ctx.roots[0] ?? "/",
+		modes: ctx.modes,
+		roots: ctx.roots,
+		units,
+		unitDecisions: units.map((unit) => decideUnit(unit, ctx)),
+		decision: decideProgram(units, ctx),
+		...(prompt === undefined ? {} : { prompt }),
+	});
+}
+
+describe("permission audit payload", () => {
+	it("records the decomposition, target scope and deciding layer", () => {
+		const cwd = project();
+		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd));
+
+		expect(payload.modes).toEqual({
+			inRead: "allow",
+			inWrite: "allow",
+			outRead: "allow",
+			outWrite: "ask",
+		});
+		expect(payload.roots).toEqual([canonicalize(cwd)]);
+		expect(payload.units).toEqual([
+			expect.objectContaining({
+				head: "rm",
+				command: "rm",
+				args: ["-rf", "/tmp/outside/x"],
+				base: canonicalize(cwd),
+				effect: "write",
+				opaque: false,
+				action: "ask",
+				layer: "mode",
+				targets: [
+					{
+						path: "/tmp/outside/x",
+						canonical: "/tmp/outside/x",
+						effect: "write",
+						source: "operand",
+						scope: "out",
+					},
+				],
+			}),
+		]);
+		expect(payload.verdict).toMatchObject({
+			action: "ask",
+			layer: "mode",
+			unit: 0,
+			target: "/tmp/outside/x",
+			effect: "write",
+			scope: "out",
+			grantScope: "root",
+			grantRoot: "/tmp/outside",
+		});
+	});
+
+	it("keeps the secret-table layer for a denied credential read", () => {
+		const cwd = project();
+		const payload = audit(`cat ${homedir()}/.ssh/id_rsa`, makeContext(cwd));
+		expect(payload.verdict).toMatchObject({
+			action: "deny",
+			layer: "secret",
+			scope: "out",
+			effect: "read",
+		});
+		expect(String((payload.verdict as Record<string, unknown>).reason)).toContain(
+			"fixed safety table",
+		);
+	});
+
+	it("marks an opaque command and records a command-scoped grant", () => {
+		const cwd = project();
+		const command = 'git -C "$DIR" log';
+		const ctx = makeContext(cwd);
+		const units = parseCommandUnits(command, cwd);
+		const payload = audit(command, ctx);
+
+		expect(units[0]?.opaque).toBe(true);
+		expect((payload.units as Array<Record<string, unknown>>)[0]).toMatchObject({
+			opaque: true,
+			action: "ask",
+			layer: "opaque",
+		});
+		expect(payload.verdict).toMatchObject({
+			action: "ask",
+			layer: "opaque",
+			grantScope: "command",
+			grantDigest: commandDigest(units),
+		});
+		expect(
+			(payload.verdict as Record<string, unknown>).grantRoot,
+		).toBeUndefined();
+	});
+
+	it("records an in-project mode allow with its layer", () => {
+		const cwd = project();
+		const payload = audit(`rm -rf ${cwd}/build`, makeContext(cwd));
+		expect(payload.verdict).toMatchObject({
+			action: "allow",
+			layer: "mode",
+			scope: "in",
+		});
+	});
+
+	it("carries the exact prompt lines when asked", () => {
+		const cwd = project();
+		const payload = audit("rm -rf /tmp/outside/x", makeContext(cwd), [
+			"Permission required",
+			"Command: rm -rf /tmp/outside/x",
+		]);
+		expect(payload.prompt).toEqual([
+			"Permission required",
+			"Command: rm -rf /tmp/outside/x",
+		]);
+	});
+
+	it("clips long arguments but keeps the target", () => {
+		const cwd = project();
+		const longArg = `--flag=${"x".repeat(2000)}`;
+		const payload = audit(`rm -rf /tmp/outside/x ${longArg}`, makeContext(cwd));
+		const unit = (payload.units as Array<Record<string, unknown>>)[0];
+		const args = unit.args as string[];
+		expect(args[2]).toContain("[+");
+		expect(unit.targets).toHaveLength(1);
+	});
+});

package/src/features/permission/audit.ts

@@ -0,0 +1,145 @@
+/**
+ * permission feature — the audit payload.
+ *
+ * The gate bus owns the record envelope (session, tool call, answer, outcome);
+ * this module contributes the part only the permission layer knows: the four
+ * modes and session roots in force, the bash decomposition, and which rule
+ * produced the verdict.
+ *
+ * The payload is deliberately lossless for *policy analysis* — every unit and
+ * every target survives, including the parser's `opaque` note — while being
+ * bounded: units, targets, args and long strings are capped, and the final
+ * serializer drops detail with a visible `truncated` marker rather than
+ * silently cutting a field. File contents never enter this payload.
+ */
+import { createHash } from "node:crypto";
+import type { ApprovalRecord } from "../../lib/approval-log.js";
+import { clipText } from "../../lib/approval-log.js";
+import type { PermissionModes } from "./constants.js";
+import { canonicalize, insideAnyRoot } from "./paths.js";
+import {
+	decisionGrantRoot,
+	type PolicyDecision,
+} from "./policy.js";
+import type { CommandUnit } from "./units.js";
+
+const MAX_UNITS = 32;
+const MAX_TARGETS = 32;
+const MAX_ARGS = 64;
+const ARG_CHARS = 512;
+const RAW_CHARS = 8192;
+const PATH_CHARS = 1024;
+const NOTE_CHARS = 512;
+const REASON_CHARS = 2048;
+
+export interface PermissionAuditInput {
+	readonly cwd: string;
+	readonly modes: PermissionModes;
+	/** Canonical session roots (working directory plus added directories). */
+	readonly roots: readonly string[];
+	readonly units: readonly CommandUnit[];
+	/** Verdict for each unit, in the same order as {@link units}. */
+	readonly unitDecisions: readonly PolicyDecision[];
+	/** Aggregate verdict (the strictest unit wins). */
+	readonly decision: PolicyDecision;
+	/** Exact dialog lines, when this payload belongs to an ask. */
+	readonly prompt?: readonly string[];
+}
+
+/** Short digest of the command text, for grouping opaque grants. */
+export function commandDigest(units: readonly CommandUnit[]): string {
+	return createHash("sha256")
+		.update(units.map((unit) => unit.raw).join(" ; "))
+		.digest("hex")
+		.slice(0, 16);
+}
+
+function serializeUnit(
+	unit: CommandUnit,
+	decision: PolicyDecision | undefined,
+	roots: readonly string[],
+): ApprovalRecord {
+	const targets = unit.targets.slice(0, MAX_TARGETS).map((target) => {
+		const canonical = canonicalize(target.path);
+		return {
+			path: clipText(target.path, PATH_CHARS),
+			canonical: clipText(canonical, PATH_CHARS),
+			effect: target.effect,
+			source: target.source,
+			scope: insideAnyRoot(roots, canonical) ? "in" : "out",
+		};
+	});
+	return {
+		raw: clipText(unit.raw, RAW_CHARS),
+		head: unit.headWord,
+		command: unit.command,
+		args: unit.args.slice(0, MAX_ARGS).map((arg) => clipText(arg, ARG_CHARS)),
+		base: unit.base === null ? null : clipText(canonicalize(unit.base), PATH_CHARS),
+		effect: unit.effect,
+		opaque: unit.opaque,
+		...(unit.note === undefined ? {} : { note: clipText(unit.note, NOTE_CHARS) }),
+		...(decision === undefined
+			? {}
+			: { action: decision.action, layer: decision.layer }),
+		targets,
+	};
+}
+
+function serializeVerdict(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const decision = input.decision;
+	const unitIndex = input.units.indexOf(decision.unit);
+	const target = decision.target;
+	const grantScope = decision.unit.opaque ? "command" : "root";
+	return {
+		action: decision.action,
+		layer: decision.layer,
+		...(unitIndex < 0 ? {} : { unit: unitIndex }),
+		...(target === undefined
+			? {}
+			: {
+					target: clipText(target.path, PATH_CHARS),
+					effect: target.effect,
+					scope: target.scope,
+				}),
+		grantScope,
+		...(grantScope === "root"
+			? {
+					grantRoot: clipText(
+						decisionGrantRoot(decision, () => input.cwd),
+						PATH_CHARS,
+					),
+				}
+			: { grantDigest: commandDigest(input.units) }),
+		...(decision.reason === undefined
+			? {}
+			: { reason: clipText(decision.reason, REASON_CHARS) }),
+	};
+}
+
+/** Structured audit fields for one permission decision. */
+export function buildPermissionAudit(
+	input: PermissionAuditInput,
+): ApprovalRecord {
+	const unitDecisions = input.unitDecisions;
+	return {
+		modes: {
+			inRead: input.modes.inRead,
+			inWrite: input.modes.inWrite,
+			outRead: input.modes.outRead,
+			outWrite: input.modes.outWrite,
+		},
+		roots: input.roots
+			.slice(0, 16)
+			.map((root) => clipText(root, PATH_CHARS)),
+		units: input.units
+			.slice(0, MAX_UNITS)
+			.map((unit, index) => serializeUnit(unit, unitDecisions[index], input.roots)),
+		...(input.units.length > MAX_UNITS
+			? { unitsOmitted: input.units.length - MAX_UNITS }
+			: {}),
+		verdict: serializeVerdict(input),
+		...(input.prompt === undefined ? {} : { prompt: [...input.prompt] }),
+	};
+}