# How to Switch Between Task Spaces Using the Ego‑Lite Ownership Model

> Learn how to switch task spaces in ego-lite. This guide explains the ownership model that secures user-owned browser sessions, preventing unauthorized access and control.

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

---

**Ego‑Lite restricts task space switching to agent-owned contexts through an ownership verification layer that prevents unauthorized control of user-owned browser sessions.**

The `citrolabs/ego-lite` browser automation framework isolates sessions into discrete task spaces governed by a strict ownership model. Switching between task spaces using the ownership model requires understanding how the `switchTaskSpace` helper validates agent permissions before invoking the native bridge. This guide examines the implementation in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) to show you how to safely navigate between spaces while respecting user-control boundaries.

## Understanding Task Space Ownership Types

Ego‑Lite assigns every task space an `ownership` field that dictates control permissions. The three possible values determine whether the agent can switch to and execute commands within a given space:

| Ownership value | Meaning |
|-----------------|---------|
| `"agent"` | Fully owned by the agent – the agent can both select and run commands in the space. |
| `"agentDelegatedToUser"` | Created by the agent but temporarily handed over to the user. The agent may select this space, but command execution respects user-control boundaries. |
| `"user"` | Owned by the user – the agent **cannot** switch to this space without first claiming it via `claimTaskSpace`. |

## The Task Space Switching Workflow

The `switchTaskSpace` function in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) implements a four-step verification process that ensures agents only access spaces they own.

### Step 1: Retrieve the Target Task Space

First, `switchTaskSpace` calls `findTaskSpace(nameOrId)`, which searches the array returned by `ego.listTaskSpaces` to locate the target space object.

### Step 2: Verify Agent Ownership

Before switching, the helper invokes `isAgentOwned(space.ownership)` to validate that the space is either `"agent"` or `"agentDelegatedToUser"`. If the space is `"user"`-owned, the function throws an error:

```js
throw new Error(
  `switchTaskSpace requires an agent‑owned task space, got ownership ${JSON.stringify(space.ownership)}`
);

```

This check occurs **before** any native bridge invocation, ensuring the agent never unintentionally attempts control of a user-owned session.

### Step 3: Invoke the Native Bridge

After verification, the helper calls `ego.useTaskSpace(id)`, passing the numeric identifier of the task space. The bridge enforces additional user-control boundaries during actual command execution.

### Step 4: Return the Resolved Space

Upon successful selection, `switchTaskSpace` returns the original task space object, allowing callers to inspect properties such as `taskId`, `name`, and `ownership`.

## Claiming User‑Owned Task Spaces

When you need to work with a `"user"`-owned space, you must first transfer ownership to the agent. The `claimTaskSpace` function handles this by changing the ownership to `"agent"` and then internally calling `switchTaskSpace`.

This two-phase approach ensures explicit consent before the agent takes control of user-initiated sessions.

## Key Implementation Files

The ownership model and switching logic are distributed across the following source files in the `ego-browser` package:

| File | Role |
|------|------|
| [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) | Contains `switchTaskSpace`, `findTaskSpace`, `isAgentOwned`, and `claimTaskSpace` implementations. |
| [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | Re-exports helpers for agent consumption. |
| [`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) | Maintains the global state object and `ego` bridge reference. |
| [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) | Defines error handling utilities used during ownership violations. |
| `package/ego-browser/src/helpers.test.mjs` | Test suite verifying ownership checks for `switchTaskSpace`. |

## Practical Code Examples

### Switching to an Agent‑Owned Space

Use `switchTaskSpace` directly when working with spaces the agent already owns:

```js
import { listTaskSpaces, switchTaskSpace } from 'ego-browser';

async function switchToSpaceByName(name) {
  // Locate the desired space
  const spaces = await listTaskSpaces();
  const space = spaces.find(s => s.name === name);
  if (!space) throw new Error(`Task space "${name}" not found`);

  // Switch – throws if user-owned
  await switchTaskSpace(space.id);
  console.log(`Switched to task space "${name}" (id=${space.id})`);
}

```

### Claiming and Switching a User‑Owned Space

For user-owned spaces, call `claimTaskSpace` to transfer ownership before switching:

```js
import { claimTaskSpace } from 'ego-browser';

async function claimAndSwitch(nameOrId) {
  // Claim transfers ownership to "agent", then selects the space
  const claimed = await claimTaskSpace(nameOrId);
  console.log(`Claimed and switched to "${claimed.name}" (id=${claimed.id})`);
}

```

## Summary

- **Ownership determines access**: Task spaces marked `"user"` cannot be switched to without claiming.
- **Verification happens first**: The `isAgentOwned` check in `switchTaskSpace` prevents unauthorized bridge calls.
- **Claiming transfers control**: Use `claimTaskSpace` to convert user-owned spaces to agent-owned before switching.
- **Native bridge enforces boundaries**: Even after switching, `ego.useTaskSpace(id)` maintains user-control restrictions for `"agentDelegatedToUser"` spaces.

## Frequently Asked Questions

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

The `switchTaskSpace` function throws an error immediately after detecting the `"user"` ownership value, before calling the native bridge. The error message explicitly indicates that only agent-owned spaces are valid for this operation.

### What is the difference between "agent" and "agentDelegatedToUser" ownership?

An `"agent"` space is fully controlled by the agent for command execution. An `"agentDelegatedToUser"` space was created by the agent but handed off to the user; the agent can select this space, but command execution respects user-control boundaries enforced by the bridge.

### Where is the ownership verification logic implemented?

The ownership check occurs in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) within the `switchTaskSpace` function, which calls `isAgentOwned()` to validate the space's ownership field. This verification happens before any native bridge invocation to prevent unauthorized access attempts.

### Can I claim a task space that is already owned by the agent?

Yes, calling `claimTaskSpace` on an already agent-owned space is safe; the function handles this idempotently and proceeds to switch to that space. This allows you to use `claimTaskSpace` uniformly regardless of current ownership state.