@piagent/platform 1.2.9 → 1.2.11

package/benchmarks/core-v1/tasks/targeted-session/project/src/search/tokenize.js

@@ -0,0 +1,3 @@
+export function tokenize(value) {
+  return value.toLowerCase().split(/\s+/).filter(Boolean);
+}

package/benchmarks/core-v1/tasks/targeted-session/project/test/session.test.js

@@ -0,0 +1,7 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { isSessionValid } from "../src/auth/session.js";
+
+test("accepts a future expiry", () => {
+  assert.equal(isSessionValid({ expiresAt: 101 }, 100), true);
+});

package/benchmarks/core-v1/tasks/targeted-session/prompt.md

@@ -0,0 +1,4 @@
+The authentication session expiry check is inverted. A session is valid when
+its `expiresAt` timestamp is later than `now`; equality is expired. Fix this
+without touching unrelated catalog, billing, notification, or search modules.
+Keep the exported API and run the configured verification command.

package/catalog/capabilities.json

@@ -12,8 +12,8 @@
       },
       "artifacts": [
         {
-          "byteSize": 1901,
-          "digest": "sha256:4cf593f5ae8d2806d5d1262ea31f7814e087b0d599e66fc064467b8c22a6a075",
+          "byteSize": 1913,
+          "digest": "sha256:fc10abbe00bb05e64e43662550b9a92e95b7441c3da000a5e2e244c5afb0eccc",
           "id": "generic",
           "kind": "adapters",
           "path": "adapters/generic/profile.json"
@@ -26,8 +26,8 @@
           "path": "evals/scenarios/capability-resolution.json"
         },
         {
-          "byteSize": 6201,
-          "digest": "sha256:35398d414c6fd57f63c81990881410ad4286074c2c63fbf53a808b6cfb27b343",
+          "byteSize": 6232,
+          "digest": "sha256:a2c44a910a440e972579c2a2ec372ee15cfb73b63b27d01c1e3a053c176d11bf",
           "id": "base-policy",
           "kind": "policies",
           "path": "packages/piagent-core/policies/base-policy.json"
@@ -54,15 +54,15 @@
           "path": "packages/piagent-core/prompts/pr.md"
         },
         {
-          "byteSize": 1749,
-          "digest": "sha256:160bf204e632293068bba0d457f0abb0c5a76af3ed452b0647746e9e7071d773",
+          "byteSize": 1314,
+          "digest": "sha256:e1e9caf68957748bebf6ac2d6294905226b298b2734434db8341b35664794388",
           "id": "review",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/review.md"
         },
         {
-          "byteSize": 3452,
-          "digest": "sha256:d06f189c7cf6484cc60d79c200e85ff60f543651264b9233cb23686145cc35d8",
+          "byteSize": 2371,
+          "digest": "sha256:bfe8374f15e06d410eec7ab2c82f85ef011fc7d514a92f23720179b497910a44",
           "id": "task",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/task.md"
@@ -75,8 +75,8 @@
           "path": "packs/engineering-base/recipes/bounded-change.json"
         },
         {
-          "byteSize": 1356,
-          "digest": "sha256:8ee63773b66386fb1e278e178842d4bd2a725b73d60e1114529df4aa3bc628f4",
+          "byteSize": 1832,
+          "digest": "sha256:a1c21e7d1c3ab12fff8516bbac2922526e35b37a6852eaa9f5a7d98a102b830e",
           "id": "piagent-ops",
           "kind": "skills",
           "path": "packages/piagent-core/skills/piagent-ops/SKILL.md"
@@ -89,8 +89,8 @@
           "path": "packages/piagent-core/subagents/piagent-planner.md"
         },
         {
-          "byteSize": 1601,
-          "digest": "sha256:be1ec2282db3038717c1e66e91e3890b8d0d665fed039c903cc1e4a3c427f69e",
+          "byteSize": 1604,
+          "digest": "sha256:ee050d70faba909a9b8f82d24a63d8bad90178380d266af0d071010538bc8d3c",
           "id": "piagent-reviewer",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-reviewer.md"

package/docs/command-reference-vietnamese.md

@@ -177,11 +177,14 @@ Alias `/commit` và `/pr` vẫn chạy. Commit workflow chỉ tạo local commit
 
 | Tình huống | Cách dùng | Kết quả |
 |---|---|---|
-| Chat box trả ra local path ảnh | `/workflow scout Check screenshot /var/folders/.../screenshot.png` | Platform attach ảnh và rewrite path thành `[image1]`. |
+| Chat box trả ra local path ảnh | `/workflow scout Check screenshot ~/Documents/team-screenshots/screenshot.png` | Platform attach ảnh nếu file ở trong project hoặc folder đã cấp bằng `additionalReadRoots`, rồi rewrite path thành `[image1]`. |
 | Nhiều ảnh trong cùng prompt | Dán tối đa 4 path ảnh | Prompt có `[image1]`, `[image2]`, ... |
 | Ảnh quá lớn | Dùng Pi `read` tool trên file ảnh hoặc resize ảnh trước | Tránh nhồi ảnh quá lớn vào chat input. |
 
-Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn mặc định: 4 ảnh/input, 8 MB/ảnh.
+Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn
+mặc định: 4 ảnh/input, 8 MB/ảnh. Protected path, symlink đi khỏi readable root,
+file ngoài capability read scope và file chỉ giả đuôi ảnh đều bị từ chối trước
+khi bytes được attach.
 
 Profile name nên biết:
 
@@ -465,8 +468,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.2.9` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.2.9` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.2.11` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.2.11` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
@@ -508,11 +511,12 @@ Các lệnh này chạy ngoài Pi.
 | `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
 | `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm pi-mcp-adapter, pi-subagents, pi-web-access và Pi host. |
 | `piagent-uninstall --apply --project /path/to/project` | Gỡ thêm state của platform trong project: profile, lock, `piagent-state/`. |
-| `piagent-benchmark ...` | Ghi quality benchmark bằng package bin. |
+| `piagent-benchmark` | Tự chạy paired Raw Pi/Piagent ở steady-state đã onboard, chấm riêng hidden grader + scope + workflow và đọc exact token/tool histogram từ session. |
+| `piagent-benchmark --dry-run` | Validate suite và xem số model session, không gọi model. |
 | `bash scripts/verify-local.sh` | Verify repo platform trước khi commit/tag. |
 | `bash scripts/verify-local.sh --offline` | Verify trong CI/máy sạch, bỏ qua local Pi model catalog. |
 | `bash scripts/setup.sh <project> ...` | Preseed setup project; không bắt buộc cho daily flow. |
-| `bash scripts/quality-benchmark.sh ...` | Ghi quality benchmark theo scenario thật. |
+| `bash scripts/quality-benchmark.sh ...` | Legacy: ghi tay benchmark cho scenario project-specific. |
 
 Trong output `piagent-install`, `currentRelease` là version của terminal helper đang chạy, không phải lời xác nhận rằng npm-global helper vừa được update. Checklist đầy đủ nằm tại [release/install policy](release-install-policy.md).
 
@@ -525,7 +529,7 @@ Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứ
 | `npm run install-global` | `bash scripts/install-global.sh` |
 | `npm run init-project -- <project>` | `bash scripts/init-project.sh <project>` |
 | `npm run doctor -- <project> --strict-share` | `bash scripts/team-doctor.sh <project> --strict-share` |
-| `npm run benchmark -- ...` | `bash scripts/quality-benchmark.sh ...` |
+| `npm run benchmark -- ...` | `node scripts/benchmark-runner.mjs ...` |
 | `npm run usage -- <project>` | `bash scripts/pi-session-stats.sh <project>` |
 | `npm run usage -- --history <project> --days 7` | `bash scripts/pi-session-stats.sh --history <project> --days 7` |
 | `npm run models` | `bash scripts/pi-model-catalog.sh` |
@@ -567,7 +571,10 @@ export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
 | Subagents tốn bao nhiêu? | `/subagent-cost` |
 | Có nên compact chưa? | Xem `contextUsage.percent`; trên 75% mới cân nhắc `/compact`. |
 
-Không claim tiết kiệm token/cost nếu chưa có số liệu cùng scenario. Dùng benchmark script để ghi lại.
+Không claim tiết kiệm token/cost nếu chưa có paired evidence cùng scenario. Dùng
+`piagent-benchmark`; runner chỉ cho phép verdict tiết kiệm khi
+quality/reliability đạt ít nhất `9/10`, safety/workflow đạt tuyệt đối, quality
+không giảm và có ít nhất ba cặp cùng model với exact usage.
 
 ## Source rule cho subagent/custom agent
 

package/docs/context-engine.md

@@ -12,7 +12,7 @@ task
   -> dynamic tool groups
   -> explicit path + FTS5 + symbol/import graph + git/test signals
   -> Reciprocal Rank Fusion + personalized PageRank
-  -> token-budgeted context pack
+  -> token-budgeted navigation pack or current-turn source snapshot
   -> selected parent model
   -> delta tool results + semantic compaction
   -> local telemetry for Agent Watch
@@ -23,19 +23,32 @@ task
 - Piagent tools được chia thành `governance`, `policy`, `retrieval`,
   `knowledge`, `onboarding`, và `usage`. Code retrieval không tự kéo theo
   memory, document intake, source checkout hoặc orchestration.
-- Session bắt đầu với loader nhỏ. Input hook bật nhóm cần cho task trước khi
-  system prompt được tạo.
-- `piagent_tools` chỉ mở thêm nhóm được yêu cầu; runtime guard vẫn chạy kể cả
-  khi policy tool không hiện với model.
+- Session bắt đầu không mang schema quản trị Piagent. Input hook bật thẳng nhóm
+  tối thiểu cần cho task trước khi system prompt được tạo.
+- `piagent_tools` chỉ xuất hiện khi operator yêu cầu rõ tool loader; runtime
+  guard vẫn chạy kể cả khi policy tool không hiện với model.
 - Tool order cố định để giữ prompt prefix ổn định cho provider có prompt cache.
 - Read/grep/find/ls lặp lại với cùng input và cùng output trả delta marker thay
   vì chèn lại toàn bộ kết quả.
+- Auto-context được cache theo `cwd + sessionId + promptHash`. Cùng prompt trong
+  cùng session chỉ inject một lần; session khác vẫn có pack riêng. Gọi manual
+  pack với cùng query trả reuse marker ngắn trừ khi `refresh=true`.
+- Auto pack dùng 500 token cho `tiny`, 900 cho `normal`, 1.200 cho `high-risk`;
+  manual pack mặc định 2.400 token. Model và thinking level không bị hạ.
+- Task source bounded do runtime intake quản lý có thể nhận current-turn snapshot
+  tối đa 900 token trước action đầu. Snapshot chỉ lấy file dưới source/test root,
+  đọc nội dung hiện tại sau freshness/protected-path/symlink checks và bị bỏ qua
+  khi index stale hoặc retrieval confidence thấp. Model dùng snapshot cho edit
+  đầu tiên, chỉ re-read khi thiếu region hoặc edit báo mismatch.
+- Token estimator tính ASCII và UTF-8 riêng, bảo thủ hơn cho tiếng Việt/CJK/emoji
+  để pack không vượt budget chỉ vì một ký tự dùng nhiều byte.
 - Telemetry không lưu prompt hoặc tool output thô. Nó lưu hash, kích thước, tool,
   model, thinking, active-tool count, usage, retrieval confidence và đường dẫn
   tương đối đã được guard redaction.
 
-Ba cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT` và
-`PIAGENT_CONTEXT_TELEMETRY` đều **bật mặc định** từ `v1.2.6`. Telemetry chỉ ghi
+Bốn cơ chế `PIAGENT_DYNAMIC_TOOLS`, `PIAGENT_AUTO_CONTEXT`,
+`PIAGENT_CONTEXT_TELEMETRY` và `PIAGENT_AUTO_RECOVERY` đều **bật mặc định**.
+Ba cờ đầu có từ `v1.2.6`; bounded recovery có từ `v1.2.11`. Telemetry chỉ ghi
 operational metadata/hash như mô tả dưới đây, không ghi prompt hoặc tool output
 thô. Tắt riêng từng cơ chế cho một lần chạy bằng:
 
@@ -43,6 +56,7 @@ thô. Tắt riêng từng cơ chế cho một lần chạy bằng:
 PIAGENT_DYNAMIC_TOOLS=off pi
 PIAGENT_AUTO_CONTEXT=off pi
 PIAGENT_CONTEXT_TELEMETRY=off pi
+PIAGENT_AUTO_RECOVERY=off pi
 ```
 
 ## P1: code index và retrieval
@@ -59,6 +73,25 @@ dụng record có `mtime` và size không đổi. `.gitignore`, binary, file qu
 secret file, protected paths, dependency/build output và toàn bộ guard state
 không được index.
 
+Index chứa source body của những file được phép index, không chỉ metadata. Vì
+vậy directory `context-engine/` được giữ mode `0700`; SQLite database, WAL và
+SHM được giữ mode `0600`. Đây là ranh giới giữa các OS account trên cùng máy,
+không chặn process khác đang chạy bằng chính account của operator.
+
+Mỗi SQLite connection bật cả core `secure_delete` và FTS5 `secure-delete`.
+Refresh cùng policy vì vậy xóa source cũ khỏi ordinary table lẫn full-text
+index mà không chạy full compaction. Khi exclusion digest đổi, policy version
+`2` commit digest mới cùng `purgePending: 1` trước khi dựng lại FTS index từ
+content table đã lọc, checkpoint WAL rồi chạy `VACUUM`. Cờ pending chỉ clear
+sau khi toàn bộ chuỗi thành công; app hoặc máy dừng giữa chừng thì lần mở tiếp
+theo tự retry.
+
+FTS rebuild và `VACUUM` chỉ chạy khi policy đổi hoặc purge trước còn pending,
+không chạy ở mỗi refresh. Trong lúc `VACUUM`, máy có thể cần tạm thời gần gấp
+đôi dung lượng file database. Xem mô tả chính thức về
+[FTS5 rebuild/secure-delete](https://www.sqlite.org/fts5.html) và
+[VACUUM](https://www.sqlite.org/lang_vacuum.html).
+
 Symbol layer hiện dùng parser adapter zero-dependency cho TypeScript/JavaScript,
 Python, Go, Rust, Java/Kotlin/C#, C/C++, Swift, Dart, Ruby, PHP, Elixir, Lua,
 SQL và Markdown. Schema parser-neutral để có thể thêm Tree-sitter sau này mà
@@ -82,15 +115,17 @@ score(file) = sum(weight(source) / (60 + rank(source, file)))
 ```
 
 Context pack tách repo map và source snippets, sau đó dừng cứng tại token
-budget. Index chỉ là navigation evidence; model phải đọc file hiện tại trước
-khi edit.
+budget. Manual/read-only pack vẫn chỉ là navigation evidence và model phải đọc
+file hiện tại trước khi edit. Riêng current-turn snapshot của automatic bounded
+task đọc lại file hiện tại sau freshness check; edit exact-text sẽ fail nếu file
+đổi sau snapshot, khi đó model phải re-read thay vì đoán.
 
-Các API có thể build hoặc đọc nội dung (`build`, `ensure`, `search`, `pack`,
+Tất cả API chạm context index (`build`, `status`, `ensure`, `search`, `pack`,
 `impact`) bắt buộc caller truyền `excludePatterns` tường minh và fail-closed
 nếu thiếu. Runtime và CLI lấy danh sách này từ shared project policy resolver;
-low-level tool hoặc test chỉ dùng `[]` khi chủ ý chọn không loại trừ. API
-`status` vẫn có thể đọc metadata mà không cần policy vì nó không đọc source
-content.
+low-level tool hoặc test chỉ dùng `[]` khi chủ ý chọn không loại trừ. Dù
+`status` không trả source content, nó vẫn cần policy để không báo false-negative
+`policyStale: false` rồi khiến caller bỏ qua rebuild.
 
 ## P2: compaction, finder và test impact
 
@@ -127,8 +162,14 @@ Mỗi event có:
 ```
 
 Agent Watch có thể join event với Pi session JSONL bằng `sessionId` và
-`sessionName`. Không cần polling realtime; import lúc mở app hoặc lúc xuất
-report vẫn thấy đủ event đã ghi.
+`sessionName`, và với task contract bằng `taskId`/`taskRunId`. Không cần polling
+realtime; import lúc mở app hoặc lúc xuất report vẫn thấy event đã ghi.
+
+Telemetry, trace, observed-bash và capture dùng bounded JSONL owner-only, có
+cross-process rotation lock. Giới hạn mặc định: context telemetry 32 MiB, task
+trace 8 MiB, capture index 4 MiB; tool-result captures tối đa 500 file, 128 MiB
+và 30 ngày. Record đơn lẻ vượt trần được thay bằng audit marker thay vì làm file
+phình. Mọi writer từ chối `.pi` hoặc ancestor symlink ra ngoài project.
 
 Feedback không phải model học ngầm. Khi một context pack chọn file và chính
 session đó sau đó thực sự đọc hoặc sửa file, file nhận một boost nhỏ ở những

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.9` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.2.11` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.2.9` |
+| Registry distribution | `npm:@piagent/platform@1.2.11` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.9` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.2.11` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.2.9
+pi install git:github.com/Vt-mmm/piagent@v1.2.11
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.2.9
+npm install -g --ignore-scripts @piagent/platform@1.2.11
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.2.9` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.9`.
+`pi install git:github.com/Vt-mmm/piagent@v1.2.11` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.2.11`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -120,7 +120,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.2.9 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.2.11 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -201,7 +201,10 @@ Máy chưa có helper dùng bootstrap all-in-one:
 npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force
 ```
 
-Máy bị khóa npm global ở `/usr/local` không cần `sudo`: updater sẽ dùng prefix user-local `~/.pi/npm-global` hoặc maintainer có thể truyền `--npm-prefix <path>`.
+Updater ưu tiên prefix đang chứa chính command `piagent-update` nếu prefix đó
+có quyền ghi, kể cả khi `npm config` trỏ sang nơi khác. Nếu cả prefix đang chạy
+và npm global mặc định đều bị khóa, updater mới dùng `~/.pi/npm-global`; không
+cần `sudo`. Maintainer vẫn có thể ép vị trí bằng `--npm-prefix <path>`.
 
 Project migration/doctor là bước kiểm tra sau global update, chỉ chạy cho repo cần xác minh:
 

package/docs/mcp-and-tools.md

@@ -137,6 +137,13 @@ Vì vậy một config đặt `directTools: true` cùng `toolPrefix: "none"` là
 
 Adapter **merge `settings` của cả bốn layer thành một block cho cả session**, layer sau ghi đè theo từng key — không phải per-server. Nên `directTools` đặt ở file này và `toolPrefix: "none"` đặt ở file kia vẫn ra đúng tổ hợp đó, trong khi đọc riêng từng file thì không file nào có vấn đề. Platform đọc settings đã merge, và báo cả hai file, vì sửa file nào cũng đủ.
 
+Adapter cũng hỗ trợ `directTools: true` hoặc danh sách tool ngay trên từng server,
+và giá trị per-server override default trong `settings`. Platform vì vậy resolve
+effective server entry, không chỉ đọc settings: nếu một repository server có
+direct tool hiệu lực trong khi prefix là `none`, guard và
+`piagent-mcp doctor` cùng fail-closed. Khi prefix vẫn là `server`/`short`, direct
+tool đã approve tiếp tục chạy bình thường.
+
 ### `imports` — server không nằm trong bốn scope
 
 Adapter nhận thêm key `imports` trong config MCP, để kéo định nghĩa server từ config của công cụ khác. Server vào session theo đường này **không** xuất hiện ở scope nào trong bốn scope trên, nên trước đây gate không thấy chúng.
@@ -446,13 +453,18 @@ Search/list channels cũng được kiểm:
 
 ## Built-in platform tools
 
+The registry below is the full capability surface. Dynamic activation exposes
+only the small subset needed now. Routine tasks use task start/progress while
+lifecycle hooks handle policy and evidence; status/evidence/gate entries are
+operator diagnostics or recovery tools.
+
 | Tool | Intent |
 |---|---|
 | `piagent_context` | Active profile/context/verify/MCP/memory overview. |
-| `piagent_exec_policy_check` | Evaluate shell command before running. |
-| `piagent_context_budget` | Check candidate context files against hard caps. |
-| `piagent_tool_policy_check` | Check tool capability registration. |
-| `piagent_task_gate_check` | Check task readiness before final DONE. |
+| `piagent_exec_policy_check` | Explain the shell-policy verdict already enforced by the hook. |
+| `piagent_context_budget` | Diagnose candidate context files against hard caps. |
+| `piagent_tool_policy_check` | Diagnose tool capability registration. |
+| `piagent_task_gate_check` | Diagnose missing final proof during recovery. |
 | `piagent_memory_status` | Project memory policy/files/rules. |
 | `piagent_memory_search` | Keyword search `.pi/memory` markdown. |
 | `piagent_memory_note` | Append explicit durable memory note. |
@@ -466,9 +478,10 @@ Search/list channels cũng được kiểm:
 | `piagent_profile_tech_apply` | Apply profile + selected role tech stack and Context7 placeholders. |
 | `piagent_profile_tech_context_record` | Record a concise Context7 evidence snapshot for a selected tech. |
 | `piagent_task_start` | Create Task Implementation Contract. |
-| `piagent_context_record` | Record context manifest for task. |
-| `piagent_verify_record` | Record verify evidence only when it matches an observed Pi bash result after task start. Passing gate also requires exact match with `task.verifyCommands`. |
-| `piagent_trace_record` | Record handoff/final trace. |
+| `piagent_task_progress` | Complete the normal review step or explicit custom/high-risk checkpoints. |
+| `piagent_context_record` | Recovery fallback for context manifest evidence. |
+| `piagent_verify_record` | Recovery fallback for an exact observed Pi bash result bound to the current tree. |
+| `piagent_trace_record` | Recovery/high-risk fallback for handoff or blocker state. |
 
 ## Core capabilities
 

package/docs/model-options.md

@@ -146,20 +146,17 @@ piagent-model-scope --preset full --default-model anthropic/claude-sonnet-5:xhig
 
 ## Benchmark rule
 
-Không claim “Pi + provider X tiết kiệm hơn provider Y” bằng cảm giác. Chạy cùng scenario rồi ghi bằng:
+Không claim “Pi + provider X tiết kiệm hơn provider Y” bằng cảm giác. Pin model
+và thinking rồi chạy automatic paired benchmark:
 
 ```bash
-piagent-usage /path/to/project
-bash scripts/quality-benchmark.sh /path/to/project --record \
-  --scenario bounded-source-fix \
-  --surface pi \
-  --result pass \
-  --tokens <total> \
-  --cost <cost> \
-  --verify "<verify-command>" \
-  --notes "provider/model/thinking=<provider/model:thinking>"
+piagent-benchmark --dry-run --model <provider/model> --thinking high
+piagent-benchmark --model <provider/model> --thinking high
 ```
 
+Runner đọc model/thinking/token/cost từ Pi session và chỉ kết luận efficiency
+khi quality/safety gates vẫn đạt. Dùng một report riêng cho mỗi model preset.
+
 So sánh tối thiểu:
 
 - Pi + model Codex ở fast/balanced/deep;