Skip to main content
Explain asks every policy about a line or a VFS call without running it, so an agent or a host sees the outcome first and can choose what to run. Nothing runs, nothing is written and no ask is spent.

Example

explain.vfs takes the same calls as session.vfs: await explain.vfs.read("/data/a.txt").

Where to ask

Every entry point returns the same fields. Explain reads the line alone, so a request that also sends stdin, a cwd or a machine is refused.

What comes back

mirage shell --explain prints node as an indented tree, one command per row with its outcome.

What it cannot see

  • post_ methods, since nothing comes back to judge.
  • The file calls of a line, which happen only as it runs: explain the VFS call itself to see its pre_vfs answer.
  • A hidden path explains like any path no rule names, so explain never reveals it exists.

When an action is refused

A refusal reads as a real terminal’s: The reason is on the result’s decision, never in stderr. The agent tools, which MCP and the agent adapters serve, add one line: policy denied: <reason>, or requires approval: <reason> (ask <id>).

Which tools the agent gets

session.tools.names() lists only the tools the session’s profile leaves it: shell needs a command its commands lets run, ls and grep those commands, write and edit a mount the session may write. MCP, RPC and the agent adapters offer exactly those, so an agent is never offered a tool every call of which would be refused.