Honor each agent's home relocation variable when resolving session dirs

[gtrrz-victor]

entire session resume restored transcripts to ~/.claude/projects/... even when CLAUDE_CONFIG_DIR had relocated Claude Code's config directory, so Claude could not find the restored session (#2367). Every restore, attach fallback and transcript-owner lookup derives its directory from the agent's GetSessionDir, so the fix lives in the agent packages.

agent.ResolveHome is now the one place that reads an agent's relocation variable, and every agent's session-dir methods go through it.

Agent	Variable	Replaces
Claude Code	CLAUDE_CONFIG_DIR	~/.claude (documented)
Gemini CLI	GEMINI_CLI_HOME	~, .gemini still appended (documented)
Factory Droid	FACTORY_HOME_OVERRIDE	~, .factory still appended (undocumented, read from the shipped binary)
Codex, Copilot CLI, pi	CODEX_HOME, COPILOT_HOME, PI_CODING_AGENT_DIR	already honored, now through the same resolver

Cursor gets no change: its CLI advertises a CURSOR_DATA_DIR transcripts folder, but the native writer stays under ~/.cursor (verified locally). A comment on its GetSessionDir records this so the bundle is not misread again.

Decisions worth a look

• A relative value is refused, via userdirs.RequireAbsoluteOverride, rather than resolved against a cwd that differs between a hook and session resume. This now applies to Codex, Copilot and pi as well.
• A blank value counts as unset; a non-blank value is used exactly as set, which is what the agents do.

Tests. An integration test reproduces the issue's flow and was red before the fix. Per agent, a resolver table test and one honors-test per session-dir method. A grep guard fails if any agent reads a relocation variable outside ResolveHome. Test harnesses scrub agent.RelocationEnvVars(). Not run: real-agent E2E.

One commit per agent, then one per review finding; the commit messages carry the detail.

Fixes #2367

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Four unresolved moderate test-isolation findings affect Gemini, Claude resume, and Factory Droid integration tests.

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

Pull request overview

This PR makes session restoration and agent path discovery honor relocated directories for Claude, Gemini CLI, Cursor, and Factory Droid.

Changes:

• Adds relocation-aware path resolvers.
• Updates Claude settings and skill discovery.
• Adds documentation and unit/integration test coverage.

File summaries

File	Summary
docs/architecture/review-command.md	Documents relocated Claude skill paths.
docs/architecture/agent-guide.md	Documents agent relocation variables.
cmd/entire/cli/integration_test/setup_test.go	Updates integration environment isolation. Open: scrub FACTORY_HOME_OVERRIDE.
cmd/entire/cli/integration_test/resume_test.go	Tests Claude resume with relocation. Open: isolate child HOME and USERPROFILE.
cmd/entire/cli/global_test.go	Clears relocation variables for CLI tests.
cmd/entire/cli/agent/geminicli/gemini.go	Adds GEMINI_CLI_HOME resolution. Open: clear it in the default-path test.
cmd/entire/cli/agent/geminicli/gemini_test.go	Tests Gemini path resolution. Open: clear GEMINI_CLI_HOME in the default-path test.
cmd/entire/cli/agent/factoryaidroid/factoryaidroid.go	Adds Factory Droid home resolution.
cmd/entire/cli/agent/factoryaidroid/factoryaidroid_test.go	Tests Droid path resolution.
cmd/entire/cli/agent/cursor/cursor.go	Adds Cursor data-directory resolution.
cmd/entire/cli/agent/cursor/cursor_test.go	Tests Cursor path resolution.
cmd/entire/cli/agent/claudecode/generate.go	Uses Claude config resolution for settings.
cmd/entire/cli/agent/claudecode/discovery.go	Discovers skills under relocated config.
cmd/entire/cli/agent/claudecode/discovery_test.go	Tests relocated skill discovery.
cmd/entire/cli/agent/claudecode/claude.go	Adds Claude config resolution for sessions.
cmd/entire/cli/agent/claudecode/claude_test.go	Tests Claude session path resolution.

Review details

Suppressed comments (2)

cmd/entire/cli/agent/geminicli/gemini.go:126

• This resolver now consumes GEMINI_CLI_HOME, but the existing TestGetSessionDir_DefaultPath only clears ENTIRE_TEST_GEMINI_PROJECT_DIR. A developer shell with a relative override will now make that test fail, while an absolute override makes it exercise the relocated path instead of the default. Please clear GEMINI_CLI_HOME in that default-path test (or in package test setup) so the default behavior remains hermetic.

	if dir := os.Getenv(geminiHomeEnvVar); dir != "" {
		if err := userdirs.RequireAbsoluteOverride(geminiHomeEnvVar, dir); err != nil {
			return "", err //nolint:wrapcheck // the error already names the override and its value
		}
		return dir, nil

cmd/entire/cli/integration_test/resume_test.go:1187

• Because this test deliberately clears ENTIRE_TEST_CLAUDE_PROJECT_DIR, the subprocess falls back to its home directory. cmd.Env inherits the developer's real HOME, so if the resolver regresses or otherwise ignores CLAUDE_CONFIG_DIR, this test writes the restored transcript into the developer's ~/.claude and leaves it behind. Give the child a temporary HOME (and USERPROFILE on Windows) before exercising the fallback so the regression test remains hermetic.

	cmd.Env = append(testutil.GitIsolatedEnv(),
		"ENTIRE_TEST_CLAUDE_PROJECT_DIR=", // empty so the real resolution runs
		"CLAUDE_CONFIG_DIR="+configDir,
	)

• Files reviewed: 16/16 changed files
• Comments generated: 2
• Review effort level: Lite

---

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

[gtrrz-victor]

Copilot's summary listed two more items as suppressed comments without threads, both addressed:

• integration_test/resume_test.go: the CLAUDE_CONFIG_DIR resume test now gives the child a throwaway HOME and USERPROFILE and asserts nothing lands under it, so a resolver regression cannot write into the developer's real ~/.claude. Fixed in 3b3c62f.
• geminicli/gemini.go: duplicate of the Gemini default-path thread, fixed in fbe1e0f.