tools-only Research – Planning Feature Deletion Map
Date: 2026-01-26 Owner: Agent Phase: Research
Goal
Map ALL layers of the planning feature in tunacode to enable clean deletion. The feature has not been actively worked on and needs to be removed.
Findings
The planning feature is a read-only mode that restricts the agent to information gathering before allowing code modifications. It spans 4 layers:
Layer 1: TOOLS (Delete Files)
| File | Purpose |
|---|---|
src/tunacode/tools/present_plan.py |
Main tool implementation (46-97 lines of core logic) |
src/tunacode/tools/prompts/present_plan_prompt.xml |
XML prompt template for tool usage instructions |
Layer 2: UI (Delete Files)
| File | Purpose |
|---|---|
src/tunacode/ui/plan_approval.py |
Plan approval panel rendering, keyboard handling (1-3 key approval) |
Layer 3: UI (Modify - Remove References)
| File | What to Remove |
|---|---|
src/tunacode/ui/commands/__init__.py |
PlanCommand class (lines ~291-321), toggles plan mode via /plan |
src/tunacode/ui/app.py |
request_plan_approval() method (_handle_plan_approval_key() (pending_plan_approval attribute (on_key() ( |
src/tunacode/ui/repl_support.py |
PendingPlanApprovalState class (~line 112) |
src/tunacode/ui/welcome.py |
/plan command mention (~lines 54-55) |
src/tunacode/ui/widgets/status_bar.py |
set_mode() method - KEEP (shared with other modes), just verify no plan-specific logic |
Layer 4: CORE (Modify - Remove References)
| File | What to Remove |
|---|---|
src/tunacode/core/state.py |
plan_mode: bool field (plan_approval_callback field ( |
src/tunacode/core/agents/agent_components/agent_config.py |
present_plan tool creation and registration (~lines 433-435) |
Layer 5: AUTHORIZATION (Modify - Simplify)
| File | What to Remove |
|---|---|
src/tunacode/tools/authorization/rules.py |
PlanModeBlockRule class (PLAN_MODE_BLOCKED_TOOLS constant ( |
src/tunacode/tools/authorization/context.py |
plan_mode field in AuthContext (from_state() plan_mode extraction ( |
src/tunacode/tools/authorization/factory.py |
PlanModeBlockRule import and registration (~lines 6, 16) |
Layer 6: TYPES (Modify - Remove Protocols)
| File | What to Remove |
|---|---|
src/tunacode/types/__init__.py |
Exports for planning types |
src/tunacode/types/state.py |
PlanSessionProtocol (PlanApprovalProtocol ( |
src/tunacode/types/callbacks.py |
PlanApprovalCallback type alias ( |
Layer 7: CONSTANTS (Modify)
| File | What to Remove |
|---|---|
src/tunacode/constants.py |
EXIT_PLAN_MODE_SENTINEL (ToolName.PRESENT_PLAN from READ_ONLY_TOOLS ( |
Layer 8: TESTS (Delete)
| File | Test Count | Purpose |
|---|---|---|
tests/unit/core/test_present_plan.py |
7 tests | Complete test suite for present_plan tool |
Test functions to delete:
TestPresentPlanTool.test_rejects_when_not_in_plan_modeTestPresentPlanTool.test_auto_approves_without_callbackTestPresentPlanTool.test_handles_approval_callback_approveTestPresentPlanTool.test_handles_approval_callback_denyTestPresentPlanTool.test_handles_exit_sentinelTestPresentPlanTool.test_signature_preservedTestPresentPlanRegistration.test_present_plan_registered_in_agent
Layer 9: DOCUMENTATION (Update)
| File | Action |
|---|---|
docs/codebase-map/modules/types.md |
Remove PlanApprovalProtocol (PlanApprovalCallback ( |
docs/codebase-map/modules/ui-overview.md |
Remove PlanCommand (~line 133) |
docs/codebase-map/structure/02-core-directory.md |
Remove planning module mentions (~lines 33, 69) |
docs/codebase-map/structure/tree-structure.txt |
Remove planning module from tree (~line 67) |
Related Tickets (Reference Only)
| File | Mention |
|---|---|
.tickets/t-6670.md |
Mentions PlanApprovalProtocol |
.tickets/t-46de.md |
Mentions plan approval callbacks |
.tickets/t-69f0.md |
Discusses plan approval callback types |
Recommended Deletion Order
Phase 1: Delete standalone files (no dependents)
tests/unit/core/test_present_plan.py- test filesrc/tunacode/tools/prompts/present_plan_prompt.xml- prompt templatesrc/tunacode/ui/plan_approval.py- UI panel
Phase 2: Remove from agent registration
4. src/tunacode/core/agents/agent_components/agent_config.py - remove tool registration
Phase 3: Delete tool implementation
5. src/tunacode/tools/present_plan.py - tool itself
Phase 4: Remove authorization layer references
6. src/tunacode/tools/authorization/factory.py - remove rule registration
7. src/tunacode/tools/authorization/rules.py - remove PlanModeBlockRule class
8. src/tunacode/tools/authorization/context.py - remove plan_mode field
Phase 5: Remove UI command and state
9. src/tunacode/ui/commands/__init__.py - remove PlanCommand
10. src/tunacode/ui/app.py - remove approval handling
11. src/tunacode/ui/repl_support.py - remove PendingPlanApprovalState
12. src/tunacode/ui/welcome.py - remove /plan mention
Phase 6: Remove core state fields
13. src/tunacode/core/state.py - remove plan_mode and callback fields
Phase 7: Remove type definitions
14. src/tunacode/types/callbacks.py - remove PlanApprovalCallback
15. src/tunacode/types/state.py - remove plan protocols
16. src/tunacode/types/__init__.py - remove exports
Phase 8: Clean constants
17. src/tunacode/constants.py - remove EXIT_PLAN_MODE_SENTINEL, update READ_ONLY_TOOLS
Phase 9: Update documentation 18. Update all docs/codebase-map files listed above
Known Failing Test Note
The user mentioned a failing test related to "layers" that should be ignored (not touched). This is likely related to the ongoing Gate 2 (dependency direction) work mentioned in CLAUDE.md. The test_present_plan.py tests should be deleted as part of this cleanup - they test planning functionality specifically.
Key Patterns / Solutions Found
| Pattern | Description |
|---|---|
| Callback Injection | UI provides plan_approval_callback closure to session state, tool invokes without knowing UI |
| Sentinel Value | EXIT_PLAN_MODE_SENTINEL distinguishes "revise plan" from "exit entirely" |
| Priority-Based Rules | PlanModeBlockRule at priority 100 blocks writes before other rules evaluate |
| Protocol Decoupling | PlanApprovalProtocol avoids circular imports between core/tools/ui |
Knowledge Gaps
- Which specific test is "failing due to layers" that should be ignored?
- Any external integrations expecting
/plancommand?
References
src/tunacode/tools/present_plan.py- Main tool implementationsrc/tunacode/ui/plan_approval.py- UI panelsrc/tunacode/tools/authorization/rules.py- Authorization blockingtests/unit/core/test_present_plan.py- All planning tests