GitHub issue submission body

Summary

Hermes already has a useful large-tool-result persistence path that spills oversized tool outputs to a sandbox file and replaces the in-context content with a preview and file reference.

I would like to propose hardening that boundary so large tool results are handled consistently before they are written into session logs, transcripts, SQLite/session state, and user-visible previews.

This is mainly a reliability/privacy-hardening improvement rather than a security advisory: the goal is to reduce context/session bloat, avoid huge transcript rows, and prevent sensitive-looking values from being unnecessarily copied into inline previews.

Problem

Large tool outputs can still cause operational issues if raw content reaches persistence/logging paths before being replaced with a persisted-output reference.

Observed failure modes include:

• oversized tool outputs bloating session logs or SQLite-backed state;
• repeated context compression being triggered earlier than necessary;
• browser or transcript views becoming slow or noisy after broad file/search/shell results;
• inline previews retaining sensitive-looking snippets even when the full result is spilled to disk;
• shell heredoc persistence being fragile when tool output contains unusual delimiters or shell-sensitive content.

A synthetic example is enough to reproduce the shape of the issue; no real credentials or private data are needed:

Example synthetic tool output:

CANARY_TOOL_RESULT_123456
line 1 ...
line 2 ...
<repeat until larger than the configured result threshold>

Expected behaviour:

• the full output is written to the sandbox result file;
• the model/session/transcript stores only a bounded replacement block;
• inline preview text is redacted/sanitised using the existing redaction helper where available;
• the same safe representation is used consistently across tool execution, session logging, and state persistence.

Proposed changes

1. Add/confirm one central helper for safe tool-result storage.

   It should accept the raw tool result plus tool name, tool call ID, and active environment, then return either:

   • the original content, if small and safe to keep inline; or
   • a bounded persisted-output replacement with path, byte/character count, and a small preview.

2. Apply that helper before writing tool messages to durable/session persistence paths.

   In particular, tool-role messages should be normalised before being encoded into session state or transcript/session logs.

3. Redact inline previews before storing them.

   If agent.redact.redact_sensitive_text is available, use it on the preview text before building the persisted-output message. If redaction fails, fall back gracefully rather than breaking tool execution.

4. Prefer env.execute(..., stdin_data=content) for sandbox writes.

   This avoids embedding arbitrary tool output into shell heredocs. Keep the heredoc method as a compatibility fallback for older/custom environments that do not support stdin_data.

5. Avoid duplicate persistence passes.

   If a tool result has already been replaced with a persisted-output block, later aggregate budget enforcement should recognise it and avoid spilling the replacement again.

6. Add tests using synthetic canary output.

   Suggested tests:

   • oversized tool result is replaced with a persisted-output block;
   • full output is written to the sandbox path;
   • session/log/state persistence receives the bounded replacement, not the full raw output;
   • preview redaction is applied to obvious synthetic secret-looking strings;
   • stdin_data write path is used where supported and heredoc fallback still works.

Why this helps

This makes Hermes more robust for real operational use where tools can return large file contents, search results, command output, API responses, or structured JSON. It reduces session bloat and keeps persisted history more manageable without removing the model’s ability to inspect the full output when needed.

Related issues

This is related to #14948, but narrower: #14948 discusses progressive compression of older tool results before LLM calls; this issue focuses on the persistence/logging boundary for large current tool results and ensuring the durable representation is bounded and preview-redacted.

Notes

I can provide a PR if maintainers agree with the direction. I have a local patch that applies this pattern around tool execution result handling, session logging/state persistence, preview redaction, and sandbox writes, but I would separate it into small reviewable commits if upstreaming.