Claude Code Worktree Says Command Is Too Complex? Fix It

If Claude Code 2.1.222 or 2.1.223 refuses a harmless command inside a claude --worktree session because it is "too complex to verify," do not weaken the worktree boundary. First replace inline environment expansion such as echo "$TERM" with a direct command such as printenv TERM. If the workflow needs source, shell variables, or shared helper functions, move that logic into one executable wrapper script and ask Claude Code to run the script directly.

Public issue reports show that the message can be misleading. A command can be refused even when it has no Git operation, redirect, or path outside the worktree. The safe workaround is structural: give the verifier a simple outer command while the executed script owns the environment setup and downstream task.

Confirm This Exact Worktree Failure

This guide owns one narrow intent: Bash commands refused by the verifier in a session started with claude --worktree or claude -w.

The August 5 report for version 2.1.222 reproduces the first case with echo "$TERM". The August 6 follow-up reports that version 2.1.223 also refuses source and . in an ordinary -w session, including a literal script path inside the worktree. Those are reporter observations, not an official root-cause statement from Anthropic.

Step 1: Prove the Boundary Without Changing Files

Ask Claude Code to run these commands separately:

pwd
git rev-parse --show-toplevel
git branch --show-current
git status --short
printenv TERM

Expected result:

• pwd and the Git top-level path name the same worktree;

• the branch belongs to this task;

• the status contains only changes you recognize;

• printenv TERM prints the value without requiring inline $TERM expansion.

If any path points to the main checkout, stop. The refusal may be protecting the correct boundary. Do not disguise an out-of-worktree path inside a wrapper.

If printenv TERM works while echo "$TERM" is refused, you have the reported environment-expansion signature. If reading a helper with head works while sourcing it is refused, you have the reported interpreter signature.

Step 2: Replace Simple Expansions With Direct Commands

Use commands that do not ask the outer shell to interpolate a value:

printenv TERM

git rev-parse --show-toplevel

git status --short

This is enough for inspection commands. Do not dump the whole environment with env, export, or set; that can expose credentials in logs or chat history. Request only the variable you need.

Splitting a long command into shorter commands can also improve reviewability, but length is not the important test. The public reproduction shows that a very short expansion can still be refused. A successful workaround must change what the verifier sees, not merely add line breaks.

Step 3: Put Setup and Execution in One Wrapper

Suppose a project normally runs this inline workflow:

source ./scripts/project-env.sh && pnpm test --filter api

Create a repository-owned wrapper for that workflow:

#!/usr/bin/env bash
set -euo pipefail

script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$script_dir/project-env.sh"
exec pnpm test --filter api

Save it under a reviewed project path such as scripts/test-api.sh, then run one simple outer command:

bash scripts/test-api.sh

Expected result: the Bash tool sees one executable script invocation, while the script performs its setup and test in the same child process.

The same pattern works when a plugin or skill sources shared functions. Convert the helper into an executable with an explicit input and output contract, or create a task wrapper that sources the helper internally and completes the task before exiting.

An executed script cannot export variables back into its parent shell. If later steps need computed values, choose one of these contracts:

• let the wrapper perform the downstream command in the same process;

• print a small, sanitized JSON result for Claude Code to read;

• write a non-secret generated file inside the worktree, then validate and consume that file separately.

Do not print tokens, API keys, cookies, or the complete environment as a workaround.

Step 4: Keep the Wrapper Inside the Worktree

Before running it, verify the wrapper path:

git rev-parse --show-toplevel
git status --short -- scripts/test-api.sh

Review the script itself. An executable wrapper is not a permission bypass. It must still obey repository instructions, approval requirements, and the current task's file boundary.

Use this prompt with Claude Code:

Work only in the current worktree. Show pwd, the Git top-level path, branch, and status before running anything. The inline shell setup is refused by the worktree verifier, so run the reviewed wrapper at scripts/test-api.sh as one command. Do not modify the wrapper, use paths outside this worktree, disable isolation, print the environment, or retry a refused command through eval. Stop if the wrapper is missing or the worktree is dirty with changes you do not recognize.

For the full setup and cleanup discipline, see How to Run Parallel Claude Code Agents With Git Worktrees.

Use a Manual Git Worktree Only as a Bounded Fallback

Anthropic's worktree documentation also supports worktrees created directly with Git. If the wrapper approach cannot support an urgent task and your repository policy permits it, create a separate Git worktree and start a normal Claude session from that directory:

git fetch origin
git worktree add ../project-fix-84182 -b fix-84182 origin/main
cd ../project-fix-84182
pwd
git rev-parse --show-toplevel
git status --short
claude

This keeps Git's separate checkout and index, but it does not claim the additional session boundary established by claude --worktree. Treat that as a security tradeoff, keep the task narrowly scoped, and verify the directory before every write. Return to the native worktree mode after a documented fix passes your reproduction.

Do not delete installed Claude Code versions, repoint installation symlinks, disable approval hooks, use eval, or add a broad isolation exception just to make one command run. Those changes are harder to audit than an explicit wrapper and can affect unrelated sessions.

Verify the Fix or Workaround

Use a harmless, version-scoped check:

1. Record claude --version.

2. Start a fresh disposable claude -w verifier-check session.

3. Confirm pwd, Git top-level path, branch, and clean status.

4. Run printenv TERM.

5. Run a reviewed wrapper that prints one non-secret value or performs a no-write check.

6. Test the original inline expansion and source command only if they are harmless.

7. Remove the disposable worktree through Git after confirming it is clean.

The workaround is successful when the direct command and wrapper complete in the intended worktree without exposing secrets or weakening approvals. The upstream issue is fixed only when the original harmless reproductions also work in a current native worktree session.

Track the Upstream Fix Without Repeated Manual Searches

This regression is still moving across versions and duplicate reports. You can ask Aident Loadout to search the public issue tracker through a reviewed, read-only integration instead of copying GitHub credentials into each worktree.

Give Claude Code the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then use a bounded prompt:

Use Aident Loadout to find a read-only GitHub issue search Action. Inspect the current schema and quote before execution. Search the anthropics/claude-code repository for open issues that mention both worktree isolation and either "too complex to verify," $TERM, or source. Return at most five deduplicated issue URLs with title, state, update time, and linked-fix evidence. Do not comment, label, close, or modify any issue.

That workflow does not repair Claude Code. It makes the refresh trigger observable and keeps provider credentials out of the prompt and repository. For the broader pattern, see How to Connect Claude Code and Codex to Real-World Tools.

Ready to monitor the fix without adding another secret to your worktree? Set up Aident Loadout and run a reviewed read-only issue search.

Sources

• Claude Code worktree documentation

• Claude Code environment variable documentation

• Claude Code issue #84182: environment expansion refused in 2.1.222

• Claude Code issue #84530: source refused in worktree sessions

• Claude Code issue #82966: earlier isolated-agent source report

• Claude Code 2.1.222 release

• Claude Code 2.1.223 release

Refresh this guide when Anthropic closes or links a fix from the cited issues, a newer Claude Code release passes both harmless reproductions, the official worktree settings change, or the Aident setup and GitHub search flow changes.