feat: add reasons to permission requests

[shabeeth2]

Intent

Add an optional human-readable reason to legacy and current permission requests, preserve it through request creation, live events, pending APIs, compatibility conversion, public OpenAPI output and generated clients, and display nonblank reasons as plain untrusted text in browser, desktop, TUI and CLI permission prompts without hiding the authoritative command, path or scope. Keep descriptions optional for shell and read compatibility, do not use reason for matching, approval, denial, saved rules or security decisions, do not invent generic built-in reasons when task-specific intent is unavailable, and keep the change limited to permission request reason behavior with no deleted files or unrelated cleanup.

What Changed

• Add an optional human-readable reason to legacy and current permission request schemas, APIs, events, compatibility adapters, and custom tool requests.
• Regenerate OpenAPI and client SDK types so permission reasons are available when creating, listing, and retrieving requests.
• Display nonblank reasons as plain text alongside the authoritative command, path, or scope in app, TUI, and CLI permission prompts.

Risk Assessment

✅ Low: The change is well-bounded and consistently preserves the optional reason across legacy/current schemas, request creation, events, APIs, compatibility conversion, generated clients, and plain-text UI rendering without affecting permission decisions.

Testing

After linking frozen dependencies with lifecycle scripts disabled, focused permission transport, decision, plugin, CLI, TUI, and app-adaptation checks passed; five browser scenarios also passed live and produced a screenshot showing the reason beside authoritative commands and unchanged controls. Live HTTP API, native desktop, and model-driven CLI/TUI sessions were unavailable, leaving overall validation inconclusive.

• Live validation: ⚠️ inconclusive - 2 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
Create permission requests with and without a reason and retrieve the preserved value through pending and single-request APIs	⏸️ untested	no	The prior payload recorded only an executable HTTP test running in a test process, not a scenario driven against a live end-user server, so it did not establish a live result.
View a nonblank reason beside authoritative permission commands in the running browser UI and approve it without hiding controls	✅ pass	live	browser-permission-reason.png and Playwright scenario shows a pending permission dock
Render HTML-like reasons as plain untrusted text and omit the Reason section for absent or whitespace-only values	✅ pass	live	Playwright cases for absent, empty, whitespace-only, and HTML-like reasons all passed against the running browser UI.
Allow once, allow always, or deny without the reason affecting matching, replies, or saved rules across CLI and TUI prompts	⏸️ untested	no	Generating a genuine interactive CLI/TUI permission request requires a configured model/provider credential, which this isolated environment does not provide. Supply a test provider credential and mod…
Pass an optional reason from a plugin custom tool into its permission request	⏸️ untested	no	The custom-tool flow was exercised through the real registry implementation in a focused test process, not through a live model-driven product session; a configured model/provider credential is needed…
Display the optional reason in the native desktop permission prompt	⏸️ untested	no	No configured native desktop runtime/package was available in this test phase. Provide the desktop development runtime and launch configuration to capture this surface live.

• Evidence: Browser permission prompt showing reason, authoritative commands, and approval controls (local file: ~.no-mistakes\evidence\01M2XADT9J2Q4P48KZ75J28ANF\browser-permission-reason.png)
• Outcome: ⚠️ 2 warnings across 1 run (7m40s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

⚠️ **Test** - 2 warnings

• ⚠️ Live browser behavior was demonstrated, but live CLI/TUI and native desktop permission prompts could not be generated without a configured model/provider credential and desktop runtime. Focused executable component tests passed for those surfaces, but they do not qualify as live product evidence.
• ⚠️ live validation verdict: inconclusive (2 of 6 scenarios were driven live against the product); untested: Create permission requests with and without a reason and retrieve the preserved value through pending and single-request APIs, Allow once, allow always, or deny without the reason affecting matching, replies, or saved rules across CLI and TUI prompts, Pass an optional reason from a plugin custom tool into its permission request, Display the optional reason in the native desktop permission prompt
• Live validation: ⚠️ inconclusive - 2 of 6 scenarios driven live against the product

Scenario	Result	Live	Evidence
Create permission requests with and without a reason and retrieve the preserved value through pending and single-request APIs	⏸️ untested	no	The prior payload recorded only an executable HTTP test running in a test process, not a scenario driven against a live end-user server, so it did not establish a live result.
View a nonblank reason beside authoritative permission commands in the running browser UI and approve it without hiding controls	✅ pass	live	browser-permission-reason.png and Playwright scenario shows a pending permission dock
Render HTML-like reasons as plain untrusted text and omit the Reason section for absent or whitespace-only values	✅ pass	live	Playwright cases for absent, empty, whitespace-only, and HTML-like reasons all passed against the running browser UI.
Allow once, allow always, or deny without the reason affecting matching, replies, or saved rules across CLI and TUI prompts	⏸️ untested	no	Generating a genuine interactive CLI/TUI permission request requires a configured model/provider credential, which this isolated environment does not provide. Supply a test provider credential and mod…
Pass an optional reason from a plugin custom tool into its permission request	⏸️ untested	no	The custom-tool flow was exercised through the real registry implementation in a focused test process, not through a live model-driven product session; a configured model/provider credential is needed…
Display the optional reason in the native desktop permission prompt	⏸️ untested	no	No configured native desktop runtime/package was available in this test phase. Provide the desktop development runtime and launch configuration to capture this surface live.

• bun install --frozen-lockfile (native lifecycle build blocked by missing Visual Studio C++ workload)
• bun install --frozen-lockfile --ignore-scripts
• bun test test/permission.test.ts from packages/core
• bun test test/permission.test.ts --test-name-pattern "preserves an optional reason" from packages/core
• bun test test/server/httpapi-v2-location.test.ts --test-name-pattern "preserves a permission reason" from packages/opencode
• bun test test/tool/registry.test.ts --test-name-pattern "passes an optional reason" from packages/opencode
• bun test test/cli/run/footer.view.test.tsx from packages/opencode
• bun test test/cli/cmd/tui/permission-reason.test.tsx from packages/tui
• bun test --conditions=solid --preload ./happydom.ts src/context/global-sync/utils.test.ts src/context/server-sdk.test.ts from packages/app
• bun x playwright test e2e/regression/session-request-docks.spec.ts --project=chromium --grep "shows a pending permission dock|renders permission reason" --workers=1 from packages/app
• Visually inspected the captured browser permission prompt screenshot

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[shabeeth2]

Closing duplicate fork-local PR created by validation automation. The intended PR is anomalyco#49993.