Agent leases
How a lease scopes a trusted coding agent's authority, context, budget, env, and audit while it works in your real project directory.
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
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
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.
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.
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
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
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
- Work with coding agents: a task guide for starting leases locally and on remote hosts.
- Work views: the review-before-apply mode a lease
uses with
--work-view. - Agent-native contract: the full contract for driving Bowline from an agent.
- Agent workflows: prompt recipes and primitive tools agents compose.
- Status and health: how review-ready leases and degraded state appear.