better-dsh 0.2.5-c → 0.2.5-e

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

@@ -1,277 +0,0 @@
----
-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

@@ -1,261 +0,0 @@
----
-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`.
-:::