AtPathExpansionMiddleware

Expands @path references in user messages by reading the referenced files through the active AbstractFilesystem and appending an <attached_file> block at the end of the message. Mirrors the Claude Code CLI's @file input syntax.

Dispatch by filesystem type (kept as in-line instanceof since there is exactly one call site):

• Local (OverlayFilesystem wrapping LocalFilesystemWithShell) — attempts fs.read; success triggers attachment, failure (typically because the path falls outside the PathPolicy allow-list) leaves the @path text untouched.

• Sandbox (AbstractSandboxFilesystem, not wrapped in overlay) — treats the reference as a path inside the sandbox; host-path upload is out of scope for this stage.

• Remote (CompositeFilesystem) — disabled. The agent is not co-located with the user so @path has no meaningful resolution; references are left as-is.

Recognises three reference shapes: absolute (@/abs/path), relative (@./rel or @rel/foo), and home-anchored (@~/file). A bare @word with no path-like character (slash, dot, tilde) is ignored to avoid swallowing handles such as @alice.