Most secret leakage in Claude Code stems from misunderstanding what environment data subagents inherit. The default behavior is not "pass nothing" or "pass everything." It is a three-layer model where shell environment, MCP server credentials, and per-task scope each follow different inheritance rules. Teams that treat subagents like trusted workers leak database passwords into test fixtures and API tokens into debug logs. The failure mode here is subtle but expensive. The problem looks like this: you set `DATABASE_URL` in your shell, spawn a subagent to run tests, and the subagent's test harness writes the production connection string to a snapshot file that gets committed. Or you configure an MCP server with admin credentials, delegate a refactoring task to a subagent, and the subagent's context includes the full credential set even though it only needs read access to a documentation index. ```mermaid flowchart LR A("Parent spawns subagent") --> B("Subagent inherits full shell env") B --> C("Production DATABASE_URL in test snapshot") style C stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 ``` The solution is to treat subagents like untrusted workers with explicit allow-lists. You scope environment variables per subagent using process-level isolation, configure MCP servers with per-task credential sets, and audit what each subagent can actually see before you deploy. The result is that a code reviewer subagent cannot read your Stripe secret key and a test fixer cannot write to your production database. ```mermaid flowchart LR A("Parent spawns subagent") --> B("Subagent receives explicit safe env") B --> C("Test runs with isolated test database") style C stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` This post shows the exact patterns for implementing that isolation in production TypeScript codebases. ## Key Takeaways - Subagents inherit the parent's shell environment by default unless you explicitly scope process-level environment variables. - MCP server credentials live in a separate boundary and must be configured per-task to prevent subagents from accessing resources they do not need. - The three-layer model (shell env, MCP credentials, per-task scope) determines what data crosses isolation boundaries. - Production patterns require vault integration with token injection scoped to subagent lifetime, not static environment files. - Auditing what each subagent can see requires runtime inspection tools that capture the effective environment, not just configuration files. ## What Gets Passed to Subagents by Default (and What Doesn't) The default behavior is that subagents inherit the parent's shell environment verbatim. If you set `OPENAI_API_KEY` in your `.zshrc` and spawn a subagent to run linting, the subagent's process sees that key. This is not a bug. It is how Unix process forking works. The distinction is critical. What does NOT get passed: MCP server credentials are scoped to the server configuration, not the shell. If you register an MCP server with Anthropic's credential provider, the subagent does not automatically inherit those credentials unless you explicitly attach the server to the subagent's task context. The implication here is that you have two separate surfaces to secure. The third layer is per-task scope. When you spawn a subagent with a specific instruction set, you can pass an environment map that overrides or supplements the inherited shell environment. This layer is where you implement isolation. ```mermaid flowchart TD A("Parent process starts") --> B("Shell env loaded") B --> C("MCP servers registered") C --> D("Subagent spawned") D --> E("Inherits shell env") D --> F("Receives per-task overrides") E --> G("Effective environment") F --> G style G stroke:#7c9cf0,fill:#142544,color:#eaf2ff ``` Developers often assume that spawning a subagent creates a clean environment. It does not. The subagent starts with whatever the parent had and then applies task-specific overrides. If you never specify overrides, the subagent runs with full access to every secret in the parent's shell. ## Environment Variable Inheritance: The Three-Layer Model The three-layer model describes how environment data flows from configuration to runtime. Understanding this model prevents the common mistake of setting a secret in one layer and expecting isolation in another. **Layer one** is the shell environment. This includes everything in `.bashrc`, `.zshrc`, exported variables, and the output of `printenv`. When you run `claude-code` from a terminal, every variable in that shell becomes part of the parent process environment. Subagents forked from the parent inherit this layer. **Layer two** is MCP server configuration. Servers are registered with credential sets stored outside the shell environment. A server configured with a Notion API token does not expose that token to subagents through the shell. The token lives in the MCP registry. Subagents only access the server if you explicitly attach it to their task context. **Layer three** is per-task overrides. When you spawn a subagent, you pass an environment map that can add new variables, override inherited ones, or unset variables from the shell. This layer has the highest precedence. It is where you implement principle-of-least-privilege. ```mermaid flowchart TD A("Shell environment layer") --> D("Parent process starts") B("MCP credential registry") --> D D --> E("Subagent spawns with task context") C("Per-task override map") --> E E --> F("Layer 3 overrides layer 1") E --> G("Layer 2 only if server attached") F --> H("Effective environment") G --> H style H stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px ``` The failure mode happens when teams set secrets in layer one, assume layer three will block them, and never audit what the subagent actually sees. The result is that a subagent meant to run tests in isolation connects to production because `DATABASE_URL` came from the shell and nothing in layer three overrode it. ## Preventing Secret Leakage: Practical Patterns for Per-Subagent Scoping The pattern that prevents leakage is to define an allow-list of environment variables per subagent type and block everything else. A code reviewer subagent gets `NODE_ENV`, `CI`, and `LOG_LEVEL`. It does not get `DATABASE_URL`, `STRIPE_SECRET_KEY`, or `OPENAI_API_KEY`. This approach inverts the default behavior from "inherit everything unless blocked" to "inherit nothing unless allowed." Here is how to implement it in TypeScript: ```typescript type SubagentRole = 'code-reviewer' | 'test-fixer' | 'doc-generator'; const allowedEnvByRole: Record = { 'code-reviewer': ['NODE_ENV', 'CI', 'LOG_LEVEL'], 'test-fixer': ['NODE_ENV', 'CI', 'TEST_DATABASE_URL', 'LOG_LEVEL'], 'doc-generator': ['NODE_ENV', 'OUTPUT_DIR'], }; function buildScopedEnv(role: SubagentRole): Record { const allowed = allowedEnvByRole[role]; const scopedEnv: Record = {}; for (const key of allowed) { const value = process.env[key]; if (value !== undefined) { scopedEnv[key] = value; } } // Explicitly unset dangerous variables scopedEnv.DATABASE_URL = ''; scopedEnv.STRIPE_SECRET_KEY = ''; scopedEnv.OPENAI_API_KEY = ''; return scopedEnv; } async function spawnSubagent(role: SubagentRole, task: string) { const env = buildScopedEnv(role); // Spawn subagent with scoped environment const result = await execSubagent({ task, env, inheritParentEnv: false, // Critical: do not inherit }); return result; } ``` The `inheritParentEnv: false` flag is critical. Without it, the scoped environment gets merged with the parent's shell environment instead of replacing it. The subagent ends up with both the allow-listed variables and the blocked secrets. The explicit unset step (`DATABASE_URL = ''`) defends against configuration drift. If a team member adds `DATABASE_URL` to the allow-list for `test-fixer`, the unset step still prevents it from reaching the subagent until the unset line is also removed. This creates a two-gate requirement for exposing secrets. ## MCP Server Credentials vs Shell Environment: Different Security Boundaries MCP server credentials and shell environment variables are two separate attack surfaces. A subagent that cannot access your shell's `OPENAI_API_KEY` can still access an MCP server configured with that key if the server is attached to the subagent's task context. The boundary difference is that shell environment flows through process inheritance. MCP credentials flow through explicit server attachment. You cannot block MCP credentials by unsetting environment variables. You block them by not attaching the server to the subagent's task. ```mermaid flowchart LR subgraph Parent["Parent process"] A("Shell env with secrets") B("MCP server registry") end subgraph Subagent["Subagent process"] C("Inherits shell or receives overrides") D("Server attached via task context") end A --> C B --> D style C stroke:#fbbf24,fill:#3a2f0b,color:#fef3c7 style D stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` The practical implication is that you need two separate scoping mechanisms. For shell secrets, use the allow-list pattern from the previous section. For MCP servers, use per-task server attachment with credential rotation. Here is how to scope MCP server access per subagent: ```typescript type MCPServerConfig = { serverId: string; capabilities: string[]; credentialTTL: number; // seconds }; const serverConfigByRole: Record = { 'code-reviewer': [ { serverId: 'github-read-only', capabilities: ['read'], credentialTTL: 600 }, ], 'test-fixer': [ { serverId: 'test-db', capabilities: ['read', 'write'], credentialTTL: 300 }, ], 'doc-generator': [ { serverId: 'notion-docs', capabilities: ['read'], credentialTTL: 1200 }, ], }; async function attachServersToSubagent( role: SubagentRole, subagentId: string ): Promise { const configs = serverConfigByRole[role]; for (const config of configs) { // Generate short-lived token scoped to subagent const token = await generateScopedToken({ serverId: config.serverId, subagentId, capabilities: config.capabilities, ttl: config.credentialTTL, }); await attachServer(subagentId, config.serverId, token); } } ``` The `credentialTTL` field ensures that even if a subagent leaks a token, the token expires within minutes. The `capabilities` array restricts what the subagent can do even if it has a valid token. A `code-reviewer` subagent with a read-only GitHub token cannot push commits. ## Production Pattern: Vault Integration with Subagent-Scoped Token Injection The production pattern for managing secrets across subagents is to integrate with a vault (HashiCorp Vault, AWS Secrets Manager, or Google Secret Manager) and inject short-lived tokens into the subagent's environment at spawn time. This approach eliminates static secrets in configuration files and ensures that each subagent gets exactly the credentials it needs for its lifetime. The flow works like this: when you spawn a subagent, the orchestration layer requests a token from the vault scoped to the subagent's role and lifetime. The vault returns a token that expires in 5-10 minutes. The orchestration layer injects that token into the subagent's environment as a new variable (`SCOPED_DB_TOKEN` instead of `DATABASE_URL`). The subagent uses the scoped token for its work. When the subagent terminates, the token is already expired or close to it. ```mermaid flowchart LR A("Orchestrator spawns subagent") --> B("Request scoped token from vault") B --> C("Vault generates 5-min token") C --> D("Inject token into subagent env") D --> E("Subagent uses scoped credentials") E --> F("Token expires after task completes") style E stroke:#c084fc,fill:#3b0764,color:#f3e8ff,stroke-width:4px style F stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Here is how to implement vault-scoped token injection in TypeScript: ```typescript import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager'; type VaultConfig = { secretName: string; scopeToSubagent: boolean; ttl: number; }; const vaultConfigByRole: Record = { 'test-fixer': [ { secretName: 'test-db-credentials', scopeToSubagent: true, ttl: 300 }, ], 'code-reviewer': [], 'doc-generator': [ { secretName: 'notion-api-token', scopeToSubagent: true, ttl: 600 }, ], }; async function injectVaultSecrets( role: SubagentRole, subagentId: string, env: Record ): Promise> { const configs = vaultConfigByRole[role]; const client = new SecretsManagerClient({ region: 'us-east-1' }); for (const config of configs) { if (!config.scopeToSubagent) { continue; // Skip non-scoped secrets } const command = new GetSecretValueCommand({ SecretId: config.secretName, VersionStage: 'AWSCURRENT', }); const response = await client.send(command); const secretValue = response.SecretString; if (!secretValue) { throw new Error(`Secret ${config.secretName} returned empty value`); } // Parse secret and inject into env const parsed = JSON.parse(secretValue); const envKey = `SCOPED_${config.secretName.toUpperCase().replace(/-/g, '_')}`; env[envKey] = parsed.token || parsed.value; // Schedule token revocation after TTL setTimeout(async () => { await revokeToken(config.secretName, subagentId); }, config.ttl * 1000); } return env; } async function spawnSubagentWithVault(role: SubagentRole, task: string) { const subagentId = generateSubagentId(); let env = buildScopedEnv(role); // Inject vault secrets env = await injectVaultSecrets(role, subagentId, env); const result = await execSubagent({ task, env, inheritParentEnv: false, }); return result; } ``` The `SCOPED_` prefix in the environment variable name makes it clear that this is a short-lived credential, not a long-lived secret. The `setTimeout` call schedules token revocation, but the real protection is the vault's TTL enforcement. Even if the `setTimeout` fails, the token expires. This matters because static secrets in `.env` files or shell environments never expire. A leaked static secret stays valid until someone manually rotates it. A vault-scoped token leaks for 5 minutes and then becomes useless. ## Testing Your Isolation: How to Audit What Each Subagent Can Actually See The only way to know what a subagent can see is to audit it at runtime. Configuration files and allow-lists tell you what *should* happen. Runtime inspection tells you what *does* happen. The gap between the two is where secrets leak. The pattern for auditing is to inject a diagnostic task into each subagent role during development that logs the effective environment and MCP server attachments. You run this diagnostic in a staging environment, capture the output, and verify that no unexpected secrets appear. ```mermaid flowchart LR A("Spawn subagent in staging") --> B("Inject diagnostic task") B --> C("Subagent logs effective env") C --> D("Audit logs for unexpected secrets") D --> E("Verify isolation boundaries") style E stroke:#34d399,fill:#0b3b2e,color:#d1fae5 ``` Here is how to implement runtime auditing in TypeScript: ```typescript type AuditReport = { subagentId: string; role: SubagentRole; effectiveEnv: Record; attachedServers: string[]; unexpectedSecrets: string[]; }; const dangerousEnvKeys = [ 'DATABASE_URL', 'STRIPE_SECRET_KEY', 'OPENAI_API_KEY', 'AWS_SECRET_ACCESS_KEY', ]; async function auditSubagentIsolation( role: SubagentRole ): Promise { const subagentId = generateSubagentId(); let env = buildScopedEnv(role); env = await injectVaultSecrets(role, subagentId, env); // Spawn subagent with diagnostic task const result = await execSubagent({ task: 'Print effective environment and attached servers', env, inheritParentEnv: false, captureEnv: true, }); const effectiveEnv = result.capturedEnv; const attachedServers = result.attachedServers; // Check for dangerous keys const unexpectedSecrets = dangerousEnvKeys.filter( (key) => effectiveEnv[key] && effectiveEnv[key] !== '' ); const report: AuditReport = { subagentId, role, effectiveEnv, attachedServers, unexpectedSecrets, }; if (unexpectedSecrets.length > 0) { console.error(`Isolation violation in ${role}:`, unexpectedSecrets); } return report; } async function runIsolationAudit() { const roles: SubagentRole[] = ['code-reviewer', 'test-fixer', 'doc-generator']; const reports: AuditReport[] = []; for (const role of roles) { const report = await auditSubagentIsolation(role); reports.push(report); } // Generate audit summary const violations = reports.filter((r) => r.unexpectedSecrets.length > 0); if (violations.length > 0) { throw new Error(`Isolation audit failed with ${violations.length} violations`); } console.log('All subagent roles passed isolation audit'); return reports; } ``` The `captureEnv: true` flag tells the subagent executor to return the effective environment instead of just the task output. This requires support from the underlying subagent runtime, but most production runtimes expose this capability through debug or introspection modes. The audit should run in CI before deployment. If a developer adds a dangerous secret to an allow-list or misconfigures vault integration, the audit catches it before production. The failure mode without auditing is that you discover the leak when a customer reports seeing production database credentials in a test output file. ## Frequently Asked Questions ### Do subagents inherit environment variables from the parent process by default? Yes. Subagents inherit the parent's shell environment unless you explicitly disable inheritance with a flag like `inheritParentEnv: false`. This means any secret in your shell is visible to all subagents unless you scope the environment per subagent. ### What is the difference between shell environment secrets and MCP server credentials? Shell environment secrets flow through process inheritance. MCP server credentials flow through explicit server attachment to the subagent's task context. You must scope both separately because blocking one does not block the other. ### How long should vault-scoped tokens live for subagents? 5-10 minutes is the practical range. Shorter TTLs reduce leak exposure but increase vault request volume. Longer TTLs simplify debugging but increase the window where a leaked token stays valid. Measure your subagent task durations and set TTL to 2x the 95th percentile. ### Can I audit subagent isolation in production without impacting performance? No. Runtime auditing requires capturing and logging the effective environment, which adds latency and log volume. Run audits in staging or as a pre-deployment gate. Use static analysis and configuration validation in production to verify isolation without runtime overhead. ### What happens if a subagent tries to access an MCP server it is not authorized for? The server attachment fails and the subagent receives an error. The subagent cannot proceed with the task unless you handle the error and provide an alternative. This is correct behavior. Silent failures would allow subagents to work without credentials, which hides misconfigurations. ## Conclusion: Treating Subagents Like Untrusted Workers The core principle for securing environment variables and secrets in Claude Code is to treat subagents like untrusted workers. The default behavior of inheriting the parent's shell environment is a convenience for local development, not a safe pattern for production. Teams that deploy subagents without explicit scoping leak database credentials, API tokens, and vault keys into logs and artifacts. The three-layer model (shell environment, MCP credentials, per-task scope) gives you the conceptual framework for implementing isolation. The allow-list pattern, vault integration, and runtime auditing give you the practical tools. Apply these in production and the difference will be immediate: subagents that can only see the secrets they need, tokens that expire minutes after tasks complete, and audit trails that catch misconfigurations before they reach production. That covers the essential patterns for managing environment variables and secrets across Claude Code subagents. The pattern is simple: scope everything, inject dynamically, audit constantly.

Posts tagged “secrets-management”

Claude Code Environment Variables and Secrets in 2026: What Gets Passed to Subagents and What Does Not