Reading this from the perspective of someone writing an external integration against the new surface. BaseSubagentCallable is the convenience base the API steers implementations to (:23-29, and subagent.py:199-201 says so explicitly). It does not override DurableCallable#reconciler(), so every sub-agent callable inherits the null default at DurableCallable.java:74.

durableExecute selects the reconcile state machine only when reconciler() is non-null (RunnerContextImpl.java:267-275), and durableExecuteAsync, which is the path SubagentSetup.call takes, gates identically (JavaRunnerContextImpl.java:62-70). Either way sub-agent calls land on durableExecuteCompletionOnly. On that path appendPendingCall is never reached: its only callers are inside durableExecuteWithReconcile (:555, :561). A crash between "external agent invoked" and "result persisted" therefore leaves no record at all, replay misses the cache, and call() re-invokes the external agent.

Grepping the new surface, reconcil does not appear anywhere under api/.../subagent/, in the e2e tests, or in the runtime sub-agent tests. Python surfaces the field (subagent.py:82) and forwards it (:184), but wires None and no test asserts the forwarding. The recovery tests seed only terminal CallResults (SubagentIdentityRecoveryTest.java:105-108,171-178), so the pending path has no sub-agent coverage on either side.

Concretely: what does an integration author write today to get reconcile-before-resend, and is there anything on this surface that would tell them the option exists? One shape that would make the choice visible, in case it is useful: BaseSubagentCallable taking the reconciler as a constructor argument, so passing null is something the author decided rather than a default they never saw.

BaseSubagentCallable doesn't shield any DurableCallable convention — it inherits reconciler() as-is (default null) and only simplifies boilerplate (getId, getResultClass, call with exception capture). Without a reconciler, a crash between invocation and persistence causes replay to re-invoke the external agent — this is expected, identical to any DurableCallable, and typically fine for read-only or idempotent sub-agents. If side effects must not be replayed, the author should provide a reconciler per the existing DurableCallable contract.

The question is whether to surface this option more visibly. Here are three options:

1. Add reconcilerInternal to BaseSubagentCallable — simplest, but just restates a convention DurableCallable already defines.
2. Remove BaseSubagentCallable — if the abstraction confuses developers into thinking it shields DurableCallable contracts, maybe we should remove it makes them implement DurableCallable directly.
3. Default reconciler + abstract querySuccess() — if the typical pattern is if (querySuccess()) return result; else return callInternal(), we can provide a default reconciler() that uses it. Enables the pending/reconcile path; developers can still override.

Which do you prefer?

result is typed Object, BaseSubagentCallable.getResultClass() pins the durable result class to Result.class (BaseSubagentCallable.java:47-48), and recovery re-binds through the plain OBJECT_MAPPER at RunnerContextImpl.java:516, which is constructed with no polymorphic typing (:67-68).

I round-tripped a small POJO payload through this Result with writeValueAsString / readValue(s, Result.class):

serialized: {"success":true,"result":{"verdict":"approve","score":7},"errorMessage":null}
payload class after replay: java.util.LinkedHashMap
ClassCastException: class java.util.LinkedHashMap cannot be cast to class Review

So getResult() hands back the author's type on the first execution and a LinkedHashMap after a failover replay. The shipped example casts at ExternalSubagentAgent.java:52 (((List<?>) result.getResult()).get(0)) and survives only because JSON arrays bind to ArrayList. Every payload in the suite is a String or a List<String> (MockExternalSubagentSetup.java:92, SubagentIdentityRecoveryTest.java:108), so nothing currently exercises the shape that breaks.

Python does not diverge here. Its durable payload goes through cloudpickle (flink_runner_context.py:430,473), which preserves the type, so this is also a Java/Python semantic gap on new public API that AGENTS.md asks to keep aligned.

What should getResult() return after a replay when the sub-agent returned a record or a POJO? A couple of routes, in case they help: making Result generic and threading the payload class through getResultClass(), or keeping the field opaque and adding getResult(Class<T>) backed by OBJECT_MAPPER.convertValue. Either way a test with a non-String, non-collection payload would pin the behavior.

Thanks for catching this — it's a real oversight. I'm currently working on the cross-language sub-agent invocation design and ran into the same issue there.

The plan is to add getResult(Class<T>) backed by OBJECT_MAPPER.convertValue. This unifies all three paths where result can appear as a LinkedHashMap: durable recovery (Jackson JSON deserialization), cross-language sub-agent calls (pemja conversion), and first execution (direct cast, no conversion needed). convertValue handles the Map→POJO conversion uniformly regardless of the source.

One known limitation: for generic collection payloads like List, both recovery and cross-language paths leave result as ArrayList — getResult(List.class) only returns List, losing element types. A getResult(TypeReference<T>) overload can be added later if type-safe collections are needed.

error(Exception) stores the full stack trace as errorMessage, and BaseSubagentCallable.call() captures every exception into it rather than throwing (BaseSubagentCallable.java:52-58). Two things follow downstream.

The durable layer sees a normal completion: durableExecuteCompletionOnly calls recordDurableCompletion with a null exception (RunnerContextImpl.java:329), and CallResult's status is derived as exceptionPayload == null ? SUCCEEDED : FAILED (CallResult.java:100). So isFailure() (:177-179) is false for every failed sub-agent call, and getCurrentCallResultFields() reports "SUCCEEDED" (RunnerContextImpl.java:490). Anything keyed on durable-call status reads sub-agent failures as successes.

The trace is also uncapped, and recordCallCompletion persists the ActionState immediately to the configured store (RunnerContextImpl.java:827-837, backed by KafkaActionStateStore / FlussActionStateStore). A flapping external agent writes a multi-KB string per failure into durable storage.

Worth capping what gets persisted, say the message plus the top N frames, and keeping the full trace to the log? And is collapsing a captured failure into a SUCCEEDED CallResult deliberate, or should the two stay distinguishable at that layer?

This is by design. As discussed in #909, "sub-agent implementations should intercept internal exceptions and populate Result, without directly exposing them to the caller." The intent is to prevent sub-agent exceptions from directly affecting the caller while avoiding the need for every caller to write its own try-catch. When an exception occurs, the persisted Result carries the failure info; the caller always receives a failed Result rather than the exception itself, so Action behavior stays consistent between first run and replay.

On durable-layer status (SUCCEEDED for failed sub-agent calls): This is deliberate. SUCCEEDED at the durable layer means "the durable call completed and returned a Result" — the sub-agent's success or failure is carried inside the Result payload (result.isFailure()), which is a separate concern from durable execution status. On replay, the caller reads the same failed Result from the persisted resultPayload, so processing behavior matches the first run.

On uncapped stack trace: The current text-based exception (full stack trace as errorMessage) was chosen to ensure cross-language transmission. I also felt the full stack trace is more helpful for problem analysis, and since exceptions are typically low-frequency events, storage savings wasn't a primary concern. While I also agree that for the caller the stack trace isn't critical — it's sufficient to find it in logs. I can align with the current convention: persist only exception type + message, and log the full stack trace.

If we were to switch to using DurableExecutionException directly, besides the cross-language issue, there's also a pre-existing problem where the recovered exception (RuntimeException from toException()) differs from the original exception type on first execution — catch blocks targeting specific exception types would no longer match after recovery. This is unrelated to sub-agent; we can discuss it separately.

Does the by-design approach (capturing into Result rather than throwing) seem reasonable, or do you prefer requiring callers to try-catch?