{"record":{"id":"be54e28348f667de","repo":"can1357/oh-my-pi","slug":"message-hint","errorCode":null,"errorMessage":"${message}${hint}","messagePattern":"\\$\\{message\\}\\$\\{hint\\}","errorType":"exception","errorClass":"TaskJobError","httpStatus":null,"severity":"error","filePath":"packages/coding-agent/src/task/index.ts","lineNumber":1223,"sourceCode":"\t\t\t\t\tawait reportProgress(statusText, buildDetails() as unknown as Record<string, unknown>);\n\t\t\t\t\tconst deliveryText = `${finalText}${await buildFollowUpHint(singleResult?.aborted === true)}`;\n\t\t\t\t\tif (resultFailed) {\n\t\t\t\t\t\t// Mark the job itself failed; the failed agent stays interrogable.\n\t\t\t\t\t\tthrow new TaskJobError(deliveryText);\n\t\t\t\t\t}\n\t\t\t\t\treturn deliveryText;\n\t\t\t\t} catch (error) {\n\t\t\t\t\tif (error instanceof TaskJobError) {\n\t\t\t\t\t\tthrow error;\n\t\t\t\t\t}\n\t\t\t\t\tprogress.status = \"failed\";\n\t\t\t\t\tprogress.durationMs = Math.max(0, Date.now() - startedAt);\n\t\t\t\t\tonSettled?.(true);\n\t\t\t\t\tconst statusText = `Background task ${agentId} failed.`;\n\t\t\t\t\tawait reportProgress(statusText, buildDetails() as unknown as Record<string, unknown>);\n\t\t\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\t\t\tconst hint = AgentRegistry.global().get(agentId) ? await buildFollowUpHint(false) : \"\";\n\t\t\t\t\tthrow new TaskJobError(`${message}${hint}`);\n\t\t\t\t} finally {\n\t\t\t\t\treleasePermit();\n\t\t\t\t}\n\t\t\t},\n\t\t\t{\n\t\t\t\tid: agentId,\n\t\t\t\tagentId,\n\t\t\t\tqueued: true,\n\t\t\t\townerId: this.session.getAgentId?.() ?? undefined,\n\t\t\t\tonProgress: text => {\n\t\t\t\t\tonUpdate?.({ content: [{ type: \"text\", text }], details: buildDetails() });\n\t\t\t\t},\n\t\t\t},\n\t\t);\n\t}\n\n\t/**\n\t * Sync fan-out (async unavailable, or every item's agent type is","sourceCodeStart":1205,"sourceCodeEnd":1241,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/packages/coding-agent/src/task/index.ts#L1205-L1241","documentation":"When a background Task job's execution fails with an unexpected error, the TaskTool wraps the original message in a TaskJobError and appends a follow-up hint (resumability/transcript info) if the agent is still registered. The thrown error text is `${message}${hint}` — the root-cause message plus guidance on how to follow up with the failed agent.","triggerScenarios":"Any error thrown inside the registered job body other than TaskJobError itself (e.g. #executeSync failing on a provider error, config problem, or spawn crash) reaches the catch block; if AgentRegistry.global().get(agentId) finds the agent, buildFollowUpHint(false) text is appended and TaskJobError is thrown.","commonSituations":"Subagent run failing due to an invalid model, auth expiry, API/network error, or a tool-level failure — the underlying cause is in `message`; the hint tells you the agent is idle and resumable via hub/transcript.","solutions":["Read the message portion (before the hint) to identify the underlying failure and fix that root cause.","If it was a transient API/network error, resume or re-run the task via the follow-up hint (hub message or history:// transcript).","Check auth/model configuration if the message indicates provider/model errors.","Catch TaskJobError in embedding code and inspect its message for the chained cause."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-validate the subagent's model/auth config before spawning the task\nconst agent = AgentRegistry.global().get(agentId);\nif (!agent) throw new Error(`unknown agent ${agentId}`);\n// ensure model credentials exist\nconst auth = await discoverAuthStorage();\nif (!auth) console.warn(\"no auth storage; task likely to fail with provider error\");","typeGuard":null,"tryCatchPattern":"try {\n  await runBackgroundTask(params);\n} catch (err) {\n  if (err instanceof TaskJobError) {\n    // message = root cause + follow-up hint; split them for reporting\n    const rootCause = err.message.split(\"\\n\\n\")[0];\n    logger.error(\"Background task failed\", { rootCause });\n  } else throw err;\n}","preventionTips":["Fix the root cause embedded in the message (model, auth, network) rather than the wrapper.","Validate model ids and auth before spawning subagents.","Use the follow-up hint (hub/transcript) to resume instead of re-spawning duplicate work.","Monitor provider errors upstream so tasks fail fast with clear causes."],"tags":["task","error-wrapping","background-job","subagent"],"backgroundTag":"task-job-failed","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}