docs: document MCP sanitization and tool-result annotations from the scout-slate wave
Post-merge docs sweep for the Aug 16 scout slate. Two pages: - mcp.md: tool-result sanitization section — invisible Unicode TAG chars (U+E0000-E007F) stripped from results/resources/descriptions (#80689); vendor _meta surfaced to the model minus protocol-reserved modelcontextprotocol/mcp prefixes (#80712) - tools.md: tool result annotations section — signal-death exit notes (subprocess -signum definite, shell 128+signum hedged) (#78074); UTF-16 read_file transcoding with disclosure hint and 10MB cap (#80717) Security-policy docs (approvals/allowlist) intentionally untouched.
This commit is contained in:
@@ -456,6 +456,13 @@ Examples:
|
||||
|
||||
In practice, you usually do not need to call the prefixed name manually — Hermes sees the tool and chooses it during normal reasoning.
|
||||
|
||||
### Tool-result sanitization and `_meta`
|
||||
|
||||
Two behaviors apply to every MCP tool result before the model sees it:
|
||||
|
||||
- **Invisible Unicode TAG characters are stripped.** Characters in the U+E0000–U+E007F range render as nothing in terminals and chat UIs but are fully visible to the model — a classic prompt-injection smuggling channel for a malicious or compromised server. Hermes strips them from tool results, resource content, and tool descriptions. Legitimate emoji tag sequences (regional flags like 🏴) are preserved.
|
||||
- **Vendor `_meta` is surfaced; protocol-reserved keys are not.** When a server attaches a `_meta` mapping to a tool result (vendor namespaces like `com.example/handoff`), Hermes passes it through to the model alongside the result content. Keys under protocol-reserved prefixes — a `modelcontextprotocol` or `mcp` label followed by another label, e.g. `modelcontextprotocol.io/...` or `tools.mcp.com/...` — are dropped, matching the MCP spec's key-name rules. If nothing model-facing remains, the `_meta` field is omitted entirely.
|
||||
|
||||
## MCP utility tools
|
||||
|
||||
When supported, Hermes also registers utility tools around MCP resources and prompts:
|
||||
|
||||
@@ -53,6 +53,13 @@ Common toolsets include `web`, `search`, `terminal`, `file`, `browser`, `vision`
|
||||
|
||||
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:
|
||||
|
||||
Reference in New Issue
Block a user