feat: add file info tracking in the state

[lemopian]

Description

This PR adds comprehensive file state tracking to the file_read, file_write, and editor tools, enabling agents to maintain awareness of their file interactions throughout a session (and cross sessions when session manager is passed).

Key Features

State Management via agent.state:

• Automatically tracks all file operations using Strands' built-in ToolContext and agent.state
• Provides both dictionary access (files dict keyed by path) and sequential lists (files_written, files_read)
• Enables stateful agents that can make decisions based on their file interaction history

Enhanced FileInfo Structure:

• Stores comprehensive metadata: path, is_dir, size, created_at, modified_at
• mode field tracks operation type (e.g., "view", "write", "search", "chunk")
• mode_info field stores mode-specific parameters (e.g., {"chunk_size": 1024, "chunk_offset": 0})

Tools Updated:

• file_write.py: Tracks file writes with mode="write"
• file_read.py: Tracks all 10 reading modes with specific mode_info parameters
• editor.py: Tracks all 7 editor commands with operation-specific details

Documentation & Examples:

• Comprehensive documentation in docs/FILE_STATE_TRACKING.md
• Working examples in examples/file_state_tracking.py demonstrating all features
• Full test coverage in tests/test_file_info.py

Benefits

• Enables audit trails for file operations
• Supports multi-agent coordination through shared state
• Facilitates debugging by tracking how files were accessed
• Provides context for intelligent file operation decisions

Related Issues

Documentation PR

Type of Change

Improving existing Tools

Testing

How have you tested the change?

• I ran hatch run prepare
• All 35 existing tests pass
• Verified backward compatibility - tools work with and without ToolContext
• Tested state tracking across multiple file operations
• Validated mode and mode_info tracking for all file_read modes
• Tested editor commands with state tracking
• Ran example script successfully

Test Coverage:

tests/test_file_info.py::test_get_file_info_for_file PASSED
tests/test_file_info.py::test_get_file_info_for_directory PASSED
tests/test_file_info.py::test_get_file_info_nonexistent_file PASSED
tests/test_file_info.py::test_format_file_info PASSED
tests/test_file_write.py::test_file_write_via_agent PASSED
tests/test_file_read.py::test_file_read_via_agent PASSED
# ... 35 tests total, all passing

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 (docs/FILE_STATE_TRACKING.md)
• I have added an appropriate example to the documentation to outline the feature (examples/file_state_tracking.py)
• My changes generate no new warnings
• Any dependent changes have been merged and published

Files Modified:

• src/strands_tools/utils/file_info.py - Core FileInfo structure and utilities
• src/strands_tools/file_write.py - State tracking for write operations
• src/strands_tools/file_read.py - State tracking for all read modes
• src/strands_tools/editor.py - State tracking for all editor commands
• docs/FILE_STATE_TRACKING.md - Comprehensive documentation
• examples/file_state_tracking.py - Working examples

---

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