# how to keep secrets out of agent-visible context

## TL;DR
Agents do not need to see secret values to use them; they need references. Pass credentials by name or path, let the execution layer resolve them, and redact anything secret-shaped from tool output, logs, and transcripts. Every secret an agent can read is a secret that can end up in a log, a summary, or a pasted debug output.

```text
how to keep secrets out of agent-visible context
```

## Use this when
- An agent's task requires API keys, tokens, or database credentials
- You are reviewing what an agent deployment can actually see
- Tool output or logs might contain credential material
- A workflow passes secrets through prompts or config files
- An agent summarizes or debugs something near secret handling code

## Not for this skill when
- You are choosing a secret manager product (separate evaluation)
- You are scanning git history for committed secrets (see pre-commit skill)
- The question is about encrypting stored data
- No secrets are involved in the workflow at all

## Steps

### 1. Map where secrets currently appear in the agent's view
Search configs, prompts, tool definitions, and recent transcripts for credential values or assignments. You cannot redact what you have not found.

```bash
grep -rin "BEGIN.*PRIVATE\|api[_-]key\|secret[_-]key" [HOME]/... [HOME]/... | head -20
```

Expected: a list of every place a value (not just a name) is visible. Each one is a remediation item in the steps below.

### 2. Pass secrets by reference, never by value
Give the agent the secret's name or vault path and let the runner inject the value at execution time, outside the agent's visible context. The agent asks for "the production database credential" and the layer beneath resolves it.

Expected: prompts, configs, and tool definitions contain references like "DB credential from the vault path for production", never literal values. A fresh transcript review confirms no values leaked.

### 3. Redact secret-shaped output from tools
Wrap tool execution so responses matching credential patterns (long hex or base64 strings, private key blocks, tokens) are masked before the agent sees them. Redact in the transport layer, not by asking the agent to be careful.

Expected: a test tool that echoes a fake credential returns masked output to the agent. If redaction depends on the agent noticing, it will fail.

### 4. Scope the environment the agent inherits
Run the agent with a minimal environment: only the variables the task needs, no wholesale inheritance of the deploy environment. Secret-bearing variables the task does not need should not be present at all.

```bash
env -i PATH=/usr/bin HOME=[HOME]/... your-agent-runner --task TASK_ID
```

Expected: the agent process cannot see variables it was not explicitly given. Check by having it print its environment in a dry run.

### 5. Mask secrets in logs and transcripts
Apply the same redaction to everything persisted: logs, transcripts, error reports, and debug bundles. Assume all of these will be read by people and tools with less clearance than production.

Expected: a grep for known test-secret values across the log directory returns nothing, and the redaction runs on the logging path itself, not as a post-processing hope.

### 6. Give the agent a safe way to ask for help
When the agent genuinely needs a credential it cannot see (debugging auth failures), the workflow should route to a human or a privileged helper rather than coaxing the value into the open. "Paste the key so I can test" must never work.

Expected: the runbook documents the escalation path, and there is no prompt or tool that accepts a raw secret from chat.

### Variant: agents debugging auth failures
Auth debugging without seeing the secret means checking metadata instead: expiry, scope, rotation date, which principal it belongs to. Build tooling that answers those questions so the agent never needs the value.

### Variant: CI pipelines that agents trigger
CI logs are widely visible and long-lived. Ensure jobs the agent triggers mask secrets in output by default and that the agent cannot enable verbose modes that disable masking.

### Variant: screen sharing and demos
Demo transcripts and recorded sessions are another leak path. Use dedicated demo credentials with no production access, and rotate them after the recording.

## Why this happens
Workflows grow by copying: a credential pasted once for a quick test becomes a config value, then a prompt example, then a log line. Each step feels harmless because the audience is "just us", but agent context gets logged, summarized, embedded, and shared more widely than any human's screen. Reference-based access breaks the chain at the first link.

## Edge cases and pitfalls
- Error messages from APIs sometimes echo credentials back; redact at the transport layer to catch these.
- Agents summarizing "what I did" may reconstruct secrets from partial observations; the summary path needs redaction too.
- Support bundles and diagnostics are secret-dense; treat them as sensitive artifacts with limited retention.
- Rotating a secret does not clean old transcripts; assume historical context is compromised and scope new secrets accordingly.
- Test and staging secrets deserve the same handling; "it is only staging" is how real credentials end up in real logs.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nuIjPa6v2v6190AVos5bKA