11. Sessions, Agents & Tasks

This page covers the REPL commands that behave like a workbench: resume saved sessions, inspect background sub-agents, view task lists, and inspect registered tools.

/sessions — saved sessions

The current session is saved under .agentao/sessions/ after every turn, including a turn you interrupt with Ctrl-C or one that fails. So a closed terminal, a killed process, or a crash keeps every turn completed before it. Each save replaces the previous file for the same session, so one session still takes one file. /exit, /clear, and /new save it once more and end it; only those three fire SessionEnd hooks, not the per-turn saves. The restore entry point is /sessions, not replay.

> /sessions
> /sessions resume a1b2c3
> /sessions delete a1b2c3
> /sessions delete all

Command	Effect
/sessions or /sessions list	List saved sessions, newest first
/sessions resume <id>	Resume by session-id prefix; model and active skills are restored too
/sessions delete <id>	Delete one saved session
/sessions delete all	Delete all saved sessions, with single-key confirmation

You can also resume at launch:

agentao --resume          # latest session
agentao --resume a1b2c3   # matching prefix

/agent and /agents — sub-agents

Sub-agents are predefined capabilities that can run in the foreground or background. Built-ins live under agentao/agents/definitions/, and plugins can register more.

> /agent
> /agent codebase-investigator trace the auth data flow
> /agent bg generalist summarize the docs/ tree
> /agents

Command	Effect
/agent or /agent list	List available sub-agents
/agent <name> <task>	Run in the foreground; the REPL waits for the result
/agent bg <name> <task>	Run in the background; status appears in the bottom toolbar, which shows this conversation's tasks and any still running (not ones finished before /new / /clear, nor records from earlier CLI runs). At most 6 run at once; past that the launch is refused with a message, and nothing is queued
/agent status	List this conversation's background tasks and any still running
/agent status --all	Also list earlier conversations and earlier CLI runs (the newest 50 finished ones are kept)
/agent status <id>	Show one background task's result, or its failure. A task that ran but stopped short (budget exhausted, no output) reports Did not finish and still prints its partial result
/agent dashboard or /agents	Open the live dashboard (same scope as /agent status; add --all for earlier ones)
/agent cancel <id>	Cancel a background task
/agent delete <id>	Remove a background-task record

When a background task finishes while the REPL is waiting at an empty prompt, the CLI prints ⟳ background agent finished — continuing and runs one turn so the main agent reads the result — whether the model launched the task or you did with /agent bg. It waits while you are typing, have images staged, or are in plan mode, and after 3 wakes in a row it pauses until you enter something. Turn it off with "background_agents": {"auto_wake": false} in .agentao/settings.json; the result then reaches the agent with your next message.

/todos — current task list

For complex work, the agent may use the todo_write tool to maintain a task list. /todos prints that list.

> /todos

Task List (2/4 completed):
  ✓ Read CLI docs
  ◉ Patch mismatched paths
  ○ Update /help

If there are no tasks, this session hasn't triggered multi-step task planning yet.

/tools — tool registry

/tools lists every tool the current agent can call. /tools <name> prints its parameter schema.

> /tools
> /tools run_shell_command

Use this when debugging “why didn't the agent call that tool”: first confirm the tool is registered, then inspect the permission mode.

Where to go next

Want to…	Read
Review events after resuming	9. Replay & Output
Attach another agent over ACP	8. MCP / ACP / Plugins
Understand sub-agent events in an embedded host	Part 4.2 · AgentEvent

---

Authoritative help

Command syntax: /help. Session restore: agentao/cli/commands/sessions.py:handle_sessions_command. Sub-agents: agentao/cli/commands_ext/agents.py. Tool listing: agentao/cli/commands/tools_intro.py:handle_tools_command.