2.1.142 untested · changelog-derived

Claude Code 2.1.142

**`claude agents` configuration flags** — Eight new flags (`--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, `--dangerously-skip-permissions`) unlock dynamic configuration of dispatched background sessions, enabling agents to customize runtime behavior without hardcoded defaults.

12 new primitives 3 workflow recipes 19 fixes

New primitives

--add-dir flagflag

Adds directory to dispatched background session configuration

Added new `claude agents` flags: `--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, and `--dangerously-skip-permissions` to configure dispatched background sessions

--settings flagflag

Configures settings for dispatched background session

--mcp-config flagflag

Configures MCP servers for dispatched background session

--plugin-dir flagflag

Specifies plugin directory for dispatched background session

--permission-mode flagflag

Configures permission behavior for dispatched background session

--model flagflag

Sets model for dispatched background session

--effort flagflag

Sets reasoning effort level for dispatched background session

--dangerously-skip-permissions flagflag

Skips permission prompts for dispatched background session

CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE env varenv-var

Pins fast mode to Opus 4.6 instead of new Opus 4.7 default

Set `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` to pin fast mode to Opus 4.6

Root-level SKILL.md skill discoverycapability

Plugins with root-level `SKILL.md` and no `skills/` subdirectory are now auto-surfaced as skills

Plugins with a root-level `SKILL.md` and no `skills/` subdirectory are now surfaced as a skill

LSP server visibility in /plugincapability

`/plugin` details pane and `claude plugin details` now expose LSP servers provided by a plugin

The `/plugin` details pane and `claude plugin details` now show LSP servers a plugin provides

/web-setup connection warningcapability

`/web-setup` warns before overwriting existing GitHub App connection

`/web-setup` warns before replacing an existing GitHub App connection

Workflow recipes

Isolated Model Experiments with Tailored Worker Sessions

--model flag + --effort flag + --dangerously-skip-permissions flag + Opus 4.7 default upgrade

Agents can now spawn isolated background workers pinned to specific models and reasoning effort levels, enabling parallel hypothesis testing (e.g., Haiku fast-explore vs. Opus deep-think) without blocking the main session or requiring user permission re-prompting.

An agent running a complex decision task spawns two background workers in parallel: one with --model claude-haiku-4-5 --effort low --dangerously-skip-permissions for rapid option enumeration, another with --model claude-opus-4-1 --effort max --dangerously-skip-permissions for deep analysis of frontrunner options. Both workers persist independently, allowing the parent agent to gather parallel signals, compare outputs, and synthesize a recommendation without sequential bottlenecks.

Persistent Graph-Synced Agents with Preconfigured Boundaries

--add-dir flag + --settings flag + --permission-mode flag + root-level SKILL.md auto-surfacing

Agents can dispatch workers with exact directory scope, pre-loaded settings, and permission lockdown, enabling reliable graph-synced agent swarms where each worker has a bounded execution context and repeatable configuration state.

A parent agent orchestrates a fleet of specialized workers for a Grafeo graph ingestion workflow. Each worker is spawned with --add-dir ./lib --settings ./worker-config.json --permission-mode strict, ensuring all workers operate in the same project scope, load the same baselines, and cannot exceed permission boundaries. Workers can be retired and respawned with identical configuration, enabling idempotent batch processing of graph ingestion tasks without global state drift.

MCP Tool Farm with Stable Daemon Lifecycle

--mcp-config flag + MCP_TOOL_TIMEOUT hardening + daemon sleep/wake resilience

Agents can now provision background workers with explicit MCP server configuration and rely on stable daemon behavior across system sleep/wake cycles, enabling 24-hour agent farms with long-running tool integrations (e.g., database pollers, API monitors) that previously crashed on macOS.

A parent agent managing a long-lived monitoring workflow spawns a background worker with --mcp-config ./mcp-servers.json pointing to remote database and HTTP monitoring tools. The daemon now correctly handles MCP_TOOL_TIMEOUT for per-request fetch caps (previously capped at 60s) and survives macOS sleep/wake transitions, allowing the worker to run unattended overnight, poll data sources on a cron-like schedule, and reliably reconnect after system wakes.

Agentic relevance

The eight new configuration flags enable agents to dispatch background sessions with tailored runtime behavior without requiring user interaction or pre-configured defaults. Combined with the Opus 4.7 upgrade and improved daemon stability (sleep/wake, worktree, permission persistence), agents can now reliably spawn persistent workers with explicit model, effort, permission, and tool configuration — unlocking multi-turn orchestration patterns where agents control resource allocation and isolation boundaries.

Hardening & fixes (19)

Fixed `MCP_TOOL_TIMEOUT` not raising the per-request fetch timeout for remote HTTP and SSE MCP servers, which capped tool calls at 60 seconds regardless of the configured value
Fixed background sessions not recognizing pre-existing git worktrees, blocking Edit while EnterWorktree refused to create a duplicate
Fixed background sessions disappearing and daemon reconnect failing after macOS sleep/wake — the daemon now detects clock jumps instead of treating them as elapsed idle time
Fixed daemon not exiting cleanly after the binary is upgraded (e.g. `brew upgrade`), causing dispatched agents to crash-loop on the deleted path
Fixed background agents crash-looping when the Claude-in-Chrome extension is connected without a shared tab
Fixed clicking links in an attached `claude agents` session — the background worker's headless browser shim no longer applies while attached
Fixed `claude agents` "v to open in editor" using the daemon's default editor instead of your shell's `$EDITOR`/`$VISUAL`
Fixed `claude agents` deadlocking on Windows with network-drive working directories; Ctrl+C now works during startup
Fixed background-color bleed when attaching to a `claude agents` session from Apple Terminal or other 256-color-only terminals
Fixed `claude --bg --dangerously-skip-permissions` not persisting across retire/wake
Fixed session titles being derived from the URL when the first message is a link
Fixed redundant `set_model` requests from remote clients injecting duplicate `/model` breadcrumbs into the transcript
Fixed plugins using `skills: ["./"]` showing a false "path escapes plugin directory" error
Fixed plugin cache cleanup deleting the active plugin version directory when no installation metadata is present
Fixed `/plugin` browse pane showing "0 installs" for newly published plugins
Fixed plugin advisories not naming every `plugin.json` key that shadows a default folder
Improved reactive compaction: the first summarize attempt now seeds from the original request's overflow size, avoiding a wasted near-full-context retry
Improved hook configuration error: configuring a prompt- or agent-type hook for `SessionStart`/`Setup`/`SubagentStart` now shows a clear "use a command-type hook instead" error
Removed stale `/model claude-sonnet-4-20250514` suggestion from Usage Policy refusal messages

Raw changelog

## 2.1.142

- Added new `claude agents` flags: `--add-dir`, `--settings`, `--mcp-config`, `--plugin-dir`, `--permission-mode`, `--model`, `--effort`, and `--dangerously-skip-permissions` to configure dispatched background sessions
- Fast mode now uses Opus 4.7 by default (previously Opus 4.6). Set `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` to pin fast mode to Opus 4.6
- Plugins with a root-level `SKILL.md` and no `skills/` subdirectory are now surfaced as a skill
- The `/plugin` details pane and `claude plugin details` now show LSP servers a plugin provides
- `/web-setup` warns before replacing an existing GitHub App connection
- Fixed `MCP_TOOL_TIMEOUT` not raising the per-request fetch timeout for remote HTTP and SSE MCP servers, which capped tool calls at 60 seconds regardless of the configured value
- Fixed background sessions not recognizing pre-existing git worktrees, blocking Edit while EnterWorktree refused to create a duplicate
- Fixed background sessions disappearing and daemon reconnect failing after macOS sleep/wake — the daemon now detects clock jumps instead of treating them as elapsed idle time
- Fixed daemon not exiting cleanly after the binary is upgraded (e.g. `brew upgrade`), causing dispatched agents to crash-loop on the deleted path
- Fixed background agents crash-looping when the Claude-in-Chrome extension is connected without a shared tab
- Fixed clicking links in an attached `claude agents` session — the background worker's headless browser shim no longer applies while attached
- Fixed `claude agents` "v to open in editor" using the daemon's default editor instead of your shell's `$EDITOR`/`$VISUAL`
- Fixed `claude agents` deadlocking on Windows with network-drive working directories; Ctrl+C now works during startup
- Fixed background-color bleed when attaching to a `claude agents` session from Apple Terminal or other 256-color-only terminals
- Fixed `claude --bg --dangerously-skip-permissions` not persisting across retire/wake
- Fixed session titles being derived from the URL when the first message is a link
- Fixed redundant `set_model` requests from remote clients injecting duplicate `/model` breadcrumbs into the transcript
- Fixed plugins using `skills: ["./"]` showing a false "path escapes plugin directory" error
- Fixed plugin cache cleanup deleting the active plugin version directory when no installation metadata is present
- Fixed `/plugin` browse pane showing "0 installs" for newly published plugins
- Fixed plugin advisories not naming every `plugin.json` key that shadows a default folder
- Improved reactive compaction: the first summarize attempt now seeds from the original request's overflow size, avoiding a wasted near-full-context retry
- Improved hook configuration error: configuring a prompt- or agent-type hook for `SessionStart`/`Setup`/`SubagentStart` now shows a clear "use a command-type hook instead" error
- Removed stale `/model claude-sonnet-4-20250514` suggestion from Usage Policy refusal messages

All 395 primitives Book a call