Summary
Two improvements to the plan toolset to reduce LLM cost and increase flexibility.
1. File-based plan revisions
Iterating on a plan is expensive today because every revision requires the LLM to output the full plan content as input. This creates unnecessary token overhead on each edit cycle.
Proposed additions:
- A
update_plan_from_file tool (or equivalent option on the existing update tool) that accepts a file path instead of inline content. The agent can write targeted edits to a temporary file and reference that path, avoiding the need to regurgitate the entire plan body each time.
- A complementary
export_plan_to_file tool that writes the current plan content to a file without returning the full content as tool-output tokens. This lets an agent cheaply materialise the plan on disk before making edits, without paying input-token cost for the read.
Together these two operations create a low-cost edit loop:
export_plan_to_file → write current plan to a temp path- Edit the file in-place (targeted patch / rewrite)
update_plan_from_file → commit the new version
2. Free-form status field
Plans currently have no lifecycle signal. A status field should be added so agents and users can track where a plan stands.
Requirements:
- The field is free-form string — no fixed enum — so users can define their own vocabulary in their system prompt (e.g.
idle, in-progress, blocked, done, canceled, or anything domain-specific).
- Status should be readable and writable independently of the plan body (a lightweight
set_plan_status / get_plan_status operation, or a dedicated field on the existing create/update tools).
- The TUI / display layer should surface the status alongside the plan title.
3. Versioning and optimistic locking
When multiple sessions collaborate on the same plan, concurrent updates can silently overwrite each other's edits.
Proposed addition:
- Each plan carries an auto-incremented version number that is bumped on every write.
- The
update_plan (and related write tools) accept an optional last_known_version parameter. If the plan's current version does not match last_known_version at write time, the operation is rejected with a conflict error — the caller must re-read the plan and retry.
- Read operations (
get_plan, export_plan_to_file, etc.) return the current version number so callers can capture it before attempting a write.
This gives agents working in parallel a safe, low-overhead mechanism to detect and handle concurrent modifications without requiring explicit locking or coordination.
Summary
Two improvements to the plan toolset to reduce LLM cost and increase flexibility.
1. File-based plan revisions
Iterating on a plan is expensive today because every revision requires the LLM to output the full plan content as input. This creates unnecessary token overhead on each edit cycle.
Proposed additions:
update_plan_from_filetool (or equivalent option on the existing update tool) that accepts a file path instead of inline content. The agent can write targeted edits to a temporary file and reference that path, avoiding the need to regurgitate the entire plan body each time.export_plan_to_filetool that writes the current plan content to a file without returning the full content as tool-output tokens. This lets an agent cheaply materialise the plan on disk before making edits, without paying input-token cost for the read.Together these two operations create a low-cost edit loop:
export_plan_to_file→ write current plan to a temp pathupdate_plan_from_file→ commit the new version2. Free-form status field
Plans currently have no lifecycle signal. A
statusfield should be added so agents and users can track where a plan stands.Requirements:
idle,in-progress,blocked,done,canceled, or anything domain-specific).set_plan_status/get_plan_statusoperation, or a dedicated field on the existing create/update tools).3. Versioning and optimistic locking
When multiple sessions collaborate on the same plan, concurrent updates can silently overwrite each other's edits.
Proposed addition:
update_plan(and related write tools) accept an optionallast_known_versionparameter. If the plan's current version does not matchlast_known_versionat write time, the operation is rejected with a conflict error — the caller must re-read the plan and retry.get_plan,export_plan_to_file, etc.) return the current version number so callers can capture it before attempting a write.This gives agents working in parallel a safe, low-overhead mechanism to detect and handle concurrent modifications without requiring explicit locking or coordination.