Skip to content

How it connects

This page walks a single intent from the words you type to the action that runs — and, when the action needs you, back up to your phone and down again on approval. It is the same spine regardless of which executor runs the work.

The end-to-end flow

flowchart TD
    A([Intent: "do X"]) --> B[Hub classifies the intent]
    B -->|needs a box / build / deploy| C[Executor A:<br/>spawn a Commander]
    B -->|read · reason · act| D[Executor B:<br/>in-band LLM-workflow]
    B -.->|ambiguous| ASK[Ask via Facet]

    C --> E{{evaluate_gate<br/>per action}}
    D --> E

    E -->|allowed| RUN[Dispatch the action]
    E -->|denied| DENY[Refuse:<br/>403 / model-readable denial]
    E -->|needs approval| ESC[Escalate]

    ESC --> Q[(Approval queue<br/>1h TTL · params-hash bound)]
    Q --> NTFY[Push to operator phone]
    NTFY --> OP([You approve / deny])
    OP -->|approve| MINT[Mint one-shot grant<br/>match-before-burn]
    MINT --> RESUME[Action executes once<br/>run RESUMES]
    OP -->|deny| DENY
    Q -.->|TTL expires| FAILCLOSED[Fail closed: expired + denied]

    RUN --> AUD[(Tamper-evident audit chain)]
    DENY --> AUD
    RESUME --> AUD
    FAILCLOSED --> AUD

Step by step

1. Intent → executor selection

You state an intent through Facet. The Hub classifies it to an executor before acting:

  • An explicit executor saved on the intent/workflow wins.
  • Otherwise a rule-plus-classifier decides: needs-a-box or code verbs → executor A; pure action/LLM verbs → executor B.
  • If it is genuinely ambiguous, the Hub asks via Facet rather than guessing into an irreversible path.

The decision is recorded and itself gated. A wrong guess never silently commits you to a destructive route.

2. Executor selection → gated action

Whichever executor runs, each action it attempts is evaluated by one function before it is dispatched:

evaluate_gate(principal, owner, target, action, params)
    → allowed | needs_approval | denied
  • Executor A calls the gate on the control surface before actuating a Commander verb (deploy / drive / stop / reset). Independently, the box the Commander runs on enforces its own code-level hooks as a backstop — defense in depth (see Unified gate).
  • Executor B calls the gate on every tool_use the model emits, before dispatch.

Both planes agree because they run the same evaluate_gate over the same rule store. The result is one of three dispositions:

Disposition What happens
allowed The action dispatches.
denied Refused. Executor A gets a 403; executor B gets a model-readable denial and the loop continues, degraded — it never bypasses.
needs_approval The action pauses and escalates to you.

3. Gated action → escalation to the human

When the disposition is needs_approval — or when a capability check denies for lack of a standing grant — the action does not fail flat. It routes up through the escalation engine:

  1. Enqueue a pending approval, bound to the exact (principal, verb, target, params-hash). The params_hash is an anti-forge nonce: the approval binds to this action and no other.
  2. Notify — a push to your phone (over the estate's notification backbone), replacing poll-only waiting.
  3. Observe + decide — you see what action, by whom, on which box, and why it was held, and you approve or deny from Facet.

A pending approval carries a 1-hour TTL. If you never answer, a watchdog expires it and the action fails closed — an unanswered request is a denied request, never a silently-allowed one.

4. Approve → resume

On approval, the resume tail is a tightly bound sequence:

  • Never self-approve — the decider must be a different principal than the asker. The model that proposed the action can never approve it; only a human operator identity can decide.
  • Mint a one-shot grant — a single-use elevation is minted only from an operator-decided approval row.
  • Match before burn — the elevation is checked against the actual action's params_hash before it is consumed. A mismatched action is refused without spending the grant.
  • Execute once, then resume — the action runs exactly once through the same core that a normally-gated action would use, and the paused run continues. One approval message flows back down to the asker.

Crucially for the per-target case: approving a one-shot elevation lets the action run once on box X without granting a standing capability on X. You are not widening the principal's permissions; you are authorizing a single act.

5. Everything is audited

Allow, deny, escalate, approve, expire — every decision lands on a tamper-evident, hash-chained audit ledger. Because both executors and the escalation engine share one path, the audit is complete: there is no side door whose actions do not appear.

The same spine, twice

The diagram above is deliberately executor-agnostic. That is the design claim made concrete: executor A driving a Commander on a remote box and executor B running a curl in-process both pass through evaluate_gate, both escalate through the same queue, both resume through the same one-shot-grant mechanism, and both write to the same audit chain. The Security mechanisms page documents the guarantees each stage upholds.