vault: session notes 2026-07-12

convention/secrets-out-of-agent-transcripts.md

@@ -0,0 +1,46 @@
+---
+summary: How to keep secret values out of AI agent session transcripts — use shell command substitution for consumption, and never echo secrets in agent-driven CLI success output.
+tags:
+  - type/convention
+  - convention/agent-secret-hygiene
+  - domain/agent-security
+  - tool/credvault
+scope: global
+type: convention
+source: credvault envelope-leak incident, 2026-07-12
+date: 2026-07-12
+last_updated: 2026-07-12
+---
+
+# Secrets out of agent transcripts
+
+## The rule
+
+In AI-agent sessions, **the transcript is the leak surface, not git**. Anything printed to
+stdout becomes durable text: session logs, memory summaries, handoff documents, cached
+context. A gitignored file does not protect a secret the agent `cat`s; a vault does not
+protect a secret the CLI echoes back.
+
+Two patterns that generalize to any credential tooling an agent drives:
+
+1. **Consume via shell command substitution.** `ENV_VAR=$(secret-fetch-cmd) target-cmd`
+   never exposes the value — the transcript records the command *text*, not the substituted
+   output. This is the default way an agent should use a credential in any command.
+2. **Agent-driven CLIs must not echo secrets in success envelopes.** Return `null`/omit the
+   secret by default (the caller supplied it or will fetch it deliberately); offer an
+   explicit opt-in flag (e.g. `--show-secret`) for the rare case a human wants to see it.
+
+Corollary: a fancier `exec`-style env-injection wrapper or local cache is usually
+overengineering — command substitution gets ~90% of the value with zero new surface area.
+
+## Why
+
+Discovered when credvault's `ensure` success envelope echoed a caller-supplied bot password
+back into a session transcript. Fixed 2026-07-12: envelope nulling + `--show-secret`
+(credvault eb51e4c), consumption pattern tracked in credvault issue #11.
+
+## How to apply
+
+- When an agent needs a credential in a command: inline it via `$( … )`, never fetch-then-paste.
+- When building or reviewing any CLI agents will drive: audit every success path for secret
+  echo; default to redaction with an opt-in display flag.