feat: environment variable filtering with filter_env, allowed_env, disallowed_env

[ppsplus-bradh]

Summary

Adds a complete environment variable control surface for CLI session spawning. Three new session options give users fine-grained control over which system env vars reach the CLI:

Option	Type	Default	Purpose
filter_env	boolean	true	Toggle built-in allowlist filtering on/off
allowed_env	[String.t()]	[]	Additional keys to pass through (additive to built-in allowlist)
disallowed_env	[String.t()]	[]	Keys to exclude (works in both modes)

Naming follows the SDK's existing convention (allowed_tools/disallowed_tools).

Depends on

• Refactor: direct spawn_executable (remove shell escaping) #42 (direct spawn_executable refactor) — this PR builds on top of the build_env/prepare_env changes from that PR.

How it works

Filtered mode (filter_env: true, default):

System.get_env()
  → filter: key in (built-in allowlist OR allowed_env) AND key not in disallowed_env
  → Map.new()

Unfiltered mode (filter_env: false):

System.get_env()
  → reject: key in disallowed_env
  → Map.new()

Setting filter_env: false with no other options reproduces the pre-filter behavior exactly — all system env vars pass through unchanged.

Both paths then merge identically with SDK vars, user :env overrides, and API key.

Examples

# Default: secure minimum, add specific vars
ClaudeCode.start_link(allowed_env: ["DATABASE_URL"])

# Everything except secrets
ClaudeCode.start_link(filter_env: false, disallowed_env: ["RELEASE_COOKIE", "GITHUB_SSH_KEY"])

# Pre-filter behavior (no filtering)
ClaudeCode.start_link(filter_env: false)

Changes

• port.ex: Built-in allowlists (@cli_env_prefixes, @cli_env_allowlist, @system_env_allowlist), collect_system_env/3, filter_system_env/1, cli_env_var?/2
• options.ex: Schema definitions for filter_env, allowed_env, disallowed_env
• command.ex: convert_option nil returns for new options
• port_test.exs: Tests for filtering, allowlist, prefix matching, exclusion
• CHANGELOG.md: Documented under Added

[guess]

also this - i did a squash + merge so just have to remove the #42 commits

[ppsplus-bradh]

Rebased on main.

[col]

Very keen to see this merged. Nice work @ppsplus-bradh !

[guess]

So disallowed_env is already implicitly supported through :env since erlang's port already supports false as a value to unset env variables: https://www.erlang.org/doc/apps/erts/erlang.html#open_port/2

So I think I'd rather maintain consistency with how the Python SDK behaves and pass all system env by default. You can use :env to override or unset them. And we can add a single allowlist option if you want to explicitly define the allowed env that can be inherited from the system. Then instead of 4 env-related options, we'll just have 2.

I'm working on a PR for this now.

[ppsplus-bradh]

So disallowed_env is already implicitly supported through :env since erlang's port already supports false as a value to unset env variables: https://www.erlang.org/doc/apps/erts/erlang.html#open_port/2

So I think I'd rather maintain consistency with how the Python SDK behaves and pass all system env by default. You can use :env to override or unset them. And we can add a single allowlist option if you want to explicitly define the allowed env that can be inherited from the system. Then instead of 4 env-related options, we'll just have 2.

I'm working on a PR for this now.

Awesome! Didn't realize we already inherently had that level of flexibility.

[guess]

@ppsplus-bradh thanks again for your help/work on these 🙏