feat(hooks): lifecycle hooks and documentation

.gitignore

@@ -121,6 +121,12 @@ coverage/
 # personal files
 personal/
 
+# local convenience scripts
+run.sh
+build-and-run.sh
+install-alias.sh
+ccstatusline/
+
 # os
 .DS_Store
 Thumbs.db

code-rs/app-server/src/message_processor.rs

@@ -3,7 +3,6 @@ use std::path::PathBuf;
 use crate::code_message_processor::CodexMessageProcessor;
 use crate::error_code::INVALID_REQUEST_ERROR_CODE;
 use crate::outgoing_message::OutgoingMessageSender;
-use code_protocol::mcp_protocol::AuthMode;
 use code_protocol::mcp_protocol::ClientInfo;
 use code_protocol::mcp_protocol::ClientRequest;
 use code_protocol::mcp_protocol::InitializeResponse;
@@ -39,7 +38,7 @@ impl MessageProcessor {
         let outgoing = Arc::new(outgoing);
         let auth_manager = AuthManager::shared_with_mode_and_originator(
             config.code_home.clone(),
-            AuthMode::ApiKey,
+            config.preferred_auth_mode(),
             config.responses_originator_header.clone(),
         );
         let conversation_manager = Arc::new(ConversationManager::new(

code-rs/cli/src/llm.rs

@@ -10,7 +10,6 @@ use code_core::agent_defaults::model_guide_markdown_with_custom;
 use code_core::AuthManager;
 use code_core::Prompt;
 use code_core::TextFormat;
-use code_app_server_protocol::AuthMode;
 use code_protocol::models::{ContentItem, ResponseItem};
 use futures::StreamExt;
 
@@ -134,7 +133,7 @@ async fn run_llm_request(
     // Auth + provider
     let auth_mgr = AuthManager::shared_with_mode_and_originator(
         config.code_home.clone(),
-        AuthMode::ApiKey,
+        config.preferred_auth_mode(),
         config.responses_originator_header.clone(),
     );
     let provider: ModelProviderInfo = config.model_provider.clone();

code-rs/cli/src/proto.rs

@@ -40,7 +40,7 @@ pub async fn run_main(opts: ProtoCli) -> anyhow::Result<()> {
     // Use conversation_manager API to start a conversation
     let auth_manager = AuthManager::shared_with_mode_and_originator(
         config.code_home.clone(),
-        code_login::AuthMode::ApiKey,
+        config.preferred_auth_mode(),
         config.responses_originator_header.clone(),
     );
     let conversation_manager = ConversationManager::new(auth_manager.clone(), SessionSource::Cli);

code-rs/code-auto-drive-core/src/auto_coordinator.rs

@@ -1105,16 +1105,11 @@ fn run_auto_loop(
     let compact_prompt_text =
         resolve_compact_prompt_text(config.compact_prompt_override.as_deref());
 
-    let preferred_auth = if config.using_chatgpt_auth {
-        code_protocol::mcp_protocol::AuthMode::ChatGPT
-    } else {
-        code_protocol::mcp_protocol::AuthMode::ApiKey
-    };
     let code_home = config.code_home.clone();
     let responses_originator_header = config.responses_originator_header.clone();
     let auth_mgr = AuthManager::shared_with_mode_and_originator(
         code_home,
-        preferred_auth,
+        config.preferred_auth_mode(),
         responses_originator_header,
     );
     let model_provider = config.model_provider.clone();

code-rs/core/src/agent_tool.rs

@@ -306,6 +306,13 @@ impl AgentManager {
         self.start_watchdog();
     }
 
+    /// Emit a status update payload to any active listener (used by tests and integrations).
+    pub fn emit_status_update(&self, payload: AgentStatusUpdatePayload) {
+        if let Some(ref sender) = self.event_sender {
+            let _ = sender.send(payload);
+        }
+    }
+
     fn start_watchdog(&mut self) {
         if self.watchdog_handle.is_some() {
             return;

code-rs/core/src/codex/compact.rs

@@ -6,15 +6,18 @@ use super::Session;
 use super::compact_remote;
 use super::TurnContext;
 use super::streaming::get_last_assistant_message_from_turn;
+use super::exec::build_postcompact_hook_payload;
 use crate::Prompt;
 use crate::client_common::ResponseEvent;
+use crate::config_types::ProjectHookEvent;
 use crate::environment_context::EnvironmentContext;
 use crate::error::CodexErr;
 use crate::error::RetryAfter;
 use crate::error::Result as CodexResult;
 use crate::protocol::AgentMessageEvent;
 use crate::protocol::ErrorEvent;
 use crate::protocol::EventMsg;
+use crate::turn_diff_tracker::TurnDiffTracker;
 use code_protocol::protocol::CompactionCheckpointWarningEvent;
 use crate::protocol::InputItem;
 use crate::protocol::TaskCompleteEvent;
@@ -175,7 +178,7 @@ pub(super) async fn run_inline_auto_compact_task(
     let sub_id = sess.next_internal_sub_id();
     let prompt_text = resolve_compact_prompt_text(turn_context.compact_prompt_override.as_deref());
     let input = vec![InputItem::Text { text: prompt_text.clone() }];
-    run_compact_task_inner_inline(sess, turn_context, sub_id, input).await
+    run_compact_task_inner_inline(sess, turn_context, sub_id, input, "auto").await
 }
 
 pub(super) async fn run_compact_task(
@@ -192,6 +195,7 @@ pub(super) async fn run_compact_task(
             Arc::clone(&turn_context),
             sub_id.clone(),
             input,
+            "manual",
         )
         .await
     } else {
@@ -201,6 +205,7 @@ pub(super) async fn run_compact_task(
             sub_id.clone(),
             input,
             true,
+            "manual",
         )
         .await
     };
@@ -222,6 +227,7 @@ pub(super) async fn perform_compaction(
     sub_id: String,
     input: Vec<InputItem>,
     remove_task_on_completion: bool,
+    reason: &str,
 ) -> CodexResult<()> {
     // Convert core InputItem -> ResponseInputItem using the same logic as the main turn flow
     let initial_input_for_turn: ResponseInputItem = response_input_from_core_items(input);
@@ -361,6 +367,8 @@ pub(super) async fn perform_compaction(
     // state bookkeeping stays centralized.
     sess.replace_history(new_history);
 
+    run_postcompact_hook(&sess, reason).await;
+
     send_compaction_checkpoint_warning(&sess, &sub_id).await;
 
     let rollout_item = RolloutItem::Compacted(CompactedItem {
@@ -389,6 +397,7 @@ async fn run_compact_task_inner_inline(
     turn_context: Arc<TurnContext>,
     sub_id: String,
     input: Vec<InputItem>,
+    reason: &str,
 ) -> Vec<ResponseItem> {
     // Convert core InputItem -> ResponseInputItem and build prompt
     let initial_input_for_turn: ResponseInputItem = response_input_from_core_items(input);
@@ -526,6 +535,8 @@ async fn run_compact_task_inner_inline(
         state.token_usage_info = None;
     }
 
+    run_postcompact_hook(&sess, reason).await;
+
     send_compaction_checkpoint_warning(&sess, &sub_id).await;
 
     let rollout_item = RolloutItem::Compacted(CompactedItem {
@@ -549,6 +560,22 @@ async fn run_compact_task_inner_inline(
     new_history
 }
 
+pub(super) async fn run_postcompact_hook(sess: &Session, reason: &str) {
+    let payload = build_postcompact_hook_payload(sess, reason);
+    let mut tracker = TurnDiffTracker::new();
+    let attempt_req = sess.current_request_ordinal();
+    let result = sess
+        .run_hooks_for_event(
+            &mut tracker,
+            ProjectHookEvent::PostCompact,
+            &payload,
+            None,
+            attempt_req,
+        )
+        .await;
+    sess.enqueue_hook_system_messages(result.system_messages);
+}
+
 pub fn content_items_to_text(content: &[ContentItem]) -> Option<String> {
     let mut pieces = Vec::new();
     for item in content {

code-rs/core/src/codex/compact_remote.rs

@@ -4,6 +4,7 @@ use super::compact::{
     is_context_overflow_error,
     prune_orphan_tool_outputs,
     response_input_from_core_items,
+    run_postcompact_hook,
     sanitize_items_for_compact,
     send_compaction_checkpoint_warning,
 };
@@ -30,7 +31,7 @@ pub(super) async fn run_inline_remote_auto_compact_task(
     extra_input: Vec<InputItem>,
 ) -> Vec<ResponseItem> {
     let sub_id = sess.next_internal_sub_id();
-    match run_remote_compact_task_inner(&sess, &turn_context, &sub_id, extra_input).await {
+    match run_remote_compact_task_inner(&sess, &turn_context, &sub_id, extra_input, "auto").await {
         Ok(history) => history,
         Err(err) => {
             let event = sess.make_event(
@@ -50,8 +51,9 @@ pub(super) async fn run_remote_compact_task(
     turn_context: Arc<TurnContext>,
     sub_id: String,
     extra_input: Vec<InputItem>,
+    reason: &str,
 ) -> CodexResult<()> {
-    match run_remote_compact_task_inner(&sess, &turn_context, &sub_id, extra_input).await {
+    match run_remote_compact_task_inner(&sess, &turn_context, &sub_id, extra_input, reason).await {
         Ok(_history) => {
             // Mirror local compaction behaviour: clear the running task when the
             // compaction finished successfully so the UI can unblock.
@@ -76,6 +78,7 @@ async fn run_remote_compact_task_inner(
     turn_context: &Arc<TurnContext>,
     sub_id: &str,
     extra_input: Vec<InputItem>,
+    reason: &str,
 ) -> CodexResult<Vec<ResponseItem>> {
     let mut turn_items = sess.turn_input_with_history({
         if extra_input.is_empty() {
@@ -167,6 +170,8 @@ async fn run_remote_compact_task_inner(
         state.token_usage_info = None;
     }
 
+    run_postcompact_hook(sess, reason).await;
+
     send_compaction_checkpoint_warning(sess, sub_id).await;
 
     let rollout_item = RolloutItem::Compacted(CompactedItem {