feat: add Lambda interceptors for AgentCore gateways

[aidandaly24]

Description

Adds end-to-end support for Lambda interceptors at gateway REQUEST and RESPONSE points: a new InterceptorPrimitive, three vended templates (pass-through, jwt-scope-authorizer, tools-list-filter) for both Python and Node.js, deploy-side preflight, and logs interceptor / invoke interceptor verbs.

Primitive surface

• `agentcore add interceptor --name --gateway --interception-points --template --runtime [--timeout] [--no-pass-request-headers] [--additional-policies]` for managed mode
• External mode via direct `agentcore.json` edit referencing a customer-provided unqualified Lambda ARN
• `agentcore remove interceptor --name` reconciles deploy state on next `agentcore deploy`
• `agentcore logs interceptor --name [--follow|--since|--until]` tails CloudWatch for managed interceptors; external interceptors short-circuit to a remediation message
• `agentcore invoke interceptor --name [--payload]` invokes the underlying Lambda for managed interceptors

Schema

• `interceptors` array on `AgentCoreProjectSpec` with cross-field `superRefine` for cardinality (max 1 per point per gateway, max 2 per gateway) and gateway-name reference checks
• Lambda ARN regex tightened to reject version/alias qualifiers
• `passRequestHeaders`, `entrypoint`, `timeoutSeconds`, `runtime` are optional with consumption-time defaults so user-edited `agentcore.json` stays sparse across CLI round-trips

Deploy

• `validateInterceptors()` checks managed-mode codeLocation existence and emits a masked cross-account WARN for external mode (with full `aws lambda add-permission` remediation snippet); also wired into `agentcore validate` so the pre-check works without invoking deploy
• `validateGatewayTargetLambdas()` does a best-effort `lambda:GetFunction` per `lambda-function-arn` target and WARNs on any failure (NotFound, AccessDenied, throttle) so a typo'd ARN surfaces before CFN ROLLBACK
• Account IDs go through `maskAccountId()` for all user-visible warning output (PII masking)

Templates

• `pass-through`, `jwt-scope-authorizer`, `tools-list-filter` for Python (`pyproject.toml` + hatchling) and Node.js (`index.mjs` + `package.json`)

Bug fixes

• ANSI cursor-show escape (`\x1b[?25h`) was being written to stdout on every CLI invocation by ink/cli-cursor on App unmount, corrupting machine-parseable output (broke `--json` JSON parsing). Fixed at the CLI entry by stripping cursor show/hide escapes from non-TTY stdout/stderr writes.

Out of scope (P0)

The following were deliberately excluded from this PR. None are bugs — flagged here so reviewers don't ask "where is X":

• PII-redaction template — patterns are wildly customer-specific (a bank's PII isn't a hospital's). Better as a future config-driven template, or roll your own using `pass-through` as a skeleton.
• Audit-logging template (OpenSearch / S3) — non-trivial destination wiring (IAM, batching, SIEM plug-in points). Ship later when there's a clearer customer ask.
• Provisioned concurrency — adds CFN complexity and runs $$$ even when idle. Wait for actual latency-sensitive customer demand.
• Multi-gateway shared interceptor pools — schema is currently 1 interceptor → 1 gateway. Sharing across gateways needs schema redesign (`gatewayNames: string[]` or a separate attach relation) and harder cardinality validation.
• Console UX parity — separate team's mission. CLI guarantees programmatic parity, not click-for-click visual matching.
• Streaming-aware first-invocation guard — shipped as commented-in code in the pass-through Node template (`if (invocationIndex > 0) { ... }`). Activating by default would change non-streaming behavior; customers opt in when needed.

Related Issue

Closes #

Documentation PR

Type of Change

• New feature

Testing

• I ran `npm run test:unit` and `npm run test:integ`
• I ran `npm run typecheck`
• I ran `npm run lint`
• If I modified `src/assets/`, I ran `npm run test:update-snapshots` and committed the updated snapshots

Additionally:

• End-to-end bug bash conducted across 60+ matrix cases against live AWS account, with 20+ parallel subagents covering: managed Python + Node templates × all 3 interception points, external same-account at REQUEST/RESPONSE/dual-point, cross-account preflight WARN, full deploy lifecycle (deploy → redeploy → remove → teardown), real MCP traffic with interceptor invocation proven via CloudWatch logs, JWT scope-authorizer allow/deny, RESPONSE-side `statusCode` mutation, tools-list filtering, additionalPolicies as file path AND managed ARN, IAM Sid hash uniqueness + size under 10240 bytes, schema rejects (qualifier ARN, unknown gateway, duplicate name, over-length name), --json output validity, TUI integration verified via tui-harness MCP

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published — depends on aws/agentcore-l3-cdk-constructs#225

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Package Tarball

aws-agentcore-0.17.0.tgz

How to install

gh release download pr-1330-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.17.0.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: the review run failed before completing. See the run for details.

[agentcore-devx-automation]

Claude Security Review: the review run failed before completing. See the run for details.

[agentcore-devx-automation]

Claude Security Review: the review run failed before completing. See the run for details.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)