Agent-invokable session rescope: let the model /move the session once the task converges on a repo

[lee98www]

Problem

Sessions launched from a multi-repo root (e.g. ~/Projects with 180+ repos) pay a heavy per-turn cost: the volatile workspace-tree snapshot scans the entire root, and none of it is relevant once the conversation converges on one repo. /move solves this — but it is a user-only surface. The agent, which is usually the first to know which repo the task belongs to, cannot invoke it. The user has to notice and type /move <repo> manually every session.

Related: #4628 fixes /move so the workspace tree actually follows the move.

Proposal

An agent-invokable session rescope tool (working name: move_session), wired through the same optional-accessor pattern goal uses:

1. ToolSession.rescopeSessionCwd?: (path: string) => Promise<{ from: string; to: string }> — optional accessor, absent in contexts where relocation must not happen (subagents, read-only bash restriction profiles).
2. Wired in sdk/session.ts next to the existing accessors: validate the target is an existing directory, then run the same sequence as the text/ACP /move handler — sessionManager.flush() → sessionManager.moveTo(resolved) → setProjectDir(resolved) → session.rescopeWorkspaceTree() → plugin/capability cache reset.
3. Tool exposed to the model with a description scoped to intent: "when the session's working directory is a broad launcher root and the task has converged on one subdirectory/repo, rescope the session there."

With this, a root-launched session auto-descends: the model resolves the repo from the conversation and calls the tool; the next turn's workspace tree, bash default cwd, and relative path resolution are all repo-scoped. Root-as-launcher becomes a first-class workflow instead of a token sink.

Design questions for maintainers

• Gating: should the tool be permission-gated like bash/edit (it is no more powerful than bash, which can already operate anywhere), or behind a setting (session.agentMove: true), or allowed by default?
• Naming: move_session vs rescope vs reusing the /move name.
• Subagents: propose the accessor is simply not provided at taskDepth > 0.
• TUI: the text/ACP /move handler already runs without InteractiveModeContext; status-line refresh happens on the next render. Acceptable, or should the tool emit an event the TUI host consumes?

Happy to implement once the shape is agreed — the /move internals are already shared, so the diff is mostly the accessor, the tool definition, and tests.

[Yeachan-Heo]

This proposal changes a user-facing authority and tool surface: whether the model may relocate the live session, its permission semantics, subagent availability, and TUI/ACP lifecycle effects. That product decision needs owner confirmation before implementation.

Holding the issue at the design gate with the concrete decisions already listed in the report; no speculative mutation lane is being opened until that authority contract is chosen. PR #4628's narrower existing /move stale-tree bug remains independently reviewable and does not decide this new agent capability.

OWNER_CONFIRMATION_REQUIRED

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Yeachan-Heo]

Acknowledging the owner hold above (OWNER_CONFIRMATION_REQUIRED, 2026-08-17). This lane re-checked current state before doing anything:

• dev @ 8711c555da490ad36475f94368bcdd8d8f01048e: no move_session/rescope tool, no rescopeSessionCwd accessor, no agent-invokable relocation surface.
• PR fix(session): re-root the volatile workspace tree after /move #4628 (fix/move-rescopes-workspace-tree, MERGEABLE): narrowly fixes the stale workspace-tree bug — AgentSession.rescopeWorkspaceTree() called from both /move surfaces. It does not add any agent-invokable capability and does not decide any of the four open questions.
• No other open/closed PR is cross-referenced to this issue.

The four product decisions remain open exactly as the issue lists them. No choice among these is being made by this lane:

1. Gating — permission-gated like bash/edit; or behind a setting (session.agentMove: true); or allowed by default (rationale given: no more powerful than bash, which already operates anywhere).
2. Naming — move_session; or rescope; or reusing the /move name.
3. Subagents — proposal is the accessor is simply not provided at taskDepth > 0; confirm or amend.
4. TUI — the text/ACP /move handler already runs without InteractiveModeContext and the status line refreshes on next render; acceptable as-is, or should the tool emit an event the TUI host consumes?

Non-mutating hold: no implementation lane is opened until the owner answers. No source, branch, PR, or release surface is changed by this lane for this issue; PR #4628's existing narrower fix remains independently reviewable and untouched.

gajae.issue-hold.v1 issue:4629 dev:8711c555da490ad36475f94368bcdd8d8f01048e state:open owner-hold:2026-08-17 open-choices:4 implementation-lane:closed

Signed: GJC / Yeachan-Heo via GitHub CLI

[Yeachan-Heo]

Implementation lane opened — PR #4688

Fresh census at dev 27afb732b3d25632d44176687d5bdd78d3419bb3: no move_session/rescope surface exists on dev, no open PR cross-references this issue, and PR #4628 (open, CHANGES_REQUESTED) owns only the separate workspace-tree re-root bug — it does not add any agent-invokable capability. The proposal is therefore not covered by any live PR.

PR #4688 implements the issue's shape on the goal-tool optional-accessor pattern:

1. ToolSession.rescopeSessionCwd?: (path: string) => Promise<{ from: string; to: string }> — absent in contexts where relocation must not happen.
2. Wired in sdk/session.ts: existing-directory validation, then the exact text/ACP /move sequence (flush → moveTo → setProjectDir → capability reset → plugin-roots cache reset → SSH tool refresh). Accessor not provided at taskDepth > 0 or under any restricted bash surface (bashRestrictionProfile / bashAllowedPrefixes) — the descriptor gate hides the tool entirely there, which covers the issue's subagent and read-only-profile questions.
3. move_session tool with intent-scoped description ("when the session's working directory is a broad launcher root and the task has converged on one subdirectory/repo, rescope the session there").

Design questions resolved by the implementation: allowed by default via accessor absence (no more powerful than bash), named move_session as proposed, subagents excluded at taskDepth > 0 as proposed, TUI follows the existing /move no-InteractiveModeContext behavior. Tree re-root stays owned by #4628 and composes once it lands.

Verified: 5-case regression suite, descriptor availability/order gates, regenerated tool catalog + reproducibility, package check/lint (TS+Rust)/schemas/gates/build/smoke, and a live print-mode dogfood where a model turn at a two-repo launcher root called move_session and pwd confirmed the rescope.

This issue closes when #4688 is merged to dev.

gajae.issue-lane.v1 issue:4629 dev:27afb732b3d25632d44176687d5bdd78d3419bb3 pr:4688 head:9cffb4205c state:open owner-hold:lifted-by-fresh-owner-direction implementation-lane:open

—
[repo owner's gaebal-gajae (clawdbot) 🦞]