docs: document safer execution patterns

[akihikokuroda]

Pull Request

Issue

Fix: #1310

Description

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

[jakelorocco]

I looked at the docstring for CapabilityPolicy; I see:

    The enforcement gap — the difference between what is *declared* and what is
    *actively enforced at runtime* — is made explicit through per-field
    `ENFORCED_*` class attributes.  Callers and UX layers can read these to
    decide whether to prompt the user ("allow once / allow always") or display
    a warning.

    .. warning::
        **Most fields are declarative only and are not enforced at runtime.**
        Setting `network_access=False`, `package_installation=False`,
        `subprocess_execution=False`, or `env_var_access=False` does *not*
        block those capabilities in the current implementation — the declared
        value is informational only.  Check the `ENFORCED_*` class attributes
        to see what is actively enforced.  For stronger isolation use a
        `"docker"` execution tier.

        `filesystem_read_roots` and `filesystem_write_roots` emit a
        :class:`UserWarning` at construction time when set to a non-`None`
        value, because those restrictions are also unenforced.

If this is true and these things aren't enforced, then I don't think we should advertise them as such in these examples / code snippets. If these things are enforced, please change the CapabilityPolicy docstring.

[akihikokuroda]

Code snippet is updated.

1. Added a clarifying comment explaining that most policy fields are declared only, not enforced
2. Updated inline comments to explicitly distinguish between enforced fields (timeout, max_output_chars) and declared-only fields (network_access, package_installation)
3. Referenced the escape hatch (CapabilityPolicy.ENFORCED_* class attributes) so readers know how to check what's enforced

[AngeloDanducci]

Likely should be (timeout, sdtoutput limits) - I don't think we restrict memory anywhere via policy even in the docker tier.

[akihikokuroda]

Thanks! it is corrected.