@piagent/platform 1.0.0

package/docs/runtime-policy-design.md

@@ -0,0 +1,132 @@
+# Runtime policy design
+
+## Mục tiêu
+
+Runtime policy là lớp kiểm soát cách agent đọc context, gọi tool, sửa source, chạy verify, và kết thúc task. Tài liệu này mô tả thiết kế trung lập của Pi Agent Platform, không phụ thuộc vào một project cụ thể.
+
+## Design principles
+
+1. Profile first: mọi task phải biết project mode, permission profile, protected paths, required context, verify commands, và MCP capabilities.
+2. Bounded context: file lớn phải qua budget check; context manifest phải ghi lý do.
+3. Guarded execution: shell/destructive actions đi qua exec policy. Đây là accident brake, không phải OS sandbox.
+4. Tool capability: tool ngoài phải map vào capability được profile cho phép.
+5. Evidence before done: source-changing task phải có verify evidence và trace.
+6. Human gate for high risk: auth, release, deploy, destructive command, provider config, database migration, production data, broad Git staging, hoặc external Git/GitHub write action cần explicit confirmation.
+
+## Runtime modules
+
+| Module | Tool/hook | Purpose |
+|---|---|---|
+| Project context | `piagent_context` | Load profile, settings, policy, and local state summary. |
+| Context index | `piagent_context_index_status/search/record` | Maintain a compact advisory node/edge/citation map for profile/project/tech/task navigation. |
+| Permission profile | `piagent_permission_status` | Show active `read-only`, `workspace-write`, or `trusted-full-access` boundary. |
+| Exec policy | `piagent_exec_policy_check` | Evaluate shell command risk before execution. |
+| Context budget | `piagent_context_budget` | Enforce size/count limits for context files. |
+| Tool registry | `piagent_tool_policy_check` | Check external tool capability against profile. |
+| Task contract | `piagent_task_start` | Persist scope, acceptance criteria, risk lane, and verify plan. |
+| Context manifest | `piagent_context_record` | Record files read for a task. |
+| Verify evidence | `piagent_verify_record` | Record command result only after matching an observed Pi `bash` tool result after task start. |
+| Final gate | `piagent_task_gate_check` | Validate readiness before final handoff. |
+| Trace | `piagent_trace_record` | Persist changed files, outcome, and handoff state. |
+| Usage | `piagent_usage_snapshot` | Show session/context/token usage when available. |
+
+## Policy precedence
+
+Effective policy is derived from:
+
+1. safe defaults in `packages/piagent-core/policies/base-policy.json`;
+2. installed package prompts/skills/extensions;
+3. project `.pi/piagent-profile.json`;
+4. explicit user instruction in the active session.
+
+User instruction can narrow scope or raise safety requirements. It should not silently bypass protected paths, destructive command checks, or final task gates.
+
+## Profiles
+
+Profiles define:
+
+- `mode`
+- `permissionProfile`
+- `rootMarkers`
+- `protectedPaths`
+- `shellProtectedPaths` — shell-only deny list for bash/exec parsing.
+- `readOnlyPaths` — path tools may read, but write/edit and shell access are denied.
+- `requiredContext`
+- `verifyCommands`
+- `mcpCapabilities`
+- `runtimePolicy`
+- `hardGates`
+
+The same platform can operate as `web-frontend`, `backend-api`, `fullstack`, `be-readonly-fe`, `data`, `devops`, `docs`, `python`, `node-typescript`, or `mobile` by switching profile.
+
+`protectedPaths` blocks read/write path-tool access and is also used for shell matching when `shellProtectedPaths` is omitted. `readOnlyPaths` is for contracts such as `be-readonly-fe`: path tools may inspect these files with `read`, `grep`, `find`, and `ls`, but write/edit and shell access are blocked automatically.
+
+`shellProtectedPaths` is intentionally shell-only. A path declared only there blocks `bash`/`exec` access, but does not block `read`, `write`, or `edit` path tools. `profile-doctor` and `team-doctor` warn on shell-only entries so older custom profiles can migrate write-sensitive paths to `protectedPaths` or `readOnlyPaths`.
+
+## Permission profiles
+
+The runtime separates the active autonomy profile from the project profile:
+
+| Profile | Meaning |
+|---|---|
+| `read-only` | Allows source inspection through `read`, `grep`, `find`, `ls`, plus piagent state tools. Blocks shell, write/edit, and unknown non-piagent tools before execution. |
+| `workspace-write` | Default governed implementation mode. Existing protected-path, shell, capability, context, verify, and final gates remain active. |
+| `trusted-full-access` | Trusted automation mode for known repos. It can relax tool-registry blocks and capability filesystem scopes inside the guard, but protected paths, secret redaction, capability-lock integrity, and destructive/external confirmation still apply. |
+
+`PIAGENT_PERMISSION_PROFILE` can override the profile for a single run. Invalid values fail closed to `read-only`. Inside Pi, `/read-only`, `/workspace-write`, and `/full-access` set a session-local override without writing the project profile. Precedence is launch env, then session command, then project profile, then policy default. `permissionProfiles.allowedModes` in base policy acts like a managed allowlist; removing `trusted-full-access` from that list disables it for the installation.
+
+## Task lifecycle
+
+```text
+intake
+  -> profile/context
+  -> task contract
+  -> context manifest
+  -> plan
+  -> guarded implementation
+  -> observed verify evidence
+  -> trace
+  -> final gate
+  -> handoff
+```
+
+This lifecycle is intentionally explicit. It makes task quality auditable and avoids relying on a long prompt as the only control layer.
+
+## Verify evidence ledger
+
+Pi `bash` results are observed through the runtime `tool_result` hook and appended to:
+
+```text
+.pi/piagent-state/observed-bash.jsonl
+```
+
+The ledger stores cwd, timestamp, status, a hash of the normalized command, and redacted command text for audit. It does not need the raw command text to validate a later `piagent_verify_record` call.
+
+This file-based ledger is intentionally shared by parent and subagent processes that run in the same project cwd. If a worker subagent runs `npm test`, the parent can later record that exact verify command without depending on process-local memory.
+
+The ledger and task/profile control files are self-protected:
+
+- raw path-like tool access to `.pi/piagent-state/**` is blocked before execution;
+- raw path-like tool access to `.pi/piagent-profile.json` is blocked before execution;
+- the same protected-path gate covers Pi built-ins such as `read`, `write`, `edit`, `grep`, `find`, `ls`;
+- custom/MCP tools are also blocked when a tool call contains path-like strings pointing at a protected path, including nested objects, arrays, and `file://` URIs;
+- path-like strings are percent-decoded once before matching;
+- input nesting above `MAX_TOOL_INPUT_INSPECTION_DEPTH=32` fails closed because an uninspectable input cannot be safely classified;
+- generic extraction skips known leaf content fields such as `content`, `query`, `pattern`, `text`, and `command`, so normal search/edit strings do not become path false positives;
+- `grep.glob` and `find.pattern` are checked when they explicitly name protected targets such as `.env*`, `auth.json`, `.pi/piagent-state/**`, or `piagent-profile.json`;
+- broad `grep`, `find`, and `ls` results are filtered through the `tool_result` hook so protected content lines or protected path metadata are redacted before the model sees them;
+- piagent tools still write/read these files through internal extension code, so normal task evidence and profile workflows continue to work.
+
+This gate is independent from the tool registry. The registry can stay `advisory` for compatibility with changing Pi/MCP tool names, while protected-path access remains fail-closed whenever the event exposes a path-like input.
+
+Final-gate semantics are stricter than simple observation:
+
+- `observed=true`: Pi actually saw a matching bash result after `task.createdAt`;
+- `matchedProfileCommand=true`: the command exactly matches one entry in `task.verifyCommands`;
+- passing final gate: requires `observed=true`, `matchedProfileCommand=true`, and `exitCode=0`.
+
+Ad-hoc commands can still be recorded for traceability, but they do not satisfy the passing verify gate unless they are part of the task verify plan. Exact matching is deliberate; if the task says `npm test`, record `npm test`, not `npm test || true` or `npm  test`.
+
+## Benchmark discipline
+
+Quality/token/cost claims must be recorded through `scripts/quality-benchmark.sh` or equivalent project evidence. The benchmark unit is a real task scenario with the same acceptance criteria and verification command.

package/docs/runtime-quality-baseline.md

@@ -0,0 +1,257 @@
+# Runtime quality baseline
+
+## Mục tiêu
+
+Runtime quality baseline định nghĩa bộ kiểm soát để Pi Agent Platform có thể chạy task một cách có kỷ luật cho solo, internal team, và public package.
+
+Các module chính:
+
+1. Permission profile
+2. Exec policy
+3. Context budget
+4. Tool registry
+5. Final task gate
+6. Local verification
+7. Quality benchmark
+
+Trạng thái hiện tại: platform đã có runtime modules đủ cho guarded implementation task. Các tuyên bố về chất lượng, token, cost, hoặc tốc độ phải dựa trên benchmark theo project/model thật.
+
+## 0. Permission profile
+
+Tool:
+
+```text
+piagent_permission_status
+```
+
+Runtime behavior:
+
+- `read-only` chặn shell, write/edit, và unknown non-piagent tools;
+- `workspace-write` là default cho implementation có guard;
+- `trusted-full-access` nới tool/scope autonomy trong môi trường trusted nhưng không tắt protected paths, redaction, capability lock, hoặc human gate cho destructive/external action.
+- `/full-access <task>` bật `trusted-full-access` cho session hiện tại rồi gửi phần task còn lại cho agent; `/permission-status` hiển thị mode và boundary đang active.
+
+## 1. Exec policy
+
+Tool:
+
+```text
+piagent_exec_policy_check
+```
+
+Runtime behavior:
+
+- phân tích shell command trước khi chạy lệnh rủi ro;
+- block destructive patterns;
+- đệ quy vào shell wrapper phổ biến như `sudo`, `env`, `bash -c`, subshell, command substitution, và backtick;
+- check `shellProtectedPaths` cho bash, mặc định bảo vệ `.git`, `auth.json`, `.env`, `.env.*`; path chỉ nằm trong `shellProtectedPaths` là shell-only và không chặn write/edit;
+- kiểm tra cả bare filename, partial glob (`*`, `?`, character class, brace), symbolic-link alias đã canonicalize, và redirect shell có hoặc không có khoảng trắng;
+- redact sensitive text trong text result và JSON-like result details trước khi output được trả về model; non-text media block được giữ nguyên;
+- cảnh báo broad command prefix như `bash`, `python`, `node`, `git`, `sudo`;
+- áp dụng policy rule `allow | prompt | forbid`;
+- ghi lý do để agent/human đánh giá trước khi tiếp tục.
+
+Config:
+
+```text
+packages/piagent-core/policies/base-policy.json
+```
+
+Mục tiêu không phải cấm mọi command mạnh hoặc thay thế sandbox OS. Đây là lớp phanh chống tai nạn: giảm rủi ro agent tự ý chạy lệnh có tác động cao, đọc secret, hoặc đụng protected path mà thiếu policy/human gate.
+
+## 2. Context budget
+
+Tool:
+
+```text
+piagent_context_budget
+```
+
+Runtime behavior:
+
+- giới hạn số file trong context manifest;
+- giới hạn kích thước file context;
+- cảnh báo fragment lớn;
+- buộc context phải có lý do đọc rõ ràng.
+
+Default:
+
+```json
+{
+  "maxContextFileChars": 50000,
+  "maxMemoryFileChars": 20000,
+  "maxManifestFiles": 80,
+  "warnFragmentChars": 4000
+}
+```
+
+Context nên được chọn theo profile/task, không đọc tràn toàn repo.
+
+## 3. Tool registry
+
+Tool:
+
+```text
+piagent_tool_policy_check
+```
+
+Runtime behavior:
+
+- map tools sang capability như `filesystem-readonly`, `filesystem-write`, `shell`, `github`, `browser`;
+- `piagent_*` tools luôn allowed;
+- default `advisory` để không phá Pi runtime khi tool names thay đổi;
+- project ổn định có thể nâng `toolRegistry=enforce`.
+
+Profile capability ví dụ:
+
+```json
+{
+  "mcpCapabilities": [
+    "filesystem-readonly",
+    "filesystem-write",
+    "shell",
+    "github",
+    "browser",
+    "memory"
+  ]
+}
+```
+
+## 4. Final task gate
+
+Tool:
+
+```text
+piagent_task_gate_check
+```
+
+Runtime behavior:
+
+- kiểm tra task contract;
+- kiểm tra context manifest;
+- kiểm tra verify evidence đã đối chiếu với Pi `bash` `tool_result` thật;
+- yêu cầu observed passing verify khớp exact `task.verifyCommands` khi task có source changes;
+- block `piagent_trace_record completed` nếu final gate đang enforce và proof chưa đủ.
+
+Agent vẫn phải gọi `piagent_task_gate_check` trước final handoff.
+
+`piagent_verify_record` không còn tin `exitCode` tự khai báo. Lệnh verify phải khớp một bash tool result đã quan sát sau `task.createdAt`, và claimed `exitCode` phải khớp trạng thái `isError` của Pi. Observed result được ghi vào `.pi/piagent-state/observed-bash.jsonl` để parent/subagent process có thể share evidence trong cùng project cwd.
+
+Gate phân biệt hai mức:
+
+- observed evidence: command thật sự đã chạy qua Pi bash;
+- profile-matched evidence: command đó exact-match một dòng trong `task.verifyCommands`.
+
+`true`, `echo ok`, hoặc `npm test || true` có thể được ghi trace nếu đã chạy thật, nhưng không đủ để pass final gate trừ khi profile/task verify plan khai đúng command đó.
+
+Guard state tự bảo vệ:
+
+- raw path-like access vào `.pi/piagent-state/**` bị block trước khi tool chạy;
+- raw path-like access vào `.pi/piagent-profile.json` bị block trước khi tool chạy;
+- Pi built-ins `read`, `write`, `edit`, `grep`, `find`, `ls` đi qua cùng protected-path gate;
+- custom/MCP tools cũng bị block nếu tool call chứa path-like string trỏ vào protected path, kể cả nested object, array, và `file://` URI;
+- path-like string được percent-decode một lần trước khi match, nên `%2Eenv` và `.%65nv` không đi vòng qua guard;
+- tool input lồng quá sâu vượt `MAX_TOOL_INPUT_INSPECTION_DEPTH=32` sẽ fail-closed;
+- generic extractor chỉ skip leaf field nội dung đã biết như `content`, `query`, `pattern`, `text`, và `command`;
+- `grep.glob` và `find.pattern` bị block khi pattern nhắm protected path rõ ràng như `.env*`, `auth.json`, `.pi/piagent-state/**`, hoặc `piagent-profile.json`; broad glob như `*.json` được phép và để result backstop xử lý;
+- broad `grep`, `find`, và `ls` sweep có thêm `tool_result` backstop để redact content line hoặc path metadata từ protected files;
+- mọi text block trong `tool_result` và string leaf trong JSON-like `details` có thêm shared sensitive-data redaction; key như `password`, `token`, `credential` được dùng làm context phát hiện;
+- `npm run benchmark:redaction` gate contextual recall, benign preservation, structured objects/arrays, và large-output correctness bằng synthetic data; opaque entropy không có credential context được báo riêng và không gate release;
+- bash evidence chỉ giữ command text đã redact ở memory/disk; raw command hash vẫn dùng để exact-match verify evidence;
+- `piagent_task_start`, `piagent_verify_record`, và `tool_result` hook vẫn ghi state được qua internal extension path.
+
+## 5. Local verification
+
+Platform verification:
+
+```bash
+npm run typecheck
+npm test
+npm run benchmark:redaction
+bash scripts/verify-local.sh
+bash scripts/verify-local.sh --offline  # CI / clean machine without Pi login catalog
+bash scripts/team-doctor.sh . --strict-share
+pi list --approve
+```
+
+`verify-local.sh` kiểm tra:
+
+- package manifests;
+- JSON parse;
+- required docs/scripts/prompts;
+- protected-path, shell protected path, recursive path-like tool access, `grep/find/ls` result backstops, guard-state self-protection, exec-policy, observed-verify, cross-process ledger, profile verify-command matching, and redaction regression tests;
+- profile doctor;
+- team doctor;
+- TypeScript syntax for extension;
+- smoke test for runtime policy;
+- public documentation wording guard.
+
+## 6. Quality benchmark
+
+Script:
+
+```bash
+bash scripts/quality-benchmark.sh <project-path> --init
+bash scripts/quality-benchmark.sh <project-path> --record \
+  --scenario bounded-source-fix \
+  --surface pi \
+  --result pass \
+  --tokens 12345 \
+  --cost 0.12 \
+  --verify "npm test" \
+  --notes "verify passed; no manual correction"
+```
+
+Output:
+
+```text
+<project>/.pi/benchmarks/quality-scenarios.md
+<project>/.pi/benchmarks/quality-runs.jsonl
+```
+
+Chỉ claim chất lượng/token/cost khi cùng scenario có:
+
+- cùng task prompt/spec;
+- cùng acceptance criteria;
+- verify command rõ;
+- token/cost/duration được ghi lại;
+- quality notes và số vòng sửa lại.
+
+## Runtime policy trong profile
+
+Project có thể override:
+
+```json
+{
+  "runtimePolicy": {
+    "execPolicy": "enforce",
+    "contextBudget": "enforce",
+    "toolRegistry": "advisory",
+    "finalGate": "enforce"
+  }
+}
+```
+
+Mode:
+
+| Mode | Ý nghĩa |
+|---|---|
+| `off` | Không áp dụng module policy đó. |
+| `advisory` | Tool trả warning/check result nhưng không block mọi thứ. |
+| `enforce` | Runtime hook/tool block khi vi phạm policy. |
+
+## Khuyến nghị vận hành
+
+Setup solo/internal nên bắt đầu với:
+
+1. `execPolicy=enforce`
+2. `contextBudget=enforce`
+3. `toolRegistry=advisory` trong giai đoạn đầu, sau đó nâng lên `enforce` khi tool registry ổn định
+4. `finalGate=enforce`
+
+## Roadmap
+
+- Hard final assistant stop-hook nếu Pi extension API expose stable hook.
+- Disposable integration test chạy Pi runtime end-to-end.
+- Optional process/filesystem/network sandbox ngoài Pi khi môi trường yêu cầu isolation mạnh.
+- Auto-discovery tool names từ Pi/MCP để giảm registry thủ công.

package/docs/security-redaction-benchmark.md

@@ -0,0 +1,56 @@
+# Sensitive-data redaction benchmark
+
+The redaction benchmark measures the text and structured-data backstop used by the runtime guard. It uses deterministic synthetic values only; real credentials must never be added to the corpus. This is an internal regression benchmark, not an independent security audit, and the detector model should be treated as still maturing.
+
+Run it from the repository root:
+
+```bash
+npm run benchmark:redaction
+```
+
+The command returns JSON and exits non-zero when a release gate fails.
+
+The v0.4.2 frozen-tree baseline is 52/52 contextual cases detected, 0/30 benign text false positives, 8/8 structured sensitive values redacted, and 7/7 structured benign values preserved. The six unlabeled-entropy cases remain observational and non-gated.
+
+## Release gates
+
+- Every contextual or known-format case must be redacted.
+- Benign text must have zero false positives in the committed corpus.
+- Structured sensitive fields and approved plural collections must be redacted.
+- Structured identifiers, checksums, labels, and semantic/design token fields must remain unchanged.
+- A large text result with a contextual credential must be redacted successfully.
+
+The corpus covers known token formats, private-key blocks, credential-bearing URLs, authorization headers, query parameters, quoted and multiline assignments, camelCase/hyphenated keys, nested objects, arrays, placeholders, existing redaction markers, hashes, identifiers, and documentation prose.
+
+## Interpreting the output
+
+| Field | Meaning | Gated |
+|---|---|---|
+| `contextual` | Known formats or values paired with a credential-bearing key/header/URL context | Yes |
+| `benign` | Text that must remain unchanged | Yes |
+| `structured` | Key-aware redaction and preservation inside objects/arrays | Yes |
+| `largeOutput` | Redaction result for a bounded large text sample | Yes for correctness; timing is informational |
+| `unlabeledEntropy` | Opaque values without a credential-bearing context | No; observational only |
+| `performance` | Local execution measurements | No; compare only on the same machine/runtime |
+
+Unlabeled high-entropy values are not automatically treated as secrets. A generic entropy rule cannot reliably distinguish a credential from a checksum, content hash, artifact identifier, or opaque public ID. Add a known format or a clear key/header context when stronger coverage is required.
+
+## Security boundary
+
+This benchmark measures pattern-based output containment. It does not authorize secret handling and does not turn the extension into an operating-system sandbox. It does not decode every transformed output form before matching; for example, base64-encoded or otherwise re-encoded secret material can evade the redaction backstop. Workloads that execute untrusted code or process untrusted prompts still require process, filesystem, network, and credential isolation.
+
+The current scope, assumptions, controls, and residual risks are documented in [security-threat-model.md](security-threat-model.md), and private intake/disclosure is documented in [SECURITY.md](../SECURITY.md). Before using redaction results as a stronger assurance claim, continue to complete and maintain:
+
+- Linux, macOS, Windows, and shell-behavior compatibility matrix;
+- parser fuzzing for shell/path extraction;
+- symlink and path-traversal adversarial tests;
+- third-party audit or independent review;
+- LTS support and backport policy for affected releases.
+
+When extending the detector:
+
+1. Add synthetic positive and benign controls first.
+2. Record the failing benchmark result.
+3. Make the smallest context-aware detector change.
+4. Run the benchmark, full test suite, typecheck, capability doctor, and offline verification.
+5. Keep the unlabeled-entropy result separate from release claims.

package/docs/security-threat-model.md

@@ -0,0 +1,66 @@
+# Security threat model
+
+## Scope and objective
+
+Pi Agent Platform adds application-level policy enforcement to Pi tool calls used in a trusted project. Its objective is to reduce accidental damage, common prompt-injection impact, secret exposure, unauthorized external mutations, and non-reproducible team installs. It is not an operating-system sandbox and does not claim to contain hostile code running with the operator's account permissions.
+
+This document covers the packaged guard, project profiles, capability locks, installer, release workflow, and packaged artifact. Project-specific applications, provider infrastructure, the Pi host implementation, third-party add-ons, and the operating system remain separate security domains.
+
+## Protected assets
+
+- credentials, OAuth sessions, `.env`, auth files, and private runtime state;
+- source and configuration outside the resolved filesystem scopes;
+- paths declared read-only by the active project profile;
+- protected guard, profile, settings, capability-lock, and evidence files;
+- external GitHub, HTTP, MCP, and provider resources that can be mutated;
+- release identity, installer sources, dependency pins, and package contents;
+- observed verification evidence used to approve task completion.
+
+## Trust assumptions
+
+- The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
+- Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
+- A human remains available to approve destructive and external-provider actions.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.0.0, and WSL2 is experimental/unverified.
+- Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
+
+## Threat actors and failure modes
+
+- an agent making an incorrect tool call or selecting an overly broad command;
+- prompt injection contained in repository text, web content, tool output, or an MCP response;
+- malformed, nested, encoded, or aliased tool input intended to bypass path or action classification;
+- a project profile or capability lock modified to request more authority;
+- a moved release tag, unexpected package content, or vulnerable transitive dependency;
+- an untrusted repository, dependency install script, interpreter payload, binary, or process executing with the operator's OS permissions.
+
+The final category is outside the containment capability of the Piagent guard. It requires isolation at the filesystem, process, network, and credential layers.
+
+## Attack-vector and control map
+
+| Vector | Current control | Residual risk |
+|---|---|---|
+| Direct or nested path-like tool input | Bounded recursive input inspection, protected-path precedence, repository boundary checks, filesystem capability scopes, and read-only profile paths | A new carrier or field name must be classified before it can be treated as controlled. Unknown/ambiguous tools fail closed where policy requires confirmation. |
+| Encoding, case variation, traversal, or symbolic-link alias | Single percent decode, case-insensitive protected matching, canonical resolution for existing paths, traversal/repository escape rejection | Filesystem races and code executing outside observed tool paths require an OS boundary. |
+| Shell glob, brace, redirection, wrapper, assignment, or command composition | Static Bash operand/action analysis with bounded expansion and regression cases; protected input is denied and external mutation is confirmation-gated | Runtime-generated interpreter payloads cannot be fully understood by static parsing. Sensitive output redaction is a backstop, not containment. |
+| Secret returned in tool output | Shared contextual redaction across guarded text/results and synthetic recall benchmark | High-entropy, novel secret formats, or transformed output such as base64-encoded content can evade pattern-based redaction. Never intentionally print real secrets. |
+| Malicious project profile or relaxed capability lock | Trust-aware profile loading, deterministic lock digest, base-policy/source integrity, protected self-state, and fail-closed verification | An already trusted malicious repository can execute code through mechanisms outside the guard. |
+| External GitHub/HTTP/MCP/provider mutation | Direct and proxied action classification plus explicit operator confirmation, including guarded shell carriers | Provider semantics and new tool schemas can change; new integrations require policy and regression review. |
+| Destructive local action | Exec-policy classification and explicit confirmation; protected paths remain denied in every permission profile | Confirmation is not isolation. A trusted process outside the observed tool path retains OS authority. |
+| Forged verification result | Observed Bash result ledger, command hash, task-start ordering, exit-code and verify-command matching | Compromise of the trusted Pi/process environment is outside this evidence model. |
+| Mutable or substituted release source | Exact team tags, stable tag-to-commit resolution, release-commit binding in tag CI, annotated-tag requirement, add-on integrity checks, and documented tag ruleset requirement | Bootstrap helper installation still relies on GitHub tag immutability; repository administrators must prevent tag update/deletion. Signed provenance remains future work. |
+| Dependency or package-content compromise | `--ignore-scripts` bootstrap installs, root and exact runtime dependency audits, immutable Action SHAs, package allowlist, artifact tests, CodeQL, Dependabot, secret scanning, and push protection | Audits are point-in-time and lower-severity/upstream findings remain. Review alerts and refresh pins continuously. |
+| Parser resource exhaustion | Bounded nested input, command length, expansion, and result processing | Fuzzing breadth is still evolving; report hangs or unusually expensive inputs privately. |
+
+## Permission model
+
+`read-only`, `workspace-write`, and `trusted-full-access` change the allowed working scope; they do not disable protected paths, secret redaction, capability integrity, destructive confirmation, or external-provider confirmation. `trusted-full-access` is intended for an already trusted repository in an externally safe environment. It is not a bypass or sandbox mode.
+
+## Security verification
+
+Release gates include policy regression tests, TypeScript checking, runtime smoke tests, redaction benchmarks, package-content inspection, release-identity checks, installer tests, exact Pi host/add-on dependency audit, and CI on Linux x64 plus the current macOS runner. CodeQL covers JavaScript/TypeScript and GitHub Actions.
+
+These are internal engineering controls, not an independent third-party audit. The project currently has no LTS promise. Stronger assurance still benefits from broader parser fuzzing, a larger OS/shell matrix, independent review, signed provenance, and continued adversarial testing.
+
+## Reporting and disclosure
+
+Follow [the security policy](../SECURITY.md). Report suspected bypasses privately with a synthetic reproduction and do not include live credentials or customer data.

package/docs/subagent-orchestration-capabilities.md

@@ -0,0 +1,104 @@
+# Subagent orchestration capabilities
+
+Review date: 2026-07-19
+
+Package used:
+
+- `pi-subagents`
+- Package docs: https://pi.dev/packages/pi-subagents
+
+## Kết luận
+
+Pi Agent Platform uses `pi-subagents` for child sessions, parallel read-only work, review loops, and structured handoffs. The platform keeps a safe default configuration and documents advanced commands separately so daily users can still start with `/task`.
+
+Core decisions:
+
+1. natural-language delegation is preferred over requiring users to remember `/run`;
+2. parent agent should decide whether independent read-only work deserves subagents;
+3. piagent roles remain narrow and policy-aware;
+4. background, watchdog, scheduled, and parallel-writer behavior stays opt-in;
+5. long child output should use file handoff when possible.
+
+## Capabilities
+
+| Capability | Meaning | Platform decision |
+|---|---|---|
+| Natural language delegation | User can ask for scout/review/planning without exact syntax. | Covered by auto-delegation policy and workflow prompts. |
+| Builtin agents | General roles such as researcher, planner, reviewer, and context-builder. | Use when they fit the task and installed tools are available. |
+| Piagent agents | `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle`. | Default roles for governed project work. |
+| Prompt shortcuts | `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan`. | Documented for explicit orchestration. |
+| Supervisor channel | Child can ask parent for a decision. | Allowed for blocked or high-context child work. |
+| Output controls | `output`, `outputMode=file-only`, `reads`, `outputSchema`, `acceptance`. | Recommended for large reports and handoff context. |
+| Worktree isolation | Separate checkout for parallel writer agents. | Non-default; use only with explicit scope and disjoint write sets. |
+| Watchdog | Additional opt-in review at session end. | Off by default to control token/cost. |
+| Scheduled runs | Delayed one-shot subagent. | Disabled by default; only for explicit monitor/wait tasks. |
+
+## Applied in platform
+
+- `scripts/configure-subagents.sh`
+  - `waitTool.enabled: true`
+  - `intercomBridge.mode: always`
+  - stable `defaultSessionDir`, `singleRunOutputBaseDir`, `worktreeBaseDir`
+  - `scheduledRuns.enabled: false`
+  - bounded `maxSubagentDepth`, spawn cap, and parallel concurrency
+- `scripts/setup.sh` / `scripts/install-global.sh`
+  - optional `--with-web-access` installs `npm:pi-web-access@0.13.0` for web/docs research
+- Workflow prompts
+  - `/task`, `/plan`, `/review`, `/be-to-fe`, `/platform-improve` instruct the parent to auto-delegate when work is independent and bounded
+- Docs
+  - command reference lists prompt shortcuts, watchdog/profile commands, supervisor control, output/fork/worktree options
+
+## Keep non-default
+
+| Feature | Reason |
+|---|---|
+| Watchdog always-on | Extra review can increase token/cost. |
+| `asyncByDefault: true` | Background work can surprise interactive users. |
+| Scheduled subagents | Useful for monitoring, unrelated to normal implementation. |
+| Parallel writers | Correct only with clean repo, worktree isolation, and non-overlapping files. |
+| Research agent without web tooling | It needs appropriate web/search/fetch tools installed. |
+
+## Recommended usage
+
+Daily implementation:
+
+```text
+/task Implement <task>.
+```
+
+Review until clean:
+
+```text
+/review-loop current diff max 3 rounds
+```
+
+Parallel review:
+
+```text
+/parallel-review current diff
+```
+
+Research-heavy task:
+
+```bash
+pi install npm:pi-web-access@0.13.0
+```
+
+```text
+/parallel-research Compare available implementation options for <topic>.
+```
+
+Context handoff before a large implementation:
+
+```text
+/parallel-context-build Build context for <large task>.
+/parallel-handoff-plan Build implementation handoff plan for <large task>.
+```
+
+Watchdog for a high-risk session:
+
+```text
+/subagents-watchdog recommend-model
+/subagents-watchdog session model recommended
+/subagents-watchdog on
+```