feat: vendor permission system source

pi-permission-system/docs/retro/0058-path-gate-universal-default.md

@@ -0,0 +1,47 @@
+---
+issue: 58
+issue_title: "The permission configuration is invalid on the Windows system"
+---
+
+# Retro: #58 — The permission configuration is invalid on the Windows system
+
+## Final Retrospective (2026-05-16T22:30:00Z)
+
+### Session summary
+
+Fixed a platform-independent bug where the cross-cutting `path` permission gate (introduced in #148) fired for every path-bearing tool call when users configured `"*": "ask"` without an explicit `"path"` surface entry.
+The fix was two `matchedPattern === undefined` early-return checks (one in `describePathGate`, one in `describeBashPathGate`) plus wiring session rules into the tool path gate's pre-check.
+Released as `pi-permission-system@5.18.2`.
+
+### Observations
+
+#### What went well
+
+- `missing-context` **recovery was fast once redirected.**
+  The user's "is that a red herring?"
+  intervention cut short a Windows path-resolution rabbit hole.
+  Once redirected to the config interaction, tracing through `describePathGate` → `checkPermission` → `evaluate` → universal default rule took only one read cycle to pinpoint.
+  The `matchedPattern === undefined` discriminator was identified from reading `PermissionManager.checkPermission()` once — the `rule.layer` → `matchedPattern` mapping is clean.
+
+- **Downstream test breakage was small and predictable.**
+  Only `tests/handlers/tool-call.test.ts` broke (2 tests), and the fix was mechanical: add `matchedPattern: "*.env"` to mocks that represent explicit config rules.
+  The plan didn't anticipate this, but the deviation was flagged and resolved in the same commit.
+
+#### What caused friction (agent side)
+
+1. `rabbit-hole` — Spent ~6 tool calls exploring Windows-specific path handling (`config-paths.ts`, `extension-paths.ts`, `expand-home.ts`, `node-modules-discovery.ts`, `getAgentDir` resolution) before the user redirected.
+   The issue title ("invalid on the Windows system") anchored investigation on platform behavior when the GIF attachment (unviewable) and the config itself were the real signal.
+   Impact: added friction but no rework — no code was written during the exploration.
+
+2. `missing-context` — Did not attempt to fetch/view the issue's screenshot early.
+   The GIF was unviewable (unsupported content type), but trying earlier would have surfaced that gap sooner and forced a config-level analysis from the start.
+   Impact: minor — the user's redirect was quick.
+
+#### What caused friction (user side)
+
+- The user could have included the key insight ("look at the config interaction, not the OS") in the initial prompt instead of waiting for the first round of exploration.
+  However, their redirect ("is that a red herring?") was well-timed and efficient — it came before any code changes, so no rework was caused.
+
+### Changes made
+
+1. Wrote this retro file at `packages/pi-permission-system/docs/retro/0058-path-gate-universal-default.md`.