#148 Background agents: no cancellation mechanism once launched

[Anonymous]

Originally created by: kumaakh
Originally owned by: kumaakh

Problem

Once a background agent is launched via the Agent tool, there is no way to cancel or stop it. The only interaction mechanism is SendMessage which resumes the agent — it cannot be used to stop it.

This becomes a problem when:

1. A dispatch agent is launched but misbehaves (e.g. calls execute_prompt multiple times)
2. The PM kills the fleet sessions to clean up
3. The misbehaving agent is still alive locally, waiting for its execute_prompt calls to time out
4. When those calls error out, the agent may retry — firing more execute_prompt calls against the same member

Impact

Two background agents simultaneously pointing at the same member, both capable of calling execute_prompt. The PM has no way to stop either one.

Proposed Fix

The Agent tool (or a companion tool) should support a cancel or stop signal — e.g. SendMessage(to: '<agent_id>', stop: true) — that causes the agent to exit cleanly after its current tool call completes, without starting new ones.

Alternatively, background agents should have a TTL or a way to be listed and stopped via a fleet-level list_agents / stop_agent command.

Related

• [#147] — execute_prompt should kill previous instances on same member

[Anonymous]

Originally posted by: kumaakh

Technical direction: This is a Claude Code / Agent framework limitation — there is no cancel API today. The practical mitigation is fleet-server-side:

Approach:

• Add a cancel_task operation to src/tools/monitor-task.ts (or a new cancel-task.ts tool): given a task_id, look up the PID from ~/.fleet-tasks/<taskId>/task.pid and SIGTERM/process.kill it. Update the task status to cancelled.
• In execute_prompt, before launching a new task on a member, check if a previous task for that member is still alive (by PID). If so, kill it first (or return an error if force is not set). This covers the 'PM killed fleet sessions but dispatch agent retries' scenario.
• For the background agent TTL problem: document in the PM skill that background agents must be given a max_turns budget and a self-termination instruction in their prompt ('if you have retried more than N times, stop'). This is the only lever available until the Agent tool gains native cancellation.

Key files:

• src/tools/monitor-task.ts or new src/tools/cancel-task.ts
• src/tools/execute-prompt.ts — add member-level previous-task kill before new dispatch
• ~/.fleet-tasks/<taskId>/task.pid — already written by the long-running task infrastructure

[Anonymous]

• assigned_to: kumaakh

[Anonymous]

Ticket changed by: kumaakh

• status: open --> closed