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

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 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 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 – Contains useOrCreateTaskSpace, claimTaskSpace, and ownership utilities.
• package/ego-browser/src/state.ts – Manages singleton runtime state including workspace paths.
• 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

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

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

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

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

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 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. 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 lines 224-236, where it invokes the native bridge unconditionally before selection.

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