How to Take Back Control of a Task Space from the User in ego-lite

Call await takeOverTaskSpace([nameOrId]) to reclaim ownership of a task space after the user completes manual intervention, or use it to resume automation workflows that were previously handed off with handOffTaskSpace.

The ego-lite framework provides isolated browsing contexts called task spaces that transfer dynamically between automated agents and human operators. When your script encounters steps requiring manual intervention—such as authentication flows or CAPTCHA challenges—you temporarily cede control using handOffTaskSpace. Reclaiming that environment to resume automation requires the complementary takeOverTaskSpace helper defined in src/helpers.ts.

Understanding Task Space Ownership

In ego-lite, every task space maintains an internal ownership map managed by the underlying ego runtime. According to the source code in src/helpers.ts, ownership states determine which entity—agent or user—can execute commands within that browsing context. The runtime validates all ownership transfers through the selectTaskSpace utility before updating the internal map, ensuring that agents and users cannot simultaneously issue conflicting commands.

Handing Off Control to the User

Before you can take back control, you must first release it. The handOffTaskSpace function in src/helpers.ts handles the transfer from agent to user ownership.

To execute a handoff:

1. Select the target space using the current context or specify a name/ID.

2. Call the helper with an optional identifier:

   await handOffTaskSpace();        // Current space
   await handOffTaskSpace(42);      // Specific numeric ID
   await handOffTaskSpace("login"); // Named space

3. Validate the result object:

   • { done: true } indicates successful handoff.
   • { done: false, skipped: "user-owned" } indicates the space was already under user control.

Reclaiming Control with takeOverTaskSpace

When the user signals completion of manual steps, reclaim the session using the takeOverTaskSpace helper, also defined in src/helpers.ts.

Basic syntax:

await takeOverTaskSpace();          // Reclaim current space
await takeOverTaskSpace(taskId);    // Reclaim specific space by ID

The function validates that the ego runtime exposes the ownership API, selects the target via selectTaskSpace, and requests the runtime to transfer ownership from user back to agent. As noted in the skill reference file skills/ego-browser/SKILL.md, you may "simply continue if the space is already yours," indicating the helper handles idempotent calls gracefully when the agent already owns the space.

Complete Workflow: Hand Off and Retrieve

This example demonstrates the full cycle of surrendering and reclaiming a task space during a login flow:

// Step 1: Encounter manual intervention point
console.log("Login required - transferring to user");
const handoffResult = await handOffTaskSpace();
if (handoffResult.done) {
  console.log("✅ Space handed off to user");
}

// Step 2: User completes login manually in their browser

// Step 3: Reclaim the space to continue automation
await takeOverTaskSpace();
console.log("✅ Control restored - resuming automation");
// Continue with post-login workflows

Validating Ownership States

Both helpers return result objects indicating success or skip reasons. When calling handOffTaskSpace, always check for the skipped: "user-owned" state to avoid redundant operations. While the source code in skills/ego-browser/SKILL.md documents these return patterns primarily for the handoff function, the takeOverTaskSpace implementation follows similar semantics for consistency, as implied by the idempotent handling noted in AGENTS.md.

Summary

• Task spaces isolate browsing contexts between agents and users in ego-lite.
• Hand off control using handOffTaskSpace([nameOrId]) when encountering manual steps.
• Reclaim control using takeOverTaskSpace([nameOrId]) to resume automation after the user finishes.
• Both helpers reside in src/helpers.ts and interact with the ego runtime's ownership map via selectTaskSpace.
• Always validate result objects to handle cases where the space is already in the desired ownership state.

Frequently Asked Questions

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

The ego-lite framework does not provide automatic callbacks when users complete manual interactions. Your application must implement an external signaling mechanism—such as a webhook, database flag, or user interface button—that triggers the agent to call takeOverTaskSpace when the human operator indicates readiness.

What happens if I call takeOverTaskSpace on a space I already own?

According to the skill reference documentation in skills/ego-browser/SKILL.md, the helper handles idempotent calls gracefully. If the agent already owns the task space, the function returns successfully without errors, allowing you to safely call it defensively before resuming operations.

Can I forcefully take back a task space while the user is actively using it?

The source code in src/helpers.ts delegates ownership decisions to the underlying ego runtime. While the runtime manages the ownership map, the documentation in AGENTS.md emphasizes cooperative hand-off protocols rather than forced reclamation. Design your workflows to coordinate with users rather than overriding active sessions.

What's the difference between handOffTaskSpace and takeOverTaskSpace?

handOffTaskSpace transfers ownership from agent to user, typically used before manual steps like CAPTCHA or login. takeOverTaskSpace performs the reverse operation, returning ownership from user to agent so automation can resume. Both use selectTaskSpace internally to resolve target spaces and reside in src/helpers.ts.

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