Teach parent agents to clean up the processes they spawn

Add a `lifecycle` help topic spelling out that the caller owns the
processes it spawns and should `close_process` when a sub-agent or
spawned child is no longer needed. The `spawn_agent` and `spawn_process`
descriptions advertised via `tools/list` now restate the same duty
inline (with a pointer to `help('lifecycle')`), so vendor TUIs see the
expectation at the moment they reach for the tool. The `spawning` topic
and `topics` index cross-reference the new content.

Bundles two already-staged improvements that fall in the same area:
- OnChildSpawned primes the snapshot-replay budget for new panes so
  diff-based vendor TUIs come up clean without a manual Ctrl+W/Ctrl+S
  refresh.
- TODO drops the three items now actioned (prompt-injection preface,
  agent cleanup duty, opencode→claude view corruption) and keeps the
  unicode `<?>` entry with the investigation notes.
This commit is contained in:
2026-05-14 21:17:03 +01:00
parent b361d12d14
commit 56fd461fb3
6 changed files with 147 additions and 9 deletions

View File

@@ -140,7 +140,8 @@ func (h *toolHost) SpawnAgent(callerID string, args mcp.SpawnAgentArgs) (mcp.Pro
if display == "" {
display = args.Agent
}
c, err := h.launcher.LaunchAgent(p, display, args.AgentInstructions, callerID)
prompt := wrapSubAgentPrompt(args.AgentInstructions, h.sess.FindChild(callerID) != nil)
c, err := h.launcher.LaunchAgent(p, display, prompt, callerID)
if err != nil {
return mcp.ProcessInfo{}, err
}
@@ -815,6 +816,25 @@ func (h *toolHost) askForTrust(callerID, presetName, reason string) {
h.prompter.promptTrust(callerID, presetName, reason)
}
// wrapSubAgentPrompt prepends a one-line orientation block to the
// caller-supplied agent_instructions. patterm injects nothing on its
// own (SPEC §7), but vendor TUIs that learn their role purely from
// their first turn need to be told they're a sub-agent — otherwise
// they finish without reporting back to the parent or cleaning up
// processes/scratchpads they spawned. The block is single-line on
// purpose: writeInput splits on CR/LF, so any embedded newline would
// submit prematurely.
func wrapSubAgentPrompt(instructions string, hasParent bool) string {
if !hasParent {
return instructions
}
if instructions == "" {
return ""
}
const preface = "[system: you are a patterm sub-agent. When your work is done, call send_message to your parent (use whoami to get parent_process_id) with a summary, and close_process / scratchpad cleanup anything you created. See help('conventions').] "
return preface + instructions
}
// applyChromeTrim deletes lines matching any of the given regexes.
// SPEC §10 chrome_trim_hints.
func applyChromeTrim(txt string, hints []string) string {
@@ -894,7 +914,7 @@ func helpFor(topic string) mcp.HelpResponse {
case "", "topics":
return mcp.HelpResponse{
Topic: "topics",
Content: "Available topics: spawning, inspection, io, coordination, " +
Content: "Available topics: spawning, lifecycle, inspection, io, coordination, " +
"scratchpads, timers, readiness, permissions, conventions, topics. " +
"Call help(topic) for guidance. Call whoami for your role and the " +
"complete tool list available to you.",
@@ -902,8 +922,14 @@ func helpFor(topic string) mcp.HelpResponse {
case "spawning":
return mcp.HelpResponse{
Topic: "spawning",
Content: "spawn_agent launches another vendor LLM CLI as a sub-agent (orchestrator only). spawn_process(kind: command, preset: …) starts a stored command; spawn_process(kind: terminal) opens a shell. Command presets need trust the first time — you'll get needs_trust until the human accepts.",
RelatedTools: []string{"spawn_agent", "spawn_process", "start_process", "restart_process"},
Content: "spawn_agent launches another vendor LLM CLI as a sub-agent (orchestrator only). spawn_process(kind: command, preset: …) starts a stored command; spawn_process(kind: terminal) opens a shell. Command presets need trust the first time — you'll get needs_trust until the human accepts. Whatever you spawn is yours to clean up — see help('lifecycle').",
RelatedTools: []string{"spawn_agent", "spawn_process", "start_process", "restart_process", "close_process"},
}
case "lifecycle":
return mcp.HelpResponse{
Topic: "lifecycle",
Content: "You own the processes you spawn. When a sub-agent has finished its task (it reports back via send_message, or you've collected what you need from it) call close_process on its process_id to remove the entry and tear down the PTY. Same goes for spawn_process children: command/terminal panes you started are not auto-reclaimed when their work completes. close_process is the normal cleanup path; stop_process(signal) is for sending a signal without removing the entry; start_process re-attaches an exited command preset. Leaving idle sub-agents around wastes vendor tokens and clutters the host — close them as soon as you're done. Sub-agents themselves are reminded (via the [system: …] preface on their first prompt) to clean up anything they created before reporting done.",
RelatedTools: []string{"close_process", "stop_process", "start_process", "list_processes", "get_process_status"},
}
case "inspection":
return mcp.HelpResponse{