fix: add --system-prompt and --tools CLI flags to add harness

[notgitika]

Summary

• Add missing --system-prompt, --tools, --mcp-name, --mcp-url, --gateway-arn, --gateway-outbound-auth, --gateway-provider-arn, and --gateway-scopes CLI option declarations to agentcore add harness
• Wire the new CLI options through the action handler type annotations and pass them to this.add()
• Add input validation in validateAddHarnessOptions to reject unknown tool names, missing companion flags, and invalid enum values — prevents silent tool omission
• Add unit tests for happy paths (4 tests) and error paths (8 tests)

Context

The AddHarnessOptions interface and add() method have supported systemPrompt, selectedTools, mcpName, mcpUrl, gatewayArn, and the gateway outbound auth fields since they were introduced, and the TUI wizard correctly collects and passes them. However, the Commander .option() registrations in registerCommands() were never added, so these flags silently fail when passed via CLI.

The DevGuide documentation references --system-prompt and --tools on agentcore add harness, causing errors for customers using the preview release.

The agentcore invoke command already has both --system-prompt and --tools flags — this fix brings agentcore add harness to parity.

Verified that these flags were never present in any version of HarnessPrimitive.ts on the preview branch (checked all 9 commits that touched the file) — this is not a regression, but a gap from initial implementation.

Validation

The tool-building logic in add() uses guarded branches that silently drop tools when companion flags are missing (e.g. remote_mcp without --mcp-url). Since these flags are being added specifically because docs reference them, a typo or missing flag would create a harness with tools: [] and no error — worse than the current "unknown flag" error.

Added validation in validateAddHarnessOptions (consistent with existing patterns like JWT auth validation):

• Unknown tool names → clear error listing valid options
• remote_mcp without --mcp-name or --mcp-url → error
• agentcore_gateway without --gateway-arn → error
• Invalid --gateway-outbound-auth value → error listing valid options
• oauth auth without --gateway-provider-arn or --gateway-scopes → error

Test plan

• npm run typecheck passes
• npm run lint passes (0 errors)
• npm run format:check passes
• HarnessPrimitive tests — 31/31 pass (4 new: tools, remote_mcp, gateway, gateway+outboundAuth)
• validate-harness tests — 14/14 pass (8 new: unknown tool, missing mcp-name/url, missing gateway-arn, invalid outbound-auth, missing oauth fields, valid combo)
• Manual: agentcore add harness --name test --system-prompt "You are a coding assistant" --tools agentcore_browser,agentcore_code_interpreter

[agentcore-cli-automation]

The new CLI flags expose several silent-failure paths that didn't matter before because the TUI wizard enforced required follow-up fields, but now become user-visible footguns. In HarnessPrimitive.add() (lines ~98–141), the tool-building loop uses guarded else if branches that quietly drop input when required fields are missing or misspelled:

1. --tools remote_mcp without --mcp-name/--mcp-url → the remote_mcp branch is skipped, tool is silently omitted from the spec.
2. --tools agentcore_gateway without --gateway-arn → gateway tool silently omitted.
3. --tools agentcore_gateway --gateway-arn ... without --gateway-outbound-auth → a gateway tool with no outbound auth is written (may or may not be intended — worth confirming against the schema).
4. --gateway-outbound-auth oauth with missing --gateway-provider-arn or --gateway-scopes → the gateway is still written, but the outboundAuth config is silently dropped.
5. --gateway-outbound-auth iam (or any typo) → cast as 'awsIam' | 'none' | 'oauth' | undefined means the bad value just falls through all the if/else if branches; no error, no auth.
6. --tools foo (unknown tool name) → silently omitted. No case-insensitive matching either (AGENTCORE_BROWSER won't work), unlike sibling flags (--model-provider, --authorizer-type) which go through matchEnumValue in validateAddHarnessOptions.

Since these flags are being added specifically because the DevGuide documents them and customers are hitting errors, a user who follows the docs and mistypes one related flag will get a harness created with tools: [] and no indication anything went wrong. That's worse than the current "flag unknown" error.

A few options to fix:

• Validate in validateAddHarnessOptions (preferred, consistent with other flags): reject unknown tool names, require mcpName+mcpUrl when remote_mcp is selected, require gatewayArn when agentcore_gateway is selected, validate gatewayOutboundAuth against the enum, and require gatewayProviderArn+gatewayScopes when it's oauth. Also run the tool names through matchEnumValue for case-insensitive parity with other enum flags.
• Return an error from add() when these guard conditions fail instead of silently dropping (less ideal — validation is normally done upstream in this codebase, and add() is also called from the TUI where the wizard already guarantees valid state).
• At minimum, change the guards so an unknown/invalid tool entry produces a thrown error rather than a silent skip.

Worth adding tests for at least the error paths (remote_mcp without URL, unknown tool, bad outbound auth value) once validation is in place — the current 4 new tests all cover happy paths.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	43.47%	9902 / 22777
🔵	Statements	42.74%	10517 / 24602
🔵	Functions	40.39%	1667 / 4127
🔵	Branches	40.17%	6396 / 15919

Generated in workflow #2342 for commit ec1d18c by the Vitest Coverage Report Action