Right now, tool handlers registered via the @tool decorator only receive the input arguments — there's no way for a tool to know which session it's running in, or what the conversation looks like so far.
I've been building tools that need to make decisions based on prior conversation context (e.g., a summarization tool that needs to see what was discussed, or a dedup tool that checks if similar work was already done in the same session). Currently the only workaround is to pass this info as explicit tool arguments, which is awkward since Claude has to serialize conversation state into the tool call.
Proposal: add an opt-in ToolContext parameter to tool handlers that carries:
session_id — the current session identifiertranscript_path — path to the session transcript (for tools that want to read history directly)conversation_history — lazy-loaded list of prior messages parsed from the transcript
This would be backward-compatible — tools that don't declare a context parameter would continue working as-is. Detection would use signature inspection (similar to how some frameworks detect optional context/state params).
Rough sketch:
\\python
from claude_agent_sdk import tool, ToolContext
@tool('summarize', 'Summarize the conversation so far', {})
async def summarize(args, context: ToolContext):
history = context.conversation_history
# ... use history to produce summary
\\
Related: #311 (context slots) addresses a similar need from the state-management angle. This proposal focuses specifically on giving tools read access to the existing conversation.
Right now, tool handlers registered via the
@tooldecorator only receive the input arguments — there's no way for a tool to know which session it's running in, or what the conversation looks like so far.I've been building tools that need to make decisions based on prior conversation context (e.g., a summarization tool that needs to see what was discussed, or a dedup tool that checks if similar work was already done in the same session). Currently the only workaround is to pass this info as explicit tool arguments, which is awkward since Claude has to serialize conversation state into the tool call.
Proposal: add an opt-in
ToolContextparameter to tool handlers that carries:session_id— the current session identifiertranscript_path— path to the session transcript (for tools that want to read history directly)conversation_history— lazy-loaded list of prior messages parsed from the transcriptThis would be backward-compatible — tools that don't declare a context parameter would continue working as-is. Detection would use signature inspection (similar to how some frameworks detect optional context/state params).
Rough sketch:
\\python
from claude_agent_sdk import tool, ToolContext
@tool('summarize', 'Summarize the conversation so far', {})
async def summarize(args, context: ToolContext):
history = context.conversation_history
# ... use history to produce summary
\\
Related: #311 (context slots) addresses a similar need from the state-management angle. This proposal focuses specifically on giving tools read access to the existing conversation.