[jefft72]

Summary

Replaces the previous assumption that plan mode must be supplied by an extension with an authoritative description of Diffex's native read-only planning workflow.
The documentation now follows the feature from CLI entry and interactive resolution through SDK hosting, accepted-plan routing, durable session replay, output-mode boundaries, extension behavior, and recovery after resume or navigation.

Reasoning

Native plan mode spans several public contracts that must agree on when mutation is prohibited, which tools remain available, how a submitted plan becomes a durable artifact, and when an accepted implementation is safe to retry.
Documenting only the interactive command would leave SDK hosts and session consumers without the persistence, routing, ownership, and failure semantics required to implement the workflow safely.

The documentation therefore emphasizes the fail-closed boundaries as well as the happy path.
Unsupported non-interactive hosts, ambiguous profile selection, malformed router output, stale continuation tokens, and extension tool overrides all have explicit behavior so integrations do not silently weaken plan-mode safeguards.

Changes

• Documents diffex --plan, /plan [on|off], pending-plan decisions, footer task context, and the interactive-only restriction across the main README and day-to-day usage guide.
• Defines the native planning tool contract as intrinsic submit_plan plus the permitted canonical subset of read, grep, find, and ls, with shell execution, file mutation, extension tools, and SDK custom tools unavailable while planning.
• Explains how caller allowlists, denylists, noTools, and active task-profile policies constrain inspection tools without removing submit_plan, and reserves canonical plan-tool identities against extension or SDK overrides.
• Expands the SDK reference with collaboration state, pending artifact and continuation accessors, plan control methods, lifecycle events, exported route helpers and types, and a complete host-side implementation example.
• Specifies accepted-plan continuation invariants, including one-shot tokens, runtime versus bare-session submission, preflight ownership, retry before the trusted initial message persists, stale-token rejection, and bypass of extension commands and input transformation.
• Documents automatic accepted-plan routing across active, related, or newly selected harnesses, including recommended-first ambiguous profile options, trusted safeguard and tool-policy metadata, explicit cancellation, pinned-profile behavior, and failure without fallback.
• Adds the collaboration_mode_change, plan, and plan_resolution JSONL session entries with append APIs, transition validation, compaction-aware replay, tree-navigation behavior, and the rule that lifecycle state entries never become LLM messages.
• Clarifies that print, JSON, and RPC hosts cannot use interactive plan resolution, and records that JSON wire output omits plan-only lifecycle events that remain available to direct AgentSession subscribers.
• Updates task-profile guidance so planning pauses automatic routing while accepted implementations route before execution and remain pending after ambiguous, low-confidence, malformed, canceled, or failed route decisions.
• Marks the historical plan-mode extension as incompatible with native plan mode, removes it from current TUI examples, and redirects users to the supported built-in workflow while retaining the example only as historical reference.

Testing

• npm run check passed against the final rebased 14-PR stack.
• Focused Vitest validation passed against the final rebased stack with 451 tests across 28 affected files.
• This PR changes documentation only and was not independently code-tested after stack reconstruction.

[jefft72]

Closing to rebuild on a clean base.

This stack does not build. Two separate defects are present, and the first masks the second:

1. A stray closing brace committed in feat: enforce native plan collaboration policy #64 stops packages/coding-agent/src/core/agent-session.ts from parsing at all.
2. From feat: activate accepted plans in routed sessions #65 onward the stack imports five modules that exist only on the task profile stack: evolved.ts, harness-descriptors.ts, profile-router.ts, profiles.ts, and runtime-telemetry.ts.

Replacement stacks:

• plan/* for native plan mode standing alone on main
• plan-harness/* for the plan and profile integration

The branch behind this PR is retained unchanged as a backup.