Tessera CLI

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.