processWrapper is documented as honored from a --settings file, but only works from the env var or user settings

Summary

The processWrapper setting documents itself as honored from a --settings-supplied settings file, but empirically it only takes effect from the CLAUDE_CODE_PROCESS_WRAPPER environment variable or from user settings (~/.claude/settings.json). Passing it in a file via --settings never invokes the wrapper.

Verified on 2.1.220, macOS.

The documented behaviour

The setting's own schema description says:

Corporate launcher argv prefix for the background-agent supervisor, the sessions and workers it hosts, and the other covered background processes... Equivalent to the CLAUDE_CODE_PROCESS_WRAPPER environment variable, which takes precedence when set. Honored from managed settings, a --settings/SDK-supplied settings file, and user settings, in that precedence order; project and local settings are ignored.

Reproduction

Using an isolated HOME each time, with a wrapper script that logs the argv it receives and then re-execs it:

| how processWrapper was supplied | wrapper invoked? |
|---|---|
| CLAUDE_CODE_PROCESS_WRAPPER env var | yes — fires for daemon run, --bg-pty-host, and --bg-spare worker claims |
| ~/.claude/settings.json (user settings) | yes — identical firings on a fresh daemon |
| --settings <file> | no — wrapper never invoked, tested twice on fresh isolated homes |

Test command in each case was claude --bg "say hi", which is enough to make the daemon spawn workers.

Likely cause

The settings-to-env sync for this key reads the policy-settings, flag-settings and user-settings sources in order, and appears to run before --settings has been merged into the flag-settings source for this particular startup path — so the flag-settings lookup is empty at the moment it is consulted.

Impact

Minor but wasteful: anyone following the documented precedence order will conclude the feature is broken rather than that one of its three documented sources does not work. It also rules out per-invocation configuration of the launcher, which is the natural way to test a wrapper before adopting it machine-wide.

Either fix the ordering or drop the --settings/SDK source from the description.

Note on a similarly-named, different issue

#61103 is about the VS Code extension setting claudeCode.claudeProcessWrapper failing with Windows .cmd wrappers. That is a separate mechanism; this report is about the CLI settings key and its documented source precedence.