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

> Learn how to hand off control of a task space back to the user in ego-lite using the handOffTaskSpace helper. Seamlessly transfer ownership for manual interaction.

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

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md).

### Hand Off the Current Task Space

```javascript
// 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

```javascript
// 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

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** for the implementation and [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), which exports the `handOffTaskSpace` function and internal selection logic. Human-readable specifications appear in [`skills/ego-browser/SKILL.md`](https://github.com/citrolabs/ego-lite/blob/main/skills/ego-browser/SKILL.md) under the "Task spaces" table and "Handing off" section, while [`AGENTS.md`](https://github.com/citrolabs/ego-lite/blob/main/AGENTS.md) provides architectural context for the ownership transfer protocol.