title: Plan Mode tags: [plan, mode, readonly, approval] library: cowboy status: future

Plan Mode

Plan Mode is a proposed read-only sub-agent configuration that enables deliberate exploration before committing to actions. Not yet implemented in cowboy.

Concept

A constrained execution mode where the agent:

Cannot modify state: all write operations disabled
Produces artifacts: conscious.md (thinking log) and response.md (structured plan)
Requires approval: plans must be explicitly approved before transitioning to execution
Links to memory: integrates with zk zettelkasten via wikilinks

Relationship to Existing Sub-Agent System

Cowboy already implements sub-agents via the spawn_subagent tool in nix/tools.nix with three types:

Type	Access	Current Implementation
`research`	read-only + web	Implemented
`code`	read + write	Implemented
`review`	read + tests	Implemented

Plan Mode would be a fourth sub-agent type with approval gates, or a mode flag that restricts the main agent to research-level tools before unlocking full access.

Tool Restrictions

Allowed (Read-Only)

Tool	Purpose
`read`	View file contents
`search`	Search within files
`find`	Find files by name
`ls`	List directory contents
`web-search`	Query web via Exa AI

Blocked

Tool	Reason
`write`	Modifies filesystem
`bash`	Arbitrary mutations
`home-switch`	System changes
`spawn_subagent` (code type)	Write access

Output Artifacts

conscious.md

Stream of consciousness during planning. Preserved as memory for future sessions.

response.md

Structured, actionable plan:

# Plan: <title>

## Summary
Brief description.

## Steps
1. **Action** - Description
2. **Action** - Description

## Files Affected
- path/to/file.nix

## Risks
- Breaking change to X

Approval Workflow

User Request -> Plan Mode (read-only) -> conscious.md + response.md
  -> Review -> Approved -> Execution Mode (full tools)
           -> Rejected -> Iterate in Plan Mode
           -> Partial  -> Approve subset of steps

Integration with cowboy

Where it fits in the two-library split

Plan Mode is a cowboy feature (platform concern, not bridge-specific):

Mode flag in the harness WASM plugin state
Tool restriction enforcement in tools.rs
Approval state machine in handlers.rs
Nix configuration in services.agent.planMode

Proposed Nix options

services.agent.planMode = {
  requireForDestructive = true;   # always plan before home-switch, write to system files
  autoApproveThreshold = 3;       # auto-approve plans with <= N steps
  timeoutSeconds = 300;
};

Configurable agent name

Plan mode artifacts would live at ${cfg.homeDirectory}/plans/ with the agent name in metadata.

Prerequisites

Before implementing Plan Mode:

zk memory system -- for wikilink integration and plan persistence
Context manager -- for session state tracking across mode transitions
Tool restriction enforcement in Rust -- currently tools are defined in Nix but restrictions aren't enforced per-mode in the harness

Why Future (Not Implemented)

The sub-agent system already provides a research (read-only) mode. Plan Mode adds:

Formal approval workflow with states (pending/approved/rejected/partial)
CLI commands (agent plan show, agent plan approve)
Automatic plan generation with structured output format
Mode transition tracking

These require harness-level Rust changes that haven't been started.