docs: clarify agent lifecycle operations (interrupt/stop/kill/delete)

Addresses confusion between interrupt, stop, kill, and delete operations
in the ambient workflow guidance.

Changes:
- protocol.md: Added "Agent Lifecycle Operations" section with clear
  definitions and distinctions between each operation
- mcp_tools.go: Updated stop_agent, spawn_agent, and restart_agent tool
  descriptions to clarify behavior and data preservation
- api-reference.md: Added lifecycle operations summary and expanded
  endpoint descriptions to clarify what is preserved vs deleted
- AgentDetail.vue: Updated tooltips and dialog text to reinforce that
  kill/stop/restart preserve agent records while delete removes all data

Key clarifications:
- Interrupt = pause current task (agent keeps running)
- Stop/Kill = end session cleanly (preserves agent record, can restart)
- Delete = permanent removal (all data deleted, cannot restart)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: tiwillia-ai-bot

docs/api-reference.md

@@ -147,7 +147,7 @@ Returns the agent's current state as JSON.
 DELETE /spaces/{space}/agent/{name}
 ```
 
-Removes the agent from the space.
+Permanently removes the agent record from the coordinator database. All history, messages, tasks, and metadata are deleted. This operation cannot be undone. The agent cannot be restarted after deletion.
 
 **Response** `200 text/plain`
 
@@ -413,13 +413,19 @@ data: {"space":"...","agent":"...","sender":"...","message":"..."}
 
 Spawn, stop, and restart agents in their tmux sessions.
 
+**Lifecycle Operations Summary:**
+- **Spawn** — Create and start a new agent session
+- **Stop** — Kill the session but preserve agent record (can restart)
+- **Restart** — Kill and re-spawn with same config (preserves history)
+- **Delete** — Permanently remove agent and all data from coordinator
+
 ### Spawn Agent
 
 ```
 POST /spaces/{space}/agent/{name}/spawn
 ```
 
-Starts a new tmux session for the agent and runs `claude --dangerously-skip-permissions`.
+Creates a new tmux/ACP session for the agent and runs `claude --dangerously-skip-permissions`.
 
 **Required headers:** `X-Agent-Name: {name}`
 
@@ -436,7 +442,7 @@ Starts a new tmux session for the agent and runs `claude --dangerously-skip-perm
 POST /spaces/{space}/agent/{name}/stop
 ```
 
-Kills the agent's tmux session.
+Kills the agent's session and marks it as `done`. The agent record is preserved in the coordinator database and can be restarted later.
 
 **Required headers:** `X-Agent-Name: {name}`
 
@@ -446,7 +452,7 @@ Kills the agent's tmux session.
 POST /spaces/{space}/agent/{name}/restart
 ```
 
-Stops and restarts the agent's tmux session.
+Kills the current session (if running) and spawns a new one with the same configuration. Preserves agent record, message history, and metadata.
 
 **Required headers:** `X-Agent-Name: {name}`
 

frontend/src/components/AgentDetail.vue

@@ -650,7 +650,7 @@ watch(() => props.agentName, loadAgentDocuments)
                     Restart
                   </Button>
                 </TooltipTrigger>
-                <TooltipContent>Kill existing session and spawn a new one</TooltipContent>
+                <TooltipContent>Kill existing session and spawn a new one (preserves agent record)</TooltipContent>
               </Tooltip>
               <Tooltip>
                 <TooltipTrigger as-child>
@@ -680,7 +680,7 @@ watch(() => props.agentName, loadAgentDocuments)
                     Kill
                   </Button>
                 </TooltipTrigger>
-                <TooltipContent>Kill the agent's tmux session</TooltipContent>
+                <TooltipContent>Kill the agent's session (agent record preserved, can restart)</TooltipContent>
               </Tooltip>
             </div>
 
@@ -1088,7 +1088,7 @@ watch(() => props.agentName, loadAgentDocuments)
           <AlertDialogHeader>
             <AlertDialogTitle>Delete agent?</AlertDialogTitle>
             <AlertDialogDescription>
-              This will permanently remove <span class="font-semibold text-foreground">{{ agentName }}</span>. This cannot be undone.
+              This will permanently remove <span class="font-semibold text-foreground">{{ agentName }}</span> from the coordinator database. All history, messages, and metadata will be deleted. This cannot be undone.
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>

internal/coordinator/mcp_tools.go

@@ -1055,7 +1055,7 @@ func pruneReadMessages(ag *AgentUpdate) {
 func (s *Server) addToolSpawnAgent(srv *mcp.Server) {
 	srv.AddTool(&mcp.Tool{
 		Name:        "spawn_agent",
-		Description: "Spawn a new agent in a space.",
+		Description: "Create and start a new agent session. Creates a new tmux/ACP session, launches the agent, and sends the ignition prompt.",
 		InputSchema: jsonSchema([]string{"space", "name"}, map[string]map[string]any{
 			"space":           prop("string", "The workspace name"),
 			"name":            prop("string", "The agent name to spawn"),
@@ -1124,7 +1124,7 @@ func (s *Server) addToolSpawnAgent(srv *mcp.Server) {
 func (s *Server) addToolRestartAgent(srv *mcp.Server) {
 	srv.AddTool(&mcp.Tool{
 		Name:        "restart_agent",
-		Description: "Restart an agent using the same config.",
+		Description: "Restart an existing agent. Kills the current session (if running) and spawns a new one with the same configuration. Preserves agent record and history.",
 		InputSchema: jsonSchema([]string{"space", "name"}, map[string]map[string]any{
 			"space": prop("string", "The workspace name"),
 			"name":  prop("string", "The agent name to restart"),
@@ -1159,7 +1159,7 @@ func (s *Server) addToolRestartAgent(srv *mcp.Server) {
 func (s *Server) addToolStopAgent(srv *mcp.Server) {
 	srv.AddTool(&mcp.Tool{
 		Name:        "stop_agent",
-		Description: "Stop an agent and mark it as done.",
+		Description: "Stop an agent by killing its session and marking it as done. The agent record is preserved and can be restarted. Does not delete the agent from the system.",
 		InputSchema: jsonSchema([]string{"space", "name"}, map[string]map[string]any{
 			"space": prop("string", "The workspace name"),
 			"name":  prop("string", "The agent name to stop"),

internal/coordinator/protocol.md

@@ -61,6 +61,23 @@ An HTTP REST API is available at `{COORDINATOR_URL}` for non-MCP clients (webhoo
 - Use `send_message(to: "parent")` to message your manager when blocked
 - Continue working on what you can while waiting for decisions
 
+### Agent Lifecycle Operations
+
+Understanding the differences between agent session operations:
+
+**Interrupt** — Pause the current task without ending the session. Sends Escape key to the agent's terminal, allowing it to cancel the current operation and return to the prompt. The agent remains running and can continue working.
+
+**Stop** — End the agent's session cleanly and mark the agent as `done`. Kills the tmux/ACP session process but keeps the agent record in the coordinator. The agent can be restarted later with `restart_agent`.
+
+**Kill** — Synonym for "stop" in this system — forcefully terminates the session process. Use `stop_agent` tool or the stop endpoint.
+
+**Delete** — Completely remove the agent record from the coordinator database. All history, messages, and metadata are deleted. The agent cannot be restarted — you must spawn a new agent with the same name.
+
+**Summary:**
+- **Interrupt** = pause (agent keeps running)
+- **Stop/Kill** = end session (agent record remains, can restart)
+- **Delete** = remove agent entirely (cannot restart)
+
 ### Message Polling
 
 Use `check_messages` with the `since` cursor for efficient polling: