sessions: add explicit worktree option to create_session

[Sandeep Somavarapu (sandy081)]

Summary

• Add an optional worktree override to create_session, with guidance to supply true or false only when explicitly requested by the user.
• Preserve existing isolation inheritance when omitted and reject the option with relationship: currentSession.
• When worktree: false, resolve a known worktree folder to its project root instead of sharing the existing worktree.
• Cover explicit overrides, invalid combinations, inheritance, and local/remote workspace resolution in regression tests; update architecture documentation.

Validation

• npm run compile passed.
• Hygiene passed for all changed files (including the pre-commit hook).
• 90 focused session tool and tool-group tests passed; the final description-only change also passed both targeted schema/guidance tests.

[Copilot]

Copilot review overview

🟡 Changes recommended

Workspace resolution can incorrectly rewrite ordinary nested or additional roots to the primary project.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review tier: Balanced
Findings: 1

New issues introduced by this change (1)

Severity	Finding
	src/​vs/​platform/​agentHost/​node/​shared/​sessionServerTools.ts — preferProject currently rewrites every matching working directory to the session's project URI,…

What changed in this PR

Adds an explicit worktree override to create_session, including validation, workspace resolution, tests, and documentation.

Changes:

• Adds and validates the optional worktree argument.
• Updates workspace and isolation resolution.
• Expands regression coverage and documentation.

File	Review
src/​vs/​platform/​agentHost/​node/​shared/​sessionServerTools.ts	Requires correction: preferProject can incorrectly replace nested or additional workspace roots.
src/​vs/​platform/​agentHost/​test/​node/​sessionServerTools.test.ts	Adds coverage for validation, inheritance, overrides, and URI resolution.
src/​vs/​platform/​agentHost/​AGENTS.md	Documents isolation behavior; should clarify that inheritance applies within the same project.

Suppressed comments (2)

src/vs/platform/agentHost/AGENTS.md:266

• This sentence says every independent session inherits isolation, while the implementation and tool schema restrict inheritance to the same project. State that condition here so the architecture contract does not misdescribe different-project sessions.

An independent session inherits the creating session's host-owned isolation
selection independently of provider-owned configuration;
otherwise it uses worktree isolation. The optional `worktree` argument overrides

src/vs/platform/agentHost/node/shared/sessionServerTools.ts:836

• When worktree is omitted, this only recognizes the same project if args.workspace equals the project root. Existing linked-worktree sessions are represented with project set to the primary root and workingDirectories set to the checkout (for example, agentService.test.ts:6085-6099), so passing that known working directory falls through to the default worktree isolation instead of inheriting the source's folder isolation. Resolve the known project identity for this comparison without rewriting the requested working directory, and add the corresponding folder-isolation regression case.

	} else if (defaults?.project !== undefined && isEqual(defaults.project, args.workspace)) {
		isolation = defaults.isolation;

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Base: e341a3c1 Current: 6255201d

No screenshot changes.

[Momin Ahmad (MominRaza)]

Closes #334727