loudmouth-ai 0.1.0

package/docs/tools/skills.md

@@ -0,0 +1,267 @@
+---
+summary: "Skills: managed vs workspace, gating rules, and config/env wiring"
+read_when:
+  - Adding or modifying skills
+  - Changing skill gating or load rules
+---
+# Skills (Clawdbot)
+
+Clawdbot uses **[AgentSkills](https://agentskills.io)-compatible** skill folders to teach the agent how to use tools. Each skill is a directory containing a `SKILL.md` with YAML frontmatter and instructions. Clawdbot loads **bundled skills** plus optional local overrides, and filters them at load time based on environment, config, and binary presence.
+
+## Locations and precedence
+
+Skills are loaded from **three** places:
+
+1) **Bundled skills**: shipped with the install (npm package or Clawdbot.app)
+2) **Managed/local skills**: `~/.clawdbot/skills`
+3) **Workspace skills**: `<workspace>/skills`
+
+If a skill name conflicts, precedence is:
+
+`<workspace>/skills` (highest) → `~/.clawdbot/skills` → bundled skills (lowest)
+
+Additionally, you can configure extra skill folders (lowest precedence) via
+`skills.load.extraDirs` in `~/.clawdbot/clawdbot.json`.
+
+## Per-agent vs shared skills
+
+In **multi-agent** setups, each agent has its own workspace. That means:
+
+- **Per-agent skills** live in `<workspace>/skills` for that agent only.
+- **Shared skills** live in `~/.clawdbot/skills` (managed/local) and are visible
+  to **all agents** on the same machine.
+- **Shared folders** can also be added via `skills.load.extraDirs` (lowest
+  precedence) if you want a common skills pack used by multiple agents.
+
+If the same skill name exists in more than one place, the usual precedence
+applies: workspace wins, then managed/local, then bundled.
+
+## Plugins + skills
+
+Plugins can ship their own skills by listing `skills` directories in
+`clawdbot.plugin.json` (paths relative to the plugin root). Plugin skills load
+when the plugin is enabled and participate in the normal skill precedence rules.
+You can gate them via `metadata.clawdbot.requires.config` on the plugin’s config
+entry. See [Plugins](/plugin) for discovery/config and [Tools](/tools) for the
+tool surface those skills teach.
+
+## ClawdHub (install + sync)
+
+ClawdHub is the public skills registry for Clawdbot. Browse at
+https://clawdhub.com. Use it to discover, install, update, and back up skills.
+Full guide: [ClawdHub](/tools/clawdhub).
+
+Common flows:
+
+- Install a skill into your workspace:
+  - `clawdhub install <skill-slug>`
+- Update all installed skills:
+  - `clawdhub update --all`
+- Sync (scan + publish updates):
+  - `clawdhub sync --all`
+
+By default, `clawdhub` installs into `./skills` under your current working
+directory (or falls back to the configured Clawdbot workspace). Clawdbot picks
+that up as `<workspace>/skills` on the next session.
+
+## Security notes
+
+- Treat third-party skills as **trusted code**. Read them before enabling.
+- Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing).
+- `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process
+  for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
+- For a broader threat model and checklists, see [Security](/gateway/security).
+
+## Format (AgentSkills + Pi-compatible)
+
+`SKILL.md` must include at least:
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+---
+```
+
+Notes:
+- We follow the AgentSkills spec for layout/intent.
+- The parser used by the embedded agent supports **single-line** frontmatter keys only.
+- `metadata` should be a **single-line JSON object**.
+- Use `{baseDir}` in instructions to reference the skill folder path.
+- Optional frontmatter keys:
+  - `homepage` — URL surfaced as “Website” in the macOS Skills UI (also supported via `metadata.clawdbot.homepage`).
+  - `user-invocable` — `true|false` (default: `true`). When `true`, the skill is exposed as a user slash command.
+  - `disable-model-invocation` — `true|false` (default: `false`). When `true`, the skill is excluded from the model prompt (still available via user invocation).
+  - `command-dispatch` — `tool` (optional). When set to `tool`, the slash command bypasses the model and dispatches directly to a tool.
+  - `command-tool` — tool name to invoke when `command-dispatch: tool` is set.
+  - `command-arg-mode` — `raw` (default). For tool dispatch, forwards the raw args string to the tool (no core parsing).
+
+    The tool is invoked with params:
+    `{ command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }`.
+
+## Gating (load-time filters)
+
+Clawdbot **filters skills at load time** using `metadata` (single-line JSON):
+
+```markdown
+---
+name: nano-banana-pro
+description: Generate or edit images via Gemini 3 Pro Image
+metadata: {"clawdbot":{"requires":{"bins":["uv"],"env":["GEMINI_API_KEY"],"config":["browser.enabled"]},"primaryEnv":"GEMINI_API_KEY"}}
+---
+```
+
+Fields under `metadata.clawdbot`:
+- `always: true` — always include the skill (skip other gates).
+- `emoji` — optional emoji used by the macOS Skills UI.
+- `homepage` — optional URL shown as “Website” in the macOS Skills UI.
+- `os` — optional list of platforms (`darwin`, `linux`, `win32`). If set, the skill is only eligible on those OSes.
+- `requires.bins` — list; each must exist on `PATH`.
+- `requires.anyBins` — list; at least one must exist on `PATH`.
+- `requires.env` — list; env var must exist **or** be provided in config.
+- `requires.config` — list of `clawdbot.json` paths that must be truthy.
+- `primaryEnv` — env var name associated with `skills.entries.<name>.apiKey`.
+- `install` — optional array of installer specs used by the macOS Skills UI (brew/node/go/uv/download).
+
+Note on sandboxing:
+- `requires.bins` is checked on the **host** at skill load time.
+- If an agent is sandboxed, the binary must also exist **inside the container**.
+  Install it via `agents.defaults.sandbox.docker.setupCommand` (or a custom image).
+  `setupCommand` runs once after the container is created.
+  Package installs also require network egress, a writable root FS, and a root user in the sandbox.
+  Example: the `summarize` skill (`skills/summarize/SKILL.md`) needs the `summarize` CLI
+  in the sandbox container to run there.
+
+Installer example:
+
+```markdown
+---
+name: gemini
+description: Use Gemini CLI for coding assistance and Google search lookups.
+metadata: {"clawdbot":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
+---
+```
+
+Notes:
+- If multiple installers are listed, the gateway picks a **single** preferred option (brew when available, otherwise node).
+- If all installers are `download`, Clawdbot lists each entry so you can see the available artifacts.
+- Installer specs can include `os: ["darwin"|"linux"|"win32"]` to filter options by platform.
+- Node installs honor `skills.install.nodeManager` in `clawdbot.json` (default: npm; options: npm/pnpm/yarn/bun).
+  This only affects **skill installs**; the Gateway runtime should still be Node
+  (Bun is not recommended for WhatsApp/Telegram).
+- Go installs: if `go` is missing and `brew` is available, the gateway installs Go via Homebrew first and sets `GOBIN` to Homebrew’s `bin` when possible.
+ - Download installs: `url` (required), `archive` (`tar.gz` | `tar.bz2` | `zip`), `extract` (default: auto when archive detected), `stripComponents`, `targetDir` (default: `~/.clawdbot/tools/<skillKey>`).
+
+If no `metadata.clawdbot` is present, the skill is always eligible (unless
+disabled in config or blocked by `skills.allowBundled` for bundled skills).
+
+## Config overrides (`~/.clawdbot/clawdbot.json`)
+
+Bundled/managed skills can be toggled and supplied with env values:
+
+```json5
+{
+  skills: {
+    entries: {
+      "nano-banana-pro": {
+        enabled: true,
+        apiKey: "GEMINI_KEY_HERE",
+        env: {
+          GEMINI_API_KEY: "GEMINI_KEY_HERE"
+        },
+        config: {
+          endpoint: "https://example.invalid",
+          model: "nano-pro"
+        }
+      },
+      peekaboo: { enabled: true },
+      sag: { enabled: false }
+    }
+  }
+}
+```
+
+Note: if the skill name contains hyphens, quote the key (JSON5 allows quoted keys).
+
+Config keys match the **skill name** by default. If a skill defines
+`metadata.clawdbot.skillKey`, use that key under `skills.entries`.
+
+Rules:
+- `enabled: false` disables the skill even if it’s bundled/installed.
+- `env`: injected **only if** the variable isn’t already set in the process.
+- `apiKey`: convenience for skills that declare `metadata.clawdbot.primaryEnv`.
+- `config`: optional bag for custom per-skill fields; custom keys must live here.
+- `allowBundled`: optional allowlist for **bundled** skills only. If set, only
+  bundled skills in the list are eligible (managed/workspace skills unaffected).
+
+## Environment injection (per agent run)
+
+When an agent run starts, Clawdbot:
+1) Reads skill metadata.
+2) Applies any `skills.entries.<key>.env` or `skills.entries.<key>.apiKey` to
+   `process.env`.
+3) Builds the system prompt with **eligible** skills.
+4) Restores the original environment after the run ends.
+
+This is **scoped to the agent run**, not a global shell environment.
+
+## Session snapshot (performance)
+
+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.
+
+Skills can also refresh mid-session when the skills watcher is enabled or when a new eligible remote node appears (see below). Think of this as a **hot reload**: the refreshed list is picked up on the next agent turn.
+
+## Remote macOS nodes (Linux gateway)
+
+If the Gateway is running on Linux but a **macOS node** is connected **with `system.run` allowed** (Exec approvals security not set to `deny`), Clawdbot can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should execute those skills via the `nodes` tool (typically `nodes.run`).
+
+This relies on the node reporting its command support and on a bin probe via `system.run`. If the macOS node goes offline later, the skills remain visible; invocations may fail until the node reconnects.
+
+## Skills watcher (auto-refresh)
+
+By default, Clawdbot watches skill folders and bumps the skills snapshot when `SKILL.md` files change. Configure this under `skills.load`:
+
+```json5
+{
+  skills: {
+    load: {
+      watch: true,
+      watchDebounceMs: 250
+    }
+  }
+}
+```
+
+## 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
+install (npm package or Clawdbot.app). `~/.clawdbot/skills` exists for local
+overrides (for example, pinning/patching a skill without changing the bundled
+copy). Workspace skills are user-owned and override both on name conflicts.
+
+## Config reference
+
+See [Skills config](/tools/skills-config) for the full configuration schema.
+
+## Looking for more skills?
+
+Browse https://clawdhub.com.
+
+---

package/docs/tools/slash-commands.md

@@ -0,0 +1,188 @@
+---
+summary: "Slash commands: text vs native, config, and supported commands"
+read_when:
+  - Using or configuring chat commands
+  - Debugging command routing or permissions
+---
+# Slash commands
+
+Commands are handled by the Gateway. Most commands must be sent as a **standalone** message that starts with `/`.
+The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
+
+There are two related systems:
+
+- **Commands**: standalone `/...` messages.
+- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
+  - Directives are stripped from the message before the model sees it.
+  - In normal chat messages (not directive-only), they are treated as “inline hints” and do **not** persist session settings.
+  - In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
+
+There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
+
+## Config
+
+```json5
+{
+  commands: {
+    native: "auto",
+    nativeSkills: "auto",
+    text: true,
+    bash: false,
+    bashForegroundMs: 2000,
+    config: false,
+    debug: false,
+    restart: false,
+    useAccessGroups: true
+  }
+}
+```
+
+- `commands.text` (default `true`) enables parsing `/...` in chat messages.
+  - On surfaces without native commands (WhatsApp/WebChat/Signal/iMessage/Google Chat/MS Teams), text commands still work even if you set this to `false`.
+- `commands.native` (default `"auto"`) registers native commands.
+  - Auto: on for Discord/Telegram; off for Slack (until you add slash commands); ignored for providers without native support.
+  - Set `channels.discord.commands.native`, `channels.telegram.commands.native`, or `channels.slack.commands.native` to override per provider (bool or `"auto"`).
+  - `false` clears previously registered commands on Discord/Telegram at startup. Slack commands are managed in the Slack app and are not removed automatically.
+- `commands.nativeSkills` (default `"auto"`) registers **skill** commands natively when supported.
+  - Auto: on for Discord/Telegram; off for Slack (Slack requires creating a slash command per skill).
+  - Set `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills`, or `channels.slack.commands.nativeSkills` to override per provider (bool or `"auto"`).
+- `commands.bash` (default `false`) enables `! <cmd>` to run host shell commands (`/bash <cmd>` is an alias; requires `tools.elevated` allowlists).
+- `commands.bashForegroundMs` (default `2000`) controls how long bash waits before switching to background mode (`0` backgrounds immediately).
+- `commands.config` (default `false`) enables `/config` (reads/writes `clawdbot.json`).
+- `commands.debug` (default `false`) enables `/debug` (runtime-only overrides).
+- `commands.useAccessGroups` (default `true`) enforces allowlists/policies for commands.
+
+## Command list
+
+Text + native (when enabled):
+- `/help`
+- `/commands`
+- `/skill <name> [input]` (run a skill by name)
+- `/status` (show current status; includes provider usage/quota for the current model provider when available)
+- `/allowlist` (list/add/remove allowlist entries)
+- `/approve <id> allow-once|allow-always|deny` (resolve exec approval prompts)
+- `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
+- `/whoami` (show your sender id; alias: `/id`)
+- `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
+- `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
+- `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
+- `/usage off|tokens|full|cost` (per-response usage footer or local cost summary)
+- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio` (control TTS; see [/tts](/tts))
+  - Discord: native command is `/voice` (Discord reserves `/tts`); text `/tts` still works.
+- `/stop`
+- `/restart`
+- `/dock-telegram` (alias: `/dock_telegram`) (switch replies to Telegram)
+- `/dock-discord` (alias: `/dock_discord`) (switch replies to Discord)
+- `/dock-slack` (alias: `/dock_slack`) (switch replies to Slack)
+- `/activation mention|always` (groups only)
+- `/send on|off|inherit` (owner-only)
+- `/reset` or `/new [model]` (optional model hint; remainder is passed through)
+- `/think <off|minimal|low|medium|high|xhigh>` (dynamic choices by model/provider; aliases: `/thinking`, `/t`)
+- `/verbose on|full|off` (alias: `/v`)
+- `/reasoning on|off|stream` (alias: `/reason`; when on, sends a separate message prefixed `Reasoning:`; `stream` = Telegram draft only)
+- `/elevated on|off|ask|full` (alias: `/elev`; `full` skips exec approvals)
+- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` (send `/exec` to show current)
+- `/model <name>` (alias: `/models`; or `/<alias>` from `agents.defaults.models.*.alias`)
+- `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`; send `/queue` to see current settings)
+- `/bash <command>` (host-only; alias for `! <command>`; requires `commands.bash: true` + `tools.elevated` allowlists)
+
+Text-only:
+- `/compact [instructions]` (see [/concepts/compaction](/concepts/compaction))
+- `! <command>` (host-only; one at a time; use `!poll` + `!stop` for long-running jobs)
+- `!poll` (check output / status; accepts optional `sessionId`; `/bash poll` also works)
+- `!stop` (stop the running bash job; accepts optional `sessionId`; `/bash stop` also works)
+
+Notes:
+- Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
+- `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
+- For full provider usage breakdown, use `clawdbot status --usage`.
+- `/allowlist add|remove` requires `commands.config=true` and honors channel `configWrites`.
+- `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from Clawdbot session logs.
+- `/restart` is disabled by default; set `commands.restart: true` to enable it.
+- `/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.
+- **Fast path:** command-only messages from allowlisted senders are handled immediately (bypass queue + model).
+- **Group mention gating:** command-only messages from allowlisted senders bypass mention requirements.
+- **Inline shortcuts (allowlisted senders only):** certain commands also work when embedded in a normal message and are stripped before the model sees the remaining text.
+  - Example: `hey /status` triggers a status reply, and the remaining text continues through the normal flow.
+- Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
+- Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
+- **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
+  - `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
+  - By default, skill commands are forwarded to the model as a normal request.
+  - Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
+  - Example: `/prose` (OpenProse plugin) — see [OpenProse](/prose).
+- **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.
+
+## Usage surfaces (what shows where)
+
+- **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled.
+- **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
+- `/model status` is about **models/auth/endpoints**, not usage.
+
+## Model selection (`/model`)
+
+`/model` is implemented as a directive.
+
+Examples:
+
+```
+/model
+/model list
+/model 3
+/model openai/gpt-5.2
+/model opus@anthropic:default
+/model status
+```
+
+Notes:
+- `/model` and `/model list` show a compact, numbered picker (model family + available providers).
+- `/model <#>` selects from that picker (and prefers the current provider when possible).
+- `/model status` shows the detailed view, including configured provider endpoint (`baseUrl`) and API mode (`api`) when available.
+
+## Debug overrides
+
+`/debug` lets you set **runtime-only** config overrides (memory, not disk). Owner-only. Disabled by default; enable with `commands.debug: true`.
+
+Examples:
+
+```
+/debug show
+/debug set messages.responsePrefix="[clawdbot]"
+/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
+/debug unset messages.responsePrefix
+/debug reset
+```
+
+Notes:
+- Overrides apply immediately to new config reads, but do **not** write to `clawdbot.json`.
+- Use `/debug reset` to clear all overrides and return to the on-disk config.
+
+## Config updates
+
+`/config` writes to your on-disk config (`clawdbot.json`). Owner-only. Disabled by default; enable with `commands.config: true`.
+
+Examples:
+
+```
+/config show
+/config show messages.responsePrefix
+/config get messages.responsePrefix
+/config set messages.responsePrefix="[clawdbot]"
+/config unset messages.responsePrefix
+```
+
+Notes:
+- Config is validated before write; invalid changes are rejected.
+- `/config` updates persist across restarts.
+
+## Surface notes
+
+- **Text commands** run in the normal chat session (DMs share `main`, groups have their own session).
+- **Native commands** use isolated sessions:
+  - Discord: `agent:<agentId>:discord:slash:<userId>`
+  - Slack: `agent:<agentId>:slack:slash:<userId>` (prefix configurable via `channels.slack.slashCommand.sessionPrefix`)
+  - Telegram: `telegram:slash:<userId>` (targets the chat session via `CommandTargetSessionKey`)
+- **`/stop`** targets the active chat session so it can abort the current run.
+- **Slack:** `channels.slack.slashCommand` is still supported for a single `/clawd`-style command. If you enable `commands.native`, you must create one Slack slash command per built-in command (same names as `/help`). Command argument menus for Slack are delivered as ephemeral Block Kit buttons.

package/docs/tools/subagents.md

@@ -0,0 +1,137 @@
+---
+summary: "Sub-agents: spawning isolated agent runs that announce results back to the requester chat"
+read_when:
+  - You want background/parallel work via the agent
+  - You are changing sessions_spawn or sub-agent tool policy
+---
+
+# Sub-agents
+
+Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel.
+
+## Slash command
+
+Use `/subagents` to inspect or control sub-agent runs for the **current session**:
+- `/subagents list`
+- `/subagents stop <id|#|all>`
+- `/subagents log <id|#> [limit] [tools]`
+- `/subagents info <id|#>`
+- `/subagents send <id|#> <message>`
+
+`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).
+
+Primary goals:
+- Parallelize “research / long task / slow tool” work without blocking the main run.
+- Keep sub-agents isolated by default (session separation + optional sandboxing).
+- Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
+- Avoid nested fan-out: sub-agents cannot spawn sub-agents.
+
+Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive
+tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.
+You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
+
+## Tool
+
+Use `sessions_spawn`:
+- Starts a sub-agent run (`deliver: false`, global lane: `subagent`)
+- Then runs an announce step and posts the announce reply to the requester chat channel
+- Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins.
+
+Tool params:
+- `task` (required)
+- `label?` (optional)
+- `agentId?` (optional; spawn under another agent id if allowed)
+- `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)
+- `thinking?` (optional; overrides thinking level for the sub-agent run)
+- `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds)
+- `cleanup?` (`delete|keep`, default `keep`)
+
+Allowlist:
+- `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent.
+
+Discovery:
+- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`.
+
+Auto-archive:
+- Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).
+- Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder).
+- `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename).
+- Auto-archive is best-effort; pending timers are lost if the gateway restarts.
+- `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
+
+## Authentication
+
+Sub-agent auth is resolved by **agent id**, not by session type:
+- The sub-agent session key is `agent:<agentId>:subagent:<uuid>`.
+- The auth store is loaded from that agent’s `agentDir`.
+- The main agent’s auth profiles are merged in as a **fallback**; agent profiles override main profiles on conflicts.
+
+Note: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.
+
+## Announce
+
+Sub-agents report back via an announce step:
+- The announce step runs inside the sub-agent session (not the requester session).
+- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
+- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).
+- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).
+- Announce messages are normalized to a stable template:
+  - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).
+  - `Result:` the summary content from the announce step (or `(not available)` if missing).
+  - `Notes:` error details and other useful context.
+- `Status` is not inferred from model output; it comes from runtime outcome signals.
+
+Announce payloads include a stats line at the end (even when wrapped):
+- Runtime (e.g., `runtime 5m12s`)
+- Token usage (input/output/total)
+- Estimated cost when model pricing is configured (`models.providers.*.models[].cost`)
+- `sessionKey`, `sessionId`, and transcript path (so the main agent can fetch history via `sessions_history` or inspect the file on disk)
+
+## Tool Policy (sub-agent tools)
+
+By default, sub-agents get **all tools except session tools**:
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+Override via config:
+
+```json5
+{
+  agents: {
+    defaults: {
+      subagents: {
+        maxConcurrent: 1
+      }
+    }
+  },
+  tools: {
+    subagents: {
+      tools: {
+        // deny wins
+        deny: ["gateway", "cron"],
+        // if allow is set, it becomes allow-only (deny still wins)
+        // allow: ["read", "exec", "process"]
+      }
+    }
+  }
+}
+```
+
+## Concurrency
+
+Sub-agents use a dedicated in-process queue lane:
+- Lane name: `subagent`
+- Concurrency: `agents.defaults.subagents.maxConcurrent` (default `8`)
+
+## Stopping
+
+- Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it.
+
+## Limitations
+
+- Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost.
+- Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.
+- `sessions_spawn` is always non-blocking: it returns `{ status: "accepted", runId, childSessionKey }` immediately.
+- Sub-agent context only injects `AGENTS.md` + `TOOLS.md` (no `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`).

package/docs/tools/thinking.md

@@ -0,0 +1,62 @@
+---
+summary: "Directive syntax for /think + /verbose and how they affect model reasoning"
+read_when:
+  - Adjusting thinking or verbose directive parsing or defaults
+---
+# Thinking Levels (/think directives)
+
+## What it does
+- Inline directive in any inbound body: `/t <level>`, `/think:<level>`, or `/thinking <level>`.
+- Levels (aliases): `off | minimal | low | medium | high | xhigh` (GPT-5.2 + Codex models only)
+  - minimal → “think”
+  - low → “think hard”
+  - medium → “think harder”
+  - high → “ultrathink” (max budget)
+  - xhigh → “ultrathink+” (GPT-5.2 + Codex models only)
+  - `highest`, `max` map to `high`.
+- Provider notes:
+  - Z.AI (`zai/*`) only supports binary thinking (`on`/`off`). Any non-`off` level is treated as `on` (mapped to `low`).
+
+## Resolution order
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agents.defaults.thinkingDefault` in config).
+4. Fallback: low for reasoning-capable models; off otherwise.
+
+## Setting a session default
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/think:medium` or `/t high`.
+- That sticks for the current session (per-sender by default); cleared by `/think:off` or session idle reset.
+- Confirmation reply is sent (`Thinking level set to high.` / `Thinking disabled.`). If the level is invalid (e.g. `/thinking big`), the command is rejected with a hint and the session state is left unchanged.
+- Send `/think` (or `/think:`) with no argument to see the current thinking level.
+
+## Application by agent
+- **Embedded Pi**: the resolved level is passed to the in-process Pi agent runtime.
+
+## Verbose directives (/verbose or /v)
+- Levels: `on` (minimal) | `full` | `off` (default).
+- Directive-only message toggles session verbose and replies `Verbose logging enabled.` / `Verbose logging disabled.`; invalid levels return a hint without changing state.
+- `/verbose off` stores an explicit session override; clear it via the Sessions UI by choosing `inherit`.
+- Inline directive affects only that message; session/global defaults apply otherwise.
+- Send `/verbose` (or `/verbose:`) with no argument to see the current verbose level.
+- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool call back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command). These tool summaries are sent as soon as each tool starts (separate bubbles), not as streaming deltas.
+- When verbose is `full`, tool outputs are also forwarded after completion (separate bubble, truncated to a safe length). If you toggle `/verbose on|full|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
+
+## Reasoning visibility (/reasoning)
+- Levels: `on|off|stream`.
+- Directive-only message toggles whether thinking blocks are shown in replies.
+- When enabled, reasoning is sent as a **separate message** prefixed with `Reasoning:`.
+- `stream` (Telegram only): streams reasoning into the Telegram draft bubble while the reply is generating, then sends the final answer without reasoning.
+- Alias: `/reason`.
+- Send `/reasoning` (or `/reasoning:`) with no argument to see the current reasoning level.
+
+## Related
+- Elevated mode docs live in [Elevated mode](/tools/elevated).
+
+## Heartbeats
+- Heartbeat probe body is the configured heartbeat prompt (default: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+- Heartbeat delivery defaults to the final payload only. To also send the separate `Reasoning:` message (when available), set `agents.defaults.heartbeat.includeReasoning: true` or per-agent `agents.list[].heartbeat.includeReasoning: true`.
+
+## Web chat UI
+- The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
+- Picking another level applies only to the next message (`thinkingOnce`); after sending, the selector snaps back to the stored session level.
+- To change the session default, send a `/think:<level>` directive (as before); the selector will reflect it after the next reload.