Locking Down Subagent Tools and Environment Variables in 2.1.313

0:00 Morning, everyone. This one's brought to you by Jellypod AI, and it's a good one if you've ever watched a subagent wander off and start poking at files it had no business touching. Last time we covered custom model deployment names and subagent compaction settings in 2.1.312. Version 2.1.313 keeps going on subagents, but this time it's about what they can touch and what they can see.

0:28 Right. Two changes. First, subagent definitions now take an explicit tools list, plus a disallowedTools list. That lives in your agent definitions under the claude agents folder, or in inline agent registrations. Second, for headless and CI runs, there's a new environment variable, CLAUDE_CODE_SUBAGENT_ENV_ALLOWLIST, and a matching flag called env passthrough.

0:54 That one controls which environment variables reach worker agents. So here's why that matters. Before this, subagents inherited the native tools and the MCP tools pretty broadly. If you wanted a reviewer that only reads code, you were leaning on a system prompt saying please don't edit anything, or on a pile of manual permission rules.

1:17 That's a bit like asking a dog nicely not to get on the couch. Now you can just take the couch away. And the example from the release is a good template. You make a reviewer agent in its own JSON file. Pick a small, cheap model, a Haiku model works fine for this. Then set tools to Read, Grep, and Glob.

1:36 And set disallowedTools to Bash, Write, and Edit. That agent can look at your code and search it, and that's it. It can't run a shell command, and it can't modify a file. The behavior when it tries is worth knowing. If that subagent reaches for a disallowed tool, it fails right away with an error local to that agent.

1:57 You don't get a permission prompt popping up in your main terminal. So when you've got a few subagents running in parallel under an orchestrator, one of them hitting a wall doesn't stop you mid-flow. There are two practical wins here. One is blast radius. If a worker agent gets confused, or picks up something odd from a file it read, a read only toolset means it can't run arbitrary Bash or make destructive changes.

2:22 The other is tokens. Filtering out tool schemas a subagent never uses cuts the system prompt overhead for that subagent. The notes say by thousands of tokens per turn. That should mean faster subagent startup and a lower API bill, especially if you've got a lot of MCP servers connected. Now the headless side, because this one's a quiet security fix.

2:43 In CI, parent secrets and dev server tokens were leaking indiscriminately into worker agent environments. Now you say exactly what comes through. The example is claude, with the permission mode flag set to auto, then env passthrough with NPM_TOKEN and GITHUB_TOKEN separated by a comma, then the print flag with the prompt, Run static checks.

3:11 Those two tokens go through. Anything else in the parent environment stays out of the workers. If you'd rather set it once, that's what CLAUDE_CODE_SUBAGENT_ENV_ALLOWLIST is for. Put it in your CI config and every headless run follows the same rule, so nobody has to remember the flag.

3:29Practical tip start with an empty list, run your pipeline,

3:33 and add only what actually fails. That's the least privilege version, and it's easy to audit later. Two gotchas. First, if an agent asks for a tool that's not on the allowlist, it gets an immediate error turn. If your system prompt doesn't tell it what to do next, it can loop, trying near variants of the same tool.

3:53So add a line like if a tool is unavailable, report that and stop.

3:58 Second, disallowedTools wins over approvals in your global settings dot json permissions. So if you've approved Bash globally and denied it on one agent, the agent's denial holds. A few smaller fixes in 2.1.313 too. Nested Git worktrees now inherit the parent directory's claudeignore file, so ignored paths stay ignored.

4:22 The status bar now shows active subagent tool counts and how long they've been running, which is handy for checking your filters actually applied. And ANSI escape sequences in subagent error output are sanitized, which stops terminal corruption in Windows PowerShell. So, your homework: pick one subagent you already use, strip it down to the tools it really needs, and check the status bar for the tool count.

4:45 Then lock down your CI environment list. Catch you tomorrow.