Add "lessons/sprints/sprint-3---background-agent-permissions-must-be-pre-granted"

lessons%2Fsprints%2Fsprint-3---background-agent-permissions-must-be-pre-granted.-.md

@@ -0,0 +1,39 @@
+# Sprint 3 - Background Agent Permissions Must Be Pre-Granted
+
+## Metadata
+- **Implementation:** [Change V5.2.0: Plugin Enhancements Proposal (Sprint 3 Hooks)](https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/wiki/Change-V5.2.0:-Plugin-Enhancements-Proposal)
+- **Issues:** #225, #226, #227, #228, #229, #230
+- **Sprint:** Sprint 3
+
+## Context
+During Sprint 3, background agents were spawned to implement hook functionality across multiple plugins. These agents needed to write files, edit code, and run git commands.
+
+## Problem
+Background agents failed silently because they didn't have permissions to use Write, Edit, or Bash tools. Permissions must be explicitly granted before spawning agents - they don't inherit the main session's permissions or prompt for them.
+
+## Solution
+Added the required permissions to `settings.local.json` before spawning agents:
+- `Write` - for creating new files
+- `Edit` - for modifying existing files  
+- `Bash(git:*)` - for git operations
+- `Bash(mkdir:*)` - for creating directories
+
+## Prevention
+**Before spawning background agents:**
+1. Review what operations the agent needs to perform
+2. Pre-grant ALL required permissions in settings.local.json
+3. Include file write (Write, Edit) and relevant Bash commands
+4. Test with a simple operation before full execution
+
+**Permission checklist for agent tasks:**
+- Creating files? Add `Write`
+- Modifying files? Add `Edit`
+- Git operations? Add `Bash(git:*)`
+- Directory creation? Add `Bash(mkdir:*)`
+- Running tests? Add `Bash(pytest:*)` or similar
+
+## Tags
+agents, permissions, claude-code, sprint-3, hooks
+
+---
+**Tags:** agents, permissions, claude-code, sprint-3, hooks