Inherit user-attached files in sub-agent sessions

[dgageot]

Problem

When a user attaches a file via @-mention in their initial prompt, only the root agent sees the file content (it's inlined into the user message). When that agent then delegates work via transfer_task, the sub-agent starts in a fresh session with no record of which files the user originally attached. If the parent's task description says "edit something.go" instead of "edit /abs/path/something.go", the sub-agent must scan the workspace, often picks the wrong file when several share the same name, and burns tokens doing it.

This was reported as a frequent pain point when working with multi-agent teams. See: user feedback in the issue.

Approach

Two complementary changes — one prompt-only, one structural:

A. Prompt guidance (LLM-side reminder)

• The parent agent's "you are a multi-agent system" prompt now explicitly says: when the task involves files, always include absolute paths in task; sub-agents do not see the conversation history or attached files.
• The sub-agent's task system message now says: treat absolute paths in <task> as authoritative; if a referenced file is given by name only, do not guess — search the workspace or ask the calling agent.

This catches the case where the parent agent itself discovers a new file mid-flight (i.e. files that were never attached by the user).

C. Inherit attached files in sub-sessions (deterministic)

• New Session.AttachedFiles []string field with AddAttachedFile, AttachedFilesSnapshot, and a WithAttachedFiles option (deduplicated, order-preserved).
• The TUI App.Run path and the CLI PrepareUserMessage / CreateUserMessageWithAttachment helpers register every successfully attached file's absolute path on the session.
• runtime.newSubSession snapshots the parent's AttachedFiles, propagates them to the child via WithAttachedFiles, and surfaces them in the task system prompt under <attached_files>. Sub-sub-sessions inherit too because the child becomes the next parent.
• branch.go and the in-memory store preserve AttachedFiles when copying session metadata.
• In-memory only (not persisted in SQLite) — the use case is delegation within an active session; reloaded sessions can re-attach.

This is the structural fix that doesn't trust the LLM to remember.

Why both?

	A alone	C alone	A + C
Files the user attached with @	LLM may still drop the path	✅ deterministic	✅ deterministic
Files the parent agent discovers mid-flight	✅ LLM is reminded	✗ not in AttachedFiles	✅ LLM is reminded

Commits

1. a896bc03d Encourage absolute file paths when delegating to sub-agents — prompt-only change in pkg/session/session.go (parent prompt) and pkg/runtime/agent_delegation.go (sub-agent prompt). E2E cassettes (TestA2AServer_MultiAgent, TestRuntime_MultiAgent_SessionReload) updated to match.

2. 359b8f6a8 Propagate user-attached files to sub-agent sessions — adds the AttachedFiles plumbing (session field + helpers, TUI/CLI registration, sub-session inheritance, system-prompt surfacing). New tests in pkg/session/session_options_test.go and pkg/runtime/agent_delegation_test.go.

3. 86641e4fe Tidy up the AttachedFiles plumbing — pure refactor, no behaviour change. Single strings.Builder in buildTaskSystemMessage, noAttachment closure to collapse seven duplicated returns in CreateUserMessageWithAttachment, drops a double clone in branch.go, trims over-eager comments.

4. 22e40848e Reject dangling and non-absolute paths in AttachedFiles — review fixes:

   • Bug: App.Run recorded att.FilePath before processFileAttachment validated it, so paths to missing files or directories silently propagated to sub-agents. processFileAttachment now returns a bool ("the path resolved to a real, regular file") and App.Run only records on true. Content-handling failures (too large to inline, unsupported MIME, transient read errors) still record because a sub-agent may have larger limits or different tools than the parent.
   • Quality: AddAttachedFile's parameter is named absPath and the docstring claims absolute, but the function accepted any string. Added a filepath.IsAbs guard with a slog.Debug for visibility.
   • Doc: Session.AttachedFiles field comment now mentions all three entry points (@-mention, /attach, --attach).

Tests

• mise test ✅ all green
• mise lint ✅ green (golangci-lint run: 0 issues, custom lint .: 778 files, no offenses, go mod tidy --diff: clean)
• New unit tests: TestAddAttachedFile (dedup, empty, non-absolute, snapshot independence), TestWithAttachedFiles, TestSubSessionInheritsAttachedFiles, TestSubSessionWithoutAttachedFilesOmitsBlock, plus expanded cases in TestBuildTaskSystemMessage.
• E2E cassettes for multi-agent tests updated and replay cleanly.

What's intentionally not changed

• Not persisted in SQLite. The use case is delegation within an active session; persisting would need a schema migration with no current consumer.
• No exposure via HTTP API. GET /sessions and GET /sessions/:id use curated DTOs (api.SessionsResponse, api.SessionResponse) that don't include AttachedFiles. POST /sessions echoes a freshly-created session where the field is empty. Same exposure surface as the pre-existing CustomModelsUsed.
• AttachedFiles is not literal @-resolution by sub-agents. That would reproduce an editor concern in the runtime and doesn't help when the parent drops the @ entirely (the actual reported failure mode).