curl -sf -X POST https://gateway.flocks.local/v1/tool \
  -H 'Content-Type: application/json' \
  -d '{
    "auth_token": "ops",
    "namespace":  "flocks.builtin",
    "name":       "shell",
    "arguments":  { "command": "echo flocks-tool-ok" }
  }'

​
Request fields

FieldTypeNotes
namespacestringTool namespace, e.g. "flocks.builtin".
namestringTool name within the namespace, e.g. "shell".
argumentsobjectTool-specific input.
auth_tokenstringCaller token forwarded to the gateway’s auth adapter. Ignored when scope_token is supplied.
scope_tokenstring?Optional capability-scoped grant per Phase 5: a base64-encoded JSON ExecutionGrant signed by the gateway. When present, takes precedence over auth_token and gates the call on the grant’s allowed_tool_scopes. The grant’s expiry, audience, and Ed25519 signature are validated.

​
Capability scoping (Phase 5)

The gateway enforces the active grant’s allowed_tool_scopes allowlist against the requested namespace.name (wildcard patterns supported, e.g. "flocks.builtin.*"). Calls outside the allowlist return HTTP 403 with tool '<scope>' not allowed by grant. Roosts advertise the tool scopes they expose via the tools array on POST /v1/enroll; the gateway records this per-roost so the scheduler can dispatch each /v1/tool call to a roost that owns the namespace.

​
Response

{
  "result": {
    "exit_code": 0,
    "stdout":    "flocks-tool-ok\n",
    "stderr":    ""
  },
  "is_error": false
}
Tools are routed by namespace.name. The gateway rejects calls that fall outside the active grant’s tool allowlist with HTTP 403.