4a46e7b fix(subagents): attribute shutdown cancellations · zut

M docs/subagents.md +1 -1


@@ -115,7 +115,7 @@ During an active delegated turn, interactive mode shows compact rows beside the
115	115
116	116		The worker and supervisor communicate over newline-delimited JSON. Current messages use version `1` envelopes with `version`, `message_id`, `agent_id`, `turn_id`, `timestamp`, and `payload`. Unknown event names and payload fields are retained. Only versioned JSONL envelopes are accepted on the worker protocol.
117	117
118		-	A completed worker emits a `turn.result` event and writes `result.json`. The host then injects `[auto-subagents update]`; that completion update, rather than polling or inspecting state, is the signal for the primary to continue. The inline output is bounded; after that update, inspect the full session through the stable references:
	118	+	A completed worker emits a `turn.result` event and writes `result.json`. Intentional cancellation records `shutdown_origin` as `targeted`, `session`, `deadline`, or `process`; manager updates describe that cancellation instead of reporting the worker as generically failed with `context canceled`. The host then injects `[auto-subagents update]`; that completion update, rather than polling or inspecting state, is the signal for the primary to continue. The inline output is bounded; after that update, inspect the full session through the stable references:
119	119
120	120		If a provider rejects a child request because its payload or context window is too large, the worker compacts its persisted transcript and continues the same request once. If compaction or that retry cannot fit, the result uses error code `context_limit` and directs the caller to narrow the task or reduce gathered context; it does not include the provider's raw request error.
121	121


@@ -115,7 +115,7 @@ During an active delegated turn, interactive mode shows compact rows beside the
115			115
116		The worker and supervisor communicate over newline-delimited JSON. Current messages use version `1` envelopes with `version`, `message_id`, `agent_id`, `turn_id`, `timestamp`, and `payload`. Unknown event names and payload fields are retained. Only versioned JSONL envelopes are accepted on the worker protocol.	116		The worker and supervisor communicate over newline-delimited JSON. Current messages use version `1` envelopes with `version`, `message_id`, `agent_id`, `turn_id`, `timestamp`, and `payload`. Unknown event names and payload fields are retained. Only versioned JSONL envelopes are accepted on the worker protocol.
117			117
118	-	A completed worker emits a `turn.result` event and writes `result.json`. The host then injects `[auto-subagents update]`; that completion update, rather than polling or inspecting state, is the signal for the primary to continue. The inline output is bounded; after that update, inspect the full session through the stable references:	118	+	A completed worker emits a `turn.result` event and writes `result.json`. Intentional cancellation records `shutdown_origin` as `targeted`, `session`, `deadline`, or `process`; manager updates describe that cancellation instead of reporting the worker as generically failed with `context canceled`. The host then injects `[auto-subagents update]`; that completion update, rather than polling or inspecting state, is the signal for the primary to continue. The inline output is bounded; after that update, inspect the full session through the stable references:
119			119
120		If a provider rejects a child request because its payload or context window is too large, the worker compacts its persisted transcript and continues the same request once. If compaction or that retry cannot fit, the result uses error code `context_limit` and directs the caller to narrow the task or reduce gathered context; it does not include the provider's raw request error.	120		If a provider rejects a child request because its payload or context window is too large, the worker compacts its persisted transcript and continues the same request once. If compaction or that retry cannot fit, the result uses error code `context_limit` and directs the caller to narrow the task or reduce gathered context; it does not include the provider's raw request error.
121			121

M packages/agent/modes/auto_subagents_test.go +5 -2


@@ -158,8 +158,11 @@ func TestTrackStoppedSubagentWorkerDeliversTerminalUpdate(t *testing.T) {
158	158		if !strings.Contains(update, "task: investigate the stuck worker") {
159	159		t.Fatalf("stop update missing task: %q", update)
160	160		}
161		-	if !strings.Contains(update, "status: killed") {
162		-	t.Fatalf("stop update missing killed status: %q", update)
	161	+	if !strings.Contains(update, "status: cancelled") {
	162	+	t.Fatalf("stop update missing cancellation status: %q", update)
	163	+	}
	164	+	if !strings.Contains(update, "subagent stopped by request") \|\| strings.Contains(update, "context canceled") {
	165	+	t.Fatalf("stop update missing attributed cancellation: %q", update)
163	166		}
164	167		}
165	168

 	if !strings.Contains(update, "task: investigate the stuck worker") {
 		t.Fatalf("stop update missing task: %q", update)
 	}
-	if !strings.Contains(update, "status: killed") {
+	if !strings.Contains(update, "status: cancelled") {
-		t.Fatalf("stop update missing killed status: %q", update)
+		t.Fatalf("stop update missing cancellation status: %q", update)
+	}
+	if !strings.Contains(update, "subagent stopped by request") || strings.Contains(update, "context canceled") {
+		t.Fatalf("stop update missing attributed cancellation: %q", update)
 	}
 }

M packages/agent/modes/interactive.go +10 -1


@@ -8821,6 +8821,13 @@ func (i Interactive) flushSupervisorSummary(batch []subagentWatchEntry) {
8821	8821		if status == "" {
8822	8822		status = string(snap.Status)
8823	8823		}
	8824	+	resultErr := ""
	8825	+	if snap.Result != nil && snap.Result.Status == subagents.ResultCanceled && snap.Result.ShutdownOrigin != "" {
	8826	+	status = "cancelled"
	8827	+	if snap.Result.Error != nil {
	8828	+	resultErr = snap.Result.Error.Message
	8829	+	}
	8830	+	}
8824	8831		task := e.task
8825	8832		if task == "" \|\| !e.followUp {
8826	8833		task = snap.Task

@@ -8830,7 +8837,9 @@ func (i Interactive) flushSupervisorSummary(batch []subagentWatchEntry) {
8830	8837		}
8831	8838		fmt.Fprintf(&sb, "%d. agent %s - status: %s\n", idx+1, snap.ID, status)
8832	8839		fmt.Fprintf(&sb, " task: %s\n", truncateForSummary(task, 240))
8833		-	if snap.Err != "" {
	8840	+	if resultErr != "" {
	8841	+	fmt.Fprintf(&sb, " cancellation: %s\n", truncateForSummary(resultErr, 240))
	8842	+	} else if snap.Err != "" {
8834	8843		fmt.Fprintf(&sb, " error: %s\n", truncateForSummary(snap.Err, 240))
8835	8844		} else if e.err != "" {
8836	8845		fmt.Fprintf(&sb, " turn error: %s\n", truncateForSummary(e.err, 240))

 		if status == "" {
 			status = string(snap.Status)
 		}
+		resultErr := ""
+		if snap.Result != nil && snap.Result.Status == subagents.ResultCanceled && snap.Result.ShutdownOrigin != "" {
+			status = "cancelled"
+			if snap.Result.Error != nil {
+				resultErr = snap.Result.Error.Message
+			}
+		}
 		task := e.task
 		if task == "" || !e.followUp {
 			task = snap.Task
 		}
 		fmt.Fprintf(&sb, "%d. agent %s - status: %s\n", idx+1, snap.ID, status)
 		fmt.Fprintf(&sb, "   task: %s\n", truncateForSummary(task, 240))
-		if snap.Err != "" {
+		if resultErr != "" {
+			fmt.Fprintf(&sb, "   cancellation: %s\n", truncateForSummary(resultErr, 240))
+		} else if snap.Err != "" {
 			fmt.Fprintf(&sb, "   error: %s\n", truncateForSummary(snap.Err, 240))
 		} else if e.err != "" {
 			fmt.Fprintf(&sb, "   turn error: %s\n", truncateForSummary(e.err, 240))

M packages/agent/subagent_worker.go +31 -9


@@ -354,21 +354,33 @@ func runSubagentWorkerMode(ctx context.Context, args Args, version string) (runE
354	354		resultStatus = "failed"
355	355		}
356	356		}
	357	+	mu.Lock()
	358	+	resultShutdownOrigin := shutdownOrigin.Sanitized()
	359	+	mu.Unlock()
	360	+	switch {
	361	+	case errors.Is(err, context.DeadlineExceeded):
	362	+	resultShutdownOrigin = subagents.ShutdownOriginDeadline
	363	+	case !errors.Is(err, context.Canceled):
	364	+	resultShutdownOrigin = ""
	365	+	}
357	366		resultPayload := map[string]any{
358	367		"status": resultStatus,
359	368		"turn_id": turnID,
360	369		"summary": boundedResultSummary(output),
361	370		"output": boundedResultOutput(output, maxOutputBytes, maxOutputLines),
362		-	"error": resultErrorPayload(err),
	371	+	"error": resultErrorPayload(err, resultShutdownOrigin),
	372	+	}
	373	+	if resultShutdownOrigin != "" {
	374	+	resultPayload["shutdown_origin"] = resultShutdownOrigin
363	375		}
364	376		em.emit("turn.result", resultPayload)
365	377		if err != nil {
366		-	em.emit("turn.failed", map[string]any{"turn_id": turnID, "error": resultErrorPayload(err)})
	378	+	em.emit("turn.failed", map[string]any{"turn_id": turnID, "error": resultErrorPayload(err, resultShutdownOrigin)})
367	379		}
368	380		em.emit("turn_end", map[string]any{
369	381		"step": step,
370	382		"turn_id": turnID,
371		-	"error": turnErrorMessage(err),
	383	+	"error": turnErrorMessage(err, resultShutdownOrigin),
372	384		})
373	385
374	386		cancel()

@@ -413,11 +425,11 @@ func runSubagentWorkerMode(ctx context.Context, args Args, version string) (runE
413	425		}
414	426
415	427		requestShutdown := func(origin subagents.ShutdownOrigin) {
416		-	mu.Lock()
417		-	closing = true
418		-	mu.Unlock()
419	428		shutdownOnce.Do(func() {
	429	+	mu.Lock()
	430	+	closing = true
420	431		shutdownOrigin = origin.Sanitized()
	432	+	mu.Unlock()
421	433		close(shutdown)
422	434		})
423	435		}

@@ -725,23 +737,33 @@ func truncateOutputUTF8(value string, maxBytes int) string {
725	737		return string(data)
726	738		}
727	739
728		-	func resultErrorPayload(err error) map[string]any {
	740	+	func resultErrorPayload(err error, shutdownOrigin subagents.ShutdownOrigin) map[string]any {
729	741		if err == nil {
730	742		return nil
731	743		}
732	744		if provider.IsContextOverflowError(err) {
733	745		return map[string]any{"code": "context_limit", "message": subagentContextLimitMessage}
734	746		}
735		-	if errors.Is(err, context.DeadlineExceeded) {
	747	+	if errors.Is(err, context.DeadlineExceeded) \|\| shutdownOrigin == subagents.ShutdownOriginDeadline {
736	748		return map[string]any{"code": "deadline_exceeded", "message": "subagent turn deadline exceeded; partial output is preserved in the result and history"}
737	749		}
	750	+	if errors.Is(err, context.Canceled) {
	751	+	if resultErr := subagents.ShutdownResultError(shutdownOrigin); resultErr != nil {
	752	+	return map[string]any{"code": resultErr.Code, "message": resultErr.Message}
	753	+	}
	754	+	}
738	755		return map[string]any{"code": "turn_failed", "message": truncateForLog(err.Error(), 500)}
739	756		}
740	757
741		-	func turnErrorMessage(err error) string {
	758	+	func turnErrorMessage(err error, shutdownOrigin subagents.ShutdownOrigin) string {
742	759		if provider.IsContextOverflowError(err) {
743	760		return subagentContextLimitMessage
744	761		}
	762	+	if err != nil {
	763	+	if resultErr := subagents.ShutdownResultError(shutdownOrigin); resultErr != nil {
	764	+	return resultErr.Message
	765	+	}
	766	+	}
745	767		return errString(err)
746	768		}
747	769

 				resultStatus = "failed"
 			}
 		}
+		mu.Lock()
+		resultShutdownOrigin := shutdownOrigin.Sanitized()
+		mu.Unlock()
+		switch {
+		case errors.Is(err, context.DeadlineExceeded):
+			resultShutdownOrigin = subagents.ShutdownOriginDeadline
+		case !errors.Is(err, context.Canceled):
+			resultShutdownOrigin = ""
+		}
 		resultPayload := map[string]any{
 			"status":  resultStatus,
 			"turn_id": turnID,
 			"summary": boundedResultSummary(output),
 			"output":  boundedResultOutput(output, maxOutputBytes, maxOutputLines),
-			"error":   resultErrorPayload(err),
+			"error":   resultErrorPayload(err, resultShutdownOrigin),
+		}
+		if resultShutdownOrigin != "" {
+			resultPayload["shutdown_origin"] = resultShutdownOrigin
 		}
 		em.emit("turn.result", resultPayload)
 		if err != nil {
-			em.emit("turn.failed", map[string]any{"turn_id": turnID, "error": resultErrorPayload(err)})
+			em.emit("turn.failed", map[string]any{"turn_id": turnID, "error": resultErrorPayload(err, resultShutdownOrigin)})
 		}
 		em.emit("turn_end", map[string]any{
 			"step":    step,
 			"turn_id": turnID,
-			"error":   turnErrorMessage(err),
+			"error":   turnErrorMessage(err, resultShutdownOrigin),
 		})
 		cancel()
 	}
 	requestShutdown := func(origin subagents.ShutdownOrigin) {
-		mu.Lock()
-		closing = true
-		mu.Unlock()
 		shutdownOnce.Do(func() {
+			mu.Lock()
+			closing = true
 			shutdownOrigin = origin.Sanitized()
+			mu.Unlock()
 			close(shutdown)
 		})
 	}
 	return string(data)
 }
-func resultErrorPayload(err error) map[string]any {
+func resultErrorPayload(err error, shutdownOrigin subagents.ShutdownOrigin) map[string]any {
 	if err == nil {
 		return nil
 	}
 	if provider.IsContextOverflowError(err) {
 		return map[string]any{"code": "context_limit", "message": subagentContextLimitMessage}
 	}
-	if errors.Is(err, context.DeadlineExceeded) {
+	if errors.Is(err, context.DeadlineExceeded) || shutdownOrigin == subagents.ShutdownOriginDeadline {
 		return map[string]any{"code": "deadline_exceeded", "message": "subagent turn deadline exceeded; partial output is preserved in the result and history"}
 	}
+	if errors.Is(err, context.Canceled) {
+		if resultErr := subagents.ShutdownResultError(shutdownOrigin); resultErr != nil {
+			return map[string]any{"code": resultErr.Code, "message": resultErr.Message}
+		}
+	}
 	return map[string]any{"code": "turn_failed", "message": truncateForLog(err.Error(), 500)}
 }
-func turnErrorMessage(err error) string {
+func turnErrorMessage(err error, shutdownOrigin subagents.ShutdownOrigin) string {
 	if provider.IsContextOverflowError(err) {
 		return subagentContextLimitMessage
 	}
+	if err != nil {
+		if resultErr := subagents.ShutdownResultError(shutdownOrigin); resultErr != nil {
+			return resultErr.Message
+		}
+	}
 	return errString(err)
 }

M packages/agent/subagent_worker_test.go +10 -3


@@ -53,12 +53,19 @@ func TestSubagentTurnContextResetsDeadlineAndHonorsShutdown(t *testing.T) {
53	53		}
54	54
55	55		func TestResultErrorPayloadClassifiesTurnDeadline(t *testing.T) {
56		-	payload := resultErrorPayload(context.DeadlineExceeded)
	56	+	payload := resultErrorPayload(context.DeadlineExceeded, "")
57	57		if payload["code"] != "deadline_exceeded" {
58	58		t.Fatalf("deadline error code = %v, want deadline_exceeded", payload["code"])
59	59		}
60	60		}
61	61
	62	+	func TestResultErrorPayloadAttributesShutdownCancellation(t *testing.T) {
	63	+	payload := resultErrorPayload(context.Canceled, subagents.ShutdownOriginSession)
	64	+	if payload["code"] != "shutdown" \|\| payload["message"] != "subagent stopped during session shutdown" {
	65	+	t.Fatalf("session shutdown error = %#v", payload)
	66	+	}
	67	+	}
	68	+
62	69		func TestShutdownExitPayloadIncludesOnlyKnownOrigin(t *testing.T) {
63	70		payload := shutdownExitPayload(subagents.ShutdownOriginSession)
64	71		if payload["reason"] != "shutdown" \|\| payload["origin"] != subagents.ShutdownOriginSession {

@@ -257,7 +264,7 @@ func TestPromptWithContextRecoveryPropagatesCompactionFailure(t *testing.T) {
257	264		if err == nil \|\| !strings.Contains(err.Error(), "compact transcript after initial overflow") {
258	265		t.Fatalf("promptWithContextRecovery error = %v, want compaction failure", err)
259	266		}
260		-	payload := resultErrorPayload(err)
	267	+	payload := resultErrorPayload(err, "")
261	268		if payload["code"] != "turn_failed" {
262	269		t.Fatalf("result error payload = %#v, want turn_failed", payload)
263	270		}

@@ -736,7 +743,7 @@ func workerRequestUserTextCount(req provider.Request, want string) int {
736	743		}
737	744
738	745		func TestResultErrorPayloadSanitizesContextOverflow(t *testing.T) {
739		-	payload := resultErrorPayload(errors.New("provider error: input exceeds the context window; echoed task text"))
	746	+	payload := resultErrorPayload(errors.New("provider error: input exceeds the context window; echoed task text"), "")
740	747		if payload["code"] != "context_limit" {
741	748		t.Fatalf("error code = %q, want context_limit", payload["code"])
742	749		}

 }
 func TestResultErrorPayloadClassifiesTurnDeadline(t *testing.T) {
-	payload := resultErrorPayload(context.DeadlineExceeded)
+	payload := resultErrorPayload(context.DeadlineExceeded, "")
 	if payload["code"] != "deadline_exceeded" {
 		t.Fatalf("deadline error code = %v, want deadline_exceeded", payload["code"])
 	}
 }
+func TestResultErrorPayloadAttributesShutdownCancellation(t *testing.T) {
+	payload := resultErrorPayload(context.Canceled, subagents.ShutdownOriginSession)
+	if payload["code"] != "shutdown" || payload["message"] != "subagent stopped during session shutdown" {
+		t.Fatalf("session shutdown error = %#v", payload)
+	}
+}
 func TestShutdownExitPayloadIncludesOnlyKnownOrigin(t *testing.T) {
 	payload := shutdownExitPayload(subagents.ShutdownOriginSession)
 	if payload["reason"] != "shutdown" || payload["origin"] != subagents.ShutdownOriginSession {
 	if err == nil || !strings.Contains(err.Error(), "compact transcript after initial overflow") {
 		t.Fatalf("promptWithContextRecovery error = %v, want compaction failure", err)
 	}
-	payload := resultErrorPayload(err)
+	payload := resultErrorPayload(err, "")
 	if payload["code"] != "turn_failed" {
 		t.Fatalf("result error payload = %#v, want turn_failed", payload)
 	}
 }
 func TestResultErrorPayloadSanitizesContextOverflow(t *testing.T) {
-	payload := resultErrorPayload(errors.New("provider error: input exceeds the context window; echoed task text"))
+	payload := resultErrorPayload(errors.New("provider error: input exceeds the context window; echoed task text"), "")
 	if payload["code"] != "context_limit" {
 		t.Fatalf("error code = %q, want context_limit", payload["code"])
 	}

M packages/agent/subagents/agent.go +14 -0


@@ -163,6 +163,7 @@ type Agent struct {
163	163		updatedAt time.Time
164	164		lastActivity time.Time
165	165		result *TurnResult
	166	+	shutdownOrigin ShutdownOrigin
166	167		resultRef string
167	168		patchRef string
168	169		changedFiles []string

@@ -410,6 +411,19 @@ func (a Agent) setResult(result TurnResult) {
410	411		a.lifecycleMu.Unlock()
411	412		}
412	413
	414	+	func (a *Agent) setShutdownOrigin(origin ShutdownOrigin) {
	415	+	a.lifecycleMu.Lock()
	416	+	a.shutdownOrigin = origin.Sanitized()
	417	+	a.updatedAt = time.Now()
	418	+	a.lifecycleMu.Unlock()
	419	+	}
	420	+
	421	+	func (a *Agent) shutdownOriginValue() ShutdownOrigin {
	422	+	a.lifecycleMu.Lock()
	423	+	defer a.lifecycleMu.Unlock()
	424	+	return a.shutdownOrigin
	425	+	}
	426	+
413	427		// Transcript returns a copy of the running transcript. Detached agents
414	428		// hydrate their durable event history the first time it is requested.
415	429		func (a *Agent) Transcript() []string {


@@ -163,6 +163,7 @@ type Agent struct {
163	updatedAt time.Time	163		updatedAt time.Time
164	lastActivity time.Time	164		lastActivity time.Time
165	result *TurnResult	165		result *TurnResult
		166	+	shutdownOrigin ShutdownOrigin
166	resultRef string	167		resultRef string
167	patchRef string	168		patchRef string
168	changedFiles []string	169		changedFiles []string

@@ -410,6 +411,19 @@ func (a Agent) setResult(result TurnResult) {
410	a.lifecycleMu.Unlock()	411		a.lifecycleMu.Unlock()
411	}	412		}
412		413
		414	+	func (a *Agent) setShutdownOrigin(origin ShutdownOrigin) {
		415	+	a.lifecycleMu.Lock()
		416	+	a.shutdownOrigin = origin.Sanitized()
		417	+	a.updatedAt = time.Now()
		418	+	a.lifecycleMu.Unlock()
		419	+	}
		420	+
		421	+	func (a *Agent) shutdownOriginValue() ShutdownOrigin {
		422	+	a.lifecycleMu.Lock()
		423	+	defer a.lifecycleMu.Unlock()
		424	+	return a.shutdownOrigin
		425	+	}
		426	+
413	// Transcript returns a copy of the running transcript. Detached agents	427		// Transcript returns a copy of the running transcript. Detached agents
414	// hydrate their durable event history the first time it is requested.	428		// hydrate their durable event history the first time it is requested.
415	func (a *Agent) Transcript() []string {	429		func (a *Agent) Transcript() []string {

M packages/agent/subagents/result.go +48 -12


@@ -37,22 +37,40 @@ type ResultError struct {
37	37		Message string `json:"message,omitempty"`
38	38		}
39	39
	40	+	// ShutdownResultError returns the stable, user-facing error associated with
	41	+	// an intentional worker shutdown. Unknown origins are not attributed.
	42	+	func ShutdownResultError(origin ShutdownOrigin) *ResultError {
	43	+	switch origin.Sanitized() {
	44	+	case ShutdownOriginTargeted:
	45	+	return &ResultError{Code: "shutdown", Message: "subagent stopped by request"}
	46	+	case ShutdownOriginSession:
	47	+	return &ResultError{Code: "shutdown", Message: "subagent stopped during session shutdown"}
	48	+	case ShutdownOriginDeadline:
	49	+	return &ResultError{Code: "deadline_exceeded", Message: "subagent turn deadline exceeded; partial output is preserved in the result and history"}
	50	+	case ShutdownOriginProcess:
	51	+	return &ResultError{Code: "shutdown", Message: "subagent stopped during process shutdown"}
	52	+	default:
	53	+	return nil
	54	+	}
	55	+	}
	56	+
40	57		// TurnResult is the protocol-level result for a delegated turn. Output is a
41	58		// bounded inline preview; the full session/history remains available through
42	59		// HistoryRef and the complete JSON result through ResultRef.
43	60		type TurnResult struct {
44		-	Version int `json:"version"`
45		-	AgentID string `json:"agent_id,omitempty"`
46		-	TurnID string `json:"turn_id,omitempty"`
47		-	Status TurnStatus `json:"status"`
48		-	Summary string `json:"summary,omitempty"`
49		-	Output string `json:"output,omitempty"`
50		-	Structured json.RawMessage `json:"structured,omitempty"`
51		-	Artifacts []ArtifactRef `json:"artifacts,omitempty"`
52		-	ChangedFiles []string `json:"changed_files,omitempty"`
53		-	Usage map[string]any `json:"usage,omitempty"`
54		-	Error *ResultError `json:"error,omitempty"`
55		-	CreatedAt time.Time `json:"created_at"`
	61	+	Version int `json:"version"`
	62	+	AgentID string `json:"agent_id,omitempty"`
	63	+	TurnID string `json:"turn_id,omitempty"`
	64	+	Status TurnStatus `json:"status"`
	65	+	Summary string `json:"summary,omitempty"`
	66	+	Output string `json:"output,omitempty"`
	67	+	Structured json.RawMessage `json:"structured,omitempty"`
	68	+	Artifacts []ArtifactRef `json:"artifacts,omitempty"`
	69	+	ChangedFiles []string `json:"changed_files,omitempty"`
	70	+	Usage map[string]any `json:"usage,omitempty"`
	71	+	Error *ResultError `json:"error,omitempty"`
	72	+	ShutdownOrigin ShutdownOrigin `json:"shutdown_origin,omitempty"`
	73	+	CreatedAt time.Time `json:"created_at"`
56	74		}
57	75
58	76		func (r *TurnResult) Validate(maxBytes, maxLines int) error {

@@ -71,6 +89,9 @@ func (r *TurnResult) Validate(maxBytes, maxLines int) error {
71	89		if r.AgentID == "" {
72	90		return errors.New("subagents: result missing agent id")
73	91		}
	92	+	if r.ShutdownOrigin != "" && r.ShutdownOrigin.Sanitized() == "" {
	93	+	return errors.New("subagents: result has invalid shutdown origin")
	94	+	}
74	95		if r.TurnID == "" {
75	96		return errors.New("subagents: result missing turn id")
76	97		}

@@ -443,6 +464,10 @@ func (f Supervisor) ensureResult(a Agent, status Status, runErr error) {
443	464		return
444	465		}
445	466		attempt := a.AttemptValue()
	467	+	shutdownOrigin := a.shutdownOriginValue()
	468	+	if errors.Is(runErr, context.DeadlineExceeded) {
	469	+	shutdownOrigin = ShutdownOriginDeadline
	470	+	}
446	471		a.mu.Lock()
447	472		partialOutput := a.lastAssistant
448	473		a.mu.Unlock()

@@ -515,6 +540,15 @@ func (f Supervisor) ensureResult(a Agent, status Status, runErr error) {
515	540		if result.CreatedAt.IsZero() {
516	541		result.CreatedAt = time.Now().UTC()
517	542		}
	543	+	if shutdownOrigin != "" {
	544	+	result.ShutdownOrigin = shutdownOrigin
	545	+	result.Error = ShutdownResultError(shutdownOrigin)
	546	+	if shutdownOrigin == ShutdownOriginDeadline {
	547	+	result.Status = ResultFailed
	548	+	} else {
	549	+	result.Status = ResultCanceled
	550	+	}
	551	+	}
518	552		if runErr != nil {
519	553		if status == StatusKilled \|\| errors.Is(runErr, context.Canceled) {
520	554		result.Status = ResultCanceled

@@ -522,6 +556,7 @@ func (f Supervisor) ensureResult(a Agent, status Status, runErr error) {
522	556		result.Status = ResultFailed
523	557		}
524	558		if errors.Is(runErr, context.DeadlineExceeded) {
	559	+	result.Status = ResultFailed
525	560		// The parent deadline is authoritative for terminal categorization, so
526	561		// it intentionally overrides any child result error, including
527	562		// context_limit. The worker was first asked to stop cleanly, and any

@@ -534,6 +569,7 @@ func (f Supervisor) ensureResult(a Agent, status Status, runErr error) {
534	569		Code: "deadline_exceeded",
535	570		Message: message,
536	571		}
	572	+	result.ShutdownOrigin = ShutdownOriginDeadline
537	573		} else if result.Error == nil {
538	574		result.Error = &ResultError{Code: "runner_failed", Message: truncate(runErr.Error(), 500)}
539	575		}

 	Message string `json:"message,omitempty"`
 }
+// ShutdownResultError returns the stable, user-facing error associated with
+// an intentional worker shutdown. Unknown origins are not attributed.
+func ShutdownResultError(origin ShutdownOrigin) *ResultError {
+	switch origin.Sanitized() {
+	case ShutdownOriginTargeted:
+		return &ResultError{Code: "shutdown", Message: "subagent stopped by request"}
+	case ShutdownOriginSession:
+		return &ResultError{Code: "shutdown", Message: "subagent stopped during session shutdown"}
+	case ShutdownOriginDeadline:
+		return &ResultError{Code: "deadline_exceeded", Message: "subagent turn deadline exceeded; partial output is preserved in the result and history"}
+	case ShutdownOriginProcess:
+		return &ResultError{Code: "shutdown", Message: "subagent stopped during process shutdown"}
+	default:
+		return nil
+	}
+}
 // TurnResult is the protocol-level result for a delegated turn. Output is a
 // bounded inline preview; the full session/history remains available through
 // HistoryRef and the complete JSON result through ResultRef.
 type TurnResult struct {
-	Version      int             `json:"version"`
+	Version        int             `json:"version"`
-	AgentID      string          `json:"agent_id,omitempty"`
+	AgentID        string          `json:"agent_id,omitempty"`
-	TurnID       string          `json:"turn_id,omitempty"`
+	TurnID         string          `json:"turn_id,omitempty"`
-	Status       TurnStatus      `json:"status"`
+	Status         TurnStatus      `json:"status"`
-	Summary      string          `json:"summary,omitempty"`
+	Summary        string          `json:"summary,omitempty"`
-	Output       string          `json:"output,omitempty"`
+	Output         string          `json:"output,omitempty"`
-	Structured   json.RawMessage `json:"structured,omitempty"`
+	Structured     json.RawMessage `json:"structured,omitempty"`
-	Artifacts    []ArtifactRef   `json:"artifacts,omitempty"`
+	Artifacts      []ArtifactRef   `json:"artifacts,omitempty"`
-	ChangedFiles []string        `json:"changed_files,omitempty"`
+	ChangedFiles   []string        `json:"changed_files,omitempty"`
-	Usage        map[string]any  `json:"usage,omitempty"`
+	Usage          map[string]any  `json:"usage,omitempty"`
-	Error        *ResultError    `json:"error,omitempty"`
+	Error          *ResultError    `json:"error,omitempty"`
-	CreatedAt    time.Time       `json:"created_at"`
+	ShutdownOrigin ShutdownOrigin  `json:"shutdown_origin,omitempty"`
+	CreatedAt      time.Time       `json:"created_at"`
 }
 func (r *TurnResult) Validate(maxBytes, maxLines int) error {
 	if r.AgentID == "" {
 		return errors.New("subagents: result missing agent id")
 	}
+	if r.ShutdownOrigin != "" && r.ShutdownOrigin.Sanitized() == "" {
+		return errors.New("subagents: result has invalid shutdown origin")
+	}
 	if r.TurnID == "" {
 		return errors.New("subagents: result missing turn id")
 	}
 		return
 	}
 	attempt := a.AttemptValue()
+	shutdownOrigin := a.shutdownOriginValue()
+	if errors.Is(runErr, context.DeadlineExceeded) {
+		shutdownOrigin = ShutdownOriginDeadline
+	}
 	a.mu.Lock()
 	partialOutput := a.lastAssistant
 	a.mu.Unlock()
 	if result.CreatedAt.IsZero() {
 		result.CreatedAt = time.Now().UTC()
 	}
+	if shutdownOrigin != "" {
+		result.ShutdownOrigin = shutdownOrigin
+		result.Error = ShutdownResultError(shutdownOrigin)
+		if shutdownOrigin == ShutdownOriginDeadline {
+			result.Status = ResultFailed
+		} else {
+			result.Status = ResultCanceled
+		}
+	}
 	if runErr != nil {
 		if status == StatusKilled || errors.Is(runErr, context.Canceled) {
 			result.Status = ResultCanceled
 			result.Status = ResultFailed
 		}
 		if errors.Is(runErr, context.DeadlineExceeded) {
+			result.Status = ResultFailed
 			// The parent deadline is authoritative for terminal categorization, so
 			// it intentionally overrides any child result error, including
 			// context_limit. The worker was first asked to stop cleanly, and any
 				Code:    "deadline_exceeded",
 				Message: message,
 			}
+			result.ShutdownOrigin = ShutdownOriginDeadline
 		} else if result.Error == nil {
 			result.Error = &ResultError{Code: "runner_failed", Message: truncate(runErr.Error(), 500)}
 		}

M packages/agent/subagents/result_test.go +35 -12


@@ -33,6 +33,20 @@ func TestTurnResultValidationAndBoundedOutput(t *testing.T) {
33	33		}
34	34		}
35	35
	36	+	func TestTurnResultValidatesShutdownOrigin(t *testing.T) {
	37	+	result := &TurnResult{
	38	+	Version: ProtocolVersion, AgentID: "a", TurnID: "t", Status: ResultCanceled,
	39	+	ShutdownOrigin: ShutdownOriginSession,
	40	+	}
	41	+	if err := result.Validate(0, 0); err != nil {
	42	+	t.Fatalf("known shutdown origin was rejected: %v", err)
	43	+	}
	44	+	result.ShutdownOrigin = ShutdownOrigin("private detail")
	45	+	if err := result.Validate(0, 0); err == nil {
	46	+	t.Fatal("unknown shutdown origin was accepted")
	47	+	}
	48	+	}
	49	+
36	50		func TestTurnResultBoundedHonorsLineAndUTF8Limits(t *testing.T) {
37	51		result := &TurnResult{
38	52		Version: ProtocolVersion, AgentID: "a", TurnID: "t", Status: ResultSucceeded,

@@ -108,11 +122,14 @@ func TestDecodeTurnResultEventValidatesIdentityAndStatus(t *testing.T) {
108	122		if _, err := decodeTurnResultEvent(mismatched, "agent-1", 100, 10); err == nil {
109	123		t.Fatal("mismatched result agent was accepted")
110	124		}
111		-	valid := NewEvent(EventTurnResult, map[string]any{"status": string(ResultSucceeded)})
	125	+	valid := NewEvent(EventTurnResult, map[string]any{
	126	+	"status": string(ResultCanceled),
	127	+	"shutdown_origin": ShutdownOriginSession,
	128	+	})
112	129		valid.AgentID = "agent-1"
113	130		valid.TurnID = "turn-1"
114	131		result, err := decodeTurnResultEvent(valid, "agent-1", 100, 10)
115		-	if err != nil \|\| result.AgentID != "agent-1" \|\| result.TurnID != "turn-1" {
	132	+	if err != nil \|\| result.AgentID != "agent-1" \|\| result.TurnID != "turn-1" \|\| result.ShutdownOrigin != ShutdownOriginSession {
116	133		t.Fatalf("valid result = %#v, err=%v", result, err)
117	134		}
118	135		}

@@ -269,19 +286,21 @@ func checkCaptureFailureResult(t testing.T, agent Agent, stateDir string) {
269	286
270	287		func TestEnsureResultReconcilesChildStatusWithRunnerError(t *testing.T) {
271	288		tests := []struct {
272		-	name string
273		-	status Status
274		-	runErr error
275		-	childCode string
276		-	wantState TurnStatus
277		-	wantCode string
278		-	wantOutput string
	289	+	name string
	290	+	status Status
	291	+	runErr error
	292	+	childCode string
	293	+	shutdownOrigin ShutdownOrigin
	294	+	wantState TurnStatus
	295	+	wantCode string
	296	+	wantOutput string
279	297		}{
280	298		{name: "runner failure", status: StatusFailed, runErr: errors.New("runner failed"), wantState: ResultFailed, wantCode: "runner_failed"},
281	299		{name: "runner cancellation", status: StatusFailed, runErr: context.Canceled, wantState: ResultCanceled, wantCode: "runner_failed"},
282	300		{name: "deadline preserves recovery guidance", status: StatusFailed, runErr: context.DeadlineExceeded, wantState: ResultFailed, wantCode: "deadline_exceeded", wantOutput: "partial answer"},
283	301		{name: "deadline overrides child error", status: StatusFailed, runErr: context.DeadlineExceeded, childCode: "context_limit", wantState: ResultFailed, wantCode: "deadline_exceeded", wantOutput: "partial answer"},
284	302		{name: "killed", status: StatusKilled, runErr: context.Canceled, wantState: ResultCanceled, wantCode: "runner_failed"},
	303	+	{name: "session shutdown", status: StatusKilled, runErr: context.Canceled, shutdownOrigin: ShutdownOriginSession, wantState: ResultCanceled, wantCode: "shutdown"},
285	304		}
286	305		for _, tt := range tests {
287	306		t.Run(tt.name, func(t *testing.T) {

@@ -293,9 +312,10 @@ func TestEnsureResultReconcilesChildStatusWithRunnerError(t *testing.T) {
293	312		childError = &ResultError{Code: tt.childCode, Message: "child error"}
294	313		}
295	314		agent := &Agent{
296		-	ID: "agent-1",
297		-	stateDir: stateDir,
298		-	lastAssistant: tt.wantOutput,
	315	+	ID: "agent-1",
	316	+	stateDir: stateDir,
	317	+	lastAssistant: tt.wantOutput,
	318	+	shutdownOrigin: tt.shutdownOrigin,
299	319		result: &TurnResult{
300	320		AgentID: "agent-1", TurnID: "turn-1", Status: childStatus, Error: childError,
301	321		},

@@ -328,6 +348,9 @@ func TestEnsureResultReconcilesChildStatusWithRunnerError(t *testing.T) {
328	348		if durable.Error == nil \|\| durable.Error.Code != tt.wantCode {
329	349		t.Fatalf("durable result error = %#v, want code %q", durable.Error, tt.wantCode)
330	350		}
	351	+	if durable.ShutdownOrigin != tt.shutdownOrigin && tt.shutdownOrigin != "" {
	352	+	t.Fatalf("durable shutdown origin = %q, want %q", durable.ShutdownOrigin, tt.shutdownOrigin)
	353	+	}
331	354		})
332	355		}
333	356		}

 	}
 }
+func TestTurnResultValidatesShutdownOrigin(t *testing.T) {
+	result := &TurnResult{
+		Version: ProtocolVersion, AgentID: "a", TurnID: "t", Status: ResultCanceled,
+		ShutdownOrigin: ShutdownOriginSession,
+	}
+	if err := result.Validate(0, 0); err != nil {
+		t.Fatalf("known shutdown origin was rejected: %v", err)
+	}
+	result.ShutdownOrigin = ShutdownOrigin("private detail")
+	if err := result.Validate(0, 0); err == nil {
+		t.Fatal("unknown shutdown origin was accepted")
+	}
+}
 func TestTurnResultBoundedHonorsLineAndUTF8Limits(t *testing.T) {
 	result := &TurnResult{
 		Version: ProtocolVersion, AgentID: "a", TurnID: "t", Status: ResultSucceeded,
 	if _, err := decodeTurnResultEvent(mismatched, "agent-1", 100, 10); err == nil {
 		t.Fatal("mismatched result agent was accepted")
 	}
-	valid := NewEvent(EventTurnResult, map[string]any{"status": string(ResultSucceeded)})
+	valid := NewEvent(EventTurnResult, map[string]any{
+		"status":          string(ResultCanceled),
+		"shutdown_origin": ShutdownOriginSession,
+	})
 	valid.AgentID = "agent-1"
 	valid.TurnID = "turn-1"
 	result, err := decodeTurnResultEvent(valid, "agent-1", 100, 10)
-	if err != nil || result.AgentID != "agent-1" || result.TurnID != "turn-1" {
+	if err != nil || result.AgentID != "agent-1" || result.TurnID != "turn-1" || result.ShutdownOrigin != ShutdownOriginSession {
 		t.Fatalf("valid result = %#v, err=%v", result, err)
 	}
 }
 func TestEnsureResultReconcilesChildStatusWithRunnerError(t *testing.T) {
 	tests := []struct {
-		name       string
+		name           string
-		status     Status
+		status         Status
-		runErr     error
+		runErr         error
-		childCode  string
+		childCode      string
-		wantState  TurnStatus
+		shutdownOrigin ShutdownOrigin
-		wantCode   string
+		wantState      TurnStatus
-		wantOutput string
+		wantCode       string
+		wantOutput     string
 	}{
 		{name: "runner failure", status: StatusFailed, runErr: errors.New("runner failed"), wantState: ResultFailed, wantCode: "runner_failed"},
 		{name: "runner cancellation", status: StatusFailed, runErr: context.Canceled, wantState: ResultCanceled, wantCode: "runner_failed"},
 		{name: "deadline preserves recovery guidance", status: StatusFailed, runErr: context.DeadlineExceeded, wantState: ResultFailed, wantCode: "deadline_exceeded", wantOutput: "partial answer"},
 		{name: "deadline overrides child error", status: StatusFailed, runErr: context.DeadlineExceeded, childCode: "context_limit", wantState: ResultFailed, wantCode: "deadline_exceeded", wantOutput: "partial answer"},
 		{name: "killed", status: StatusKilled, runErr: context.Canceled, wantState: ResultCanceled, wantCode: "runner_failed"},
+		{name: "session shutdown", status: StatusKilled, runErr: context.Canceled, shutdownOrigin: ShutdownOriginSession, wantState: ResultCanceled, wantCode: "shutdown"},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 				childError = &ResultError{Code: tt.childCode, Message: "child error"}
 			}
 			agent := &Agent{
-				ID:            "agent-1",
+				ID:             "agent-1",
-				stateDir:      stateDir,
+				stateDir:       stateDir,
-				lastAssistant: tt.wantOutput,
+				lastAssistant:  tt.wantOutput,
+				shutdownOrigin: tt.shutdownOrigin,
 				result: &TurnResult{
 					AgentID: "agent-1", TurnID: "turn-1", Status: childStatus, Error: childError,
 				},
 			if durable.Error == nil || durable.Error.Code != tt.wantCode {
 				t.Fatalf("durable result error = %#v, want code %q", durable.Error, tt.wantCode)
 			}
+			if durable.ShutdownOrigin != tt.shutdownOrigin && tt.shutdownOrigin != "" {
+				t.Fatalf("durable shutdown origin = %q, want %q", durable.ShutdownOrigin, tt.shutdownOrigin)
+			}
 		})
 	}
 }

M packages/agent/subagents/supervisor.go +2 -0


@@ -814,6 +814,7 @@ func (f *Supervisor) stop(ctx context.Context, id string, origin ShutdownOrigin)
814	814		pid := a.ProcessPIDValue()
815	815		a.mu.Unlock()
816	816		f.mu.Unlock()
	817	+	a.setShutdownOrigin(origin)
817	818		// The detached worker may take the full grace period to exit. Do not
818	819		// serialize unrelated supervisor operations for that entire wait.
819	820		f.operationMu.Unlock()

@@ -832,6 +833,7 @@ func (f *Supervisor) stop(ctx context.Context, id string, origin ShutdownOrigin)
832	833		}
833	834		a.mu.Unlock()
834	835		f.mu.Unlock()
	836	+	a.setShutdownOrigin(origin)
835	837		f.operationMu.Unlock()
836	838		a.setTurnState(TurnCanceling, a.CurrentTurnID())
837	839


@@ -814,6 +814,7 @@ func (f *Supervisor) stop(ctx context.Context, id string, origin ShutdownOrigin)
814	pid := a.ProcessPIDValue()	814		pid := a.ProcessPIDValue()
815	a.mu.Unlock()	815		a.mu.Unlock()
816	f.mu.Unlock()	816		f.mu.Unlock()
		817	+	a.setShutdownOrigin(origin)
817	// The detached worker may take the full grace period to exit. Do not	818		// The detached worker may take the full grace period to exit. Do not
818	// serialize unrelated supervisor operations for that entire wait.	819		// serialize unrelated supervisor operations for that entire wait.
819	f.operationMu.Unlock()	820		f.operationMu.Unlock()

@@ -832,6 +833,7 @@ func (f *Supervisor) stop(ctx context.Context, id string, origin ShutdownOrigin)
832	}	833		}
833	a.mu.Unlock()	834		a.mu.Unlock()
834	f.mu.Unlock()	835		f.mu.Unlock()
		836	+	a.setShutdownOrigin(origin)
835	f.operationMu.Unlock()	837		f.operationMu.Unlock()
836	a.setTurnState(TurnCanceling, a.CurrentTurnID())	838		a.setTurnState(TurnCanceling, a.CurrentTurnID())
837		839