How PowerShell Manages State Across Commands: The Complete Architecture Guide

PowerShell manages state across commands through a runspace-based execution model where each isolated runspace contains an ExecutionContext object that holds a SessionStateInternal instance, maintaining persistent scope hierarchies, variables, drives, and modules unless explicitly isolated in a child runspace.

The PowerShell/PowerShell repository implements a sophisticated state management system that enables variables, functions, and providers to persist between successive commands in a single session. Understanding how PowerShell manages state across commands is essential for developers building advanced automation tools, remote management solutions, and complex scripting workflows that require consistent data availability across multiple execution units.

The Runspace as an Isolated Execution Environment

PowerShell’s command execution centers on the runspace—an isolated environment that serves as the boundary for state persistence. Each runspace owns exactly one ExecutionContext instance, which functions as the central hub for all state-related operations. The ExecutionContext object, defined in [src/System.Management.Automation/engine/ExecutionContext.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/ExecutionContext.cs), maintains a reference to EngineSessionState, which maps directly to the internal SessionStateInternal class.

When you execute commands in a standard PowerShell session, you are operating within a single runspace. All commands share the same ExecutionContext and therefore access the same underlying state containers. This design ensures that variables set in one command remain available in subsequent commands within that same runspace.

Core State Management Components

PowerShell’s state architecture relies on three primary classes working in concert to provide both persistence and isolation. These components handle everything from variable resolution to drive management across command boundaries.

ExecutionContext: The Central Hub

The ExecutionContext class acts as the top-level container created for each runspace. It stores the current SessionStateInternal instance and provides the execution engine with access to language modes, streams, and host information. According to the source in ExecutionContext.cs, this context is instantiated when a runspace opens and remains constant for the lifetime of that runspace, ensuring state continuity across command invocations.

SessionStateInternal: The State Container

The SessionStateInternal class, implemented in [src/System.Management.Automation/engine/SessionState.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/SessionState.cs), serves as the actual repository for session state. This internal class holds:

• Scope hierarchy – A tree of SessionStateScope objects representing global, script, and local scopes
• Variable tables – Storage for automatic and special variables like $Error and $PSDefaultParameterValues
• Drives and providers – Collections of PSDriveInfo objects and provider registrations
• Module tables – Imported module information and load ordering
• Language constraints – The current PSLanguageMode (Full, Restricted, NoLanguage, or Constrained)

The constructor signature internal SessionStateInternal(SessionStateInternal parent, bool linkToGlobal, ExecutionContext context) enables the creation of child sessions that optionally inherit the parent’s global scope while maintaining isolated local scopes.

SessionStateScope: Managing Variable Visibility

Individual scope boundaries are enforced by SessionStateScope objects, defined in [src/System.Management.Automation/engine/SessionStateScope.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/SessionStateScope.cs). Each scope tracks its parent scope, script scope associations, local variable tuples, and drive collections. This hierarchy ensures that variable lookups traverse from local to script to global scopes, providing the scoping semantics that PowerShell scripters rely upon.

State Inheritance in Child Runspaces

When creating isolated execution environments—such as background jobs, remote sessions, or restricted runspaces—PowerShell supports state inheritance through a copy mechanism. The SessionStateInternal copy constructor creates a new state instance that duplicates the parent’s scopes, drives, and providers.

By passing linkToGlobal: true to this constructor, a child runspace can share its global scope with the parent while maintaining independent script and local scopes. This approach balances isolation with continuity, allowing child sessions to access parent variables while preventing unwanted pollution of the parent’s state. The InitialSessionState class in [src/System.Management.Automation/engine/InitialSessionState.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/InitialSessionState.cs) exposes this functionality to cmdlet authors and host application developers.

Public vs Internal APIs

PowerShell exposes session state functionality through two distinct layers. The SessionState class in [src/System.Management.Automation/engine/SessionStatePublic.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/SessionStatePublic.cs) acts as a thin façade over SessionStateInternal, providing cmdlet authors with intrinsics such as:

• Drive – Access to PSDrives
• Provider – Access to PowerShell providers
• Path – Path manipulation utilities
• PSVariable – Variable intrinsics

This public API enforces visibility rules through static methods IsVisible and ThrowIfNotVisible, ensuring that commands can only access public entries unless running with internal elevation. The façade pattern allows Microsoft to modify internal state representations while maintaining backward compatibility with existing cmdlets and scripts.

Practical Examples

Accessing Current Session State via Reflection

While SessionStateInternal is internal, you can access the current execution context through the default runspace to inspect the live state container.

# Access the ExecutionContext through reflection (for diagnostic purposes)

$runspace = [System.Management.Automation.Runspaces.Runspace]::DefaultRunspace
$context = $runspace.ExecutionContext
$sessionState = $context.EngineSessionState

# Enumerate available drives (same as Get-PSDrive)

$sessionState.Drives.Keys

This example demonstrates how the EngineSessionState property exposes the internal SessionStateInternal instance to the engine components, confirming that your current session maintains persistent drive and variable collections.

Creating Child Runspaces with Inherited State

When spawning isolated sessions that require parent context, use InitialSessionState to copy the parent’s configuration.

using System.Management.Automation;
using System.Management.Automation.Runspaces;

// Create and open parent runspace
Runspace parent = RunspaceFactory.CreateRunspace();
parent.Open();

// Create child runspace inheriting parent's initial session state
Runspace child = RunspaceFactory.CreateRunspace(
    new InitialSessionState(parent.InitialSessionState)
);
child.Open();

// Demonstrate state inheritance
parent.SessionStateProxy.SetVariable("SharedVar", "CrossSessionData");
object value = child.SessionStateProxy.GetVariable("SharedVar");
Console.WriteLine(value);  // Outputs: CrossSessionData

The InitialSessionState constructor internally invokes the SessionStateInternal copy constructor, ensuring the child runspace initializes with identical scopes, drives, and module availability.

Demonstrating Scope Isolation

PowerShell’s scope hierarchy prevents unwanted variable leakage while allowing explicit parent access.

# Define a global variable

$global:counter = 1

function Test-Scope {
    $script:counter = $counter + 1
    Write-Host "Script scope: $script:counter"
}

Test-Scope      # Outputs: Script scope: 2

$global:counter # Outputs: 1 (global unchanged)

This behavior relies on SessionStateScope objects created for each function invocation, which maintain separate variable tables while preserving the hierarchy for lookup purposes.

Summary

• Runspaces provide isolated execution environments where state persists across commands via a single ExecutionContext instance per runspace.
• SessionStateInternal acts as the actual state container, managing scopes, variables, drives, modules, and language modes in [src/System.Management.Automation/engine/SessionState.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/SessionState.cs).
• SessionStateScope objects form a hierarchy (global, script, local) that controls variable visibility and lookup order.
• Child runspaces can inherit parent state through the SessionStateInternal copy constructor while maintaining isolation for sensitive operations.
• The public SessionState façade exposes intrinsics like Drive, Provider, and PSVariable while enforcing visibility constraints.

Frequently Asked Questions

What is a runspace in PowerShell?

A runspace is an isolated execution environment that contains the complete infrastructure needed to execute PowerShell commands, including the engine, type table, and state containers. Each runspace maintains its own ExecutionContext and SessionStateInternal instances, ensuring that variables and drives persist across commands within that specific runspace while remaining separate from other runspaces.

How do variables persist between commands in PowerShell?

Variables persist because the SessionStateInternal object stored in the runspace’s ExecutionContext maintains a scope hierarchy of SessionStateScope objects. When you set a variable in one command, PowerShell writes it to the appropriate scope table (global, script, or local) within the current SessionStateInternal instance. Subsequent commands access the same instance, retrieving values from the scope hierarchy unless explicitly removed or overwritten.

What is the difference between SessionState and SessionStateInternal?

SessionState is the public façade class exposed to cmdlet developers through the SessionState property in PSCmdlet, providing safe access to drives, providers, paths, and variables. SessionStateInternal is the actual implementation class that contains the raw data structures for scopes, variable tables, and drive collections. The public class forwards calls to the internal instance while performing visibility checks via IsVisible and ThrowIfNotVisible methods defined in [SessionStatePublic.cs](https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/SessionStatePublic.cs).

How can I create an isolated PowerShell session while preserving parent state?

Create a new runspace using RunspaceFactory.CreateRunspace with an InitialSessionState object constructed from the parent runspace’s InitialSessionState property. This invokes the internal SessionStateInternal(SessionStateInternal parent, bool linkToGlobal, ExecutionContext context) constructor, copying the parent’s scopes, drives, and providers. Set linkToGlobal to true if you want the child to share the parent’s global scope, or false for complete isolation while retaining the initial configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}