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

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 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 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:

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	Contains switchTaskSpace, findTaskSpace, isAgentOwned, and claimTaskSpace implementations.
package/ego-browser/src/index.ts	Re-exports helpers for agent consumption.
package/ego-browser/src/state.ts	Maintains the global state object and ego bridge reference.
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:

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:

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}