[NEEDS GROOMING] Build execution profiles UI (Read Only / Ask Every Time / Auto Approve) since pi-coding-agent has no built-in permission-mode system

[tbrandenburg]

Background

Follow-up to #132 (re-enabling pi-coding-agent's full built-in tools). #132 accepts "no approval gate" as an interim tradeoff for a 1-day config flip. This issue tracks building a real, user-facing permission/execution-profile system on top of that.

Confirmed (exhaustive research, see #132) that pi-coding-agent deliberately does not ship any named permission-mode concept. Straight from its README:

"No permission popups. Run in a container, or build your own confirmation flow with extensions..." (node_modules/@earendil-works/pi-coding-agent/README.md:499)
"No plan mode. Write plans to files, or build it with extensions, or install a package." (README.md:501)

So there is nothing like Claude Code's default/acceptEdits/bypassPermissions/plan modes to adopt as-is — pi-desktop needs to build its own "execution profiles" concept on top of pi-coding-agent's lower-level primitives, and expose it in the UI.

Available primitives (all confirmed to exist)

1. Tool allow/deny-lists on CreateAgentSessionOptions (dist/core/sdk.d.ts:10-46): tools?: string[], excludeTools?: string[], noTools?: "all" | "builtin", plus a ready-made createReadOnlyTools() factory. Runtime-live equivalent: ExtensionAPI.getActiveTools() / setActiveTools(toolNames) (dist/core/extensions/types.d.ts:933,937).
2. tool_call extension event (dist/core/extensions/types.d.ts:648-778) — fires before every bash/read/edit/write/grep/find/ls/custom tool call. Handler can return { block: true, reason } to veto, or mutate event.input in place before execution. Wired internally by AgentSession (core/agent-session.js:214-259) regardless of trust status — a separate mechanism from the per-package install-time trust gate (fix(packages): share PackageService with real ~/.pi/agent + close trust-gate bypass #107-refactor(packages): replace per-package trust gate with install-time consent #110).
3. ctx.ui.confirm / ctx.ui.select (dist/core/extensions/types.d.ts:71-72,399) — interactive confirmation primitives used by pi's own CLI/TUI extensions. These are TUI-specific and not usable directly in pi-desktop per architecture rule fix: distinct artifact names for Windows nsis/portable targets #4 (renderer never talks to Node/Pi APIs directly) — pi-desktop needs its own IPC-driven equivalent instead.
4. Reference implementations already exist in pi-coding-agent's own examples/extensions/, worth reading directly as a starting template:
   • examples/extensions/permission-gate.ts — regex-detects dangerous bash commands (rm -rf, sudo, chmod/chown 777) and confirms via ctx.ui.select before allowing.
   • examples/extensions/plan-mode/index.ts — full read-only-exploration-mode pattern: toggles getActiveTools()/setActiveTools() and blocks non-allowlisted bash commands via tool_call.

Proposed execution profiles

Profile	Implementation
Read Only	excludeTools: ["bash","edit","write"] (or createReadOnlyTools()); no tool_call handler needed.
Ask Every Time	Full built-ins + an inline tool_call handler that blocks execution until an IPC round-trip to a renderer confirmation dialog resolves (approve/deny), modeled on permission-gate.ts.
Auto Approve (a.k.a. "skip permissions")	Full built-ins, no tool_call handler at all — current end state of #132.
Plan Mode (optional/bonus)	Reuse the plan-mode example's pattern: start read-only for exploration, toggle to full tools only once the user explicitly promotes the session to "execute".

What needs to change

1. src/main/agent/runtime.ts

   • Add an execution-profile parameter to AgentRuntime/its run() method (or read from settings), mapping each profile to the right tools/excludeTools/noTools combination on createAgentSession(...).
   • For "Ask Every Time", register an inline tool_call extension handler via DefaultResourceLoaderOptions.extensionFactories (the same seam already used for additionalExtensionPaths in buildAdditionalPathsResourceLoader()), that pauses execution and awaits an IPC-driven approval from the renderer before resolving { block }.

2. New IPC channel(s) (following the <domain>:<verb> convention, docs/INITIAL.md/AGENTS.md "Adding an IPC channel" recipe):

   • src/shared/events.ts — add method signature(s), e.g. tool:confirm (main → renderer request) and its response shape, plus a settings-facing settings:getExecutionProfile / settings:setExecutionProfile pair.
   • src/preload/index.ts — expose the new methods on api.
   • src/main/ipc.ts — wire the handler(s); the tool:confirm flow will need to be a webContents.send + one-shot response channel (main-initiated, not renderer-invoked), since it's the main process asking the renderer for a decision mid-tool-call.
   • src/renderer/lib/fake-desktop-api.ts — update the in-memory fake so the browser dev harness keeps working (per repo convention).

3. Renderer UI

   • A profile selector (e.g. in Settings or a per-conversation control) persisted via the settings store, following the existing SettingsStore/Sidebar.tsx component conventions (flat file under src/renderer/components/, styled via the single shared styles.css).
   • A confirmation dialog component for "Ask Every Time" mode, showing the tool name + event.input (command/path/content) with Approve/Deny actions, wired to resolve the pending tool:confirm IPC request.

4. Persistence

   • Store the selected execution profile per-session (or globally, TBD) alongside existing session state (SessionService/session-projection.ts), so resumed conversations restore the profile the same way they already restore selectedModel (see AGENTS.md lesson fix: distinct artifact names for Windows nsis/portable targets #4).

5. Docs

   • docs/adr/0001-reuse-pi-extension-mechanism.md — document the new tool-permission architecture (profiles, the tool_call handler mechanism, IPC confirmation flow) once implemented, superseding the "no approval gate" interim note added by Re-enable pi-coding-agent's full built-in tools (bash/edit/write/read/list), remove read-only-only scope #132.
   • STATUS.md — new milestone entry.
   • AGENTS.md — update "Adding an IPC channel" section if the confirm-dialog pattern introduces a new recipe worth documenting (main-initiated request/response over IPC is a new pattern not covered by the existing invoke-based recipe).

Testing

• Unit test the profile → createAgentSession option mapping (no real network/tool execution).
• Unit/integration test the tool_call handler's block/allow logic independent of the UI (given a fake confirm resolver).
• E2E: verify via the fake-desktop-api.ts browser harness that switching profiles changes available tools, and that "Ask Every Time" actually surfaces a confirmation dialog before a tool call event is shown in the timeline.

Acceptance criteria

• Three profiles implemented: Read Only, Ask Every Time, Auto Approve.
• Profile selectable in the renderer UI and persisted (settings and/or per-session).
• "Ask Every Time" blocks tool execution on a real tool_call event until the renderer responds via IPC; rejecting the dialog actually prevents the tool from running (verified against the real packaged app, not just dev mode — see AGENTS.md "packaged app" testing rules).
• "Read Only" profile produces the same tool restriction as Re-enable pi-coding-agent's full built-in tools (bash/edit/write/read/list), remove read-only-only scope #132's now-removed bundled read-only-tools package (parity check).
• Docs (ADR 0001, STATUS.md, AGENTS.md) updated.
• Depends on Re-enable pi-coding-agent's full built-in tools (bash/edit/write/read/list), remove read-only-only scope #132 (full built-in tools) being merged first.

[tbrandenburg]

Warning

⚠️ NEEDS GROOMING BEFORE PICKING UP

This issue is a rough scope dump from research/discussion, not a ready-to-implement spec. Before starting work, groom it: confirm the profile set (3 vs. 4 with Plan Mode), decide session-level vs. global persistence, nail down the main-initiated IPC confirm-dialog pattern (no existing recipe for this in the repo), and re-validate all primitives still apply once #132 lands. Do not start implementation straight from this issue as-is.

[why459097630]

Your execution profiles make sense, but you should definitely try a workflow where AI never gets write access at all. I send a project ZIP + prompt to web AI, get exact BEFORE/AFTER patches, then load them into ChangeLatch, a local patch review/apply tool. I review and approve every change there before it touches the real project.

[tbrandenburg]

Note: @gotgenes/pi-permission-system as the likely permission-UI vendor — findings + working assumptions

While scoping this issue we looked at whether we should reuse an existing community extension rather than build the approval UI from scratch, and landed on @gotgenes/pi-permission-system (npm, ~31k weekly downloads, MIT, the de-facto standard in the pi-package ecosystem — see issue discussion history) as the leading candidate. Summary of what we found and what we're assuming:

What it gives us for free

• A real policy engine (allow/deny/ask per tool, bash pattern, path, MCP/skill) with a documented config format (~/.pi/agent/extensions/pi-permission-system/config.json), project-trust gating, fail-closed bash parsing, and an extensible authorizer-chain for future automated pre-checks (deny-first model judges etc.) — all things we would otherwise have to design and build ourselves for [NEEDS GROOMING] Build execution profiles UI (Read Only / Ask Every Time / Auto Approve) since pi-coding-agent has no built-in permission-mode system #133.
• It already reads ctx.mode and degrades gracefully for non-TUI hosts (source-verified, see below) — it isn't a TUI-only package.

Verified via source read (not just README)

Its interactive dialog has two code paths, gated on ctx.mode:

• mode === "tui": a hand-rolled ctx.ui.custom() Component (src/authority/permission-prompt-component.ts) giving the full y/s/n/r hotkeys + double-press-to-confirm safety behavior. This is TUI-only rendering (@earendil-works/pi-tui Component) with no React/Electron equivalent — permanently out of reach per ADR 0001 §3.4.
• Any other mode (src/authority/permission-dialog.ts, requestPermissionDecisionFromUi): falls back to the fully generic ctx.ui.select() + ctx.ui.input() primitives — the same approve/session-approve/deny/deny-with-reason choices, just without hotkeys/double-press.

pi-desktop reports mode: "rpc" (src/main/agent/runtime.ts:158), which is exactly the fallback condition. Working assumption: the extension's core ask flow already renders correctly in pi-desktop today, via the existing generic select/input/confirm IPC bridge, with zero new code required — this has not yet been verified end-to-end in a running pi-desktop instance (only traced statically), so treat as a strong hypothesis pending a real install-and-click-through test.

What would still be missing / needed if we adopt it

1. UX polish only, not a functional gap: no hotkeys, no double-press-confirm safety in the fallback path — acceptable for a mouse/keyboard-driven Electron app, but worth a follow-up if we want approval-decision parity with the TUI experience.
2. Bundling posture is still an open decision, not yet made: it's a third-party community package (fork of a fork), not one of ADR 0001's three approved Pi packages (pi-ai/pi-agent-core/pi-coding-agent). Two options, not mutually exclusive:
   • Soft bundle (lower risk, preferred): surface it as a one-click "recommended package" in the existing Settings → Packages UI (PackageService, already wired to DefaultPackageManager) — reuses the existing install-consent flow (Simplify: replace the per-package trust gate with one-time install consent + transparency #109), no ADR change, no silent ~/.pi/agent/settings.json mutation for users who also use the real pi CLI.
   • Hard bundle (always-on default): ship as a real dependency + always-registered extension — would need an explicit ADR update and supply-chain vetting; not recommended as the default posture given the existing "no hidden install/no hidden loaded state" design tenet (Simplify: replace the per-package trust gate with one-time install consent + transparency #109).
3. No test coverage or vetting yet on our side of its actual runtime behavior in pi-desktop — before relying on it we'd want a real end-to-end run (install via Settings → trigger an ask policy → confirm the select()/input() dialog renders and resolves correctly), not just this static trace.

Recommendation

Treat "adopt @gotgenes/pi-permission-system via the soft-bundle path" as the current leading design direction for #133's policy engine, pending: (a) a real end-to-end verification run of the RPC-mode fallback dialog, and (b) an explicit go/no-go on the bundling posture (soft vs hard) before any implementation starts.

[tbrandenburg]

Decision: soft-bundle `@gotgenes/pi-permission-system`

Following up on the previous note — decided: go with the soft-bundle path, not hard-bundle.

Concretely: surface `@gotgenes/pi-permission-system` as a one-click "recommended package" in the existing Settings → Packages UI, reusing `PackageService`/`DefaultPackageManager` and the existing install-consent flow (#109) as-is. No ADR update, no always-on dependency, no change to the "no hidden install/no hidden loaded state" design tenet — installing it stays an explicit, visible user action like any other package.

Not yet implemented — this just records the direction so future work on #133 doesn't have to re-litigate soft vs. hard bundling. Still open before implementation:

• Real end-to-end verification that its RPC-mode fallback dialog (`select()`/`input()`) actually renders and resolves correctly in a running pi-desktop instance (only statically traced so far).
• Where exactly to surface the "recommended package" affordance in the Settings UI.