# claimTaskSpace vs useOrCreateTaskSpace in ego-browser: Task Space Ownership Explained

> Understand the difference between claimTaskSpace and useOrCreateTaskSpace in ego-browser. Learn how to manage task space ownership effectively with ego-lite in Citrolabs.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-07-26

---

**`useOrCreateTaskSpace` selects existing task spaces without transferring ownership from users, while `claimTaskSpace` forcibly claims user-owned spaces before selection to grant the agent full control.**

In the `citrolabs/ego-lite` repository, the `ego-browser` package exposes a façade for isolated browsing contexts called task spaces. Understanding the distinction between `claimTaskSpace` and `useOrCreateTaskSpace` is critical for agents that must respect user boundaries while automating browser interactions.

## Task Space Ownership Models

### Agent-Owned vs User-Owned Spaces

Task spaces carry explicit ownership metadata that determines control privileges. A space is **agent-owned** when `ownership` equals `"agent"` or `"agentDelegatedToUser"`, granting the agent unrestricted access. Conversely, a **user-owned** space (`ownership === "user"`) restricts the agent from performing privileged actions unless ownership is explicitly transferred.

## Core Semantic Differences

### useOrCreateTaskSpace: Selective Access Without Claiming

Implemented in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) at lines 191-215, `useOrCreateTaskSpace` follows a resolution logic that preserves existing ownership:

- Returns a newly created agent-owned space when no match exists.
- Selects the space directly if it is already agent-owned.
- For user-owned spaces, it **selects the space without claiming**, leaving the user in control and allowing the `EGO_TASK_SPACE_USER_IN_CONTROL` error to surface if the agent attempts privileged commands.

### claimTaskSpace: Forced Ownership Transfer

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, `claimTaskSpace` takes an aggressive approach to ownership:

- Resolves the target space and invokes the native `ego.claimTaskSpace` bridge.
- **Transfers ownership from user to agent** before selecting the space.
- Eliminates user-control restrictions, enabling immediate privileged operations.

## Architectural Implementation

Both helpers begin by invoking `listTaskSpaces()` to obtain the current snapshot of spaces. They then use `findMatchingTaskSpace` to locate targets by name or numeric ID. The helper `isAgentOwned` checks the ownership status before determining whether to create, select, or claim.

Key source files implementing these behaviors include:
- [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) – Contains `useOrCreateTaskSpace`, `claimTaskSpace`, and ownership utilities.
- [`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) – Manages singleton runtime state including workspace paths.
- [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) – Defines `EGO_TASK_SPACE_USER_IN_CONTROL` and other error mappings.

## Practical Code Examples

### Safe Selection Respecting User Ownership

```javascript
// Use 'my-space' if it exists. Creates a new agent-owned space if missing.
// If user-owned, selects without claiming (user remains in control).
await taskSpaces.useOrCreate('my-space');

```

### Explicitly Taking Control of a User Space

```javascript
// Forces ownership transfer from user to agent.
// Required before privileged operations on user-created spaces.
await taskSpaces.claim('my-space');

```

### Conditional Claiming Based on Ownership Status

```javascript
const space = await taskSpaces.useOrCreate('work-space');

if (space.ownership === 'user') {
  await taskSpaces.claim('work-space');
}

// Agent now has full ownership
await page.goto('https://example.com/admin');
await page.locator('#action').click();

```

### Switching Between Agent-Owned Spaces

```javascript
// Switches to an existing agent-owned space.
// Throws if the space is user-owned and unclaimed.
await taskSpaces.switch('existing-agent-space');

```

## Summary

- **`useOrCreateTaskSpace`** creates missing spaces or selects existing ones, but **never claims user-owned spaces**, preserving user control and deferring privilege checks.
- **`claimTaskSpace`** **forcibly transfers ownership** from user to agent via the native bridge, enabling immediate privileged access.
- Both helpers rely on `listTaskSpaces()` and `findMatchingTaskSpace` in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) to resolve targets.
- Attempting privileged actions on user-owned spaces selected via `useOrCreateTaskSpace` triggers the `EGO_TASK_SPACE_USER_IN_CONTROL` error defined in [`ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/ego-errors.ts).

## Frequently Asked Questions

### When should I use claimTaskSpace instead of useOrCreateTaskSpace?

Use `claimTaskSpace` when you need to perform privileged actions on a user-created space and have explicit permission to take control. Use `useOrCreateTaskSpace` for general browsing tasks where you want to avoid accidentally seizing control from the user.

### Does useOrCreateTaskSpace ever change ownership of an existing space?

No. According to the implementation in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) lines 191-215, this helper explicitly avoids the native claim bridge for user-owned spaces. It either creates new agent-owned spaces or selects existing spaces while leaving their ownership metadata unchanged.

### What error occurs if I try privileged actions on a user-owned space selected via useOrCreateTaskSpace?

The system throws `EGO_TASK_SPACE_USER_IN_CONTROL`, as defined in [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts). This error signals that the agent attempted an operation requiring ownership while the user retained control of the space.

### Can claimTaskSpace be called on spaces that are already agent-owned?

While technically possible, calling `claimTaskSpace` on an agent-owned space is redundant. The helper is designed specifically for claiming user-owned spaces, as shown in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts) lines 224-236, where it invokes the native bridge unconditionally before selection.