Migrating from v0.5 to v0.6

Migrating from v0.5 to v0.6

Executive summary

Chimera v0.6 is purely additive over v0.5. There are no breaking API changes, no removed flags, no renamed slash commands. Everything you wrote against 0.5.0 keeps working unchanged.

What’s new is breadth-and-depth filling on the seven-CLI surface that v0.5 shipped: a new apply_patch write tool, an 18+9-event hook bus, the five-mode permission standard (read-only / suggest / auto / yolo / strict), a content-addressed file-undo store, declarative permission rules, the Ctrl-X chord layer, plan mode, instruction-file ingestion (AGENTS.md), 13 algorithm skills, the swe-agent agent preset, and three new benchmarks (ProgramBench, MultiSWE-bench, three more bench adapters). All seven CLIs gained --help-long’s auto-promotion safety net, multi-step /undo, and the new permission-mode standard.

The v0.5-era deprecations remain on schedule for v0.7.0:

Symbol	Status in v0.6	Removed in
chimera cc subcommand alias	DeprecationWarning (stderr line)	v0.7.0
AgentPreset.build()	DeprecationWarning (Python warning)	v0.7.0
chimera.agents.presets.agent_styles module	DeprecationWarning via AgentPreset.build()	v0.7.0
claude_code preset key	DeprecationWarning (use coding_agent)	v0.7.0

Nothing on that list moved. The v0.5-to-v0.6 gap is one minor version, not the larger v0.5-to-v0.7 horizon.

What’s new

Tools and hooks

• apply_patch tool — diff-format file editing for agents that prefer unified-diff output over a structured Edit tool. Lives at chimera/tools/apply_patch.py. (W13 G1.)
• write_guard, notebook_edit, worktree, cron — four more high-leverage tools landed alongside apply_patch. (W13 G13.)
• 18 lifecycle hook events + 9 wave-14 events — the hook bus now surfaces 27 distinct events (PreToolUse, PostToolUse, PreCompaction, Notification, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, plus 9 fine-grained additions for wave-14 coverage). (W13 G4 + W14-7.) Wave-14 also adds an event filter to HookMatcher so a single matcher can listen on a subset rather than firing for every event in a category.

Permission system

• Five-mode permission standard — read-only, suggest, auto, yolo, strict — wired across every CLI’s --permission-mode flag on top of the legacy four-choice surface (default, acceptEdits, bypassPermissions, plan). Both sets are accepted; legacy values keep their existing semantics. (W13 G3.)
• Declarative permission rules — ~/.chimera/permissions.json loaded by every CLI. Rule shape: {tool, action, arg_key?, arg_pattern?, description?}. Manage via /permissions list|add|remove in the otter REPL. (W13 G6.)

Editor / TUI ergonomics

• Ctrl-X chord layer — a vi-style chord prefix for stoat/otter REPLs (Ctrl-X p toggles plan mode, Ctrl-X s shell mode, etc.). (W13 G7.)
• Plan mode — boot any CLI’s REPL in planner posture; the agent emits a plan rather than acting. Toggle mid-session with /plan. Plans persist to ~/.chimera/plans/ for /resume. (W13 G7 + stoat W14-3 hooks engine.)
• File-undo store — content-addressed per-turn snapshots under ~/.chimera/snapshots/<session>/ so otter’s /undo rewinds conversation and files. (W13 G5.)
• Multi-step /undo --steps N — wave-13’s snapshot store could always do multi-step; v0.6 wires the slash dispatcher to walk it. Forms accepted: /undo --steps 3 / /undo -n 3 / /undo 3. The symmetric /redo --steps N works the same way. (W14-9.)
• Bracketed paste, sessions slash, mode chords — stoat REPL UX features. (W14-3.)
• 12-slash palette — badger gained 12 new slash commands. (W14-4.)
• 5 print-mode flags — weasel’s -p print mode gained five new flags for output shape, attachment, and structured emission. (W14-5.)
• Quality layer (4 features) — shrew gained model profiles, output parser, quality monitor, and skill injector. (W14-6 + W13 G11/G12.)

Project ingestion

• Instruction-file ingestion — every CLI now ingests AGENTS.md and CLAUDE.md from project root and merges them into the system prompt. (W13 G2.)
• 13 algorithm skills — curated SKILL.md files under chimera/skills/algos/ covering common algorithm patterns. (W13 G12.)

Subagents and slash

• Subagent registry — chimera/agents/registry.py extended with a proper register/get/list/load_directory surface; swe-agent agent preset added. (W13 G8.)
• /resume slash + /diff slash — top-level /resume and /diff slash commands across all 7 CLIs. (W13 G9.)
• help-long auto-promote across all 7 CLIs — register_argument is now wired in mink, otter, ferret, weasel, shrew, stoat, badger. Future contributors who paste a verbose help= string can no longer silently bloat --help past the 50-line ceiling. (W13 E6 + W14-9.)
• cc-alias deprecation prep — clearer stderr banner naming both the rename version and the removal version. (W13 E4.)

Benchmarks and evaluation

• ProgramBench inference loop — full inference loop harness for the ProgramBench benchmark, replacing the wave-13 scaffold. (W14-8.)
• ProgramBench + MultiSWE-bench scaffolds — wave-13 scaffolds matured into runnable adapters. (W13 B1, B2.)
• 3 more benchmark scaffolds — see chimera/eval/benchmarks/. (W13 B3.)
• Provider catalog refresh — 7 model families recognised by the pricing/cost subsystem, plus PyPI release prep. (W13 E2 + E5.)

CLI-by-CLI

CLI	Wave-13	Wave-14
mink	5-mode permissions; settings keys	9 hook events + settings apply (W14-7)
otter	apply_patch, file-undo, perm rules, plan mode	(Tier-1 polish in flight)
ferret	codex flags, instruction files	Codex-style subcommands (W14-1)
weasel	JS/TS exec, RPC streaming, CodingAgent default	5 print-mode flags (W14-5)
shrew	skill injector, 13 algo skills	Quality layer: 4 features (W14-6)
stoat	chord+plan mode	Hooks engine + UX features (W14-3)
badger	(parity + provider chain refresh)	Slash palette: 12 commands (W14-4)

Breaking changes

None. The v0.5-era surface — every flag, every slash command, every public API — is preserved bit-for-bit.

Behavior changes

--legacy-react is still the escape hatch

The wave-10 default flip (bare chimera code boots CodingAgent, not the legacy ReAct loop) carries forward unchanged. Pass --legacy-react to opt back into the legacy Session REPL. (Same as v0.5.)

Auto-launches for new subsystems

Several new subsystems auto-launch by default; opt out with a flag:

• Permission rules — ~/.chimera/permissions.json is loaded if present. To disable, delete the file or pass --permission-mode bypassPermissions.
• File-undo store — otter snaps every turn to ~/.chimera/snapshots/<session>/ so /undo can rewind files. Disabled implicitly when the session has no environment (e.g. tiny test fakes). The store self-garbage-collects via the existing gc_blobs API; no periodic cron needed.
• Instruction-file ingestion — AGENTS.md / CLAUDE.md merge into the system prompt at REPL startup. Pass --no-rules (otter) or set CHIMERA_NO_INSTRUCTION_FILES=1 to skip.

None of these change behavior for prompts that don’t touch them.

Per-CLI version bumped to 0.6.0

Every animal CLI’s --version now prints chimera <name> 0.6.0. Scripts that pinned exact-string match against 0.5.0 need to bump their pin. (Test fixtures updated in this release; user scripts may need a one-line change.)

Recommended upgrade path

1. Upgrade. pip install --upgrade chimera-run (or uv pip install --upgrade chimera-run). The PyPI distribution name is chimera-run; the Python import is still import chimera.

2. chimera doctor — re-runs cleanly under v0.6 and now reports 0.6.0 for each CLI’s version row. Catches API-key drift, optional daemons, and extras.

3. Optionally adopt apply_patch. If your agent prefers unified-diff output to a structured Edit tool, register chimera.tools.apply_patch.ApplyPatchTool in your tool set.

4. Optionally tighten permissions. Drop a ~/.chimera/permissions.json to lock down Bash to a glob allowlist:

   {
     "rules": [
       {"tool": "Bash", "action": "allow", "arg_key": "command",
        "arg_pattern": "git *"},
       {"tool": "Bash", "action": "ask", "arg_key": "command",
        "arg_pattern": "rm -rf*"},
       {"tool": "Bash", "action": "deny"}
     ]
   }

5. Optionally ingest project instructions. Drop an AGENTS.md or CLAUDE.md at project root; every CLI will merge it into the system prompt.

6. Optionally explore plan mode. chimera stoat --plan-mode boots the REPL in planner posture. Ctrl-X p toggles mid-session.

No code-level migrations are required — the AgentPreset.build() → CodingAgent.from_preset(...) rewrite from v0.5 is still the only recommended migration, and it remains a DeprecationWarning until v0.7.0.

See also

• Chimera 0.6.0 release notes — the full ship list and quality bar.
• Migrating from v0.4 to v0.5 — read first if you skipped v0.5.
• Per-CLI quickstarts: mink · otter · ferret · weasel · shrew · stoat · badger.