# Agent leases (/docs/concepts/agent-leases)



A trusted coding agent works in the real project directory by default, the same
`~/Code/acme/web` you use. It does so under a lease: a scoped, audited grant that
defines the task, what the agent can read and write, its hydration budget, its
env, and when it expires. The lease is the machinery that lets an agent share
your workspace reality safely, while you keep using normal shell, editor, and Git
tools above the product fold.

## What a lease scopes [#what-a-lease-scopes]

A lease turns an outcome ("fix the auth callback race in `~/Code/acme/web`")
into a bounded run. Bowline compiles that outcome into a context bundle,
primitive tools, a budget, and a write target. The default write target is the
real project directory; a work view is the explicit isolation mode.

A lease records, at minimum:

| Field              | What it scopes                                                                  |
| ------------------ | ------------------------------------------------------------------------------- |
| `task`             | The outcome the agent is working toward.                                        |
| `read_scope`       | Which projects and paths the agent may read.                                    |
| `write_scope`      | `direct project` (real path) or an isolated work-view overlay.                  |
| `hydration_budget` | How many bytes the agent may hydrate during the run.                            |
| `env`              | The inherited project env profile, with secret values kept out of prompts.      |
| `expires_at`       | When the lease ends.                                                            |
| `output_target`    | Where the agent's result lands: a Workspace Snapshot or a review-ready overlay. |

Secret values never enter prompt text. The prompt receives env key names, source
files, materialization mode, and grant identifiers; runtime env and tools
receive the actual values only when policy permits. Policy changes, blocked
paths, and local-only files are off-limits to the agent's judgment.

## Overlays and how output lands [#overlays-and-how-output-lands]

The writes an agent makes under a lease form an Agent Overlay: isolated writes
from the lease before they advance the Workspace Head or become part of a
conflict. What happens next depends on the write scope.

For a direct lease, the edits enter the normal local write log on the real
project path. A non-conflicting Agent Overlay becomes a new Workspace Snapshot
and advances the Workspace Head automatically. No Git publish required.
Diverging edits become a Sync Conflict instead, handled like any other conflict.

For a work-view lease (`--work-view`), the Agent Overlay stays isolated in a work
view and never touches the main project until you accept it.

A completed lease whose output needs your review is a Review-Ready Agent Lease.
It surfaces in `bowline status` and `bowline work` immediately, and Bowline can
send a native notification for it only when you started, followed, or are already
viewing that work.

<Callout type="info">
  A non-conflicting direct lease advances the Workspace Head on its own. Git
  publish is a separate, later step in your own workflow. Bowline never commits,
  branches, or pushes for the agent.
</Callout>

## Lease lifecycle [#lease-lifecycle]

You create and drive a lease through the `bowline agent` commands. Creation
returns the exact context and prompt commands to use next, so a driving agent
never has to scrape prose. Mutating commands accept `--dry-run` and
`--idempotency-key <key>`, and most accept `--json`.

| Stage              | Command                                           | What it does                                                                      |
| ------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------- |
| Create             | `bowline agent start [project] --task <task>`     | Create a lease (alias `agent lease create`); returns context and prompt commands. |
| Read context       | `bowline agent context --lease <id>`              | Return the structured context bundle for the run.                                 |
| Render prompt      | `bowline agent prompt --lease <id>`               | Render the redacted task prompt for the agent.                                    |
| Extend budget      | `bowline agent budget --lease <id> --add <bytes>` | Add hydration budget to a running lease.                                          |
| Publish for review | `bowline agent publish --lease <id>`              | Publish the lease output as a Review-Ready Agent Lease.                           |
| Complete           | `bowline agent complete --lease <id>`             | Signal completion, partial completion, or a blocked state.                        |

`bowline agent start` accepts `--base <base>` to pin the base snapshot,
`--hydrate-budget <bytes>` to set the initial budget, and `--work-view` to route
writes into an isolated work view instead of the real path.

## Hydration budget [#hydration-budget]

Broad recursive reads are not free, so every lease carries a hydration budget.
The agent hydrates bounded paths under that budget rather than pulling the whole
project, and it's expected to use index-backed search before broad reads. When a
run needs more, you grant it explicitly with
`bowline agent budget --lease <id> --add <bytes>`. A degraded workspace state
stops risky agent actions, so a lease that can't safely continue surfaces in
status instead of pressing on.

## Staying below the product fold [#staying-below-the-product-fold]

The lease, context bundle, overlays, and budgets are machinery, not a surface you
manage by hand. Humans use the real `~/Code` tree with normal tools; the lease
exists so an agent can share that reality without new ceremony. You review an
agent's output the same way you review your own work (open the folder, run the
tests, and accept or discard) rather than learning a workflow console.

## Next steps [#next-steps]

* [Work with coding agents](/docs/guides/working-with-agents): a task guide for
  starting leases locally and on remote hosts.
* [Work views](/docs/concepts/work-views): the review-before-apply mode a lease
  uses with `--work-view`.
* [Agent-native contract](/docs/agents/contract): the full contract for driving
  Bowline from an agent.
* [Agent workflows](/docs/agents/workflows): prompt recipes and primitive tools
  agents compose.
* [Status and health](/docs/concepts/status-and-health): how review-ready leases
  and degraded state appear.