my-pi/pi-permission-system/docs/retro/0130-handler-classes.md

issue, issue_title

issue	issue_title
130	refactor: replace HandlerDeps with handler classes using narrow constructor injection

Retro: #130 — replace HandlerDeps with handler classes

Final Retrospective (2026-05-08T02:55:00Z)

Session summary

Replaced the monolithic HandlerDeps interface and free-function handlers with three handler classes (SessionLifecycleHandler, AgentPrepHandler, PermissionGateHandler), each with 2–3 narrow constructor deps. Absorbed canPrompt/prompt/createPermissionRequestId into PermissionSession, added a ToolRegistry interface, relocated PromptPermissionDetails to permission-prompter.ts, and deleted src/handlers/types.ts. Released as v5.11.0. This completes the full handler decomposition series (#126 → #127 → #128 → #129 → #130).

Observations

What went well

• The 8-step incremental plan converted one handler class at a time, keeping the repo green after every commit. Zero rework across all steps.
• The lift-and-shift pattern (introduce new alongside old, migrate, delete old last) worked exactly as designed. HandlerDeps survived until step 7, so steps 4–6 could each wire their new class in index.ts independently.
• Test factory simplification was dramatic: makeDeps() with 8 unrelated fields replaced by new Handler(mockSession, ...) with 2–3 typed deps. No as unknown as casts needed for the narrow mocks.
• Full test suite (1288 tests) passed at every step with no behavioral changes, confirming this was a pure refactor.
• The plan correctly identified that canPrompt/prompt needed to migrate to PermissionSession (deferred from #129), preventing a gap when HandlerDeps was deleted.

What caused friction (agent side)

• missing-context — Step 7 (delete HandlerDeps) broke tests/permission-prompter.test.ts which imported PromptPermissionDetails from the deleted src/handlers/types.ts. The plan's module-level changes table did not list this test file. Caught by pnpm run build, fixed immediately. Impact: one extra build-fix cycle, no rework.
• missing-context — Stale HandlerDeps references in JSDoc comments across src/permission-prompter.ts, src/session-logger.ts, src/forwarding-manager.ts, and docs/architecture/permission-prompter.md were not flagged by the plan. Caught during cleanup with grep. Impact: added friction but no rework — comments were updated in the same commit.
• other — Autoformat (Biome) reordered imports in src/index.ts between the handler barrel edit and the wiring edit in step 4, causing the second Edit call to fail on oldText mismatch. Required re-reading the file to get the new import order. Impact: one extra read + retry, ~10 seconds.

What caused friction (user side)

• No friction observed. The user's plan was well-scoped and the issue body provided exact class signatures, making implementation straightforward.