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

> Learn how to take back control of a task space in ego-lite by calling await takeOverTaskSpace. Reclaim ownership and resume automation workflows seamlessly.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:
   ```javascript
   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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).

**Basic syntax:**

```javascript
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`](https://github.com/citrolabs/ego-lite/blob/main/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:

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) delegates ownership decisions to the underlying ego runtime. While the runtime manages the ownership map, the documentation in [`AGENTS.md`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts).