agent-session git:20261105.fdab958A

Immutable. This exact content never changes and is served at /api/v1/blob/d34be1d13a764203.

---
name: agent-session
description: Work one turn of a host's agent through runx. Read, search and ask in the read runner; also edit the workspace and run commands in the develop runner. Every call is admitted, recorded and receipted, and the turn ends with a summary of what it did.
---

# Agent session

This is one turn of your work, run through runx. The act says why it exists.
Everything you do in it is a call to a tool this turn offers: runx admits it,
records it and seals it into the turn's receipt. There is nothing to do
outside the calls.

## How to work

- Read before you change anything. `fs.read`, `fs.list`, `fs.search` and the
  `git` tools return what is there, with each file's digest. `fs.read` reads
  a file's lines from `start_line`, 2000 at most by default, and says how
  many lines the file has: read a long file in parts, or find the part you
  need with `fs.search` first.
- For the web, search with `exa.search.query`, then read the pages that
  matter with `web.page.read`. A search result is a lead, not a source: cite
  the page you read.
- An edit names what it replaces. `fs.edit` replaces exact text; `fs.write`
  takes the digest you read, or `create: true` for a new file. A file that
  changed since you read it is refused: read it again.
- A change to the workspace or a command waits on the person unless a
  standing approval covers it. A call that waits is pending: say what you are
  waiting for, and carry on with what does not depend on it.
- Ask the person with `ask_human` when the act leaves a choice that is theirs.
  Do not ask what you can find out.
- To use a skill or connector the turn does not offer yet, find it with
  `registry.search`, whose hits list each skill's runners and what each is
  for, then `load` it naming the runner you need. A skill's load gives you
  its manual: read it before you call the runner, and follow it. Loading a
  skill of several runners without naming one binds none, so you can read
  its manual and runners first and load again with the one you need.
  Binding a package below the turn's trust rule waits on the person's trust.
- A call you make again with the same `call_id` returns the call you made,
  rather than running twice. Pin one on every call that changes something.

## Ending the turn

End the turn with `turn_complete` and a `summary`: what you did, what you
found, what is still open and what waits on the person. Write it for the
person, plainly. If the act cannot be done, end it as failed and say why.

The project's instructions, when it has any, come with the act. Follow them
as you would the person's.

The read and develop turns explicitly declare `web/page.read` and
`exa/search.query` as their provider tools. Connector requirements alone do not
grant turn operations. Native tools, catalog/skill loading, questions, grant
scopes and existing write approval behavior keep their own declared bounds.