Feature: Iterative mode for team_spawn — keep agents alive for multi-turn refinement

[saahil-khan]

Problem

team_spawn is currently one-shot: agent works → reports → stops. The reported_to_lead flag blocks further messages. The lead system prompt says "summarize results and suggest next steps" — it's a linear shutdown pipeline.

Real-world use: a prompt engineering team of 5 agents where the user wants to go back-and-forth with each agent, iteratively refining outputs. Each agent asks follow-up questions, gets feedback, iterates, and only finishes when the user says "I'm satisfied."

Proposed Solution

New iterative parameter on team_spawn:

team_spawn({
  name: "prompt-engineer",
  agent: "S1-intent-decoder-prompt-engineer",
  iterative: true,
  prompt: "Refine this prompt..."
})

Changes Required (3 files)

---

1. src/tools/team-spawn.ts — Context message for iterative agents

When iterative === true, replace the standard "When you finish your task" block with:

IMPORTANT: You are in ITERATIVE MODE. You will go through multiple rounds of refinement
with the lead until they are satisfied.

When you complete a round of work:
1. Send your current output to the lead via team_message using the <task-result> format
2. Then WAIT. Do NOT stop. Do NOT mark your task complete.
3. The lead will respond with feedback, questions, or new instructions
4. Incorporate the feedback and iterate
5. Repeat until the lead explicitly says "I'm satisfied" or "you're done"

Only when the lead says you're done:
- Mark your task complete with team_tasks_complete
- Send one final <task-result> message

---

2. src/system-prompt.ts — Lead system prompt additions

After the existing merge workflow section, add when iterative agents are present:

ITERATIVE MODE:
Some teammates are in ITERATIVE MODE. Do NOT shut them down after they report results.
Do NOT call team_cleanup while any iterative agent is active.

When an iterative agent sends results:
- Read their full message with team_results
- Relay the findings to the user
- Wait for the user's explicit feedback before messaging the agent back
- The user may say "Looks good, ask them to refine X" or "I'm satisfied with this one"

Reply to iterative agents via team_message with the user's feedback.
Only shut down and merge an iterative agent when the user explicitly says
"I'm satisfied with [agent-name]" or "shut down [agent-name]".

team_cleanup should only be called after ALL iterative agents are done.

---

3. src/messaging.ts / src/index.ts — Completion-loop prevention

The reported_to_lead flag currently blocks further message delivery to completed agents. For iterative agents, either:

• Skip reported_to_lead flagging for iterative agents (they never "complete" until told), OR
• Add a new iterative column to team_member and check it before blocking delivery

Simplest: don't set reported_to_lead when iterative === true.

---

How it works end-to-end

User:  "Run my 5 prompt-engineering agents in iterative mode"

Lead:  Spawns S1, S2, dr-brac, converter, S2-assembly with iterative: true
       "I've spawned 5 agents. They'll report their first drafts and wait for feedback."

S1:    <task-result>Here's my first prompt draft... [waits]
User:  "S1: Add more design system terminology, make it more instructional"
Lead:  team_message(to: S1, "Lead says: add more design system terminology...")
S1:    <task-result>Updated draft with design system focus... [waits]
User:  "Perfect. I'm satisfied with S1."
Lead:  team_message(to: S1, "Lead is satisfied. Mark complete and send final.")
S1:    <task-result status="completed">Final draft</task-result>
Lead:  team_shutdown("S1") → team_merge("S1")

...same for other 4 agents...

User:  "All done"
Lead:  team_cleanup (all iterative agents already shut down)

Edge cases

• User disconnects: watchdog timeout still applies. If iterative: true, extend the idle timeout (or make it configurable per-spawn).
• Agent goes idle without responding: stall detection still applies; escalate to lead.
• Spawn with iterative: true on read-only agent: allowed — iterative exploration/review is valid.
• Mixed team: some iterative, some one-shot. Lead handles each according to its mode.