Private capabilities in Z-Script

A Z-Script step can ask the engine for a private capability, such as "which of my tools would handle this request?". It can never call one by itself. The script only names what it wants. The engine checks that request after the script has run, answers it under your signed-in project, and records the outcome in the run's trace.

What is live

The capability: sqr.route/1, a read-only capability. It returns the engine's decision over your project's own tools: {outcome, tool, arguments, why}.
With no arguments, it routes the run's own request.
With {:question "..."}, it routes that question instead.
Where it runs: in a saved project flow's transform step, on a signed-in /v1/runs run.
Where it never runs: POST /v1/scripts/run, request pre/post scripts, the SDK and the browser. They return the request unresolved or stop with host_not_resolved.

1. Grant it to your project

Every capability is off until your project grants it, in the saved project's harness:

{
  "agent": {
    "harness": { "host_capabilities": ["sqr.route/1"] }
  }
}

Remove the entry to revoke the grant. The next request is refused.

2. Use it in a flow

{
  "key": "route-preview",
  "entry": "lookup",
  "nodes": {
    "lookup": {
      "kind": "transform",
      "script": "(let [d (host \"sqr.route/1\")] {:why (str \"This request goes to \" (get d :tool))})",
      "next": "done"
    },
    "done": { "kind": "respond" }
  }
}

The capability name is a fixed text such as "sqr.route/1". A name built while the script runs is refused before the script starts.

3. Read the trace

Each request appears in that step of the run's path, and in the Studio under Private capability requests:

{
  "node": "lookup",
  "kind": "transform",
  "host_calls": [
    {
      "capability": "sqr.route/1",
      "organization_id": "…",
      "project_id": "…",
      "principal": "key:…",
      "outcome": "resolved",
      "reason": null,
      "index": 0
    }
  ]
}

A refused request stops the flow. The step then carries reason, and its record says "outcome": "refused" with the reason code. The trace never stores the request's arguments or its result.

reason	meaning
`not_granted`	your project has not granted this capability
`unknown_capability` / `unknown_version`	no such capability, or no such version
`invalid_args`	the arguments don't match the capability's schema (a project or tenant can never be passed)
`write_needs_confirmation`	a capability that changes data is never run from a script
`over_budget`, `time_limit`, `result_too_large`, `too_many_host_requests`	a limit was reached
`host_not_resolved`	the run has no signed-in project, so nothing is resolved