Shimpz
request_approval

Ask before one externally visible action

Use approval when the Action already has every value it needs, but the human must explicitly authorize the described action. Approval is attributable, one-use, and bound to this exact Assistant, Action, and request.

Practical example

Describe the action, then perform it

actions/publish_dns.py python 
from typing import TypedDict

from shimpz import Context, action, domain, text


class PublishedDns(TypedDict):
    id: str
    status: str


@action(
    human_requests=["approval"],
    description="Publish a reviewed DNS change to one of your zones.",
)
async def run(zone: str, *, ctx: Context) -> PublishedDns:
    ctx.request_approval(
        title=text("Publish the reviewed DNS change"),
        description=text("Create the approved records in {zone}.", zone=domain(zone, max_length=253)),
    )

    # The externally visible action happens only after approval.
    return await publish_dns_change(zone)

request_approval returns None only after approval. Do not branch on a Boolean result: denial, dismissal, cancellation, or expiry terminates the Action and never reaches the next line. The final provider helper is illustrative Creator code.

Action // approval

Publish the reviewed DNS change

Create the approved records in example.com.

Action publish-dns from Example Assistant v1.0.0 needs human validation. Expires in 300 seconds.

Native, non-submitting documentation preview using the same frontend primitives as Shimpz. Approval presents the exact consequence before the human makes a one-use decision. Controls are disabled and nothing is submitted.
Request copy

Make the consequence obvious without hidden context

  • title: an imperative summary of the action, at most 80 characters.
  • description: the target, scope, and consequence, at most 500 characters.
  • Write both as shimpz.text request copy; each parameter counts at its declared maximum, and the human sees the copy in their interface language.
  • Name the target with a typed parameter, such as the zone above, so the scope survives translation exactly.
  • Do not place secrets, tokens, internal prompts, or raw payloads in either field.
  • Do not describe several unrelated effects behind one approval.