Merge branch 'main' into commands-list-clean

docs/concepts/agent-workspace.md

@@ -16,6 +16,8 @@ sessions.
 resolve relative paths against the workspace, but absolute paths can still reach
 elsewhere on the host unless sandboxing is enabled. If you need isolation, use
 [`agent.sandbox`](/gateway/sandboxing) (and/or per‑agent sandbox config).
+When sandboxing is enabled and `workspaceAccess` is not `"rw"`, tools operate
+inside a sandbox workspace under `~/.clawdbot/sandboxes`, not your host workspace.
 
 ## Default location
 

docs/concepts/usage-tracking.md

@@ -11,7 +11,8 @@ read_when:
 - No estimated costs; only the provider-reported windows.
 
 ## Where it shows up
-- `/status` in chats: adds a short “Usage” line (only if available).
+- `/status` in chats: compact one‑liner with session tokens + estimated cost (API key only) and provider quota windows when available.
+- `/cost on|off` in chats: toggles per‑response usage lines (OAuth shows tokens only).
 - CLI: `clawdbot status --usage` prints a full per-provider breakdown.
 - CLI: `clawdbot providers list` prints the same usage snapshot alongside provider config (use `--no-usage` to skip).
 - macOS menu bar: “Usage” section under Context (only if available).

docs/docs.json

@@ -556,6 +556,7 @@
           "concepts/agent",
           "concepts/agent-loop",
           "concepts/system-prompt",
+          "token-use",
           "concepts/oauth",
           "concepts/agent-workspace",
           "concepts/multi-agent",

docs/gateway/configuration.md

@@ -1473,6 +1473,7 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
 
 Fields:
 - `mainKey`: direct-chat bucket key (default: `"main"`). Useful when you want to “rename” the primary DM thread without changing `agentId`.
+  - Sandbox note: `agent.sandbox.mode: "non-main"` uses this key to detect the main session. Any session key that does not match `mainKey` (groups/channels) is sandboxed.
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
 - `sendPolicy.rules[]`: match by `provider`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.

docs/gateway/sandboxing.md

@@ -31,6 +31,8 @@ Not sandboxed:
 - `"off"`: no sandboxing.
 - `"non-main"`: sandbox only **non-main** sessions (default if you want normal chats on host).
 - `"all"`: every session runs in a sandbox.
+Note: `"non-main"` is based on `session.mainKey` (default `"main"`), not agent id.
+Group/channel sessions use their own keys, so they count as non-main and will be sandboxed.
 
 ## Scope
 `agent.sandbox.scope` controls **how many containers** are created:

docs/gateway/troubleshooting.md

@@ -122,6 +122,19 @@ or state drift because only one workspace is active.
 **Fix:** keep a single active workspace and archive/remove the rest. See
 [Agent workspace](/concepts/agent-workspace#legacy-workspace-folders).
 
+### Main chat running in a sandbox workspace
+
+Symptoms: `pwd` or file tools show `~/.clawdbot/sandboxes/...` even though you
+expected the host workspace.
+
+**Why:** `agent.sandbox.mode: "non-main"` keys off `session.mainKey` (default `"main"`).
+Group/channel sessions use their own keys, so they are treated as non-main and
+get sandbox workspaces.
+
+**Fix options:**
+- If you want host workspaces for an agent: set `routing.agents.<id>.sandbox.mode: "off"`.
+- If you want host workspace access inside sandbox: set `workspaceAccess: "rw"` for that agent.
+
 ### "Agent was aborted"
 
 The agent was interrupted mid-response.

docs/multi-agent-sandbox-tools.md

@@ -252,6 +252,15 @@ The global `agent.workspace` and `agent.sandbox` are still supported for backwar
 
 ---
 
+## Common Pitfall: "non-main"
+
+`sandbox.mode: "non-main"` is based on `session.mainKey` (default `"main"`),
+not the agent id. Group/channel sessions always get their own keys, so they
+are treated as non-main and will be sandboxed. If you want an agent to never
+sandbox, set `routing.agents.<id>.sandbox.mode: "off"`.
+
+---
+
 ## Testing
 
 After configuring multi-agent sandbox and tools:

docs/start/getting-started.md

@@ -19,6 +19,23 @@ Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It set
 
 If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
 
+Sandboxing note: `agent.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`),
+so group/channel sessions are sandboxed. If you want the main agent to always
+run on host, set an explicit per-agent override:
+
+```json
+{
+  "routing": {
+    "agents": {
+      "main": {
+        "workspace": "~/clawd",
+        "sandbox": { "mode": "off" }
+      }
+    }
+  }
+}
+```
+
 ## 0) Prereqs
 
 - Node `>=22`

docs/token-use.md

@@ -0,0 +1,72 @@
+---
+summary: "How Clawdbot builds prompt context and reports token usage + costs"
+read_when:
+  - Explaining token usage, costs, or context windows
+  - Debugging context growth or compaction behavior
+---
+# Token use & costs
+
+Clawdbot tracks **tokens**, not characters. Tokens are model-specific, but most
+OpenAI-style models average ~4 characters per token for English text.
+
+## How the system prompt is built
+
+Clawdbot assembles its own system prompt on every run. It includes:
+
+- Tool list + short descriptions
+- Skills list (only metadata; instructions are loaded on demand with `read`)
+- Self-update instructions
+- Workspace + bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` when new)
+- Time (UTC + user timezone)
+- Reply tags + heartbeat behavior
+- Runtime metadata (host/OS/model/thinking)
+
+See the full breakdown in [System Prompt](/concepts/system-prompt).
+
+## What counts in the context window
+
+Everything the model receives counts toward the context limit:
+
+- System prompt (all sections listed above)
+- Conversation history (user + assistant messages)
+- Tool calls and tool results
+- Attachments/transcripts (images, audio, files)
+- Compaction summaries and pruning artifacts
+- Provider wrappers or safety headers (not visible, but still counted)
+
+## How to see current token usage
+
+Use these in chat:
+
+- `/status` → **compact one‑liner** with the session model, context usage,
+  last response input/output tokens, and **estimated cost** (API key only).
+- `/cost on|off` → appends a **per-response usage line** to every reply.
+  - Persists per session (stored as `responseUsage`).
+  - OAuth auth **hides cost** (tokens only).
+
+Other surfaces:
+
+- **TUI/Web TUI:** `/status` + `/cost` are supported.
+- **CLI:** `clawdbot status --usage` and `clawdbot providers list` show
+  provider quota windows (not per-response costs).
+
+## Cost estimation (when shown)
+
+Costs are estimated from your model pricing config:
+
+```
+models.providers.<provider>.models[].cost
+```
+
+These are **USD per 1M tokens** for `input`, `output`, `cacheRead`, and
+`cacheWrite`. If pricing is missing, Clawdbot shows tokens only. OAuth tokens
+never show dollar cost.
+
+## Tips for reducing token pressure
+
+- Use `/compact` to summarize long sessions.
+- Trim large tool outputs in your workflows.
+- Keep skill descriptions short (skill list is injected into the prompt).
+- Prefer smaller models for verbose, exploratory work.
+
+See [Skills](/tools/skills) for the exact skill list overhead formula.

docs/tools/skills.md

@@ -163,6 +163,23 @@ This is **scoped to the agent run**, not a global shell environment.
 
 Clawdbot snapshots the eligible skills **when a session starts** and reuses that list for subsequent turns in the same session. Changes to skills or config take effect on the next new session.
 
+## Token impact (skills list)
+
+When skills are eligible, Clawdbot injects a compact XML list of available skills into the system prompt (via `formatSkillsForPrompt` in `pi-coding-agent`). The cost is deterministic:
+
+- **Base overhead (only when ≥1 skill):** 195 characters.
+- **Per skill:** 97 characters + the length of the XML-escaped `<name>`, `<description>`, and `<location>` values.
+
+Formula (characters):
+
+```
+total = 195 + Σ (97 + len(name_escaped) + len(description_escaped) + len(location_escaped))
+```
+
+Notes:
+- XML escaping expands `& < > " '` into entities (`&amp;`, `&lt;`, etc.), increasing length.
+- Token counts vary by model tokenizer. A rough OpenAI-style estimate is ~4 chars/token, so **97 chars ≈ 24 tokens** per skill plus your actual field lengths.
+
 ## Managed skills lifecycle
 
 Clawdbot ships a baseline set of skills as **bundled skills** as part of the

docs/tools/slash-commands.md

@@ -36,6 +36,7 @@ Text + native (when enabled):
 - `/help`
 - `/commands`
 - `/status`
+- `/cost on|off` (toggle per-response usage line)
 - `/stop`
 - `/restart`
 - `/activation mention|always` (groups only)
@@ -53,6 +54,7 @@ Text-only:
 
 Notes:
 - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
+- `/cost` appends per-response token usage; it only shows dollar cost when the model uses an API key (OAuth hides cost).
 - `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
 - `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
 

docs/tui.md

@@ -77,6 +77,7 @@ Session controls:
 - `/think <off|minimal|low|medium|high>`
 - `/verbose <on|off>`
 - `/reasoning <on|off|stream>`
+- `/cost <on|off>`
 - `/elevated <on|off>` (alias: `/elev`)
 - `/activation <mention|always>`
 - `/deliver <on|off>`

docs/web/tui.md

@@ -53,6 +53,7 @@ Use SSH tunneling or Tailscale to reach the Gateway WS.
 - `/think <off|minimal|low|medium|high>`
 - `/verbose <on|off>`
 - `/reasoning <on|off|stream>` (stream = Telegram draft only)
+- `/cost <on|off>`
 - `/elevated <on|off>`
 - `/elev <on|off>`
 - `/activation <mention|always>`