Grok Build · Context Isolation

Four Isolation Dimensions of Sub-Agents

Context source, identity continuity, working directory, and file change scope each control different boundaries. Conflating them into a single "isolation level" easily leads to misreading the true behavior of resumption and worktrees.

Learning Objective

Be able to accurately explain ContextSource::New / Resumed、ResumeSourceData、SubagentIsolationMode, and select new sessions, resumption, and worktrees based on the task.

TEACHING DIAGRAM

Isolation is a Set of Orthogonal Dimensions

The same Resumed sub-agent can reuse a worktree or inherit the ordinary cwd. Context continuity and file-space isolation must be evaluated independently.

Four isolation dimensions: context, identity, working directory, and change scope childsession ContextSourceNew / Resumed Identitytype / persona / model pin Effective cwdworktree > override > parent Isolation modeNone / Worktree
Public Semantics of ContextSource

ContextSource::New

A new session does not inherit history. The spawn process establishes a new system prompt and prompt context, then receives the current task input. It does not imply an independent file space — that still depends on isolation and cwd.

ContextSource::Resumed

Continues from a completed peer subagent. Source code copies the original transcript and tool state; the model reuses the source model. System prompt and prompt context are re-rendered according to the current AgentDefinition.

Implementation Note: xai-grok-subagent-resolution::ContextSource The public enum has only New and Resumed. Internally, the shell also has InitialContextSource::Forked, used to mirror or summarize context from the parent session. It belongs to a different bootstrap branch and should not be presented as a public enum member.
ResumeSourceData Carries Resumption Location Information
Identitysubagent_id, type, persona, model_id
Directorychild_cwd, worktree_path
Session Datachild_session_id locates transcript and tool state
Snapshotsnapshot_ref can reconstruct a deleted worktree

Identity Validation

  • subagent_type must match the source.
  • An explicit Persona must match the source; if not explicitly provided, the source persona is inherited.
  • model is not part of the identity gate. A model override in the request is soft-ignored and pinned to the source model.

Resumption Constraints

  • If copying the transcript or reading it fails, an explicit resume will fail and close.
  • Resumption is rejected if the source transcript exceeds 80% of the target model's context window.
  • Resumption copies tool state but not plan state, plan mode state, or signals.
SubagentIsolationMode Has Only Two Variants

None

The sub-agent uses the resolved cwd, typically the same as the parent workspace. The context window is still an independent child session. None describes file workspace isolation — it does not mean shared conversation history.

Worktree

The sub-agent uses an independent worktree path. On resumption, the source worktree is reused first; if the path has been removed and a snapshot_ref exists, it can be rehydrated from the persistent git ref. This enum has no "sandbox" member.

crates/codegen/xai-grok-subagent-resolution/src/types.rs crates/codegen/xai-grok-subagent-resolution/src/resume.rs crates/common/xai-tool-types/src/task.rs bootstrap_initial_context resolve_child_cwd
Real Source Code Snapshot
crates/common/xai-tool-types/src/task.rsREAL SOURCE
pub enum SubagentIsolationMode {
    #[default]
    #[serde(alias = "None")]
    None,
    #[serde(alias = "Worktree", alias = "work_tree", alias = "work-tree")]
    Worktree,
}

Snapshot Note: The enum is fully preserved to show wire aliases. The concentric circles above are course visuals emphasizing dimension orthogonality — they do not represent object hierarchy in the source code.

Classroom Exercise: Choose Boundaries for Two Tasks

Task A needs to continue a half-finished refactor from yesterday and keep the original worktree's uncommitted changes. Task B only needs to independently analyze the current repository. For each, choose New or Resumed and None or Worktree, and explain how transcript, model, cwd, and file change scope are handled.

Takeaway: New and Resumed control information continuity; None and Worktree control file space; ResumeSourceData handles locating identity, directory, session, and snapshot. Decompose dimensions first, then discuss isolation strength.