feat: expose internals through tool decorator param StrandsContext

[dbschmigelski]

Description

Previously, @tool-decorated functions could not access the same contextual information available to module-based tools, specifically the tool_use_id and other framework-provided data. This limitation made it impossible for decorated tools to implement features like global storage indexing or request tracking that required access to tool execution metadata.

Solution

This PR introduces StrandsContext, a typed dictionary that provides @tool-decorated functions with access to framework-level context data in a future-proof and backward-compatible way.

Name very much open for suggestions

Key Features

Backward Compatibility
All existing @tool functions continue to work unchanged. Existing agent parameter injection remains fully functional with no breaking changes to current tool implementations.

Future-Proof Design
Single reserved parameter name (strands_context) eliminates risk of future naming conflicts. Extensible TypedDict structure allows adding new context fields without breaking changes. Defensive architecture prevents accidental parameter collisions as the framework evolves.

Type Safety
Full TypeScript-like typing with IDE autocomplete support. StrandsContext provides structured access to tool_use: ToolUse for complete tool invocation details including toolUseId, and invocation_state: dict[str, Any] for agent state and execution context.

Usage Example

from strands import tool, StrandsContext

@tool
def my_storage_tool(data: str, strands_context: StrandsContext) -> dict:
    # Access tool_use_id for indexing
    tool_use_id = strands_context["tool_use"]["toolUseId"]

    # Access agent from invocation state
    agent = strands_context["invocation_state"]["agent"]

    # Use for global storage, tracking, etc.
    global_storage[tool_use_id] = data

    return {"status": "success", "content": [{"text": f"Stored with ID: {tool_use_id}"}]}

Convenience Features

For common use cases, we maintain convenient parameter injection. The agent parameter continues to work as before for easy agent access. strands_context provides comprehensive access when needed. Tools can use either approach based on their requirements.

Future Roadmap

Strongly Typed InvocationState: We're planning to replace invocation_state: dict[str, Any] with a proper InvocationState TypedDict in an upcoming release. This will provide better type safety for framework-provided state, IDE autocomplete for known invocation context fields, and clearer documentation of available context data.

The current StrandsContext design accommodates this future enhancement without requiring changes to existing tool implementations.

Related Issues

#194

Documentation PR

Documentation PR to be raised before merging after naming is aligned.

Type of Change

New feature
Breaking change

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 hatch run prepare

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.

[dbschmigelski]

Related #580

After discussing offline that we want so synchronize the overall tool context population. So a revision will be made so the way/object we populate decorated, module, class tools will all try to leverage the same object.