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 {