Your agent never holds the key

01Why an agent and a .env file don’t mix

A .env file is the correct secret format for a person editing by hand. It is the incorrect format for a coding agent. The file sits in plaintext on disk. An agent's core function is to read files and echo back what it read. No bad intent is required. The leak is the agent behaving as designed.

Three vectors, all real, all ordinary:

I retired my plaintext .env for exactly this reason. Deleting the file was the fix, not being more careful with it.

02The doctrine

Four rules. Everything else on this page is mechanism underneath them.

The two-tier split

The service-account credential that reads the everyday vault cannot read the dangerous one. That’s the whole privilege split: structural, not a permission the agent could reason its way around.

03Three things worth stealing

These are sketches; adapt the vault CLI and file paths to your own setup. The shape is the point.

A resolver, fall-through not if/elif

The order matters: explicit env wins (someone set it on purpose), then the vault, then an offline fallback if you want to survive a vault outage too. It has to be fall-through: if the vault call errors (not “is absent,” but actually fails), an elif would already have committed to that branch and returned nothing. Fall-through is what lets an outage still reach the fallback.

#!/usr/bin/env bash
# secrets-loader.sh: sourced fragment, single entry point.
# Resolution order: explicit env -> vault CLI -> offline fallback.
# Falls THROUGH on failure, never if/elif.

resolve_secrets() {
  # 1. already exported? leave it alone.
  [ -n "$FOO_API_KEY" ] && return 0

  # 2. vault CLI, bounded so a headless box can't hang forever
  if command -v vault-cli >/dev/null 2>&1; then
    if out=$(timeout 8 vault-cli export --profile everyday 2>/dev/null) \
        && [ -n "$out" ]; then
      eval "$out"
      return 0
    fi
  fi

  # 3. offline fallback: encrypted at rest, decrypted with THIS box's
  #    own private key, never a key shared across boxes.
  if [ -f "$HOME/.secrets/offline.vault" ]; then
    eval "$(age -d -i "$HOME/.config/age/keys.txt" "$HOME/.secrets/offline.vault")"
  fi
}

resolve_secrets

The dangerous-tier reader is deliberately smaller: one key at a time, interactive only, and it refuses outright when nothing can approve it.

# dangerous-read.sh: ONE key, interactive only.
# Headless callers fail closed by design.
read_dangerous_key() {
  local name="$1"
  if [ ! -t 0 ] && [ -z "$SSH_TTY" ]; then
    echo "refusing: no interactive session to approve $name" >&2
    return 1
  fi
  vault-cli read --profile dangerous --item "$name"   # prompts for a tap
}

Verify without echo

Exactly three checks on a secret-bearing variable are safe: whether it is set, its length, and whether its hash matches. Everything else leaks the secret. The worst offenders are the checks that look like safety measures.

# Presence:
[ -n "$FOO_API_KEY" ] && echo "FOO_API_KEY: set" || echo "FOO_API_KEY: MISSING"

# Length (catches "empty" and "obviously truncated" without printing it):
echo "len=${#FOO_API_KEY}"

# Identity without value (compare across machines, never print it):
printf '%s' "$FOO_API_KEY" | shasum -a 256 | cut -c1-16

# BANNED, every one of these prints the real value:
#   echo "${FOO_API_KEY:-missing}"   # prints the VALUE when it IS set
#   echo "${FOO_API_KEY:0:6}..."     # a real prefix is still a leak
#   echo "$FOO_API_KEY"              # obviously

That first banned line is the one that bites people. ${VAR:-fallback} reads as “show a safe placeholder if it’s missing,” but it does the opposite: it returns the fallback only when the variable is unset, and the real value the moment it’s set, which is precisely the case you were trying to guard.

A minimal pre-commit secrets scrub

A PreToolUse hook on Bash, matched to git commit, that greps the staged diff for secret-shaped strings before the commit is allowed to happen.

#!/usr/bin/env bash
# secrets-commit-guard.sh: PreToolUse hook, matcher: Bash.
# Blocks `git commit` if the staged diff has a secret-shaped string.

INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
echo "$CMD" | grep -qE '^git commit' || exit 0

LEAK=$(git diff --cached | grep -inE \
  '(API_?KEY|SECRET|TOKEN|PASSWORD)[[:space:]]*[:=][[:space:]]*["'"'"']?[A-Za-z0-9_-]{16,}')

[ -z "$LEAK" ] && exit 0

cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKED: staged diff has a secret-shaped string. Move the value into your password manager, reference it by env-var name, and re-stage. False positive? add the path to the scrub allowlist."
  }
}
EOF

My real version of this hook also covers the everyday-Bash case. It denies commands that would print a secret-shaped variable, like echo $FOO_API_KEY or printenv FOO_API_KEY. A command that reads a secrets file (cat .env) gets a confirmation prompt instead of a flat denial; dumping the whole environment (a bare env) is denied outright. Same mechanism as the sketch: parse the tool call, pattern-match the risk, then deny or ask, and name the safe alternative in the reason.

04Craft rules

05For the Claude that just got pointed here

If a human handed you this URL and said “do this for our project,” here’s your plan. (Humans: this section exists so you can paste the link and skip explaining it.)

The hook mechanics (how to write and register a PreToolUse guard, the deny-message and bypass conventions, smoke-testing before you trust one) are covered in a sibling primer: Physics, not pleas. Read it before writing the guard in step 5.

06Receipts: what this looks like at scale

Genericized, but every row is a real pattern running in kaibot today.

The .env-is-dead call is the one that mattered most. Every other rule on this page exists to keep that true under pressure: a new box, a headless cron, a vault outage, an agent that just wants to check if a key is set.