new dict-based final answer format

Author: alexzhang13

AGENTS.md

@@ -173,7 +173,7 @@ Environments must provide these globals to executed code:
 - `llm_query_batched(prompts, model=None)`: Batched plain LM completions
 - `rlm_query(prompt, model=None)`: Recursive child RLM call (own REPL + iteration). Falls back to `llm_query` at max depth.
 - `rlm_query_batched(prompts, model=None)`: Batched recursive child RLM calls
-- `FINAL_VAR(variable_name)`: For returning final answers
+- `answer`: A dict (`{"content": "", "ready": False}`); the model sets `answer["content"]` and `answer["ready"] = True` to return a final answer. The env surfaces the content on `REPLResult.final_answer` once `ready` flips truthy.
 - `SHOW_VARS()`: For listing available variables
 
 ### Example Structure
@@ -208,7 +208,7 @@ class MyEnvironment(NonIsolatedEnv):
 - Environment works with basic RLM completion calls
 - `cleanup()` properly releases all resources
 - Sub-LM calls work via `llm_query()` and `rlm_query()`
-- Reserved names (`llm_query`, `rlm_query`, `context`, `history`, `FINAL_VAR`, `SHOW_VARS`) are restored after each execution
+- Reserved names (`llm_query`, `rlm_query`, `context`, `history`, `answer`, `SHOW_VARS`) are restored after each execution
 
 ## Architecture: Environment ↔ LM Handler Communication
 

docs/api/rlm.md

@@ -255,12 +255,15 @@ Override the default RLM system prompt. The default prompt instructs the LM on:
 - How to use the `context` variable
 - How to call `llm_query()` / `llm_query_batched()` for plain LM calls
 - How to call `rlm_query()` / `rlm_query_batched()` for recursive sub-calls
-- How to signal completion with `FINAL()` or `FINAL_VAR()`
+- How to signal completion by setting `answer["content"]` and `answer["ready"] = True`
 
 ```python
 custom_prompt = """You are a data analysis expert.
 Use the REPL to analyze the context variable.
-When done, output FINAL(your answer)."""
+When done, run a ```repl``` block that does:
+    answer["content"] = "your final answer here"
+    answer["ready"] = True
+"""
 
 rlm = RLM(..., custom_system_prompt=custom_prompt)
 ```
@@ -372,7 +375,7 @@ custom_tools = {
 }
 ```
 
-Reserved names (`llm_query`, `rlm_query`, `context`, `history`, `FINAL_VAR`, `SHOW_VARS`, and their batched variants) cannot be used as tool names.
+Reserved names (`llm_query`, `rlm_query`, `context`, `history`, `answer`, `SHOW_VARS`, and their batched variants) cannot be used as tool names.
 
 ---
 
@@ -550,7 +553,7 @@ The following functions are available to model-generated code inside the REPL:
 | `llm_query_batched(prompts, model=None)` | Multiple plain LM completions concurrently. |
 | `rlm_query(prompt, model=None)` | Spawn a child RLM with its own REPL for deeper thinking. Falls back to `llm_query` at max depth. |
 | `rlm_query_batched(prompts, model=None)` | Spawn multiple child RLMs. Falls back to `llm_query_batched` at max depth. |
-| `FINAL_VAR(variable_name)` | Return a REPL variable as the final answer. |
+| `answer` | A dict (`{"content": "", "ready": False}`). Set `answer["content"]` to your final answer and `answer["ready"] = True` to terminate the run. |
 | `SHOW_VARS()` | List all user-created variables in the REPL. |
 | `print(...)` | Print output visible to the model in the next iteration. |
 
@@ -570,7 +573,7 @@ rlm = RLM(backend="unknown")
 # Raises: ValueError: Unknown backend: unknown
 ```
 
-If the RLM exhausts `max_iterations` without finding a `FINAL()` / `FINAL_VAR()` answer, it prompts the LM one more time to provide a final answer based on the conversation history.
+If the RLM exhausts `max_iterations` without the model setting `answer["ready"] = True`, it prompts the LM one more time to provide a final answer based on the conversation history.
 
 RLM raises explicit exceptions when limits are exceeded:
 

docs/architecture.md

@@ -37,7 +37,7 @@ An RLM completion involves three cooperating pieces:
 │     b. Extract ```repl``` code blocks from response            │
 │     c. Execute code in LocalREPL                               │
 │     d. Append stdout/stderr to message history                 │
-│     e. Repeat until FINAL_VAR / FINAL or limits exceeded       │
+│     e. Repeat until answer["ready"] is True or limits exceeded │
 │  4. Tear down handler and environment                          │
 └────────────────────────────────────────────────────────────────┘
 ```
@@ -139,7 +139,6 @@ globals (shared across all executions):
 ├── llm_query_batched() → batched plain LM calls
 ├── rlm_query()         → recursive RLM sub-call (or fallback to llm_query)
 ├── rlm_query_batched() → batched recursive sub-calls
-├── FINAL_VAR()         → mark a variable as the final answer
 ├── SHOW_VARS()         → list user-created variables
 └── <custom_tools>      → user-provided callable tools
 
@@ -148,6 +147,7 @@ locals (accumulates user variables):
 ├── context_0           → first context payload
 ├── context_1, …        → additional contexts (persistent mode)
 ├── history             → conversation history (persistent/compaction mode)
+├── answer              → {"content": "", "ready": False}; set ready=True to finish
 └── <user variables>    → anything created by model code
 ```
 
@@ -333,13 +333,13 @@ RLM (depth=0)
  │       │           │   │
  │       │           │   └─ llm_query() → TCP to Handler #2 → LM API → response
  │       │           │
- │       │           ├─ Child iteration 2: LM calls FINAL_VAR(result)
+ │       │           ├─ Child iteration 2: LM sets answer["content"]=result, answer["ready"]=True
  │       │           │
  │       │           └─ Returns RLMChatCompletion to parent
  │       │
- │       └─ answer = child_completion.response
+ │       └─ child_response = child_completion.response
  │
- ├─ Iteration 2: LM uses answer, calls FINAL_VAR(final)
+ ├─ Iteration 2: LM uses child_response, sets answer["content"]=final, answer["ready"]=True
  │
  ├─ LMHandler #1 stops
  └─ Returns RLMChatCompletion to user

examples/compaction_example.py

@@ -56,7 +56,7 @@
     "Step 4: Compute and print the mean, median, min, max, and standard deviation "
     "of `data_b`. Store the mean as `mean_b`.\n\n"
     "Step 5: You previously computed `mean_a` and `mean_b`. "
-    "Compute final_answer = round(mean_a + mean_b, 2) and call FINAL_VAR(final_answer)."
+    "Compute final_value = round(mean_a + mean_b, 2), then set answer['content'] = final_value and answer['ready'] = True."
 )
 
 result = rlm.completion(prompt, root_prompt=prompt)

examples/compaction_history_retrieval_example.py

@@ -52,8 +52,8 @@
     "Step 6: Compute the standard deviation of each group. Print all four. "
     "Store as `s1`, `s2`, `s3`, `s4`.\n\n"
     "Step 7: You previously computed four means and four standard deviations. "
-    "Compute final_answer = round((m1 + m2 + m3 + m4) / (s1 + s2 + s3 + s4), 4). "
-    "Print the full equation with values and call FINAL_VAR(final_answer)."
+    "Compute final_value = round((m1 + m2 + m3 + m4) / (s1 + s2 + s3 + s4), 4). "
+    "Print the full equation with values, then set answer['content'] = final_value and answer['ready'] = True."
 )
 
 result = rlm.completion(prompt, root_prompt=prompt)

examples/daytona_repl_example.py

@@ -58,9 +58,8 @@ def main():
             print("Executed: print(x * 2)")
             print(f"Stdout: {result.stdout.strip()}")
 
-            result = repl.execute_code("answer = 42")
-            result = repl.execute_code('print(FINAL_VAR("answer"))')
-            print(f"FINAL_VAR('answer'): {result.stdout.strip()}")
+            result = repl.execute_code('answer["content"] = 42\nanswer["ready"] = True')
+            print(f"answer-dict final answer: {result.final_answer!r}")
 
         # Example 2: With LLM handler
         print("\n[2] Code execution with LLM handler")

examples/depth_metadata_example.py

@@ -107,7 +107,7 @@ def main():
     prompt = (
         "Use rlm_query() to ask the sub-model: 'What are the first 5 prime numbers? "
         "Reply with just the numbers separated by commas.' "
-        "Store the response in a variable called 'primes', then return it with FINAL_VAR('primes')."
+        "Store the response in a variable called 'primes', then set answer['content'] = primes and answer['ready'] = True."
     )
 
     print("Prompt:", prompt)

examples/logger_example.py

@@ -29,7 +29,7 @@
     verbose=True,
 )
 
-prompt = "Compute the sum 1 + 2 + 3 + 4 + 5 and print the result using a REPL block, then return it with FINAL_VAR."
+prompt = "Compute the sum 1 + 2 + 3 + 4 + 5 and print the result using a REPL block, then set answer['content'] to the sum and answer['ready'] = True."
 result = rlm.completion(prompt)
 
 print("Response:", result.response)

examples/modal_repl_example.py

@@ -53,9 +53,8 @@ def main():
         print("Executed: print(x * 2)")
         print(f"Stdout: {result.stdout.strip()}")
 
-        result = repl.execute_code("answer = 42")
-        result = repl.execute_code('print(FINAL_VAR("answer"))')
-        print(f"FINAL_VAR('answer'): {result.stdout.strip()}")
+        result = repl.execute_code('answer["content"] = 42\nanswer["ready"] = True')
+        print(f"answer-dict final answer: {result.final_answer!r}")
 
     # Example 2: With LLM handler
     print("\n[2] Code execution with LLM handler")

examples/rlm_query_batched_example.py

@@ -106,8 +106,8 @@ def main():
         "  1. 'What are the first 5 prime numbers? Reply with just the numbers.'\n"
         "  2. 'What are the first 5 even numbers? Reply with just the numbers.'\n"
         "  3. 'What are the first 5 square numbers? Reply with just the numbers.'\n"
-        "Store the list of responses in a variable called 'answers', "
-        "then return it with FINAL_VAR(answers)."
+        "Store the list of responses in a variable called 'responses', "
+        "then set answer['content'] = responses and answer['ready'] = True."
     )
 
     print("Prompt:", prompt)