Feature Request: allow the host application to supply files and documents as session context

No files, tests, or entry points are identified in the issue. Start by locating the session-creation and subsequent-turn APIs, then trace how resources would be ingested and reported. Done means attached text and binary resources work without repository commits, and unsupported, oversized, or inaccessible resources produce actionable results.

Problem

A session can be given a prompt and a repository. It cannot be given the surrounding material that motivated the work: a specification, a design document, a log file, a crash dump, a screenshot, or a prior conversation transcript. That material typically lives outside source control and should not be committed to the repository merely to make the agent aware of it.

Today the only reliable workaround is to paste the content into the prompt, which loses fidelity and structure for anything that is not plain text, or to commit the file to the repository, which pollutes history with transient artifacts.

What is missing

• No API for attaching arbitrary files or binary content to a session as first-class resources.
• No way to supply an external transcript or prior conversation as additional grounding.
• No feedback about which supplied resources were actually read, skipped, or rejected.

Proposed behavior

• Session creation and subsequent turns accept a list of context resources, each with content or a resolvable reference, a MIME type, and a display name.
• Supplied resources are available to the agent for reading and are distinguishable from repository files.
• The session reports, per resource, whether it was ingested successfully; failures state the reason, such as unsupported type, size limit, or missing permission.
• Size and count limits are documented and enforced predictably.

Example scenario

A caller supplies a design document and two log files alongside a prompt asking the agent to determine whether the implementation matches the design and to explain a failure visible in the logs.

Acceptance criteria

• Files and binary content can be attached to a session without committing them to the repository.
• Attached resources are readable by the agent and reported in the session result.
• Ingestion failures are explicit and actionable.

Related

• #2349 — attachments silently ignored in one command path; this request covers the general capability.