Support explicit session file paths for persistent subagents #131

Summary

Please support an explicit subagent session file path/name, not only persist_session: true plus session_dir.

Today persist_session can write a subagent as a normal Pi session and session_dir can choose the directory, but the actual JSONL filename is still generated by Pi's SessionManager. For larger multi-task workflows it would be useful to make the file path deterministic and user-managed.

Motivation

When coordinating many tasks, I often want stable semantic subagent sessions such as:

.agents/sessions/KEY.dev.jsonl
.agents/sessions/KEY.reviewer.jsonl
.agents/sessions/KEY.plan.jsonl

This makes the session file itself part of the task workflow:

• the parent/orchestrator can intentionally assign a durable lane to a subagent;
• humans can later inspect, resume, or reply to the same session by path;
• external task dashboards can map issue keys and roles to known files without guessing generated session IDs;
• background agent management becomes much easier when many Linear/GitHub/GitLab tasks are active at the same time;
• repeated plan/review/dev loops can reuse a stable context instead of creating many unrelated generated session files.

Desired API

One possible design is to add a frontmatter field, for example:

---
persist_session: true
session_file: .agents/sessions/KEY.reviewer.jsonl
---

And/or support an Agent tool parameter for dynamic task-specific use:

Agent({
  subagent_type: "reviewer",
  prompt: "Review the current implementation",
  description: "Review KEY",
  run_in_background: true,
  session_file: ".agents/sessions/KEY.reviewer.jsonl",
})

The exact name is not important; session_file, session_path, or another explicit term would be fine.

Expected behavior

• Relative paths should resolve from the agent cwd, similar to session_dir.
• ~ and absolute paths should be supported if they are acceptable for session_dir.
• The feature should probably imply persist_session: true, or produce a clear validation error if persistence is not enabled.
• If the target file already exists, the behavior should be explicit: either resume/append to it, or fail unless a separate resume/overwrite flag is supplied. Silent overwrite should be avoided.
• The resulting session should still work as a normal Pi session JSONL and remain compatible with session_dir defaults when session_file is omitted.

Current workaround

Use persist_session: true and point session_dir at a task-specific directory, then discover the generated filename afterward. This helps but does not solve the stable lane problem, because the filename is not predictable.

Related existing feature

This builds on PR #111 (persist_session / session_dir). The request here is more specific: choose the concrete JSONL session file so humans and task automation can continue the same subagent lane later.