fix: prompt caching, and adding docs references (#2421)

Author: brandonskiser

Cargo.toml

@@ -92,7 +92,7 @@ security-framework = "3.2.0"
 semantic_search_client = { path = "crates/semantic-search-client" }
 semver = { version = "1.0.26", features = ["serde"] }
 serde = { version = "1.0.219", features = ["derive", "rc"] }
-serde_json = "1.0.140"
+serde_json = { version = "1.0.140", features = ["preserve_order"] }
 sha2 = "0.10.9"
 shell-color = "1.0.0"
 shell-words = "1.1.0"

crates/chat-cli/src/cli/chat/cli/context.rs

@@ -10,7 +10,10 @@ use crossterm::{
     style,
 };
 
-use crate::cli::chat::consts::CONTEXT_FILES_MAX_SIZE;
+use crate::cli::chat::consts::{
+    AGENT_FORMAT_HOOKS_DOC_URL,
+    CONTEXT_FILES_MAX_SIZE,
+};
 use crate::cli::chat::token_counter::TokenCounter;
 use crate::cli::chat::util::drop_matched_context_files;
 use crate::cli::chat::{
@@ -281,12 +284,13 @@ impl ContextSubcommand {
                 execute!(
                     session.stderr,
                     style::SetForegroundColor(Color::Yellow),
-                    style::Print("The /context hooks command is deprecated. Use "),
+                    style::Print(
+                        "The /context hooks command is deprecated.\n\nConfigure hooks directly with your agent instead: "
+                    ),
                     style::SetForegroundColor(Color::Green),
-                    style::Print("/hooks"),
-                    style::SetForegroundColor(Color::Yellow),
-                    style::Print(" instead.\n\n"),
-                    style::SetForegroundColor(Color::Reset)
+                    style::Print(AGENT_FORMAT_HOOKS_DOC_URL),
+                    style::SetForegroundColor(Color::Reset),
+                    style::Print("\n"),
                 )?;
             },
         }

crates/chat-cli/src/cli/chat/cli/hooks.rs

@@ -10,6 +10,7 @@ use bstr::ByteSlice;
 use clap::Args;
 use crossterm::style::{
     self,
+    Attribute,
     Color,
     Stylize,
 };
@@ -36,6 +37,7 @@ use crate::cli::agent::hook::{
     Hook,
     HookTrigger,
 };
+use crate::cli::chat::consts::AGENT_FORMAT_HOOKS_DOC_URL;
 use crate::cli::chat::util::truncate_safe;
 use crate::cli::chat::{
     ChatError,
@@ -67,7 +69,7 @@ impl HookExecutor {
     /// If `updates` is `Some`, progress on hook execution will be written to it.
     /// Errors encountered with write operations to `updates` are ignored.
     ///
-    /// Note: [`HookTrigger::ConversationStart`] hooks never leave the cache.
+    /// Note: [`HookTrigger::AgentSpawn`] hooks never leave the cache.
     pub async fn run_hooks(
         &mut self,
         hooks: HashMap<HookTrigger, Vec<Hook>>,
@@ -175,6 +177,8 @@ impl HookExecutor {
             });
         }
 
+        results.append(&mut cached);
+
         Ok(results)
     }
 
@@ -275,6 +279,8 @@ fn sanitize_user_prompt(input: &str) -> String {
     before_long_help = "Use context hooks to specify shell commands to run. The output from these 
 commands will be appended to the prompt to Amazon Q.
 
+Refer to the documentation for how to configure hooks with your agent: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md#hooks-field
+
 Notes:
 • Hooks are executed in parallel
 • 'conversation_start' hooks run on the first user prompt and are attached once to the conversation history sent to Amazon Q
@@ -290,18 +296,34 @@ impl HooksArgs {
             });
         };
 
+        let mut out = Vec::new();
         for (trigger, hooks) in &context_manager.hooks {
-            writeln!(session.stdout, "{trigger}:")?;
+            writeln!(&mut out, "{trigger}:")?;
             match hooks.is_empty() {
-                true => writeln!(session.stdout, "<none>")?,
+                true => writeln!(&mut out, "<none>")?,
                 false => {
                     for hook in hooks {
-                        writeln!(session.stdout, "  - {}", hook.command)?;
+                        writeln!(&mut out, "  - {}", hook.command)?;
                     }
                 },
             }
         }
 
+        if out.is_empty() {
+            queue!(
+                session.stderr,
+                style::Print(
+                    "No hooks are configured.\n\nRefer to the documentation for how to add hooks to your agent: "
+                ),
+                style::SetForegroundColor(Color::Green),
+                style::Print(AGENT_FORMAT_HOOKS_DOC_URL),
+                style::SetAttribute(Attribute::Reset),
+                style::Print("\n"),
+            )?;
+        } else {
+            session.stdout.write_all(&out)?;
+        }
+
         Ok(ChatState::PromptUser {
             skip_printing_tools: true,
         })

crates/chat-cli/src/cli/chat/cli/mod.rs

@@ -62,13 +62,13 @@ pub enum SlashCommand {
     PromptEditor(EditorArgs),
     /// Summarize the conversation to free up context space
     Compact(CompactArgs),
-    /// View and manage tools and permissions
+    /// View tools and permissions
     Tools(ToolsArgs),
     /// Create a new Github issue or make a feature request
     Issue(issue::IssueArgs),
     /// View and retrieve prompts
     Prompts(PromptsArgs),
-    /// View and manage context hooks
+    /// View context hooks
     Hooks(HooksArgs),
     /// Show current session's context window usage
     Usage(UsageArgs),

crates/chat-cli/src/cli/chat/cli/tools.rs

@@ -19,7 +19,10 @@ use crossterm::{
 
 use crate::api_client::model::Tool as FigTool;
 use crate::cli::agent::Agent;
-use crate::cli::chat::consts::DUMMY_TOOL_NAME;
+use crate::cli::chat::consts::{
+    AGENT_FORMAT_TOOLS_DOC_URL,
+    DUMMY_TOOL_NAME,
+};
 use crate::cli::chat::tools::ToolOrigin;
 use crate::cli::chat::{
     ChatError,
@@ -150,19 +153,19 @@ impl ToolsArgs {
             }
         }
 
-        queue!(
-            session.stderr,
-            style::Print("\nTrusted tools will run without confirmation."),
-            style::SetForegroundColor(Color::DarkGrey),
-            style::Print(format!("\n{}\n", "* Default settings")),
-            style::Print("\n💡 Use "),
-            style::SetForegroundColor(Color::Green),
-            style::Print("/tools help"),
-            style::SetForegroundColor(Color::Reset),
-            style::SetForegroundColor(Color::DarkGrey),
-            style::Print(" to edit permissions.\n\n"),
-            style::SetForegroundColor(Color::Reset),
-        )?;
+        if origin_tools.is_empty() {
+            queue!(
+                session.stderr,
+                style::Print(
+                    "\nNo tools are currently enabled.\n\nRefer to the documentation for how to add tools to your agent: "
+                ),
+                style::SetForegroundColor(Color::Green),
+                style::Print(AGENT_FORMAT_TOOLS_DOC_URL),
+                style::SetForegroundColor(Color::Reset),
+                style::Print("\n"),
+                style::SetForegroundColor(Color::Reset),
+            )?;
+        }
 
         Ok(ChatState::default())
     }
@@ -176,7 +179,9 @@ impl ToolsArgs {
 #[derive(Debug, PartialEq, Subcommand)]
 #[command(
     before_long_help = "By default, Amazon Q will ask for your permission to use certain tools. You can control which tools you
-trust so that no confirmation is required. These settings will last only for this session."
+trust so that no confirmation is required.
+
+Refer to the documentation for how to configure tools with your agent: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md#tools-field"
 )]
 pub enum ToolsSubcommand {
     /// Show the input schema for all available tools

crates/chat-cli/src/cli/chat/consts.rs

@@ -26,3 +26,9 @@ pub const MAX_NUMBER_OF_IMAGES_PER_REQUEST: usize = 10;
 
 /// In bytes - 10 MB
 pub const MAX_IMAGE_SIZE: usize = 10 * 1024 * 1024;
+
+pub const AGENT_FORMAT_HOOKS_DOC_URL: &str =
+    "https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md#hooks-field";
+
+pub const AGENT_FORMAT_TOOLS_DOC_URL: &str =
+    "https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md#tools-field";

crates/chat-cli/src/cli/chat/context.rs

@@ -176,10 +176,13 @@ impl ContextManager {
     /// A vector containing pairs of a [`Hook`] definition and its execution output
     pub async fn run_hooks(
         &mut self,
+        trigger: HookTrigger,
         output: &mut impl Write,
         prompt: Option<&str>,
     ) -> Result<Vec<((HookTrigger, Hook), String)>, ChatError> {
-        self.hook_executor.run_hooks(self.hooks.clone(), output, prompt).await
+        let mut hooks = self.hooks.clone();
+        hooks.retain(|t, _| *t == trigger);
+        self.hook_executor.run_hooks(hooks, output, prompt).await
     }
 }
 

crates/chat-cli/src/cli/chat/conversation.rs

@@ -328,14 +328,14 @@ impl ConversationState {
         &mut self,
         os: &Os,
         stderr: &mut impl Write,
-        run_hooks: bool,
+        run_perprompt_hooks: bool,
     ) -> Result<FigConversationState, ChatError> {
         debug_assert!(self.next_message.is_some());
         self.enforce_conversation_invariants();
         self.history.drain(self.valid_history_range.1..);
         self.history.drain(..self.valid_history_range.0);
 
-        let context = self.backend_conversation_state(os, run_hooks, stderr).await?;
+        let context = self.backend_conversation_state(os, run_perprompt_hooks, stderr).await?;
         if !context.dropped_context_files.is_empty() {
             execute!(
                 stderr,
@@ -389,28 +389,30 @@ impl ConversationState {
     pub async fn backend_conversation_state(
         &mut self,
         os: &Os,
-        run_hooks: bool,
+        run_perprompt_hooks: bool,
         output: &mut impl Write,
     ) -> Result<BackendConversationState<'_>, ChatError> {
         self.update_state(false).await;
         self.enforce_conversation_invariants();
 
         // Run hooks and add to conversation start and next user message.
-        let mut conversation_start_context = None;
-        if let (true, Some(cm)) = (run_hooks, self.context_manager.as_mut()) {
-            // Get the user prompt from next_message if available
+        let mut agent_spawn_context = None;
+        if let Some(cm) = self.context_manager.as_mut() {
             let user_prompt = self.next_message.as_ref().and_then(|m| m.prompt());
-            let hook_results = cm.run_hooks(output, user_prompt).await?;
-
-            conversation_start_context = Some(format_hook_context(&hook_results, HookTrigger::AgentSpawn));
-
-            // add per prompt content to next_user_message if available
-            if let Some(next_message) = self.next_message.as_mut() {
-                next_message.additional_context = format_hook_context(&hook_results, HookTrigger::UserPromptSubmit);
+            let agent_spawn = cm.run_hooks(HookTrigger::AgentSpawn, output, user_prompt).await?;
+            agent_spawn_context = format_hook_context(&agent_spawn, HookTrigger::AgentSpawn);
+
+            if let (true, Some(next_message)) = (run_perprompt_hooks, self.next_message.as_mut()) {
+                let per_prompt = cm
+                    .run_hooks(HookTrigger::UserPromptSubmit, output, next_message.prompt())
+                    .await?;
+                if let Some(ctx) = format_hook_context(&per_prompt, HookTrigger::UserPromptSubmit) {
+                    next_message.additional_context = ctx;
+                }
             }
         }
 
-        let (context_messages, dropped_context_files) = self.context_messages(os, conversation_start_context).await;
+        let (context_messages, dropped_context_files) = self.context_messages(os, agent_spawn_context).await;
 
         Ok(BackendConversationState {
             conversation_id: self.conversation_id.as_str(),
@@ -556,7 +558,7 @@ impl ConversationState {
     async fn context_messages(
         &mut self,
         os: &Os,
-        conversation_start_context: Option<String>,
+        additional_context: Option<String>,
     ) -> (Option<Vec<HistoryEntry>>, Vec<(String, String)>) {
         let mut context_content = String::new();
         let mut dropped_context_files = Vec::new();
@@ -591,7 +593,7 @@ impl ConversationState {
             }
         }
 
-        if let Some(context) = conversation_start_context {
+        if let Some(context) = additional_context {
             context_content.push_str(&context);
         }
 
@@ -765,7 +767,17 @@ impl From<InputSchema> for ToolInputSchema {
     }
 }
 
-fn format_hook_context(hook_results: &[((HookTrigger, Hook), String)], trigger: HookTrigger) -> String {
+/// Formats hook output to be used within context blocks (e.g., in context messages or in new user
+/// prompts).
+///
+/// # Returns
+/// [Option::Some] if `hook_results` is not empty and at least one hook has content. Otherwise,
+/// [Option::None]
+fn format_hook_context(hook_results: &[((HookTrigger, Hook), String)], trigger: HookTrigger) -> Option<String> {
+    if hook_results.iter().all(|(_, content)| content.is_empty()) {
+        return None;
+    }
+
     let mut context_content = String::new();
 
     context_content.push_str(CONTEXT_ENTRY_START_HEADER);
@@ -779,7 +791,7 @@ fn format_hook_context(hook_results: &[((HookTrigger, Hook), String)], trigger:
         context_content.push_str(&format!("{output}\n\n"));
     }
     context_content.push_str(CONTEXT_ENTRY_END_HEADER);
-    context_content
+    Some(context_content)
 }
 
 fn enforce_conversation_invariants(

crates/chat-cli/src/cli/chat/message.rs

@@ -152,9 +152,10 @@ impl UserMessage {
     /// Converts this message into a [UserInputMessage] to be stored in the history of
     /// [api_client::model::ConversationState].
     pub fn into_history_entry(self) -> UserInputMessage {
+        let content = self.content_with_context();
         UserInputMessage {
             images: self.images.clone(),
-            content: self.prompt().unwrap_or_default().to_string(),
+            content,
             user_input_message_context: Some(UserInputMessageContext {
                 env_state: self.env_context.env_state,
                 tool_results: match self.content {
@@ -179,17 +180,10 @@ impl UserMessage {
         model_id: Option<String>,
         tools: &HashMap<ToolOrigin, Vec<Tool>>,
     ) -> UserInputMessage {
-        let formatted_prompt = match self.prompt() {
-            Some(prompt) if !prompt.is_empty() => {
-                format!("{}{}{}", USER_ENTRY_START_HEADER, prompt, USER_ENTRY_END_HEADER)
-            },
-            _ => String::new(),
-        };
+        let content = self.content_with_context();
         UserInputMessage {
             images: self.images,
-            content: format!("{} {}", self.additional_context, formatted_prompt)
-                .trim()
-                .to_string(),
+            content,
             user_input_message_context: Some(UserInputMessageContext {
                 env_state: self.env_context.env_state,
                 tool_results: match self.content {
@@ -270,6 +264,21 @@ impl UserMessage {
             self.content = UserMessageContent::Prompt { prompt };
         }
     }
+
+    /// Returns a formatted [String] containing [Self::additional_context] and [Self::prompt].
+    fn content_with_context(&self) -> String {
+        match (self.additional_context.is_empty(), self.prompt()) {
+            // Only add special delimiters if we have both a prompt and additional context
+            (false, Some(prompt)) => format!(
+                "{} {}{}{}",
+                self.additional_context, USER_ENTRY_START_HEADER, prompt, USER_ENTRY_END_HEADER
+            ),
+            (true, Some(prompt)) => prompt.to_string(),
+            _ => self.additional_context.clone(),
+        }
+        .trim()
+        .to_string()
+    }
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]