fix(ambient): remove redundant 'Await instructions' message

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}`
 

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: