agent_interrupt — Claude Code subagent: what it does, how to install
This Claude Code subagent stops another agent and can send it a new instruction immediately. Use it to interrupt a stalled loop, repeated failure, or work heading in the wrong direction.
MIT ★ 395 updated 2026-11-16
.claude/agents/agent_interrupt.mdWhat agent_interrupt does
agent_interrupt cuts off the selected agent’s current turn and can pass it a replacement instruction right away. Select the machine by the name or ID shown in agents_list, then provide the agent’s session ID or its first eight characters. Leave then empty to stop without sending a message.
The agent and its session remain, but completed work is untouched. Files already changed and commands already run need a separate instruction to undo. This subagent does not target assistant conversations or read-only agents. A then value containing only /exit or /quit is rejected for an agent on a task supervised by another conversation; nothing is stopped or sent.
What it helps with
- stop an agent repeating a failed step
- interrupt an agent stuck polling or sleeping
- redirect an agent without ending its session
- send a replacement instruction as the agent stops
Example prompts for the agent
- Stop the agent on
devboxwith sessiona1b2c3d4and ask it to revert its latest changes tosrc/app.ts. - Interrupt session
a1b2c3d4ondevbox; it is stuck checking the same thing. - Stop agent
a1b2c3d4ondevboxwithout sending another instruction.
How to install agent_interrupt
Manually: put the files in place
.claude/agents/agent_interrupt.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/agent_interrupt.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/agent_interrupt.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about agent_interrupt
How do I install agent_interrupt in Claude Code?
Place the subagent file at .claude/agents/agent_interrupt.md.
What does agent_interrupt do?
It interrupts a selected agent’s current turn and can send it another instruction immediately. The agent and its session remain active.
What details are needed to stop an agent?
Provide the machine name or ID from agents_list, plus the session ID or its first eight characters. Work already done is not rolled back.
Source text
agent_interrupt.md · MIT
Stop what an agent (from agents_list) is doing right now, and optionally redirect it: its current turn is cut off (Esc in its terminal, or its runtime's cancel), the agent and its session stay, and `then` is sent to it at once as the user would type it. Use it when waiting is worse than stopping: it works in the wrong direction, waits in a loop (sleep, polling), repeats a failing step, collides with another agent, or the user said stop. To add a word to an agent that works fine, use agent_send instead (queued behind its turn). What it did already is not undone (files it changed, commands it ran): tell it in `then` what to put back. Not for assistant conversations, and not for agents that can only be read. A `then` of only /exit or /quit to an agent on a task another conversation supervises is refused, as agent_send refuses it: nothing is stopped or sent.
```json
{
"type": "object",
"required": ["machine", "session_id"],
"properties": {
"machine": {
"type": "string",
"description": "the machine's id or name, as agents_list shows it"
},
"session_id": {
"type": "string",
"description": "the agent's session id, or its first 8 characters"
},
"then": {
"type": "string",
"description": "the new instruction, sent right after it stopped; empty: just stop it"
}
}
}
```
© nwverse · MIT · nwverse/persona