> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={2}>
  <Card title="Full Access" icon="rocket">
    Default mode with maximum autonomy. Sessions start with `approvalPolicy: never` and `sandboxMode: danger-full-access`.
  </Card>

  <Card title="Supervised" icon="shield-check">
    Safety-first mode with user approval required. Sessions start with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, prompting for command/file approvals.
  </Card>
</CardGroup>

## Runtime Mode Types

The `RuntimeMode` type defines the high-level security posture:

```typescript packages/contracts/src/orchestration.ts theme={null}
export const RuntimeMode = Schema.Literals([
  "approval-required",
  "full-access"
]);

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

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

## Approval Policies

Approval policies determine when the agent must request user permission:

```typescript theme={null}
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:

```typescript apps/server/src/codexAppServerManager.ts theme={null}
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:

```typescript theme={null}
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
]);
```

<Warning>
  **Full Access Mode** grants unrestricted file system access and never prompts for approval. Only use in trusted environments with code you're comfortable executing.
</Warning>

## Approval Request Types

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

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

### Approval Request Flow

<Steps>
  <Step title="Agent Requests Approval">
    The agent sends an approval request via JSON-RPC (e.g., `item/commandExecution/requestApproval`)
  </Step>

  <Step title="Server Generates Request ID">
    The server creates a unique `ApprovalRequestId` and tracks the pending request
  </Step>

  <Step title="Client Displays Prompt">
    The web UI shows the approval dialog with request details
  </Step>

  <Step title="User Responds">
    User chooses: accept, acceptForSession, decline, or cancel
  </Step>

  <Step title="Server Forwards Decision">
    The server sends the decision back to the provider via JSON-RPC response
  </Step>
</Steps>

## Approval Decisions

Users can respond to approval requests with four decision types:

```typescript theme={null}
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
]);
```

<CodeGroup>
  ```typescript Responding to Approval theme={null}
  await providerService.respondToRequest({
    threadId,
    requestId,
    decision: "accept",
  });
  ```

  ```typescript Approval Request Event theme={null}
  {
    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",
    }
  }
  ```
</CodeGroup>

## User Input Requests

Beyond approval requests, agents can request structured user input:

```typescript theme={null}
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,
});
```

<Note>
  User input requests are separate from approval requests and are primarily used in **Plan Mode** for collaborative planning conversations.
</Note>

## Runtime Mode Changes

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

```typescript theme={null}
// 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(),
});
```

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

## Session Status and Runtime Mode

The orchestration session tracks the active runtime mode:

```typescript theme={null}
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:

```typescript apps/server/src/codexAppServerManager.ts theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
export const ProviderInteractionMode = Schema.Literals([
  "default",  // Standard execution mode
  "plan",     // Collaborative planning mode
]);

export const DEFAULT_PROVIDER_INTERACTION_MODE = "default";
```

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

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

## Best Practices

<CardGroup cols={2}>
  <Card title="Start Supervised" icon="shield">
    Use `approval-required` for unfamiliar codebases or destructive operations
  </Card>

  <Card title="Plan Before Execute" icon="list-check">
    Use Plan Mode for complex changes to validate approach before implementation
  </Card>

  <Card title="Session-Scoped Approvals" icon="clock">
    Use `acceptForSession` for repetitive safe operations like test runs
  </Card>

  <Card title="Review Declined Actions" icon="eye">
    Check activity logs to understand why declined operations were attempted
  </Card>
</CardGroup>

## Security Considerations

<Warning>
  **Full Access Mode Risks**:

  * Unrestricted file system access
  * Arbitrary command execution
  * No approval prompts or safety nets
  * Suitable only for trusted environments
</Warning>

<Note>
  **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
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sessions" icon="plug" href="/concepts/sessions">
    Learn about session lifecycle and management
  </Card>

  <Card title="Providers" icon="robot" href="/concepts/providers">
    Understand provider adapter architecture
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/concepts/architecture">
    Explore the overall system design
  </Card>
</CardGroup>