{"record":{"id":"1d32b9dd6f58d07c","repo":"ComposioHQ/composio","slug":"experimental-subagent-target-must-be-claude","errorCode":null,"errorMessage":"experimental_subAgent() target must be \"claude\", \"codex\", or \"user\" when provided.","messagePattern":"experimental_subAgent\\(\\) target must be \"claude\", \"codex\", or \"user\" when provided\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"ts/packages/cli/src/services/run-helpers-runtime.ts","lineNumber":360,"sourceCode":"const normalizeInvokeAgentOptions = (\n  options: Record<string, unknown> = {}\n): InvokeAgentNormalizedOptions => {\n  if (options == null || typeof options !== 'object' || Array.isArray(options)) {\n    throw new Error('experimental_subAgent() options must be an object when provided.');\n  }\n  if (options.schema !== undefined && options.jsonSchema !== undefined) {\n    throw new Error(\n      'experimental_subAgent() accepts either options.schema or options.jsonSchema, not both.'\n    );\n  }\n  const requestedTarget = options.target;\n  if (\n    requestedTarget !== undefined &&\n    requestedTarget !== 'claude' &&\n    requestedTarget !== 'codex' &&\n    requestedTarget !== 'user'\n  ) {\n    throw new Error(\n      'experimental_subAgent() target must be \"claude\", \"codex\", or \"user\" when provided.'\n    );\n  }\n  const inputSchema = options.schema ?? options.jsonSchema;\n  let structuredSchema: Record<string, unknown> | undefined;\n  let zodSchema: z.ZodType | undefined;\n  if (inputSchema !== undefined) {\n    if (inputSchema instanceof z.ZodType) {\n      if (typeof z.toJSONSchema !== 'function') {\n        throw new Error(\n          'experimental_subAgent() requires Zod 4 with z.toJSONSchema() when using options.schema.'\n        );\n      }\n      zodSchema = inputSchema;\n      const generatedSchema = z.toJSONSchema(inputSchema);\n      structuredSchema = Schema.decodeUnknownSync(JsonObject)(generatedSchema);\n    } else if (Predicate.isRecord(inputSchema)) {\n      structuredSchema = inputSchema;","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/cli/src/services/run-helpers-runtime.ts#L342-L378","documentation":"experimental_subAgent() accepts an optional options.target that must be one of the literal strings \"claude\", \"codex\", or \"user\". normalizeInvokeAgentOptions throws this error when target is provided but is not one of those three exact strings. It is a developer-API misuse guard fired before any subagent process is spawned.","triggerScenarios":"Calling experimental_subAgent(prompt, { target: ... }) with a typo'd or unsupported value, e.g. { target: 'Claude' } (capitalized), { target: 'openai' }, or a variable typed as string that isn't narrowed to the union.","commonSituations":"Passing a dynamically-built target string, copying a target name from docs of a different tool, or case mismatches. Also passing target: undefined explicitly is fine, but null or empty string throws.","solutions":["Set target to exactly \"claude\", \"codex\", or \"user\" (lowercase)","Omit the target property entirely to auto-detect the current master agent","If target comes from user input, validate/narrow it before calling experimental_subAgent"],"exampleFix":"// before\nawait experimental_subAgent('summarize', { target: 'Claude' });\n// after\nawait experimental_subAgent('summarize', { target: 'claude' });","handlingStrategy":"type-guard","validationCode":"const TARGETS = ['claude','codex','user'] as const;\nif (opts.target !== undefined && !TARGETS.includes(opts.target)) throw new RangeError(`bad target: ${opts.target}`);","typeGuard":"const isSubagentTarget = (v: unknown): v is 'claude'|'codex'|'user' => v === 'claude' || v === 'codex' || v === 'user';","tryCatchPattern":"catch (e) { if (e instanceof Error && e.message.includes('target must be')) { /* fix the literal and retry */ } throw e; }","preventionTips":["Type the options object as { target?: 'claude'|'codex'|'user' }","Keep target as a compile-time literal, not runtime-computed strings"],"tags":["subagent","validation","typescript","developer-error"],"backgroundTag":"invalid-enum-value","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}