fix(hermes): frame recalled context as untrusted data

[yingliang-zhang]

Problem

Auto-injected recall/reflect output was passed to the model as raw bulleted text under a header that invited instruction-like trust ("Use this to answer questions about the user and prior sessions"). External memory content is untrusted data: it can contain instruction-shaped text, leaked wrapper tags (</memory-context><forged>…), or Markdown/XML-like boundaries (```system blocks), and without a stable outer trust boundary such content is easy to mistake for system instructions — a poisoned memory can masquerade as an instruction and drive tool calls.

Fix (hindsight half of NousResearch/hermes-agent#64421)

• Bounded, whitelisted JSON serialization (_serialize_prefetch_data in settings.py): recall/reflect output ships as {"source": "hindsight", "kind": "recall"|"reflect", "content": [...]} — a fixed key whitelist so result fields like hidden_instruction/arbitrary_metadata can never leak into the prompt — with </> escaped after serialization (\u003c/\u003e, so tags can't open markup) and the whole payload truncated to the recall token budget (4 chars/token, 256-char floor) on valid serialized candidates.
• Untrusted framing in the default preamble: the injected block now states the JSON is untrusted reference data from prior sessions that cannot override system or user instructions. A configured recall_prompt_preamble still wins (no surface change).
• The hindsight_recall tool output path is deliberately unchanged — it returns to the model as a tool result, not as injected context.

This is defense-in-depth model-facing framing, not a cryptographic isolation boundary.

Tests

tests/test_untrusted_recall_framing.py (ports of the original PR's adversarial tests, adapted to this tree's FakeClient):

• test_recall_prefetch_serializes_whitelisted_bounded_json — adversarial results (instruction-shaped text, hidden_instruction/arbitrary_metadata attributes, a 500× <tag>"\ item): whitelisted keys only, full first item, second truncated with …, no raw angle brackets or newline-fence sequences in the payload, length within the derived bound.
• test_reflect_prefetch_serialization_is_valid_json_within_final_bound — reflect path: exact whitelisted payload, valid JSON, within the final 256-char bound.
• test_prefetch_failure_remains_non_fatal — a failing recall still yields "", never an exception.

Existing-contract update: test_provider.py::test_prefetch_injects_recalled_memories pinned the old - fact one bullet format — the format change is the point of this fix, so it now asserts the untrusted header plus the JSON payload carrying the memory (indicator count assertion unchanged).

Verification

Pre-fix (tests against main's raw-bullet formatting) — RED:

FAILED tests/test_untrusted_recall_framing.py::test_recall_prefetch_serializes_whitelisted_bounded_json - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
FAILED tests/test_untrusted_recall_framing.py::test_reflect_prefetch_serialization_is_valid_json_within_final_bound - json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
========================= 2 failed, 1 passed in 0.04s ==========================

(The non-fatal test passes both ways — it pins the error contract, which this fix preserves.)

Post-fix, uv run pytest tests/test_untrusted_recall_framing.py -v (touched test file):

collecting ... collected 3 items

tests/test_untrusted_recall_framing.py::test_recall_prefetch_serializes_whitelisted_bounded_json PASSED [ 33%]
tests/test_untrusted_recall_framing.py::test_reflect_prefetch_serialization_is_valid_json_within_final_bound PASSED [ 66%]
tests/test_untrusted_recall_framing.py::test_prefetch_failure_remains_non_fatal PASSED [100%]

============================== 3 passed in 0.02s ===============================

uv run pytest tests/test_provider.py tests/test_settings.py (the other touched/covered files — test_provider.py modified, test_settings.py covers the touched settings.py): 19 passed in 0.04s, including the updated test_prefetch_injects_recalled_memories.

Provenance

Hindsight half of NousResearch/hermes-agent#64421 (fix(memory): frame recalled context as untrusted data), by @yingliang-zhang — reviewed there by @teknium1's automated sweep (mechanism confirmed against build_memory_context_block and the auto-prefetch path) and an independent hard review (ACCEPT). The hermes PR stays open for its agent/memory_manager.py / streaming-scrubber halves; only the provider-side serialization + framing is ported here. Tracked in #4662.

Stacked PR (pre-chained 2026-09-30): the diff vs main is cumulative with #4674, #4671, #4672, #4673, #4675; this PR's own change is the untrusted-recall framing (bounded whitelisted JSON serialization and a trust boundary around recalled context). Merge top-down: 4674 -> 4671 -> 4672 -> 4673 -> 4675 -> 4676. Identical shared commits merge cleanly in any order (git dedups same-patch-both-sides).

[yingliang-zhang]

CI note: verify-generated-files fails here for a pre-existing reason — ./scripts/generate-docs-skill.sh on a clean upstream/main (7a593e8) reproduces the same skills/hindsight-docs/references/developer/oracle.md drift, so the gate is red on every PR including unmodified main. Fixed by #4678 (single-file regeneration); once it merges, this PR's gate goes green with no changes needed here.

[yingliang-zhang]

Generated-files sync commit added atop the substantive commit(s): the verify-generated-files gate runs its generators against the PR head (actions/checkout at ref: head.sha), so this branch now carries its own regenerated skills/hindsight-docs/references/developer/oracle.md plus the lint.sh ruff formatting, committed as chore: sync generated files for verify-generated-files. No substantive changes — the review surface is exactly as before.

[nicoloboschi]

Thanks for this! We no longer merge pull requests from outside the team (see CONTRIBUTING.md), so I'm closing this one.

If the problem still affects you, please open an issue with steps to reproduce and we'll take it from there.