diff --git a/docs/ai-coder/agent-compatibility.md b/docs/ai-coder/agent-compatibility.md
new file mode 100644
index 0000000000..8f0352e183
--- /dev/null
+++ b/docs/ai-coder/agent-compatibility.md
@@ -0,0 +1,92 @@
+# Agent compatibility
+
+Coder Tasks works with a range of AI coding agents, each with different levels
+of support for preserving conversation context across pause and resume cycles.
+This page covers which agents support resume, what session data they store,
+and what to watch out for when configuring persistent storage.
+
+## Compatibility levels
+
+Agents with **full support** automatically resume the previous session when a
+task resumes. The conversation history, tool calls, and context are all
+preserved, so the agent picks up exactly where it left off.
+
+Agents with **partial support** have resume wiring in the module but it is
+either off by default or has known bugs. A module update is needed before resume
+works reliably. See the linked tracking issue for details.
+
+Agents with **planned support** have native session persistence but the registry
+module does not wire it yet. These agents start a fresh conversation on each
+resume until the module is updated.
+
+Agents marked **not supported** cannot resume a previous session. They start a
+fresh conversation on each resume, even if some chat history is visible in the
+UI.
+
+## Compatibility matrix
+
+| Agent           | Module                                                                           | Min version | Support       | Tracking                                                     | Session data paths                                   | Min storage               |
+|-----------------|----------------------------------------------------------------------------------|-------------|---------------|--------------------------------------------------------------|------------------------------------------------------|---------------------------|
+| Claude Code     | [claude-code](https://registry.coder.com/modules/coder/claude-code)              | >= 4.8.0    | Full          | -                                                            | `~/.claude/`                                         | 100 MB (can grow to GB)   |
+| Codex           | [codex](https://registry.coder.com/modules/coder-labs/codex)                     | -           | Partial       | [registry#740](https://github.com/coder/registry/issues/740) | `~/.codex/`, `~/.codex-module/`                      | 100 MB                    |
+| Copilot         | [copilot](https://registry.coder.com/modules/coder-labs/copilot)                 | -           | Partial       | [registry#741](https://github.com/coder/registry/issues/741) | `~/.copilot/`                                        | 50 MB                     |
+| OpenCode        | [opencode](https://registry.coder.com/modules/coder-labs/opencode)               | -           | Partial       | [registry#742](https://github.com/coder/registry/issues/742) | `~/.local/share/opencode/`, `~/.config/opencode/`    | 50 MB                     |
+| Auggie          | [auggie](https://registry.coder.com/modules/coder-labs/auggie)                   | -           | Planned       | [registry#743](https://github.com/coder/registry/issues/743) | `~/.augment/`                                        | 50 MB                     |
+| Goose           | [goose](https://registry.coder.com/modules/coder/goose)                          | -           | Planned       | [registry#744](https://github.com/coder/registry/issues/744) | `~/.local/share/goose/sessions/`, `~/.config/goose/` | 50 MB                     |
+| Amazon Q        | [amazon-q](https://registry.coder.com/modules/coder/amazon-q)                    | -           | Planned       | [registry#746](https://github.com/coder/registry/issues/746) | `~/.local/share/amazon-q/`, `~/.aws/amazonq/`        | 50 MB                     |
+| Gemini          | [gemini](https://registry.coder.com/modules/coder-labs/gemini)                   | -           | Planned       | [registry#745](https://github.com/coder/registry/issues/745) | `~/.gemini/`                                         | 200 MB (can reach 400 MB) |
+| Cursor CLI      | [cursor-cli](https://registry.coder.com/modules/coder-labs/cursor-cli)           | -           | Planned       | [registry#747](https://github.com/coder/registry/issues/747) | `~/.cursor/`                                         | 50 MB                     |
+| Sourcegraph Amp | [sourcegraph-amp](https://registry.coder.com/modules/coder-labs/sourcegraph-amp) | -           | Planned       | [registry#748](https://github.com/coder/registry/issues/748) | `~/.config/amp/` (config only)                       | 10 MB                     |
+| Aider           | [aider](https://registry.coder.com/modules/coder/aider)                          | -           | Not supported | [registry#739](https://github.com/coder/registry/issues/739) | `.aider.chat.history.md` (workdir)                   | 50 MB                     |
+
+## Persistent storage
+
+Every agent's session data lives under the home directory, so persisting the
+home directory with a volume mount is the simplest way to cover all agents at
+once. This also preserves the AgentAPI state file that Coder uses to stream chat
+content between the agent and the Tasks UI.
+
+See
+[Resource persistence](../admin/templates/extending-templates/resource-persistence.md)
+for configuration patterns.
+
+## Agent-specific notes
+
+**Claude Code**: Session files are JSONL and grow unbounded. Long-running
+tasks can accumulate multiple gigabytes of data in `~/.claude/projects/`.
+Monitor disk usage and consider periodic cleanup.
+
+**Goose**: Sessions are stored in a SQLite database with WAL mode enabled. You
+must preserve the `-wal` and `-shm` sidecar files alongside the main database,
+or the session database may become corrupted.
+
+**Amazon Q**: The Amazon Q Developer CLI has been rebranded to Kiro CLI. The
+existing module pins a specific CLI version. An authentication tarball is stored
+alongside session data; if it is lost, the agent must re-authenticate.
+
+**Gemini**: Session data can reach 400 MB for long-running tasks. You can set
+the `general.sessionRetention` configuration value to control how long sessions
+are retained.
+
+**Sourcegraph Amp**: Conversation threads are stored server-side on
+Sourcegraph servers, so only local configuration in `~/.config/amp/` needs
+persistence. The workspace must have network connectivity to Sourcegraph for
+resume to work.
+
+**Auggie**: May require connectivity to the Augment cloud backend for session
+resume. Behavior in fully headless or network-restricted environments is not
+fully verified.
+
+**Aider**: The `--restore-chat-history` flag performs a lossy reconstruction
+from a Markdown log file, but the agent loses full conversation context on each
+restart and does not support MCP for status reporting. When
+`enable_state_persistence` is enabled in the module, the Coder UI preserves chat
+history across pause and resume, but Aider itself starts each session fresh with no
+memory of previous conversations.
+
+## Next steps
+
+- [Task lifecycle](./tasks-lifecycle.md) for how pause and resume work and
+  what your template needs.
+- [Set up Coder Tasks](./tasks.md) in your template.
+- [Build a custom agent](./custom-agents.md) with MCP support.
diff --git a/docs/ai-coder/cli.md b/docs/ai-coder/cli.md
index 2e56a76cf4..f352a3a108 100644
--- a/docs/ai-coder/cli.md
+++ b/docs/ai-coder/cli.md
@@ -6,7 +6,9 @@ The Tasks CLI documentation has moved to the auto-generated CLI reference pages:
 - [task create](../reference/cli/task_create.md) - Create a task
 - [task delete](../reference/cli/task_delete.md) - Delete tasks
 - [task list](../reference/cli/task_list.md) - List tasks
-- [task logs](../reference/cli/task_logs.md) - Show task logs
+- [task logs](../reference/cli/task_logs.md) - Show a task's logs
+- [task pause](../reference/cli/task_pause.md) - Pause a task
+- [task resume](../reference/cli/task_resume.md) - Resume a task
 - [task send](../reference/cli/task_send.md) - Send input to a task
 - [task status](../reference/cli/task_status.md) - Show task status
 
diff --git a/docs/ai-coder/custom-agents.md b/docs/ai-coder/custom-agents.md
index 6ab68d949a..0f95d51dc3 100644
--- a/docs/ai-coder/custom-agents.md
+++ b/docs/ai-coder/custom-agents.md
@@ -33,6 +33,27 @@ This will start the MCP server and report activity back to the Coder control pla
 > [!NOTE]
 > See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/goose/main.tf) source code for a real-world example of configuring reporting via MCP. Note that in addition to setting up reporting, you'll need to make your template [compatible with Tasks](./tasks.md#option-2-create-or-duplicate-your-own-template), which is not shown in the example.
 
+## Pause and resume
+
+Custom agents can support task pause and resume by enabling state
+persistence on the agentapi module. Set `enable_state_persistence = true`
+so that AgentAPI saves and restores conversation history across pause and
+resume cycles:
+
+```hcl
+module "agentapi" {
+  source                   = "registry.coder.com/coder/agentapi/coder"
+  version                  = ">= 2.2.0"
+  agent_id                 = coder_agent.main.id
+  enable_state_persistence = true
+  # ...
+}
+```
+
+Your template also needs persistent storage and a sufficient graceful
+shutdown timeout. See [Task lifecycle](./tasks-lifecycle.md) for the full
+requirements.
+
 ## Contributing
 
 We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.
diff --git a/docs/ai-coder/tasks-lifecycle.md b/docs/ai-coder/tasks-lifecycle.md
new file mode 100644
index 0000000000..783dc7cd28
--- /dev/null
+++ b/docs/ai-coder/tasks-lifecycle.md
@@ -0,0 +1,190 @@
+# Task lifecycle
+
+Tasks can pause when idle and resume when you interact with them again.
+Pausing frees compute resources while preserving conversation context, so
+the agent can pick up where it left off. This page covers how pause and
+resume work, what gets preserved, and what your template needs.
+
+> [!NOTE]
+> Task pause and resume is in beta. Some details may change in future releases.
+
+## How tasks pause
+
+Tasks pause in two ways:
+
+- **Auto-pause**: The workspace idle timeout expires. Tasks use the
+  template's existing `default_ttl` and `activity_bump` settings, the same
+  ones that control regular workspace auto-stop. When a task auto-pauses,
+  the build reason is recorded as "idle timeout" and a notification is sent
+  to the task owner.
+- **Manual pause**: You can pause a task through the CLI with
+  `coder task pause`, the API, or the pause button in the Tasks UI.
+
+When a task pauses, the workspace stops. Compute resources are freed and
+persistent storage remains intact. Stopping a task workspace manually (via
+the workspace UI or `coder stop`) triggers the same pause behavior,
+including log snapshot capture and state persistence. Similarly, starting
+the workspace (`coder start`) resumes the task.
+
+### Activity detection for tasks
+
+AI agent activity extends the workspace deadline just like SSH or IDE
+connections do. When an agent reports "working" status through Coder Tasks,
+the workspace deadline is bumped by the template's `activity_bump` duration.
+This prevents auto-pause while the agent is actively working.
+
+See [Workspace scheduling](../user-guides/workspace-scheduling.md) for the
+full list of activity types.
+
+## What gets preserved
+
+Three things survive a pause:
+
+1. **Log snapshot**: Up to 30 of the last messages from the conversation
+   are captured during shutdown and stored server-side. While paused,
+   `coder task logs` and the Tasks UI show this snapshot so you can see
+   what the agent was working on.
+
+1. **AgentAPI state**: When state persistence is enabled, the full
+   conversation history is saved to a file on persistent storage. After
+   resume, the Tasks UI shows the complete chat history.
+
+1. **AI agent session**: Agents that support session persistence (such as
+   Claude Code via `~/.claude/`) retain their own context on persistent
+   storage. On resume, the agent picks up where it left off with full
+   memory of the previous conversation.
+
+> [!NOTE]
+> Log snapshots and AgentAPI state persistence are best-effort. If the
+> shutdown script is interrupted or times out, the workspace still stops
+> normally, but the snapshot may not be captured and chat history may be
+> empty after resume.
+
+If `enable_state_persistence` is true but the AI agent does not support
+session resume, the UI shows previous messages but the agent starts fresh
+with no memory of the conversation. This is expected behavior. See
+[Agent compatibility](./agent-compatibility.md) for which agents support
+full session resume.
+
+## Resuming a task
+
+You can resume a paused task in several ways:
+
+- **CLI**: `coder task resume <task>`
+- **UI**: Click the **Resume** button on the task page or in the tasks list
+
+Resume starts the workspace, runs startup scripts, starts AgentAPI (which
+loads its state file if state persistence is enabled), and starts the AI
+agent (which resumes its session if supported).
+
+> [!NOTE]
+> Resume requires a full workspace build, which can take several minutes
+> depending on your template.
+
+## Requirements
+
+### Persistent storage
+
+Templates must have persistent storage (Docker volume, Kubernetes PVC, or
+similar) that survives workspace stop and start cycles. Without it, the AI
+agent's session files and the AgentAPI state file are lost on stop.
+
+See
+[Resource persistence](../admin/templates/extending-templates/resource-persistence.md)
+for configuration patterns.
+
+### Compatible module version
+
+AI agent registry modules handle shutdown scripts and state persistence
+through the agentapi base module. To enable pause and resume, use a module
+version that includes this support.
+
+For Claude Code, update the module version in your template:
+
+```hcl
+module "claude-code" {
+  source   = "registry.coder.com/coder/claude-code/coder"
+  version  = ">= 4.8.0" # Minimum version with pause/resume support
+  agent_id = coder_agent.main.id
+  # ...
+}
+```
+
+Versions 4.8.0 and above set `enable_state_persistence = true`, which
+configures the shutdown script and state file automatically.
+
+See [Agent compatibility](./agent-compatibility.md) for the minimum module
+version per agent.
+
+#### The `enable_state_persistence` variable
+
+The `enable_state_persistence` variable controls whether AgentAPI saves and
+restores conversation history across pause and resume cycles. It defaults to
+`false` in the agentapi base module. Agent modules that support session
+persistence, like `claude-code`, override this to `true` in their module
+definition.
+
+When `enable_state_persistence` is `false`, the shutdown script still runs to
+capture log snapshots, but skips saving AgentAPI state. On resume, chat
+history is not restored.
+
+If you are building a [custom agent](./custom-agents.md#pause-and-resume),
+set this variable on the agentapi module directly.
+
+### Graceful shutdown timeout
+
+> [!WARNING]
+> Without this configuration, log snapshots and state persistence may
+> silently fail. The container runtime can terminate the container before
+> the shutdown script finishes.
+
+The shutdown script runs inside the workspace container. The container
+runtime controls how long the process has to shut down before it is
+force-terminated. The defaults are often too short:
+
+- **Docker**: 10 seconds
+- **Kubernetes**: 30 seconds
+
+The grace period covers not just this shutdown script but also the workspace
+agent's own graceful shutdown and any other modules that run shutdown
+scripts. Set at least **1 minute** as a baseline. **5 minutes** is
+recommended to account for slow disks, multiple shutdown scripts, and other
+modules performing cleanup.
+
+**Docker**: Add to your `docker_container` resource:
+
+```hcl
+resource "docker_container" "workspace" {
+  # Both attributes are needed for graceful shutdown.
+  destroy_grace_seconds = 300 # 5 minutes
+  stop_timeout          = 300
+  stop_signal           = "SIGINT"
+  # ...
+}
+```
+
+**Kubernetes**: Add to your `kubernetes_pod` resource:
+
+```hcl
+resource "kubernetes_pod" "main" {
+  timeouts {
+    delete = "6m" # Must exceed the grace period below.
+  }
+  spec {
+    termination_grace_period_seconds = 300 # 5 minutes
+  }
+}
+```
+
+If the container is terminated before the shutdown script finishes, the workspace
+still stops normally but log snapshots may be missing and chat history may
+not be restored after resume.
+
+## Next steps
+
+- [Agent compatibility](./agent-compatibility.md) for session persistence
+  support and minimum module versions.
+- [Resource persistence](../admin/templates/extending-templates/resource-persistence.md)
+  for configuring persistent storage in templates.
+- [Workspace scheduling](../user-guides/workspace-scheduling.md) for how
+  auto-stop and activity detection work.
diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
index c1ac7dfec9..df4a5b5258 100644
--- a/docs/ai-coder/tasks.md
+++ b/docs/ai-coder/tasks.md
@@ -141,6 +141,17 @@ Coder can automatically generate a name your tasks if you set the `ANTHROPIC_API
 
 If you tried Tasks and decided you don't want to use it, you can hide the Tasks tab by starting `coder server` with the `CODER_HIDE_AI_TASKS=true` environment variable or the `--hide-ai-tasks` flag.
 
+## Pausing and resuming tasks
+
+Tasks automatically pause when the workspace reaches its idle timeout,
+freeing compute resources. While paused, you can view a snapshot of the
+last conversation messages. When you resume or send a new message, the
+workspace restarts and the agent picks up where it left off if the agent
+and template support session persistence.
+
+For details on how pause and resume works and what your template needs,
+see [Task lifecycle](./tasks-lifecycle.md).
+
 ## Command Line Interface
 
 See [Tasks CLI](./cli.md).
diff --git a/docs/manifest.json b/docs/manifest.json
index be0108191f..1044eb1bb4 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -981,6 +981,16 @@
 							"description": "Run custom agents with Coder Tasks",
 							"path": "./ai-coder/custom-agents.md"
 						},
+						{
+							"title": "Task Lifecycle",
+							"description": "How tasks pause and resume, and what gets preserved",
+							"path": "./ai-coder/tasks-lifecycle.md"
+						},
+						{
+							"title": "Agent Compatibility",
+							"description": "Which AI agents support session persistence across workspace restarts",
+							"path": "./ai-coder/agent-compatibility.md"
+						},
 						{
 							"title": "Tasks Migration Guide",
 							"description": "Changes to Coder Tasks made in v2.28",
diff --git a/docs/user-guides/workspace-scheduling.md b/docs/user-guides/workspace-scheduling.md
index 151829c27d..d1188bbd75 100644
--- a/docs/user-guides/workspace-scheduling.md
+++ b/docs/user-guides/workspace-scheduling.md
@@ -58,6 +58,8 @@ A workspace is considered "active" when Coder detects one or more active session
 - **JetBrains IDE sessions**: Using JetBrains Gateway or remote IDE plugins
 - **Terminal sessions**: Using the web terminal (including reconnecting to the web terminal)
 - **SSH sessions**: Connecting via `coder ssh` or SSH config integration
+- **AI agent task status**: When a coding agent reports "working" status via
+  [Coder Tasks](../ai-coder/tasks.md), the workspace deadline is extended
 
 Activity is only detected when there is at least one active session. An open session will keep your workspace marked as active and prevent automatic shutdown.
 
@@ -67,7 +69,8 @@ The following actions do **not** count as workspace activity:
 - Viewing or editing workspace settings
 - Viewing build logs or audit logs
 - Accessing ports through direct URLs without an active session
-- Background agent statistics reporting
+- Background agent statistics reporting (note: AI agent _task status_
+  reporting is different and does count as activity, see above)
 
 To avoid unexpected cloud costs, close your connections, this includes IDE windows, SSH sessions, and others, when you finish using your workspace.