feat: vendor permission system source

2026-08-28 08:35:57 +00:00 · 2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
@@ -0,0 +1,53 @@
+---
+issue_title: "Investigate double-prompt on external directory permission checks"
+---
+
+# Retro: double-prompt investigation
+
+## Final Retrospective (2026-05-08T14:45:00Z)
+
+### Session summary
+
+Investigated a user report that external-directory permission prompts required two Enter presses.
+After extensive instrumentation and bisection, the root cause was the extension being loaded twice — once from the global `npm:@gotgenes/pi-permission-system` package and once from the project `.pi/settings.json` entry `"../"`.
+Two handler instances meant two identical `ui.select` prompts for every gate check.
+Fixed by suppressing the npm copy's extension in project settings with `{ "source": "npm:@gotgenes/pi-permission-system", "extensions": [] }`.
+Also closed a testing gap with integration tests for session-rule dedup across sequential tool calls.
+
+### Observations
+
+#### What went well
+
+- The instrumentation approach (file-based trace at multiple layers: handler entry, gate runner, prompter, `ui.select`) was effective once applied — it definitively proved one `ui.select` call per prompt.
+- The integration tests written for session-rule dedup (`tests/handlers/external-directory-session-dedup.test.ts`) are genuine value — they use stateful mocks that model the real `checkPermission`/`approveSessionRule`/`getSessionRuleset` interaction, covering same-path, same-directory, different-directory, approve-once vs approve-for-session, and cross-tool (bash→read) scenarios.
+- Bisection via `pi --no-extensions -e .` was the decisive experiment — it immediately proved the bug vanished in isolation.
+
+#### What caused friction (agent side)
+
+1. `rabbit-hole` — spent multiple instrumentation rounds and reload cycles investigating hypotheses (concurrent tool calls, working-indicator focus stealing, Pi TUI `ExtensionSelectorComponent` regression, forwarding poller interference) before checking the simplest environmental explanation: whether the extension was loaded twice.
+   Impact: ~45 minutes of user time across 6+ reload-and-test cycles, 4 files instrumented then cleaned up, several dead-end hypotheses explored.
+
+2. `missing-context` — did not inspect `.pi/settings.json` or cross-reference it with `~/.pi/agent/settings.json` early in the session.
+   The project settings file was right there and showed both `"../"` and the global npm package loading the same extension.
+   Impact: this single check would have resolved the investigation in minutes.
+
+3. `premature-convergence` — after confirming Pi dispatches `beforeToolCall` sequentially (via the agent-loop source), concluded "the bug can't exist" and almost closed the investigation.
+   The user had to push back ("From my perspective it seems to be the same prompt, twice") to keep investigating.
+   Impact: nearly missed the real bug by trusting the theoretical model over the user's observation.
+
+4. `wrong-abstraction` — early instrumentation wrote to `/tmp/gate-trace.log`, which bash commands like `: > /tmp/gate-trace.log` then truncated, destroying the trace.
+   Switched to `/tmp/gate-trace-2.log` mid-investigation.
+   Impact: lost trace data from several experiments, required re-running them.
+
+#### What caused friction (user side)
+
+- The user's initial framing ("two tool calls with the same path") sent the investigation toward concurrent-dispatch dedup, which was a plausible but incorrect hypothesis.
+  Reframing to "I had to press Enter twice" and "I had to answer twice" were the pivotal observations that redirected the investigation.
+  Opportunity: when reporting UI bugs, "what did the screen do" is more diagnostic than "what I think the system did."
+
+### Changes made
+
+1. `tests/handlers/external-directory-session-dedup.test.ts` — 6 integration tests for session-rule dedup across sequential tool calls.
+2. `.pi/settings.json` — added `{ "source": "npm:@gotgenes/pi-permission-system", "extensions": [] }` to prevent double-loading.
+3. `AGENTS.md` — added § Debugging with isolation-first heuristic.
+4. Commented on [earendil-works/pi#4033](https://github.com/earendil-works/pi/issues/4033) with the cross-scope variant of the duplicate-package bug.