feat(prompts): allow embedders to override constitutional prompt text via OnceLock hooks

[h3c-hexin]

Summary

An application embedding this engine may want to ship its own constitutional preamble, locale preamble, or authority-recap block without forking the prompt constants. Today the only way to change BASE_PROMPT, LOCALE_PREAMBLE_ZH_HANS, or AUTHORITY_RECAP is to edit the bundled markdown/strings in this crate.

This adds three process-global, set-once override hooks:

• set_base_prompt_override(String)
• set_locale_preamble_zh_hans_override(String)
• set_authority_recap_override(String)

Each is backed by a OnceLock and read through a small accessor (effective_base_prompt() / effective_locale_preamble_zh_hans() / effective_authority_recap()) that falls back to the existing default constant when no override is set. Prompt assembly now calls these accessors instead of the constants directly.

Default builds are unaffected (no override set → bundled constant is used). Overrides are expected to be installed once at startup, before the engine builds any prompt; later set_* calls are no-ops (OnceLock semantics).

Testing

• cargo fmt --all -- --check
• cargo build -p codewhale-tui (compiles)
• cargo clippy --workspace --all-targets --all-features
• cargo test --workspace --all-features

Checklist

• Updated docs or comments as needed
• Added or updated tests where relevant (mechanism is opt-in; default path unchanged)
• Verified TUI behavior manually if UI changes (n/a)

Greptile Summary

This PR adds process-global OnceLock-backed prompt override hooks (base prompt, all locale preambles/closers, authority recap) so embedders can customise prompt text without forking the crate. It also introduces InstructionSource (file-path or inline string) to replace Vec<PathBuf>, adds slash-command frontmatter with an allowed-tools restriction, and moves the environment block below the volatile-content boundary to improve KV-cache reuse across sessions.

• Prompt overrides — 10 new set_* / effective_* pairs backed by OnceLock; first call wins and returns Ok(()), subsequent calls return the rejected Err(String), addressing the previously noted silent-no-op concern. All locales (zh-Hans, ja, pt-BR, vi — the last one also newly added) now have symmetric preamble and closer overrides.
• InstructionSource enum — File(PathBuf) preserves existing semantics (missing → warn + skip, oversize → truncate); Inline { name, content } lets embedders inject rendered templates without staging disk files. From<PathBuf> provided for call-site compatibility.
• Slash-command frontmatter + allowed_tools — YAML-like --- block in command files; allowed-tools field restricts which tools the model may call during that turn; parse_allowed_tools normalises entries to lowercase; gating happens in command_allows_tool inside the turn loop.

Confidence Score: 4/5

Safe to merge with minor follow-up: the changes are well-scoped and backwards-compatible, but two small hardening fixes in the tool-taxonomy assert and the allowed_tools normalisation are recommended.

The prompt-override mechanism, InstructionSource, and frontmatter parsing are solid and well-tested. Two non-blocking quality issues remain: debug_assert! in render_core_tool_taxonomy_block won't surface an empty taxonomy block in release builds, and command_allows_tool normalises only the tool-name side of the comparison, leaving an implicit lowercase contract on EngineConfig.allowed_tools that could silently mismatch when embedders set the field directly.

crates/tui/src/prompts.rs (render_core_tool_taxonomy_block assert) and crates/tui/src/core/engine/turn_loop.rs (command_allows_tool normalisation)

Important Files Changed

Filename	Overview
crates/tui/src/prompts.rs	Core file for this PR: adds 10 OnceLock-backed prompt overrides (all locale preambles/closers + base + authority), InstructionSource enum, render_core_tool_taxonomy_block, and moves the env block below the volatile boundary; debug_assert! in taxonomy builder is the main concern.
crates/tui/src/commands/user_commands.rs	Adds YAML-like frontmatter parsing with allowed-tools support; parse_allowed_tools correctly normalizes to lowercase, but command_allows_tool in turn_loop relies on that assumption without enforcing it on the EngineConfig.allowed_tools field directly.
crates/tui/src/core/engine/turn_loop.rs	Refactors tool name resolution into resolve_tool_definition, adds allowed_tools gate, adds ApprovalRequired input field, and pins prefix-cache combined hash to events; structurally sound.
crates/tui/src/core/engine/tool_catalog.rs	Adds max_results parameter to tool search (default 20, cap 100, previously hard-coded 5), exposes TOOL_SEARCH_REGEX_NAME, and extends DEFAULT_ACTIVE_NATIVE_TOOLS with new async shell tools; all changes are tested.
crates/tui/src/core/engine.rs	Generalises EngineConfig.instructions from Vec to Vec, adds allowed_tools field (None = unrestricted), and plumbs both through handle_send_message cleanly.
crates/tui/src/core/events.rs	Adds input field to ApprovalRequired and pinned_combined_hash to PrefixCacheStatus; clean event-shape additions.

_{Reviews (2): Last reviewed commit: "Merge main into prompt override hooks" | Re-trigger Greptile}

[gemini-code-assist]

Code Review

This pull request introduces startup override mechanisms for compile-time prompt constants (BASE_PROMPT, LOCALE_PREAMBLE_ZH_HANS, and AUTHORITY_RECAP) using std::sync::OnceLock, allowing embedders to customize prompts without modifying the files in-tree. Feedback suggests returning a Result from the setter functions instead of silently ignoring failures when setting the OnceLock values. Additionally, it is recommended to use isolated integration tests rather than standard unit tests to prevent global state pollution and test flakiness.

[gemini-code-assist]

Instead of silently ignoring the result of OnceLock::set, it is highly recommended to return Result<(), String>. This allows the embedder/caller to handle or log failures if they attempt to set the override multiple times or after initialization.

Suggested change

	pub fn set_base_prompt_override(s: String) {
	let _ = BASE_PROMPT_OVERRIDE.set(s);
	}
	/// Replace the Simplified-Chinese locale preamble (`## 语言要求`).
	pub fn set_locale_preamble_zh_hans_override(s: String) {
	let _ = LOCALE_PREAMBLE_ZH_HANS_OVERRIDE.set(s);
	}
	/// Replace the trailing `## Authority Recap` block.
	pub fn set_authority_recap_override(s: String) {
	let _ = AUTHORITY_RECAP_OVERRIDE.set(s);
	}
	pub fn set_base_prompt_override(s: String) -> Result<(), String> {
	BASE_PROMPT_OVERRIDE.set(s)
	}
	/// Replace the Simplified-Chinese locale preamble (## 语言要求).
	pub fn set_locale_preamble_zh_hans_override(s: String) -> Result<(), String> {
	LOCALE_PREAMBLE_ZH_HANS_OVERRIDE.set(s)
	}
	/// Replace the trailing ## Authority Recap block.
	pub fn set_authority_recap_override(s: String) -> Result<(), String> {
	AUTHORITY_RECAP_OVERRIDE.set(s)
	}

[gemini-code-assist]

Since OnceLock is process-global, calling these setters in standard unit tests will pollute the global state and cause other tests in the same test runner process to fail or behave flakily. To safely test these overrides, we should add integration tests in a separate test target (e.g., under tests/prompt_overrides.rs), which runs in its own isolated process.

[Hmbown]

love this!! the plan is to make this a "harness creator" in that you'll be able to go thru steps and make your own constitution / preamble / base prompt for your codewhale + individual projects. this is a great start . thank you!

[Hmbown]

Thanks for the prompt override hook work. I am leaving this open because the branch is currently conflict-blocked, and the override API needs a little more test coverage before it is safe to carry into the prompt layer.

The specific things I would tighten: surface/handle OnceLock::set failures instead of silently dropping them, make the zh-Hans preamble/closer override behavior symmetric, and add focused tests for the global override path. After a rebase, the useful verification target is cargo test -p codewhale-tui prompts --all-features plus full CI.

[Hmbown]

Pushed a maintainer update to get this branch current with main and address the review nits while keeping your original embedder-hook direction intact.

What changed:

• resolved the prompt-layer conflict with current main while preserving the new core tool taxonomy block
• routed base prompt composition through the override accessor
• made duplicate override registration observable by returning Result<(), String> instead of silently dropping the second value
• made locale preamble/closer overrides symmetric across the supported locale bookends
• added a focused regression for duplicate-set behavior without mutating the process-global prompt cells

Local verification on the updated head:

• cargo fmt --all -- --check
• python3 scripts/check-provider-registry.py
• cargo test -p codewhale-tui prompt_override_storage_reports_duplicate_sets -- --nocapture
• cargo test -p codewhale-tui prompts::tests:: -- --nocapture
• cargo check -p codewhale-tui --all-features --locked

Thanks again @h3c-hexin — this is a nice foundation for the future harness/constitution customization path.

[Hmbown]

One more stewardship note before merge: the only red CI leg is Windows, and I checked the failed job logs. The failures are the existing background shell process-handle tests (�[0mexpected completed vs still running�[0m) rather than anything in this prompt-only change set. Ubuntu/macOS/lint/npm smoke/Greptile/GitGuardian are green, and the focused prompt tests plus tui check pass locally, so I’m treating this as mergeable rather than sending more busywork back to you. Thanks again @h3c-hexin.