feat(familiars): add access tier so build-tier familiars can use git/shell

[BunsDev]

Summary

Adds an access field to CovenFamiliar (~/.coven/familiars.toml) and wires Coven familiars into the existing --agent / agent-mode pipeline so each familiar's declared access tier (full / read-only / search-only) controls which tools they can invoke once activated.

• Default is read-only — write/exec power is opt-in per familiar (access = "full").
• Build-tier familiars (nova, cody, kitty in the canonical roster) are expected to opt into "full" so they can git, edit files, and run shell.
• Research / strategy / memory familiars (sage, astra, echo, charm) stay on the default "read-only" tier and only get read/search tools.

What changed

crates/core/src/coven_shared.rs

• New DEFAULT_FAMILIAR_ACCESS = "read-only" constant.
• CovenFamiliar gains access: Option<String> with a resolved_access() helper that falls back to the default.
• New familiar_to_agent_definition() — converts a familiar to config::AgentDefinition, threading access into the field the existing tool-filter pipeline already consults.
• New default_agents_with_familiars() — merges built-in agents (build/plan/explore) with familiars (built-ins win on id collision). Callers extend this with config.agents afterwards so user definitions still win.

crates/cli/src/main.rs

• Both agent-merge sites (--agent headless flow, interactive agent-mode switch) now use default_agents_with_familiars(). Merge order: built-ins → familiars → settings.json agents.

crates/tui/src/agents_view.rs + crates/tui/src/app.rs

• confirm_selection() now returns Option<(id, display)> when the user picks a Coven familiar from the picker (List or Detail route).
• App handler activates the returned familiar via agent_mode + agent_mode_changed = true and closes the menu. User-defined agents continue to open the editor as before.

docs/familiars.md

• Documents the new access field, the recommended tier per role, and how access interacts with settings.json overrides.

~/.coven/familiars.toml (user-side, not in this repo)

• access = "full" added to nova, cody, kitty. Other familiars omit access and inherit the read-only default.

Test plan

• cargo build --workspace --manifest-path src-rust/Cargo.toml — clean.
• New unit tests in coven_shared (5) — defaults, explicit tiers, agent-definition propagation, merge collision behaviour.
• New unit tests in agents_view (4) — familiar_id_from_source parsing + confirm_selection return paths.
• All pre-existing tests still pass (verified the failing tests on this branch — codex_adapter::test_anthropic_to_openai_request_basic, keybindings::test_default_bindings_contains_ctrl_c, keybindings::test_resolver_simple_action, app::test_ctrl_a_shortcut_opens_model_picker, and 4 other TUI snapshot tests — are identical to origin/main and unrelated to this branch).
• Clippy diff vs main: no new errors introduced (49 pre-existing errors on both).
• Manual edit of ~/.coven/familiars.toml verified to parse via the new unit test fixtures.

Notes for review

• The repo has substantial pre-existing cargo fmt --check drift (~2687 diffs on main). This PR adds no new fmt drift; all my changes are fmt-clean (verified by comparing the diff list to main).
• The TUI's confirm-selection signature changed from () to Option<(String, String)> — only one external caller (app.rs's handle_agents_menu_key), updated in this PR.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.