---
title: "Control the Autohand CLI from Every Agent SDK"
source: https://docs.autohand.ai/agent-sdk/concepts/cli-runtime-control
---

# Control the Autohand CLI from every SDK

The CLI-backed TypeScript, Python, Go, Java, Rust, Ruby, C#/.NET, and C++ SDKs expose typed control APIs beyond prompting. Hosts can reset conversations, hand sessions to a browser, operate auto-mode, answer approval protocols, attach saved sessions, manage MCP and learned skills, inspect tools, and change context compaction.

**Availability:** This page covers the common CLI-backed SDK contract introduced in the v1.0.4 parity wave. Native Swift uses a separate in-process SDK contract. TypeScript adds concurrent-session awareness in v1.0.5 and per-step `stopWhen` control in the current development surface.

## Capability map

| Area | Typed operations | Host responsibility |
|---|---|---|
| Conversation lifecycle | Reset the active conversation; create, consume, or attach the latest browser-handoff token. | Keep the CLI session alive and treat handoff tokens as short-lived credentials. |
| Auto-mode | Start, inspect, pause, resume, cancel, and read iteration-log entries. | Persist the returned session ID and observe asynchronous lifecycle events. |
| Approval protocols | Acknowledge permission and directory prompts, grant or deny directory access, and decide multi-file change batches. | Correlate every response to the original request or batch ID. |
| Saved sessions | Page through history, load typed details, and attach an exact saved session. | Handle typed business failures instead of silently selecting a different session. |
| Timed unrestricted mode | Set the canonical YOLO pattern with an optional positive timeout. | Expose the risk clearly and prefer the canonical method over its compatibility alias. |
| VS Code MCP | Replace extension-hosted MCP tool descriptors and respond to correlated invocation requests. | Send exactly one success result or one failure error for the request ID. |
| Project learning | Get scored skill recommendations, update installed skills, and generate a project- or user-scoped skill. | Review generated or updated skill material before relying on it in sensitive workflows. |
| Runtime inspection | Read the registered tool catalog and diagnostics; enable or disable automatic context compaction. | Refresh host UI from typed results rather than assuming a static tool list. |

## Run the control lifecycle in TypeScript

``` typescript
import { Agent } from '@autohandai/agent-sdk';

const agent = await Agent.create({ cwd: '/path/to/project' });

try {
  const reset = await agent.reset();
  console.log('fresh session', reset.sessionId);

  const started = await agent.startAutomode({
    prompt: 'Implement and verify the release checklist.',
    maxIterations: 20,
    useWorktree: true,
  });
  console.log('auto-mode session', started.sessionId);

  const status = await agent.getAutomodeStatus();
  if (status.active) await agent.pauseAutomode();

  const history = await agent.getHistory({ page: 1, pageSize: 20 });
  console.log(history);

  const tools = await agent.getToolsRegistry();
  console.log(tools);
} finally {
  await agent.close();
}
```

Auto-mode start confirms that the CLI accepted the autonomous session; it does not wait for that session to finish. Use status, log, and the typed `automode_iteration`, `automode_complete`, and `automode_error` events for ongoing state.

## Choose the right object

| SDK | Core lifecycle and auto-mode | Full approval, session, MCP, learning, and context surface |
|---|---|---|
| TypeScript | Agent, AutohandSDK, RPCClient | Agent, AutohandSDK, RPCClient |
| Python | Agent, AutohandSDK, RPC client | Agent, AutohandSDK, RPC client |
| Go | Agent, SDK, RPCClient | SDK, RPCClient |
| Java | Agent, AutohandSDK, RPCClient | AutohandSDK, RPCClient |
| Rust | Agent, AutohandSdk | AutohandSdk |
| Ruby | AutohandSDK::Client, RPC client | AutohandSDK::Client, RPC client |
| C#/.NET | Agent, AutohandSdk | AutohandSdk |
| C++ | autohand::Agent, autohand::AutohandSdk | autohand::AutohandSdk |

## Conversation, handoff, and auto-mode names

| SDK | Conversation and browser handoff | Auto-mode lifecycle |
|---|---|---|
| TypeScript | reset, createBrowserHandoff, attachBrowserHandoff, attachLatestBrowserHandoff | startAutomode, getAutomodeStatus, pauseAutomode, resumeAutomode, cancelAutomode, getAutomodeLog |
| Python | reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff | start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log |
| Go | Reset, CreateBrowserHandoff, AttachBrowserHandoff, AttachLatestBrowserHandoff | StartAutomode, GetAutomodeStatus, PauseAutomode, ResumeAutomode, CancelAutomode, GetAutomodeLog |
| Java | reset, createBrowserHandoff, attachBrowserHandoff, attachLatestBrowserHandoff | startAutoMode, getAutoModeStatus, pauseAutoMode, resumeAutoMode, cancelAutoMode, getAutoModeLog |
| Rust | reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff | start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log |
| Ruby | reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff | start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log |
| C#/.NET | ResetAsync, CreateBrowserHandoffAsync, AttachBrowserHandoffAsync, AttachLatestBrowserHandoffAsync | StartAutoModeAsync, GetAutoModeStatusAsync, PauseAutoModeAsync, ResumeAutoModeAsync, CancelAutoModeAsync, GetAutoModeLogAsync |
| C++ | reset, create_browser_handoff, attach_browser_handoff, attach_latest_browser_handoff | start_automode, get_automode_status, pause_automode, resume_automode, cancel_automode, get_automode_log |

## Approval and saved-session names

| SDK | Approval protocol | Saved sessions |
|---|---|---|
| TypeScript | acknowledgePermission, respondToDirectoryAccess, acknowledgeDirectoryAccess, decideChanges | getHistory, getSession, attachSession |
| Python | acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes | get_history, get_session, attach_session |
| Go | AcknowledgePermission, RespondToDirectoryAccess, AcknowledgeDirectoryAccess, DecideChanges | GetHistory, GetSession, AttachSession |
| Java | acknowledgePermission, respondDirectoryAccess, acknowledgeDirectoryAccess, decideChanges | getHistory, getSession, attachSession |
| Rust | acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes | get_history, get_session, attach_session |
| Ruby | acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes | get_session_history, get_session_details, attach_session |
| C#/.NET | AcknowledgePermissionAsync, RespondDirectoryAccessAsync, AcknowledgeDirectoryAccessAsync, DecideChangesAsync | GetHistoryAsync, GetSessionAsync, AttachSessionAsync |
| C++ | acknowledge_permission, respond_to_directory_access, acknowledge_directory_access, decide_changes | get_session_history, get_session, attach_session |

## YOLO, MCP, learning, tools, and context names

| SDK | Public method names |
|---|---|
| TypeScript | setYolo, setYoloCompat, setVscodeMcpTools, respondToMcpInvocation, getLearningRecommendations, updateLearnedSkills, generateSkill, getToolsRegistry, setContextCompact |
| Python | set_yolo, set_yolo_compat, set_vscode_mcp_tools, respond_to_mcp_invocation, get_learning_recommendations, update_learned_skills, generate_skill, get_tools_registry, set_context_compact |
| Go | SetYolo, SetYoloAlias, SetVSCodeMCPTools, RespondToMCPInvocation, RecommendProjectLearning, UpdateProjectLearning, GenerateProjectSkill, GetToolsRegistry, SetContextCompact |
| Java | setYoloMode, setYoloModeAlias, setVscodeMcpTools, respondMcpInvocation, recommendLearn, updateLearn, generateLearn, getToolsRegistry, setContextCompact |
| Rust | set_yolo, set_yolo_alias, set_vscode_mcp_tools, respond_to_mcp_invocation, recommend_project_learning, update_project_learning, generate_project_skill, get_tools_registry, set_context_compact |
| Ruby | set_yolo_mode, register_vscode_mcp_tools, complete_mcp_invocation, recommend_project_learning, update_project_learning, generate_project_skill, get_tools_registry, set_context_compaction |
| C#/.NET | SetYoloModeAsync, SetYoloModeAliasAsync, SetVscodeMcpToolsAsync, RespondMcpInvocationAsync, RecommendLearnAsync, UpdateLearnAsync, GenerateLearnAsync, GetToolsRegistryAsync, SetContextCompactAsync |
| C++ | set_yolo, set_yolo_compat, set_vscode_mcp_tools, respond_to_mcp_invocation, recommend_project_skills, update_project_skills, generate_skill, get_tools_registry, set_context_compact |

## Protocol and safety contracts

-   **Acknowledge before deciding:** permission and directory acknowledgements confirm receipt; they do not grant the requested action.
-   **Keep request identity:** directory, change-batch, and MCP responses must use the request or batch ID emitted by the CLI.
-   **Validate selected changes:** an accept-selected decision requires at least one selected change ID.
-   **Attach explicitly:** saved-session attachment uses an exact ID and returns typed success or business failure.
-   **Bound unrestricted mode:** timeout values must be positive. Compatibility aliases exist for older CLI versions but the canonical YOLO-set method is preferred.
-   **Complete MCP once:** a successful response cannot carry an error; a failed response requires one.
-   **Do not infer tool state:** tool registry, learning, and context-compaction calls return the CLI's validated typed result.

## Observe the extended runtime

Auto-mode emits `automode_iteration`, `automode_complete`, and `automode_error`. MCP invocation requests, MCP tool changes, project-learning progress, and all 16 CLI hook notifications are also typed across the CLI-backed wrappers.

Read [Hooks and events](/agent-sdk/concepts/hooks-and-events.html) for the normalized event names, payload families, unknown-notification fallback, and the native Swift boundary.

## Next steps

-   Use [Work with sessions](/agent-sdk/concepts/sessions.html) for persistence and TypeScript concurrent-session awareness.
-   Use [Approvals and user input](/agent-sdk/io/approvals.html) for the normal allow, deny, remember, and alternative flow.
-   Use [Pause and resume with stopWhen](/agent-sdk/io/step-control.html) for TypeScript per-step host control.
-   Open the language-specific API reference for native parameter and result types.