Configuration

The proxy is configured entirely through environment variables — there's no config file.

Environment variables

Fail-open vs. fail-closed

TAWA_PROXY_FAIL_MODE decides what happens if the call to Tawa's scan endpoint fails — not what happens when a scan succeeds and returns a block, which always blocks regardless of this setting.

• open (default): if the scan call itself fails, the request forwards to Anthropic anyway. A Tawa outage degrades you back to unprotected Claude Code rather than a broken one.
• closed: if the scan call fails, the request is rejected instead of forwarded. Choose this if you'd rather Claude Code stop working outright than run a single turn unscanned.

What triggers a block

By default, a scan verdict of BLOCK, HARD_BLOCK, or SANDBOX stops it — an Anthropic-shaped 400 error on the request side (Claude Code never reaches Anthropic), or a protocol-level event: error SSE frame on the response side that ends the stream before a blocked tool call or reply reaches the client. Every other verdict (ALLOW, REVIEW, SOFT_BLOCK, AMBIGUOUS, OOD) forwards through by default. This mirrors the SDKs' own action severity ladder (see How Tawa works), narrowed to a binary forward-or-block decision because there's no human in a local CLI's loop to hand an ambiguous verdict to — the same threshold applies to the inbound request scan and both outbound scans (tool call and model reply).

Override which tiers actually block with TAWA_PROXY_BLOCK_ACTIONS — a comma-separated list of any of ALLOW, REVIEW, SOFT_BLOCK, BLOCK, HARD_BLOCK, SANDBOX, AMBIGUOUS, OOD:

# Also stop on SOFT_BLOCK and REVIEW, not just the hard-block family:
TAWA_PROXY_BLOCK_ACTIONS=BLOCK,HARD_BLOCK,SANDBOX,SOFT_BLOCK,REVIEW

# Narrower than the default — only a HARD_BLOCK stops anything:
TAWA_PROXY_BLOCK_ACTIONS=HARD_BLOCK

Scanning the model's own reply

By default, the model's own visible reply (any text content block in the streamed response) is scanned too — via the same scan route as analyze(), tagged llm_response provenance — before it reaches Claude Code. This catches a different threat shape than tool-call gating: a hijacked model can exfiltrate something it read (a secret in a file, credentials from a tool result) just by printing it in its answer, with no tool call involved at all.

Turn it off entirely if that's not worth it for a given workflow — e.g. you only care about stopping tool calls, not what the model says:

TAWA_PROXY_SCAN_OUTPUT_TEXT=false

An empty reply (or one that's all whitespace) is never sent for scanning regardless of this setting — there's nothing to evaluate. tool_use gating is unaffected either way; this only controls the text side.

Streaming checkpoints vs. standard mode

Once output-text scanning is on, TAWA_PROXY_OUTPUT_CHUNK_CHARS decides how it's scanned — this is the actual cost/delay trade-off, and it's worth understanding before turning the feature on for a team.

• Streaming checkpoints (default, 400): every time roughly that many new characters have streamed in, the proxy scans everything accumulated so far (the whole utterance up to that point, not just the new fragment — an isolated fragment is a weaker detection signal) and releases whatever's cleared to Claude Code. The reply keeps feeling like normal streaming instead of arriving in one dump at the end, at the cost of one scan call per checkpoint — a reply long enough to cross the checkpoint several times costs several scans, not one.
• Standard mode (TAWA_PROXY_OUTPUT_CHUNK_CHARS=0): no mid-stream checkpoints. The entire reply is held until the model finishes generating it, scanned exactly once, then released (or blocked) as a single piece. Fewer scan calls, but a human watching the reply stream sees nothing at all until the whole thing has both finished generating and cleared a scan — for a long reply, that's a real, felt delay, not a rounding error.

# Smaller checkpoints: closer to un-gated streaming, more scan calls
TAWA_PROXY_OUTPUT_CHUNK_CHARS=150

# Standard mode: one scan per reply, but nothing streams until it's done
TAWA_PROXY_OUTPUT_CHUNK_CHARS=0

tool_use blocks are never chunked regardless of this setting — a proposed tool call is always scanned exactly once, at the instant its arguments finish streaming, since there's no partial-JSON checkpoint that would mean anything.

Session correlation

If Claude Code sends an x-claude-code-session-id header, the proxy passes it through to Tawa as session_id on every scan from that session — purely to correlate related scans in Tawa's own event stream/audit trail. It's opaque to the proxy; nothing about it is parsed or validated.

Not yet configurable here

• Per-user identifiers (cuid / tenant_id in the SDKs — see Identifiers) — there's no way yet to attribute a proxy's scans to a specific end user or tenant.
• Policy Studio directives (policy_overrides in the SDKs — see Policy rules and Enforcing a policy) — your org's Policy Studio rules aren't evaluated or enforced by this proxy.
• Language hints (language in the SDKs) — not passed through.
• A fully custom block predicate (shouldBlock in the SDKs takes an arbitrary function of the whole ScanResult) — TAWA_PROXY_BLOCK_ACTIONS above covers picking which verdict tiers block, but not arbitrary logic (e.g. "block by confidence score" or "block based on rationale").

If you need any of these today, they're available through the TypeScript or Python SDK directly — just not through this proxy yet.