---
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.
- 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`, read it with `registry.inspect`, then `load` it. 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.