Add "lessons/sprints/sprint-3---agent-runaway-detection-and-timeout-handling"

lessons%2Fsprints%2Fsprint-3---agent-runaway-detection-and-timeout-handling.-.md

@@ -0,0 +1,41 @@
+# Sprint 3 - Agent Runaway Detection and Timeout Handling
+
+## 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
+Background agents were spawned to implement hook functionality. Some agents ran for extended periods without completing.
+
+## Problem
+Agents ran 400+ tool calls over approximately 1 hour without completing their tasks. They got stuck in loops or kept exploring tangential paths instead of completing the core implementation. Manual intervention was required to stop them and commit the partial work.
+
+## Solution
+1. Stopped the runaway agents manually
+2. Reviewed what work had been completed
+3. Committed the completed portions
+4. Finished remaining work in the main session
+
+## Prevention
+**Agent design best practices:**
+1. Give agents NARROW, SPECIFIC tasks (not broad "implement feature X")
+2. Include explicit completion criteria in the agent prompt
+3. Set maximum tool call limits when possible
+4. Break large tasks into smaller subtasks with checkpoints
+
+**Monitoring:**
+1. Check agent progress periodically (every 15-20 minutes)
+2. If agent exceeds 100 tool calls, review if it's making progress
+3. Look for repetitive patterns (same files being read/edited repeatedly)
+4. Be ready to intervene and salvage partial work
+
+**Task scoping:**
+- BAD: "Implement the vagueness detection hook"
+- GOOD: "Create hooks/hooks.json with a UserPromptSubmit hook that runs detect-vagueness.sh"
+
+## Tags
+agents, timeout, runaway, claude-code, sprint-3
+
+---
+**Tags:** agents, timeout, runaway, claude-code, sprint-3