From 342f0a399c11d0a71c1ae2fcbea78391dca66cab Mon Sep 17 00:00:00 2001
From: Aakash Bakhle <48802744+aakashb95@users.noreply.github.com>
Date: Wed, 5 Aug 2026 10:29:43 +0530
Subject: [PATCH] fix(captain): resolve V2 FAQ citations from trusted sources
 (#15159)

Captain V2 now adds FAQ citations from a structured model response. The
model returns ordered response parts with citation indexes, and Chatwoot
turns only trusted indexes into customer links.

## Before

Captain V2 asked the model to copy text markers such as `[[faq:1]]`.
Chatwoot used one regular expression to replace those markers with links
in the outgoing message and another regular expression to remove the
rendered links before the next model turn. Long conversations depended
on parsing the customer message to recover plain model context.

## After

The FAQ lookup tool now gives each eligible source document a numeric
index and never gives the model a URL. FAQ results from the same
document reuse the same index. The model returns `response_parts`, where
each part contains customer text and the supporting citation indexes.
Chatwoot checks every index against the document IDs registered during
the current run.

Only stored HTTP or HTTPS web-document links without embedded
credentials can appear in the customer reply. Blank links, PDF sources,
attachments, non-HTTP storage links, and unknown indexes do not create
links. Sources receive display numbers in the order they first appear,
and repeated sources keep the same display number.

Chatwoot saves the structured response parts with each newly generated
Captain message. Later Captain V2 turns use the saved plain text for
those messages, so they never need to parse rendered links. Existing
messages remain unchanged and continue to use their stored content. When
citations are disabled, Chatwoot clears citation indexes before it
returns or saves the response.

Captain V1, Copilot, legacy prompts, legacy tools, and the playground
response contract are unchanged. The playground continues to show the
plain `response` field.

## Closes

[AI-138](https://linear.app/chatwoot/issue/AI-138/faq-citation-fix)

## How to test

1. Open a conversation handled by a Captain V2 assistant and turn
citations off. Ask a greeting, an FAQ question, a code question, and a
follow up question. Confirm that the assistant answers normally and
shows no source links.
2. Turn citations on and ask a question that matches one public web
document. Confirm that the reply shows the stored public link after the
supported text.
3. Ask a question that needs two public web documents. Confirm that the
response order stays correct, each link appears after the supported
text, and repeated sources keep the same display number.
4. Ask a question that retrieves several FAQ results from one document.
Confirm that the reply shows the document once at each supported
response part rather than exposing separate FAQ sources.
5. Ask a question supported by a PDF, attachment, blank link, or
non-HTTP storage link. Confirm that Captain can use the information but
does not show a customer link.
6. Ask for a fenced code example with a citation. Confirm that the code
block stays complete and the citation appears after the closing fence.
7. Continue the conversation with a follow up question. Confirm that
Captain uses the earlier plain response text and does not receive or
repeat rendered citation links.
8. Test a scenario handoff in a conversation. Confirm that the handoff
and final response still work.
---
 .../message/CaptainGenerationDetails.vue      |  13 +-
 ...dd_cited_document_ids_to_agent_sessions.rb |   5 +
 ...ex_on_agent_sessions_cited_document_ids.rb |   7 +
 ...0002_add_used_faq_ids_to_agent_sessions.rb |   5 +
 ...dd_index_on_agent_sessions_used_faq_ids.rb |   7 +
 db/schema.rb                                  |   6 +-
 .../captain/agent_sessions_controller.rb      |   8 +-
 .../captain/conversation/message_builder.rb   |  13 +-
 .../app/models/captain/agent_session.rb       |  38 +--
 enterprise/app/models/captain/assistant.rb    |  21 ++
 .../app/models/captain/assistant_response.rb  |   4 +
 enterprise/app/models/captain/document.rb     |  35 +++
 enterprise/app/models/captain/scenario.rb     |   1 +
 .../captain/assistant/agent_run_response.rb   |  67 +++++
 .../captain/assistant/agent_runner_service.rb |  54 +---
 .../captain/assistant/response_parts.rb       |  70 ++++++
 .../captain/assistant/response_rewriter.rb    |  57 +++--
 .../assistant/session_capture_service.rb      |  14 ++
 .../message_history_builder_service.rb        |  13 +-
 .../captain/agent_sessions/show.json.jbuilder |   8 +-
 .../lib/captain/prompts/assistant.liquid      |   2 +
 .../lib/captain/prompts/scenario.liquid       |   2 +
 .../captain/prompts/snippets/citations.liquid |   4 +
 enterprise/lib/captain/response_schema.rb     |  12 +-
 .../lib/captain/tools/faq_lookup_tool.rb      |  42 ++--
 .../captain/agent_sessions_controller_spec.rb |  30 +--
 .../captain/assistants_controller_spec.rb     |   8 +-
 .../conversation/response_builder_job_spec.rb | 230 +++++++++++++++++-
 .../lib/captain/prompt_renderer_spec.rb       |  11 +
 .../lib/captain/tools/faq_lookup_tool_spec.rb |  64 ++++-
 .../models/captain/agent_session_spec.rb      |   4 +-
 .../models/captain/document_spec.rb           |  32 +++
 .../models/concerns/agentable_spec.rb         |  13 +
 .../assistant/agent_runner_service_spec.rb    | 189 +++++++++++++-
 .../assistant/session_capture_service_spec.rb |  49 ++++
 35 files changed, 996 insertions(+), 142 deletions(-)
 create mode 100644 db/migrate/20260804000000_add_cited_document_ids_to_agent_sessions.rb
 create mode 100644 db/migrate/20260804000001_add_index_on_agent_sessions_cited_document_ids.rb
 create mode 100644 db/migrate/20260804000002_add_used_faq_ids_to_agent_sessions.rb
 create mode 100644 db/migrate/20260804000003_add_index_on_agent_sessions_used_faq_ids.rb
 create mode 100644 enterprise/app/services/captain/assistant/agent_run_response.rb
 create mode 100644 enterprise/app/services/captain/assistant/response_parts.rb
 create mode 100644 enterprise/lib/captain/prompts/snippets/citations.liquid

diff --git a/app/javascript/dashboard/components-next/message/CaptainGenerationDetails.vue b/app/javascript/dashboard/components-next/message/CaptainGenerationDetails.vue
index 752616109..85e1fdf2d 100644
--- a/app/javascript/dashboard/components-next/message/CaptainGenerationDetails.vue
+++ b/app/javascript/dashboard/components-next/message/CaptainGenerationDetails.vue
@@ -37,6 +37,11 @@ const isLoading = computed(
 );
 
 const citations = computed(() => session.value?.citations || []);
+const usedFaqs = computed(() => session.value?.usedFaqs || []);
+const knowledgeSources = computed(() => [
+  ...citations.value.map(source => ({ ...source, type: 'document' })),
+  ...usedFaqs.value.map(source => ({ ...source, type: 'faq' })),
+]);
 
 const scenarioTitles = computed(() =>
   (session.value?.scenarios || []).reduce((map, scenario) => {
@@ -289,7 +294,7 @@ const onPopoverHide = () => {
                 </div>
               </div>
             </div>
-            <div v-if="citations.length" class="flex flex-col gap-2">
+            <div v-if="knowledgeSources.length" class="flex flex-col gap-2">
               <div class="flex items-baseline gap-1.5">
                 <span class="text-xs font-medium text-n-slate-11">
                   {{ t('CONVERSATION.CAPTAIN_GENERATION.SOURCES') }}
@@ -298,15 +303,15 @@ const onPopoverHide = () => {
                   {{
                     t(
                       'CONVERSATION.CAPTAIN_GENERATION.SOURCES_SUMMARY',
-                      citations.length
+                      knowledgeSources.length
                     )
                   }}
                 </span>
               </div>
               <ul class="flex flex-col gap-1 m-0 list-disc ps-4">
                 <li
-                  v-for="citation in citations"
-                  :key="citation.id"
+                  v-for="citation in knowledgeSources"
+                  :key="`${citation.type}-${citation.id}`"
                   class="text-xs text-n-slate-12"
                 >
                   <a
diff --git a/db/migrate/20260804000000_add_cited_document_ids_to_agent_sessions.rb b/db/migrate/20260804000000_add_cited_document_ids_to_agent_sessions.rb
new file mode 100644
index 000000000..68b549b6a
--- /dev/null
+++ b/db/migrate/20260804000000_add_cited_document_ids_to_agent_sessions.rb
@@ -0,0 +1,5 @@
+class AddCitedDocumentIdsToAgentSessions < ActiveRecord::Migration[7.1]
+  def change
+    add_column :agent_sessions, :cited_document_ids, :jsonb, default: [], null: false
+  end
+end
diff --git a/db/migrate/20260804000001_add_index_on_agent_sessions_cited_document_ids.rb b/db/migrate/20260804000001_add_index_on_agent_sessions_cited_document_ids.rb
new file mode 100644
index 000000000..062b531f4
--- /dev/null
+++ b/db/migrate/20260804000001_add_index_on_agent_sessions_cited_document_ids.rb
@@ -0,0 +1,7 @@
+class AddIndexOnAgentSessionsCitedDocumentIds < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :agent_sessions, :cited_document_ids, using: :gin, algorithm: :concurrently
+  end
+end
diff --git a/db/migrate/20260804000002_add_used_faq_ids_to_agent_sessions.rb b/db/migrate/20260804000002_add_used_faq_ids_to_agent_sessions.rb
new file mode 100644
index 000000000..e4410cf58
--- /dev/null
+++ b/db/migrate/20260804000002_add_used_faq_ids_to_agent_sessions.rb
@@ -0,0 +1,5 @@
+class AddUsedFaqIdsToAgentSessions < ActiveRecord::Migration[7.1]
+  def change
+    add_column :agent_sessions, :used_faq_ids, :jsonb, default: [], null: false
+  end
+end
diff --git a/db/migrate/20260804000003_add_index_on_agent_sessions_used_faq_ids.rb b/db/migrate/20260804000003_add_index_on_agent_sessions_used_faq_ids.rb
new file mode 100644
index 000000000..4fee6b7ce
--- /dev/null
+++ b/db/migrate/20260804000003_add_index_on_agent_sessions_used_faq_ids.rb
@@ -0,0 +1,7 @@
+class AddIndexOnAgentSessionsUsedFaqIds < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  def change
+    add_index :agent_sessions, :used_faq_ids, using: :gin, algorithm: :concurrently
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index b2b2ac870..59de4c368 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[7.1].define(version: 2026_08_03_130000) do
+ActiveRecord::Schema[7.1].define(version: 2026_08_04_000003) do
   # These extensions should be enabled to support this database
   enable_extension "pg_stat_statements"
   enable_extension "pg_trgm"
@@ -163,11 +163,15 @@ ActiveRecord::Schema[7.1].define(version: 2026_08_03_130000) do
     t.jsonb "run_context", default: {}
     t.datetime "created_at", null: false
     t.datetime "updated_at", null: false
+    t.jsonb "cited_document_ids", default: [], null: false
+    t.jsonb "used_faq_ids", default: [], null: false
     t.index ["account_id", "result_type", "result_id"], name: "idx_on_account_id_result_type_result_id_ca66c00cd7"
     t.index ["account_id", "session_type", "created_at"], name: "idx_on_account_id_session_type_created_at_c20a14bd4e"
     t.index ["account_id", "subject_type", "subject_id"], name: "idx_on_account_id_subject_type_subject_id_6d60963b3d"
     t.index ["account_id"], name: "index_agent_sessions_on_account_id"
     t.index ["assistant_id"], name: "index_agent_sessions_on_assistant_id"
+    t.index ["cited_document_ids"], name: "index_agent_sessions_on_cited_document_ids", using: :gin
+    t.index ["used_faq_ids"], name: "index_agent_sessions_on_used_faq_ids", using: :gin
     t.index ["user_id"], name: "index_agent_sessions_on_user_id"
   end
 
diff --git a/enterprise/app/controllers/api/v1/accounts/captain/agent_sessions_controller.rb b/enterprise/app/controllers/api/v1/accounts/captain/agent_sessions_controller.rb
index f9163de04..72c9b77ac 100644
--- a/enterprise/app/controllers/api/v1/accounts/captain/agent_sessions_controller.rb
+++ b/enterprise/app/controllers/api/v1/accounts/captain/agent_sessions_controller.rb
@@ -6,9 +6,11 @@ class Api::V1::Accounts::Captain::AgentSessionsController < Api::V1::Accounts::B
     @agent_session = Current.account.captain_agent_sessions.find_by(result_type: 'Message', result_id: @message.id)
     return head :not_found if @agent_session.blank?
 
-    @citations = Current.account.captain_assistant_responses
-                        .where(id: @agent_session.faq_ids)
-                        .includes(:documentable)
+    @citations = Current.account.captain_documents.where(id: @agent_session.cited_document_ids)
+    @used_faqs = Current.account.captain_assistant_responses.approved.where(
+      id: @agent_session.used_faq_ids,
+      documentable_type: 'User'
+    )
     @scenario_titles = Captain::Scenario.where(account_id: Current.account.id, id: @agent_session.scenario_ids)
                                         .pluck(:id, :title).to_h
   end
diff --git a/enterprise/app/jobs/captain/conversation/message_builder.rb b/enterprise/app/jobs/captain/conversation/message_builder.rb
index 7954e9465..95f76b791 100644
--- a/enterprise/app/jobs/captain/conversation/message_builder.rb
+++ b/enterprise/app/jobs/captain/conversation/message_builder.rb
@@ -28,6 +28,16 @@ module Captain::Conversation::MessageBuilder
   end
 
   def create_messages
+    return create_v1_message unless captain_v2_enabled?
+
+    response_parts = Captain::Assistant::ResponseParts.from_response(@response)
+    citation_urls = @assistant.trusted_citation_urls(@run_result)
+    message_content = response_parts.customer_message_content(citation_urls: citation_urls)
+    validate_message_content!(message_content)
+    create_outgoing_message(message_content, agent_name: @response['agent_name'], response_parts: response_parts.to_a)
+  end
+
+  def create_v1_message
     validate_message_content!(@response['response'])
     create_outgoing_message(@response['response'], agent_name: @response['agent_name'])
   end
@@ -36,9 +46,10 @@ module Captain::Conversation::MessageBuilder
     raise ArgumentError, 'Message content cannot be blank' if content.blank?
   end
 
-  def create_outgoing_message(message_content, agent_name: nil, preserve_waiting_since: false)
+  def create_outgoing_message(message_content, agent_name: nil, response_parts: nil, preserve_waiting_since: false)
     additional_attrs = {}
     additional_attrs[:agent_name] = agent_name if agent_name.present?
+    additional_attrs[Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY] = response_parts unless response_parts.nil?
 
     @conversation.messages.create!(
       message_type: :outgoing,
diff --git a/enterprise/app/models/captain/agent_session.rb b/enterprise/app/models/captain/agent_session.rb
index d02dffcab..803e2ea23 100644
--- a/enterprise/app/models/captain/agent_session.rb
+++ b/enterprise/app/models/captain/agent_session.rb
@@ -2,23 +2,25 @@
 #
 # Table name: agent_sessions
 #
-#  id               :bigint           not null, primary key
-#  credits_consumed :float
-#  document_ids     :jsonb
-#  faq_ids          :jsonb
-#  llm_model        :string
-#  result_type      :string
-#  run_context      :jsonb
-#  scenario_ids     :jsonb
-#  session_type     :integer          not null
-#  subject_type     :string           not null
-#  created_at       :datetime         not null
-#  updated_at       :datetime         not null
-#  account_id       :bigint           not null
-#  assistant_id     :bigint           not null
-#  result_id        :bigint
-#  subject_id       :bigint           not null
-#  user_id          :bigint
+#  id                 :bigint           not null, primary key
+#  cited_document_ids :jsonb            not null
+#  credits_consumed   :float
+#  document_ids       :jsonb
+#  faq_ids            :jsonb
+#  llm_model          :string
+#  result_type        :string
+#  run_context        :jsonb
+#  scenario_ids       :jsonb
+#  session_type       :integer          not null
+#  subject_type       :string           not null
+#  used_faq_ids       :jsonb            not null
+#  created_at         :datetime         not null
+#  updated_at         :datetime         not null
+#  account_id         :bigint           not null
+#  assistant_id       :bigint           not null
+#  result_id          :bigint
+#  subject_id         :bigint           not null
+#  user_id            :bigint
 #
 # Indexes
 #
@@ -27,6 +29,8 @@
 #  idx_on_account_id_subject_type_subject_id_6d60963b3d  (account_id,subject_type,subject_id)
 #  index_agent_sessions_on_account_id                    (account_id)
 #  index_agent_sessions_on_assistant_id                  (assistant_id)
+#  index_agent_sessions_on_cited_document_ids            (cited_document_ids) USING gin
+#  index_agent_sessions_on_used_faq_ids                  (used_faq_ids) USING gin
 #  index_agent_sessions_on_user_id                       (user_id)
 #
 class Captain::AgentSession < ApplicationRecord
diff --git a/enterprise/app/models/captain/assistant.rb b/enterprise/app/models/captain/assistant.rb
index 44b64d956..0149049ec 100644
--- a/enterprise/app/models/captain/assistant.rb
+++ b/enterprise/app/models/captain/assistant.rb
@@ -18,6 +18,7 @@
 #
 class Captain::Assistant < ApplicationRecord
   DESCRIPTION_LENGTH_LIMIT = 500
+  CITATION_SOURCES_STATE_KEY = :captain_v2_citation_sources
   AUTO_RESOLVE_MODES = %w[disabled legacy evaluated].freeze
 
   include Avatarable
@@ -107,6 +108,25 @@ class Captain::Assistant < ApplicationRecord
     }
   end
 
+  def customer_visible_citation_urls(citation_document_ids)
+    citation_documents = documents.where(id: citation_document_ids.values).index_by(&:id)
+    citation_urls = citation_document_ids.transform_values do |document_id|
+      citation_documents[document_id.to_i]&.customer_visible_source_url
+    end
+    citation_urls.compact.transform_keys(&:to_i)
+  end
+
+  def citations_enabled?
+    config['feature_citation']
+  end
+
+  def trusted_citation_urls(run_result)
+    return {} unless citations_enabled?
+
+    citation_document_ids = run_result&.context&.dig(:state, CITATION_SOURCES_STATE_KEY) || {}
+    customer_visible_citation_urls(citation_document_ids)
+  end
+
   private
 
   def set_default_auto_resolve_mode
@@ -132,6 +152,7 @@ class Captain::Assistant < ApplicationRecord
       name: name,
       description: description,
       product_name: config['product_name'] || 'this product',
+      citation_enabled: citations_enabled?,
       scenarios: scenarios.enabled.map do |scenario|
         {
           title: scenario.title,
diff --git a/enterprise/app/models/captain/assistant_response.rb b/enterprise/app/models/captain/assistant_response.rb
index d2dd031a8..758bc4203 100644
--- a/enterprise/app/models/captain/assistant_response.rb
+++ b/enterprise/app/models/captain/assistant_response.rb
@@ -51,6 +51,10 @@ class Captain::AssistantResponse < ApplicationRecord
     nearest_neighbors(:embedding, embedding, distance: 'cosine').limit(5)
   end
 
+  def customer_visible_source_url
+    documentable.customer_visible_source_url if documentable.is_a?(Captain::Document)
+  end
+
   private
 
   def ensure_status
diff --git a/enterprise/app/models/captain/document.rb b/enterprise/app/models/captain/document.rb
index 6eda0eb5a..4d838e943 100644
--- a/enterprise/app/models/captain/document.rb
+++ b/enterprise/app/models/captain/document.rb
@@ -103,6 +103,21 @@ class Captain::Document < ApplicationRecord
     end
   end
 
+  def customer_visible_source_url
+    return unless customer_visible_source?
+
+    url = external_link.presence
+    return unless url
+
+    uri = URI.parse(url)
+    return unless customer_visible_uri?(uri)
+    return if File.extname(uri.path).casecmp('.pdf').zero?
+
+    uri.to_s
+  rescue URI::InvalidURIError
+    nil
+  end
+
   def to_llm_metadata
     { document_id: id, assistant_id: assistant_id, external_link: external_link }
   end
@@ -121,6 +136,26 @@ class Captain::Document < ApplicationRecord
 
   private
 
+  def customer_visible_source?
+    !pdf_document? && !pdf_file.attached?
+  end
+
+  def customer_visible_uri?(uri)
+    return false unless uri.is_a?(URI::HTTP) && uri.host.present? && uri.userinfo.blank?
+
+    addresses = SsrfFilter::DEFAULT_RESOLVER.call(uri.host)
+    addresses.present? && addresses.all? { |ip| publicly_routable_address?(ip) }
+  rescue Resolv::ResolvError, Resolv::ResolvTimeout, IPAddr::InvalidAddressError
+    false
+  end
+
+  def publicly_routable_address?(ip)
+    return false if ip.ipv6? && SsrfFilter::NAT64_LOCAL_PREFIX.dup.include?(ip)
+
+    blocked_ranges = ip.ipv4? ? SsrfFilter::IPV4_BLACKLIST : SsrfFilter::IPV6_BLACKLIST
+    blocked_ranges.none? { |range| range.include?(ip) }
+  end
+
   def enqueue_crawl_job
     return if status != 'in_progress'
 
diff --git a/enterprise/app/models/captain/scenario.rb b/enterprise/app/models/captain/scenario.rb
index 895133897..67f24dcb3 100644
--- a/enterprise/app/models/captain/scenario.rb
+++ b/enterprise/app/models/captain/scenario.rb
@@ -67,6 +67,7 @@ class Captain::Scenario < ApplicationRecord
       instructions: resolved_instructions,
       tools: resolved_tools,
       assistant_name: assistant.name.downcase.gsub(/\s+/, '_'),
+      citation_enabled: assistant.citations_enabled?,
       response_guidelines: response_guidelines || [],
       guardrails: guardrails || []
     }
diff --git a/enterprise/app/services/captain/assistant/agent_run_response.rb b/enterprise/app/services/captain/assistant/agent_run_response.rb
new file mode 100644
index 000000000..2138f8dc9
--- /dev/null
+++ b/enterprise/app/services/captain/assistant/agent_run_response.rb
@@ -0,0 +1,67 @@
+module Captain::Assistant::AgentRunResponse
+  private
+
+  def process_agent_result(run_result)
+    Rails.logger.info "[Captain V2] Agent result: #{run_result.inspect}"
+    model_output = run_result.output
+    structured_response = if model_output.is_a?(Hash)
+                            model_output.with_indifferent_access
+                          else
+                            { 'response' => model_output.to_s, 'reasoning' => 'Processed by agent' }
+                          end
+    response_parts = Captain::Assistant::ResponseParts.from_response(structured_response)
+    response_parts = response_parts.without_citations unless @assistant.citations_enabled?
+    structured_response['response_parts'] = response_parts.to_a
+    structured_response['response'] = response_parts.plain_text
+    structured_response['agent_name'] = run_result.context&.dig(:current_agent)
+    structured_response['handoff_tool_called'] = run_result.context&.dig(:captain_v2_handoff_tool_called) || false
+    structured_response
+  end
+
+  def rewrite_oversized_response(run_result)
+    response_parts = Captain::Assistant::ResponseParts.from_response(run_result.output)
+    rendered_customer_message = customer_message_content(run_result)
+    citation_markup_length = rendered_customer_message.length - response_parts.plain_text.length
+    response_text_limit = message_length_limit - citation_markup_length
+    raise 'Captain citation links exceed the channel limit' unless response_text_limit.positive?
+
+    response_rewriter.rewrite(run_result, response_parts: response_parts, response_text_limit: response_text_limit)
+  end
+
+  def response_rewriter
+    @response_rewriter ||= Captain::Assistant::ResponseRewriter.new(
+      assistant: @assistant,
+      attribute_provider: Captain::Assistant::InstrumentationAttributeProvider.new(self)
+    )
+  end
+
+  def record_turn_start(run_result)
+    history = Array(run_result.context&.dig(:conversation_history))
+    turn_start_index = history.rindex { |message| message[:role].to_s == 'user' }
+    run_result.context[:captain_v2_turn_start_index] = turn_start_index if turn_start_index
+  end
+
+  def response_too_long?(run_result)
+    message_length_limit && customer_message_content(run_result).length > message_length_limit
+  end
+
+  def customer_message_content(run_result)
+    response_parts = Captain::Assistant::ResponseParts.from_response(run_result.output)
+    response_parts.customer_message_content(citation_urls: @assistant.trusted_citation_urls(run_result))
+  end
+
+  def message_length_limit
+    @message_length_limit ||= Captain::MessageLengthLimit.for(@conversation)
+  end
+
+  def error_response(error)
+    {
+      'response' => 'conversation_handoff',
+      'response_parts' => [{ 'text' => 'conversation_handoff', 'citation_indexes' => [] }],
+      'reasoning' => "Error occurred: #{error.message}",
+      'error' => true,
+      'error_reason' => error.class.name.underscore.tr('/', '_'),
+      'handoff_tool_called' => @handoff_tool_called
+    }
+  end
+end
diff --git a/enterprise/app/services/captain/assistant/agent_runner_service.rb b/enterprise/app/services/captain/assistant/agent_runner_service.rb
index b2c7efa45..68ca142b8 100644
--- a/enterprise/app/services/captain/assistant/agent_runner_service.rb
+++ b/enterprise/app/services/captain/assistant/agent_runner_service.rb
@@ -3,6 +3,7 @@ require 'agents/instrumentation'
 
 class Captain::Assistant::AgentRunnerService
   include Captain::Assistant::RunnerCallbacksHelper
+  include Captain::Assistant::AgentRunResponse
   include Captain::Assistant::RunnerInstrumentationHelper
   include Captain::Assistant::TracePayloadHelper
   include Captain::Assistant::RunnerStateHelper
@@ -86,7 +87,10 @@ class Captain::Assistant::AgentRunnerService
 
   def extract_text_from_content(content)
     # Handle structured output from agents
-    return content[:response] || content['response'] || content.to_s if content.is_a?(Hash)
+    if content.is_a?(Hash)
+      response_text = Captain::Assistant::ResponseParts.from_response(content).plain_text
+      return response_text.presence || content.to_s
+    end
 
     return content unless content.is_a?(Array)
 
@@ -94,54 +98,6 @@ class Captain::Assistant::AgentRunnerService
     text_parts.join(' ')
   end
 
-  def process_agent_result(result)
-    Rails.logger.info "[Captain V2] Agent result: #{result.inspect}"
-    output = result.output
-    response = output.is_a?(Hash) ? output.with_indifferent_access : { 'response' => output.to_s, 'reasoning' => 'Processed by agent' }
-    response['agent_name'] = result.context&.dig(:current_agent)
-    response['handoff_tool_called'] = result.context&.dig(:captain_v2_handoff_tool_called) || false
-    response
-  end
-
-  def rewrite_oversized_response(result)
-    response_rewriter.rewrite(result, response: response_text(result), limit: message_length_limit)
-  end
-
-  def response_rewriter
-    @response_rewriter ||= Captain::Assistant::ResponseRewriter.new(
-      assistant: @assistant,
-      attribute_provider: Captain::Assistant::InstrumentationAttributeProvider.new(self)
-    )
-  end
-
-  def record_turn_start(result)
-    history = Array(result.context&.dig(:conversation_history))
-    turn_start_index = history.rindex { |message| message[:role].to_s == 'user' }
-    result.context[:captain_v2_turn_start_index] = turn_start_index if turn_start_index
-  end
-
-  def response_too_long?(result)
-    message_length_limit && response_text(result).length > message_length_limit
-  end
-
-  def response_text(result)
-    extract_text_from_content(result.output).to_s
-  end
-
-  def message_length_limit
-    @message_length_limit ||= Captain::MessageLengthLimit.for(@conversation)
-  end
-
-  def error_response(error)
-    {
-      'response' => 'conversation_handoff',
-      'reasoning' => "Error occurred: #{error.message}",
-      'error' => true,
-      'error_reason' => error.class.name.underscore.tr('/', '_'),
-      'handoff_tool_called' => @handoff_tool_called
-    }
-  end
-
   def build_and_wire_agents
     assistant_agent = @assistant.agent
     scenario_agents = @assistant.scenarios.enabled.map(&:agent)
diff --git a/enterprise/app/services/captain/assistant/response_parts.rb b/enterprise/app/services/captain/assistant/response_parts.rb
new file mode 100644
index 000000000..eb35d2c94
--- /dev/null
+++ b/enterprise/app/services/captain/assistant/response_parts.rb
@@ -0,0 +1,70 @@
+class Captain::Assistant::ResponseParts
+  MESSAGE_ATTRIBUTE_KEY = 'captain_v2_response_parts'.freeze
+  CLOSING_CODE_FENCE_LINE = /\A(?:`{3,}|~{3,})\z/
+
+  attr_reader :parts
+
+  def self.from_response(response)
+    return new([{ text: response.to_s, citation_indexes: [] }]) unless response.is_a?(Hash)
+
+    response = response.with_indifferent_access
+    return new(response[:response_parts]) if response.key?(:response_parts)
+
+    new([{ text: response[:response], citation_indexes: [] }])
+  end
+
+  def initialize(response_parts)
+    @parts = Array(response_parts).filter_map { |part| normalize_part(part) }
+  end
+
+  def plain_text
+    parts.pluck('text').join("\n\n")
+  end
+
+  def without_citations
+    self.class.new(parts.map { |part| part.merge('citation_indexes' => []) })
+  end
+
+  def customer_message_content(citation_urls: {})
+    display_numbers = {}
+
+    parts.map do |part|
+      links = part['citation_indexes'].filter_map do |citation_index|
+        url = citation_urls[citation_index]
+        next if url.blank?
+
+        # Number trusted sources by first appearance and reuse that number for later references.
+        display_number = display_numbers[url] ||= display_numbers.size + 1
+        markdown_safe_url = url.gsub('(', '%28').gsub(')', '%29')
+        "[[#{display_number}](#{markdown_safe_url})]"
+      end.uniq
+
+      final_text_line = part['text'].lines.last.to_s.strip
+      citation_separator = final_text_line.match?(CLOSING_CODE_FENCE_LINE) ? "\n" : ' '
+      [part['text'], links.join(' ')].compact_blank.join(citation_separator)
+    end.join("\n\n")
+  end
+
+  def to_a
+    parts
+  end
+
+  private
+
+  def normalize_part(part)
+    return unless part.is_a?(Hash)
+
+    part = part.with_indifferent_access
+    return unless part[:text].is_a?(String)
+
+    text = part[:text].strip
+    return if text.blank?
+
+    {
+      'text' => text,
+      'citation_indexes' => Array(part[:citation_indexes]).select do |citation_index|
+        citation_index.is_a?(Integer) && citation_index.positive?
+      end.uniq
+    }
+  end
+end
diff --git a/enterprise/app/services/captain/assistant/response_rewriter.rb b/enterprise/app/services/captain/assistant/response_rewriter.rb
index 972a1e1ad..0703dc993 100644
--- a/enterprise/app/services/captain/assistant/response_rewriter.rb
+++ b/enterprise/app/services/captain/assistant/response_rewriter.rb
@@ -12,26 +12,55 @@ class Captain::Assistant::ResponseRewriter
     @attribute_provider = attribute_provider
   end
 
-  def rewrite(result, response:, limit:)
-    prompt = "The response below is #{response.length} characters, but this channel allows a maximum of #{limit}. " \
-             'Shorten it while preserving names, numbers, dates, links, warnings, and completed actions. ' \
-             "Do not add facts.\n\nResponse:\n#{response}"
-    context = {
-      session_id: result.context[:session_id],
-      state: result.context[:state],
-      captain_v2_trace_input: prompt
+  def rewrite(run_result, response_parts:, response_text_limit:)
+    rewrite_prompt = build_rewrite_prompt(response_parts, response_text_limit)
+    rewrite_context = {
+      session_id: run_result.context[:session_id],
+      state: run_result.context[:state],
+      captain_v2_trace_input: rewrite_prompt
     }
-    rewritten_result = runner.run(prompt, context: context, max_turns: 1)
-    raise rewritten_result.error || 'Captain response rewrite failed' if rewritten_result.failed?
+    rewrite_run_result = runner.run(rewrite_prompt, context: rewrite_context, max_turns: 1)
+    raise rewrite_run_result.error || 'Captain response rewrite failed' if rewrite_run_result.failed?
 
-    replace_final_assistant_output(result.context[:conversation_history], rewritten_result.output)
-    replace_final_assistant_output(result.messages, rewritten_result.output)
-    result.output = rewritten_result.output
-    result
+    rewritten_model_output = rewritten_response_with_original_citations(rewrite_run_result.output, response_parts)
+    replace_final_assistant_output(run_result.context[:conversation_history], rewritten_model_output)
+    replace_final_assistant_output(run_result.messages, rewritten_model_output)
+    run_result.output = rewritten_model_output
+    run_result
   end
 
   private
 
+  def build_rewrite_prompt(response_parts, response_text_limit)
+    response_text = response_parts.plain_text
+
+    "The response text below is #{response_text.length} characters, but it must be at most #{response_text_limit} characters " \
+      'so the complete customer message fits this channel. ' \
+      'Shorten the text in each response part so the joined customer message fits the limit. ' \
+      'Keep the same number and order of response parts. Change only each text field. ' \
+      'Preserve names, numbers, dates, links, warnings, and completed actions. Keep Markdown valid within each text field. Do not add facts. ' \
+      "Return the complete structured response.\n\nResponse parts:\n#{response_parts.to_a.to_json}"
+  end
+
+  def rewritten_response_with_original_citations(rewritten_model_output, original_response_parts)
+    rewritten_model_output = rewritten_model_output.with_indifferent_access
+    rewritten_response_parts = Captain::Assistant::ResponseParts.from_response(rewritten_model_output)
+    original_parts = original_response_parts.to_a
+    rewritten_parts = rewritten_response_parts.to_a
+    raise 'Captain response rewrite changed the number of response parts' unless rewritten_parts.size == original_parts.size
+
+    original_citation_indexes = original_parts.pluck('citation_indexes')
+    rewritten_citation_indexes = rewritten_parts.pluck('citation_indexes')
+    if @assistant.citations_enabled? && rewritten_citation_indexes != original_citation_indexes
+      raise 'Captain response rewrite changed the response part citation order'
+    end
+
+    rewritten_model_output['response_parts'] = rewritten_parts.zip(original_parts).map do |rewritten_part, original_part|
+      rewritten_part.merge('citation_indexes' => original_part['citation_indexes'])
+    end
+    rewritten_model_output
+  end
+
   def runner
     @runner ||= begin
       agent = Agents::Agent.new(
diff --git a/enterprise/app/services/captain/assistant/session_capture_service.rb b/enterprise/app/services/captain/assistant/session_capture_service.rb
index 3927faefa..643bc302a 100644
--- a/enterprise/app/services/captain/assistant/session_capture_service.rb
+++ b/enterprise/app/services/captain/assistant/session_capture_service.rb
@@ -31,6 +31,8 @@ class Captain::Assistant::SessionCaptureService
       llm_model: "#{Llm::Models.provider_for(model)}-#{model}",
       credits_consumed: @credits_consumed,
       faq_ids: metadata[:faq_ids] || [],
+      used_faq_ids: metadata[:used_faq_ids] || [],
+      cited_document_ids: cited_document_ids,
       document_ids: metadata[:document_ids] || [],
       scenario_ids: scenario_ids,
       run_context: current_turn_history
@@ -47,6 +49,18 @@ class Captain::Assistant::SessionCaptureService
     @metadata ||= context.dig(:state, :cw_metadata) || {}
   end
 
+  def cited_document_ids
+    return [] unless @assistant.config['feature_citation']
+
+    citation_document_ids = (context.dig(:state, Captain::Assistant::CITATION_SOURCES_STATE_KEY) || {}).transform_keys(&:to_i)
+    visible_citation_indexes = @assistant.customer_visible_citation_urls(citation_document_ids).keys
+    stored_response_parts = result_message.additional_attributes.to_h[Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY]
+    response_parts = Captain::Assistant::ResponseParts.new(stored_response_parts)
+    selected_citation_indexes = response_parts.to_a.flat_map { |part| part['citation_indexes'] }.uniq
+
+    (selected_citation_indexes & visible_citation_indexes).filter_map { |index| citation_document_ids[index] }.uniq
+  end
+
   # On handoff, HandoffTool records the private reason note it created; the session
   # attaches there so agents can inspect the generation path on the note itself.
   def result_message
diff --git a/enterprise/app/services/captain/conversation/message_history_builder_service.rb b/enterprise/app/services/captain/conversation/message_history_builder_service.rb
index c70b876ad..805c40044 100644
--- a/enterprise/app/services/captain/conversation/message_history_builder_service.rb
+++ b/enterprise/app/services/captain/conversation/message_history_builder_service.rb
@@ -24,8 +24,11 @@ class Captain::Conversation::MessageHistoryBuilderService
   def message_hash_for_context(message)
     return activity_message_hash(message) if message.message_type == 'activity'
 
+    content = prepare_multimodal_message_content(message)
+    return if content.blank?
+
     {
-      content: prepare_multimodal_message_content(message),
+      content: content,
       role: determine_role(message)
     }
   end
@@ -45,6 +48,14 @@ class Captain::Conversation::MessageHistoryBuilderService
   end
 
   def prepare_multimodal_message_content(message)
+    if message.outgoing? && message.sender_type == 'Captain::Assistant' && !message.deleted
+      message_attributes = message.additional_attributes.to_h
+      response_parts_attribute = Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY
+      if message_attributes.key?(response_parts_attribute)
+        return Captain::Assistant::ResponseParts.new(message_attributes[response_parts_attribute]).plain_text.presence
+      end
+    end
+
     Captain::OpenAiMessageBuilderService.new(message: message).generate_content
   end
 end
diff --git a/enterprise/app/views/api/v1/accounts/captain/agent_sessions/show.json.jbuilder b/enterprise/app/views/api/v1/accounts/captain/agent_sessions/show.json.jbuilder
index 1e1cd1d7d..ed5940314 100644
--- a/enterprise/app/views/api/v1/accounts/captain/agent_sessions/show.json.jbuilder
+++ b/enterprise/app/views/api/v1/accounts/captain/agent_sessions/show.json.jbuilder
@@ -5,13 +5,17 @@ json.credits_consumed @agent_session.credits_consumed
 json.run_context @agent_session.run_context.is_a?(Array) ? @agent_session.run_context : []
 json.citations @citations do |citation|
   json.id citation.id
-  json.title citation.question
+  json.title citation.name
   # display_url resolves uploaded PDFs to their blob URL; external_link holds a
   # "PDF: ..." placeholder for those. Guard on scheme so placeholders render as
   # plain text instead of dead anchors.
-  link = citation.documentable.is_a?(Captain::Document) ? citation.documentable.display_url : nil
+  link = citation.display_url
   json.link link&.match?(%r{\Ahttps?://}) ? link : nil
 end
+json.used_faqs @used_faqs do |faq|
+  json.id faq.id
+  json.title faq.question
+end
 json.scenarios @scenario_titles do |id, title|
   json.id id
   json.title title
diff --git a/enterprise/lib/captain/prompts/assistant.liquid b/enterprise/lib/captain/prompts/assistant.liquid
index 722ca0631..34c30746f 100644
--- a/enterprise/lib/captain/prompts/assistant.liquid
+++ b/enterprise/lib/captain/prompts/assistant.liquid
@@ -10,6 +10,8 @@ You are {{name}}, a helpful, friendly, and knowledgeable assistant for the produ
 
 Don't digress away from your instructions, and use all the available tools at your disposal for solving customer issues. If you are to state something factual about {{product_name}}, use the `captain--tools--faq_lookup` tool to check the available information first.
 
+{% render 'citations', citation_enabled: citation_enabled %}
+
 {% render 'current_time', current_time: current_time %}
 
 {% render 'core_rules' %}
diff --git a/enterprise/lib/captain/prompts/scenario.liquid b/enterprise/lib/captain/prompts/scenario.liquid
index 667c009dc..7fd702877 100644
--- a/enterprise/lib/captain/prompts/scenario.liquid
+++ b/enterprise/lib/captain/prompts/scenario.liquid
@@ -8,6 +8,8 @@ You are a specialized agent called "{{ title }}", your task is to handle the fol
 
 If you believe the user's request is not within the scope of your role, you can assign this conversation back to the orchestrator agent using the `handoff_to_{{ assistant_name }}` tool
 
+{% render 'citations', citation_enabled: citation_enabled %}
+
 {% render 'current_time', current_time: current_time %}
 
 {% render 'core_rules' %}
diff --git a/enterprise/lib/captain/prompts/snippets/citations.liquid b/enterprise/lib/captain/prompts/snippets/citations.liquid
new file mode 100644
index 000000000..455c8284d
--- /dev/null
+++ b/enterprise/lib/captain/prompts/snippets/citations.liquid
@@ -0,0 +1,4 @@
+{% if citation_enabled -%}
+# Citations
+Each eligible FAQ result can include a numeric citation index. Put the supporting result's index in the `citation_indexes` array for each response part that uses it. Use only indexes shown in FAQ results. Reuse the same index for repeated references. Leave the array empty when the response part has no eligible source. Never include a source URL in response text or a citation field.
+{% endif -%}
diff --git a/enterprise/lib/captain/response_schema.rb b/enterprise/lib/captain/response_schema.rb
index 651eb7e23..055171bab 100644
--- a/enterprise/lib/captain/response_schema.rb
+++ b/enterprise/lib/captain/response_schema.rb
@@ -1,6 +1,16 @@
 # TODO: Wrap the schema lib under ai-agents
 # So we can extend it as Agents::Schema
 class Captain::ResponseSchema < RubyLLM::Schema
-  string :response, description: 'The message to send to the user'
+  array :response_parts,
+        description: 'Ordered parts of the message to send to the user. Keep all customer-visible text within each part text field.',
+        min_items: 1 do
+    object do
+      string :text, description: 'Customer-visible response text without citation markers or source URLs.', min_length: 1
+      array :citation_indexes,
+            description: 'Numeric citation indexes from FAQ results that support this text. Use an empty array when none apply.' do
+        integer minimum: 1
+      end
+    end
+  end
   string :reasoning, description: "Agent's thought process"
 end
diff --git a/enterprise/lib/captain/tools/faq_lookup_tool.rb b/enterprise/lib/captain/tools/faq_lookup_tool.rb
index 087e35672..fd5b9c8a9 100644
--- a/enterprise/lib/captain/tools/faq_lookup_tool.rb
+++ b/enterprise/lib/captain/tools/faq_lookup_tool.rb
@@ -6,7 +6,7 @@ class Captain::Tools::FaqLookupTool < Captain::Tools::BasePublicTool
     log_tool_usage('searching', { query: query })
 
     # Use existing vector search on approved responses
-    responses = @assistant.responses.approved.search(query).to_a
+    responses = @assistant.responses.approved.search(query).includes(:documentable).to_a
     record_retrieved_sources(tool_context, responses)
 
     if responses.empty?
@@ -14,7 +14,7 @@ class Captain::Tools::FaqLookupTool < Captain::Tools::BasePublicTool
       "No relevant FAQs found for: #{query}"
     else
       log_tool_usage('found_results', { query: query, count: responses.size })
-      format_responses(responses)
+      format_responses(tool_context, responses)
     end
   end
 
@@ -30,34 +30,42 @@ class Captain::Tools::FaqLookupTool < Captain::Tools::BasePublicTool
     metadata = tool_context.state[:cw_metadata] ||= {}
     metadata[:faq_ids] = Array(metadata[:faq_ids]) | responses.map(&:id)
 
-    document_ids = responses.filter_map { |response| response.documentable_id if response.documentable_type == 'Captain::Document' }
+    responses_by_type = responses.group_by(&:documentable_type)
+    document_ids = Array(responses_by_type['Captain::Document']).map(&:documentable_id)
     metadata[:document_ids] = Array(metadata[:document_ids]) | document_ids
+
+    used_faq_ids = Array(responses_by_type['User']).map(&:id)
+    metadata[:used_faq_ids] = Array(metadata[:used_faq_ids]) | used_faq_ids
   end
 
-  def format_responses(responses)
-    responses.map { |response| format_response(response) }.join
+  def format_responses(tool_context, responses)
+    responses.map { |response| format_response(tool_context, response) }.join
   end
 
-  def format_response(response)
+  def format_response(tool_context, response)
     formatted_response = "
+        FAQ result:
+        "
+    if @assistant.citations_enabled? && response.customer_visible_source_url.present?
+      formatted_response += "
+          Citation index: #{citation_index(tool_context, response)}
+          "
+    end
+    formatted_response += "
         Question: #{response.question}
         Answer: #{response.answer}
         "
-    if should_show_source?(response)
-      formatted_response += "
-          Source: #{response.documentable.external_link}
-          "
-    end
 
     formatted_response
   end
 
-  def should_show_source?(response)
-    return false if response.documentable.blank?
-    return false unless response.documentable.try(:external_link)
+  def citation_index(tool_context, response)
+    citation_document_ids = tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY] ||= {}
+    existing_index = citation_document_ids.find { |_index, document_id| document_id == response.documentable_id }&.first
+    return existing_index if existing_index.present?
 
-    # Don't show source if it's a PDF placeholder
-    external_link = response.documentable.external_link
-    !external_link.start_with?('PDF:')
+    next_citation_index = citation_document_ids.size + 1
+    citation_document_ids[next_citation_index] = response.documentable_id
+    next_citation_index
   end
 end
diff --git a/spec/enterprise/controllers/api/v1/accounts/captain/agent_sessions_controller_spec.rb b/spec/enterprise/controllers/api/v1/accounts/captain/agent_sessions_controller_spec.rb
index 1444dc0a8..7af9f857f 100644
--- a/spec/enterprise/controllers/api/v1/accounts/captain/agent_sessions_controller_spec.rb
+++ b/spec/enterprise/controllers/api/v1/accounts/captain/agent_sessions_controller_spec.rb
@@ -26,21 +26,14 @@ RSpec.describe 'Api::V1::Accounts::Captain::AgentSessions', type: :request do
     end
 
     context 'when the message has an agent session' do
-      let(:document) { create(:captain_document, account: account, assistant: assistant) }
+      let(:document) { create(:captain_document, account: account, assistant: assistant, name: 'Password reset guide') }
       let(:documented_faq) do
         create(:captain_assistant_response, account: account, assistant: assistant,
                                             question: 'How do I reset my password?', documentable: document)
       end
-      let(:plain_faq) do
-        create(:captain_assistant_response, account: account, assistant: assistant, question: 'How do I change my email?')
-      end
-      let(:pdf_document) do
-        create(:captain_document, account: account, assistant: assistant, external_link: nil,
-                                  pdf_file: Rack::Test::UploadedFile.new(Rails.root.join('spec/assets/sample.pdf'), 'application/pdf'))
-      end
-      let(:pdf_faq) do
+      let(:used_faq) do
         create(:captain_assistant_response, account: account, assistant: assistant,
-                                            question: 'What are the pricing tiers?', documentable: pdf_document)
+                                            question: 'How long do refunds take?', documentable: agent, status: :approved)
       end
       let(:scenario) { create(:captain_scenario, account: account, assistant: assistant, title: 'Refund flow') }
       let(:run_context) do
@@ -56,7 +49,10 @@ RSpec.describe 'Api::V1::Accounts::Captain::AgentSessions', type: :request do
         create(:captain_agent_session, account: account, assistant: assistant,
                                        subject: conversation, result: message,
                                        llm_model: 'openai-gpt-5.2', credits_consumed: 1.0,
-                                       faq_ids: [documented_faq.id, plain_faq.id, pdf_faq.id, documented_faq.id + 100_000],
+                                       faq_ids: [documented_faq.id],
+                                       used_faq_ids: [used_faq.id],
+                                       document_ids: [document.id],
+                                       cited_document_ids: [document.id],
                                        scenario_ids: [scenario.id],
                                        run_context: run_context)
       end
@@ -75,13 +71,11 @@ RSpec.describe 'Api::V1::Accounts::Captain::AgentSessions', type: :request do
           expect(json_response[:run_context].second[:tool_calls].first[:arguments][:query]).to eq('refund')
 
           citations = json_response[:citations].index_by { |citation| citation[:id] }
-          expect(citations.keys).to contain_exactly(documented_faq.id, plain_faq.id, pdf_faq.id)
-          expect(citations[documented_faq.id][:title]).to eq('How do I reset my password?')
-          expect(citations[documented_faq.id][:link]).to eq(document.external_link)
-          expect(citations[plain_faq.id][:link]).to be_nil
-          expect(pdf_document.external_link).to start_with('PDF:')
-          expect(citations[pdf_faq.id][:link]).to eq(pdf_document.display_url)
-          expect(citations[pdf_faq.id][:link]).to match(%r{\Ahttps?://})
+          expect(citations.keys).to contain_exactly(document.id)
+          expect(citations[document.id][:title]).to eq('Password reset guide')
+          expect(citations[document.id][:link]).to eq(document.external_link)
+
+          expect(json_response[:used_faqs]).to eq([{ id: used_faq.id, title: 'How long do refunds take?' }])
 
           expect(json_response[:scenarios]).to eq([{ id: scenario.id, title: 'Refund flow' }])
         end
diff --git a/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb b/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
index d3d7ac419..f30cda7d0 100644
--- a/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
+++ b/spec/enterprise/controllers/api/v1/accounts/captain/assistants_controller_spec.rb
@@ -477,7 +477,12 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do
           assistant: assistant,
           source: 'playground'
         ).and_return(agent_runner_service)
-        allow(agent_runner_service).to receive(:generate_response).and_return({ response: 'Assistant response' })
+        allow(agent_runner_service).to receive(:generate_response).and_return(
+          {
+            response: 'Assistant response',
+            response_parts: [{ text: 'Assistant response', citation_indexes: [] }]
+          }
+        )
         expect(Captain::Llm::AssistantChatService).not_to receive(:new)
 
         post "/api/v1/accounts/#{account.id}/captain/assistants/#{assistant.id}/playground",
@@ -490,6 +495,7 @@ RSpec.describe 'Api::V1::Accounts::Captain::Assistants', type: :request do
           message_history: valid_params[:message_history] + [{ role: 'user', content: valid_params[:message_content] }]
         )
         expect(json_response[:response]).to eq('Assistant response')
+        expect(json_response[:response_parts]).to eq([{ text: 'Assistant response', citation_indexes: [] }])
       end
 
       it 'does not duplicate the latest user message if it is already in history' do
diff --git a/spec/enterprise/jobs/captain/conversation/response_builder_job_spec.rb b/spec/enterprise/jobs/captain/conversation/response_builder_job_spec.rb
index 922a59c7c..1d7fe151f 100644
--- a/spec/enterprise/jobs/captain/conversation/response_builder_job_spec.rb
+++ b/spec/enterprise/jobs/captain/conversation/response_builder_job_spec.rb
@@ -4,7 +4,6 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
   let(:account) { create(:account, custom_attributes: { plan_name: 'startups' }) }
   let(:inbox) { create(:inbox, account: account) }
   let(:assistant) { create(:captain_assistant, account: account) }
-  let(:captain_inbox_association) { create(:captain_inbox, captain_assistant: assistant, inbox: inbox) }
 
   describe '#perform' do
     let(:conversation) { create(:conversation, inbox: inbox, account: account, status: :pending) }
@@ -13,16 +12,19 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
     let(:mock_action_classifier_service) { instance_double(Captain::Llm::AssistantActionClassifierService) }
     let(:mock_false_promise_service) { instance_double(Captain::Llm::AssistantFalsePromiseService) }
     let(:assistant_model) { Llm::Models.default_model_for('assistant') }
-    let(:responding_to_message) { conversation.messages.find_by!(content: 'Hello') }
+    let!(:responding_to_message) { create(:message, conversation: conversation, content: 'Hello', message_type: :incoming) }
+    let(:v2_response_parts) { [{ 'text' => 'Hey, welcome to Captain V2', 'citation_indexes' => [] }] }
 
     before do
-      create(:message, conversation: conversation, content: 'Hello', message_type: :incoming)
-
       allow(inbox).to receive(:captain_active?).and_return(true)
       allow(Captain::Llm::AssistantChatService).to receive(:new).and_return(mock_llm_chat_service)
       allow(mock_llm_chat_service).to receive(:generate_response).and_return({ 'response' => 'Hey, welcome to Captain Specs' })
       allow(Captain::Assistant::AgentRunnerService).to receive(:new).and_return(mock_agent_runner_service)
-      allow(mock_agent_runner_service).to receive(:generate_response).and_return({ 'response' => 'Hey, welcome to Captain V2' })
+      allow(mock_agent_runner_service).to receive(:generate_response).and_return({
+                                                                                   'response_parts' => v2_response_parts,
+                                                                                   'response' => 'Hey, welcome to Captain V2',
+                                                                                   'reasoning' => 'A friendly greeting'
+                                                                                 })
       allow(mock_agent_runner_service).to receive(:last_run_result).and_return(nil)
       allow(mock_agent_runner_service).to receive(:response_discarded?).and_return(false)
       allow(mock_agent_runner_service).to receive(:handoff_completed?).and_return(false)
@@ -446,7 +448,21 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
 
       it 'passes message history with resolution markers to agent runner service' do
         same_second = Time.current.change(usec: 0)
-        conversation.messages.find_by!(content: 'Hello').update!(created_at: same_second, updated_at: same_second)
+        responding_to_message.update!(created_at: same_second, updated_at: same_second)
+        create(
+          :message,
+          conversation: conversation,
+          sender: assistant,
+          content: 'Earlier answer [[1](https://help.example.com/private-from-model)]',
+          message_type: :outgoing,
+          additional_attributes: {
+            Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY => [
+              { 'text' => 'Earlier answer', 'citation_indexes' => [1] }
+            ]
+          },
+          created_at: same_second,
+          updated_at: same_second
+        )
         create(
           :message,
           conversation: conversation,
@@ -463,6 +479,7 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
 
         expected_messages = [
           { content: 'Hello', role: 'user' },
+          { content: 'Earlier answer', role: 'assistant' },
           {
             content: Captain::Conversation::MessageHistoryBuilderService::RESOLUTION_MARKER,
             role: 'assistant'
@@ -477,11 +494,40 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
         described_class.perform_now(conversation, assistant)
       end
 
+      it 'does not restore deleted Captain response parts into message history' do
+        deleted_content = I18n.t('conversations.messages.deleted')
+        create(
+          :message,
+          conversation: conversation,
+          sender: assistant,
+          content: deleted_content,
+          content_attributes: { deleted: true },
+          message_type: :outgoing,
+          additional_attributes: {
+            Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY => [
+              { 'text' => 'Sensitive deleted answer', 'citation_indexes' => [] }
+            ]
+          }
+        )
+
+        expect(mock_agent_runner_service).to receive(:generate_response).with(
+          message_history: [
+            { content: 'Hello', role: 'user' },
+            { content: deleted_content, role: 'assistant' }
+          ]
+        )
+
+        described_class.perform_now(conversation, assistant)
+      end
+
       it 'generates and processes response' do
         described_class.perform_now(conversation, assistant)
         expect(conversation.messages.count).to eq(2)
         expect(conversation.messages.outgoing.count).to eq(1)
         expect(conversation.messages.last.content).to eq('Hey, welcome to Captain V2')
+        expect(
+          conversation.messages.last.additional_attributes[Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY]
+        ).to eq(v2_response_parts)
       end
 
       it 'increments usage response' do
@@ -490,6 +536,177 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
         expect(account.usage_limits[:captain][:responses][:consumed]).to eq(1)
       end
 
+      context 'with structured citations' do
+        before do
+          allow(Resolv).to receive(:getaddresses).and_return(['93.184.216.34'])
+
+          first_document = create(:captain_document, assistant: assistant, external_link: 'https://help.example.com/password')
+          second_document = create(:captain_document, assistant: assistant, external_link: 'https://help.example.com/email')
+          run_result = Agents::RunResult.new(
+            output: { 'response_parts' => v2_response_parts, 'reasoning' => 'Used the FAQ results' },
+            context: {
+              state: {
+                Captain::Assistant::CITATION_SOURCES_STATE_KEY => {
+                  1 => first_document.id,
+                  2 => second_document.id
+                }
+              }
+            }
+          )
+          allow(mock_agent_runner_service).to receive(:last_run_result).and_return(run_result)
+          assistant.update!(config: assistant.config.merge('feature_citation' => true))
+        end
+
+        it 'does not render links when citations are disabled' do
+          assistant.update!(config: assistant.config.merge('feature_citation' => false))
+          v2_response_parts.first['citation_indexes'] = [1]
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq('Hey, welcome to Captain V2')
+        end
+
+        it 'renders one cited document from the trusted run mapping' do
+          v2_response_parts.first['citation_indexes'] = [1]
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq(
+            'Hey, welcome to Captain V2 [[1](https://help.example.com/password)]'
+          )
+          cited_document_id = mock_agent_runner_service.last_run_result.context[:state][Captain::Assistant::CITATION_SOURCES_STATE_KEY][1]
+          expect(Captain::AgentSession.last.cited_document_ids).to eq([cited_document_id])
+        end
+
+        it 'encodes Markdown delimiters in citation URLs' do
+          document = create(
+            :captain_document,
+            assistant: assistant,
+            external_link: 'https://help.example.com/guides/reset_(new)'
+          )
+          citation_sources = mock_agent_runner_service.last_run_result.context[:state][Captain::Assistant::CITATION_SOURCES_STATE_KEY]
+          citation_sources[3] = document.id
+          v2_response_parts.first['citation_indexes'] = [3]
+
+          described_class.perform_now(conversation, assistant)
+
+          content = conversation.messages.outgoing.last.content
+          expect(content).to eq('Hey, welcome to Captain V2 [[1](https://help.example.com/guides/reset_%28new%29)]')
+          expect(ChatwootMarkdownRenderer.new(content).render_message.to_s).to include(
+            '<a href="https://help.example.com/guides/reset_%28new%29">1</a>'
+          )
+        end
+
+        it 'renders a citation after a closing code fence' do
+          v2_response_parts.replace(
+            [
+              { 'text' => "```ruby\nputs 'hello'\n```", 'citation_indexes' => [1] },
+              { 'text' => 'Continue with the next step.', 'citation_indexes' => [2] }
+            ]
+          )
+
+          described_class.perform_now(conversation, assistant)
+
+          content = conversation.messages.outgoing.last.content
+          expect(content).to eq(
+            "```ruby\nputs 'hello'\n```\n[[1](https://help.example.com/password)]\n\n" \
+            'Continue with the next step. [[2](https://help.example.com/email)]'
+          )
+
+          rendered_content = ChatwootMarkdownRenderer.new(content).render_message.to_s
+          expect(rendered_content).to include("</code></pre>\n<p>[<a href=\"https://help.example.com/password\">1</a>]</p>")
+          expect(rendered_content).to include('<p>Continue with the next step.')
+        end
+
+        it 'preserves response part order and numbers trusted sources by first appearance' do
+          v2_response_parts.replace(
+            [
+              { 'text' => 'Email changes are in settings.', 'citation_indexes' => [2] },
+              { 'text' => 'Password resets use the reset link.', 'citation_indexes' => [1] }
+            ]
+          )
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq(
+            "Email changes are in settings. [[1](https://help.example.com/email)]\n\n" \
+            'Password resets use the reset link. [[2](https://help.example.com/password)]'
+          )
+        end
+
+        it 'reuses a display number when a response cites the same source more than once' do
+          v2_response_parts.replace(
+            [
+              { 'text' => 'Use the reset link.', 'citation_indexes' => [1, 1] },
+              { 'text' => 'The same page has the next steps.', 'citation_indexes' => [1] }
+            ]
+          )
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq(
+            "Use the reset link. [[1](https://help.example.com/password)]\n\n" \
+            'The same page has the next steps. [[1](https://help.example.com/password)]'
+          )
+        end
+
+        it 'ignores unknown indexes and non-numeric citation values' do
+          v2_response_parts.first['citation_indexes'] = [99, 'https://model.example/source']
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq('Hey, welcome to Captain V2')
+        end
+
+        it 'renders a wrong but valid index only through its trusted source mapping' do
+          v2_response_parts.first['citation_indexes'] = [2, 'https://model.example/source']
+
+          described_class.perform_now(conversation, assistant)
+
+          content = conversation.messages.outgoing.last.content
+          expect(content).to eq('Hey, welcome to Captain V2 [[1](https://help.example.com/email)]')
+          expect(content).not_to include('model.example')
+        end
+
+        it 'does not render mapped PDF or non-public sources' do
+          pdf_document = create(
+            :captain_document,
+            assistant: assistant,
+            external_link: 'https://storage.example.com/private-file.pdf?token=secret'
+          )
+          citation_sources = mock_agent_runner_service.last_run_result.context[:state][Captain::Assistant::CITATION_SOURCES_STATE_KEY]
+          citation_sources[3] = pdf_document.id
+          citation_sources[4] = 0
+          v2_response_parts.first['citation_indexes'] = [3, 4]
+
+          described_class.perform_now(conversation, assistant)
+
+          expect(conversation.messages.outgoing.last.content).to eq('Hey, welcome to Captain V2')
+        end
+
+        it 'joins valid markdown parts and drops blank or invalid parts' do
+          v2_response_parts.replace(
+            [
+              { 'text' => "  **Steps**\n\n- Open settings  ", 'citation_indexes' => [] },
+              { 'text' => '   ', 'citation_indexes' => [1] },
+              'invalid',
+              { 'text' => 'Save the change.', 'citation_indexes' => ['1'] }
+            ]
+          )
+
+          described_class.perform_now(conversation, assistant)
+
+          message = conversation.messages.outgoing.last
+          expect(message.content).to eq("**Steps**\n\n- Open settings\n\nSave the change.")
+          expect(message.additional_attributes[Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY]).to eq(
+            [
+              { 'text' => "**Steps**\n\n- Open settings", 'citation_indexes' => [] },
+              { 'text' => 'Save the change.', 'citation_indexes' => [] }
+            ]
+          )
+        end
+      end
+
       it 'emits a response completed event' do
         expect(Captain::ConversationEvents).to receive(:response_completed)
           .with(conversation: conversation, assistant: assistant, message: kind_of(Message), at: kind_of(Time))
@@ -653,6 +870,7 @@ RSpec.describe Captain::Conversation::ResponseBuilderJob, type: :job do
           llm_model: 'openai-gpt-5.2',
           credits_consumed: 1.0,
           faq_ids: [7, 9],
+          cited_document_ids: [],
           document_ids: [3],
           scenario_ids: [],
           user_id: nil
diff --git a/spec/enterprise/lib/captain/prompt_renderer_spec.rb b/spec/enterprise/lib/captain/prompt_renderer_spec.rb
index 910319253..9898ad8da 100644
--- a/spec/enterprise/lib/captain/prompt_renderer_spec.rb
+++ b/spec/enterprise/lib/captain/prompt_renderer_spec.rb
@@ -95,6 +95,17 @@ RSpec.describe Captain::PromptRenderer do
 
       expect(result).to include('Liquid error')
     end
+
+    it 'renders structured citation instructions only when citations are enabled' do
+      allow(File).to receive(:read).with(template_path).and_return("{% render 'citations', citation_enabled: citation_enabled %}")
+
+      enabled_result = described_class.render(template_name, { citation_enabled: true })
+      disabled_result = described_class.render(template_name, { citation_enabled: false })
+
+      expect(enabled_result).to include('citation_indexes', 'numeric citation index')
+      expect(enabled_result).not_to include('[[faq:')
+      expect(disabled_result).to be_blank
+    end
   end
 
   describe '.load_template' do
diff --git a/spec/enterprise/lib/captain/tools/faq_lookup_tool_spec.rb b/spec/enterprise/lib/captain/tools/faq_lookup_tool_spec.rb
index dc2b9f6c6..869b16e64 100644
--- a/spec/enterprise/lib/captain/tools/faq_lookup_tool_spec.rb
+++ b/spec/enterprise/lib/captain/tools/faq_lookup_tool_spec.rb
@@ -47,10 +47,13 @@ RSpec.describe Captain::Tools::FaqLookupTool, type: :model do
                assistant: assistant,
                question: 'How to change email?',
                answer: 'Go to settings and update email',
+               documentable: document,
                status: 'approved')
       end
 
       before do
+        allow(Resolv).to receive(:getaddresses).and_return(['93.184.216.34'])
+
         # Mock nearest_neighbors to return our test responses
         allow(Captain::AssistantResponse).to receive(:nearest_neighbors).and_return(
           Captain::AssistantResponse.where(id: [response1.id, response2.id])
@@ -64,14 +67,61 @@ RSpec.describe Captain::Tools::FaqLookupTool, type: :model do
         expect(result).to include('Answer: Click on forgot password link')
         expect(result).to include('Question: How to change email?')
         expect(result).to include('Answer: Go to settings and update email')
+        expect(result).not_to include('Citation index:')
       end
 
-      it 'includes source link when document has external_link' do
+      it 'does not assign indexes to attachments or storage links' do
+        assistant.update!(config: assistant.config.merge('feature_citation' => true))
+        document.pdf_file.attach(
+          io: StringIO.new('PDF content'),
+          filename: 'private-file.pdf',
+          content_type: 'application/pdf'
+        )
+
+        pdf_result = tool.perform(tool_context, query: 'private document')
+
+        expect(pdf_result).not_to include('Citation index:')
+        expect(tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY]).to be_nil
+
+        document.pdf_file.detach
+        document.update!(external_link: 's3://private-bucket/password')
+
+        storage_result = tool.perform(tool_context, query: 'private storage document')
+
+        expect(storage_result).not_to include('Citation index:')
+        expect(tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY]).to be_nil
+
+        document.update!(external_link: 'https://storage.example.com/private-file.pdf?token=secret')
+
+        pdf_url_result = tool.perform(tool_context, query: 'private PDF URL')
+
+        expect(pdf_url_result).not_to include('Citation index:')
+        expect(tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY]).to be_nil
+      end
+
+      it 'assigns stable numeric indexes to customer-visible document links' do
+        assistant.update!(config: assistant.config.merge('feature_citation' => true))
         document.update!(external_link: 'https://help.example.com/password')
 
         result = tool.perform(tool_context, query: 'password')
+        repeated_result = tool.perform(tool_context, query: 'password again')
 
-        expect(result).to include('Source: https://help.example.com/password')
+        expect(result).to include('Citation index: 1')
+        expect(repeated_result).to include('Citation index: 1')
+        expect(result).not_to include('https://help.example.com/password')
+        expect(result.scan('Citation index: 1').size).to eq(2)
+        expect(result).not_to include('Citation index: 2')
+        expect(tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY]).to eq(1 => document.id)
+      end
+
+      it 'does not cite document URLs containing credentials' do
+        assistant.update!(config: assistant.config.merge('feature_citation' => true))
+        document.update!(external_link: 'https://user:pass@help.example.com/password')
+
+        result = tool.perform(tool_context, query: 'password')
+
+        expect(result).not_to include('Citation index:')
+        expect(tool_context.state[Captain::Assistant::CITATION_SOURCES_STATE_KEY]).to be_nil
       end
 
       it 'logs tool usage for search' do
@@ -84,7 +134,15 @@ RSpec.describe Captain::Tools::FaqLookupTool, type: :model do
       it 'records retrieved faq ids and document ids into Chatwoot metadata' do
         tool.perform(tool_context, query: 'password reset')
 
-        expect(tool_context.state.dig(:cw_metadata, :faq_ids)).to contain_exactly(response1.id, response2.id)
+        user = create(:user, account: account)
+        user_faq = create(:captain_assistant_response, assistant: assistant, documentable: user, status: :approved)
+        allow(Captain::AssistantResponse).to receive(:nearest_neighbors).and_return(
+          Captain::AssistantResponse.where(id: user_faq.id)
+        )
+        tool.perform(tool_context, query: 'user faq')
+
+        expect(tool_context.state.dig(:cw_metadata, :faq_ids)).to contain_exactly(response1.id, response2.id, user_faq.id)
+        expect(tool_context.state.dig(:cw_metadata, :used_faq_ids)).to contain_exactly(user_faq.id)
         expect(tool_context.state.dig(:cw_metadata, :document_ids)).to contain_exactly(document.id)
       end
 
diff --git a/spec/enterprise/models/captain/agent_session_spec.rb b/spec/enterprise/models/captain/agent_session_spec.rb
index b4306a11e..bd71f069f 100644
--- a/spec/enterprise/models/captain/agent_session_spec.rb
+++ b/spec/enterprise/models/captain/agent_session_spec.rb
@@ -129,10 +129,12 @@ RSpec.describe Captain::AgentSession, type: :model do
   end
 
   describe 'defaults' do
-    it 'defaults faq_ids, document_ids, scenario_ids and run_context' do
+    it 'defaults source ids, scenario ids and run_context' do
       session = create(:captain_agent_session, account: account, assistant: assistant)
 
       expect(session.faq_ids).to eq([])
+      expect(session.used_faq_ids).to eq([])
+      expect(session.cited_document_ids).to eq([])
       expect(session.document_ids).to eq([])
       expect(session.scenario_ids).to eq([])
       expect(session.run_context).to eq({})
diff --git a/spec/enterprise/models/captain/document_spec.rb b/spec/enterprise/models/captain/document_spec.rb
index af6c1cb58..04779dc6b 100644
--- a/spec/enterprise/models/captain/document_spec.rb
+++ b/spec/enterprise/models/captain/document_spec.rb
@@ -15,6 +15,38 @@ RSpec.describe Captain::Document, type: :model do
     end
   end
 
+  describe '#customer_visible_source_url' do
+    let(:document) do
+      build(:captain_document, assistant: assistant, account: account, external_link: 'https://example.com/runbooks')
+    end
+
+    it 'returns URLs that resolve only to public addresses' do
+      allow(Resolv).to receive(:getaddresses).with('example.com').and_return(['93.184.216.34'])
+
+      expect(document.customer_visible_source_url).to eq('https://example.com/runbooks')
+    end
+
+    it 'rejects URLs that resolve to private, loopback, or link-local addresses' do
+      ['10.0.0.5', '127.0.0.1', '169.254.1.1', 'fc00::1', 'fe80::1'].each do |address|
+        allow(Resolv).to receive(:getaddresses).with('example.com').and_return([address])
+
+        expect(document.customer_visible_source_url).to be_nil
+      end
+    end
+
+    it 'rejects URLs with mixed public and private addresses' do
+      allow(Resolv).to receive(:getaddresses).with('example.com').and_return(['93.184.216.34', '10.0.0.5'])
+
+      expect(document.customer_visible_source_url).to be_nil
+    end
+
+    it 'rejects URLs with unresolved hosts' do
+      allow(Resolv).to receive(:getaddresses).with('example.com').and_return([])
+
+      expect(document.customer_visible_source_url).to be_nil
+    end
+  end
+
   describe 'PDF support' do
     let(:pdf_document) do
       doc = build(:captain_document, assistant: assistant, account: account)
diff --git a/spec/enterprise/models/concerns/agentable_spec.rb b/spec/enterprise/models/concerns/agentable_spec.rb
index f2145ff85..c423c51ec 100644
--- a/spec/enterprise/models/concerns/agentable_spec.rb
+++ b/spec/enterprise/models/concerns/agentable_spec.rb
@@ -198,6 +198,19 @@ RSpec.describe Concerns::Agentable do
     it 'returns Captain::ResponseSchema' do
       expect(dummy_instance.send(:agent_response_schema)).to eq(Captain::ResponseSchema)
     end
+
+    it 'defines complete structured response parts with nested citation indexes' do
+      schema = Captain::ResponseSchema.new.to_json_schema[:schema]
+      response_parts = schema.dig(:properties, :response_parts)
+      response_part = response_parts.dig(:items, :properties)
+
+      expect(schema[:required]).to contain_exactly(:response_parts, :reasoning)
+      expect(response_parts).to include(type: 'array', minItems: 1)
+      expect(response_part.dig(:text, :type)).to eq('string')
+      expect(response_part.dig(:citation_indexes, :items, :type)).to eq('integer')
+      expect(response_part.dig(:citation_indexes, :items, :minimum)).to eq(1)
+      expect(schema[:properties]).not_to have_key(:response)
+    end
   end
 
   describe 'required methods' do
diff --git a/spec/enterprise/services/captain/assistant/agent_runner_service_spec.rb b/spec/enterprise/services/captain/assistant/agent_runner_service_spec.rb
index 494d60dbc..093cbccf4 100644
--- a/spec/enterprise/services/captain/assistant/agent_runner_service_spec.rb
+++ b/spec/enterprise/services/captain/assistant/agent_runner_service_spec.rb
@@ -13,7 +13,16 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
   let(:mock_runner) { instance_double(Agents::AgentRunner) }
   let(:mock_agent) { instance_double(Agents::Agent) }
   let(:mock_scenario_agent) { instance_double(Agents::Agent) }
-  let(:mock_result) { instance_double(Agents::RunResult, output: { 'response' => 'Test response' }, context: nil) }
+  let(:mock_result) do
+    instance_double(
+      Agents::RunResult,
+      output: {
+        'response_parts' => [{ 'text' => 'Test response', 'citation_indexes' => [] }],
+        'reasoning' => 'Test reasoning'
+      },
+      context: nil
+    )
+  end
 
   let(:message_history) do
     [
@@ -185,7 +194,13 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
     it 'processes and formats agent result' do
       result = service.generate_response(message_history: message_history)
 
-      expect(result).to eq({ 'response' => 'Test response', 'agent_name' => nil, 'handoff_tool_called' => false })
+      expect(result).to eq({
+                             'response_parts' => [{ 'text' => 'Test response', 'citation_indexes' => [] }],
+                             'response' => 'Test response',
+                             'reasoning' => 'Test reasoning',
+                             'agent_name' => nil,
+                             'handoff_tool_called' => false
+                           })
     end
 
     it 'exposes the raw run result via last_run_result' do
@@ -197,7 +212,14 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
     context 'when handoff tool was called during agent execution' do
       let(:runner_context) { { captain_v2_handoff_tool_called: true } }
       let(:mock_result) do
-        instance_double(Agents::RunResult, output: { 'response' => 'Let me connect you' }, context: runner_context)
+        instance_double(
+          Agents::RunResult,
+          output: {
+            'response_parts' => [{ 'text' => 'Let me connect you', 'citation_indexes' => [] }],
+            'reasoning' => 'A human is needed'
+          },
+          context: runner_context
+        )
       end
 
       it 'includes handoff_tool_called flag in response' do
@@ -205,6 +227,8 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
 
         expect(result).to eq({
                                'response' => 'Let me connect you',
+                               'response_parts' => [{ 'text' => 'Let me connect you', 'citation_indexes' => [] }],
+                               'reasoning' => 'A human is needed',
                                'agent_name' => nil,
                                'handoff_tool_called' => true
                              })
@@ -234,6 +258,7 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
 
         expect(result).to eq({
                                'response' => 'Simple string response',
+                               'response_parts' => [{ 'text' => 'Simple string response', 'citation_indexes' => [] }],
                                'reasoning' => 'Processed by agent',
                                'agent_name' => nil,
                                'handoff_tool_called' => false
@@ -241,6 +266,149 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
       end
     end
 
+    context 'when structured response parts contain invalid values' do
+      let(:assistant) { create(:captain_assistant, account: account, config: { 'feature_citation' => true }) }
+      let(:mock_result) do
+        instance_double(
+          Agents::RunResult,
+          output: {
+            'response_parts' => [
+              { 'text' => '  First part  ', 'citation_indexes' => [2, 2, 0, '1', 'https://model.example/source'] },
+              { 'text' => '   ', 'citation_indexes' => [1] },
+              'invalid',
+              { 'text' => 'Second part', 'citation_indexes' => [1] }
+            ],
+            'reasoning' => 'Test reasoning'
+          },
+          context: nil
+        )
+      end
+
+      it 'keeps valid ordered parts and derives the compatibility response string' do
+        result = service.generate_response(message_history: message_history)
+
+        expect(result['response_parts']).to eq(
+          [
+            { 'text' => 'First part', 'citation_indexes' => [2] },
+            { 'text' => 'Second part', 'citation_indexes' => [1] }
+          ]
+        )
+        expect(result['response']).to eq("First part\n\nSecond part")
+      end
+    end
+
+    context 'when citations are disabled' do
+      let(:mock_result) do
+        instance_double(
+          Agents::RunResult,
+          output: {
+            'response_parts' => [{ 'text' => 'FAQ-backed response', 'citation_indexes' => [1] }],
+            'reasoning' => 'Test reasoning'
+          },
+          context: nil
+        )
+      end
+
+      it 'discards model-provided citation indexes' do
+        result = service.generate_response(message_history: message_history)
+
+        expect(result['response_parts']).to eq(
+          [{ 'text' => 'FAQ-backed response', 'citation_indexes' => [] }]
+        )
+      end
+    end
+
+    context 'when a structured response exceeds the channel limit' do
+      let(:channel_limit_rewrite) do
+        original_model_output = {
+          'response_parts' => [
+            { 'text' => 'The first answer has more detail than this channel can accept.', 'citation_indexes' => [2] },
+            { 'text' => 'The second answer also has more detail than this channel can accept.', 'citation_indexes' => [1] }
+          ],
+          'reasoning' => 'Used two FAQ results'
+        }
+        rewritten_model_output = {
+          'response_parts' => [
+            { 'text' => 'Short first answer.', 'citation_indexes' => [2] },
+            { 'text' => 'Short second answer.', 'citation_indexes' => [1] }
+          ],
+          'reasoning' => 'Shortened both parts'
+        }
+        runner_context = {
+          session_id: "#{account.id}_#{conversation.display_id}",
+          state: { Captain::Assistant::CITATION_SOURCES_STATE_KEY => { 1 => 101, 2 => 202 } },
+          conversation_history: [{ role: :assistant, content: original_model_output }]
+        }
+        runner_messages = [{ role: :assistant, content: original_model_output }]
+
+        {
+          original_run_result: Agents::RunResult.new(output: original_model_output, messages: runner_messages, context: runner_context),
+          rewrite_run_result: Agents::RunResult.new(output: rewritten_model_output, messages: [], context: {}),
+          citation_urls: {
+            1 => 'https://help.example.com/first',
+            2 => 'https://help.example.com/second'
+          },
+          runner_context: runner_context
+        }
+      end
+      let(:mock_result) { channel_limit_rewrite[:original_run_result] }
+
+      before do
+        allow(assistant).to receive(:config).and_return('feature_citation' => true)
+        allow(assistant).to receive(:customer_visible_citation_urls).and_return(channel_limit_rewrite[:citation_urls])
+        allow(Captain::MessageLengthLimit).to receive(:for).with(conversation).and_return(140)
+        allow(mock_runner).to receive(:run).and_return(mock_result, channel_limit_rewrite[:rewrite_run_result])
+      end
+
+      it 'reserves space for rendered citations and restores their original indexes' do
+        original_response_parts = Captain::Assistant::ResponseParts.from_response(mock_result.output)
+        original_customer_message = original_response_parts.customer_message_content(citation_urls: channel_limit_rewrite[:citation_urls])
+        citation_markup_length = original_customer_message.length - original_response_parts.plain_text.length
+        response_text_limit = 140 - citation_markup_length
+
+        expect(original_response_parts.plain_text.length).to be < 140
+        expect(original_customer_message.length).to be > 140
+
+        result = service.generate_response(message_history: message_history)
+
+        expect(result['response_parts']).to eq(
+          [
+            { 'text' => 'Short first answer.', 'citation_indexes' => [2] },
+            { 'text' => 'Short second answer.', 'citation_indexes' => [1] }
+          ]
+        )
+        expect(channel_limit_rewrite[:runner_context][:conversation_history].last[:content]['response_parts']).to eq(result['response_parts'])
+        expect(
+          Captain::Assistant::ResponseParts.from_response(result).customer_message_content(
+            citation_urls: channel_limit_rewrite[:citation_urls]
+          ).length
+        ).to be <= 140
+        expect(mock_runner).to have_received(:run).with(
+          include(
+            "must be at most #{response_text_limit} characters",
+            'Keep the same number and order of response parts',
+            '"citation_indexes":[2]',
+            '"citation_indexes":[1]'
+          ),
+          context: hash_including(state: channel_limit_rewrite[:runner_context][:state]),
+          max_turns: 1
+        )
+        expect(mock_runner).not_to have_received(:run).with(include('help.example.com'), any_args)
+      end
+
+      it 'rejects a rewrite that changes the response part citation order' do
+        channel_limit_rewrite[:rewrite_run_result].output['response_parts'].reverse!
+        allow(ChatwootExceptionTracker).to receive(:new).and_return(
+          instance_double(ChatwootExceptionTracker, capture_exception: true)
+        )
+
+        result = service.generate_response(message_history: message_history)
+
+        expect(result['response']).to eq('conversation_handoff')
+        expect(result['reasoning']).to eq('Error occurred: Captain response rewrite changed the response part citation order')
+      end
+    end
+
     context 'when an error occurs' do
       let(:error) { StandardError.new('Test error') }
 
@@ -258,6 +426,7 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
 
         expect(result).to eq({
                                'response' => 'conversation_handoff',
+                               'response_parts' => [{ 'text' => 'conversation_handoff', 'citation_indexes' => [] }],
                                'reasoning' => 'Error occurred: Test error',
                                'error' => true,
                                'error_reason' => 'standard_error',
@@ -288,6 +457,7 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
 
           expect(result).to eq({
                                  'response' => 'conversation_handoff',
+                                 'response_parts' => [{ 'text' => 'conversation_handoff', 'citation_indexes' => [] }],
                                  'reasoning' => 'Error occurred: Test error',
                                  'error' => true,
                                  'error_reason' => 'standard_error',
@@ -314,6 +484,7 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
 
           expect(result).to eq({
                                  'response' => 'conversation_handoff',
+                                 'response_parts' => [{ 'text' => 'conversation_handoff', 'citation_indexes' => [] }],
                                  'reasoning' => 'Error occurred: Test error',
                                  'error' => true,
                                  'error_reason' => 'standard_error',
@@ -406,6 +577,18 @@ RSpec.describe Captain::Assistant::AgentRunnerService do
       expect(result).to eq('Hash response')
     end
 
+    it 'joins structured response parts from hash content' do
+      content = {
+        'response_parts' => [
+          { 'text' => 'First response part', 'citation_indexes' => [1] },
+          { 'text' => 'Second response part', 'citation_indexes' => [] }
+        ]
+      }
+      result = service.send(:extract_text_from_content, content)
+
+      expect(result).to eq("First response part\n\nSecond response part")
+    end
+
     it 'extracts text from multimodal array content' do
       content = [
         { type: 'text', text: 'First part' },
diff --git a/spec/enterprise/services/captain/assistant/session_capture_service_spec.rb b/spec/enterprise/services/captain/assistant/session_capture_service_spec.rb
index daf38c8d6..239053d6f 100644
--- a/spec/enterprise/services/captain/assistant/session_capture_service_spec.rb
+++ b/spec/enterprise/services/captain/assistant/session_capture_service_spec.rb
@@ -49,6 +49,7 @@ RSpec.describe Captain::Assistant::SessionCaptureService do
 
   before do
     allow(assistant).to receive(:agent_model).and_return('gpt-5.2')
+    allow(Resolv).to receive(:getaddresses).and_return(['93.184.216.34'])
   end
 
   describe '#capture' do
@@ -98,6 +99,8 @@ RSpec.describe Captain::Assistant::SessionCaptureService do
         llm_model: 'openai-gpt-5.2',
         credits_consumed: 1.0,
         faq_ids: [11, 12],
+        used_faq_ids: [],
+        cited_document_ids: [],
         document_ids: [5],
         scenario_ids: [],
         user_id: nil
@@ -149,10 +152,56 @@ RSpec.describe Captain::Assistant::SessionCaptureService do
 
       expect(session.result).to eq(result_message)
       expect(session.faq_ids).to eq([])
+      expect(session.used_faq_ids).to eq([])
+      expect(session.cited_document_ids).to eq([])
       expect(session.document_ids).to eq([])
       expect(session.run_context).to eq([])
     end
 
+    it 'stores only selected customer-visible document citations' do
+      cited_document = create(:captain_document, assistant: assistant, external_link: 'https://help.example.com/reset-password')
+      cited_faq = create(:captain_assistant_response, assistant: assistant, documentable: cited_document)
+      retrieved_document = create(:captain_document, assistant: assistant, external_link: 'https://help.example.com/change-email')
+      retrieved_faq = create(:captain_assistant_response, assistant: assistant, documentable: retrieved_document)
+      user = create(:user, account: account)
+      used_faq = create(:captain_assistant_response, assistant: assistant, documentable: user, status: :approved)
+      assistant.update!(config: assistant.config.merge('feature_citation' => true))
+      run_context[:state] = {
+        :cw_metadata => {
+          faq_ids: [cited_faq.id, retrieved_faq.id, used_faq.id],
+          used_faq_ids: [used_faq.id],
+          document_ids: [cited_document.id, retrieved_document.id]
+        },
+        Captain::Assistant::CITATION_SOURCES_STATE_KEY => { 1 => cited_document.id, 2 => retrieved_document.id }
+      }
+      run_result.output = {
+        'response_parts' => [{ 'text' => 'Reset your password from settings.', 'citation_indexes' => [1] }],
+        'reasoning' => 'Used the password FAQ'
+      }
+      result_message.update!(
+        additional_attributes: {
+          Captain::Assistant::ResponseParts::MESSAGE_ATTRIBUTE_KEY => run_result.output['response_parts']
+        }
+      )
+
+      session = service.capture!
+
+      expect(session.faq_ids).to contain_exactly(cited_faq.id, retrieved_faq.id, used_faq.id)
+      expect(session.used_faq_ids).to eq([used_faq.id])
+      expect(session.cited_document_ids).to eq([cited_document.id])
+    end
+
+    it 'does not store citations when citations are disabled' do
+      document = create(:captain_document, assistant: assistant, external_link: 'https://help.example.com/reset-password')
+      run_context[:state][Captain::Assistant::CITATION_SOURCES_STATE_KEY] = { 1 => document.id }
+      run_result.output = {
+        'response_parts' => [{ 'text' => 'Reset your password from settings.', 'citation_indexes' => [1] }],
+        'reasoning' => 'Used the password FAQ'
+      }
+
+      expect(service.capture!.cited_document_ids).to eq([])
+    end
+
     it 'extracts every scenario that authored a message in the current turn' do
       first_scenario = create(:captain_scenario, assistant: assistant, account: account)
       second_scenario = create(:captain_scenario, assistant: assistant, account: account)