# How claimTaskSpace Transfers Ownership from a User to an Agent in ego-lite

> Learn how ego-lite's claimTaskSpace transfers ownership from user to agent. This helper flips ownership and activates the space for agent operations.

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

---

**The `claimTaskSpace` helper in ego-lite resolves a user-owned task space, invokes the native `ego.claimTaskSpace` bridge to flip the `ownership` field from `"user"` to `"agent"`, and then activates the space with `selectTaskSpace` so the agent can operate inside it.**

In the `citrolabs/ego-lite` repository, agents sometimes need to take control of task spaces that were originally created by a user. The `claimTaskSpace` async helper orchestrates this hand-off in three sequential stages—resolution, native bridge claiming, and activation—providing a clean API for ownership transfer.

## Step‑by‑Step Ownership Transfer Flow

### Resolve the Task Space

Before any ownership change can happen, `claimTaskSpace` must locate the target. It delegates this to `findTaskSpace`, which internally calls `listTaskSpaces` and matches the supplied identifier—either a string name or a numeric id. This resolution step ensures the helper is working with a valid space object that actually exists in the runtime. In [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), this lookup logic is implemented around lines 40‑47.

### Claim the Space via the Native Ego Bridge

Once the space is resolved, the internal `claimResolvedTaskSpace` function takes over (lines 29‑42 in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)). It first validates that the native method `ego.claimTaskSpace` is available. It then extracts the space’s numeric identifier via `taskSpaceNumericId` and calls `ego.claimTaskSpace(id, space.name)`. The Ego runtime performs the actual ownership mutation, updating the space’s `ownership` property from `"user"` to `"agent"` (or in some cases to `"agentDelegatedToUser"`). The return value is normalized and its id is re-checked before proceeding.

### Select the Now‑Claimed Space

After the runtime confirms the ownership switch, `claimTaskSpace` calls `selectTaskSpace` to make the claimed space the active context for the current Node invocation. This helper executes `ego.useTaskSpace(id)` (see lines 45‑51 in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)). Subsequent helper calls—such as `page.goto` or `locator.click`—then operate within this agent-owned context.

## Practical Code Examples

### Claim a Task Space by Name

```typescript
import { claimTaskSpace } from "./helpers.js";

async function takeControl() {
  // "checkout-flow" is a user-owned task space created earlier
  const space = await claimTaskSpace("checkout-flow");
  console.log("Now owned by agent:", space);
}

takeControl();

```

### Claim a Task Space by Numeric ID

```typescript
import { claimTaskSpace } from "./helpers.js";

async function takeControlById() {
  // Assuming the numeric id is 7
  const space = await claimTaskSpace(7);
  console.log("Claimed task space:", space);
}

takeControlById();

```

Both snippets follow the same three-phase flow: resolve the specified space, invoke the native `ego.claimTaskSpace` to flip the `ownership` field, and select the space so that later helper calls act within that context.

## Key Source Files and Helper Functions

Several modules in `ego-browser` cooperate to make the transfer safe and predictable:

- [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) – Houses the public `claimTaskSpace` API and the internal `claimResolvedTaskSpace`, `findTaskSpace`, and `selectTaskSpace` logic.
- [`package/ego-browser/src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/state.ts) – Provides the runtime state singleton used by helpers for workspace paths and active context tracking.
- [`package/ego-browser/src/ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/ego-errors.ts) – Supplies error handling utilities such as `assertNoEgoError`, which guards native bridge invocations against runtime failures.

## Summary

- `claimTaskSpace` is the public async helper that agents use to take over user-owned task spaces.
- It resolves the target space by name or numeric id through `findTaskSpace`.
- Ownership is changed natively via `ego.claimTaskSpace(id, space.name)`, which mutates the `ownership` field from `"user"` to `"agent"`.
- The helper finishes by calling `selectTaskSpace`, which runs `ego.useTaskSpace(id)` to activate the claimed context.
- Supporting infrastructure in [`helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/helpers.ts), [`state.ts`](https://github.com/citrolabs/ego-lite/blob/main/state.ts), and [`ego-errors.ts`](https://github.com/citrolabs/ego-lite/blob/main/ego-errors.ts) ensures the process is robust and errors are caught early.

## Frequently Asked Questions

### What happens to the ownership field when `claimTaskSpace` is called?

The Ego runtime updates the space’s `ownership` property from `"user"` to `"agent"` or `"agentDelegatedToUser"` when the native `ego.claimTaskSpace` method succeeds. This mutation happens inside the runtime, not in the helper itself.

### Can `claimTaskSpace` resolve a task space by both name and numeric id?

Yes. The helper accepts either a string name or a numeric id. Internally, `findTaskSpace` calls `listTaskSpaces` and matches the identifier, returning the full space object needed for the claim step.

### What native method actually performs the ownership transfer?

The native bridge method `ego.claimTaskSpace` performs the actual transfer. The helper validates its existence, builds the call with `taskSpaceNumericId(id)` and `space.name`, and then normalizes the result.

### Does `claimTaskSpace` automatically activate the claimed space?

Yes. After a successful claim, the helper automatically invokes `selectTaskSpace`, which executes `ego.useTaskSpace(id)` to set the space as the active context for the current invocation.