# How to Claim a User-Owned Task Space in Ego-Lite: Complete SDK Guide

> Learn how to claim a user-owned task space in Ego-Lite with our SDK guide. This article explains the claimTaskSpace helper and ego.claimTaskSpace() for agent ownership transfer.

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

---

**To claim a user-owned task space in Ego-Lite, invoke the `claimTaskSpace(nameOrId)` helper, which resolves the space identifier, calls `ego.claimTaskSpace()` to transfer ownership from the user to the agent, and activates the context via `ego.useTaskSpace()`.**

In the Ego-Lite browser automation framework, task spaces represent isolated execution contexts that can be owned by either the user or the agent. When a task space is user-owned, the runtime restricts agent operations until ownership is explicitly transferred through the claiming mechanism.

## Understanding Task Space Ownership

Ego-Lite supports two distinct ownership models for task spaces. When a space is agent-owned, the agent has immediate operational access. However, when a task space is user-owned, the agent cannot perform actions until it **claims** the space. This security boundary ensures agents cannot interfere with user-controlled contexts without explicit authorization.

The ownership transfer mechanism is exposed through the public helper function `claimTaskSpace()`, implemented in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 18-27) and exported as part of the official SDK surface in [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) (lines 24-33).

## The `claimTaskSpace` Implementation

According to the Ego-Lite source code, the claiming process follows a specific four-step sequence to safely transfer control:

### Step 1: Resolve the Task Space

The helper accepts either a string name or numeric ID as `nameOrId`. It first validates the input by calling `findTaskSpace(nameOrId)`, which looks up the space and returns its metadata.

### Step 2: Transfer Ownership via the Runtime

After resolution, the function invokes the runtime method `ego.claimTaskSpace(id, name)`. This internal call performs the actual ownership transfer from the user to the agent, updating the runtime state to reflect the new ownership model.

### Step 3: Select the Claimed Space

Immediately following the ownership transfer, the helper calls `ego.useTaskSpace` to select the newly claimed space as the active context for the current invocation. This ensures subsequent browser automation commands operate within the correct isolated environment.

### Step 4: Return Normalized Metadata

Finally, the function returns the normalized task-space object, allowing the caller to access metadata and confirm successful claiming.

## Code Examples: Claiming Task Spaces

Claim a user-owned task space by its string name:

```javascript
// Claim a user-owned task space by name
const space = await claimTaskSpace('my-user-space');
console.log('Claimed task space:', space);
// The agent now has full control over the space

```

Claim using a numeric identifier:

```javascript
// Claim by numeric id
const space2 = await claimTaskSpace(42);
console.log('Claimed by id:', space2);

```

## Complete Agent Workflow Integration

In production scenarios, claiming a task space typically follows this integrated pattern:

```javascript
// 1. List available task spaces (optional discovery)
const spaces = await listTaskSpaces();
console.log('Available task spaces:', spaces);

// 2. Claim a specific user-owned space
await claimTaskSpace('support-ticket-123');

// 3. Execute automation actions within the claimed space
await navigate('https://example.com');
await click('@login-button');

// 4. Complete the task and optionally preserve the space
await completeTaskSpace('support-ticket-123', { keep: true });

```

## Summary

- **User-owned spaces require explicit claiming** before agents can operate on them, enforcing security boundaries in the Ego-Lite runtime.
- **The `claimTaskSpace(nameOrId)` helper** handles the complete lifecycle: resolution, ownership transfer via `ego.claimTaskSpace()`, and activation via `ego.useTaskSpace()`.
- **Implementation resides in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)** (lines 18-27) and is exported through [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) (lines 24-33) as part of the official SDK.
- **Supports both string names and numeric IDs** for flexible space identification.
- **Returns normalized metadata** to confirm successful ownership transfer.

## Frequently Asked Questions

### What happens if I try to operate on a user-owned task space without claiming it first?

The Ego-Lite runtime will block agent operations and throw a permission error. The `ego.claimTaskSpace()` runtime method must complete successfully before the agent gains execution privileges within that context.

### Can I claim a task space using either its name or its ID?

Yes, the `claimTaskSpace(nameOrId)` helper accepts either a string name (e.g., `'support-ticket-123'`) or a numeric ID (e.g., `42`). The function internally calls `findTaskSpace()` to resolve the identifier before proceeding with the ownership transfer.

### What is the difference between `claimTaskSpace()` and `useTaskSpace()`?

`claimTaskSpace()` is a high-level helper function that performs ownership transfer from user to agent, while `useTaskSpace()` is a lower-level runtime method that simply selects an already-claimed space as the active context. The helper function internally calls both `ego.claimTaskSpace()` and `ego.useTaskSpace()` to provide a complete claiming workflow.

### How do I release a task space back to the user after claiming it?

Use the `completeTaskSpace(nameOrId, options)` helper with the `keep` parameter set according to your persistence needs. Setting `{ keep: true }` preserves the space state while returning ownership to the user, whereas omitting or setting `keep: false` closes the space entirely.