Skip to content

revert(session_plan): remove the per-session plan toolset - #4195

Closed
trungutt wants to merge 2 commits into
docker:mainfrom
trungutt:remove-session-plan-toolset
Closed

trungutt wants to merge 2 commits into
docker:mainfrom
trungutt:remove-session-plan-toolset

Conversation

@trungutt

@trungutt trungutt commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Why

The session_plan toolset was added to power a host-driven "draft, review, execute" workflow: one agent writes a per-session plan, calls exit_plan_mode to mark it ready, and the host routes the next turn to an executing agent. That workflow never materialised in any known consumer. The toolset ships in every runtime with no active user, and its cross-cutting shape (a whole new event type, a runtime-owned handler set alongside handoff/transfer_task, a session_plans/ directory under the data dir, a first-class docs page) makes it non-trivial dead weight.

Retiring it keeps the built-in toolset surface single-purpose: shared, named plans agents collaborate on across sessions go through the plan toolset — there is no per-session variant.

What this PR removes

A clean inverse of #3305:

  • The sessionplan package (pkg/tools/builtin/sessionplan/)
  • The runtime handlers (pkg/runtime/sessionplan_handlers.go) and the three toolMap entries in pkg/runtime/loop.go
  • runtime.SessionPlanUpdatedEvent and its session_plan_updated client-side registry entry
  • The session_plan creator in pkg/teamloader/toolsets/toolsets.go and the passive catalog entry in pkg/teamloader/toolsets/catalog.go
  • The two session_plan schema enum entries in agent-schema.json
  • examples/session_plan.yaml and docs/tools/session_plan/index.md

What this PR does NOT touch (deliberate)

pkg/plans (the host-facing plan service) and its consumers (cmd/root/plans, pkg/tui/plans*) were built on top of the session-plan toolset and reference the removed types. They will not compile against main after this lands. Same for a handful of cross-references from the session_context toolset and the CLI/TUI docs pages.

Those all sit in a different design surface (unified host-side plan management, with session plans as one of two scopes) whose future shape is not this PR to decide. Options for the follow-up:

  1. Collapse the surface to shared-plans-only (drop Scope, SessionRef, UpdateSession, WithSessionDir, the SessionID fields on Plan/Ref/ListOptions, the UnsupportedError type) — this PR's minimum-viable land-together companion.
  2. Keep the two-scope surface and re-back session plans against a different store (e.g. session-tagged shared plans).
  3. Something else.

I'll open the (1) companion PR in a follow-up if that is the direction; happy to sequence differently.

Compatibility

Any external agent config that references type: session_plan will fail to load with "unknown toolset type" after this lands. Given no known consumer, I've treated it as a straight removal rather than adding a deprecation cycle — happy to invert if a deprecation window is preferred.

Users who ran the toolset have ~/.cagent/session_plans/*.md files on disk. Nothing under the runtime enumerates them any longer; they can be removed with rm -rf ~/.cagent/session_plans to reclaim the space.

Test status

go build and go test pass in every package this PR modifies (pkg/runtime/..., pkg/teamloader/toolsets/...). go build ./... fails only at pkg/plans/service.go — the coordination boundary described above.

The session_plan toolset was designed for a host-driven draft/review/execute
workflow that never materialised in any known consumer. Removing it keeps
the built-in toolset surface single-purpose: shared, named plans go through
the plan toolset; there is no per-session variant.

Reverts the toolset package, the runtime handlers and event, the registry
and catalog entries, the schema enum entries, the example config, and the
docs page.

Downstream packages that were built to unify shared and session plans
(pkg/plans, its CLI/TUI consumers, and cross-references in the session_context
docs) still reference the removed toolset and will need a follow-up cleanup
from their maintainer to either drop the session scope or re-back it against
a different store.
@aheritier aheritier added "status/needs-triage" area/core Core agent runtime, session management area/docs Documentation changes area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection area/tools For features/issues/fixes related to the usage of built-in and MCP tools status/needs-triage For issues that need to be triaged and removed "status/needs-triage" labels Sep 8, 2026
Follows the toolset removal in the previous commit: the concepts and
configuration overviews, the /plans TUI browser docs, the plan-toolset
doc, the CLI data-dir reference, and the nav all still pointed at
docs/tools/session_plan/index.md and its `~/.cagent/session_plans/`
storage directory. Prune every dead reference so the docs site builds
again.
@trungutt

trungutt commented Sep 8, 2026

Copy link
Copy Markdown
Contributor Author

Abandoning this direction.

@trungutt trungutt closed this Sep 8, 2026
@trungutt
trungutt deleted the remove-session-plan-toolset branch September 8, 2026 07:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/core Core agent runtime, session management area/docs Documentation changes area/runtime Runtime engine, agent loop execution, tool dispatch, loop detection area/tools For features/issues/fixes related to the usage of built-in and MCP tools status/needs-triage For issues that need to be triaged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants