my-pi/pi-permission-system/docs/retro/0096-broaden-subagent-env-hint-keys.md

issue, issue_title

issue	issue_title
96	Subagent permission forwarding broken for all major pi-subagent extensions

Retro: #96 — Subagent permission forwarding broken for all major pi-subagent extensions

Final Retrospective (2026-05-05T20:45:00Z)

Session summary

Planned, implemented, and shipped broadened subagent env-var detection for nicobailon/pi-subagents and HazAT/pi-interactive-subagents, plus a multi-candidate parent-session resolver. Released as v5.2.0 with 35 new tests. The implementation was straightforward — the issue was well-specified with a concrete env var inventory.

Observations

What went well

• The issue's env var inventory table made planning and implementation nearly mechanical — no research phase needed.
• TDD cycles were clean: no downstream breakage, no rework, all 5 steps landed on first attempt.
• The deprecated alias pattern (SUBAGENT_PARENT_SESSION_ENV_KEY kept as candidates[0]) was a low-cost backward-compatibility guard.

What caused friction (agent side)

• instruction-violation — Plan file committed without an H1 heading after YAML frontmatter, triggering markdownlint MD041 pre-commit failure. Every existing plan file has an H1, and MD041 is enabled by default. The /plan-issue prompt template shows frontmatter followed directly by ## Problem Statement with no H1, which is the root cause. Self-identified after the commit hook failed. Impact: one failed commit + fix cycle, minor time waste.

What caused friction (user side)

• No meaningful friction from the user side. The issue was thorough, the related issues (#29, #97, #98) were already filed, and the "Proposed fix" section was concrete enough to skip the ask-user design decision gate entirely.

Changes made

1. Updated .pi/prompts/plan-issue.md — added H1 heading requirement to the "Write the plan" template section.