[ElainaRoxy]

Approval asks can show only a command or tool name, without explaining the operation, and file-tool previews may omit replacements. This proposal carries a per-call display explanation and complete file-operation evidence through separate existing payload channels.

Refs #1105. Draft for discussion of the sender contract; no release or merge is requested.

Behavior and contract

• Optional _permissionPurpose is consumed at the tool-call boundary and carried only as an operation-purpose annotation for human presentation. It remains an agent-authored claim, never a policy fact or permission grant.
• A separate file operation JSON evidence entry carries tool and path, read ranges, every edit replacement, or complete write content. The public API document specifies the exact shapes. Extra input metadata is not copied into this entry.
• Evidence is independent of both purpose and the human preview formatter. Consumers can select complete file evidence without reading purpose annotations. The revised classifier PR #2 does exactly that and does not send purpose to the judge.
• Existing request facts, deterministic decision order, forwarding, public UI-event projection, and permission review-log projection remain unchanged. The evidence is untruncated in the payload; each authorizer must validate, budget, and delimit what it selects.
• Tool arguments are submitted action data, not disk contents collected by this extension or a claim of successful execution. Edit old text and write content can reach a hosted judge when a consumer selects them.

The latest commit clarifies these independent channels and adds a contract regression demonstrating that structured payload forwarding preserves file evidence without copying purpose or extra fields into it.

Validation

• Root pnpm run check: all workspace packages passed.
• Root pnpm run lint: passed.
• Root pnpm run test: all workspace package suites and root tests passed; pi-permission-system ran 6,446 tests, and the root suite ran 286 tests.
• Focused operation-purpose, file-evidence, and dialog tests: 18 passed.
• Earlier declaration-bundle build and Pi schema/input-reference verification remain unchanged by this documentation/test-only follow-up.

Prepared with AI assistance. An independent subagent review was unavailable in this environment. Both changes remain proposals pending maintainer agreement on this contract.