fabro/docs/public/agents
Scott Werner d58e722647 fix(hooks): keep allowed_env_vars enforced for header interpolation
HTTP-hook headers carry credentials, so a `{{ env.NAME }}` token in a
header value must only resolve env vars the hook explicitly opts into via
`allowed_env_vars`. The typed-interpolation rewrite dropped that
allowlist: headers resolved any `{{ env.* }}` while `allowed_env_vars`
was parsed, carried, and documented but ignored in the executor — a
silent fail-open regression.

Restore the allowlist as a fail-closed control without reviving the
removed template env API. Header values now resolve through a scoped env
lookup that returns a value only for names in the hook's
`allowed_env_vars` and `None` otherwise, so a non-allowlisted
`{{ env.X }}` resolves as absent (Missing) and the hook blocks before
firing — never sending a half-resolved or empty credential header. An
empty `allowed_env_vars` permits no env vars in headers, matching the
prior behavior. The allowlist applies only to headers; url, command,
prompt, and model keep no allowlist.

Also:
- Correct the resolve helper doc comments to say env is the only wired
  namespace; secrets/vars/inputs are unavailable here and fail closed.
- Log the unresolved URL token source instead of the resolved URL on
  header/URL resolution failures, so a URL-embedded credential cannot
  leak into logs.
- Update the hooks docs and the OpenAPI `headers`/`allowed_env_vars`
  descriptions to document `{{ env.NAME }}` token interpolation and the
  enforced header allowlist.

Tests cover both directions: an allowlisted var resolves and the header
is sent, while a non-allowlisted var blocks and never fires the request.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 20:49:00 -04:00
..
hooks.mdx fix(hooks): keep allowed_env_vars enforced for header interpolation 2026-06-29 20:49:00 -04:00
mcp.mdx feat(sandbox): secure daytona snapshot names (#429) 2026-05-27 11:52:35 -04:00
outputs.mdx docs: clarify structured output fallbacks 2026-05-25 10:56:53 -04:00
permissions.mdx refactor(docs): split docs/ into public/ and internal/ 2026-04-27 07:21:13 -07:00
prompts.mdx docs: sync public docs to recent changes 2026-05-18 14:42:54 -04:00
skills.mdx refactor(docs): split docs/ into public/ and internal/ 2026-04-27 07:21:13 -07:00
subagents.mdx docs: add child runs guide 2026-05-25 15:43:53 -04:00
tools.mdx refactor: rationalize server secret scopes (vault-only for optional int… (#401) 2026-05-25 17:26:01 -04:00