better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/tool-search.md

@@ -0,0 +1,277 @@
+---
+title: Tool Search
+sidebar_position: 95
+---
+
+# Tool Search
+
+When you have many MCP servers or non-core plugin tools attached to a
+session, their JSON schemas can consume a substantial fraction of the
+context window on every turn — even when only a few of them are relevant
+to what the user actually asked for.
+
+**Tool Search** is Hermes' opt-in progressive-disclosure layer for that
+problem. When activated, MCP and plugin tools are replaced in the
+model-visible tools array by three bridge tools, and the model loads each
+specific tool's schema on demand.
+
+:::info Built-in Hermes tools never defer
+The tools that make up Hermes' core capability set (`terminal`,
+`read_file`, `write_file`, `patch`, `search_files`, `todo`, `memory`,
+`browser_*`, `web_search`, `web_extract`, `clarify`, `execute_code`,
+`delegate_task`, `session_search`, and the rest of
+`_HERMES_CORE_TOOLS`) are *always* loaded directly. Only MCP tools and
+non-core plugin tools are eligible for deferral.
+:::
+
+## How it works
+
+When Tool Search activates for a turn, the model sees three new tools in
+place of the deferred ones:
+
+```
+tool_search(queries, limit?)   search the deferred-tool catalog (one or more queries)
+tool_describe(names)           load the full schemas for one or more tools
+tool_call(calls)               invoke deferred tools; `calls` is an array of {name, arguments}
+```
+
+`calls` takes one entry per invocation; a single local call is an array of
+one. Only `connectors__` names may be batched together; mixed and
+multi-local batches are rejected.
+
+A typical interaction looks like:
+
+```
+Model: tool_search(["create a github issue", "send a slack message"])
+  → { results: [ { query: "create a github issue",
+                   matches: ["mcp_github_create_issue", ...] },
+                 { query: "send a slack message",
+                   matches: ["mcp_slack_post_message", ...] } ],
+      tools: { mcp_github_create_issue: { description: "...",
+                                          required: ["title"], ... },
+               mcp_slack_post_message: { ... } } }
+Model: tool_describe(["mcp_github_create_issue", "mcp_slack_post_message"])
+  → { tools: { mcp_github_create_issue: { parameters: { ... } },
+               mcp_slack_post_message: { parameters: { ... } } } }
+Model: tool_call({ calls: [{ name: "mcp_github_create_issue",
+                             arguments: { title: "...", body: "..." } }] })
+  → { ok: true, issue_number: 42 }
+```
+
+Each query in a `tool_search` call is searched independently against the
+same catalog (`limit` applies per query); the per-query groups carry tool
+names only, while the shared `tools` map holds each matched tool's
+description and required parameter names once. Queries are stemmed, so
+"issues" finds `create_issue`. Each query group that returns no matches
+includes an `available_sources` summary of the connected servers so a lexical
+miss is not mistaken for a missing capability.
+`tool_describe` resolves every requested name in one call; unknown names
+are reported in `not_found` without failing the rest of the batch.
+
+When the model invokes `tool_call`, Hermes **unwraps the bridge** and
+dispatches the underlying tool exactly as if the model had called it
+directly. Pre-tool-call hooks, guardrails, approval prompts, and
+post-tool-call hooks all run against the real tool name — not against
+`tool_call`. The activity feed in the CLI and gateway also unwraps so you
+see the underlying tool, not the bridge.
+
+## When does it activate?
+
+Tool Search uses **tiered disclosure**: the presence of *any* deferrable
+(MCP/plugin) tool activates the bridge; what scales with catalog size is
+how much of the catalog stays visible, not whether schemas defer.
+
+| Tier | Condition | What the model sees |
+| --- | --- | --- |
+| **0** | No MCP/plugin tools | Every tool eager, no bridge. Pass-through. |
+| **1** | Deferred catalog's listing fits the budget | Bridge + a skills-style manifest of every deferred tool (name + short description, degrading to names-only when over budget). Degradation is **per server**: when one oversized server (Cloudflare) is attached alongside small ones (Linear), the small servers keep their per-tool listings and only the oversized server collapses to a summary line. |
+| **2** | Per-tool listing exceeds the budget even names-only for every server (e.g. Cloudflare's flat API surface alone: ~3,300 tools whose names are ~32K tokens) | Bare bridge + a one-line-per-server summary (server name + tool count), so the model knows which domains are reachable; individual tools are discoverable only through `tool_search`. |
+
+The listing budget is `min(threshold_pct% of context, listing_max_tokens)`.
+The decision is re-evaluated every time the tools array is built, so
+adding or removing MCP servers mid-session moves the session between
+tiers on the next assembly.
+
+## Configuration
+
+```yaml
+tools:
+  tool_search:
+    enabled: auto       # auto (default), on, or off
+    threshold_pct: 5    # listing budget as a percentage of context
+    search_default_limit: 5
+    max_search_limit: 25
+    listing: auto       # embed a grouped name+description catalog manifest
+    listing_max_tokens: 4000
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `auto` | `auto`/`on` activate whenever at least one deferrable tool exists; `off` disables entirely (everything stays eager). `auto` is currently an alias of `on` — it is reserved for a future mode that inlines schemas when they fit the context and defers only when they don't. Pin `on` or `off` if you want today's behavior guaranteed across upgrades. |
+| `threshold_pct` | `5` | Listing budget as a percentage of the active model's context length. Range 0–100. |
+| `search_default_limit` | `5` | Hits returned per query when the model calls `tool_search` without a `limit`. |
+| `max_search_limit` | `25` | Hard upper bound the model can request via `limit` (per query). Range 1–50. |
+| `listing` | `auto` | Embed a skills-style manifest of every deferred tool (name + first sentence of its description, ≤60 chars, grouped by MCP server) in the `tool_search` bridge description. `auto` includes it when it fits the budget (falling back to names-only, then to the tier-2 server summary); `on`/`off` force either way. |
+| `listing_max_tokens` | `4000` | Absolute cap on the embedded listing, regardless of context size. Range 200–60000. Large catalogs degrade to names-only or per-server summaries, keeping full schemas available through search. |
+
+Per-call array caps are internal safety bounds, not configuration. Over-cap
+calls return an error so the model can retry with a smaller batch.
+
+### Why the listing exists
+
+Without it, deferred capabilities are *invisible* — live benchmarking showed
+models substituting visible core tools (running `gh` in the terminal instead
+of searching for the deferred GitHub tool) or declaring a capability
+nonexistent instead of calling `tool_search`. The listing applies the skills
+pattern to tools: every capability stays discoverable by name at all times,
+while full parameter schemas remain deferred. If the model sees the exact
+tool name in the listing, it can skip `tool_search` and go straight to
+`tool_describe`, saving a round trip.
+
+You can also flip the legacy boolean shape:
+
+```yaml
+tools:
+  tool_search: true   # equivalent to {enabled: auto}
+```
+
+## Connectors (remote tools)
+
+When you are signed in to the Nous Portal, the bridge additionally reaches
+**connectors** — remote tools served by the managed tool gateway. They are
+never registered locally: `tool_search` sends each query to the gateway, adds
+the gateway's hits to the local catalog as documents (tagged
+`source: "connectors"`, named `connectors__<connector>__<tool>`), and ranks
+both with the same BM25 pass and the same rarest-token rule, so `limit`
+caps the group as a whole and a connector tool that answers the query is
+never pushed out by local tools that share one word with it. The gateway
+call is bounded at 30 seconds; a slow or dark gateway degrades to local
+results only. `tool_describe` fetches connector schemas from the gateway,
+and `tool_call` sends each connector entry in a batch as its own gateway
+request, in input order (a tool name the gateway does not know under its
+conventional slug is retried once under the literal slug, so an entry can
+cost two requests). If a connector ever shipped both `GMAIL_X` and a literal
+`X`, both would compose to `connectors__gmail__X`, which runs `GMAIL_X`;
+search keeps that twin, drops the other, and logs a warning. Results splice back into the batch's original order
+with recomputed counts.
+
+```yaml
+tools:
+  connectors:
+    enabled: true   # false — never touch connector routes; the bridge
+                    # behaves exactly as if the feature didn't exist
+```
+
+Signed out (or when the gateway does not serve connectors for your
+account), everything above is invisible: local search behaves exactly as
+described in the rest of this page, with no errors shown to the model.
+
+A connector call that needs an account you haven't linked returns a
+`CONNECTION_REQUIRED` error. The `manage_connections` tool lists connectors and
+their connection state and starts an authorization: in the desktop app the call
+shows a card, blocks until each app is connected or skipped, and reports the
+outcomes; elsewhere it returns a connect link per app for the user to open.
+Disconnecting an account is done by the user in the Portal. The same tool also installs, enables and authorizes
+local MCP servers from the catalog (targets with `mcp: true`), so it is
+present whether or not you are signed in; only the managed-connector actions
+need the sign-in.
+
+`tool_call` accepts a batch: `calls` is an array of `{name, arguments}`
+entries (a single call is an array of one). Each connector entry in a batch
+is dispatched as its own gateway request, one after another; local deferred
+tools stay one entry per `tool_call`. Approvals settle per entry before
+dispatch, and a `/stop` between entries leaves the unstarted ones unsent
+(their slots report `INTERRUPTED`).
+
+## When NOT to use it
+
+Tool Search trades a fixed per-turn token cost (the three bridge tool
+schemas plus the catalog listing) and at least one extra round trip on
+cold tools (describe → call) for the savings on the deferred schemas.
+At tier 1 the listing keeps every capability visible, so the discovery
+round trip usually disappears — the model goes straight to
+`tool_describe`. Live benchmarking showed the listing mode matching
+eager loading's task success while costing less than the bare bridge.
+
+If you want the old always-eager behavior for a small toolset, set
+`enabled: off`.
+
+## Trade-offs that don't go away
+
+These come from the prompt-cache integrity invariant — they are inherent
+to any progressive-disclosure design, not specific to this implementation:
+
+- **One extra round trip on cold tools.** The first time the model needs
+  a deferred tool, it spends one or two extra model calls to find and
+  load the schema. The token savings on the static side are real, but a
+  portion is paid back at runtime.
+- **No cache benefit on deferred schemas.** A loaded `tool_describe`
+  result enters the conversation history (so it does get cached on
+  subsequent turns) but it never benefits from the system-prompt cache
+  prefix.
+- **No provider-native validation for deferred schemas.** `tool_describe`
+  lets the model read a deferred tool's schema, but the provider still sees
+  only the generic `tool_call.arguments` object. Hermes therefore coerces and
+  validates the underlying arguments locally before dispatch; the concrete
+  tool or MCP server remains responsible for schemas Hermes cannot safely
+  validate, such as malformed schemas or external references.
+- **Model-quality dependence.** Tool Search assumes the model can write a
+  reasonable search query for the tool it wants. Smaller models do this
+  less well; the published Anthropic numbers (49% → 74% on Opus 4 with
+  vs. without tool search) show the upside but also that ~26 points of
+  accuracy is still retrieval failure.
+- **Toolset edits invalidate cache.** Adding or removing a tool mid-
+  session changes the bridge tools' descriptions (which include the
+  count of deferred tools) and the catalog, so the prompt cache is
+  invalidated. This is the same trade-off as any toolset edit.
+
+## Implementation details
+
+- **Retrieval:** BM25 over tokenized tool name, source name (the MCP
+  server or plugin toolset the tool belongs to, so searching `"linear"`
+  finds that server's tools even when a tool's own name doesn't carry
+  the service), description, and parameter names, with Snowball
+  stemming (English) applied to both the index and the query so
+  morphological variants match ("issues" finds `create_issue`). A tool is
+  a result only if it contains the query's rarest token (the one in the
+  fewest tool documents, so the word that names the intent: `gmail`,
+  `github`, `incident`, not `send` or `create`). A query whose rarest
+  token appears in no tool returns an empty group with the connected
+  sources and a retry hint, instead of `limit` tools that share one
+  common word.
+- **Relevance floor:** a tool must match at least half of a query's
+  *answerable* terms (terms present anywhere in the catalog) before it
+  is offered — sharing one incidental word with a long query is not a
+  match. A hunt for a capability that doesn't exist returns no results
+  instead of a plausible-looking list the model rephrases against
+  forever. The floor only engages from four answerable terms up, so
+  short queries like "list issues" keep full recall, and an exact
+  tool-name query always matches.
+- **Parallel execution unwraps the bridge.** The batch planner decides
+  concurrency on the *underlying* tool of a `tool_call`, not on the
+  literal bridge name — so an MCP server opted in via
+  `supports_parallel_tool_calls: true` keeps its concurrency when its
+  tools are called through the bridge, and `tool_search` /
+  `tool_describe` lookups batch concurrently like any read-only tool.
+- **Catalog is stateless across turns.** It rebuilds from the current
+  tool-defs list every assembly — no session-keyed `Map`. This avoids
+  the class of bug where a stored catalog drifts out of sync with the
+  live tool registry.
+- **The catalog is scoped to the session's toolsets.** `tool_search`,
+  `tool_describe`, and `tool_call` only ever see and invoke tools the
+  session was actually granted. A subagent, kanban worker, or gateway
+  session restricted to a subset of toolsets cannot use the bridge to
+  discover or call a tool outside that subset — the deferred catalog is
+  the deferrable slice of the session's own enabled/disabled toolsets,
+  not the whole process registry.
+- **No JS sandbox.** Hermes uses the simpler "structured tools" mode
+  (search / describe / call as plain functions). The JS-sandbox "code
+  mode" some other implementations offer is a large surface area; we
+  skip it.
+
+## See also
+
+- `tools/tool_search.py` — the implementation
+- `tests/tools/test_tool_search.py` — the regression suite
+- The `openclaw-tool-search-report` PDF in the original implementation
+  PR for the research that shaped the design

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/tools.md

@@ -0,0 +1,261 @@
+---
+sidebar_position: 1
+title: "Tools & Toolsets"
+description: "Overview of Hermes Agent's tools — what's available, how toolsets work, and terminal backends"
+---
+
+# Tools & Toolsets
+
+Tools are functions that extend the agent's capabilities. They're organized into logical **toolsets** that can be enabled or disabled per platform.
+
+## Available Tools
+
+Hermes ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, scheduled tasks, Home Assistant, and more.
+
+:::note
+**Honcho cross-session memory** is available as a memory provider plugin (`plugins/memory/honcho/`), not as a built-in toolset. See [Plugins](./plugins.md) for installation.
+:::
+
+High-level categories:
+
+| Category | Examples | Description |
+|----------|----------|-------------|
+| **Web** | `web_search`, `web_extract` | Search the web and extract page content. |
+| **X Search** | `x_search` | Search X (Twitter) posts and threads via xAI's built-in `x_search` Responses tool — gated on xAI credentials (SuperGrok OAuth or `XAI_API_KEY`); off by default, opt in via `hermes tools` → 🐦 X (Twitter) Search. |
+| **Terminal & Files** | `terminal`, `process`, `read_file`, `patch` | Execute commands and manipulate files. |
+| **Browser** | `browser_navigate`, `browser_snapshot`, `browser_vision` | Interactive browser automation with text and vision support. |
+| **Media** | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. |
+| **Agent orchestration** | `todo`, `clarify`, `execute_code`, `delegate_task` | Planning, clarification, code execution, and subagent delegation. |
+| **Memory & recall** | `memory`, `session_search` | Persistent memory and session search. |
+| **Automation** | `cronjob` | Scheduled tasks with create/list/update/pause/resume/run/remove actions. Outbound delivery is handled by cron's own delivery, the `hermes send` CLI, and the gateway notifier — not by an agent-callable tool. |
+| **Integrations** | `ha_*`, MCP server tools | Home Assistant, MCP, and other integrations. |
+
+For the authoritative code-derived registry, see [Built-in Tools Reference](/reference/tools-reference) and [Toolsets Reference](/reference/toolsets-reference).
+
+:::tip Nous Tool Gateway
+Paid [Nous Portal](https://portal.nousresearch.com) subscribers can use web search, image generation, TTS, and browser automation through the **[Tool Gateway](tool-gateway.md)** — no separate API keys needed. Run `hermes model` to enable it, or configure individual tools with `hermes tools`.
+:::
+
+## Using Toolsets
+
+```bash
+# Use specific toolsets
+hermes chat --toolsets "web,terminal"
+
+# See all available tools
+hermes tools
+
+# Configure tools per platform (interactive)
+hermes tools
+```
+
+Common toolsets include `web`, `search`, `terminal`, `file`, `browser`, `vision`, `image_gen`, `skills`, `tts`, `todo`, `memory`, `session_search`, `cronjob`, `code_execution`, `delegation`, `clarify`, `homeassistant`, `messaging`, `spotify`, `discord`, `discord_admin`, `debugging`, and `safe`.
+
+See [Toolsets Reference](/reference/toolsets-reference) for the full set, including platform presets such as `hermes-cli`, `hermes-telegram`, and dynamic MCP toolsets like `mcp-<server>`.
+
+## Tool result annotations
+
+A few tool behaviors are worth knowing when you read agent transcripts:
+
+- **Signal deaths are explained.** When a terminal command is killed by a signal, the result carries a human-readable note instead of a bare numeric code — e.g. exit `-9`/`137` becomes "terminated by signal 9: SIGKILL — often the kernel OOM killer on memory exhaustion, or an explicit kill -9", and segfaults, aborts, SIGTERM, broken pipes, and CPU/file-size limits are labeled the same way. Negative codes (subprocess semantics) are stated definitively; the shell's `128+signum` convention is hedged with "usually" since an application can legitimately exit with those codes.
+- **UTF-16 text files are transcoded, not refused.** `read_file` detects UTF-16 (BOM or byte-pattern heuristic, either endianness — common for Windows Notepad files and PowerShell `>` redirects) and transcodes it to UTF-8 for display instead of flagging the file as binary. The result includes a hint disclosing the conversion; edits via `patch`/`write_file` re-encode as UTF-8. Files over 10 MB and genuinely binary files still get the binary-file refusal.
+
+## Terminal Backends
+
+The terminal tool can execute commands in different environments:
+
+| Backend | Description | Use Case |
+|---------|-------------|----------|
+| `local` | Run on your machine (default) | Development, trusted tasks |
+| `docker` | Isolated containers | Security, reproducibility |
+| `ssh` | Remote server | Sandboxing, keep agent away from its own code |
+| `singularity` | HPC containers | Cluster computing, rootless |
+| `modal` | Cloud execution | Serverless, scale |
+| `daytona` | Cloud sandbox workspace | Persistent remote dev environments |
+| `vercel_sandbox` | Vercel Sandbox cloud microVM | Cloud execution with snapshot-backed filesystem persistence |
+
+### Configuration
+
+```yaml
+# In ~/.hermes/config.yaml
+terminal:
+  backend: local    # or: docker, ssh, singularity, modal, daytona, vercel_sandbox
+  cwd: "."          # Working directory
+  timeout: 180      # Command timeout in seconds
+```
+
+### Shell startup files and non-interactive commands
+
+Agent terminal calls run your shell **non-interactively** — there is no TTY and no human at the prompt. Heavy or interactive shell initialisation that you never notice in a normal terminal can break or badly slow every command the agent runs:
+
+- **Slow init (`nvm`, version managers, network-touching prompts):** the classic `nvm.sh` sourcing adds noticeable latency to *every* shell start, and the agent starts many shells. Multi-second rc files turn a quick `git status` into a timeout risk.
+- **TTY-expecting blocks:** anything in `.bashrc`/`.zshrc` that prompts, runs `tmux`/`screen` attach, calls `read`, or prints a menu will hang a non-interactive shell — the command appears to run forever and then times out.
+- **Unconditional output:** rc files that `echo` banners pollute every command's output the agent has to parse.
+
+The fix is the standard guard most distros already ship at the top of `.bashrc` — return early when the shell is non-interactive, and keep anything heavy or interactive below it:
+
+```bash
+# ~/.bashrc — keep this guard near the top
+case $- in
+  *i*) ;;      # interactive: continue
+  *) return;;  # non-interactive: stop here
+esac
+
+# heavy/interactive init goes BELOW the guard
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
+```
+
+Zsh users: put login-only setup in `.zprofile` and interactive-only setup in `.zshrc`; keep `.zshenv` minimal, since it runs for every shell including non-interactive ones. If the agent genuinely needs a tool that only your rc file puts on `PATH`, export the `PATH` change *above* the guard (path exports are cheap) or symlink the binary into `~/.local/bin`.
+
+If agent terminal commands hang or time out immediately after working in your own terminal, your shell init is the first suspect.
+
+### Docker Backend
+
+```yaml
+terminal:
+  backend: docker
+  docker_image: python:3.11-slim
+```
+
+**One persistent container, shared across the whole process.** Hermes starts a single long-lived container on first use (`docker run -d ... sleep infinity`) and routes every terminal, file, and `execute_code` call through `docker exec` into that same container. Working-directory changes, installed packages, environment tweaks, and files written to `/workspace` all carry over from one tool call to the next, across `/new`, `/reset`, and `delegate_task` subagents, for the lifetime of the Hermes process. The container is stopped and removed on shutdown.
+
+This means the Docker backend behaves like a persistent sandbox VM, not a fresh container per command. If you `pip install foo` once, it's there for the rest of the session. If you `cd /workspace/project`, subsequent `ls` calls see that directory. See [Configuration → Docker Backend](../configuration.md#docker-backend) for the full lifecycle details and the `container_persistent` flag that controls whether `/workspace` and `/root` survive across Hermes restarts.
+
+### SSH Backend
+
+Recommended for security — agent can't modify its own code:
+
+```yaml
+terminal:
+  backend: ssh
+```
+```bash
+# Set credentials in ~/.hermes/.env
+TERMINAL_SSH_HOST=my-server.example.com
+TERMINAL_SSH_USER=myuser
+TERMINAL_SSH_KEY=~/.ssh/id_rsa
+```
+
+### Singularity/Apptainer
+
+```bash
+# Pre-build SIF for parallel workers
+apptainer build ~/python.sif docker://python:3.11-slim
+
+# Configure
+hermes config set terminal.backend singularity
+hermes config set terminal.singularity_image ~/python.sif
+```
+
+### Modal (Serverless Cloud)
+
+```bash
+uv pip install modal
+modal setup
+hermes config set terminal.backend modal
+```
+
+### Vercel Sandbox
+
+```bash
+pip install 'hermes-agent[vercel]'
+hermes config set terminal.backend vercel_sandbox
+hermes config set terminal.vercel_runtime node24
+```
+
+Authenticate with all three of `VERCEL_TOKEN`, `VERCEL_PROJECT_ID`, and `VERCEL_TEAM_ID`. This access-token setup is the supported path for deployments and normal long-running Hermes processes on Render, Railway, Docker, and similar hosts. Supported runtimes are `node24`, `node22`, and `python3.13`; Hermes defaults to `/vercel/sandbox` as the remote workspace root.
+
+For one-off local development, Hermes also accepts short-lived Vercel OIDC tokens:
+
+```bash
+VERCEL_OIDC_TOKEN="$(vc project token <project-name>)" hermes chat
+```
+
+From a linked Vercel project directory:
+
+```bash
+VERCEL_OIDC_TOKEN="$(vc project token)" hermes chat
+```
+
+With `container_persistent: true`, Hermes uses Vercel snapshots to preserve filesystem state across sandbox recreation for the same task. This can include Hermes-synced credentials, skills, and cache files inside the sandbox. Snapshots do not preserve live processes, PID space, or the same live sandbox identity.
+
+Background terminal commands use Hermes' generic non-local process flow: spawn, poll, wait, log, and kill work through the normal process tool while the sandbox is alive, but Hermes does not provide native Vercel detached-process recovery after cleanup or restart.
+
+Leave `container_disk` unset or at the shared default `51200`; custom disk sizing is unsupported for Vercel Sandbox and will fail diagnostics/backend creation.
+
+### Container Resources
+
+Configure CPU, memory, disk, and persistence for all container backends:
+
+```yaml
+terminal:
+  backend: docker  # or singularity, modal, daytona, vercel_sandbox
+  container_cpu: 1              # CPU cores (default: 1)
+  container_memory: 5120        # Memory in MB (default: 5GB)
+  container_disk: 51200         # Disk in MB (default: 50GB)
+  container_persistent: true    # Persist filesystem across sessions (default: true)
+```
+
+When `container_persistent: true`, installed packages, files, and config survive across sessions.
+
+### Container Security
+
+All container backends run with security hardening:
+
+- Read-only root filesystem (Docker)
+- All Linux capabilities dropped
+- No privilege escalation
+- PID limits (256 processes)
+- Full namespace isolation
+- Persistent workspace via volumes, not writable root layer
+
+Docker can optionally receive an explicit env allowlist via `terminal.docker_forward_env`, but forwarded variables are visible to commands inside the container and should be treated as exposed to that session.
+
+## Background Process Management
+
+Start background processes and manage them:
+
+```python
+terminal(command="pytest -v tests/", background=true)
+# Returns: {"session_id": "proc_abc123", "pid": 12345}
+
+# Then manage with the process tool:
+process(action="list")       # Show all running processes
+process(action="poll", session_id="proc_abc123")   # Check status
+process(action="wait", session_id="proc_abc123")   # Block until done
+process(action="log", session_id="proc_abc123")    # Full output
+process(action="kill", session_id="proc_abc123")   # Terminate
+process(action="write", session_id="proc_abc123", data="y")  # Send input
+```
+
+PTY mode (`pty=true`) enables interactive CLI tools like Codex and Claude Code.
+
+Completed background commands retain their exit status and captured output in the
+active profile. Resume the conversation that launched the command (or its
+compressed continuation), then use the original `session_id` with
+`process(action="log")` for output and `process(action="poll")` for exit status.
+Unrelated conversations and requests without a bound owning session cannot read
+retained receipts, even with an exact process handle. `process(action="list")`
+also includes retained results for the current task or conversation.
+
+Hermes keeps the newest **64 completed results**, for up to **7 days after
+completion**, under `logs/process-results/` in the profile's Hermes home. Each
+receipt contains at most the existing rolling **200,000-character output tail**,
+with terminal secret-redaction rules always applied, even when live-output
+redaction is disabled. Receipts expire on subsequent
+result reads or writes. Recovery does not rerun commands or replay completion
+notifications. This preserves work that finished while the parent was alive;
+it does not keep unfinished children alive after a timeout or crash.
+
+## Sudo Support
+
+On an interactive parent session, supported sudo commands use the masked password prompt (cached for the session). This includes literal absolute or quoted executable paths and `env` prefixes with ordinary options and assignments, such as `env -u UNUSED /usr/bin/sudo id`. Passwordless sudo does not need a prompt. You can also configure `SUDO_PASSWORD` in your profile's `.env` file on the agent machine.
+
+Shell payloads such as `bash -c 'sudo id'`, `env -S` split strings, dynamic executable paths, and unrecognized `env` options are not interpreted by the password rewriter. Invoke sudo directly when you need the interactive prompt. This handling does not change approval rules or the guard against agent-supplied sudo passwords.
+
+Delegated subagents cannot open a password prompt: their concurrent work does not have a serialized human password channel. Run the command in the parent session instead, or provision `SUDO_PASSWORD` locally. Messaging/headless sessions do not have a secure password reply channel; never send passwords in chat.
+
+:::warning
+On messaging platforms, if sudo fails, the output includes a tip to add `SUDO_PASSWORD` to `~/.hermes/.env`.
+:::