feat(claude): attach workspace files as @-mention in Claude mode

[pjdoland]

Summary

Closes #326. In Claude Code mode, workspace files attached via the picker no longer get their contents read client-side and injected as a fenced code block. Instead the backend emits a short prose message with the file path prefixed by @, letting the agent's Read tool decide what (and how much) to load.

This unblocks three cases the content-injection path couldn't handle:

• Images in the workspace: previously rejected by serializeWorkspaceFileContent's binary check, now picker-eligible (the agent uses vision via Read).
• Large files: stop silently truncating at the 80% context-window budget; the agent can grep, then read the relevant slice.
• Notebooks (.ipynb): Claude Code's notebook-aware Read surfaces cells natively instead of dumping the raw JSON.

Solution

Backend (notebook_intelligence/extension.py)

A new branch in the additional-context loop fires when is_claude_code_mode is true, after the existing is_image branch and before the legacy _build_additional_context_message path. It emits "The user attached @<workspace-relative-path>. Read it if relevant to the request." Workspace files use path.relpath against the realpath'd root (computed once before the loop); uploads outside the workspace use the absolute server-temp path (parity with the existing pasted-image branch).

The deictic-reference pointer prose the legacy path produced is preserved as a tail on the @-mention message:

• When currentCellContents is present (active notebook cell, no text selected), append the cell input/output prose so "explain this cell" still has a referent.
• When the entry carries a multi-line selection (endLine > startLine), append "Their selection spans lines N-M." The bulk selection text is intentionally not echoed; the agent reads the file via the @-mention and is told where to focus.

Filename codepoint guard: defense-in-depth on a path that already passed the workspace sandbox. The new has_dangerous_text_codepoints helper (extracted in util.py) wraps the existing _DISALLOWED_URI_CODEPOINTS set already used by safe_anchor_uri (C0/DEL/C1, NEL/NBSP/LS/PS, BOM, ZWSP, bidi-override controls). A filename containing newlines or U+202E would otherwise split or visually impersonate the prose envelope.

Frontend (src/chat-sidebar.tsx)

handleWorkspaceFileSelection short-circuits in Claude mode and skips the contentsManager.get(..., { content: true }) call (which throws on binary), attaching with content: '' and lineCount: 0. One fewer HTTP round-trip per pick. The binary-rejection guard is preserved for non-Claude providers via the same call site.

What stays the same

• The pasted-image branch (is_image && is_claude_code_mode) is intentionally untouched: it already does the right thing for uploaded images, and changing its wording is out of scope.
• The structured cell-output bundle path (outputContext, from PR Extend cell-output context with structured bundles and image support #160) is also untouched. It short-circuits at the top of the additional-context loop before reaching the new branch, so the right-click "Explain / Ask / Troubleshoot" menu continues to deliver images and dataframe HTML as proper vision blocks.

Testing

Seven new tests in tests/test_websocket_handler_integration.py pin the contract:

• @-mention emitted in Claude mode; file contents not echoed, even with a 10MB content blob the legacy path would have truncated.
• is_image branch unchanged in Claude mode (the new branch must not shadow it).
• Out-of-workspace paths (../../etc/passwd) rejected by the pre-existing sandbox before the @-mention branch can format them.
• is_upload=True non-image attachments emit the absolute upload path rather than relpath'ing against the workspace root.
• Filename codepoint guard rejects three vectors: literal newline, U+2028 LINE SEPARATOR, U+202E RIGHT-TO-LEFT OVERRIDE.
• Notebook cell-pointer prose flows through when currentCellContents is present (the cell input/output and "this cell" referent prose all land in chat history).
• Multi-line selection produces a "lines N-M" pointer; bulk selection content does not leak. Whole-document / no-selection cases emit no pointer.

Each new regression test verified to fail against its stashed pre-fix code (cell-pointer test, selection-range test).

Full suite: pytest tests/ --ignore=tests/test_claude_client.py (1050 passed), jlpm tsc --noEmit, jlpm lint:check, jlpm jest (254 passed).

Manual: dropped a binary image from the workspace picker in Claude mode and confirmed it attaches without the "Binary files cannot be attached" error.

Risks / follow-ups

• The pasted-image branch's prose format diverges from the new @-mention format ("It is saved at this path: '<abs>'" vs "@<rel>"). Intentional: pasted-image uploads live outside the workspace where @<abs> wouldn't resolve via Claude Code's workspace-anchored mention parser. Could be unified in a follow-up if uploads land inside jupyter_root.
• The codepoint guard fires only in the new Claude branch. The existing pasted-image and upload-non-image branches embed filenames into prose without it. Worth a defense-in-depth sweep in a separate hardening PR.
• Multi-file attachments emit one {role: user, content: ...} entry per file. The SDK joins them with \n on the wire, so a single combined message would be byte-equivalent today; left as separate messages for clarity.
• The Claude Agent SDK's built-in Read tool is not yet path-sandboxed via safe_jupyter_path (it falls through to the generic per-tool user confirmation). Pre-existing gap, not introduced by this change; worth a separate PR.
• When the user's prompt begins with /, the join logic in claude.py (query_lines[-1].startswith('/')) drops every prior user-role message, including the new @-mention context lines. Pre-existing behavior, documented inline near the @-mention emit so a future reader doesn't chase the @-mention silently disappearing when paired with a slash-command.

Issue linkage

Closes #326.