Commands

Commands are actions the client sends to the server. The server processes them and updates state accordingly. Commands are fire-and-forget — the client observes results through state deltas.

Implemented

submit

Submit a prompt for Claude Code to execute.

{ type: "submit"; prompt: string }

Creates a user message, starts a sandbox run, and streams assistant responses back as deltas.

cancel

Abort the current run.

{ type: "cancel" }

Aborts the active agent session and sets status back to idle.

Planned

Steering

steer

Send a steering message to the running agent mid-execution. Allows the user to redirect, correct, or provide additional context without waiting for the run to complete.

{ type: "steer"; message: string }

Examples: "Focus on the backend first", "Don't modify that file", "Use TypeScript instead".

Permission Control

approve

Approve a pending tool call. When the agent requires user approval (e.g. file writes, shell commands), the server pauses and waits.

{ type: "approve"; toolCallId: string }

deny

Deny a pending tool call.

{ type: "deny"; toolCallId: string; reason?: string }

Session Management

resume

Resume a completed session with a follow-up prompt. Unlike submit, this continues the existing conversation history.

{ type: "resume"; prompt: string; sessionId: string }

The Claude Agent SDK supports continueLastConversation, resume (by session ID), and forkSession — this command maps to those capabilities.

Configuration

configure

Update runtime configuration for the sandbox session.

{
  type: "configure";
  config: {
    permissionMode?: "default" | "acceptEdits" | "fullAuto";
    maxTurns?: number;
    model?: string;
    systemPrompt?: string;
    effort?: "low" | "medium" | "high" | "max";
  }
}

Maps to the SDK's setPermissionMode(), setModel(), and query options.

File Operations

rewind

Revert files to their state at a specific message in the conversation.

{ type: "rewind"; messageId: string; dryRun?: boolean }

Maps to the SDK's query.rewindFiles().

State Extensions

As commands expand, HarnessState grows to support new capabilities:

type HarnessState = {
  status: "idle" | "running" | "awaiting-approval" | "error";
  messages: HarnessMessage[];
  pendingApprovals?: PendingApproval[];
  sessionId?: string;
  error?: string;
};

type PendingApproval = {
  toolCallId: string;
  toolName: string;
  description: string;
};

New message content types

Tool calls will carry richer information:

type HarnessToolCall = {
  id: string;
  name: string;
  status: "running" | "awaiting-approval" | "complete" | "error" | "denied";
  input?: Record<string, unknown>;
  output?: string;
};

Out of Scope

The following SDK capabilities are intentionally not exposed as commands. They are server-side configuration or internal concerns:

• MCP server management — configured server-side, not per-client
• Hooks — server-side event handlers
• Sandbox settings — configured in the Dockerfile/DO, not by the client
• Custom agents/subagents — configured server-side
• Plugins — server-side configuration
• Settings hierarchy — managed by the server

Design Principles

• Commands are fire-and-forget. The client sends a command and observes state changes. No request/response pairs.
• State is the single source of truth. Everything is reflected in deltas.
• Commands can be batched. Multiple commands in a single commands message are processed in order.
• Err on fewer commands. Only add commands for genuinely distinct user intents.
• Client commands map to SDK capabilities. Each command should have a clear mapping to the Claude Agent SDK's API surface.