Skip to content
TapPass

Governance Flags

Flags let agent code attach governance intent to a single call:

X-TapPass-Flags: mode=observe, email=mirror:me@acme.com, pii=mask

The server validates the header against a fixed catalog, resolves it against agent-level defaults and org policy, and records the resolved flags with the call’s audit event and response metadata.

Enforcement note. Flags are intent and metadata. In the current kernel, enforcement comes from policy rules — a flag records what the developer asked for; a rule decides what is enforced. Use flags for per-call context and annotation; use rules for guarantees.

Flag catalog

Section titled “Flag catalog”
Flag Modes Default Intent
mode observe, warn, enforce, lockdown enforce Overall governance posture
email mirror:<addr>, internal:<domain>, reviewqueue, block, allow allow Email tool restrictions
pii mask, block, flag, off off PII handling in responses
budget dev, standard, custom:<per_call>:<per_session>, unlimited unlimited Cost/token caps
tools allowlist:<t1>:<t2>, denylist:<t1>:<t2>, confirm, log, block log Tool call restrictions
files read_only, project, sandbox, block, allow allow File operation restrictions
db read_only, safe_write, block safe_write Database operation restrictions
secrets redact, block, flag redact Secret handling in responses

Unknown flags and invalid modes are silently ignored — a typo never breaks a call.

Resolution order

Section titled “Resolution order”

Flags resolve from four sources; org policy always wins:

  1. Org policy — admins can lock a flag (locked: true); a locked flag cannot be overridden by agents or headers. Orgs can also set a minimum mode — e.g. minimum enforce means a per-call mode=observe is upgraded, never downgraded.
  2. Per-call header — X-TapPass-Flags on the request.
  3. Agent defaults — stored on the agent’s registration.
  4. Catalog defaults — the table above.

Setting flags

Section titled “Setting flags”

HTTP header (any language)

Section titled “HTTP header (any language)”
Terminal window
curl -X POST https://tappass.example.com/v1/chat/completions \
  -H "Authorization: Bearer tp_..." \
  -H "X-TapPass-Flags: mode=observe, pii=mask" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

OpenAI SDK

Section titled “OpenAI SDK”
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={"X-TapPass-Flags": "pii=mask, email=internal:acme.com"},
)

Header format

Section titled “Header format”
X-TapPass-Flags: flag1=mode1, flag2=mode2:param1, flag3=mode3:p1:p2

Comma-separated name=mode[:param…] pairs. A bare name is treated as name=name.

Where flags show up

Section titled “Where flags show up”

Resolved flags (only non-default values) are attached to the call’s response metadata and written into the audit event — so the trail shows not just what was decided, but what the developer declared alongside the call.

Next steps

Section titled “Next steps”