Parent Issue

Sub-issue of #410 (Secure Secrets Management Tool). This is Phase 1 of the phased rollout.

Scope

A new agent-facing secrets tool that provides secure secret lifecycle management, plus hardening of existing redaction coverage.

1. New secrets tool (tools/secrets_tool.py)

Key security property: secret values never enter LLM context. The request action handles the entire input flow internally and only returns {"stored": true} to the agent.

2. Platform-specific secure ingestion

• CLI: getpass.getpass() — input not echoed, not in readline history
• Telegram: DM the user, accept reply, immediately delete the message containing the key
• Discord: Same DM+delete pattern
• Other platforms: Best-effort (WhatsApp has limited deletion support)

3. Skill requires_secrets frontmatter

Skills can declare required secrets in SKILL.md:

---
name: twilio
requires_secrets:
  - key: TWILIO_ACCOUNT_SID
    description: "Twilio Account SID"
    instructions: "Find at https://console.twilio.com/"
  - key: TWILIO_AUTH_TOKEN
    description: "Twilio Auth Token"
---

When loading a skill, the agent checks for missing secrets and prompts via secrets(action="request").

4. Redaction hardening (relates to #363)

• Apply redact_sensitive_text() to read_file, search_files, patch, and execute_code tool outputs
• Expand agent/redact.py patterns: add Twilio SIDs/tokens, AWS AKIA*, Stripe keys, JWTs, PEM private key blocks
• File permissions: chmod 600 on ~/.hermes/.env

5. Storage

Phase 1 continues using ~/.hermes/.env for storage. Encrypted storage comes in Phase 3.

Files to Create/Modify

• New: tools/secrets_tool.py (~400 lines)
• New: tests/tools/test_secrets_tool.py
• Modify: agent/redact.py — expanded patterns
• Modify: tools/file_tools.py — apply redaction to read/search output
• Modify: tools/code_execution_tool.py — apply redaction to script output
• Modify: model_tools.py — add to discovery
• Modify: toolsets.py — add to _HERMES_CORE_TOOLS
• Modify: agent/skill_commands.py — parse requires_secrets frontmatter

Acceptance Criteria

• secrets(action="list") returns secret names, never values
• secrets(action="request") uses getpass() in CLI, DM+delete in gateway
• Secret values never appear in conversation history or LLM context
• requires_secrets parsed from skill frontmatter
• read_file / search_files / execute_code output is redacted
• New redaction patterns cover Twilio, AWS, Stripe, JWT, PEM
• Tests cover all tool actions + edge cases

References

• Feature: Secure Secrets Management Tool — API Key Ingestion, Scoped Access, Redaction, and Skill Requirements #410 — Parent umbrella issue
• Security: File Tool Output Redaction Gap — Secrets Exposed via read_file but Masked via Terminal #363 — File tool output redaction gap
• Feature: Agent-Vault Skill — Placeholder-Based Secret Management for Config Files #364 — Agent-vault placeholder-based secret management
• PR feat(secrets): Secrets Management Tool (Phase 1) #3245 — Previous partial implementation by @zaycruz (closed, concepts reusable)