# 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 using taskSpaces.claim(id) or ego.claimTaskSpace(id, name?). Transfer ownership to your agent for automated interaction.

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

---

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

In the **ego-lite** browser automation library, task spaces represent isolated browsing contexts that can be owned by either the **agent** or the **user**. When a space is user-owned, the agent cannot execute actions like navigation or clicking until it explicitly claims ownership. This guide explains the exact methods and source implementations for transferring control.

## Understanding Task Space Ownership Models

ego-lite implements a strict ownership model to prevent unauthorized automation in user-controlled contexts. A **user-owned task space** is created when a user manually opens a new tab or window, while an **agent-owned space** is spawned by your automation script. The library exposes specific Chrome DevTools Protocol (CDP) calls to manage these transitions safely.

According to the source code in `citrolabs/ego-lite`, the runtime provides two low-level CDP methods on the `ego` object:

- `ego.claimTaskSpace(id, name?)` – Transfers ownership of the task space with numeric ID `id` to the agent
- `ego.takeOverTaskSpace()` – Allows the agent to become the default owner of a newly created space

These primitives ensure that automation only occurs in explicitly claimed contexts.

## Methods to Claim a User-Owned Task Space

### Using the High-Level Helper (Recommended)

The most reliable approach uses the public helper `claimTaskSpace(nameOrId)` defined in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) at lines 224–236. This function accepts either a numeric ID or a string name, resolves it to a task-space object, calls `ego.claimTaskSpace`, and automatically selects the space for subsequent actions.

```javascript
// Claim by numeric ID
const space = await taskSpaces.claim(3);
console.log('Claimed space:', space);

// Claim by string name
const space = await taskSpaces.claim('research-task');

```

### Using Low-Level CDP Calls

For advanced use cases requiring direct protocol access, invoke `ego.claimTaskSpace` directly. This method requires the numeric ID and optionally accepts a name parameter for logging purposes.

```javascript
// Direct CDP call
await ego.claimTaskSpace(7, 'automation-space');

```

### Taking Over Newly Created Spaces

When a user creates a space and you need immediate control before any interaction occurs, use `taskSpaces.takeOver(id?)`. Without arguments, it claims the most recently created space. With a specific ID, it targets that exact context.

```javascript
// Take over the most recent user-created space
await taskSpaces.takeOver();

// Take over a specific space by ID
await taskSpaces.takeOver(5);

```

## Step-by-Step Implementation Workflow

Follow this sequence to safely claim and operate within a user-owned task space:

1. **List available task spaces** (optional) to identify the target ID or name of the user-owned space
2. **Call `taskSpaces.claim`** with the identifier, or use `ego.claimTaskSpace` for low-level control
3. **Verify ownership transfer** – the helper automatically selects the space, but confirm `space.owned === true` in the returned object
4. **Execute automation actions** – use standard helpers like `nav`, `click`, or `type` within the claimed context

## Complete Code Examples

The following patterns demonstrate practical implementations based on the runtime 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):

```javascript
// Example 1: Claim by numeric ID and auto-select
const space = await taskSpaces.claim(3);
console.log('Ownership transferred:', space);

// Example 2: Claim by descriptive name
const space = await taskSpaces.claim('research-task');
console.log('Resolved and claimed:', space);

// Example 3: Direct helper import for standalone usage
import { claimTaskSpace } from 'ego-lite/helpers';
await claimTaskSpace('7');  // Equivalent to taskSpaces.claim(7)

// Example 4: Preemptive takeover of new user space
await taskSpaces.takeOver();  // Claims most recent space before user interaction

```

## Error Handling and Edge Cases

Ownership claims may fail if the space is already agent-owned, the ID does not exist, or the browser context was destroyed. The library wraps CDP errors in user-friendly messages as implemented in [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) (lines 53–61).

```javascript
try {
  await taskSpaces.claim(999);  // Non-existent ID
} catch (error) {
  console.error('Claim failed:', error.message);
  // Handles "Task space not found" or "Already owned" scenarios
}

```

Always verify the returned task space object contains `id` and `url` properties before proceeding with navigation to ensure the claim succeeded.

## Summary

- **Task spaces** in ego-lite are isolated browsing contexts with strict ownership rules separating user and agent control
- Use **`taskSpaces.claim(nameOrId)`** for the simplest resolution and ownership transfer via the helper in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)
- Call **`ego.claimTaskSpace(id, name?)`** directly when you need low-level CDP access without helper abstractions
- Apply **`taskSpaces.takeOver()`** to claim newly created user spaces before any manual interaction occurs
- Check error handling in [`src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ego-errors.ts) for robust automation that handles invalid IDs or ownership conflicts

## Frequently Asked Questions

### Can I claim a task space by its URL instead of ID or name?

No, ego-lite requires either the numeric task space ID or the registered string name to claim ownership. The `claimTaskSpace` helper in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) only resolves these two identifier types. You must first list available spaces to map a URL to its corresponding ID.

### What happens if I try to claim a space already owned by the agent?

The `ego.claimTaskSpace` CDP call will return successfully without error, as the space is already under agent control. However, the helper functions in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) may skip redundant selection steps. Check the returned space object's properties to confirm the current state.

### Is there a way to claim ownership automatically when a user creates a new tab?

Yes, use `taskSpaces.takeOver()` immediately after detecting a new space creation. This method, documented in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts), claims the most recent task space without requiring you to know its ID beforehand. Implement this in an event listener for new tab creation to automate the handoff.

### Why does my automation fail with "Cannot interact with user-owned space" even after claiming?

This error occurs when the claim operation completed but the space selection did not persist. The `taskSpaces.claim` helper should auto-select the space, but if using low-level `ego.claimTaskSpace` directly, you must manually call the selection method afterward. Verify your context by checking `ego.currentTaskSpace` after claiming.