Tool permissions

Faimulus evaluates every tool call at execution time. Tool discovery is not an authorization boundary, and workflow input cannot supply a principal or grant.

Decision order

1. The workflow manifest must declare a matching capability.
2. A host policy of deny rejects the call. Missing host policy defaults to ask.
3. always-ask in the workflow can tighten an allow host policy.
4. A host-issued launch grant may satisfy ask when its capability ID, fully qualified tool name, and argument JSON Schema all match.
5. Otherwise the runtime requests exact-call consent, or returns CONSENT_REQUIRED when the launch has no response route.

Common deny and ask reasons include:

• TOOL_NOT_DECLARED: the manifest does not declare the requested tool capability.
• TOOL_DENIED: host policy explicitly denies that fully qualified tool.
• GRANT_SCOPE_MISMATCH: a launch grant exists but its argument schema does not match the attempted argument payload.

Provider-supplied MCP annotations are shown as risk hints. They never grant authority and are not trusted as host policy.

Manifest example

schemaVersion: 1
id: post-document
name: Post document
description: Posts one document and reads its accounting record.
flow: flow.yaml
permissions:
  tools:
    - id: accounting-read
      tool: accounting/read
      arguments:
        type: object
        properties:
          ledger: { const: documents }
      consent: inherit
      required: true
webhook:
  endpoints: { base: sync }
  request: { type: json }

Webhook access is protected uniformly with the configured APPLICATION_API_KEY bearer token, not with per-manifest authorization grants. Workflow-as-tool calls receive no parent grants unless the parent capability explicitly delegates named child capability IDs.

Trusted identities

TRUSTED_IDENTITY_HEADER enables identity supplied by a trusted reverse proxy. Do not expose the server directly when this is configured. Manual consent creates a five-minute, opaque, single-use launch token. Scheduled workflows snapshot the creator's scoped grants when enabled.