[FEATURE] `--freeze-context` / `--context-lock` for subagent and agent team configuration inheritance

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request: --freeze-context / --context-lock for subagent and agent team configuration inheritance

Summary

When launching subagents (via the Task tool) or agent team teammates, there is no way to guarantee they run with the same configuration as the parent session. Subagents read configuration from disk at spawn time, which may have diverged from the parent session's actual state. I'm requesting a native mechanism to snapshot and propagate the parent session's live configuration to child agents.

Problem

In a typical workflow, my session starts with a specific configuration — a model, a set of MCP servers, plugins, environment variables, and permissions. Over the course of a working session:

1. Disk drifts from session. A teammate pushes new agents, skills, or plugins to .claude/agents/ or .claude/settings.json. A new MCP server appears in .mcp.json. My session was started before these changes, so I'm not running with them — but any subagent I spawn will pick them up from disk.

1. Session drifts from disk. I change my model mid-session with /model opus. I add a directory with /add-dir. These changes exist only in my live session, not on disk — so subagents don't inherit them either.

The result: subagents run with an unpredictable mix of new-disk-state and missing-session-state, which is neither the parent's config nor a coherent standalone config.

Proposed Solution

Proposed solution

A native mechanism, ideally:

Option A: Session-level flag

claude --freeze-context

or

export CLAUDE_CODE_FREEZE_CONTEXT=1

When enabled, all subagents and agent team teammates inherit a snapshot of the parent session's live state — model, MCP servers, plugins, env vars, permissions, tools — rather than reading from disk. This snapshot is taken at spawn time from the parent's in-memory config.

Option B: Per-spawn parameter on the Task tool

Task(
  prompt="...",
  subagent_type="my-agent",
  inherit_context=true  # new parameter
)

This would be the most granular approach and wouldn't require a session-level flag.

Option C: Subagent config field

---
name: my-agent
description: ...
context: inherit  # new field — inherit parent session config
model: inherit
---

What "inherit" should include

At minimum:

• Model (the actual model the parent is running, not the default)
• MCP servers (the set that was loaded at parent session start)
• Plugins (enabled/disabled state from the parent)
• Environment variables (the merged set the parent is running with)
• Permissions (the effective allow/deny rules)

Ideally also:

• Additional directories (added via --add-dir or /add-dir)
• Skills (the set loaded in the parent)
• CLAUDE.md context (though this is large — maybe opt-in)

What "inherit" should NOT include

• Conversation history (subagents should start with a clean context — this is already the case and is correct)
• Tool approval state (session-specific approvals shouldn't propagate blindly)

Impact

This affects anyone using parallel subagents or agent teams for serious work, which is exactly the workflow Anthropic is promoting with the Task tool and Agent Teams feature. The current behavior makes multi-agent orchestration unreliable in any environment where configuration evolves — which is every team project.

The hook-based workaround I've built demonstrates the demand and provides a reference implementation, but the limitations listed above make it unsuitable as a long-term solution. Native support would be straightforward to implement since Claude Code already has the live session state in memory — it just needs a mechanism to propagate it.

Alternative Solutions

Current workarounds (and why they're insufficient)

I've built a hook-based workaround called context-lock that:

• Captures a config snapshot at SessionStart (when disk ≈ session)
• Uses PreToolUse(Task) hooks to write the snapshot into settings.local.json before each subagent spawn
• Uses PostToolUse(Task) hooks to restore the original file afterward

This works partially, but has fundamental limitations:

• Can't capture live session state — only reconstructs from files + env vars
• Relies on subagents re-reading disk — if Claude Code caches config in memory, the file changes have no effect
• Can't intercept or modify the subagent's prompt — verification has to happen after-the-fact
• Race conditions — if multiple subagents launch in parallel (which is the whole point), they share one settings.local.json file
• Fragile JSON merging — the backup/restore cycle can corrupt settings.local.json if things go wrong
• Mid-session changes aren't captured — /model changes, /add-dir additions, etc. are invisible to the snapshot

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

Concrete scenarios

• I'm running Opus for a complex task. I spawn subagents to parallelize research. They silently launch on Sonnet (the default subagent model), giving me degraded results on work I specifically chose Opus for.
• My project has 3 MCP servers configured. A teammate adds a 4th that requires credentials I don't have. My session is fine (it was started before the change), but my subagents fail trying to connect to the new server.
• I have a carefully curated set of plugins enabled. Someone adds a new plugin to .claude/settings.json. My subagents pick it up and its agents/hooks interfere with my task.
• I curated my configuration for security reasons, a change on disk can mean a vector of attack
• I want to test something and disabled memory related features on my session so my subagents should also not mess with my memory related features
• Etc.

Additional Context

Related issues

• #5456 — Sub-agents Don't Inherit Model Configuration in Task Tool
• #8932 — general-purpose agent sets model as 'sonnet' rather than 'inherit'

Poor man's implementation of the workaround

Did it mostly with Opus, not thoroughly tested yes, and I would expect issues with the implementation, but also I want to burn cycles if the feature is going to be available soon.

Anthropic.zip