How to Hand Off Control of a Task Space Back to the User in ego-lite

Use the handOffTaskSpace() helper to transfer ownership from the automated agent to the user when manual interaction is required.

ego-lite provides isolated browsing contexts called task spaces that agents control during automation workflows. When a workflow encounters a step requiring human intervention—such as logging in, solving a CAPTCHA, or confirming a sensitive action—you must hand off control of a task space back to the user to maintain security and compliance. The handOffTaskSpace function in src/helpers.ts provides the standard protocol for this transfer.

Understanding Task Space Ownership

Task spaces represent isolated browser sessions that automated agents operate within during ego-lite workflows. These contexts ensure that agent actions remain sandboxed and traceable. When an agent reaches a boundary requiring human judgment or credentials, the system must transfer ownership from the agent runtime to the user. This prevents unauthorized automation of sensitive actions while preserving the session state for later automation.

The Handoff Workflow

The handOffTaskSpace helper implements a four-step protocol to safely transfer control. This workflow ensures that the underlying ego runtime updates its internal ownership map correctly.

1. Select the Target Task Space

Identify which task space requires user intervention. You can target the currently active space by passing no arguments, or specify a particular space using its string name or numeric ID obtained from previous listTaskSpaces calls.

2. Execute the Handoff Call

Invoke the helper with await handOffTaskSpace([nameOrId]). According to the source code in src/helpers.ts, this function validates that the ego runtime exposes the required handOffTaskSpace function, delegates space selection to selectTaskSpace, and forwards the request to the runtime.

3. Validate the Result Object

Inspect the returned object to confirm the operation status:

• { done: true } — The handoff succeeded; the user now owns the task space.
• { done: false, skipped: "user-owned" } — The space was already under user control, so no transfer occurred.

4. Resume Automation

After the user completes their manual steps, reclaim control using takeOverTaskSpace with the specific task ID, or simply continue execution if the user signals readiness through your application interface.

Code Examples

The following examples demonstrate common handoff patterns using the public API documented in skills/ego-browser/SKILL.md.

Hand Off the Current Task Space

// Hand off the currently selected task space for a login step
const result = await handOffSpace();

if (result.done) {
  console.log('✅ Handed off to user – they can now complete the login.');
} else if (result.skipped === 'user-owned') {
  console.log('⚠️ Space already under user control – no handoff needed.');
}

Hand Off a Specific Task Space by ID

// Obtain ID from a previous listTaskSpaces call
const taskId = 42;
const result = await handOffTaskSpace(taskId);

if (result.done) {
  console.log(`✅ Handed off task space ${taskId} to the user.`);
}

Reclaim Control After User Completion

// After the user completes the manual step, reclaim the space
await takeOverTaskSpace(taskId);
// Continue automated workflow...

Technical Implementation Details

Under the hood, the handOffTaskSpace implementation in src/helpers.ts performs strict validation before executing the transfer. It verifies that the global ego runtime object exists and exposes the native handOffTaskSpace capability. The helper then uses selectTaskSpace to resolve the target space identifier before invoking the runtime method.

The ego runtime updates its internal task-space ownership map upon receiving the request. This map tracks which contexts belong to automated agents versus human users, causing subsequent agent API calls to respect the new ownership status and reject unauthorized automation attempts on user-controlled spaces. This architecture is detailed in AGENTS.md and the skill reference documentation.

Summary

• Use handOffTaskSpace() to transfer task space ownership from agent to user when manual steps are required.
• Handle the result object to distinguish between successful transfers (done: true) and spaces already under user control (skipped: "user-owned").
• Target specific spaces by passing a name or numeric ID, or omit the argument to use the currently selected space.
• Reclaim automation rights later using takeOverTaskSpace once the user finishes their work.
• Reference src/helpers.ts for the implementation and skills/ego-browser/SKILL.md for complete API documentation.

Frequently Asked Questions

What happens if I call handOffTaskSpace on a space the user already owns?

The function returns { done: false, skipped: "user-owned" } without throwing an error. This idempotent behavior allows you to safely request handoffs without first querying the current ownership state, simplifying error handling in your agent logic.

How do I know when the user has finished their manual steps?

ego-lite does not provide an automatic callback mechanism. Your application must implement a signaling protocol—such as a "Continue" button in the UI—that triggers the agent to call takeOverTaskSpace or resume execution. Alternatively, poll the task space status using listTaskSpaces to detect ownership changes.

Can I hand off multiple task spaces at once?

No, handOffTaskSpace processes one space per invocation as implemented in src/helpers.ts. To hand off multiple spaces, iterate over your target IDs and call the helper sequentially for each task space requiring user attention.

Where is the handoff logic documented in the source code?

The primary implementation resides in src/helpers.ts, which exports the handOffTaskSpace function and internal selection logic. Human-readable specifications appear in skills/ego-browser/SKILL.md under the "Task spaces" table and "Handing off" section, while AGENTS.md provides architectural context for the ownership transfer protocol.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}