feat: update vended tools/plugins for sandbox compatibility"

[gautamsirdeshmukh]

Description

Update vended tools (bash, fileEditor) and plugins (context offloader, skills) to be Sandbox compatible.

This is the fourth PR split off from strands-agents/sdk-typescript#1011, preceded by the base interface merged in strands-agents/sdk-typescript#1090, Docker/SSH implementations merged in strands-agents/sdk-typescript#1110 and Agent integration merged in #2563.

What's New

• Vended tools (bash, file editor) as now sandbox-aware, all routing handled under the hood
• Vended plugins (context offloader, skills) are now sandbox-aware, all routing handled under the hood
  • Added SandboxStorage file storage implementation for context offloader
• getTools() overridable method added to sandboxes enabling default tool registration
  • Empty by default, bash and file editor auto-registered for Docker and SSH sandboxes
• makeBash() factory for generating bash tool instances with environment-appropriate descriptions

Related Issues

• feat: Sandbox parent PR (base/shell/remote/docker/tools/plugins) sdk-typescript#1011 (parent mega-PR)
• feat: base Sandbox interface sdk-typescript#1090 (base Sandbox / PosixShellSandbox interfaces)
• feat: add Sandbox implementations (Docker, SSH) sdk-typescript#1110 (Docker / SSH implementations)
• feat: integrate Sandbox with Agent #2563 (Agent integration)

Documentation PR

Not yet

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran all tests + added several

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Issue: This PR adds sandbox as a new public property on the LocalAgent interface and the AgentConfig type. It also introduces statFile as a new abstract method on the Sandbox base class (a breaking change for external implementors), and adds getTools() to Sandbox. These are moderate-to-substantial API surface changes that affect customers implementing Sandbox or LocalAgent.

Per the API Bar Raising process, this PR should have the needs-api-review label. The PR description documents the feature well but doesn't include the specific API review materials (complete API signatures with defaults, example usage snippets from a customer perspective, module exports map).

Suggestion: Add the needs-api-review label and include a brief API summary section in the PR description showing:

1. New AgentConfig.sandbox option with usage example
2. New abstract statFile() on Sandbox (breaking for existing custom implementations)
3. getTools() override point on Sandbox

[github-actions]

Assessment: Comment

Well-structured PR that makes vended tools sandbox-aware with a clean architecture (default slot pattern, environment-conditional entry points). The code is modular and well-tested.

Review Categories

• API Semantics: The sandbox: false option's documented intent ("distinct opt-out") doesn't match its runtime behavior (same as omitting). The getter uses || which treats false and undefined identically — clarify the documentation or fix the implementation.
• Breaking Changes: New abstract statFile() on Sandbox breaks existing custom implementations. Since Sandbox was introduced recently, this is likely acceptable but should be documented.
• Exports Completeness: SandboxTimeoutError, SandboxAbortError, DockerSandbox, SshSandbox, and NotASandboxLocalEnvironment are not re-exported from the top-level index, which contradicts the "Prefer Flat Namespaces" decision record.
• Implementation Coupling: The instanceof NotASandboxLocalEnvironment check in bash.ts is a capability-routing decision hardcoded to a concrete class rather than an interface/capability flag.
• Feature Parity: NotASandboxLocalEnvironment silently ignores the env option in ExecuteOptions, unlike the Docker/SSH implementations.
• API Review Process: This PR introduces new public API surface (AgentConfig.sandbox, LocalAgent.sandbox, Sandbox.statFile, Sandbox.getTools) and should have the needs-api-review label per the bar-raising process.

The overall design is solid — default slot for environment-specific behavior, clean test separation by environment, and good use of the streaming infrastructure.

[github-actions]

Issue: The PR introduces or modifies several public API surfaces (new sandbox config on Agent, new statFile abstract method, new getTools() on Sandbox, new SandboxStorage export, new DefaultNotConfiguredError). The PR description documents use cases and what's new, but doesn't include API signatures with defaults or module export changes in the format expected by the API bar-raising process.

Suggestion: Consider adding the needs-api-review label given the scope of public API changes — particularly the new abstract method on Sandbox (breaking) and the new property on LocalAgent interface (breaking). These merit explicit API reviewer sign-off per the bar-raising guidelines.

[github-actions]

Assessment: Comment

Well-architected feature that cleanly integrates sandbox awareness into vended tools and plugins. The defaultSlot pattern, node-specific entry point, and tool-routing approach are all solid design choices.

Review Categories

• API Breaking Changes: Adding statFile as abstract on Sandbox and sandbox on LocalAgent are breaking changes for downstream implementors — these should be called out and either mitigated (default implementations) or versioned appropriately.
• API Design: The sandbox: false config option documents a future distinction that has no runtime effect today — this adds API surface area without clear value. The instanceof NotASandboxLocalEnvironment check in bash is a fragile discrimination mechanism.
• Public API Completeness: SandboxTimeoutError and SandboxAbortError should be exported so consumers can catch them by type.
• API Bar-Raising: Given the scope of public API additions (new abstract methods, new interface properties, new exported classes), this PR likely warrants the needs-api-review label.

Good test coverage overall and the architecture cleanly separates concerns between the sandbox abstraction, the default-slot mechanism, and the tool routing.

[mkmeral]

any reason we don't support input schema, and name too?

[gautamsirdeshmukh]

Updating to take name and inputSchema along with description

[mkmeral]

let's namespace tool names

[gautamsirdeshmukh]

Updating to namespace with sandbox_{toolname} the way MCP adds mcp_{toolname}