feat(tools): add optional security metadata to tool definitions

[srbhsrkr]

Summary

Closes #2154

• Adds optional read_only, destructive, and requires_confirmation parameters to the @tool decorator and corresponding properties to AgentTool base class
• Extends ToolSpec with a SecurityMetadata TypedDict for serializable security classification
• Propagates security metadata through ToolRegistry and MCPAgentTool so hooks can reason about tool safety via BeforeToolCallEvent

Details

New @tool decorator parameters (all optional, backward-compatible):

@tool(read_only=True)
def list_files(directory: str) -> list[str]: ...

@tool(destructive=True, requires_confirmation=True)
def delete_file(path: str) -> str: ...

AgentTool properties with safe defaults (False):

• is_read_only — tool only reads state
• is_destructive — tool performs irreversible actions
• requires_confirmation — tool should require user confirmation

Hook integration — BeforeToolCallEvent now exposes selected_tool so hooks can inspect security metadata:

def before_tool_call(self, event):
    if event.selected_tool and event.selected_tool.is_destructive:
        event.cancel_tool = "Destructive tool blocked"

Test plan

• Unit tests for @tool decorator with security metadata combinations
• Unit tests for AgentTool default property values
• Unit tests for ToolRegistry metadata propagation
• Unit tests for MCPAgentTool security metadata support
• Unit tests for BeforeToolCallEvent.selected_tool integration
• Backward compatibility — existing tools work unchanged
• All 92 related tests pass