Runtime Modes

Understanding approval policies, sandbox modes, and security controls

Runtime modes control how T3 Code agents interact with your system, balancing autonomy with safety through approval policies and sandbox restrictions.

Overview

T3 Code provides two primary runtime modes accessible via the chat toolbar:

Full Access

Default mode with maximum autonomy. Sessions start with approvalPolicy: never and sandboxMode: danger-full-access.

Supervised

Safety-first mode with user approval required. Sessions start with approvalPolicy: on-request and sandboxMode: workspace-write, prompting for command/file approvals.

Runtime Mode Types

The RuntimeMode type defines the high-level security posture:

packages/contracts/src/orchestration.ts

export const RuntimeMode = Schema.Literals([
  "approval-required",
  "full-access"
]);

export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";

Runtime modes are set at session creation and affect the entire conversation lifecycle. They map to specific Codex approval policies and sandbox modes.

Approval Policies

Approval policies determine when the agent must request user permission:

export const ProviderApprovalPolicy = Schema.Literals([
  "untrusted",    // Approve everything (not yet implemented)
  "on-failure",   // Approve after failed attempts
  "on-request",   // Approve when agent requests permission
  "never",        // Never require approval
]);

Approval Policy Mapping

T3 Code maps runtime modes to Codex approval policies:

apps/server/src/codexAppServerManager.ts

function mapCodexRuntimeMode(runtimeMode: RuntimeMode): {
  readonly approvalPolicy: "on-request" | "never";
  readonly sandbox: "workspace-write" | "danger-full-access";
} {
  if (runtimeMode === "approval-required") {
    return {
      approvalPolicy: "on-request",
      sandbox: "workspace-write",
    };
  }

  return {
    approvalPolicy: "never",
    sandbox: "danger-full-access",
  };
}

Sandbox Modes

Sandbox modes restrict file system and system access:

export const ProviderSandboxMode = Schema.Literals([
  "read-only",            // Read files only, no modifications
  "workspace-write",      // Write within workspace, read elsewhere
  "danger-full-access",   // Unrestricted file system access
]);

Full Access Mode grants unrestricted file system access and never prompts for approval. Only use in trusted environments with code you’re comfortable executing.

Approval Request Types

When approval is required, the agent requests permission for specific operations:

export const ProviderRequestKind = Schema.Literals([
  "command",      // Shell command execution
  "file-read",    // Reading file contents
  "file-change",  // Writing or modifying files
]);

Approval Request Flow

1. Agent Requests Approval

   The agent sends an approval request via JSON-RPC (e.g., item/commandExecution/requestApproval)

2. Server Generates Request ID

   The server creates a unique ApprovalRequestId and tracks the pending request

3. Client Displays Prompt

   The web UI shows the approval dialog with request details

4. User Responds

   User chooses: accept, acceptForSession, decline, or cancel

5. Server Forwards Decision

   The server sends the decision back to the provider via JSON-RPC response

Approval Decisions

Users can respond to approval requests with four decision types:

export const ProviderApprovalDecision = Schema.Literals([
  "accept",              // Approve this one request
  "acceptForSession",    // Approve this and similar requests for session
  "decline",             // Deny this request
  "cancel",              // Cancel the entire operation
]);

Responding to Approval

await providerService.respondToRequest({
  threadId,
  requestId,
  decision: "accept",
});

{
  kind: "request",
  method: "item/commandExecution/requestApproval",
  threadId: "thread-123",
  turnId: "turn-456",
  requestId: "req-789",
  requestKind: "command",
  payload: {
    command: "npm install",
    workingDirectory: "/path/to/project",
  }
}

User Input Requests

Beyond approval requests, agents can request structured user input:

export const ProviderUserInputAnswers = Schema.Record(
  Schema.String,
  Schema.Unknown
);

// Example: Plan mode questions
const answers = {
  "question-1": "Option A",
  "question-2": ["Choice 1", "Choice 2"],
};

await providerService.respondToUserInput({
  threadId,
  requestId,
  answers,
});

User input requests are separate from approval requests and are primarily used in Plan Mode for collaborative planning conversations.

Runtime Mode Changes

Runtime modes can be changed during a thread’s lifetime:

// Dispatch command to change runtime mode
await orchestration.dispatchCommand({
  type: "thread.runtime-mode.set",
  commandId: CommandId.makeUnsafe(randomUUID()),
  threadId,
  runtimeMode: "approval-required",
  createdAt: new IsoDateTime(),
});

Session Restart Required: Changing runtime mode requires stopping and restarting the provider session with new settings. Existing sessions retain their original runtime mode.

Session Status and Runtime Mode

The orchestration session tracks the active runtime mode:

export const OrchestrationSession = Schema.Struct({
  threadId: ThreadId,
  status: OrchestrationSessionStatus,
  providerName: Schema.NullOr(TrimmedNonEmptyString),
  runtimeMode: RuntimeMode.pipe(
    Schema.withDecodingDefault(() => DEFAULT_RUNTIME_MODE)
  ),
  activeTurnId: Schema.NullOr(TurnId),
  lastError: Schema.NullOr(TrimmedNonEmptyString),
  updatedAt: IsoDateTime,
});

Pending Approval Tracking

The server tracks pending approvals in memory:

apps/server/src/codexAppServerManager.ts

interface PendingApprovalRequest {
  requestId: ApprovalRequestId;
  jsonRpcId: string | number;
  method:
    | "item/commandExecution/requestApproval"
    | "item/fileChange/requestApproval"
    | "item/fileRead/requestApproval";
  requestKind: ProviderRequestKind;
  threadId: ThreadId;
  turnId?: TurnId;
  itemId?: ProviderItemId;
}

interface CodexSessionContext {
  // ...
  pendingApprovals: Map<ApprovalRequestId, PendingApprovalRequest>;
  pendingUserInputs: Map<ApprovalRequestId, PendingUserInputRequest>;
  // ...
}

Service Tier

Independent of runtime mode, you can specify compute service tier:

export const ProviderServiceTier = Schema.Literals(["fast", "flex"]);

// Start session with specific tier
const session = await providerService.startSession(threadId, {
  threadId,
  runtimeMode: "full-access",
  serviceTier: "fast",
});

Interaction Modes

Interaction modes control conversation behavior:

export const ProviderInteractionMode = Schema.Literals([
  "default",  // Standard execution mode
  "plan",     // Collaborative planning mode
]);

export const DEFAULT_PROVIDER_INTERACTION_MODE = "default";

Default Mode

Standard execution mode where the agent directly implements requests.

• Minimal questions, bias toward action
• Direct execution of user requests
• request_user_input tool unavailable

Plan Mode

Collaborative planning mode for refining specifications before implementation.

• Three-phase conversation: environment grounding, intent chat, implementation chat
• request_user_input tool available for structured questions
• Non-mutating exploration allowed (read files, run tests)
• Mutating actions blocked until plan finalized
• Outputs <proposed_plan> blocks when ready

Interaction modes are orthogonal to runtime modes. You can use Plan Mode with either full-access or approval-required runtime mode.

Best Practices

Start Supervised

Use approval-required for unfamiliar codebases or destructive operations

Plan Before Execute

Use Plan Mode for complex changes to validate approach before implementation

Session-Scoped Approvals

Use acceptForSession for repetitive safe operations like test runs

Review Declined Actions

Check activity logs to understand why declined operations were attempted

Security Considerations

Full Access Mode Risks:

• Unrestricted file system access
• Arbitrary command execution
• No approval prompts or safety nets
• Suitable only for trusted environments

Supervised Mode Limitations:

• workspace-write restricts writes to workspace directory
• Read access still available outside workspace
• Agent cannot execute commands without approval
• May require more user interaction

Next Steps

Sessions

Learn about session lifecycle and management

Providers

Understand provider adapter architecture

Architecture

Explore the overall system design