• Introduction to the problem (AI agents accessing secrets)
• The three main features
• Audit log explanation
• Reason-on-access feature
• Configuration options
• What this means for developers

When Your AI Agent Goes Looking for Secrets

Here's something most developers don't think about until it becomes a problem: your AI coding agent is accessing secrets. A lot of them. Every session, multiple times, autonomously running commands, deploying code, and exploring your codebase — all while reaching for the same API keys, database credentials, and tokens you use yourself.

The tricky part? From a security standpoint, those reads look identical whether they came from you or from an AI agent running in the background. That's a visibility gap that many teams don't even know they have.

SecretSpec 0.12 addresses this head-on with three new features designed to make secret access by AI agents transparent, auditable, and accountable.

The Audit Log: Every Access, Every Time

The centerpiece of this release is a new audit logging system that captures every secret read and write operation. When you — or an AI agent — touches a secret, SecretSpec appends an event to a local JSONL log file. No secret values are ever recorded, but the metadata tells a complete story: which secret was accessed, which profile and provider were involved, the outcome, and critically, whether a human or an AI agent initiated the request.

The log lives at ~/.local/state/secretspec/audit.log and is scoped to your user, not the project. This is an important detail: it means a repository you clone can't quietly disable or redirect your audit log. Your security controls stay with you.

To view your audit trail, SecretSpec includes a new secretspec audit command that filters and summarizes the log, or you can pipe raw JSON Lines directly to jq for custom analysis. The log is capped at 1 MiB, serving as a recent record rather than permanent compliance storage — if you need long-term audit history, you'll want to forward these events to a central logging system.

Reason-on-Access: Accountability Built In

This is where things get interesting for teams using AI coding agents. SecretSpec 0.12 introduces a "reason-on-access" requirement: when a coding agent accesses a secret, the request fails unless a human-readable reason is supplied. The reason is free-form text, not a dropdown menu, giving agents flexibility to explain their intent in context while still creating a meaningful audit trail.

How does SecretSpec know an AI agent is making the request? It detects environment variables that tools like Claude Code set, including CLAUDE_CODE, CLAUDE_MAYBE_AGENT, AICI_RUN, and others. When these signals are present, SecretSpec knows to enforce the reason requirement.

For interactive workflows, agents can prompt for a reason using the same TTY prompt the CLI uses. For automated or non-interactive scenarios, the SECRETSPEC_REASON environment variable lets you supply a reason programmatically.

Configuration: Flexibility for Different Workflows

The require_reason setting in your project's secretspec.toml controls when reasons are mandatory:

• require_reason = false — No reason ever required
• require_reason = "agents" — Reason required only when a coding agent is detected (this is the new default)
• require_reason = true — Reason required for all secret access

This graduated approach means you can start with the default behavior and tighten or loosen controls based on your team's security posture and workflow requirements.

What This Means for Your Team

If you're already using SecretSpec inside AI coding agents, version 0.12 introduces a behavior change: secret access will fail until a reason is supplied when an agent is detected. The upgrade path is straightforward — test your workflow with the new version, and if you need to restore the previous behavior, simply add require_reason = false to your [project] table.

For teams that haven't adopted SecretSpec yet, this release makes a compelling case: AI coding agents are becoming a standard part of development workflows, and having visibility into how they access secrets isn't just nice-to-have — it's becoming essential for security-conscious teams.

The audit log gives you visibility. The reason-on-access feature gives you control. Together, they ensure that when your AI agent touches a secret, you know about it, you have context, and you can trace it back if something goes wrong.

That's not security theater — that's security that actually scales with how we build software today.

Ready to upgrade? Check the SecretSpec documentation for full details on the new audit logging system and configuration options.