feat(phase3-step8): Plan + Permission Contract

[AVADSA25]

Summary

Phase 3 Step 8 — Plan + Permission Contract. Drop-a-project planning layer.

User describes a project → Qwen-3.6 drafts structured plan with permission manifest → user approves in PWA → grants persisted to ~/.codec/agents/<id>/grants.json with plan_hash for Step 9 tamper detection.

No execution yet — Step 9 picks that up. Step 8 alone is shippable: drafted plans sit in awaiting_approval, approved plans sit in approved waiting for the runner.

Reference

• Blueprint: docs/PHASE3-BLUEPRINT.md §2 (approved 2026-05-03)
• TDD plan: docs/PHASE3-STEP8-PLAN.md (19 tasks, 89 atomic steps)
• Resolved Q&A (blueprint §8): Q1 Qwen-3.6 only, Q2 inline edit, Q3 clarifying loop, Q4 global allowlist tier, Q13 plan-hash tamper detection

What ships

Component	Lines	Tests
codec_agent_plan.py (NEW)	~640	—
routes/agents.py (extended)	+250	—
tests/test_agent_plan.py (NEW)	~700	31 tests
codec_audit.py (modified)	+18	constants + frozenset
codec_dashboard.py (modified)	router mount	—
AGENTS.md (modified)	+57	docs

Audit envelope

6 new schema:1 events, all paired correlation_ids per Step 1 §1.4 contract:

• agent_plan_drafted (info) — agent_id, checkpoint_count, estimated_duration_minutes, skills_count, domains_count
• agent_plan_approved (info) — agent_id, plan_hash (sha256), checkpoint_count, skills_count, domains_count
• agent_plan_rejected (warning) — agent_id, reason
• agent_plan_revised (info) — agent_id, checkpoint_count
• agent_global_grant_added (info) — kind, value
• agent_global_grant_removed (info) — kind, value

PHASE3_STEP8_EVENTS frozenset exposed.

Permission model (Q4 — plan-and-grant + global allowlist)

Per-agent grants (extracted from plan): valid for that agent's lifetime, written to ~/.codec/agents/<id>/grants.json at approval. Plan-hash (sha256) computed at approval; Step 9 will verify on every daemon tick (Q13 tamper detection).

Global allowlist (~/.codec/agent_global_grants.json): cross-agent permissions. Items already in global → marked auto_approved in per-agent grants. User manages via /api/agent_global_grants GET/POST/DELETE. 4 grant kinds: network_domains, read_paths, write_paths, skills.

Vague-description handling (Q3)

Up to 3 rounds of codec_ask_user.ask clarifying questions before drafting. After 3 rounds without convergence: status=plan_failed, reason=description_too_vague. Tunable via MAX_CLARIFYING_ROUNDS constant (default 3).

State machine

draft_pending → awaiting_approval → approved | rejected | revised
                                       ↓
                                  awaiting_approval (if revised)

plan_failed (terminal-with-retry from draft_pending)

Step 9 will extend with: approved → running → checkpoint_completed / blocked_* / aborted / completed.

Kill switches

• AGENT_PLANNING_ENABLED=false — drafting disabled (existing plans untouched)
• Plan validation hard-rejects unknown skills (no silent degradation)

Test plan

• 🧪 tests/test_agent_plan.py → 31 passed
• 🧪 Full suite — 870 passed / 20 failed / 73 skipped (same 20/73 baseline as main, +27 new tests)
• AST extraction validates skill names against codec_skill_registry
• All Phase 3 Step 8 audit events emit with paired correlation_ids
• Post-merge: pm2 restart codec-dashboard (no skill install needed; module is in repo root)
• PWA test: POST /api/agents with a project description, verify drafted plan appears, POST /api/agents/{id}/approve, verify grants.json + plan_hash written

Out of scope (Step 9 + 10)

• codec_agent_runner.py daemon (Step 9)
• Plan execution loop + permission gate enforcement (Step 9)
• Resume after PM2 restart (Step 9)
• Strict-consent gate integration for destructive ops (Step 9)
• Project mode UI / mode dropdown / status pills (Step 10)
• Proactive messaging from agent to user (Step 10)
• Auto-escalation from chat mode (Step 10)

Implementation note

Plan + Implementation Plan documents (docs/PHASE3-BLUEPRINT.md + docs/PHASE3-STEP8-PLAN.md) approved by user 2026-05-03 via the superpowers:brainstorming + superpowers:writing-plans skill flow. Implementation followed TDD strictly: every commit has a failing test → implementation → passing test cycle.

🤖 Generated with Claude Code