Agents & sessions

Agent definitions

Palette → Agents. Each definition (claude / opencode / Cursor builtin) is a droppable agent-def node.

• Pick a model in the inspector (required for detached runs).
• Wire a prompt (or iterator items) into the agent.
• Optional: wire a session as continuation. The agent reuses that conversation.
• Claude: optional permission mode (plan, acceptEdits, bypassPermissions, …). Passed as --permission-mode.
• Codex: optional sandbox / ask for approval. Override the default workspace-write / never.

Elevated settings show on the agent subtitle and under Security → workflow agent settings.

Plan usage on the card

Claude agent-def nodes can show a small usage chip when a plan window is hot (≥90%) or exhausted (100%). E.g. 7d 100% · 5h 94%. Hover for reset times.

Window	Source
5h · 7d (weekly) · Opus 7d	Mirrored from ~/.claude.json (same tiles as Statistics)

Cursor / Grok / other providers do not expose remaining % on disk. Their model pools are typically monthly (Cursor Spending). When a CLI run hits a limit, the run log gets a clear line instead:

! model usage exhausted (Other Models pool) — pick another model on the agent …

Claude also preflights before a run: if the relevant window is already at 100%, the node fails with that message without shelling out. Pick another model on the card, wait for reset, or (Cursor) raise Spending / switch pool.

See Costs & billing · Errors & retries.

Running creates a real session through the provider CLI. On the canvas, a result session node can appear and stay linked.

Happy path vs error connector

Upper out · lower red err. Hover ports for out / err · after retries exhausted.

Agent nodes expose two text outs on the right edge:

Handle	Canvas	When
out (default)	Upper connector · provider color	Successful reply
out:err	Lower connector · red · red wire	Failure text after per-node retries are exhausted

Hover a connector for a short hint (in · out · err · after retries exhausted).

Wire out:err to a fallback convert, Judge, or output. When that handle is wired, final failure no longer aborts the whole run. The err arm continues and the happy-path arm starves. Unwired err keeps the old halt (or continueOnError starve) behavior.

Graph lint hints when you set continue on error without wiring out:err.

threadle run agent-err-fallback

See Errors & retries.

Sessions

Existing sessions from discovery are first-class nodes. Double-click for transcript, files, context pressure.

Use them as:

• sources for context extract
• targets for inject / handoff
• continuation links for agents

threadle reads provider storage. It does not rewrite transcripts.