Promote opaque actions to typed control points

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

An invoice assistant can use a general shell, but invoice delivery must display the exact invoice and recipient first. The teaching task sends INV-17 to billing@example.test; the host has an approval policy for that pair. It needs to recognize the sending action to apply the policy.

Mechanism

1. Identify effects requiring separate authorization, rendering or auditing and define an action interface. The teaching interface is send_invoice(invoice_id, recipient).
2. The host checks invoice existence, recipient validity and approval for the exact pair, displaying it before sending. Insufficient approval returns an unexecuted state.
3. Bind the approved object to the actual payload so the recipient cannot change after checking. Record action, arguments, approval basis and delivery result.
4. If a general shell can still bypass this gate, constrain the same effect in the execution environment or service.

Bad example

Send INV-17 to billing@example.test by hiding the sending command in the shell tool. Treat it as ordinary command execution; the host need not know it is an invoice delivery.

Good example

Send INV-17 to billing@example.test through send_invoice with the invoice identity and exact recipient. The host first displays and validates existing approval for this pair, then sends that same payload. A failed check returns not sent. Record a verifiable delivery result; generating a tool call is not successful delivery.

Why the change matters

An explicit action and its parameters give the host a stable control point without interpreting arbitrary command strings. The interface also supports dedicated rendering and auditing. Types help express the action; they do not grant permission.

Observable expectation

In the teaching test, approval for INV-17 and its specified recipient permits one send. Changing the recipient to other@example.test must reject with zero sends. A simulated service failure must display failure. Compare audited arguments with the actual request.

Limits

A typed interface does not automatically prevent bypasses, payload changes or repeated delivery; host/service controls and appropriate idempotency are still needed. A shell-aware host can enforce gates too, so the source’s absolute claim is too broad. This method concerns action control points, not dedicated tools for every simple command.