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,57 @@
+---
+issue: 147
+issue_title: "Per-tool path patterns for path-bearing tools"
+---
+
+# Retro: #147 — Per-tool path patterns for path-bearing tools
+
+## Final Retrospective (2026-05-13T20:45:00-04:00)
+
+### Session summary
+
+Designed and shipped per-tool path patterns for path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) in a single session.
+The design phase was the bulk of the work — exploring OpenCode's model, nested bash rules with additive evaluation, a universal `path` surface, and ultimately converging on a minimal `normalizeInput` change.
+The implementation was ~10 lines of production code; the rest was tests, docs, and gate-composition verification.
+Filed #148 (path-aware bash rules) as a follow-on.
+
+### Observations
+
+#### What went well
+
+- **Design exploration produced a better outcome than the original issue.**
+  The user's redirections ("why make external paths special?", "bash is fundamentally opaque to read vs write") steered the design away from tool-type keys in `external_directory` toward per-tool path patterns — a cleaner, more general solution.
+  Two GitHub issues were filed (#147, #148) that together cover more ground than the original #144.
+- **`ask_user` earned its keep.**
+  Two calls surfaced genuine design forks (tool-keys-vs-path-patterns, compound-vs-simple keys).
+  The user's free-text responses ("I don't actually know" / "I like the clean separation") were more valuable than any preset option.
+- **Tiny implementation, large impact.**
+  The change to `normalizeInput` was ~10 lines.
+  The existing `evaluate()` / `evaluateFirst()` / `wildcardMatch()` machinery already supported arbitrary pattern matching — no new evaluation logic was needed.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — Skipped `docs/configuration.md` and `docs/opencode-compatibility.md` during the docs step despite the plan's Module-Level Changes table listing 7 files.
+   Updated only 4 (schema, example config, README, architecture.md).
+   User caught it with "Did we update the configuration.md document too?"
+   Impact: follow-up commit after CI passed and release merged. (user-caught)
+
+2. `missing-context` — Every config example that set `"write": "deny"` or `"write": "ask"` omitted `"edit"`.
+   The `edit` tool is a real Pi tool that modifies files, but it's easy to forget because it's less commonly referenced.
+   User caught it with "Then shouldn't our examples show it?"
+   Impact: follow-up commit touching 3 files. (user-caught)
+
+3. `wrong-abstraction` — When asked "can the user allow reading all external paths but not `~/.ssh/*`?", I analyzed the gates in isolation and claimed there were gaps.
+   The user showed the OpenCode example and I realized the two-gate composition (`external_directory` + per-tool rules) already works correctly.
+   Impact: added confusion to the conversation but no rework. (user-caught)
+
+#### What caused friction (user side)
+
+- The user's early exploration of nested bash rules and a universal `path` surface was valuable design work, but it extended the design phase significantly before converging on the simpler per-tool path patterns scope.
+  This was appropriate given the design space, but earlier convergence on "what's the minimal viable scope?"
+  could have shortened the session.
+  Not a criticism — the exploration produced #148 as a well-scoped follow-on.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — Added explicit cross-check step (step 4) in "After the last TDD step": verify all files listed in the plan's Module-Level Changes table were actually touched.
+2. `AGENTS.md` — Added rule: when a config example sets a policy for `write`, include the same policy for `edit`.