# How Agents Reclaim Control in ego-lite Using `takeOverTaskSpace`

> Learn how to use ego-lite's takeOverTaskSpace to reclaim control from users and instantly resume automation commands. Expert guide for citrolabs/ego-lite.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: internals
- Published: 2026-08-28

---

**An agent calls `takeOverTaskSpace()` to forcibly transfer ownership of a browser task space from the user back to itself, enabling immediate resumption of automation commands.**

In the **ego-lite** browser-automation framework, task spaces represent isolated browsing contexts with strict ownership rules. When a human user takes control of a space, automated operations halt until the agent reclaims it. The `takeOverTaskSpace` helper in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) provides this essential handoff mechanism.

## Understanding Task Space Ownership in ego-lite

ego-lite operates on a **single-owner model**: any given task space is either **agent-controlled** or **user-controlled**, never simultaneously both. This prevents conflicts between automated scripts and manual user interactions.

When ownership transfers to the user (typically through UI interaction), the agent's connection to that space is suspended. Rather than waiting passively, agents can proactively reclaim control using the runtime's ownership-transfer API.

## How `takeOverTaskSpace` Works

The implementation in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 347–354) follows a streamlined four-step process:

1. **Runtime validation** — Verifies the global `ego` object exists and exposes the native `takeOverTaskSpace` method
2. **Target resolution** — Uses `selectTaskSpaceIfProvided` to resolve optional `nameOrId` to a concrete task-space object, or defaults to the active space
3. **Ownership transfer** — Invokes `ego.takeOverTaskSpace()` to execute the runtime-level ownership change
4. **Error surfacing** — Wraps runtime errors via `assertNoEgoError` for clear exception propagation

Notably, the helper **does not verify current ownership status** before attempting transfer. This permissive design allows agents to reclaim spaces even in edge cases where internal state tracking may be inconsistent.

## Using `takeOverTaskSpace` in Practice

### Reclaim the Currently Active Space

```javascript
// Regain control of whatever task space is currently active
await takeOverTaskSpace();

```

### Target a Named Task Space

```javascript
// Reclaim control of a specific space by its assigned name
await takeOverTaskSpace('checkout-flow');

```

### Target by Numeric ID

```javascript
// Directly address a task space using its internal ID
await takeOverTaskSpace(3);

```

## Related Helper Functions

The ego-lite helper suite provides complementary utilities for ownership management:

- **`waitForAgentControl`** — Polls until agent ownership is restored (passive alternative to forced reclaim)
- **`selectTaskSpaceIfProvided`** — Internal utility for resolving space references by name or ID
- **`assertNoEgoError`** — Standard runtime error wrapper used across all helper functions

These functions share the same architectural pattern: thin wrappers around native `ego.*` runtime methods with consistent error handling and TypeScript type safety.

## Source File Reference

| File | Purpose |
|------|---------|
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Contains `takeOverTaskSpace` implementation (lines 347–354) and related ownership helpers |
| [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | Registers helpers in the public API surface |
| [`package/ego-browser/src/taskspace.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/taskspace.ts) | Defines underlying runtime primitives consumed by helpers |

## Summary

- **Control transfer is immediate** — `takeOverTaskSpace` does not wait for user consent or idle states
- **Targeting is flexible** — Accepts string names, numeric IDs, or defaults to the active space
- **No ownership pre-check** — The runtime, not the helper, enforces transfer validity
- **Standard error pattern** — Uses `assertNoEgoError` for consistent exception handling across the helper suite

## Frequently Asked Questions

### What happens if the agent calls `takeOverTaskSpace` on a space it already owns?

The runtime permits redundant ownership transfers without error. The call completes successfully and the space remains agent-controlled, as implemented in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts).

### Can users reject or block an agent's `takeOverTaskSpace` request?

No. According to the source implementation, there is no user confirmation mechanism. The runtime executes the transfer immediately upon agent request, reflecting ego-lite's design priority for autonomous automation workflows.

### How does `takeOverTaskSpace` differ from `waitForAgentControl`?

**`takeOverTaskSpace`** actively forces ownership transfer regardless of current state, while **`waitForAgentControl`** passively polls until control returns naturally (such as when a user releases a space). Both are defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) and serve different recovery strategies.

### Is there any delay between calling `takeOverTaskSpace` and regaining operational control?

No measurable delay is introduced by the helper itself. The synchronous nature of `ego.takeOverTaskSpace()` means subsequent automation commands can execute immediately after the promise resolves.