From 1836ce9fc9283b279f4fad46f678df1e3ee28233 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Wed, 28 Jan 2026 15:09:52 +0000 Subject: [PATCH] Add "lessons/sprints/sprint-3---agent-runaway-detection-and-timeout-handling" --- ...unaway-detection-and-timeout-handling.-.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 lessons%2Fsprints%2Fsprint-3---agent-runaway-detection-and-timeout-handling.-.md diff --git a/lessons%2Fsprints%2Fsprint-3---agent-runaway-detection-and-timeout-handling.-.md b/lessons%2Fsprints%2Fsprint-3---agent-runaway-detection-and-timeout-handling.-.md new file mode 100644 index 0000000..40370c6 --- /dev/null +++ b/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 \ No newline at end of file