Skip to main content
A task is one running unit of work for an agent. Most product integrations map one user session, conversation, or job to one task.

​
Lifecycle Hooks

The public Python runtime exposes three handlers:
  • @server.on_create
  • @server.on_event
  • @server.on_cancel
There is no public on_complete hook.

​
Typical Flow

  1. Your app creates a task with agent_name or agent_id.
  2. You optionally attach an existing filesystem with filesystem_id, or ask TerminalUse to create one from a project_id.
  3. TerminalUse resolves the target version for the requested branch.
  4. The runtime calls on_create.
  5. Your app sends follow-up events and the runtime calls on_event.
  6. The agent emits messages and updates state.
  7. If the task is cancelled, the runtime calls on_cancel.

​
What Lives On A Task

ResourceScope
MessagesPer task
EventsPer task
StatePer task and agent
System foldersPer task
Filesystem mountShared only if you attach the same filesystem

​
Filesystem Behavior

If a task has a filesystem, TerminalUse syncs that filesystem into /workspace before on_create and on_event, and syncs changes back after those handlers complete. on_cancel is different: the current runtime registers cancel handlers with sync disabled, so you should not rely on writing files in on_cancel and expecting those workspace changes to persist. If the caller can run the task but does not have filesystem update permission, /workspace is mounted read-only. See Access Control.

​
TaskContext

TaskContext gives your handler pre-bound helpers for the current task:
  • ctx.task
  • ctx.agent
  • ctx.messages
  • ctx.state
  • ctx.events
See Building Agents for examples.