diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md
index ba1a50c404a2..b13b02673bdf 100644
--- a/docs/automation/cron-jobs.md
+++ b/docs/automation/cron-jobs.md
@@ -116,6 +116,8 @@ The script must return `{ fire, message?, state? }`. The previous JSON state is
`fire: false` persists evaluation state and counters, then reschedules without creating run history. If a fired payload run fails, the returned `state` is **not** persisted — the next evaluation sees the previous state and can fire again, so write scripts as read-only checks and keep actions in the payload. Trigger schedules have a configurable minimum interval (30 seconds by default). Each evaluation has a 30-second wall-clock budget and up to 5 tool calls.
+Author watchers around **actionable state**, not only success: a watcher that goes quiet when its check fails or times out looks healthy while broken. Compare the observation with `trigger.state` and return fresh state to deduplicate; do not rely on model or process memory. When firing, make `message` self-contained because it becomes the fired run's complete event context.
+
Enabling `cron.triggers.enabled` lets agent-authored scripts run headlessly with the owning agent's **full tool policy, including `exec`**. Treat this as unattended code execution with that agent's permissions; leave it disabled unless every agent allowed to create cron jobs is trusted accordingly.
@@ -227,6 +229,12 @@ Delivered text is derived from process output: non-empty stdout wins; if stdout
A new transcript/session id per run. OpenClaw carries safe preferences (thinking/fast/verbose settings, labels, explicit user-selected model/auth overrides), but does not inherit ambient conversation context from an older cron row: channel/group routing, send or queue policy, elevation, origin, or ACP runtime binding. Use `current` or `session:` when a recurring job should deliberately build on the same conversation context.
+
+ Isolated cron and hook agent turns are explicitly unattended: no one is present to clarify or approve. The final reply must be the deliverable rather than a plan, acknowledgement, or request for input. The agent returns `HEARTBEAT_OK` when nothing needs doing and states failures plainly; cron owns retry and failure-alert policy.
+
+ For trusted scheduled jobs, the job's own instructions win when they intentionally ask for a question or plan, and the agent may remove a job that is no longer needed. External hook turns receive only the common unattended contract; they do not receive that override or self-removal guidance across the external-content boundary.
+
+
When isolated cron runs orchestrate subagents, delivery prefers the final descendant output over stale parent interim text. If descendants are still running, OpenClaw suppresses that partial parent update instead of announcing it.
diff --git a/docs/concepts/session-tool.md b/docs/concepts/session-tool.md
index 174ec618de97..d0349c31305d 100644
--- a/docs/concepts/session-tool.md
+++ b/docs/concepts/session-tool.md
@@ -13,7 +13,9 @@ OpenClaw gives agents tools to work across sessions, inspect status, and orchest
| Tool | What it does |
| -------------------- | --------------------------------------------------------------------------- |
+| `sessions` | Patch visible session settings and manage the global session-group catalog |
| `sessions_list` | List sessions with optional filters (kind, label, agent, archive, preview) |
+| `sessions_search` | Search visible session transcripts and return matching excerpts |
| `sessions_history` | Read the transcript of a specific session |
| `sessions_send` | Run another session on the same Gateway and optionally wait |
| `conversations_list` | List stable external conversation addresses |
@@ -21,19 +23,10 @@ OpenClaw gives agents tools to work across sessions, inspect status, and orchest
| `conversations_turn` | Send to one exact external conversation and wait for its correlated reply |
| `sessions_spawn` | Spawn an isolated sub-agent session for background work |
| `sessions_yield` | End the current turn and wait for follow-up sub-agent results |
-| `subagents` | List spawned sub-agent status for this session |
+| `subagents` | List or cancel background work in this session tree |
| `session_status` | Show a `/status`-style card and optionally set a per-session model override |
-These tools are still subject to the active tool profile and allow/deny policy. `tools.profile: "coding"` includes the full session orchestration set, including `sessions_spawn`, `sessions_yield`, and `subagents`. `tools.profile: "messaging"` includes cross-session and external-conversation tools (`sessions_list`, `sessions_history`, `sessions_send`, `conversations_list`, `conversations_send`, `conversations_turn`, `session_status`) but does not include sub-agent spawning. To keep a messaging profile and still allow native delegation, add:
-
-```json5
-{
- tools: {
- profile: "messaging",
- alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
- },
-}
-```
+These tools are still subject to the active tool profile and allow/deny policy. `tools.profile: "coding"` includes the full session orchestration set. `tools.profile: "messaging"` includes session self-service, discovery, recall, cross-session messaging, external-conversation tools, and the complete spawn lifecycle (`sessions_spawn`, `sessions_yield`, and `subagents`). The UI-only task-suggestion tools `spawn_task` and `dismiss_task` remain coding-profile tools.
Group, provider, sandbox, and per-agent policies can still remove those tools after the profile stage. Use `/tools` from the affected session to inspect the effective tool list.
@@ -61,6 +54,17 @@ Use the returned **session key** (like `"main"`) with `sessions_history`, `sessi
If you need the exact raw transcript, inspect the scoped SQLite transcript rows instead of treating `sessions_history` as an unfiltered dump.
+Use [`sessions_search`](/concepts/session-search) for exact full-text recall across visible user and assistant transcript text. Its results include a `sessionKey` for a follow-up `sessions_history` call; visibility filtering, snippet redaction, and output bounds match the history boundary.
+
+## Managing session settings and groups
+
+The owner-gated `sessions` tool exposes two bounded self-service surfaces:
+
+- `action: "patch"` changes the current session by default, or another visible session selected by `sessionKey`. It can set the label, sidebar icon, pin/archive state, model, and thinking level. It does not expose reset, delete, or compact actions.
+- `group_list`, `group_set`, `group_rename`, and `group_delete` manage the global ordered session-group catalog. `group_set` replaces the ordered name list rather than patching one entry.
+
+An agent-selected model patch stays reversible until that selection completes a successful run. If the selected model is definitively unusable because of authentication, billing, or model-not-found failure, OpenClaw restores the previous model and writes a visible system note. Transient rate-limit, overload, timeout, network, and server failures do not undo the selection.
+
## Sessions versus conversations
A **session** is local model context. A **conversation** is an exact external address such as one peer, channel, or thread. The two are linked, but they are not interchangeable: direct messages can share one `main` session while retaining separate conversation addresses.
@@ -106,7 +110,7 @@ See [Session state awareness](/concepts/session-state) for the full model: event
`sessions_yield` intentionally ends the current turn so the next message can be the follow-up event you are waiting for. Use it after spawning sub-agents when you want completion results to arrive as the next message instead of building poll loops.
-`subagents` is the visibility helper for already spawned OpenClaw sub-agents. It supports `action: "list"` to inspect active/recent runs.
+`subagents` is the session-tree view over native sub-agent runs and the shared background-task ledger. `action: "list"` reports active/recent sub-agents plus scoped ACP, CLI/media, and cron tasks. `action: "cancel"` accepts a returned `taskId` and can stop only work inside the caller's controlled session tree; leaf sub-agents cannot cancel another session's task.
## Spawning sub-agents
@@ -119,6 +123,7 @@ Key options:
- `thread: true` to bind the spawn to a chat thread (Discord, Slack, etc.).
- `sandbox: "require"` to enforce sandboxing on the child.
- `context: "fork"` for native sub-agents when the child needs the current requester transcript; omit it or use `context: "isolated"` for a clean child. `context: "fork"` is only valid with `runtime: "subagent"`. Thread-bound native sub-agents default to `context: "fork"` unless `threadBindings.defaultSpawnContext` says otherwise.
+- `visible: true` to create a persistent dashboard session instead of a hidden sub-agent session. Visible spawns support an explicit model, working directory, same-agent transcript fork, and an optional [managed worktree](/concepts/managed-worktrees); see [Sub-agents](/tools/subagents#tool-parameters) for the exact compatibility limits.
Default leaf sub-agents do not get session tools. When `maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive `sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they can manage their own children. Leaf runs still do not get recursive orchestration tools.
diff --git a/docs/docs_map.md b/docs/docs_map.md
index 1eb477212f06..42d08fd02590 100644
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -2949,6 +2949,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
- Headings:
- H2: Available tools
- H2: Listing and reading sessions
+ - H2: Managing session settings and groups
- H2: Sessions versus conversations
- H2: Sending cross-session messages
- H2: Status and orchestration helpers
diff --git a/docs/gateway/config-tools.md b/docs/gateway/config-tools.md
index d8867dc646fa..93f18ad8d32b 100644
--- a/docs/gateway/config-tools.md
+++ b/docs/gateway/config-tools.md
@@ -20,32 +20,32 @@ sidebarTitle: "Tools and custom providers"
Local onboarding defaults new local configs to `tools.profile: "coding"` when unset (existing explicit profiles are preserved).
-| Profile | Includes |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `minimal` | `session_status` only |
-| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop`, `image`, `image_generate`, `music_generate`, `video_generate` |
-| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`, `ask_user` |
-| `full` | No restriction (same as unset) |
+| Profile | Includes |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `minimal` | `session_status` only |
+| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop`, `image`, `image_generate`, `music_generate`, `video_generate` |
+| `messaging` | `group:messaging`, `sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `ask_user` |
+| `full` | No restriction (same as unset) |
`coding` and `messaging` also implicitly allow `bundle-mcp` (configured MCP servers).
### Tool groups
-| Group | Tools |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`) |
-| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
-| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task` |
-| `group:memory` | `memory_search`, `memory_get` |
-| `group:web` | `web_search`, `x_search`, `web_fetch` |
-| `group:ui` | `browser`, `canvas` |
-| `group:automation` | `heartbeat_respond`, `cron`, `gateway` |
-| `group:messaging` | `message` |
-| `group:nodes` | `nodes`, `computer` |
-| `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop` |
-| `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` |
-| `group:openclaw` | All built-in tools above except `read`/`write`/`edit`/`apply_patch`/`exec`/`process`/`canvas` (excludes plugin tools) |
-| `group:plugins` | Tools owned by loaded plugins, including configured MCP servers exposed through `bundle-mcp` |
+| Group | Tools |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `group:runtime` | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`) |
+| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
+| `group:sessions` | `sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task` |
+| `group:memory` | `memory_search`, `memory_get` |
+| `group:web` | `web_search`, `x_search`, `web_fetch` |
+| `group:ui` | `browser`, `screen`, `terminal`, `canvas`, `show_widget` |
+| `group:automation` | `heartbeat_respond`, `cron`, `gateway` |
+| `group:messaging` | `message` |
+| `group:nodes` | `nodes`, `computer` |
+| `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop` |
+| `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` |
+| `group:openclaw` | All built-in tools above except `read`/`write`/`edit`/`apply_patch`/`exec`/`process`/`canvas` (excludes plugin tools) |
+| `group:plugins` | Tools owned by loaded plugins, including configured MCP servers exposed through `bundle-mcp` |
`spawn_task` lets a coding agent propose confirmed follow-up work without starting it. The Control UI shows the title and summary as an actionable chip; a Gateway-backed TUI shows an equivalent interactive prompt. Accepting either creates a fresh managed-worktree session and sends the full prompt there while the current turn continues. `dismiss_task` withdraws a still-pending suggestion by the ephemeral `task_id` returned from `spawn_task`.
diff --git a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
index b82ea07d9d78..9af0e7fcfcda 100644
--- a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
+++ b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
@@ -91,21 +91,21 @@ Tool policies (global, agent, sandbox) support `group:*` entries that expand to
Available groups:
-| Group | Tools |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`) |
-| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
-| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` |
-| `group:memory` | `memory_search`, `memory_get` |
-| `group:web` | `web_search`, `x_search`, `web_fetch` |
-| `group:ui` | `browser`, `canvas` |
-| `group:automation` | `heartbeat_respond`, `cron`, `gateway` |
-| `group:messaging` | `message` |
-| `group:nodes` | `nodes`, `computer` |
-| `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop` |
-| `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` |
-| `group:openclaw` | most built-in OpenClaw tools (excludes the `read`/`write`/`edit`/`apply_patch`/`exec`/`process` fs and runtime primitives, `canvas`, and provider plugins) |
-| `group:plugins` | all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp` |
+| Group | Tools |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `group:runtime` | `exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`) |
+| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
+| `group:sessions` | `sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task` |
+| `group:memory` | `memory_search`, `memory_get` |
+| `group:web` | `web_search`, `x_search`, `web_fetch` |
+| `group:ui` | `browser`, `screen`, `terminal`, `canvas`, `show_widget` |
+| `group:automation` | `heartbeat_respond`, `cron`, `gateway` |
+| `group:messaging` | `message` |
+| `group:nodes` | `nodes`, `computer` |
+| `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop` |
+| `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` |
+| `group:openclaw` | most built-in OpenClaw tools (excludes the `read`/`write`/`edit`/`apply_patch`/`exec`/`process` fs and runtime primitives, `canvas`, and provider plugins) |
+| `group:plugins` | all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp` |
For read-only agents, deny `group:runtime` as well as mutating filesystem tools unless sandbox filesystem policy or a separate host boundary enforces the read-only constraint.
diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md
index 31b623969553..a5c77fe37850 100644
--- a/docs/tools/subagents.md
+++ b/docs/tools/subagents.md
@@ -134,10 +134,11 @@ then runs an announce step and posts the announce reply to the requester
chat channel.
Availability depends on the caller's effective tool policy. The built-in
-`coding` profile includes `sessions_spawn`; `messaging` and `minimal` do
-not. `full` allows every tool. Add `tools.alsoAllow: ["sessions_spawn",
-"sessions_yield", "subagents"]`, or use `tools.profile: "coding"`, for
-agents on a narrower profile that should still delegate work.
+`coding` and `messaging` profiles include `sessions_spawn`,
+`sessions_yield`, and `subagents`; `minimal` does not. `full` allows every
+tool. Add those tools with `tools.alsoAllow`, or use one of the profiles
+above, for an agent on a custom narrower profile that should still
+delegate work.
Channel/group, provider, sandbox, and per-agent allow/deny policies can
still remove the tool after the profile stage. Use `/tools` from the same
session to confirm the effective tool list.
@@ -212,7 +213,7 @@ Per-agent override: `agents.list[].subagents.delegationMode`.
Override the sub-agent model. Invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result.
- Override thinking level for the sub-agent run.
+ Override thinking level for the sub-agent run. Not available with `visible: true`.
When `true`, requests channel thread binding for this sub-agent session.
@@ -228,7 +229,19 @@ Per-agent override: `agents.list[].subagents.delegationMode`.
`require` rejects the spawn unless the target child runtime is sandboxed.
- `fork` branches the requester's current transcript into the child session. Native sub-agents only. Thread-bound spawns default to `fork`; non-thread spawns default to `isolated`.
+ `fork` branches the requester's current transcript into the child session. Native sub-agents only. Thread-bound spawns default to `fork`; non-thread spawns default to `isolated`. A visible fork must target the same agent as the requester.
+
+
+ Create a persistent dashboard session that the user can open in the Control UI. Visible spawns support only `runtime: "subagent"` and always keep the created session.
+
+
+ Provision a managed git worktree for the new dashboard session. Requires `visible: true`.
+
+
+ Optional managed-worktree name. Requires `visible: true` and `worktree: true`.
+
+
+ Optional git base ref for the managed worktree. Requires `visible: true` and `worktree: true`.
@@ -238,6 +251,8 @@ their latest assistant turn back to the requester; external delivery stays with
the parent/requester agent.
+With `visible: true`, `model`, `cwd`, and a same-agent `context: "fork"` are supported. A sandboxed target restricts `cwd` to that agent's workspace. Thread binding, `mode`, thinking overrides, light bootstrap context, and attachment staging are unavailable on this path because visible sessions are persistent dashboard sessions created through `sessions.create`. Visible spawning is also rejected when inherited tool restrictions cannot be carried into the dashboard session. See [Managed worktrees](/concepts/managed-worktrees) for checkout naming, setup, cleanup, and restore behavior.
+
### Task names and targeting
`taskName` is a model-facing handle for orchestration, not a session key.
@@ -280,12 +295,18 @@ from user/model-provided spawn arguments.
## Tool: `subagents`
-Lists spawned sub-agent runs owned by the requester session. It is scoped
-to the current requester; a child can only see its own controlled children.
+Lists spawned sub-agent runs and background-task records owned by the
+requester session tree. The task rows cover native sub-agents, ACP runs,
+Gateway CLI/media work, and cron executions. It is scoped to the current
+requester; a child can only see its own controlled children.
Use `subagents` for on-demand status and debugging. Use `sessions_yield` to
wait for completion events.
+Use `action: "cancel"` with a `taskId` returned by `action: "list"` to stop
+a task. Cancellation is confined to the controlled session tree; a leaf
+sub-agent cannot cancel work owned by another session.
+
## Thread-bound sessions
When thread bindings are enabled for a channel, a sub-agent can stay bound