Policy configuration
An OpenAPPA policy defines restrictions on tool results and requirements for tool calls. It also defines the approvals and data transformations available when a call is blocked.
Let the
appa-guideskill write it. We suggest using it for the initial policy and for every later change: it inspects your installed tools, proposes contracts in plain English, and applies them after you approve. See Claude Code or kagent for how to run it.
This page specifies the configuration format. For the concepts behind these rules, see How it works.
Policy file#
OpenAPPA reads its configuration from appa.toml.
The configuration consists of two primary sections:
[policy]: Declares the policy version, tool contracts, audience hierarchies, and trust chains.[externals]: Configures transport bindings (HTTP endpoints or local executables) for external membership services, annotators, sanitizers, authorities, recorders, and context providers, as well as global timeouts and payload limits.
[policy]
version = 2
[[policy.tool]]
name = "get_ticket_from_crm"
delta = { audience = ["internal"] }
[externals]
timeout_ms = 2000
max_body_bytes = 65536
Tool contracts#
Each [[policy.tool]] entry defines a contract governing a tool's execution lifecycle:
| Lifecycle stage | Contract field | Description |
|---|---|---|
| Pre-dispatch evaluation | requires | Preconditions evaluated against the outbound label (current_label ⊓ forwards). Call is blocked if unsatisfied. |
| Pre-dispatch evaluation | forwards | Label of content the tool sends beyond its arguments. Combined into the outbound label during pre-dispatch checks. |
| Post-dispatch update | delta | Label transition applied to the trajectory after result delivery. Can narrow audience or lower trust; cannot expand permissions. |
| Post-dispatch update | effects | Side-effect identifiers appended to trajectory history upon successful execution. |
In the example below, get_ticket_from_crm restricts the trajectory audience to and downgrades trust to . The send_email contract requires that all email recipients belong to the trajectory's current audience:
[[policy.tool]]
name = "get_ticket_from_crm"
description = "Reads a customer support ticket."
delta = { trust = "suspicious", audience = ["internal"] }
[[policy.tool]]
name = "send_email"
parameters = { type = "object", properties = { recipient = { type = "string" }, body = { type = "string" } }, required = ["recipient", "body"] }
requires = { audience = { contains = ["$recipient"] } }
delta = {}
effects = ["egress"]
| Field | Description |
|---|---|
name | Tool name, optionally with an argument selector. |
description | Optional description of the tool. Forwarded to annotators. |
parameters | JSON Schema for tool arguments. Required when extracting specific arguments for annotators. |
tags | Category tags used to route blocked calls to matching authorities and sanitizers. See Tags. |
delta | Label transition for tool results. Can narrow audience or lower trust; cannot expand permissions. |
forwards | Label of content the tool sends beyond its arguments. Accepts only literal entries (no $<argument> placeholders). |
requires | Preconditions for executing the call: audience, trust, effects, or attention requirements. |
effects | Side-effect identifiers recorded in trajectory history after successful execution. |
annotator | Name of a registered annotator that dynamically computes the contract for each call. |
recorder | Name of a registered recorder that receives audit records for released calls. |
If omitted, and add no restrictions, and imposes no preconditions.
A tool contract uses either static fields (, , , ) or an . Beside an annotator, a tool can declare only a label floor; any other static field causes a configuration load error.
OpenAPPA evaluates before dispatching a tool call. The engine checks the outbound flow label: the trajectory's current label combined with the tool's . The tool's applies only to the returned result, so it does not affect pre-call evaluation.
Use when a tool itself sends content that its arguments do not carry. In the example below, mail_report reads a server-side report and emails it. Because the report is marked , mailing it to an external recipient fails the check regardless of what data the trajectory previously read:
[[policy.tool]]
name = "mail_report"
parameters = { type = "object", properties = { to = { type = "string" } }, required = ["to"] }
forwards = { audience = ["internal"] }
requires = { audience = { contains = ["$to"] } }
Tool names#
Policies identify tools using either host-native names or canonical tool IDs. Canonical IDs use a three-segment format: . The family must be mcp, host, or agent. Each segment matches [A-Za-z0-9_.-]+. Namespace segments must not contain __.
| Family | Namespace | Description | Example |
|---|---|---|---|
mcp | Server name | A tool provided by an MCP server. | mcp/github/create_issue |
host | Host name | A tool provided natively by the host harness. | host/claude-code/Bash |
agent | Deployment namespace | A subagent invoked as a tool. | agent/kagent/log-analyst |
is the runtime's built-in control tool and the sole member of the appa family. Policies cannot declare it; the runtime handles it directly, and any [[policy.tool]] entry referencing it causes a configuration load error. The wildcard entry name = "*" is not a canonical ID; it acts as a fallback for calls without a matching explicit contract (see Handling undeclared tools).
Agents continue using host-native tool names. The runtime adapter maps native tool invocations to canonical IDs for policy evaluation and audit logging, and formats tool names using host syntax when returning suggestions to the agent. Claude Code and kagent use the following mappings:
| Adapter | Raw tool spelling | Canonical tool id |
|---|---|---|
| Claude Code | mcp__<server>__<tool> — split at the first __ after mcp__ | mcp/<server>/<tool> |
| Claude Code | Built-in tools: Bash, Read, Edit, Agent, … | host/claude-code/<name> |
| Claude Code | mcp__appa__execute_remedy_plan (remedy tool for the runtime's internal appa server) | appa/execute_remedy_plan |
| kagent | Tools discovered from configured MCP endpoints | mcp/<source-id>/<tool> |
| kagent | Delegated subagents invoked as tools | agent/<namespace>/<agent> |
| kagent | Built-in tools: ask_user, load_memory, save_memory, prefetch_memory, or skill tools | host/kagent/<name> |
| kagent | Entrypoint gates | host/kagent-gate/code_execution, host/kagent-gate/memory_persist |
| kagent | Remedy tool | appa/execute_remedy_plan |
In Claude Code, names like Bash or mcp__github__create_issue identify specific tools. In kagent, an unqualified rule such as name = "read_secret" matches that native tool name across all connected MCP servers and built-in tools (excluding remote-agent delegation).
Custom hosts embedding the runtime implement an adapter to map incoming calls to canonical IDs and format tool names for the model. See Add to your agent.
Use server when a rule must apply strictly to a single MCP connection:
[[policy.tool]]
name = "read_secret"
server = "demo-tools"
delta = { trust = "suspicious" }
This rule matches mcp/demo-tools/read_secret. Deployment-level [aliases] maps policy namespaces to deployment-specific identifiers:
aliases.mcpmaps a server name to configured connection identities (e.g.databricks = ["genie", "sql"]), expanding rules under that name to cover each connection.aliases.hostmaps a battery's host namespace to the host serving those tools (e.g.claude-code = ["archestra"]), translatinghost/claude-code/...rules tohost/archestra/....
Aliases resolve after policy composition, preserving root rule precedence over battery rules. OpenAPPA does not infer providers from hostnames or connection metadata. If a host exposes duplicate dispatch names, the host itself must disambiguate them.
Canonical tools#
Different agent harnesses use different names and argument schemas for the same underlying capability. For example, Claude Code executes shell commands using Bash with a command argument, while other tools may use exec_command with a cmd argument. A policy can define rules once for a canonical tool tool/<namespace>/<tool>, and aliases.tool binds that canonical tool to client-specific tools:
[aliases.tool.coding]
shell = [
{ name = "host/claude-code/Bash", args = { command = "command" }, confined = true },
{ name = "host/codex/exec_command", args = { command = "cmd" } },
]
[[policy.tool]]
name = "tool/coding/shell(command:*.env*)"
delta = { audience = ["self"] }
During composition, OpenAPPA replaces each tool/... rule with one concrete rule per mapped client tool at the same position. Each copy references the client tool name (e.g. host/claude-code/Bash(command:*.env*) and host/codex/exec_command(cmd:*.env*)). The args table maps canonical argument names to client-specific argument names, rewriting argument selectors, $argument recipients, @provider:.../$argument placeholders, and parameters schemas.
The runtime never rewrites tool calls. It evaluates tools and arguments exactly as sent by the client, ensuring call digests and audit records remain cryptographically bound to the raw invocation.
aliases.mcp and aliases.host then resolve the generated rules. Under aliases.host = { claude-code = ["archestra"] }, the first rule resolves to host/archestra/Bash(command:*.env*).
The root policy and any battery MAY declare aliases.tool, including for a namespace another battery writes rules for. Only root policies may declare aliases.mcp and aliases.host. The loader rejects the configuration if:
- A rule references an argument that a target does not map.
- A target maps multiple canonical arguments to the same client argument.
- Two mappings in one canonical namespace bind the same client tool after alias resolution.
- A canonical tool mapping defines no client targets.
Two canonical namespaces MAY map the same client tool. Their rules then apply in include order, and the first matching rule wins. A tool/... rule with no alias binding remains inactive, and a mapping for a namespace no rule names binds nothing; OpenAPPA logs both at load. accepts only client-specific tool names; setting confined = true on a target alias automatically adds that client tool to .
Annotators and context providers always receive the native call. Argument placeholders in and refer to native argument names and are not translated by alias mappings. Code-based annotators that expect canonical argument names will receive missing arguments when invoked by clients with different native schemas. Model-backed annotators inspect the entire call object and adapt to native schemas.
kagent derives a default source ID from the configured endpoint URL. Native rules do not require that ID. Tool discovery observes available tools but does not grant authority: discovered tools still require policy coverage, and all calls undergo runtime policy evaluation. Trajectories retain accepted tool identities and evaluate them against the active deployment policy.
Native names also work in , assumed_tools, and provider_run_tools. Coverage reports distinguish a rule spanning servers from an observed concrete tool. Overlapping declarations with incompatible provider-run execution settings are rejected.
Adapters automatically detect tool calls that spawn child trajectories (such as Claude Code's Agent or kagent delegated agents); policies do not need to declare spawn behavior.
Tags#
Tags route blocked tool calls to matching authorities and sanitizers. For example, this contract assigns the support tag to a CRM tool:
[[policy.tool]]
name = "get_ticket_from_crm"
tags = ["support"]
delta = { audience = ["internal"] }
An authority or sanitizer specifying tags = ["support"] applies to any tool carrying that tag. If multiple tags are listed, matching any single tag suffices. If an authority or sanitizer omits , it applies across all tools (subject to its configured permissions).
Attention approvals follow a different mechanism: OpenAPPA matches authorities for attention marks by , ignoring tool tags. See Attention.
Pattern matching#
A policy can declare multiple contracts for the same tool. OpenAPPA evaluates contracts sequentially in declaration order and selects the first match. This applies across overlapping native and canonical names; canonical names receive no special precedence.
In the example below, the first contract matches path values starting with /docs/ and labels results as . The second contract matches all other calls to read_file and labels results as :
[[policy.tool]]
name = "read_file(path:/docs/*)"
delta = { audience = ["public"] }
[[policy.tool]]
name = "read_file"
delta = { audience = ["internal"] }
Argument selectors filter on top-level string arguments and arrays of strings. Specify selectors in parentheses after the tool name using comma-separated argument:pattern pairs. Each argument may appear only once, in any order.
Each pattern must match the entire argument value. For array arguments, the selector matches only if the array is non-empty and every element matches the pattern (for example, edit_agent(teams:*) matches any non-empty array of strings). If an argument is missing, null, an empty array, or a non-string type, the selector does not match.
[[policy.tool]]
name = "mcp__github__fork_repository(owner:archestra-ai,repo:website)"
requires = { trust = "trusted" }
delta = {}
Use * to match any sequence of characters (including an empty sequence):
| Pattern | Matches | Does not match |
|---|---|---|
report.txt | report.txt | old-report.txt |
/docs/* | /docs/guide.md, /docs/setup/install.md | /private/guide.md |
*.md | guide.md, /docs/guide.md | guide.txt |
Because * matches /, ?, and #, avoid using wildcards within URL hostnames: https://*.example.com/* matches https://attacker.test/?x=.example.com/. Instead, terminate each hostname with / and specify subdomains explicitly (e.g. https://docs.example.com/*). OpenAPPA logs a warning at policy load if a wildcard appears within a URL host pattern.
Match one of several values#
Use | to separate alternatives in a pattern. A string argument matches if it satisfies any alternative. An array argument matches if every element satisfies at least one alternative (different elements can match different alternatives). Each alternative must match the full value and may contain *.
For example, this contract matches Python package installations where all entries in hosts come from designated PyPI domains:
[[policy.tool]]
name = "install(hosts:pypi.org|files.pythonhosted.org)"
delta = {}
A call whose hosts array includes evil.example does not match, because that element satisfies no alternative. Specify hostnames explicitly whenever a wildcard could match untrusted domains.
Match special characters literally#
To match special characters (*, ), ,, \, |) literally, escape them with a backslash:
| Character to match | Escape sequence |
|---|---|
Asterisk (*) | \* |
Closing parenthesis ()) | \) |
Comma (,) | \, |
Backslash (\) | \\ |
Pipe (|) | | |
For example, this contract matches a search call where query is exactly a,b:
[[policy.tool]]
name = 'search(query:a\,b)'
delta = {}
Use single-quoted string literals in TOML to preserve backslashes verbatim. In double-quoted strings, backslashes must be doubled ("search(query:a\\,b)").
Only the five escape sequences listed above are supported. Other escape sequences cause a configuration load error.
OpenAPPA selects a contract before validating its parameters schema. If schema validation fails, the call is rejected; the engine does not fall through to subsequent contracts. If a sanitizer rewrites call arguments, the new arguments undergo fresh contract selection. See Sanitizers.
Handling undeclared tools#
The wildcard tool contract name = "*" routes any call that lacks an explicit matching contract through a dynamic annotator. This includes calls to declared tools whose argument selectors did not match:
[[policy.annotator]]
name = "classify_unknown_tool"
ranks = ["suspicious"]
[[policy.tool]]
name = "*"
annotator = "classify_unknown_tool"
A policy may declare at most one wildcard entry. The wildcard contract requires an . Beside it, the wildcard can declare only a label floor; it cannot define other static fields, metadata, or argument selectors.
Explicit tool contracts always take precedence over the wildcard, regardless of declaration order. If an explicit contract matches but fails argument schema validation, the engine rejects the call rather than falling back to the wildcard. If no wildcard is configured, any call lacking a matching contract is denied immediately.
Restrictions and requirements#
OpenAPPA tracks information flow using security labels composed of an audience set and a trust rank (audience × trust). Policies can also require recorded effects () and per-call approvals ().
Audiences#
An audience defines the authorized recipients of data. Reading restricted data narrows the trajectory's audience label, restricting where the agent can send data in subsequent steps.
Use delta.audience to restrict the audience permitted to read a tool's output. Use requires.audience to enforce recipient preconditions on outbound calls:
| Field | Description | Runtime behavior |
|---|---|---|
delta.audience | Allowed readers for the tool result. | Narrows the trajectory audience to the specified readers. |
forwards.audience | Allowed readers for content the tool sends beyond its arguments. | Narrows the outbound label evaluated against requires. |
requires.audience.contains | Required recipients for outbound data. | Verifies that the trajectory audience is authorized to reach every specified reader. |
In the example below, reading a CRM ticket restricts the trajectory to . The subsequent publish_update call requires unrestricted outbound reach ():
[[policy.tool]]
name = "get_ticket_from_crm"
delta = { audience = ["internal"] }
[[policy.tool]]
name = "publish_update"
requires = { audience = { contains = ["public"] } }
Multiple entries combine readers as follows:
| Declaration | Meaning |
|---|---|
delta = { audience = ["@finance", "@support"] } | Restricts output to readers who belong to either group (union of reader sets). |
requires = { audience = { contains = ["@finance", "@support"] } } | Requires the current audience to contain all members of both groups. |
is the only supported precondition operator under requires.audience.
Audience entries support three formats:
| Format | Meaning |
|---|---|
"public", "internal", "self" | Built-in audiences: unrestricted (public), organization members (internal), or the identity OpenAPPA acts for (self). |
"@name", "@provider:selector" | Configured groups (e.g. "@finance") or source collections read directly from providers (e.g. "@slack:user-group/oncall"). |
Literal reader IDs (e.g. "alice@example.com") | Exact-match reader IDs. Note that "finance" represents a literal reader ID, whereas "@finance" references a configured group. |
For example, audience = ["@finance", "alice@example.com"] covers all members of the finance group plus the individual reader alice@example.com.
Built-in audiences#
The built-in audience lattice forms a subset chain: ⊆ ⊆ . includes , and includes all recipients. Policies cannot add levels to this chain; define named groups for custom reader subsets.
Within a single audience array, specify at most one of and . Do not combine with other entries; contains = ["public"] requires completely unrestricted outbound reach.
Read an audience from a tool argument#
Under , use $<argument_name> to read a destination audience dynamically from a tool argument (for example, $recipient):
[[policy.tool]]
name = "send_email"
requires = { audience = { contains = ["$recipient"] } }
OpenAPPA inspects the proposed call's recipient argument at check time and verifies that the trajectory's current audience contains those recipients. Referencing an argument placeholder makes that argument a required top-level string in the tool's parameters schema: OpenAPPA injects the property if omitted, enforces that it is required, and rejects schemas defining it as a non-string type. Argument placeholders as standalone audience entries are valid only within .
The argument value may be a literal reader ID, , , , or an @ group mention. An unresolvable group mention causes an operational error and denies the call.
Read a source collection from a tool argument#
A selector placeholder dynamically resolves an audience collection by extracting selector segments from tool arguments. Format placeholders as @<provider>:<selector> and substitute $<argument_name> for one or more segments:
# Reading a channel restricts the result to that channel's members.
[[policy.tool]]
name = "mcp/claude_ai_Slack/slack_read_channel"
delta = { audience = ["@slack:channel/$channel_id"] }
# Posting to a channel requires that its members can already read the data.
[[policy.tool]]
name = "mcp/claude_ai_Slack/slack_send_message"
requires = { trust = "trusted", audience = { contains = ["@slack:channel/$channel_id"] } }
# The service that reads Slack membership declares the channel template.
[externals.audience.slack]
url = "https://audience.corp/slack"
selectors = [{ template = "viewer", feeds = "self" }, { template = "channel/<id>" }]
A selector placeholder MUST be the sole entry in delta.audience or requires.audience.contains, or an entry in an annotator's mandate (see Permits and hint). It MUST NOT appear alongside other entries in the same list or in an annotator response.
Each $<argument_name> becomes a required top-level argument in the tool schema. Unlike scalar placeholders under , selector placeholders also support string array arguments. The placeholder pattern MUST match a declared template under the provider's definition (see Declare selector templates), with $<argument_name> mapping strictly to <variable> segments.
At evaluation time, OpenAPPA substitutes argument values into the selector, queries the external membership provider, pins the membership in the audit log, and applies the policy check. In the Slack example above, reading channel C0123 restricts the output label to members of C0123, while posting to C0123 requires that all channel members already belong to the trajectory's current audience.
When an argument is an array of strings, the placeholder represents the union of the referenced collections. For example, sharing with teams ["t1", "t2"] under contains = ["@corp:team/$team_ids"] requires the current audience to contain every member of both teams; in delta.audience, it restricts output to readers in either team. A placeholder may include at most one array argument, capped at 100 elements. Empty arrays, arrays exceeding 100 elements, multiple array arguments, or invalid segment values cause immediate call rejection.
Static mentions must not contain segments beginning with $. The dollar-sign prefix is reserved strictly for argument placeholders and cannot be escaped.
Configure audience membership#
External membership services resolve which individual reader IDs belong to an audience collection (such as members of a Google Workspace or Slack group).
Under , and specify the provider selectors supplying their members. defines custom groups using and .
Session principal#
Multi-user hosts can specify the identity each session acts for by passing an email address as the session's principal during session startup. Within that session, resolves directly to that email address without querying external selectors, and automatically includes the principal alongside configured organization sources. Child trajectories and root forks inherit the session principal. Sessions initialized without a principal resolve from [policy.audience] self.
Hosts supply the principal in-process via the embedded runtime API, or over HTTP via the principal field in session_start. Wire-supplied principals are supported under kagent when APPA_SESSION_PRINCIPAL=wire is set (the default, none, rejects requests containing a principal). Because /hook does not authenticate incoming callers, enable wire only when kagent authenticates requests and /hook is network-isolated. OpenAPPA relies on the host for authentication and does not verify session credentials directly; hosts must provide the verified address reported by membership providers. Multi-user configurations typically omit [policy.audience] self, causing any unauthenticated session lacking a principal to fail checks. Policies referencing in boundary declarations or starting labels still require a declared source at load time.
Policies may omit or . If a policy check requires members of an omitted audience level (for example, checking contains = ["internal"] after output restricted the audience to ), the check cannot resolve. OpenAPPA denies the call and names the missing key.
Each selector entry uses the format provider:selector. The provider name corresponds to a binding under [externals.audience.<provider>]. The selector identifies the specific group or resource to query, matching one of the provider's declared templates.
The example below configures Google Workspace membership for , , and :
# Use the Google Workspace viewer as self and organization members as internal.
[policy.audience]
self = ["google-workspace:viewer"]
internal = ["google-workspace:full-members"]
# Define @finance from a Workspace group and declare it part of internal.
[policy.audience.group.finance]
within = "internal"
from = ["google-workspace:group/finance@corp.com"]
# Set the service that supplies Google Workspace membership and declare what it serves.
[externals.audience.google-workspace]
url = "https://audience.corp/google-workspace"
selectors = [
{ template = "viewer", feeds = "self" },
{ template = "full-members", feeds = "internal" },
{ template = "group/<group-address>" },
]
For google-workspace:group/finance@corp.com, OpenAPPA sends group/finance@corp.com as the selector query to https://audience.corp/google-workspace. The service returns the list of reader IDs belonging to that group.
Configuring a provider declares how OpenAPPA queries membership; the deployment must supply the underlying service endpoint or helper script. Pre-built batteries provide membership helpers for common providers (see What is a battery).
Declare selector templates#
The array on [externals.audience.<provider>] defines the selector templates supported by the membership service:
| Field | Description |
|---|---|
template | Selector format consisting of literal segments and <variable> segments separated by / (e.g. viewer, full-members, group/<group-address>, or channel/<id>). |
feeds | Built-in audience fed by this template (self or internal). Omit for templates supplying named groups and direct @provider:selector mentions. |
A provider is registered in a policy when referenced in , a tool contract, an annotator mandate, or a selector placeholder. Every selector used in the policy MUST match a declared template for that provider with the required role:
| Audience key | Permitted template type |
|---|---|
self | Templates with feeds = "self" (typically viewer, representing the session identity). |
internal | Templates with feeds = "internal" (e.g. full-members or org/<org>/members). |
group.<name>.from, direct mentions, and selector placeholders | Any declared template, excluding templates with feeds = "self". |
OpenAPPA rejects configurations referencing selectors under incompatible keys (for example, using a feeds = "self" selector to populate ). Load errors list all templates declared by the provider. Declared templates become part of the cryptographic policy identity; URLs, commands, and credentials do not.
When multiple sources are configured for an audience key, the resulting audience is their union. For example, internal = ["google-workspace:full-members", "slack:full-members"] combines members returned by both providers.
within = "internal" asserts that all members of the group belong to . OpenAPPA accepts this assertion without verifying individual member IDs against sources or checking email domains. Groups may declare within = "self" or within = "internal".
Policies can reference provider groups directly as "@slack:user-group/oncall" without declaring an explicit block, provided the slack provider is configured:
# Use Slack workspace members as internal.
[policy.audience]
internal = ["slack:full-members"]
# Restrict incident details to the Slack oncall group.
[[policy.tool]]
name = "get_incident"
delta = { audience = ["@slack:user-group/oncall"] }
# Set the service that supplies Slack membership and declare what it serves.
[externals.audience.slack]
url = "https://audience.corp/slack"
selectors = [
{ template = "viewer", feeds = "self" },
{ template = "full-members", feeds = "internal" },
{ template = "user-group/<handle>" },
]
OpenAPPA rejects references to undeclared named audiences, unconfigured providers, or selectors that match no declared template.
Reader IDs#
A reader ID is an exact string identifier. Membership services assign reader IDs using verified email addresses when available, or qualified identifiers formatted as <provider>:<id> (such as slack:U012345 or github:alice). The default Slack, GitHub, and Google Workspace integrations follow this convention. The GitHub service uses verified public profile emails when available, falling back to github:<login>.
Membership services must authenticate address ownership. When multiple services report the same verified email address, OpenAPPA recognizes them as the same reader. Qualified provider IDs remain distinct and do not alias across providers.
OpenAPPA lowercases the domain portion of email addresses while preserving the local part before @ verbatim (including dots and +tag suffixes). It does not resolve email aliases or conflate personal and corporate addresses.
Every reader ID returned by a membership service must be a valid email address or match <provider>:<non-empty> under the responding provider. An ID containing a colon before the @ symbol is parsed as a qualified ID, not an address. Any invalid format causes the membership response to be rejected as an operational failure, denying the call. If a service reports multiple addresses for one account, OpenAPPA treats them as distinct reader IDs, producing a strictly narrower audience.
Membership request protocol#
Audience providers implement either HTTP endpoints or local executables.
OpenAPPA queries membership services to expand group selectors into reader IDs or to resolve individual member IDs to canonical reader IDs. For the complete JSON wire schema, see The consult request.
Consult requests include declaration.templates listing the declared templates for that provider. The service MUST validate that this declaration matches the templates it supports before evaluating credentials or upstream APIs, refusing requests on mismatch. Operational failures abort policy evaluation without recording an allowance.
To query group membership for user-group/oncall, OpenAPPA sends:
{"selector": "user-group/oncall"}
The service returns reader IDs:
{"members": ["a@corp.com", "slack:U2"]}
An empty group returns {"members": []}.
To look up an individual member, OpenAPPA sends:
{"member": "slack:U1"}
The service returns the resolved reader ID:
{"principal": "a@corp.com"}
If the member cannot be resolved, the service returns {"principal": null}, and the identifier remains unchanged. Non-null principal values must conform to reader ID format rules.
If the service fails, times out, or returns invalid data, the audience check cannot complete, and OpenAPPA denies the operation. OpenAPPA records all membership responses in the audit log alongside the associated decision.
Map members with and #
By default, a provider's own service resolves member lookups. Configure lookup = "<name>" on a provider to delegate member lookups to another [externals.audience.<name>] definition. The target entry must define exactly one of , command, or url. A entry provides a static inline map from <provider>:<id> to reader IDs, resolving lookups in-memory without network calls:
[policy.audience]
self = ["github:viewer"]
internal = ["github:org/acme/members"]
[externals.audience.github]
command = ["python3", "batteries/github/audience-source.py"]
token_env = "APPA_PROVIDER_GITHUB_TOKEN"
selectors = [
{ template = "viewer", feeds = "self" },
{ template = "org/<org>/members", feeds = "internal" },
{ template = "org/<org>/team/<team>" },
]
lookup = "people"
[externals.audience.people]
readers = { "github:alice" = "alice@corp.com" }
When is configured, OpenAPPA automatically queries the lookup provider for any group member that is not already an email address. In the example above, github:alice returned for org/acme/members maps to alice@corp.com. If a lookup returns null or an ID is missing from , the identifier remains unchanged. Lookup results are pinned in the audit record alongside group membership responses.
Batteries bind their included membership services and selectors within their own appa.toml. Root policies retain mappings. Redefining a provider binding in the root configuration when already declared by an included battery causes a duplicate binding error.
Source probe at start and reload#
Before serving traffic from a new or reloaded policy, OpenAPPA executes a startup probe: it queries each referenced selector once, queries each configured target with a sample member returned by those selectors, and validates that all returned values conform to reader ID rules. If a service fails, returns an invalid reader ID, or rejects declared selector templates, the startup or reload fails with an error specifying the provider and reason. If a policy reload fails its probe, OpenAPPA continues serving the existing configuration without interruption. Replay executions do not execute startup probes.
Trust#
Trust ranks quantify data provenance and integrity within a trajectory. A trust rank is a discrete level (such as or ). Reading data at a lower rank lowers the trajectory's trust, and later results cannot raise it again. Tools can require a minimum rank before they run.
Configure trust bounds using the following fields:
| Field | Description | Example |
|---|---|---|
delta.trust | Output trust rank. Computes the meet with trajectory trust; can lower or maintain trust, but cannot elevate it. | delta = { trust = "suspicious" } |
forwards.trust | Trust rank of content the tool sends beyond its arguments. Combined into the outbound label evaluated against requires.trust. | forwards = { trust = "suspicious" } |
requires.trust | Minimum trajectory trust rank required to execute this tool call. | requires = { trust = "trusted" } |
Trust rank names must appear in the policy's configured trust chain.
Trust ranks#
If omitted, defaults to ["suspicious", "trusted"] (ordered from least trusted to most trusted).
Define custom ranks by setting under [policy]. For example, trust_chain = ["untrusted", "reviewed", "trusted"] defines three ranks in ascending order. Any trust rank referenced in contracts, annotators, or sanitizers must be declared in this list.
Choose a result's trust by who wrote it#
Assign trust ranks based on author accountability rather than transport service or audience visibility. Trust reflects author accountability, not audience visibility: a public repository issue authored solely by your team maintains trust, whereas an external contributor's comment on an internal repository is .
Content authored strictly by organization members or verified collaborators maintains trajectory trust (by omitting from ). Similarly, content from authenticated external publishers on controlled channels (such as vendor documentation or package registry metadata) can remain trusted. Surfaces open to arbitrary third-party writes (public issues, forum posts, package READMEs, web search results, or shared external channels) must assign trust.
Because static contracts cannot inspect per-call authors, they must assume worst-case write access: reading a public repository issue statically assigns . Dynamic annotators can evaluate specific authors using context reported by a context provider. Deployment hints ([policy.deployment] hint) instruct annotators on whether specific endpoints are trusted or suspicious.
Guest accounts and installed integrations write as the organization, so text they post keeps the trajectory's trust.
Declare tool restrictions and requirements#
In the example below, sets the default ranks explicitly. The read_web_page contract marks its output as . Once the trajectory ingests web content, OpenAPPA blocks apply_db_migration because it requires inputs:
[policy]
version = 2
trust_chain = ["suspicious", "trusted"]
[[policy.tool]]
name = "read_web_page"
delta = { trust = "suspicious" }
[[policy.tool]]
name = "apply_db_migration"
requires = { trust = "trusted" }
Subsequent tool results marked do not restore a trajectory's trust after a downgrade to . An authority with appropriate permissions can approve a blocked call without altering the underlying trajectory label, or a sanitizer can assign a cleaned result the audience or trust rank its allow.
Effects#
Effects track completed actions in trajectory history, so later calls can require that an action has, or has not, already occurred.
| Field | Description | Example |
|---|---|---|
effects | Appends effect identifiers to trajectory history on call success. | effects = ["backup.completed"] |
requires.effects.contains | Requires specified effect identifiers to be present in trajectory history. | contains = ["backup.completed"] |
requires.effects.excludes | Denies the call if any specified effect is already recorded or emitted by an in-flight call. | excludes = ["migration.applied"] |
Only and are permitted under requires.effects.
In the example below, backup_database records backup.completed upon success. The migration requires this prior backup and is blocked if a migration has already succeeded or if another migration call is currently in flight:
[[policy.tool]]
name = "backup_database"
delta = {}
effects = ["backup.completed"]
[[policy.tool]]
name = "apply_db_migration"
delta = {}
effects = ["migration.applied", "mutation"]
[policy.tool.requires.effects]
contains = ["backup.completed"]
excludes = ["migration.applied"]
Attention#
Attention marks require explicit, per-invocation approval. Prior approvals or recorded effects do not satisfy attention requirements.
| Field | Description | Example |
|---|---|---|
requires.attention | Attention marks required to execute the tool call. | requires = { attention = ["sre-signoff"] } |
permits.attention | Attention marks an authority is authorized to approve (["*"] covers all declared marks except blocked). | permits = { attention = ["sre-signoff"] } |
In the example below, apply_db_migration requires sre-signoff. The sre-reviewer authority uses the built-in human-in-the-loop reviewer (hitl) to approve this mark:
[[policy.tool]]
name = "apply_db_migration"
requires = { attention = ["sre-signoff"] }
delta = {}
effects = ["migration.applied"]
[[policy.authority]]
name = "sre-reviewer"
permits = { attention = ["sre-signoff"] }
[externals.authorities.sre-reviewer]
builtin = "hitl"
An attention mark is an identifier for an approval requirement (such as sre-signoff). OpenAPPA routes approval requests to any authority whose includes that mark, irrespective of tool tags. See Authorities.
Authorities with permits = { attention = ["*"] } can approve any declared attention mark (excluding ). The wildcard "*" must be the sole entry in ; combining it with named marks causes a configuration load error.
is a reserved attention mark used for unconditional denials. No authority can permit , and the ["*"] wildcard does not match it. A call requiring cannot be approved by any authority or remedy plan.
Annotators#
An annotator dynamically computes contract rules for tool calls. It can return output restrictions (), restrictions on content the call sends beyond its arguments (), execution preconditions (), and side effects (). (The built-in jev annotator determines audience and trust labels only.)
Use annotators when call rules depend on runtime arguments or external context (such as classifying file access by filesystem directory or database queries by target table).
Tools bind an annotator using annotator = "<name>". The annotator computes , , , and emitted effects for each invocation.
A tool can also declare a label floor beside its annotator. The floor narrows every answer, so no answer can loosen it:
requires.trust: the call requires the higher of this floor and the annotator's floor.requires.audience.contains: the call requires these readers and the annotator's. The readers MUST be literal; a placeholder is refused.delta.trust: the result carries the lower of this trust and the annotator's.
A tool with an annotator MUST NOT declare , , delta.audience, requires.effects, or requires.attention. The loader refuses each of them.
[[policy.annotator]]
name = "file-tracker"
[[policy.tool]]
name = "Bash(network_hosts:*)"
annotator = "file-tracker"
requires = { audience = { contains = ["public"] } }
delta = { trust = "suspicious" }
Example: annotate a tool call with Claude Code#
The example below uses Claude Code as a classifier for Bash invocations. It inspects the full tool call and uses the configured to evaluate restrictions and preconditions. The , , , and fields bound the permitted outputs:
[[policy.annotator]]
name = "classify-command"
builtin = "claude-code"
ranks = ["suspicious", "trusted"]
audiences = ["internal"]
marks = []
effects = []
hint = "Hosts under corp.example are the organization's own: what they return is internal. Files under /srv/customer-records are internal."
[[policy.tool]]
name = "Bash"
description = "Runs one shell command and returns its output."
annotator = "classify-command"
This configuration forwards the tool name, description, and arguments to Claude Code without requiring a parameters schema. If a tool omits description, it is omitted from the consult payload.
Inputs#
By default, an annotator receives the complete tool call. Use to restrict the payload to specific call attributes. In the example below, the annotator receives only the customer_id argument (renamed to subject):
[[policy.annotator]]
name = "classify-customer"
inputs = { subject = "$tool_call.arguments.customer_id" }
ranks = ["suspicious"]
audiences = ["internal"]
marks = []
effects = []
hint = "Classify customer records as internal and suspicious."
[[policy.tool]]
name = "get_customer"
parameters = { type = "object", properties = { customer_id = { type = "string" } }, required = ["customer_id"] }
annotator = "classify-customer"
[externals.annotators.classify-customer]
url = "https://classifier.corp/label"
Restricting inputs does not reduce the annotator's response obligations; it must still return a complete annotation. Supported input selectors include:
| Selector | Extracted data |
|---|---|
$tool_call | Full call: name, description (if declared), and argument map. |
$tool_call.name | Tool name string. |
$tool_call.description | Tool description string (requires description in the contract). |
$tool_call.arguments | Entire arguments map. |
$tool_call.arguments.<name> | Single top-level argument (must be marked required in parameters). |
Selected argument values retain their native JSON types as validated by the tool's schema.
Context providers#
Context providers gather external facts about a tool call that cannot be derived from call arguments alone (such as checking repository visibility via GitHub API during a git push, or querying ticket metadata during an issue lookup). Configure context providers under .
[[policy.annotator]]
name = "classify-push"
builtin = "claude-code"
[[policy.tool]]
name = "Bash(command:*git push*)"
annotator = "classify-push"
[externals.context.github]
command = ["python3", "context.py"]
hint = "A push into a public repository requires audience public; into a private one, internal."
Before consulting an annotator, OpenAPPA sends concurrent consult requests (kind = "context") to all configured context providers. The payload includes tool, arguments, and cwd (if provided by the harness). Providers return {"version": 1, "answer": <JSON>} or null if the call is not relevant.
OpenAPPA passes provider outputs to the annotator under , keyed by provider name:
{
"github": { "answer": { "repository": { "name": "acme/widget", "visibility": "public" } } },
"tickets": { "error": "timeout" }
}
If a provider returns null, its key is omitted. If a provider times out, returns an error, or produces invalid JSON, OpenAPPA records an error object with the failure reason. Context provider failures never block execution directly; annotators treat missing or failed context as unknown data. Annotators do not receive cwd.
An optional (maximum 2,048 characters) under guides the annotator on interpreting the provider's data. OpenAPPA forwards hints in declaration.context_hints whenever the provider returns an answer or error. Context provider answers represent factual data, while hints represent deployment instructions.
Provider answers are arbitrary JSON. Providers SHOULD return factual state rather than security labels (e.g. reporting visibility: "public" rather than an audience label). Quoted external text SHOULD include author metadata so annotators can evaluate trust.
OpenAPPA logs context outputs alongside the resulting annotation. Subsequent evaluations that reuse the cached annotation reuse its recorded context without re-querying providers.
Permits and hint#
Annotator permits enforce strict bounds on what an annotator may return:
| Field | Allowed values in response | Default (if omitted) |
|---|---|---|
ranks | Trust ranks permitted in delta.trust or requires.trust. | All ranks in trust_chain. |
audiences | Audiences, group references, selector placeholders, or reader IDs allowed in answers (public is always permitted). | All declared policy audiences (self, internal, named groups, reader IDs). |
marks | Attention marks permitted in requires.attention. | All marks declared across tools, authorities, and annotators. |
effects | Effect names permitted in emits or requires.history. | All effect names declared in the policy. |
is always permitted and must not be listed in . Setting audiences = [] allows only classifications.
An empty list explicitly denies all values for that field (for example, marks = [] forbids the annotator from attaching attention marks, and audiences = [] permits only ). An omitted field permits any value valid within the policy: omitting lets the annotator require any mark the policy declares, including if the policy uses it.
An annotator may return selector placeholders only if explicitly declared in its permit (such as @github:repo/$owner/$repo/collaborators). Declaring a placeholder requires all tools bound to the annotator to provide those arguments; consequently, the wildcard tool * cannot use an annotator with selector placeholders. In consult requests, OpenAPPA instantiates placeholders into concrete values (e.g. @github:repo/acme/api/collaborators), and the annotator must reference only those instantiated values. See Read a source collection from a tool argument.
An optional (maximum 512 characters) provides task-specific classification rules (e.g. mapping specific directory paths or commands to labels). Built-in annotators (claude-code, llm, jev) automatically include OpenAPPA's label guide, so a hint does not restate it. Hints cannot expand configured permits.
An optional deployment-wide hint ([policy.deployment] hint, maximum 2,048 characters, root configuration only) defines global environment boundaries, such as internal hostnames or forge domains. OpenAPPA forwards this to all annotators as declaration.deployment_hint.
[policy.deployment]
hint = "Hosts under corp.example and the forge git.corp.example are the organization's own."
Implementing an annotator#
Annotators can execute as HTTP services, local executables, or built-in model classifiers. Configure endpoints or executable commands under , matching the annotator's policy name.
Built-in annotator engines are configured directly via builtin on :
- : Runs local Claude Code (
claude -p). - : Dispatches to the model backend configured under .
- : Queries TypeSafe's Jev classifier using credentials configured under .
An annotator declaring builtin must not define an section. Unlike sanitizers and authorities, annotator builtins belong in .
claude-code requires the claude CLI on PATH. On Windows, claude must resolve to claude.exe (OpenAPPA cannot execute the claude.cmd npm shim). llm requires configuration. jev requires credentials, classifies the entire call object (cannot use ), and requires a mandate whose admit at least two trust ranks. Configurations with missing, unrecognized, or unconfigured builtins are rejected at policy load.
Annotator protocol#
OpenAPPA transmits consult requests with kind = "annotation". Policy rules and permits reside in ; call attributes reside in artifact.args:
{
"version": 1,
"kind": "annotation",
"name": "classify-customer",
"declaration": {
"hint": "Classify customer records as internal and suspicious.",
"inputs": ["subject"],
"trust_ranks": ["suspicious"],
"audiences": ["internal"],
"attention_marks": [],
"effects": []
},
"artifact": { "args": { "subject": "cust-7" }, "context": {} }
}
contains context provider outputs. When is omitted, declaration.inputs is empty and artifact.args contains the complete call:
{
"args": {
"name": "Bash",
"description": "Runs one shell command and returns its output.",
"arguments": { "command": "cargo test" }
},
"context": {}
}
Consult requests do not disclose the trajectory's current audience, trust rank, or history.
Annotators respond with an answer object specifying , , and :
{
"version": 1,
"answer": {
"delta": { "trust": "suspicious", "audience": ["internal"] },
"requires": { "history": [], "attention": [] },
"emits": []
}
}
Protocol constraints:
answermust define , , and , and may include and . Unrecognized keys are rejected.- is an optional opaque string (up to 1,024 bytes) recording provenance (such as a policy version or file hash). It is part of the recorded annotation and is forwarded to configured recorders.
- uses the same structure and validation as .
- must include
historyand arrays (even when empty). requires.audiencemust contain exactly .- History checks use
{"contains":"<effect>"}or{"excludes":"<effect>"}. - Audience arrays use
"public"or a list of permitted audiences."public"must not be placed inside an audience list. - Audience lists must not contain duplicate entries or combine and .
OpenAPPA rejects responses containing unknown keys, null values, empty audience objects, duplicate emitted effects, or values outside configured permits. If a response violates permits, OpenAPPA denies the call and logs the violating field and allowed set (e.g. field=delta.audience allowed=declaration.audiences) without echoing the unvetted value. Built-in model classifiers return the inner answer object directly.
Annotations are bound strictly to the specific call evaluated. Any change to call arguments requires a fresh annotation. Replaying a recorded session reuses cached annotations and membership data without re-querying annotators.
If an annotator fails, times out, or returns values outside its permits, the call is denied. OpenAPPA checks that the answer uses permitted values; the annotator is responsible for classifying the call correctly.
Test an annotator#
Use appa runtime annotate to test annotator classifications against sample tool calls offline. It exercises the production consult pathway (including declaration generation, request serialization, backend execution, and permits validation) without opening a trajectory or executing tools.
appa runtime [--config <path>] [--batteries-dir <dir>] annotate [--repeat <n>] [--concurrency <n>] < calls.jsonl
Standard input accepts newline-delimited JSON objects representing tool calls:
| Field | Description |
|---|---|
id | Call identifier echoed in output. |
tool | Tool name as declared in policy. |
arguments | Tool arguments object. |
cwd | Optional working directory forwarded to context providers. |
Standard output yields newline-delimited JSON responses in arrival order:
outcome | Meaning | Diagnostic fields |
|---|---|---|
answer | Annotator returned valid labels within permits. | annotator, answer |
outside_mandate | Response violated the protocol or exceeded permits (denied in production). | annotator, answer |
no_answer | Annotator failed to respond or timed out (denied in production). | annotator, reason |
static | Tool has a static contract; no annotator was consulted. | |
unresolved | Tool or argument pattern is not defined in policy. | reason |
--repeat <n> runs each call n times to assess model classification consistency (default: 1). n MUST be at least 1. --concurrency <n> limits in-flight requests (default: 4).
Example checking Google Drive tool calls against battery rules:
# appa.toml
include = ["batteries/google-workspace/appa.toml"]
[policy]
version = 2
[policy.audience]
self = ["google-workspace:viewer"]
internal = ["google-workspace:full-members"]
cat > calls.jsonl <<'EOF'
{"id":"org","tool":"mcp/claude_ai_Google_Drive/create_file","arguments":{"title":"t","textContent":"x","parentId":"<org-wide folder id>"}}
{"id":"read","tool":"mcp/claude_ai_Google_Drive/read_file_content","arguments":{"fileId":"<file id>"}}
EOF
APPA_PROVIDER_GOOGLE_WORKSPACE_TOKEN=... appa runtime --config appa.toml annotate < calls.jsonl
Output:
{"id":"read","repeat":0,"latency_ms":0,"outcome":"static"}
{"id":"org","repeat":0,"latency_ms":387,"outcome":"answer","annotator":"google-workspace.drive-readers","answer":{"delta":{},"emits":["google-workspace.changed"],"requires":{"attention":[],"audience":{"contains":["internal"]},"history":[],"trust":"trusted"}}}
Without the token, the org line is a no_answer with the program's error:
{"id":"org","repeat":0,"latency_ms":67,"outcome":"no_answer","annotator":"google-workspace.drive-readers","reason":"non_success status=1 detail=\"google-workspace.drive-readers: APPA_PROVIDER_GOOGLE_WORKSPACE_TOKEN is not set\""}
The command exits with status 0 after testing all input calls, regardless of individual outcomes. It exits with a non-zero status if the policy fails to load or if input JSON is malformed. It also exits with a non-zero status when it cannot write an answer to standard output, for example after the reader closes the pipe. In that case no further call is scheduled, and the calls in flight are dropped.
Recorders#
Recorders receive event notifications when tool calls are released, allowing external systems to track state across calls. For example, a file tracker records security labels when files are written via Write, enabling its paired annotator to retrieve those labels when Read subsequently accesses the files.
Tools bind a recorder using recorder = "<name>" (supported on explicit contracts and the "*" wildcard). Bind each recorder under using url or command. There is no [[policy.recorder]] section; every recorder referenced by a tool contract must have a matching binding under [externals.recorders].
[[policy.annotator]]
name = "file-tracker"
[[policy.tool]]
name = "host/claude-code/Write"
annotator = "file-tracker"
recorder = "file-tracker"
[externals.annotators.file-tracker]
command = ["appa", "file-tracker", "annotate"]
[externals.recorders.file-tracker]
command = ["appa", "file-tracker", "record"]
Recorders operate asynchronously. They cannot block, approve, or delay execution. However, because subsequent annotators may rely on recorded state, recorder components must maintain high integrity.
Published label#
The published label for a released call is the trajectory label at release time combined with the tool's and . For write operations, this captures the label of data available in call arguments. For copy operations, it reflects the source object's label via even if payload bytes bypassed the agent context. If an input sanitizer rewrites arguments, the published label reflects the post-rewrite trajectory state.
Recorder protocol#
OpenAPPA sends batch delivery notifications after committing decisions and call outcomes to the log. Deliveries contain engine-derived labels:
{
"version": 1,
"kind": "recorder",
"name": "file-tracker",
"root": "cc:7f3a…",
"records": [
{
"record": "released",
"dispatch": "cc:7f3a…/9c1e…/0",
"tool": "host/claude-code/Write",
"arguments": { "file_path": "/work/notes.md", "content": "…" },
"label": { "trust": "suspicious", "audience": [["internal"]] },
"evidence": "absent"
},
{ "record": "outcome", "dispatch": "cc:7f3a…/9c1e…/0", "outcome": "success" }
]
}
| Record type | Fields | Meaning |
|---|---|---|
released | dispatch, tool, arguments, label, evidence | The tool call was released for execution. label is its published label. |
outcome | dispatch, outcome | The tool call completed with status success, failure, or indeterminate. |
unreleased | trajectory, batch, tool, arguments, evidence | The batch was evaluated and the tool call was denied or suppressed. |
label.audience is "public" or a list of conjunctive clauses. Each clause contains audience identifiers; a reader belongs to the audience only if included in every clause. contains the annotator's string, or null.
Recorders must respond with {"version":1,"answer":{}}. OpenAPPA delivers records in append-log order with at-least-once delivery semantics. Failed deliveries are retried on subsequent batches. Following a restart, OpenAPPA replays deliveries from the start of the trajectory family; recorders MUST ensure idempotent processing by deduplicating against dispatch identifiers.
Sanitizers#
Sanitizers transform or validate data across trust or audience boundaries before an agent or tool receives it. The sanitizer's section defines the exact label transition OpenAPPA applies to the transformed output.
In the example below, the integration withholds raw CRM tickets while remove_customer_details strips private customer information. The policy permits the sanitized output to be released as :
[[policy.tool]]
name = "get_ticket_from_crm"
tags = ["support"]
delta = { audience = ["internal"] }
[[policy.sanitizer]]
name = "remove_customer_details"
on = ["tool_output"]
tags = ["support"]
hint = "Remove customer identities and all other private details from the ticket."
[policy.sanitizer.permits]
audience = { from = ["internal"], to = ["public"] }
[policy.deployment]
confined_results = ["get_ticket_from_crm"]
[externals.sanitizers.remove_customer_details]
url = "https://sanitizer.corp/sanitize"
Permitted transitions#
A sanitizer transition modifies either the audience or the trust rank, declared via and under . A sanitizer definition may configure or , but not both.
| Transition type | from definition | to definition |
|---|---|---|
audience | Readers required in the raw input audience. | Audience assigned to the sanitized output. |
trust | Minimum trust rank required for the raw input. | Trust rank assigned to the sanitized output. |
For example, this contract authorizes a sanitizer to verify or clean unvetted text, promoting it to :
[policy.deployment]
context_control = true
[[policy.sanitizer]]
name = "vouch-fetched-text"
on = ["tool_output"]
[policy.sanitizer.permits]
trust = { from = "suspicious", to = "trusted" }
The underlying implementation is responsible for removing sensitive content or verifying data integrity before returning it. The integration must withhold the raw payload until sanitization succeeds.
The optional instructs the sanitizer on what data to redact or validate. Hints cannot expand authority beyond .
Tool outputs and inputs#
The array specifies which data surfaces the sanitizer can transform:
on value | Target data | Integration requirement |
|---|---|---|
tool_output | Tool result payloads or child agent returns. | Withhold the raw payload from the agent context and deliver the sanitized result. |
tool_input | All arguments for a proposed tool call. | Execute the tool using the sanitized arguments returned by the service. |
When a tool result would restrict the trajectory label, OpenAPPA offers matching output sanitizers as remedy plans. If selected, the integration executes the sanitizer before releasing the payload to the agent context.
If the sanitized output still carries restrictions, the agent may accept the narrowed label or apply another compatible sanitizer. Sanitizing a newly ingested result does not retroactively remove restrictions incurred from earlier steps.
Transforming tool arguments can satisfy audience requirements (for example, replacing an external recipient with an internal address). Argument sanitization cannot satisfy trust requirements because modifying arguments does not remove the the trajectory already carries. Argument sanitization replaces argument values only; any label defined on the tool contract continues to apply.
Following argument sanitization, OpenAPPA evaluates the call against contracts matching the modified arguments, re-checking preconditions, effects, and schemas. If the new contract uses an annotator, a fresh annotation is requested. Cached audience membership data is reused.
Sanitizer tags restrict which tools the sanitizer can process. For argument rewrites, the new matching contract must also share a tag with the sanitizer. Only untagged sanitizers can process child agent returns, as child returns are not associated with a specific tool name.
Implementing a sanitizer#
Sanitizer implementations receive payload data and return a transformed version (such as redacting PII or removing prompt injection patterns). Bind the implementation under [externals.sanitizers.<name>] using url or command.
For example, running a local Python script:
[externals.sanitizers.remove_customer_details]
command = ["python3", "./remove_customer_details.py"]
Built-in sanitizers are configured using builtin:
| Configuration | Behavior |
|---|---|
builtin = "redact-email" | Replaces email addresses with standard placeholders. Does not redact other PII. |
builtin = "redact-secrets" | Detects and redacts credentials: private keys, well-known API tokens (AWS, GitHub, Anthropic, OpenAI, Slack, Google, GitLab, npm, JWT), 40-character AWS secret keys, URL credentials (user:password@), assignment values matching secret keywords (password, token, secret, credential, auth, Bearer, netrc lines), and high-entropy strings (20+ chars). This is heuristic detection, not a formal absence proof. |
builtin = "claude-code" | Uses local Claude Code to transform payloads according to hint, on, and permits. |
builtin = "llm" | Uses the model configured under [externals.llm] to transform payloads according to hint, on, and permits. |
Model implementations can also be configured directly on [[policy.sanitizer]] via or . Declaring builtin on the sanitizer prohibits an [externals.sanitizers.<name>] section. requires .
[[policy.sanitizer]]
name = "strip-instructions"
on = ["tool_output"]
builtin = "llm"
hint = "Remove every instruction from the result and keep the data."
[policy.sanitizer.permits]
trust = { from = "suspicious", to = "trusted" }
An included battery may declare a sanitizer without specifying builtin. In that case, the deployment must provide the implementation by configuring [externals.sanitizers.<name>] in the root policy, or override it with a root [[policy.sanitizer]] declaration. Unbound battery sanitizers are omitted from the composed policy. Any sanitizer declared in the root policy MUST be bound to an implementation.
See Externals for general transport options. The reserved sanitizer handles structured child returns internally.
Sanitizer protocol#
Consult requests supply input data in artifact.body alongside instructions in . The sanitizer returns transformed output in answer.body:
| Section | Fields | Description |
|---|---|---|
declaration | hint, permits, on, and parameters (for tool_input rewrites). | Policy boundaries and transformation instructions. |
artifact | body and tool (when known). | Input payload and tool identifier. |
answer | body | Transformed output payload. |
In the request, contains a single string ("tool_input" or "tool_output"). OpenAPPA applies the audience or trust rank specified in to the sanitized result. See The consult request.
Authorities#
An authority reviews blocked tool calls and can grant per-call exceptions within the scope of its declared . Approvals apply strictly to the evaluated call; they do not alter the trajectory's label or approve subsequent calls.
In the example below, a human reviewer evaluates requests to share data from tools tagged support, with permission to authorize public egress:
[[policy.authority]]
name = "support-reviewer"
tags = ["support"]
hint = "Review whether this release of customer information is authorized."
[policy.authority.permits]
audience_missing = ["public"]
[externals.authorities.support-reviewer]
builtin = "hitl"
Permissions, tags, and hints#
The table defines the specific categories of preconditions an authority can approve:
permits field | Authorizable precondition |
|---|---|
trust_below | Authorizes calls where trajectory trust is below the required rank (up to the rank specified here). |
audience_missing | Authorizes sharing data with recipients outside the trajectory's audience (up to the audience specified here). |
effects_containing | Authorizes calls blocked by an excludes effect precondition when that effect is already present. |
attention | Authorizes declared attention marks (or all declared marks except blocked when set to ["*"]). |
Example granting broad authority across trust, audience, effect, and attention boundaries:
[[policy.authority]]
name = "finance-officer"
[policy.authority.permits]
trust_below = "trusted"
audience_missing = ["public"]
effects_containing = ["email.sent"]
attention = ["finance-signoff"]
Authority tags route reviews for unmet audience, trust, or effect preconditions. Attention approvals route strictly via regardless of tags.
excludes specific tool tags from authority routing for audience, trust, or effect requirements (attention approvals remain unaffected). In this example, rollout can approve unmet trust requirements for all tools except send_payment:
[[policy.tool]]
name = "send_payment"
tags = ["enforced"]
requires = { trust = "trusted" }
delta = {}
[[policy.authority]]
name = "rollout"
except_tags = ["enforced"]
[policy.authority.permits]
trust_below = "trusted"
Each tag in MUST exist on at least one tool and MUST NOT appear in the authority's own list. OpenAPPA rejects policies that violate these constraints.
The optional provides guidance for reviewers or automated classification models. Hints cannot expand authority beyond .
Implementing an authority#
Authorities can use built-in handlers, HTTP endpoints, or local executables. Configure implementations under [externals.authorities.<name>]:
| Implementation | Behavior |
|---|---|
builtin = "hitl" | Routes requests to an interactive human reviewer displaying call details and requested exceptions. |
builtin = "approve" | Automatically approves matching requests within permits. If a blocked call requires only automatic approvals, OpenAPPA applies them transparently without interrupting the agent. (Plans requiring narrowing acceptance are still returned to the agent.) |
builtin = "claude-code" or builtin = "llm" | Uses an LLM to evaluate approval requests against the declaration and unmet preconditions. |
builtin = "<module>" | Executes a shared library module loaded from --modules-dir. |
url or command | Dispatches approval requests to an external service or executable. |
All authority implementations, including automatic approvers, remain strictly constrained by declared .
Authority protocol#
OpenAPPA transmits consult requests detailing the proposed tool call and unmet preconditions. carries and ; contains tool, arguments, and the requirements array:
| Precondition type | JSON structure in requirements |
|---|---|
| Trust | {"kind":"trust","required":"trusted"} |
| Public audience | {"kind":"audience","required":"public"} |
| Restricted audience | {"kind":"audience","required":["internal","@finance","alice@corp.com"]} (ordered by built-in audience, @ references, then literal reader IDs). |
| Effect exclusion | {"kind":"effect","excludes":"email.sent"} |
| Attention | {"kind":"attention","mark":"finance-signoff"} |
Consult requests do not disclose the trajectory's current label or existing audience members.
The authority responds with a ruling ("approve" or "deny") and an optional reason:
{
"version": 1,
"answer": {
"ruling": "approve",
"reason": "The user authorized this email."
}
}
See The consult request.
Remedy plans and child returns#
When a tool call is blocked or a result introduces new restrictions, OpenAPPA generates structured remedy plans outlining how the agent can proceed safely:
- For blocked calls, plans can request authority review or propose argument sanitization.
- For restricted results, plans can offer output sanitization or allow the agent to accept label narrowing.
- For side-effecting tools listed in , plans can offer to withhold the result payload from the agent context while recording the tool's declared effects.
A withhold plan executes the tool and suppresses its result payload from the agent (including failure messages). Successful calls still record their declared effects in trajectory history, and the withheld result does not alter the trajectory label.
Subagent Returns#
This section applies to child agents spawned within a parent trajectory family (subagent forks). It does not apply to root forks, which run independent trajectory families from snapshot state and do not cross return boundaries. See Subagent forks and root forks.
Child agents can inspect sensitive data without leaking it to the parent trajectory. When context_control = true is configured, the integration isolates the child's context and buffers its return payload until OpenAPPA evaluates it. The parent selects a return contract before the child begins execution.
OpenAPPA offers return plans in order:
- A direct validation plan checking the raw answer against target return limits.
- Sanitization plans using untagged sanitizers.
- A void return plan that discards the child's return payload entirely.
The parent provides to define audience and trust bounds for the child's return. Passing label = {} binds the return to the parent's current label, preventing the child from introducing narrower restrictions. If a sanitizer is selected, the sanitized output must satisfy those bounds.
Declaring the return#
Return declarations are executed autonomously by the agent without requiring human approval.
When a child spawn is initially blocked, OpenAPPA offers return declaration plans first. The parent executes a return plan and retries the spawn call. OpenAPPA then evaluates any remaining preconditions (such as tool permissions or attention requirements). Once all preconditions are resolved, the child trajectory begins execution. A declaration binds to exactly one spawn; releasing the spawn consumes the declaration.
Parents can also declare return bounds prospectively before issuing the spawn by invoking execute_remedy_plan without an offer_id:
{ "label": {} }
Prospective declarations apply strictly to the parent's next immediate child spawn within the same turn. The declaration remains valid only while the parent's label remains unchanged. If intervening tool calls alter the parent's label, the declaration lapses. Prospective declarations must immediately precede the subagent call with no intervening tool invocations. Fan-out spawns ignore prospective declarations and must configure return contracts at the spawn block.
A host can also declare the return on the spawn's own tool_call event, in the declares field. The field takes the same and optional :
{ "declares": { "label": {} } }
declares selects one of three returns. Without , the return crosses as spoken. With , attests the return. With deferred, the return is a deferred return. A void return or a named output sanitizer needs a plan from the spawn's block.
If the spawn is blocked, OpenAPPA applies the declaration through the block's declaration plan and checks the call again in the same hook. The call is then released, or blocked only by its other preconditions. If no declaration plan of the block fits declares, the block states that the declaration was not applied.
A declaration that already stands for the call, with the same tool and arguments, is kept: declares does not replace it. A prospective declaration also takes precedence over declares.
OpenAPPA refuses a tool_call that carries declares but does not start exactly one subagent. Under a deployment without a spawn is released without a prepared child, so OpenAPPA applies no declaration there.
Deferred returns#
A deferred return sets no limit for the child. The parent decides when the child stops, instead of choosing a limit before the child starts. Only an embedded host that delivers a child's answer to the parent itself declares one, and a served hook that declares it is refused. The declaration is deferred in declares, with neither nor , on a call that carries the host's call_id:
{ "declares": { "deferred": true } }
The child may read and accept whatever the parent's own limits allow. OpenAPPA decides the return at the child's stop:
- An empty final message returns nothing.
- An answer that leaves the parent's label unchanged crosses as spoken.
- An answer that would narrow the parent's label is frozen. The hook answers
defer_return, the child's errand ends, and nothing crosses.
The parent decides on a frozen answer once, by calling execute_remedy_plan. The deferral notice gives one reference that accepts the answer and one that discards it:
[appa] The subagent's answer was deferred. Its label is suspicious/a restricted audience; accepting it combines this session's label with that label. Decide once:
Accept: execute_remedy_plan(offer_id: "ret-5f1c02a9d3e84b77")
Discard: execute_remedy_plan(offer_id: "ret-9a40c7e1b2d36f05")
The notice names the answer's trust and whether its audience is restricted, but none of the groups or readers in that audience: the child's own calls chose them.
Accepting returns the answer as the result of that call and combines the parent's label with the answer's label. OpenAPPA refuses an acceptance that would take the parent below a limit the parent itself stands under. Discarding crosses nothing, and a discarded answer cannot be accepted later. Repeating either call answers the recorded decision. Only the trajectory that spawned the child can decide on its answer.
The spawn's own result never carries the child's words. OpenAPPA replaces it with the deferral notice once an answer is frozen, and withholds it otherwise. The notice reads the same before and after the parent decides.
OpenAPPA takes deferred only from declares, and only for a spawn that starts exactly one subagent. A declaration made for a call proposed without deferred does not cover the same call proposed with it, and the reverse.
In the example below, a child agent can inspect internal customer data and pass its return payload through remove_customer_details before the parent receives it:
[[policy.sanitizer]]
name = "remove_customer_details"
on = ["tool_output"]
hint = "Remove customer identities and all other private details from the return."
[policy.sanitizer.permits]
audience = { from = ["internal"], to = ["public"] }
[policy.deployment]
context_control = true
[externals.sanitizers.remove_customer_details]
url = "https://sanitizer.corp/sanitize"
The parent selects this sanitizer plan using its offer_id, constraining the sanitized return to the parent's current label:
{ "offer_id": "<the sanitizer offer ID>", "label": {} }
The declared return limits constrain what the child may read: the child cannot accept restrictions that prevent it from satisfying its return contract. OpenAPPA communicates return requirements to the child at spawn time. If the child's final response violates these constraints, OpenAPPA returns an explanation allowing the child to revise its output.
Void returns#
A suppresses all return communication from the child to the parent trajectory:
{ "offer_id": "<the void offer ID>" }
Because no output crosses the boundary into the parent context, the child's cannot reach the parent's label. The child may accept any label narrowing required for its task. The child must terminate with an empty final message; OpenAPPA blocks non-empty final text or StructuredOutput calls and instructs the child to terminate with an empty response.
Use void returns for child agents that perform autonomous mutations through their own tools without returning data. Void contracts govern return communication only; all tool calls issued by the child remain subject to their own policy contracts.
Fan-out spawns#
A launches multiple concurrent or sequential subagents under a single parent return contract (for example, Claude Code's Workflow tool):
- Each child agent initializes its own fork when launched, inheriting the parent's active label at that moment.
- Each child agent's return is validated independently against the declared return contract. If a subagent uses
StructuredOutput, OpenAPPA checks the output payload against the return bounds. - Available remedy plans include direct validation, untagged sanitizers, and void returns ( is excluded because later agents may start after trust has degraded).
- In Claude Code, child agents are associated with the prompt context of the enclosing
Workflow. ConcurrentWorkflowcalls within the same prompt are rejected until the active workflow completes.
The workflow's own result needs no separate check: the script performs no I/O, so the only data it passes to the parent is the validated child answers.
Child agent transcripts are protected session files; direct tool reads targeting them are denied. The return check covers the child's answer. Files the child writes carry no label unless a recorder tracks them.
Structured child returns#
Use the built-in sanitizer when a child agent must extract structured data (such as integers or enum values) from untrusted inputs without inheriting trust. validates the payload against a declared JSON Schema without mutating it. It can elevate trust from to only when all of the following conditions are met:
- Every schema leaf bounds what the child can return: a boolean, an integer or decimal with declared bounds, a fixed list of choices (
enumorconst), or aformatfrom OpenAPPA's closed list. Free strings, including strings constrained only bypattern, are rejected. - The parent declares the schema before the child reads untrusted data.
- The parent holds status when spawning the child.
[[policy.sanitizer]]
name = "attest-schema"
on = ["tool_output"]
hint = "Validate the child's structured return against the declared schema."
[policy.sanitizer.permits]
trust = { from = "suspicious", to = "trusted" }
[policy.deployment]
context_control = true
The parent provides when selecting the plan:
{
"offer_id": "<the attest-schema offer ID>",
"label": {},
"return_schema": {
"type": "object",
"properties": { "days_allowed": { "type": "integer", "minimum": 0 } },
"required": ["days_allowed"],
"additionalProperties": false
}
}
OpenAPPA evaluates internally; defining an [externals.sanitizers.attest-schema] section is prohibited. Schema validation verifies structural types; it does not validate semantic accuracy.
Example: Customer Ticket Policy#
This policy configuration accompanies the customer ticket sharing walkthrough.
The integration must support result withholding () and subagent context isolation (context_control = true). The example uses an external sanitization service authenticated via APPA_PII_TOKEN:
[policy]
version = 2
[policy.deployment]
context_control = true
confined_results = ["get_ticket_from_crm"]
[policy.audience]
internal = ["google-workspace:full-members"]
[[policy.tool]]
name = "get_ticket_from_crm"
delta = { audience = ["internal"] }
[[policy.tool]]
name = "send_email"
parameters = { type = "object", properties = { recipient = { type = "string" }, body = { type = "string" } }, required = ["recipient", "body"] }
requires = { audience = { contains = ["$recipient"] } }
delta = {}
effects = ["egress"]
[[policy.tool]]
name = "file_github_issue"
requires = { audience = { contains = ["public"] } }
delta = {}
effects = ["egress", "mutation"]
[[policy.sanitizer]]
name = "remove_customer_details"
on = ["tool_output"]
hint = "Remove customer identities and all other private details from the ticket."
[policy.sanitizer.permits]
audience = { from = ["internal"], to = ["public"] }
[[policy.authority]]
name = "user"
[policy.authority.permits]
audience_missing = ["public"]
[externals]
timeout_ms = 2000
max_body_bytes = 65536
[externals.sanitizers.remove_customer_details]
url = "https://sanitizer.corp/sanitize"
token_env = "APPA_PII_TOKEN"
[externals.authorities.user]
builtin = "hitl"
[externals.audience.google-workspace]
url = "https://audience.corp/google-workspace"
selectors = [
{ template = "viewer", feeds = "self" },
{ template = "full-members", feeds = "internal" },
{ template = "group/<group-address>" },
]
After ingesting raw ticket data, the agent can email verified internal organization members. Sending email to external recipients or filing public GitHub issues triggers an authority approval request. If approved, the exception applies to that single invocation while preserving the trajectory's label.
If the agent receives sanitized ticket data (or a sanitized child return), the public output does not restrict the trajectory to .
Because the user authority declares no tags, it can review requests from any tool. See Validation.
Include policy files#
Use to compose modular policy fragments into a root configuration. Declare at the top of appa.toml, outside [policy] and [externals]:
include = ["battery.toml"]
[policy]
version = 2
[externals]
timeout_ms = 2000
max_body_bytes = 65536
Entries can also use wildcards to include all policy files in a directory (e.g. mcp/*.toml), allowing teams to add modular policies without modifying the root configuration:
include = [
"batteries/github/appa.toml",
"mcp/*.toml",
]
Wildcard paths must place * strictly in the filename portion and must end with .toml. Matching files are loaded at that position in alphabetical order:
- Only regular files match. Hidden files, directories, and symlinks are ignored.
- Target directories must reside within the root configuration directory. Directory traversal (
..) is prohibited. - Missing directories match zero files.
- The root policy file never matches its own wildcard pattern.
- Explicitly named files load only at their specific entry and are not duplicated by wildcards.
- Hosted policies cannot use directory wildcards.
OpenAPPA evaluates root declarations before included files, processing included files in the order listed under :
- Included files cannot include other files.
- Included files cannot override deployment-wide settings. The sole exception is under
[policy.deployment]: included files may append tools they declare. Included files must not set[policy.deployment] hint. - Root declarations for or
[[policy.sanitizer]]replace included components sharing the same name. Omitted fields in the replacement are not inherited. - Two included files cannot declare the same annotator name. They also cannot both declare an annotator or sanitizer that the root declares. OpenAPPA refuses such a configuration at load.
- Multiple files cannot configure the same external component name within the same category (e.g. two
[externals.sanitizers.clean]blocks).
See Batteries for pre-packaged policy bundles.
Deployment coverage#
Deployment settings declare the interception and confinement capabilities supported by the agent integration:
[policy.deployment]
confined_results = ["get_ticket_from_crm"]
context_control = true
[[policy.tool]]
name = "get_ticket_from_crm"
delta = { audience = ["internal"] }
lists tools whose result payloads the harness can intercept and withhold from the agent context. If a tool in declares effects and produces a restricted result, OpenAPPA can offer a withhold plan before invocation.
context_control = true asserts that the integration can isolate child agent execution and withhold return payloads until approved by policy. This enables pre-return validation and sanitization. The underlying harness must implement context isolation; setting this flag asserts capability but does not synthesize it.
Constraints:
- A sanitizer requires either a tool listed in or a child return governed by
context_control = true. - Every tool listed in must have a corresponding policy contract (explicit or wildcard).
- Provider-executed tools (tools executed within remote model infrastructure where outputs cannot be intercepted prior to inference) support static declarations only. They cannot declare preconditions, annotators, or argument selectors, and must not appear in .
OpenAPPA rejects configurations requiring integration capabilities that the deployment does not provide. See integration configuration.
Externals#
The [externals] section configures transport bindings for policy components. Each component is defined under , where <kind> specifies the component type (, , , recorders, , or context) and <name> matches the policy declaration.
In the example below, approval requests for support-reviewer route to an HTTP endpoint with a 2-second timeout and a 64 KiB response cap:
[externals]
timeout_ms = 2000
max_body_bytes = 65536
[externals.authorities.support-reviewer]
url = "https://approver.corp/rule"
token_env = "APPA_APPROVER_TOKEN"
Deployment settings:
timeout_ms: Maximum execution time per consult request (default: 5,000 ms).max_body_bytes: Maximum accepted response payload size (default: 65,536 bytes).review_timeout_ms: Maximum duration human review requests remain pending (default: 600,000 ms).
These settings apply to the whole deployment; a binding cannot override them. Model implementations and Jev configure their own timeout_ms and max_concurrent limits in their own sections. max_concurrent bounds concurrent requests to a backend across all active sessions.
Implementation requirements by component type:
| Component kind | Transport options | Binding requirement |
|---|---|---|
authorities | Exactly one of url, command, or builtin. | Optional. Unbound authorities return no answer. |
sanitizers | Exactly one of url, command, or builtin. | Required (except for internal attest-schema). |
annotators | Exactly one of url or command. | Required unless declaring a builtin on the annotator. |
context | Exactly one of url or command. | Optional. Queried for every call requiring dynamic annotation. |
recorders | Exactly one of url or command. | Required for every recorder referenced by a tool contract. |
audience | Exactly one of url, command, or readers; requires selectors on url or command; optional lookup. | Required for each referenced provider and lookup target. Non-empty readers tables are valid only on lookup targets. |
OpenAPPA rejects declared components missing required bindings, and an authority binding that no declaration names. A sanitizer, annotator, recorder, or audience binding that no declaration names stays idle, so a root can bind the components of a battery it may include. For annotators, builtin is declared on rather than under [externals].
Included files may add external bindings and annotator builtins, as well as configuration. Included files cannot override root settings for timeout_ms, max_body_bytes, review_timeout_ms, [externals.claude_code], or .
HTTP services#
Set url to the service endpoint. Remote services must use HTTPS; unencrypted HTTP is permitted only for loopback addresses (such as 127.0.0.1). Credentials must not be embedded in the URL.
If the endpoint requires authentication, set token_env to the name of an environment variable (e.g. APPA_SANITIZER_TOKEN). OpenAPPA forwards the variable's value as an HTTP Bearer token. Variable names must start with APPA_ and must not begin with APPA_PROVIDER_.
Local programs#
Set command to an array specifying the executable and arguments (e.g. command = ["python3", "./sanitize.py"]). OpenAPPA executes the process directly without an intermediate shell, launching it with the configuration directory as its working directory and terminating child processes upon completion. Commands referencing appa invoke the runtime's own binary to execute built-in plugins (such as appa file-tracker).
Commands read a single JSON consult request from standard input and write a JSON response to standard output within timeout_ms and max_body_bytes. APPA_CONSULT_TIMEOUT_MS informs the process of remaining execution time (accounting for queue wait). The runtime limits concurrent local program executions to eight.
If a command requires credentials, specify token_env with an environment variable name prefixed with APPA_PROVIDER_. OpenAPPA passes that variable into the process environment while filtering out other internal APPA_* variables.
OpenAPPA does not require credential variables to be present at policy load time; the process must handle missing credentials at runtime.
The consult request#
Consult requests send a standardized JSON payload to external components across HTTP and local command transports:
{
"version": 1,
"kind": "authority",
"name": "support-reviewer",
"declaration": {
"hint": "Review whether this release of customer information is authorized.",
"permits": { "audience_missing": ["public"] }
},
"artifact": {
"tool": "send_email",
"arguments": { "recipient": "auditor@external.com", "body": "Ticket summary" },
"requirements": [{ "kind": "audience", "required": ["auditor@external.com"] }]
}
}
| Key | Description |
|---|---|
version | Protocol version (must be 1). |
kind | Component type: authority, sanitizer, annotation, audience, or context. |
name | Component identifier declared in policy. |
declaration | Policy constraints, permits, and hints for the component. |
artifact | Call data: proposed tool invocation, data payload, or membership selector. |
Payload structure by component kind:
| Kind | declaration contents | artifact contents | Expected answer contents |
|---|---|---|---|
authority | hint, permits | tool, arguments, requirements | ruling, optional reason |
sanitizer | hint, on, permits; parameters for input rewrites | tool (when known), body | body |
annotation | hint, optional deployment_hint and context_hints, inputs, trust_ranks, audiences, attention_marks, effects | args, context | delta, optional forwards, requires, emits |
audience | templates | selector or member | members or principal |
context | Empty | tool, arguments, optional cwd | Arbitrary JSON or null |
In audience requests, declaration.templates lists the selector templates declared for that provider. The service MUST reject requests if its supported templates do not match this list.
OpenAPPA pins membership responses in the audit record alongside the decision. If an evaluation pauses for approval or remediation, cached membership responses are reused when execution resumes. Fresh decisions execute new membership queries. Replaying recorded decisions reuses saved responses without contacting external services.
Consult requests never expose the agent's full trajectory label, history, or conversation transcript. Components process input data in strictly within the bounds specified by . Context requests uniquely include cwd, and context answers are passed directly to annotators without engine validation.
Components must respond with {"version":1,"answer":{...}} containing fields corresponding to their component type. Additional top-level fields are rejected.
OpenAPPA rejects a response if the service returns an HTTP error, exits with a non-zero status code, times out, exceeds max_body_bytes, or returns malformed JSON.
Model implementations#
The claude-code and llm backends dispatch consult requests to language models. OpenAPPA injects fixed instructions and constraints into the system prompt, including the label guide for annotators. Call data in is sent as user content.
Before dispatching annotator requests to external model providers (claude-code, llm, or jev), OpenAPPA automatically redacts detected credentials in artifact.args using the built-in secret detector. Fields matching credential keywords (password, token, secret, api_key, credential, etc.) or high-entropy tokens are replaced with [redacted-secret]. Redaction is best effort. Authority and sanitizer payloads are not redacted, as sanitizers require raw text for processing.
OpenAPPA checks authority and annotator answers against their permits and assigns sanitized data the declared audience or trust rank. The model is responsible for making the correct judgment or removing the required content.
OpenAPPA derives expected response schemas from the component's declaration. Model backends return the inner answer object directly.
[externals.claude_code] configures the local Claude Code process:
| Field | Description | Default |
|---|---|---|
command | Executable path. | claude |
model | Target model name. | sonnet |
timeout_ms | Per-request timeout including queue wait. | 60000 |
max_concurrent | Maximum concurrent processes. | 4 |
Each consult spawns a fresh claude -p process in a temporary working directory with project settings and tools disabled.
configures direct API integrations for components:
[externals.llm]
provider = "anthropic"
model = "claude-sonnet-4-5"
token_env = "APPA_LLM_TOKEN"
timeout_ms = 30000
max_concurrent = 4
# Optional endpoint override:
# url = "https://gateway.corp/v1"
Supported providers are anthropic, openai, gemini, and ollama. token_env specifies the environment variable holding the API key. url optionally overrides the provider endpoint. timeout_ms defaults to 60,000 ms, and max_concurrent defaults to 4.
Deployments referencing initialize only if the required API token is set in the environment (or if using ollama without authentication). An unused section does not require an API key to load.
Transient failures (connection errors, HTTP 429, or HTTP 5xx) are retried with a 500 ms backoff, up to three attempts in total, if timeout_ms permits.
Requests use provider default temperature and sampling parameters. openai uses the Chat Completions API. ollama defaults to http://localhost:11434 without authentication.
Jev#
The section configures TypeSafe's Jev classifier for annotators:
[externals.jev]
token_env = "APPA_PROVIDER_JEV_API_KEY"
# Optional limits:
# timeout_ms = 2000
# max_concurrent = 16
| Field | Description |
|---|---|
token_env | Environment variable holding the TypeSafe API key. Required; must start with APPA_. |
timeout_ms | Request timeout including queue wait. Defaults to global timeout_ms (minimum: 550 ms). |
max_concurrent | Maximum concurrent requests across the runtime (default: 16). |
Battery policies shipping Jev annotators declare token_env only; root policies can supply timeout_ms and max_concurrent. OpenAPPA sends requests strictly to https://api.typesafe.ai/v1/systemone (or the URL specified by APPA_PROVIDER_JEV_API_URL in the process environment).
Deployments declaring a jev annotator initialize only if the configured API key variable is set. An unused section loads without an API key.
Each consult transmits the tool name, description, and arguments with credentials redacted as described in Model implementations. Payloads exceeding 64 KiB are rejected. Consult records retain diagnostic probabilities under jev_diagnostics.