Tool runners and execution contracts

A tool runner accepts a defined task, provides the environment it needs, and reports the outcome. The runner may live on a developer machine, a test worker, or managed infrastructure. Its contract should explain the boundary between requesting work and proving that work completed.

Make execution predictable

Specify valid inputs, allowed targets, deadlines, and output locations before starting a task. Keep setup separate from the actual action. A runner should make it possible to tell whether a failure came from configuration, unavailable infrastructure, the target application, or the action itself.

A practical sequence

• Validate the request before creating expensive resources.
• Prepare an isolated session with only the needed permissions.
• Run named steps with explicit timeout and cancellation behavior.
• Release resources and return a structured result.

Watch for this failure mode

Automatically retrying every failed task can repeat a side effect. Decide which actions are safe to repeat, whether a previous attempt might have succeeded, and how the caller can recognize duplicated work.

Make the handoff clear

Write a small execution checklist for a new runner: startup, permissions, state, cleanup, logging, and result shape. Test failure during setup as well as failure halfway through the workflow. Resource cleanup belongs in the design from the beginning.

Before expanding the workflow, write one representative success case and one useful failure case. Agree on the result shape and how a reviewer should decide whether the next step can proceed. Keep the example small enough that the assumptions remain visible.

Go deeper

Read the complete tool runners guide for examples and design decisions. Connect this step to structured logs, or return to the workflow library to map the whole sequence.