CLI reference

tama session

Who holds the uncommitted edits of each file in a checkout several agent sessions share, and how one session's edits pass to another. The commit review admits a commit only when every staged file is what the committing session's own recorded edits make of it, so a file holding two sessions' uncommitted edits can enter nobody's commit. The edit lease keeps that from happening, and a handover is the way out when it already has.

#The edit lease

The first session to edit a file that is what HEAD holds takes a lease on it in pre-write-edit, before its write lands. While the lease holds, pre-write-edit refuses every other session's edit of the file, after the write has passed every other rule, and names the holder:

edit-lease: BLOCKED: src/main.rs is leased to session first-session, which runs now and has held it since 2026-10-22T01:40:00Z; its uncommitted edits and this session's would enter nobody's commit. Ask that session to commit them, or to hand its edits over to this session: tama session handover --path src/main.rs --from first-session --to second-session

When the holder has ended the refusal says so and that a supervisor hands its edits over. The file's state, the blob HEAD holds at its path and the lease are read under the register's lock. A file that still reads as HEAD does not by that alone end a lease, since the holder's write lands after its pre-write: the lease ends once the file is what HEAD holds after the holder's edits were seen in it, after a commit changed what HEAD holds at the path, after the holder ended, or once the call the holder made on the file has its result while the file is unchanged (another gate refused the call, or the tool failed), and the next session to edit the file takes it. That call is named when the lease is taken: the call on the file in the newest assistant record of the transcript the holder writes now, the one tama stage reads, so a session OMP moved to a new transcript is read there; a path the call gives relative to the session's working directory is resolved against it. Only the end of the transcript, back to the call, is read. A holder whose call still runs keeps a lease on an unchanged file; a holder whose call cannot be named holds it only once its edit is seen. A file that already differs from HEAD with no lease naming it carries edits nobody recorded, so an edit of it is admitted and nobody becomes its holder. A write no recorded session makes, such as one the operator makes in his own shell, takes no lease and is not refused by one. A write whose path is relative and names no working directory, a holder transcript that cannot be read, or a checkout whose lease register cannot be read, is refused with the cause, since whose edits the file holds would otherwise be unknown.

#Invocation

tama session handover --path P --from A --to B [--json]
tama session leases [--repository PATH] [--json]

#Verbs

Verb What it does

handover --path P --from A --to B Passes session A's lease on file P to session B and records the SHA-256 of the bytes P holds now. B's first edit after it builds on those bytes, so the commit review reads B's change of P as including A's edits: B's commit carries them, and the handover names A as the co-author of that change. While A runs, only A hands its own edits over; the edits of a session that has ended are handed over by whoever supervises the work

leases Every file of the checkout under a lease, with its holder and since when, and every handover with who made it and when

Verb	What it does
`handover --path P --from A --to B`	Passes session A's lease on file P to session B and records the SHA-256 of the bytes P holds now. B's first edit after it builds on those bytes, so the commit review reads B's change of P as including A's edits: B's commit carries them, and the handover names A as the co-author of that change. While A runs, only A hands its own edits over; the edits of a session that has ended are handed over by whoever supervises the work
`leases`	Every file of the checkout under a lease, with its holder and since when, and every handover with who made it and when

#Example

$ tama session handover --path src/main.rs --from first-session --to second-session
session first-session's edits of src/main.rs pass to session second-session (content 4f1c…); its commit carries them with first-session as co-author
$ tama session leases
src/main.rs  held by second-session since 2026-10-22T01:52:10Z
src/main.rs  handed from first-session to second-session by first-session at 2026-10-22T01:52:10Z

With --json, handover answers {"path","from","to","content_sha256","by","at"} and leases answers {"leases":{PATH:{"session","since","head_blob","written","call"}},"handovers":[…]}: head_blob is the blob HEAD held at the path when the lease was taken (null when it held no file there), written whether the holder's edits have been seen in the file since, and call the id of the holder's call that is writing it (null when none was named, as after a handover).

#Where it is kept

The register is tama-edit-leases.json in the repository's common Git directory, shared by every index and worktree of the checkout. It is changed under an exclusive lock on tama-edit-leases.lock beside it and replaced whole through a renamed file, so two hooks never interleave their writes.

#Refusal boundary

handover refuses a missing --path, --from or --to, the same session on both sides, a path in no Git checkout, a file that is what HEAD holds (nothing to hand over), a file whose lease names another session than --from or no session, and a handover from a running session made by anyone but that session. leases refuses a directory in no Git checkout. A register that cannot be read or written refuses with its path and cause.

Return to tama reviews or the complete CLI tree.