Skip to content
AM

Simulate tools (inblack_simulate_*)

Every catalog write tool has a generated simulate tool. Simulate tools preview an action without changing platform state.

Naming

For a write tool:

inblack_create_journal_entry

the generated simulate tool is:

inblack_simulate_create_journal_entry

The catalog sets:

FieldValue
kindsimulate
tierT1
provenancenot_applicable
paginationnone
simulatesThe write tool name

The write tool entry has simulated_by pointing back to the generated simulate tool.

What simulate returns

The router builds an action preview and returns a tool result like:

{
  "status": "ok",
  "tier": "simulate",
  "summary": "Simulated inblack_create_journal_entry. No platform state was changed.",
  "preview": {
    "schema_version": "2026-05-01",
    "preview_id": "preview_...",
    "tool_name": "inblack_create_journal_entry",
    "tier": "T3",
    "action_label": "Create Journal Entry",
    "summary": "Create a manual journal entry.",
    "args_hash": "...",
    "fields": [],
    "impacts": [
      "No platform state has changed yet.",
      "Approving runs Create Journal Entry."
    ],
    "warnings": []
  },
  "data": {
    "simulated": true,
    "write_tool": "inblack_create_journal_entry",
    "accepted_args": {},
    "preview": {},
    "preview_hash": "..."
  }
}

The preview is deterministic-aware when fixture deterministic headers are present. Sensitive argument keys are redacted before they are stored in preview data.

When to use simulate

Use simulate before a write when the user needs to inspect the proposed action. This is especially useful for:

  • T3 writes that will create pending actions.
  • T4 destructive requests where policy may block execution.
  • Bulk or high-blast-radius operations.
  • User prompts asking “what would happen if…”.

Simulate does not approve, queue, or execute the write. It only previews.

Relationship to pending actions

A typical agent flow:

  1. Call inblack_simulate_<tool> to produce a preview.
  2. Show the preview to the user.
  3. If the user approves the specific action, call the real write tool.
  4. If the real tool is T3 or allowed T4, the router creates a pending action and returns INBLACK_CONFIRMATION_REQUIRED.
  5. Confirm or reject with inblack_confirm_action.