fix: document /etc/hosts sandbox issue and add bwrapExtraBinds config

[Oxygen56]

Summary

Fixes issue #861: When the SDK runs inside Docker with sandbox.enabled=True, the bwrap sandbox does not expose /etc/hosts inside the isolated filesystem namespace, breaking localhost DNS resolution and proxy connections (e.g., botocore credential fetching in AWS Bedrock AgentCore).

Root Cause

The bwrap command is constructed by the CLI via @anthropic-ai/sandbox-runtime (see linux-sandbox-utils.js wrapCommandWithSandboxLinux()). It uses --ro-bind / / as the base filesystem mount, but when running inside Docker with --unshare-user (triggered by enableWeakerNestedSandbox), container-managed files like /etc/hosts may not propagate correctly into the sandbox namespaces. The permanent fix requires a CLI update to explicitly bind-mount /etc/hosts and /etc/resolv.conf.

SDK Changes

1. Documentation: Added "Known issue" section to SandboxSettings docstring explaining the problem and workarounds (disable sandbox or use excludedCommands).

2. bwrapExtraBinds config: Added a new optional field to SandboxSettings that allows specifying additional --ro-bind source paths for the Linux bwrap sandbox. This is a forward-looking config surface — users can set ["/etc/hosts", "/etc/resolv.conf"] for when the CLI adds support for this feature.

3. Tests: Added test_sandbox_with_bwrap_extra_binds verifying the field passes through the --settings JSON correctly.

How Sandbox Config Flows

ClaudeAgentOptions.sandbox (Python SDK) → _build_settings_value() → --settings <JSON> (CLI flag) → CLI configures @anthropic-ai/sandbox-runtime → wrapCommandWithSandboxLinux() constructs bwrap args → bwrap executes command.

The sandbox-runtime source analysis is in the PR description for reference.

Workaround (until CLI is fixed)

options = ClaudeAgentOptions(
    sandbox={"enabled": False}  # Disable sandbox in Docker environments
)

Or use excludedCommands:

options = ClaudeAgentOptions(
    sandbox={
        "enabled": True,
        "excludedCommands": ["python", "aws", "curl"],
    }
)