feat(hindsight): add enable_retain_tool config to gate hindsight_retain exposure

[kumaxs]

Summary

Add enable_retain_tool config option to the Hindsight memory plugin, giving users control over whether the hindsight_retain tool is exposed to the agent.

Follow-up to #55819 (closed as implemented_on_main), which identified the destructive risk of hindsight_retain but was resolved upstream by isolating background review forks (skip_memory=True). That fix prevents background review from calling memory tools, but the main conversation agent still has access to hindsight_retain — and if the model calls it without understanding the tool's semantics, it will overwrite the entire session document, silently destroying all auto-retained memories.

Problem

hindsight_retain is a full-overwrite operation, not an incremental append. When the agent calls it:

1. The existing session document in Hindsight is completely replaced with whatever content the model provides.
2. All previous auto-retained turns are irretrievably lost.
3. The tool description (RETAIN_SCHEMA) reads "Store important information" — it does NOT disclose the destructive nature.

Most users rely on auto_retain + auto_recall for memory — these work internally without the model ever touching the hindsight_retain tool. Exposing a destructive manual write tool to the agent is an unnecessary risk vector for those users.

Changes

Single file: plugins/memory/hindsight/__init__.py (+7 / −1 lines)

1. Schema — new config key enable_retain_tool (default: true, backward-compatible)
2. Config parsing — reads enable_retain_tool from config, falling back to True
3. get_tool_schemas() — filters out hindsight_retain when enable_retain_tool is false

Config in hindsight/config.json:

{
  "enable_retain_tool": false
}

When disabled:

• The agent cannot see or call hindsight_retain — it's removed from the tool list
• auto_retain continues to work internally and is completely unaffected
• hindsight_recall and hindsight_reflect (read-only tools) remain exposed

Why this matters

Background review isolation (#27190) is a good fix for one call path, but it doesn't address the broader risk: any agent turn can invoke hindsight_retain. This PR gives users a simple config toggle to eliminate that risk entirely, without sacrificing the automatic memory functionality they already rely on.

[teknium1]

Thanks for the focused Hindsight safety proposal.

Automated hermes-sweeper review is closing this under the standing tools-disabled policy: Hermes does not add configuration paths that selectively remove tool schemas from the model. Use the existing memory_mode: "context" option when the desired setup is automatic recall/retention with no Hindsight tools exposed.

• plugins/memory/hindsight/__init__.py:1698-1701 already implements context mode by returning no Hindsight tool schemas; plugins/memory/hindsight/README.md:108-111 documents it as automatic injection only.
• The claimed destructive path is not present as described on current main: hindsight_retain calls aretain_batch without a document_id at plugins/memory/hindsight/__init__.py:1710-1722, while automatic session retention supplies its document target through sync_turn().
• The PR at ce9b6048373d751e4416488d973de96929241531 would instead add an opt-in per-tool schema exclusion.

The existing context mode preserves auto_retain while avoiding all manual Hindsight tool exposure.

---

Closed as not-planned per standing maintainer policy (tools-disabled). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.