feat(prompts): align repository tool contracts (#50)

Inject a shared repository-tool contract into every built-in agent prompt, document canonical context-tool parameters and continuation behavior, and keep the guidance synchronized with registered schemas through regression tests.

Author: ZhiXiao-Lin

CHANGELOG.md

@@ -12,6 +12,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added an opt-in real-LLM integration suite for batch-read continuation,
   every grep output mode, guarded edit previews and writes, and stable glob
   pagination.
+- Added a shared repository-tool contract to every built-in agent prompt with
+  canonical `read`, `grep`, `glob`, and `edit` arguments, pagination rules, and
+  guarded mechanical-edit guidance.
 
 ### Fixed
 

core/prompts/common/repository_tool_contract.md

@@ -0,0 +1,31 @@
+## Repository Tool Contract
+
+The registered tool schema is authoritative for availability, types, and limits.
+Use its canonical argument names exactly; do not invent aliases, cursors, or
+continuations.
+
+- `read`: use `file_path` with optional 0-based `offset` and `limit` for one
+  file. When several known text files are relevant, prefer one call with
+  `files=[{path, offset?, limit?}]` and optional `max_output_bytes`; never send
+  `file_path` and `files` together. If `metadata.batch.continuation` is non-empty,
+  copy that exact array into the next call's `files` and stop when it is empty.
+- `grep`: pass `pattern` and, when useful, `path`, `glob`, `context`, and `-i`.
+  Choose the smallest useful `output_mode`: `content` for matching evidence,
+  `files_with_matches` for paths, `count` for matching-line counts per file, or
+  `summary` for totals only. Only `files_with_matches` and `count` accept
+  pagination `limit`/`cursor`; copy `metadata.page.next_cursor` exactly and stop
+  when it is absent.
+- `glob`: pass `pattern` and optional `path`, `limit`, `cursor`, and `sort`.
+  Keep the default `sort: "backend"` when backend relevance or recency matters;
+  use `sort: "path"` for deterministic lexical pagination. Copy
+  `metadata.page.next_cursor` exactly and stop when it is absent.
+- `edit`: pass `file_path`, `old_string`, and `new_string`; set `replace_all`
+  only when every occurrence should change. For `replace_all` or any mechanical
+  change whose scope is uncertain, first use `dry_run`, inspect the diff and
+  replacement count, then apply with that count as `expected_replacements` and
+  an appropriate `max_replacements`. On a count mismatch or version conflict,
+  re-read and re-preview instead of weakening the guards.
+
+Use dedicated repository tools instead of shell commands for reading, searching,
+and editing. Use `bash` for builds, tests, and commands that genuinely require a
+shell.

core/src/prompts.rs

@@ -35,6 +35,13 @@ pub const CONTINUATION: &str = include_str!("../prompts/common/continuation.md")
 /// agent styles and delegated subagents (which build through the same path).
 pub const BOUNDARIES: &str = include_str!("../prompts/common/boundaries.md");
 
+/// Canonical repository-tool arguments and context-efficient usage strategy.
+///
+/// Appended to every assembled system prompt so general, planning, exploration,
+/// review, and verification styles share one tool contract.
+pub const REPOSITORY_TOOL_CONTRACT: &str =
+    include_str!("../prompts/common/repository_tool_contract.md");
+
 // ============================================================================
 // Delegated Run Prompts
 // ============================================================================
@@ -446,7 +453,8 @@ impl SystemPromptSlots {
     /// Build the final system prompt by assembling slots around the core prompt.
     ///
     /// The core agentic behavior (Core Behaviour, Tool Usage Strategy, Completion
-    /// Criteria) is always preserved. Users can only customize the edges.
+    /// Criteria), shared repository-tool contract, and safety boundaries are always
+    /// preserved. Users can only customize the edges.
     ///
     /// Note: This uses `AgentStyle::GeneralPurpose` as the base. Use
     /// `build_with_message()` to enable automatic intent-based style detection.
@@ -504,7 +512,16 @@ impl SystemPromptSlots {
 
         parts.push(core);
 
-        // 2b. Safety boundaries — single source of truth, appended uniformly so
+        // 2b. Repository-tool contract — shared by every style so parameter and
+        // pagination guidance cannot drift between built-in agents.
+        parts.push(
+            REPOSITORY_TOOL_CONTRACT
+                .replace('\r', "")
+                .trim_end()
+                .to_string(),
+        );
+
+        // 2c. Safety boundaries — single source of truth, appended uniformly so
         // every style and delegated subagent (which build through this path)
         // carries injection-hygiene, secret-handling, and malware-refusal rules.
         parts.push(BOUNDARIES.replace('\r', "").trim_end().to_string());

core/src/prompts/tests.rs

@@ -6,6 +6,7 @@ fn test_all_prompts_loaded() {
     assert!(!SYSTEM_DEFAULT.is_empty());
     assert!(!CONTINUATION.is_empty());
     assert!(!BOUNDARIES.is_empty());
+    assert!(!REPOSITORY_TOOL_CONTRACT.is_empty());
     assert!(!AGENT_EXPLORE.is_empty());
     assert!(!AGENT_PLAN.is_empty());
     assert!(!AGENT_CODE_REVIEW.is_empty());
@@ -100,6 +101,65 @@ fn test_boundaries_not_duplicated_in_general_purpose() {
     assert_eq!(built.matches("## Boundaries").count(), 1);
 }
 
+#[test]
+fn test_repository_tool_contract_is_injected_for_every_style() {
+    let required_contract = [
+        "## Repository Tool Contract",
+        "`file_path`",
+        "`files`",
+        "`max_output_bytes`",
+        "`metadata.batch.continuation`",
+        "`output_mode`",
+        "`files_with_matches`",
+        "`metadata.page.next_cursor`",
+        "`sort: \"path\"`",
+        "`dry_run`",
+        "`expected_replacements`",
+        "`max_replacements`",
+    ];
+
+    for style in [
+        AgentStyle::GeneralPurpose,
+        AgentStyle::Plan,
+        AgentStyle::Verification,
+        AgentStyle::Explore,
+        AgentStyle::CodeReview,
+    ] {
+        let built = SystemPromptSlots::default().with_style(style).build();
+        for expected in required_contract {
+            assert!(
+                built.contains(expected),
+                "style {style:?} missing repository-tool guidance: {expected}"
+            );
+        }
+    }
+}
+
+#[test]
+fn test_repository_tool_contract_is_not_duplicated() {
+    let built = SystemPromptSlots::default().build();
+    assert_eq!(built.matches("## Repository Tool Contract").count(), 1);
+}
+
+#[test]
+fn test_repository_tool_contract_tracks_registered_schema_parameters() {
+    for (tool, schema) in crate::tools::builtin::repository_tool_parameter_schemas() {
+        assert!(
+            REPOSITORY_TOOL_CONTRACT.contains(&format!("`{tool}`")),
+            "repository-tool contract missing tool: {tool}"
+        );
+        let properties = schema["properties"]
+            .as_object()
+            .unwrap_or_else(|| panic!("{tool} schema has no object properties"));
+        for parameter in properties.keys() {
+            assert!(
+                REPOSITORY_TOOL_CONTRACT.contains(&format!("`{parameter}`")),
+                "repository-tool contract missing {tool} parameter: {parameter}"
+            );
+        }
+    }
+}
+
 #[test]
 fn test_slots_custom_role_replaces_default() {
     let slots = SystemPromptSlots {
@@ -399,6 +459,7 @@ fn test_code_review_guidelines_appended() {
 fn test_prompts_do_not_reference_removed_surfaces() {
     let prompts = [
         SYSTEM_DEFAULT,
+        REPOSITORY_TOOL_CONTRACT,
         AGENT_VERIFICATION,
         PRE_ANALYSIS_SYSTEM,
         AGENT_EXPLORE,

core/src/tools/builtin/mod.rs

@@ -77,6 +77,22 @@ pub fn register_builtins(
     registry.register_builtin(Arc::new(web_search::WebSearchTool::new()));
 }
 
+#[cfg(test)]
+pub(crate) fn repository_tool_parameter_schemas() -> Vec<(String, serde_json::Value)> {
+    use crate::tools::Tool;
+
+    let read = read::ReadTool;
+    let grep = grep::GrepTool;
+    let glob = glob_tool::GlobTool;
+    let edit = edit::EditTool;
+    vec![
+        (read.name().to_string(), read.parameters()),
+        (grep.name().to_string(), grep.parameters()),
+        (glob.name().to_string(), glob.parameters()),
+        (edit.name().to_string(), edit.parameters()),
+    ]
+}
+
 /// Register the batch tool. Must be called after the registry is wrapped in Arc.
 pub fn register_batch(registry: &Arc<ToolRegistry>) {
     registry.register_builtin(Arc::new(batch::BatchTool::new(Arc::clone(registry))));