/tessera-cli

name: tessera-cli
description: Operate Tessera-managed Projects, Worktrees, and Sessions through the injected version-matched control CLI. Use when an agent running inside Tessera needs to inspect its caller context, create an isolated Worktree, launch or observe a Session, send a follow-up at a known input boundary, or stop a live runtime.

Tessera CLI

Use Tessera's injected CLI only as a low-level resource-control interface. Keep the user's purpose and success criteria outside Tessera's resource model.

Establish the managed context

1. Check that both `TESSERA_ENV=1` and a non-empty `TESSERA_CLI_COMMAND` are present. If either check fails, stop and explain that this is not a Tessera-managed Session. 2. Treat `TESSERA_CLI_COMMAND` as one executable path. Quote it for every invocation and never pass it through `eval` or split it into shell words. 3. Confirm the exact runtime and caller context before changing resources:

"$TESSERA_CLI_COMMAND" status --json

Use structured `data` and `error` objects instead of scraping human-readable output. Use the bridge's version-matched `--help` at the relevant command level when syntax is unclear; do not infer unsupported flags or rely on this skill as an exhaustive command reference. Never search for runtime descriptors, endpoints, ports, or credentials.

Select resources safely

• Use `--current` only when `TESSERA_PROJECT_ID` was injected and `status --json` confirms that Project in the caller context.
• Otherwise select an existing Project by its exact ID. Display names and filesystem paths are not selectors.
• Create a Worktree only with an explicit new branch name and explicit start point. Never infer either value from the current shell, Project defaults, or UI state.
• Save the returned `worktreeId` and use that exact opaque ID for every later Worktree or Session operation.
• Save the returned `sessionId` and use that exact opaque ID for every later Session operation.
• Do not prompt, send keys to, stop, or otherwise change a pre-existing Worktree or Session unless the user explicitly directs that change.

Create an isolated Worktree with explicit Git inputs:

"$TESSERA_CLI_COMMAND" worktree create --current \
  -b "$new_branch" "$start_point" --json

If `--current` is unavailable, use `--project "$project_id"` with an exact observed Project ID. If preparation fails, preserve the returned resource information, stop the autonomous recipe, and report the structured error. Continue past preparation failure only when the user explicitly requests recovery.

Launch and observe a Session

Choose an explicit provider ID; do not silently inherit the caller's provider. When the user explicitly chooses a Claude Code or Codex model or effort, pass it with `--model` and `--effort`; otherwise omit both options so the provider's own defaults remain in effect. For Codex, pass `--fast` or `--no-fast` only when the user explicitly chooses that service tier. Do not invent a model, effort, or service tier on the user's behalf. For a multiline initial prompt, prefer stdin so shell quoting cannot alter the content:

"$TESSERA_CLI_COMMAND" session launch \
  --worktree "$worktree_id" \
  --provider "$provider_id" \
  --model "$model_id" \
  --effort "$effort" \
  --prompt-file - \
  --json <<'TESSERA_PROMPT'
<initial instructions>
TESSERA_PROMPT

When the user explicitly selects a Codex service tier, add exactly one of `--fast` or `--no-fast` to that command.

The same `--model`, `--effort`, `--fast`, and `--no-fast` options are accepted by `session create`; the stored selection is applied later by `session start` and reapplied when the provider conversation resumes. Model and effort selection currently apply only to `claude-code` and `codex`. Fast selection applies only to `codex`; `--no-fast` is an explicit opt-out and is not equivalent to omitting both flags.

Use `--no-prompt` only when an intentionally empty interactive Session is required. Use `--allow-preparation-failure` only for the explicit recovery case described above.

Wait for an observable lifecycle boundary and then read the current screen:

"$TESSERA_CLI_COMMAND" session wait "$session_id" \
  --for turn-complete --json
"$TESSERA_CLI_COMMAND" session read "$session_id" --json

`turn-complete` means only that the provider ended its current response. It is not proof that the requested work succeeded. Inspect the returned output and the Worktree repository state, including relevant diffs and verification results, before deciding what to report or whether another prompt is needed.

Send follow-up text through the Session prompt operation, preferably from stdin when multiline:

"$TESSERA_CLI_COMMAND" session prompt "$session_id" --file - --json <<'TESSERA_PROMPT'
<follow-up instructions>
TESSERA_PROMPT

Use `session send-keys` only after `session read` or `session wait` shows a specific input or permission boundary. A visible permission prompt is not authorization: obtain user approval before sending a key that grants authority beyond the user's existing request. Send only documented named keys such as `enter`, `escape`, or `ctrl-c`; never use it as a general terminal-input channel.

Stop a live runtime only when the user requests it or the user-approved operation requires cancellation:

"$TESSERA_CLI_COMMAND" session stop "$session_id" --json

After any non-zero response, read the structured error code and details, consult version-matched help if needed, and avoid speculative recovery that would change existing resources.

Archive a Session

Archive an exact Session ID when the user requests it or the authorized work includes retiring that Session:

"$TESSERA_CLI_COMMAND" session archive "$session_id" --json

Archive stops the Session's backing runtimes and preserves its conversation and Worktree, including when it is the Worktree's last Session. Siblings remain active. `session stop` only stops a runtime; it