# Changing a session's scope

A session's scope is what it works on: its repositories, and the applications on them, its tasks
and its bug reports. You can change it at any time until the session is **Completed** or **Rolled
Back**: while the agent plans or builds, while it waits for your answer, between steps, in a Live
session and in a Code conversation. You don't need to stop or cancel the session, and the agent is
told about every change you make.

<Availability permission="Sessions: Update to add and remove a session's repositories, tasks and bug reports, and to answer the agent's request for a repository." />

## Key concepts

**Scope.** The repositories, tasks and bug reports a session works on. Adding an application adds
its repository, and removing a repository removes the applications on it. Only the sandbox stays as
it was once the agent has started. See
[Starting a session](/user-guide/sessions/starting-a-session#how-starting-a-session-behaves).

**Told.** The agent hears about each change. While it works, it hears about it in the step it's on:
Claude Code after its next round of actions, such as reading files or running commands, and Codex
the next time it uses one of Productmind's tools. Otherwise it's told at the start of its next step.

**Leaving.** A repository you remove after the agent has started leaves when the current step ends.
Changes the agent hasn't pushed yet are pushed to its working branch first, with no pull request,
and then its copy is deleted.

## The scope at a glance

The chips under the session's tabs show its repositories, and its tasks or bug reports. While a
change is on its way to the agent, the chip says so.

A repository you added after the agent started shows where it is:

| The chip says | It means |
| --- | --- |
| **Adding...** | It's being copied next to the agent's work, in the background. The agent is told once it's there. |
| **Joins at next step** | Nothing is running for the session right now, so the next step copies it, and the agent is told then. |
| **Added** | It's copied, and the agent is told shortly. |
| **Copy failed** | Copying it failed. Point at the mark to see why. It's tried again at the next step. |

A repository you removed is crossed out until it has left. It reads **Leaving**, with where it is
when you point at the mark, such as **Saving its changes...**, or **Save failed** if its changes
couldn't be pushed.

A task or bug report you added shows a dot until the agent has been told: point at it to read **Not
told yet**.

Each change also shows in the session's conversation, for example **Repository added**, with the
repository and its branch.

## Adding to the scope

### To add a repository while the agent works

1. On the session page, choose **Add a base repository** (the **+**) beside the repositories.
2. Search for an application or a repository, and select it.

The repository joins the session on the session's working branch, and the agent gets a copy of it
next to its work. Once the agent knows, the chip looks like the others. A repository added while the
agent builds is published with the rest of that step's work, with its own pull request.

Until it has been copied, you can still change its base branch or make it read-only. If an
application on it is read-only, it joins read-only. See
[Read-only repositories](/user-guide/sessions/working-in-a-session#read-only-repositories).

### To add a task or bug report while the agent works

1. Choose **Add tasks to the session** or **Add bug reports to the session** (the **+**).
2. Select them, and choose **Add N tasks** or **Add N bug reports**.

The task joins the session and moves forward: to **In Planning** while the agent plans, or to **In
Progress** while it builds and in a Live session. A bug report added to a bug fix session moves to
**In Progress** if it is still **Open**, **In Review** or **Confirmed**. A Code conversation moves
nothing. The agent is told, with the item's description.

If a task you add is in an application whose repository the session doesn't have, a message offers
to add that too, for example **Add acme/web too?**: choose **Add**. **Add a base repository** also
lists it under **Suggested**. It isn't added on its own, because a repository changes what the agent
can push to.

If another session is working on the task, you're asked first, for example **Move TASK-12 here?**.
Choose **Move here** to take the task out of that session and add it to this one: that session's
agent is told the task left. Or choose **Open SSID-4 instead** to continue it there. A bug report
that's in another unfinished session can't be added until you remove it from that session.

## Removing from the scope

### To remove a repository while the agent works

1. On the repository's chip, choose **Detach repository** (the **x**).
2. Read what removing it does, and choose **Remove repository**.

The confirmation lists what's at stake:
- the agent is told the repository is no longer part of the session;
- an open pull request on it stays open, but the session stops tracking it;
- changes not pushed yet are pushed to its working branch, with no pull request, before its copy is
  deleted. A read-only repository has nothing to save;
- while a step runs, the repository leaves when that step ends;
- a running live preview keeps serving it until the preview restarts.

Once it has gone, the conversation says so, for example **Saved acme/api's changes to
task/add-csv-export and removed it from this session.**

A repository the agent hasn't been told about yet, such as one that still reads **Adding...** or
**Joins at next step**, is removed at once, without a confirmation.

### To keep a repository you removed

While a removed repository's chip still reads **Leaving** or **Save failed**:

1. On its chip, choose the **...**.
2. Choose **Keep repository**.

The repository is back in the session as it was, with its branch, its read-only setting and its pull
request. If the agent had already been told it was leaving, it's told it stays. Adding the same
repository again does the same.

### To remove a repository without saving its changes

If pushing a removed repository's changes fails, for example because a branch rule refuses the push,
its chip reads **Save failed** and the conversation says why. Its copy is kept aside, and saving is
tried again at the next step. To give up on those changes instead:

1. On the chip that reads **Save failed**, choose the **...**.
2. Choose **Remove without saving...**, then **Remove without saving**.

The next step deletes the copy and pushes nothing. The conversation shows **Repository removed
without saving**.

:::caution
The changes that weren't saved are lost. This can't be undone.
:::

### To remove a task or bug report while the agent works

1. On the task's or bug report's chip, choose the **x**.
2. Choose **Remove**.

The confirmation says what happens, for example **TASK-12 leaves this session. The agent is told.
Its status goes back to To Do.** The agent is told to stop working on it, and the work it already did
for it stays on the session's branch. The status goes back to the one it had before this session
moved it, unless it has since left the statuses a session sets, for example once it's **Done** or
**Closed**, or another unfinished session also holds it. The task's or bug report's history notes the
removal. See [Tasks](/user-guide/tasks#how-tasks-behave) and
[Bug reports](/user-guide/bug-reports#how-bug-reports-behave).

## Answering the agent's request for a repository

When the agent needs a repository the session doesn't have, it can ask you to add it, the way it asks
a question: while it plans, and while it builds, until it opens its pull requests. The session's
status becomes **Awaiting User Input**, and a window shows the repository, the applications on it and why
the agent needs it.

### To answer the agent's request for a repository

1. Read the agent's reason.
2. To let the agent only read the repository, turn read-only on. If an application on the repository
   is read-only, it can only be added read-only.
3. Optionally, enter a note for the agent.
4. Choose **Add repository** (**Add read-only** when read-only is on), or **Decline**.

When you add it, the repository is added as you, with the same checks as when you add one yourself,
and the agent carries on with it. When you decline, the agent carries on without it, and reads your
note. If it asks for a repository you removed that hasn't left yet, the window offers to keep it
instead.

The agent can only ask for the repository of one of your workspace's applications. In a Code
conversation, which can't pause, it asks in its reply instead.

## How scope changes behave

**The sandbox stays.** Once the agent has started, the session's sandbox can't change, and a
repository that one of the sandbox's applications runs from can't be removed.

**A change you undo is never told.** If you add something and remove it again, or remove a
repository and keep it, before the agent was told, the agent hears about neither.

**No runner is started for a change.** An added repository is copied, and a removed one saved and
deleted, by the step that is running, or between steps by the runner or Productmind agent already up
for the session. When there is none, the next step does it.

**Statuses follow the scope.** A task or bug report you add moves forward as described above, and
one you remove goes back. A task works in one session at a time, so adding one that another session
is working on asks you to move it. See [Code](/user-guide/sessions/overview#how-sessions-behave).

**A running live preview keeps its applications.** Restart the preview to include an added
repository's applications. A removed repository the preview serves stays until the preview stops or
restarts. See [Live preview](/user-guide/sessions/live-preview#how-live-previews-behave).

**The Productmind agent on your machine must be up to date.** For a session that runs on your
Productmind agent, removing a repository and the agent's requests for one need a current version of
the agent. Adding works with every version, but an older agent gets the added repository, task or
bug report only at its next step. See [Productmind CLI](/user-guide/tools/productmind-cli).

**A session your AI coding assistant works over MCP** reads its scope from Productmind when it asks
for it. Removing a repository from it saves nothing: your assistant keeps its own copy.

**Every change is in the audit log**, with who made it. See
[Audit log](/user-guide/settings/identity-and-access/audit-log#how-the-audit-log-behaves).

## Permissions

| To | You need |
| --- | --- |
| See a session's scope | **Sessions: Read** |
| Add or remove a session's repositories, tasks and bug reports | **Sessions: Update** |
| Keep a removed repository, or remove it without saving | **Sessions: Update** |
| Answer the agent's request for a repository | **Sessions: Update** |

## Troubleshooting

### Removing a repository says the Productmind agent is too old

The session runs on a Productmind agent whose version can't save a removed repository's work, for
example "The Productmind agent on my-laptop is too old to remove a repository from a session it is
working on". The repository stays in the session. A run of a session with a repository still leaving
it is refused the same way. Update the CLI on that machine as described in
[Updating the CLI](/user-guide/tools/productmind-cli#updating-the-cli), then try again.

### A repository can't be removed because the sandbox's application runs from it

The message names the application, for example "acme/web runs APP-1, an application of this
session's sandbox". The sandbox stays as it was once the agent has started, and its applications run
from their repositories, so the repository stays. To work without it, start a new session with
another sandbox.

### A repository can't be added while another one is leaving

The message says, for example, "acme/web is still leaving this session, and its copy uses the same
folder as other-org/web". Two repositories with the same name can't be in the session at once. Try
again once the leaving one has gone, when the current step ends.

### "This session is finished: its repositories, tasks and bug reports can no longer change."

The session is **Completed** or **Rolled Back**, so its scope is final. Start a new session for more
work.

## Related topics

- [Working in a session](/user-guide/sessions/working-in-a-session)
- [Starting a session](/user-guide/sessions/starting-a-session)
- [Live preview](/user-guide/sessions/live-preview)
- [Tasks](/user-guide/tasks)
- [Bug reports](/user-guide/bug-reports)
- [Productmind CLI](/user-guide/tools/productmind-cli)
