Control the Autohand CLI from every SDK

Capability map

Run the control lifecycle in 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

Conversation, handoff, and auto-mode names

Approval and saved-session names

YOLO, MCP, learning, tools, and context names

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 for the normalized event names, payload families, unknown-notification fallback, and the native Swift boundary.

Next steps

• Use Work with sessions for persistence and TypeScript concurrent-session awareness.
• Use Approvals and user input for the normal allow, deny, remember, and alternative flow.
• Use Pause and resume with stopWhen for TypeScript per-step host control.
• Open the language-specific API reference for native parameter and result types.