# How to Claim Ownership of a User-Owned Task Space in ego-lite

> Learn how to claim ownership of a user-owned task space in ego-lite with taskSpaces.claim or ego.claimTaskSpace. Transfer control to your agent for automated browsing.

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

---

**To claim ownership of a user-owned task space in ego-lite, call `taskSpaces.claim(nameOrId)` or the low-level `ego.claimTaskSpace(id, name?)` to transfer control from the user to the agent, enabling automated interaction within that isolated browsing context.**

In the citrolabs/ego-lite browser automation framework, a **task space** represents an isolated browsing context that operates under discrete ownership. When a space is user-owned, the agent cannot execute actions within it until it explicitly claims ownership through specific CDP (Chrome DevTools Protocol) calls or helper methods. Understanding how to claim ownership of a user-owned task space in ego-lite is essential for agents that need to interact with pages initiated or controlled by human users.

## Understanding Task Space Ownership Models

ego-lite distinguishes between two ownership states for task spaces:

- **Agent-owned spaces**: Created and controlled automatically by the automation framework
- **User-owned spaces**: Initiated by human users or external processes, requiring explicit transfer before agent interaction

According to the source code in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 701-713), the runtime API exposes ownership transfer methods through the `taskSpaces` namespace, while low-level CDP interactions are handled directly on the `ego` runtime object.

## Core Methods for Claiming Ownership

The library provides multiple abstraction levels for claiming task spaces, from low-level CDP calls to high-level helper functions.

### Low-Level CDP Calls

For direct control without helper abstractions, the `ego` runtime exposes two critical methods:

- `ego.claimTaskSpace(id, name?)` – Transfers ownership of the task space with numeric ID `id` to the agent, with an optional name parameter for identification
- `ego.takeOverTaskSpace()` – Allows the agent to become the default owner of a newly created space immediately upon creation

These methods are implemented as raw CDP calls to the underlying browser instance and form the foundation of the ownership transfer mechanism.

### High-Level Helper API

The public helper `claimTaskSpace(nameOrId)` in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 224-236) provides the most common interface for ownership transfer. This helper:

1. Resolves the supplied identifier (numeric ID or string name) to a task-space object
2. Invokes `ego.claimTaskSpace` with the resolved parameters
3. Automatically selects the space for subsequent actions

As documented in the runtime API generation logic, this corresponds to the `taskSpaces.claim` entry point.

### Taking Over Newly Created Spaces

For spaces freshly created by users, the `taskSpaces.takeOver(id?)` method offers a streamlined approach. When called without arguments, it claims the most recently created user-owned space, making it ideal for reactive automation scenarios where users initiate actions that agents must immediately continue.

## Step-by-Step Implementation Guide

Follow this workflow to claim and activate a user-owned task space:

1. **Enumerate available spaces** (optional) to identify the target ID or name of the user-owned space
2. **Invoke the claim method** using either `taskSpaces.claim(identifier)` or the direct helper `claimTaskSpace(identifier)`
3. **Verify ownership transfer** – the helper automatically switches to the claimed space, but verify the returned space object confirms successful transfer

If working with a newly created space, substitute step 2 with `taskSpaces.takeOver()` to claim the most recent addition.

## Practical Code Examples

### Claim by Numeric ID

```javascript
// Transfer ownership using the high-level API
const space = await taskSpaces.claim(3);
console.log('Claimed space:', space);
// Agent can now navigate, click, and interact within this space

```

### Claim by String Name

```javascript
// Resolve name to ID internally before claiming
const space = await taskSpaces.claim('research-task');
console.log('Claimed space:', space);

```

### Direct Helper Invocation

```javascript
// Equivalent to taskSpaces.claim(7) but imported directly from helpers
import { claimTaskSpace } from 'ego-lite/helpers';

await claimTaskSpace('7');
// Space 7 is now active and owned by the agent

```

### Taking Over Newly Created Spaces

```javascript
// Become owner of the most recent user-created space
await taskSpaces.takeOver();
// Immediate interaction possible without knowing the specific ID

```

## Error Handling and Edge Cases

The [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) file (lines 53-61) implements error wrapping for failed ownership transfers. When `ego.claimTaskSpace` encounters invalid IDs, already-claimed spaces, or permission conflicts, the runtime generates structured error objects that include:

- The original CDP error context
- The attempted space identifier
- Suggested resolution steps

Always wrap claim attempts in try-catch blocks when dealing with dynamic space IDs to handle scenarios where the user has already released the space or the ID has changed.

## Summary

- **User-owned task spaces** require explicit ownership transfer before agent interaction in ego-lite
- **Two abstraction levels** exist: low-level CDP calls (`ego.claimTaskSpace`, `ego.takeOverTaskSpace`) and high-level helpers (`claimTaskSpace`, `taskSpaces.claim`)
- **Automatic space selection** occurs when using the helper API, immediately enabling `nav`, `click`, and other browsing actions
- **Source implementation** resides in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 224-236) with API documentation in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 701-713)
- **Error handling** is centralized in [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) for debugging ownership conflicts

## Frequently Asked Questions

### What happens if I try to interact with a user-owned space without claiming it first?

The agent will receive a permission error indicating the space is under user control. According to the error handling implementation in [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts), the runtime throws a controlled exception preventing any `nav`, `click`, or evaluation operations until `claimTaskSpace` or `takeOver` successfully transfers ownership.

### Can I use a space name instead of a numeric ID when claiming ownership?

Yes. The `claimTaskSpace(nameOrId)` helper in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) accepts either format. When a string name is provided, the helper resolves it to the internal numeric ID before calling `ego.claimTaskSpace`, making the API flexible for human-readable space management.

### What is the difference between `taskSpaces.claim` and `taskSpaces.takeOver`?

`taskSpaces.claim(id)` requires you to specify the exact space identifier (name or ID) you want to own, regardless of when it was created. `taskSpaces.takeOver(id?)` specifically targets newly created spaces—when called without arguments, it claims the most recent user-owned space, making it ideal for reactive workflows where the user just opened a new tab or context.

### How do I verify that ownership transfer was successful?

The helper methods return a space object containing the confirmed ID and ownership state. Check the returned object’s properties to verify the transfer. If the promise resolves without error, the space is immediately active and selected for subsequent operations, as implemented in the resolution logic at lines 224-236 of the helpers module.