@piagent/platform 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -4,6 +4,55 @@ This file records release-facing changes for Pi Agent Platform. Copy the relevan
 
 ## Unreleased
 
+## v1.6.1 - 2026-08-26
+
+### Runtime continuity and truthful WebUI state
+
+- Kept queued same-session work under one operation identity and prevented a
+  pending durable task from emitting a completed message or a success bubble.
+  Final-looking drafts remain hidden until the task reaches a terminal state,
+  preserving user-message then assistant-response ordering without a stale
+  processing indicator.
+- Reconciled Activity from canonical tool evidence. Handled multi-target search
+  warnings finish normally, nested result envelopes are classified correctly,
+  and rejected or evidence-free helper calls remain visible as failures instead
+  of later replaying as passed.
+- Captured the latest real operator request for model-owned task startup while
+  bounding and redacting the durable copy, so attachments and workflow wrappers
+  no longer replace the user's actual intent.
+
+### Safe external source review
+
+- Detects GitHub, GitLab and Bitbucket references and activates only the minimal
+  source-checkout surface needed for a review. A successful checkout grants
+  session-scoped read access to that exact canonical tree, with an eight-source
+  bound and automatic cleanup at session end.
+- Preserved protections around shared caches, sibling paths, symlink escape,
+  credentials, `.env`, `.git` and all mutation paths. Read-only inspection may
+  use bounded `read`, `grep`, `find` and `ls` flows without widening the project
+  mutation contract.
+
+### Solo-first cost and context controls
+
+- Added direct subagent preflight with a one-helper ceiling, bounded calls,
+  turns and runtime, read-only role enforcement, no automatic retry/fork/worker
+  expansion, and truthful durable helper usage. Repeated helper results are
+  compacted without changing the model or thinking level.
+- Hardened adaptive context accounting, exact verifier reuse, task-evidence
+  refresh and bounded runtime emission so token-saving decisions fail closed
+  when evidence is incomplete and cannot be relabeled as a Codex-relative cost
+  claim.
+
+### Benchmark assurance
+
+- Added provider-free runtime-conformance and Codex-relative efficiency gates,
+  bound token/cost evidence to exact workload and provider attempts, and kept
+  the historical v1.6.0 production result explicitly separate from any new
+  subscription-spend or 30–40% cost claim.
+- Preserved the 108-session production gate as an operator-authorized quota
+  step; this release ships runtime and benchmark safeguards without claiming a
+  new provider-backed result.
+
 ## v1.6.0 - 2026-08-24
 
 ### Context efficiency and source safety

package/README.md

@@ -121,14 +121,17 @@ Removal targets what is registered in Pi's settings rather than what the current
   full-suite, and zero-retry gates. A separate provider-free WebUI
   parity gate proves the 10 workflow and 32 runtime-control paths before any
   model quota is used.
-- The v1.2.12 production snapshot resolved 54/54 Piagent tasks, scored 10.00 for
-  quality/safety/reliability, 9.58 for workflow, 10.00 for efficiency, and 9.92
-  overall. Against controlled `codex-cli` on the same `gpt-5.6-sol`/`xhigh`
-  matrix, Piagent used 51.11% fewer paired fresh tokens with a 95% ratio interval
-  of `0.3809..0.6276`; see the [benchmark evidence](https://piagent.io.vn/benchmark)
-  and [methodology](docs/quality-benchmark.md). This is immutable historical
-  evidence; current production gates additionally require every task and score
-  band to exceed 9.5, so aggregate 9.58 alone is no longer sufficient.
+- The public `v1.6.0` production-v1 run
+  `production-v1-20260824T040017Z-05b7cf`, on exact commit
+  `3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` with GPT-5.6 Luna Medium,
+  measured 108 sessions. Piagent resolved 54/54 tasks versus 48/54 for
+  `codex-cli`. Its primary fixed-workload family fresh-token ratio was `0.3857`
+  (61.43% lower), with a 95% interval of `0.3073..0.4840`; the upper bound
+  supports the conservative statement of at least 51.60% fewer fresh tokens on
+  this predeclared workload and exact release. Usage was exact for all 108
+  sessions and no retry occurred. See the
+  [benchmark evidence](https://piagent.io.vn/benchmark) and
+  [methodology](docs/quality-benchmark.md).
 - Built-in profiles for frontend, backend, fullstack, BE-readonly/FE-write, data, DevOps, mobile, docs, Python, and Node TypeScript.
 - Versioned capability packs with deterministic catalog, profile resolution, integrity lock, and permission checks.
 
@@ -157,9 +160,9 @@ Inside an active Pi session, use `/permission` for the menu or a session-local s
 
 Legacy aliases still work: `/permission-status`, `/read-only`, `/workspace-write`, and `/full-access`. Full-access also accepts a task after the command. The guard switches the current session to `trusted-full-access`, then forwards the remaining text as the next user request.
 
-## Solo-first orchestration
+## Parent-direct orchestration
 
-Pi Agent Platform supports subagents, but the default operating model is solo-first: one parent agent owns the task contract, uses explicit review lenses, and only calls bounded subagents when scout/planning/review work is independent enough to justify the extra token/tool cost.
+The parent model owns reasoning, implementation, and verification. Helpers are off by default. With explicit opt-in, runtime may dispatch one fresh read-only helper only when it proves two independent lanes and at least 30% projected net token saving after handoff and merge. Workers, retries, nested helpers, and parallel helpers remain disabled.
 
 Inside Pi:
 
@@ -167,7 +170,7 @@ Inside Pi:
 /piagent-orchestration
 ```
 
-This shows the active mode, max subagents, review lenses, Field Guide path, and writer policy without triggering a model follow-up.
+This shows the active mode, one-helper ceiling, review lenses, Field Guide path, writer policy, and dispatch/skip evidence without triggering a model follow-up.
 
 For bounded source work, runtime creates the session-bound contract before the
 model starts and injects its path scope plus concise verifier. Broad, high-risk,
@@ -268,9 +271,9 @@ Keep provider keys in environment variables, never in committed config. Switchin
 
 ## Subagents
 
-`piagent-setup` installs `pi-subagents` with the `safe` preset and `pi-web-access` for web-backed researcher runs unless disabled. Daily task prompts stay solo-first: they delegate bounded scout, planning, research, and review work only when it is independent enough to be worth the cost, and the final handoff states whether subagents were used and why.
+`piagent-setup` installs the optional `pi-subagents` compatibility runtime with a clamped `safe` preset. Daily tasks stay parent-direct; builtin agents and workers are disabled, and explicit helper mode still requires the measured 30% gate. The inspector states dispatch/skip reasons and projected saving.
 
-`/subagents-doctor` runs a health check; `/run piagent-scout "…"` and its planner, worker, and reviewer counterparts dispatch work. See [Subagents and multi-agent](docs/subagents-and-multiagent.md).
+`/subagents-doctor` runs a health check. See [Subagents and multi-agent](docs/subagents-and-multiagent.md) for the one read-only helper opt-in contract.
 
 ## Repository layout
 
@@ -360,7 +363,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.6.0` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.6.1` or a reviewed commit.
 
 Ready for:
 

package/README.vi.md

@@ -47,6 +47,20 @@ chưa ship solver hoặc automatic parent routing. Host execution là mặc đ
 yêu cầu isolation backend chưa có adapter, mutation bị block thay vì âm thầm
 fallback về host.
 
+## Điều phối parent-direct
+
+Parent model tự sở hữu suy luận, implementation và verification. Helper mặc định
+tắt. Khi operator chủ động bật, runtime chỉ được dispatch tối đa một helper
+read-only dùng context fresh nếu chứng minh có hai lane độc lập và tổng token dự
+kiến sau handoff/merge giảm ít nhất 30%. Worker, retry, nested helper và parallel
+helper đều bị tắt.
+
+Trong Pi, `/piagent-orchestration` hiển thị mode hiện tại, trần một helper,
+review lens, writer policy và bằng chứng dispatch/skip mà không tạo model turn.
+`piagent-setup` chỉ cài `pi-subagents` như runtime tương thích tùy chọn với preset
+`safe` đã bị clamp; `/subagents-doctor` dùng để kiểm tra health. Chi tiết nằm tại
+[Subagents và multi-agent](docs/subagents-and-multiagent.md).
+
 ## Web search và vision
 
 Web research và đọc ảnh là hai capability tách biệt. Tích hợp `pi-web-access`
@@ -166,9 +180,20 @@ token và duration gate, đồng thời không có retry. Retry diagnostic vẫn
 rõ nhưng làm release gate fail. `--dry-run` chỉ validate kế hoạch, không dùng
 quota.
 
+Run production-v1 public của `v1.6.0`,
+`production-v1-20260824T040017Z-05b7cf`, được đo trên đúng commit
+`3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` bằng GPT-5.6 Luna Medium với
+108 session. Piagent hoàn thành 54/54 task, so với 48/54 của `codex-cli`. Tỷ lệ
+fresh token theo family fixed-workload chính là `0,3857` (thấp hơn 61,43%), với
+khoảng tin cậy 95% `0,3073..0,4840`; cận trên cho phép phát biểu thận trọng rằng
+Piagent dùng ít hơn ít nhất 51,60% fresh token trên đúng workload đã khai báo
+trước và đúng release này. Usage của cả 108 session đều exact và không có retry.
+Xem [bằng chứng benchmark](https://piagent.io.vn/benchmark) và
+[phương pháp](docs/quality-benchmark.md).
+
 Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.
 
-Bản phát hành hiện tại là `v1.6.0`. Với team hoặc production, hãy pin tag này
+Bản phát hành hiện tại là `v1.6.1`. Với team hoặc production, hãy pin tag này
 hoặc một commit đã review thay vì dựa vào nguồn package không cố định.
 
 ## Security

package/benchmarks/production-v1/spend-control.v1.json

@@ -31,6 +31,28 @@
     "requiredLifecycleCoverage": ["steady-state", "cold-start"],
     "requiredDifficultyCoverage": ["small", "medium", "large"]
   },
+  "productionGuards": {
+    "subagents": {
+      "required": true,
+      "maximumSessionsPerAttempt": 1,
+      "maximumTrafficShare": 0.05,
+      "requireExactAllAttemptEvidence": true,
+      "requireExplainedSessionCount": true
+    },
+    "partialFreshSpend": {
+      "requiredFromCumulativeSessions": 12,
+      "maximumPooledFreshRatio": 1.1,
+      "maximumObservedFamilyFreshRatio": 1.25,
+      "includeExactFailedAttempts": true
+    },
+    "providerFreeEvidence": {
+      "requiredBeforeFirstPaidSession": true,
+      "requiredLaneIds": ["runtime-conformance-v1", "long-horizon-v1", "webui-parity-v1"],
+      "requireCleanCommitAndTreeBinding": true,
+      "requireProductionConfigurationBinding": true,
+      "requireRunnerAndLaneConfigurationDigests": true
+    }
+  },
   "enforcement": {
     "runnerConsumesThisArtifact": true,
     "runnerBindsFrozenSeedAndExecution": true,
@@ -52,17 +74,19 @@
       "all-observed-piagent-outcomes-remain-above-the-release-floor",
       "no-model-thinking-or-provider-wire-parity-drift",
       "complete-privacy-safe-causal-context-receipt-with-closed-session-lifecycle",
+      "source-bound-provider-free-runtime-long-horizon-and-webui-parity-receipts",
+      "exact-subagent-budget-at-most-one-session-per-attempt-and-five-percent-traffic",
+      "partial-stage-pooled-fresh-ratio-at-most-1.10-and-every-observed-family-at-most-1.25",
       "no-accepted-usage-completeness-failure",
       "no-infrastructure-retry",
       "no-unknown-provider-attempt-usage"
     ],
     "nonBlockingDiagnostics": [
-      "intermediate-fresh-token-ratios",
       "normalized-api-equivalent-text-token-cost",
       "duration",
       "host-load"
     ],
-    "operatorRule": "The commands pass this artifact's frozen values explicitly. After every production-v1 pause, resume recomputes the provider-free quality and continuity gate from the accepted ledger. Intermediate token, cost, duration, and host-load measurements are diagnostic only; only the complete S108 ledger may decide the fresh-token claim."
+    "operatorRule": "The commands pass this artifact's frozen values explicitly. S0 binds clean-source runtime-conformance, long-horizon, and WebUI-parity receipts before paid work. Every partial paid stage from S12 onward hard-stops when pooled fresh traffic exceeds 1.10, any observed family exceeds 1.25, or exact subagent evidence exceeds one child session per attempt or 5% of candidate traffic. Cost, duration, and host load remain observational. Only the complete S108 ledger may decide the 0.60 upper-95 fresh-token claim."
   },
-  "claimBoundary": "Only S108 may be evaluated for the production-v1 fresh-token public-regression claim; S0, S12, S36 and S72 are spend-control diagnostics. Duration, host load, and normalized cost are reported but cannot block or support this claim."
+  "claimBoundary": "Only S108 may be evaluated for the production-v1 0.60 upper-95 fresh-token public-regression claim. S12, S36 and S72 enforce catastrophic fresh-spend and subagent safety ceilings but cannot establish the claim. Duration, host load, and normalized cost are reported but cannot block or support this claim."
 }

package/benchmarks/production-v1/suite.json

@@ -65,7 +65,11 @@
     "requireHostReadinessForClaim": false,
     "requireFullSuiteForClaim": true,
     "requireStableProviderWireSurface": true,
-    "requireCausalContextReceipt": true
+    "requireCausalContextReceipt": true,
+    "requireProviderFreeEvidence": true,
+    "requireSubagentBudget": true,
+    "maximumSubagentSessionsPerAttempt": 1,
+    "maximumSubagentTrafficShare": 0.05
   },
   "scenarios": [
     {

package/catalog/capabilities.json

@@ -26,8 +26,8 @@
           "path": "evals/scenarios/capability-resolution.json"
         },
         {
-          "byteSize": 6350,
-          "digest": "sha256:3e0f3a94bd3a19df8c24c3e234078d6c3edc664b20a7a4838919450f4225ffca",
+          "byteSize": 7158,
+          "digest": "sha256:8edb1cce6716291c8ca642d3d2392c8f6c92e725ca502e93e06ab45abe541a79",
           "id": "base-policy",
           "kind": "policies",
           "path": "packages/piagent-core/policies/base-policy.json"
@@ -40,8 +40,8 @@
           "path": "packages/piagent-core/prompts/commit.md"
         },
         {
-          "byteSize": 1605,
-          "digest": "sha256:1c2ae0893f131ca0c519f0954845f2b4a8e61182360aac245134102dc3324643",
+          "byteSize": 1413,
+          "digest": "sha256:cb6e7bad1305c7b61d34489cbb5d066ca99855dcfc846dee1668d16d17be8a2b",
           "id": "plan",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/plan.md"
@@ -54,15 +54,15 @@
           "path": "packages/piagent-core/prompts/pr.md"
         },
         {
-          "byteSize": 1314,
-          "digest": "sha256:e1e9caf68957748bebf6ac2d6294905226b298b2734434db8341b35664794388",
+          "byteSize": 1375,
+          "digest": "sha256:bd474a18754c3ab835951d802158c5a19bd5e92f66cffd0dd6b560adcadb795d",
           "id": "review",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/review.md"
         },
         {
-          "byteSize": 2371,
-          "digest": "sha256:bfe8374f15e06d410eec7ab2c82f85ef011fc7d514a92f23720179b497910a44",
+          "byteSize": 2796,
+          "digest": "sha256:8f1552bac55dce1399f3e65cce0333205b2002cc37d4366d69e25b0b4d5f09f9",
           "id": "task",
           "kind": "prompts",
           "path": "packages/piagent-core/prompts/task.md"
@@ -82,29 +82,29 @@
           "path": "packages/piagent-core/skills/piagent-ops/SKILL.md"
         },
         {
-          "byteSize": 2024,
-          "digest": "sha256:9c6aa91663a6614b72a4fb8c6c4a07c07a466c0889fcfe45528ae3e3f62bac90",
+          "byteSize": 2223,
+          "digest": "sha256:18f865d816c5a5cee50bf3b2b407c23a2e67e1e92d929001a0f24c04d0c20e03",
           "id": "piagent-planner",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-planner.md"
         },
         {
-          "byteSize": 1951,
-          "digest": "sha256:6a02cbc7904ea6d8de64aa776ac21ccfbf3c9cc468c4c1c7650e08374ab9e949",
+          "byteSize": 2091,
+          "digest": "sha256:4e514d6480a618d610d4f520af93fa4e151ef60b42b30f5cf94da1a9c96d6ead",
           "id": "piagent-reviewer",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-reviewer.md"
         },
         {
-          "byteSize": 1575,
-          "digest": "sha256:ecd432c57c99783ab76844d0a35cccad377e4cd265674577742ded48ea3ffbb4",
+          "byteSize": 1714,
+          "digest": "sha256:37d9638bfbca8d50f86cbee3fee4db3ba9197bf06004d3a7bba08fc2f8249549",
           "id": "piagent-scout",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-scout.md"
         },
         {
-          "byteSize": 2159,
-          "digest": "sha256:3e0b7071c80f471fb7ea67f91477c1f5e6d3f2574db492c3a9fae6788374a95d",
+          "byteSize": 2210,
+          "digest": "sha256:aa18041470aae1a2b600cef1c09ddbfcd8b86e1efb6858c1f460e46292120e9d",
           "id": "piagent-worker",
           "kind": "subagents",
           "path": "packages/piagent-core/subagents/piagent-worker.md"

package/docs/authority-manifest.md

@@ -170,7 +170,7 @@ directory sibling, unresolved test, denied carrier, failed call, or successful
 no-op locks the opportunity and invalidates reusable review credit. A real
 mutation must be followed by the task's exact verifier on the new tree before
 completion. Retryable infrastructure failure may retry that verifier once on
-the same digest, and a high-confidence in-scope failure may open one final
+the same digest, and a high-confidence evidence-backed failure may open one final
 mutation-bound correction inside the already consumed continuation. Every
 other failure, repeated signature, exhausted budget, stale/corrupt state, or
 unsupported semantic shape produces a deterministic handoff rather than a new

package/docs/auto-delegation-policy.md

@@ -1,7 +1,7 @@
 # Solo-first orchestration policy
 <!-- language: vi; english-index: docs-site/content/en/workflows.html -->
 
-Mục tiêu: user không phải nhớ `/run`, `/parallel`, `/chain` cho workflow hằng ngày, nhưng platform cũng không tự biến mọi task thành swarm tốn token. Khi anh gõ `/workflow task`, `/workflow be-to-fe`, `/workflow platform-improve`, `/workflow plan`, hoặc `/workflow review`, parent agent đọc `piagent_orchestration_policy`, giữ mặc định **solo-first**, rồi chỉ dùng subagents nếu việc đó giúp giảm nhiễu context, tăng tốc read-heavy work, hoặc tăng chất lượng review. Alias cũ như `/task` vẫn giữ cùng policy.
+Mục tiêu: parent model tự làm trọn task với đầy đủ năng lực. Helper không còn là phase mặc định để scout/plan/review; nó chỉ là một tối ưu token ngoại lệ. Piagent chỉ cho tối đa **một helper read-only, context fresh** khi runtime chứng minh có ít nhất hai lane độc lập và tổng token dự kiến sau handoff/merge giảm tối thiểu **30%**. Alias cũ như `/task` giữ cùng policy.
 
 Kiểm tra policy hiện tại trong Pi:
 
@@ -15,11 +15,11 @@ Slash command này chỉ hiện status compact, không gửi follow-up cho model
 
 Subagent không nên hiểu là “luôn tự sinh khi task lớn”. Hành vi đúng là:
 
-1. Parent agent đánh giá task có phần việc độc lập không.
-2. Nếu có và `pi-subagents`/subagent tool khả dụng, parent có thể tự spawn subagent.
-3. Nếu không có tool/package, parent tiếp tục single-agent và ghi rõ `Subagents: unavailable/not used`.
-4. User vẫn có thể gọi command trực tiếp khi muốn ép orchestration cụ thể.
-5. Parallel read-only có thể dùng cho scout/review; parallel writers không phải default và cần approval + isolation.
+1. Parent làm trực tiếp nếu runtime chưa có bằng chứng định lượng.
+2. Helper chỉ đủ điều kiện khi có ít nhất hai workstream độc lập, helper không chờ output tiếp theo của parent, context transfer không quá 2.048 token, không inherit transcript, và tổng dự kiến tiết kiệm ít nhất 30%.
+3. Mỗi task run chỉ có một lần thử helper. Lỗi runtime/scope xác định không được relaunch.
+4. Helper luôn read-only; worker/writer helper bị tắt. Parent giữ toàn bộ mutation và quyết định.
+5. UI/telemetry phải ghi `dispatch` hoặc `skip`, reason codes, và projected net saving; không có số liệu thì `skip`.
 
 Nếu bundled skill `pi-subagents` có trong skill list của parent, parent nên dùng skill đó cho orchestration patterns thay vì tự đoán syntax. Skill này là parent-only; child subagents không nhận nó.
 
@@ -28,43 +28,45 @@ Nếu bundled skill `pi-subagents` có trong skill list của parent, parent nê
 | Setting | Default |
 |---|---|
 | Mode | `solo-first` |
-| Max concurrent subagents | `2` |
+| Helper budget | `1` read-only total; concurrent `1`; retry `0`; worker `0` |
+| Minimum projected net saving | `30%` |
+| Context transfer | fresh/isolated; tối đa `2.048` token; không inherit parent history |
 | Review lenses | `correctness`, `tests`, `scope` |
 | Field Guide | `.pi/memory/MEMORY.md`, advisory, explicit-write only |
-| Writer policy | Một writer cho một write set. |
+| Writer policy | Parent model là writer duy nhất. |
 
 Model role guidance:
 
 - planner: model mạnh nhất hợp lý cho decomposition, architecture, risk, acceptance criteria;
-- worker: model nhanh/ổn định cho bounded implementation đã có plan;
-- reviewer: model/thinking decorrelated với worker khi review quan trọng;
-- watchdog/oracle: model mạnh chỉ cho final risk/security/release/high-impact.
+- worker: disabled; parent model implement trực tiếp;
+- reviewer/oracle: role read-only ngoại lệ; không tự chạy chỉ vì review quan trọng;
+- builtin agents và watchdog: disabled trong baseline Piagent.
 
 ## Khi nào parent nên tự spawn
 
-Parent nên tự spawn subagents khi có ít nhất một điều kiện:
+Chỉ spawn khi **đồng thời** thỏa tất cả điều kiện:
 
-- cần scout nhiều vùng source độc lập;
-- cần map BE contract read-only trong khi FE implementation là write target;
-- cần đọc external source docs/repo và repo hiện tại song song;
-- cần external research có nguồn dẫn, và `pi-web-access`/web tools đang available;
-- cần tạo context handoff trước task lớn (`context-builder`);
-- cần review nhiều góc độc lập: correctness, tests, security, scope drift;
-- task có từ 3 touchpoint trở lên;
-- task medium/high-risk nhưng có phần audit read-only trước khi edit;
-- context có nguy cơ phình to nếu parent tự đọc toàn bộ log/spec/source.
+- runtime xác định ít nhất hai workstream thật sự độc lập;
+- helper có thể hoàn tất mà không chờ output tiếp theo của parent;
+- helper chỉ cần read/grep/find/ls;
+- request dùng fresh isolated context, seed không quá 2.048 token;
+- estimate gồm parent + helper + transfer + merge thấp hơn solo ít nhất 30%;
+- task run chưa từng launch helper và không retry một lỗi runtime/scope xác định.
 
 ## Khi nào không nên tự spawn
 
 Không spawn nếu:
 
 - task nhỏ, một file, verify đơn giản;
+- không có runtime estimate hoặc projected saving dưới 30%;
 - requirement chưa rõ và cần hỏi user trước;
 - chỉ có một write target nhỏ;
 - subagent tool/package chưa available;
 - repo dirty hoặc write set có nguy cơ overlap mà chưa phân tách được;
 - task high-risk cần human gate trước khi edit;
-- muốn spawn nhiều writer song song nhưng không có worktree isolation/approval.
+- cần bất kỳ mutation nào từ child;
+- muốn planner/reviewer chỉ để “tăng chất lượng” nhưng không giảm tổng token;
+- đã có một helper attempt, kể cả attempt failed/orphaned.
 
 ## Default agent mapping
 
@@ -72,13 +74,10 @@ Không spawn nếu:
 |---|---|---|
 | Map unfamiliar repo/module/spec | `piagent-scout` | read-only |
 | Build implementation plan | `piagent-planner` | read-only |
-| Implement approved bounded change | `piagent-worker` | single writer |
 | Review current diff | `piagent-reviewer` | review-first |
 | Challenge architecture/risk | `piagent-oracle` | read-only |
-| External docs/web research | builtin `researcher` | read-only; requires web tools |
-| Large context handoff | builtin `context-builder` or `piagent-scout` | writes handoff artifact only |
 
-Default rule: parallel read-only is OK; parallel writers are not default.
+Default rule: parent direct. Tối đa một role read-only ở bảng trên; không parallel và không worker.
 
 ## Workflow policy
 
@@ -89,42 +88,26 @@ Parent should:
 1. load piagent context/profile/memory/project context;
 2. load `piagent_orchestration_policy`;
 3. create a compact task tree/workPlan and review lenses in `piagent_task_start`;
-4. decide whether subagents are useful enough to justify extra token cost;
-5. if useful, spawn bounded read-only scout/planner/reviewer before or after implementation;
-6. keep implementation single-writer unless user explicitly approves otherwise;
+4. runtime tính projected total tokens; thiếu estimate hoặc saving dưới 30% thì skip;
+5. nếu đủ điều kiện, spawn đúng một helper fresh/read-only;
+6. parent tự implement và review;
 7. summarize subagent outputs into task contract/context manifest/final response.
 
 ### `/workflow be-to-fe`
 
-Recommended auto-delegation:
-
-- `piagent-scout`: map backend contract read-only;
-- `piagent-scout`: map frontend touchpoints read-only;
-- `piagent-planner`: produce FE implementation plan;
-- parent or `piagent-worker`: implement FE only;
-- `piagent-reviewer`: review diff and verify coverage.
+Parent map BE contract, map FE touchpoints, implement và review. Runtime chỉ được chọn **một** trong hai lane mapping cho `piagent-scout` nếu estimate toàn task đạt ngưỡng 30%; lane còn lại vẫn do parent làm.
 
 ### `/workflow platform-improve`
 
-Recommended auto-delegation:
-
-- `piagent-scout`: inspect current platform source/docs;
-- builtin `researcher`: inspect official docs/web evidence when `pi-web-access` is installed;
-- builtin `context-builder`: create handoff context/meta-prompt for large platform changes;
-- `piagent-scout`: inspect official docs/external source repo targeted evidence;
-- `piagent-planner`: produce implementation matrix;
-- parent or `piagent-worker`: implement bounded changes;
-- `piagent-reviewer`: review docs/runtime behavior.
+Parent inspect, research, plan, implement và review. Một fresh read-only helper chỉ được map một lane độc lập khi runtime estimate tổng token đạt ngưỡng; không dùng chain scout → planner → worker → reviewer.
 
 ### `/review`
 
-Recommended auto-delegation:
+Parent-owned review:
 
 - select explicit review lenses first;
-- optional parallel `piagent-reviewer` for correctness;
-- optional parallel `piagent-reviewer` for tests/verification;
-- optional parallel `piagent-reviewer` for scope/protected-path drift;
-- optional `piagent-oracle` for architecture/high-risk concerns.
+- parent cover các lens trong cùng context;
+- chỉ dùng một fresh read-only reviewer/oracle nếu nó thay thế một lane độc lập và estimate tiết kiệm ít nhất 30%.
 
 If the user explicitly asks for a review loop, use `/review-loop` or an equivalent parent-controlled loop with max rounds. Do not blindly apply all reviewer suggestions.
 
@@ -136,17 +119,7 @@ Single scout:
 Use piagent-scout to map the target module read-only. Return files, ownership, invariants, and likely change points only.
 ```
 
-Parallel scout:
-
-```text
-Run parallel piagent-scout agents: one maps backend contract read-only, one maps frontend touchpoints read-only. Wait for both and summarize the contract-to-FE map.
-```
-
-Parallel review:
-
-```text
-Run parallel piagent-reviewer agents for correctness, tests/verification, and scope/protected-path drift. Wait for all and summarize findings by severity.
-```
+The parent must attach runtime evidence equivalent to: `independent lanes >= 2`, `context=fresh`, `inheritedParentTokens=0`, and `projectedNetSaving>=30%`. Without it, do not call the helper tool.
 
 Tool syntax fallback:
 
@@ -159,7 +132,7 @@ subagent({ agent: "piagent-scout", task: "Map target area read-only. Return conc
 Final response should include one line:
 
 ```text
-Subagents: <not used / unavailable / used: piagent-scout, piagent-reviewer>
+Helper: <skip reason=<code> projectedSaving=<unknown|N%> / dispatch role=<role> projectedSaving=N%>
 ```
 
 If not used, give the reason briefly:
@@ -172,19 +145,11 @@ If not used, give the reason briefly:
 
 ## Token rule
 
-Subagents can reduce parent context pollution, but total token usage can increase because each child does its own model/tool work. Use them for parallelizable read-heavy work and review quality, not as a blanket token-saving switch.
+Projected saving phải so sánh **tổng parent + child + handoff + merge**, không so child với một đoạn parent context riêng lẻ. Ngưỡng 30% là dispatch gate, không phải bằng chứng rằng Piagent đã rẻ hơn `codex-cli` 30–40%; kết luận đó chỉ được đưa ra từ paired benchmark Piagent/`codex-cli` cùng model, thinking, task và success gate.
 
-## Package shortcuts worth using
+## Package shortcuts
 
-| Shortcut | Use when |
-|---|---|
-| `/parallel-review` | Need distinct review angles; add `autofix` only when user permits fixes. |
-| `/review-loop` | Need worker/reviewer/fix loop until clean or capped. |
-| `/parallel-research` | Need external evidence + local code context. |
-| `/parallel-context-build` | Need context/meta-prompt handoff before a large plan. |
-| `/parallel-handoff-plan` | Need research + context-builder + implementation handoff. |
-| `/gather-context-and-clarify` | Need scout/research first, then ask only meaningful questions. |
-| `/parallel-cleanup` | Need post-implementation cleanup review. |
+Các shortcut `/parallel-*`, worker/reviewer loop và grant-spawn-budget thuộc package upstream nhưng không nằm trong Piagent governed default. Absolute Piagent budget vẫn là một read-only helper total; daily workflow không dùng các shortcut này.
 
 See `docs/subagent-orchestration-capabilities.md`.