feat: add completion_mode: :auto for simplified multi-turn semantics

Adds an opt-in auto-return mode where println presence controls the
multi-turn loop: println = exploration (continue), no println = answer
(return last expression). This eliminates the return/fail interaction
rules that were the #1 model failure mode in benchmarks.

Key design decisions:
- completion_mode: :explicit (default) preserves all existing behavior
- completion_mode: :auto uses a simpler prompt (33% smaller) with one
  rule instead of three
- Auto-return is disabled when a plan is present — plan agents use the
  regular multi_turn_journal prompt with explicit return/step-done
- Plan always auto-enables journaling for progress checklist rendering
- return/fail still work as escape hatches in auto mode

Benchmark results (gemini-3.1-flash-lite-preview, 3 runs of 25 tests):
- auto_return: 97.3% avg pass rate, 2214 avg tokens
- multi_turn:  94.7% avg pass rate, 2794 avg tokens
- 21% fewer tokens, 15% faster, same or better accuracy

Also includes coordinator + worker delegation scripts for testing
Claude Code-style agent composition patterns.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: andreasronge

demo/lib/ptc_demo/agent.ex

@@ -547,6 +547,14 @@ defmodule PtcDemo.Agent do
       thinking: thinking
     ]
 
+    # Add completion_mode for auto_return prompt profile
+    base_opts =
+      if prompt_profile == :auto_return do
+        Keyword.put(base_opts, :completion_mode, :auto)
+      else
+        base_opts
+      end
+
     # Add plan and enable journaling when plan is present
     base_opts =
       if plan do

demo/lib/ptc_demo/prompts.ex

@@ -53,7 +53,8 @@ defmodule PtcDemo.Prompts do
   def get(profile \\ :single_shot)
 
   # Delegate standard prompts to the library
-  def get(profile) when profile in [:single_shot, :multi_turn, :base, :addon_memory] do
+  def get(profile)
+      when profile in [:single_shot, :multi_turn, :auto_return, :base, :addon_memory] do
     LibLanguageSpec.get(profile)
   end
 
@@ -75,7 +76,8 @@ defmodule PtcDemo.Prompts do
   def list do
     [
       {:single_shot, "Base language reference for single-turn queries"},
-      {:multi_turn, "Base + memory addon for multi-turn conversations"}
+      {:multi_turn, "Base + memory addon for multi-turn conversations"},
+      {:auto_return, "Base + auto-return (println to explore, last expr to answer)"}
     ]
   end
 
@@ -102,7 +104,7 @@ defmodule PtcDemo.Prompts do
       {:ok, :single_shot}
 
       iex> PtcDemo.Prompts.validate_profile("invalid")
-      {:error, "Unknown prompt profile 'invalid'. Valid: single_shot, multi_turn"}
+      {:error, "Unknown prompt profile 'invalid'. Valid: single_shot, multi_turn, auto_return"}
 
   """
   @spec validate_profile(String.t()) :: {:ok, atom()} | {:error, String.t()}

demo/scripts/coordinator_test.exs

@@ -1,18 +1,17 @@
-# Coordinator + Worker delegation test
+# Coordinator + Worker delegation test (Claude Code style)
 #
-# Tests whether a coordinator agent can decompose a complex task
-# and delegate sub-questions to a worker agent — similar to how
-# Claude Code spawns sub-agents.
+# The coordinator has NO data — only an analyst tool (worker sub-agent).
+# It must: 1) decide what to ask, 2) call the analyst, 3) inspect results,
+# 4) decide if more info is needed or assemble the answer.
 #
-# The coordinator has NO data — it can only delegate to the worker.
-# The worker has all datasets and answers focused questions.
+# Uses completion_mode: :auto — println means "exploring", no println means "done".
 #
 # Usage:
 #   cd demo && mix run scripts/coordinator_test.exs
 #
 # Set OPENROUTER_API_KEY in .env or environment.
 
-alias PtcDemo.{CLIBase, SampleData, SearchTool}
+alias PtcDemo.{CLIBase, SampleData}
 alias PtcRunner.SubAgent
 
 CLIBase.load_dotenv()
@@ -21,7 +20,7 @@ CLIBase.ensure_api_key!()
 model = System.get_env("COORDINATOR_MODEL") || "openrouter:google/gemini-3.1-flash-lite-preview"
 timeout = 60_000
 
-IO.puts("=== Coordinator + Worker Delegation Test ===")
+IO.puts("=== Coordinator + Worker Test (auto-return) ===")
 IO.puts("Model: #{model}\n")
 
 # --- LLM callback ---
@@ -41,7 +40,7 @@ llm = fn %{system: system, messages: messages} ->
   end
 end
 
-# --- Datasets (only for the worker) ---
+# --- Datasets (only the worker sees these) ---
 
 datasets = %{
   "products" => SampleData.products(),
@@ -50,19 +49,15 @@ datasets = %{
   "expenses" => SampleData.expenses()
 }
 
-# --- Worker: a function tool that internally runs a SubAgent ---
-# This is the key pattern: the worker is a plain function tool from
-# the coordinator's perspective, but internally spawns a full SubAgent
-# with its own LLM call and data access.
+# --- Worker: function tool that spawns a SubAgent ---
 
 worker_agent =
   SubAgent.new(
     prompt: "{{question}}",
     signature: "(question :string) -> :any",
     context_descriptions: SampleData.context_descriptions(),
     system_prompt: %{
-      prefix:
-        "You are a data analyst. Answer the question precisely using the datasets provided.",
+      prefix: "You are a data analyst. Answer the question precisely using the datasets.",
       language_spec: :single_shot
     },
     max_turns: 1
@@ -78,35 +73,32 @@ analyst_tool = fn %{"question" => question} ->
   end
 end
 
-# --- Coordinator agent: decomposes and delegates ---
-# The coordinator has NO datasets — it can only call the analyst tool.
-# It must break the problem into sub-questions and combine results.
+# --- Coordinator: auto-return mode, no data, only the analyst tool ---
 
 coordinator =
   SubAgent.new(
     prompt: "{{mission}}",
     signature: "(mission :string) -> :map",
+    completion_mode: :auto,
     tools: %{
       "analyst" =>
         {analyst_tool,
          signature: "(question :string) -> :any",
          description:
-           "Answers a data analysis question. Delegates to a sub-agent with full dataset access. " <>
-             "Available datasets: employees (200 records with id, department, salary, remote, level), " <>
-             "expenses (800 records with employee_id, amount, category, status), " <>
-             "orders (1000 records with customer_id, total, created_at, status), " <>
-             "products (500 records with category, price, stock). " <>
+           "Answers a data analysis question using datasets not available to you. " <>
+             "Datasets: employees (id, department, salary, remote, level), " <>
+             "expenses (employee_id, amount, category, status), " <>
+             "orders (customer_id, total, created_at, status), " <>
+             "products (category, price, stock). " <>
              "Ask focused questions that return simple values (numbers, lists, maps)."}
     },
     system_prompt: %{
       prefix: """
-      You are a coordinator that breaks down complex data analysis tasks.
-      You have an analyst tool that can query datasets and return results.
-      Break the mission into focused sub-questions, call the analyst for each,
-      then combine the results into the final answer.
-      You do NOT have direct access to data — you must use the analyst tool.
+      You are a coordinator. You have NO direct data access.
+      Use the analyst tool to query datasets. Use println to inspect results.
+      When you have all the data you need, write your final answer as the last expression (no println).
       """,
-      language_spec: :multi_turn
+      language_spec: :auto_return
     },
     max_turns: 6,
     timeout: 120_000,
@@ -120,9 +112,7 @@ tests = [
     name: "Remote vs Office expenses",
     mission:
       "Compare average expense amounts between remote and office employees. " <>
-        "Ask the analyst for the average expense amount for remote employees, " <>
-        "then ask for the average expense amount for office employees. " <>
-        "Return a map with :remote_avg, :office_avg, and :remote_higher (boolean).",
+        "Return a map with :remote_avg (number), :office_avg (number), and :remote_higher (boolean).",
     check: fn result ->
       is_map(result) and
         Map.has_key?(result, :remote_avg) and
@@ -142,6 +132,17 @@ tests = [
         Map.has_key?(result, :silver) and
         Map.has_key?(result, :gold)
     end
+  },
+  %{
+    name: "Department with highest avg salary",
+    mission:
+      "Find which department has the highest average salary. " <>
+        "Return a map with :department (string) and :avg_salary (number).",
+    check: fn result ->
+      is_map(result) and
+        Map.has_key?(result, :department) and
+        Map.has_key?(result, :avg_salary)
+    end
   }
 ]
 
@@ -159,10 +160,12 @@ for test <- tests do
     {:ok, step} ->
       SubAgent.Debug.print_trace(step, raw: true, usage: true)
       result = step.return
+      turns = length(step.turns)
 
       passed = test.check.(result)
       status = if passed, do: "PASS", else: "FAIL"
       IO.puts("\nResult: #{inspect(result, limit: 10, pretty: true)}")
+      IO.puts("Turns: #{turns}")
       IO.puts("#{status}\n")
 
     {:error, step} ->