bug(policy): add policy --target generates an undeployable Cedar statement (wrong action id suffix, resource scope not narrowed)

[kawaji]

Description

agentcore add policy --target <target-name> generates a Cedar statement that the AgentCore Control API always rejects, so a tool-scoped policy can never be deployed. Two independent defects in the same generated statement:

1. Wrong action id suffix. The CLI emits AgentCore::Action::"<target>___POST:/invocations". The service expects AgentCore::Action::"<target>___<toolName>" and even suggests the correct value in its error.
2. Resource scope not narrowed. The CLI emits resource is AgentCore::Gateway. For a tool-scoped policy the service requires a concrete gateway ARN (resource == AgentCore::Gateway::"<arn>").

synthesizeCedar already accepts a gatewayArn option and produces the ARN-scoped form when it is supplied, but add policy never passes it.

Both defects must be fixed by hand in agentcore.json before agentcore deploy succeeds, which makes add policy --target unusable as shipped.

Steps to Reproduce

agentcore create --name gwprobe2 --no-agent
cd gwprobe2
agentcore add gateway --name toolgw --protocol-type MCP --authorizer-type AWS_IAM
agentcore add gateway-target --type connector --connector web-search \
  --gateway toolgw --name websearch
agentcore add policy-engine --name toolpe --attach-to-gateways toolgw --attach-mode ENFORCE
agentcore add policy --name blockViolence --engine toolpe \
  --form-category contentFilter --form-filters VIOLENCE --form-effect forbid \
  --target websearch
agentcore deploy -y

Generated statement in agentcore.json:

forbid (principal, action == AgentCore::Action::"websearch___POST:/invocations",
        resource is AgentCore::Gateway)
when guardrails { BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.prompt])["VIOLENCE"].confidenceScore.greaterThan(decimal("0.2")) };

Expected Behavior

agentcore deploy creates the AWS::BedrockAgentCore::Policy resource.

Actual Behavior

Deploy fails at CreatePolicy. Defect 1 surfaces first:

Resource handler returned message: "Multiple errors occurred during policy parsing/validation:
* for policy `blockViolence_..._0`, unrecognized action
  `AgentCore::Action::"websearch___POST:/invocations"` at line 1, column 30
did you mean `AgentCore::Action::"websearch___WebSearch"`?
* for policy `blockViolence_..._0`, unable to find an applicable action given the
  policy scope constraints
(Service: Bedrock AgentCore Control; Operation: CreatePolicy; Status Code: 400;
 Error Code: ValidationException)"

After correcting the action id by hand, defect 2 surfaces:

Resource handler returned message: "When parsing the policy statement, a constrained
action scope was encountered, please constrain the resource to a specific
AgentCore::Gateway resource when creating tool-specific policies.
(Service: Bedrock AgentCore Control; Operation: CreatePolicy; Status Code: 400;
 Error Code: ValidationException)"

Both corrections applied by hand, the policy deploys and enforces correctly — confirming the statement is the only problem:

forbid (principal, action == AgentCore::Action::"websearch___WebSearch",
        resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:ap-northeast-1:<account>:gateway/gwprobe2-toolgw-<id>")
when { context.input.query like "*forbidden*" };

Verified end to end over the gateway's MCP endpoint (SigV4):

• query = "washing machine error code" → isError: false, results returned
• query = "this is forbidden content" → Tool Execution Denied: Tool call not allowed due to policy enforcement [Policy evaluation denied due to <policy-id>]

CLI Version

0.30.0

Operating System

macOS

Additional Context

• Region: ap-northeast-1. Gateway authorizerType: AWS_IAM, target type connector / web-search.
• @aws/agentcore-cdk 0.1.0-alpha.53. In dist/cdk/.../synthesizeCedar, the gatewayArn option already selects resource == AgentCore::Gateway::"${arn}" over resource is AgentCore::Gateway, so defect 2 looks like a missing call-site argument rather than a missing feature.
• The action id suffix appears as a literal ___POST:/invocations template in the same function.
• Related but distinct: TUI/CLI accepts INSULT as a contentFilter value, fails CFN deploy with ValidationException #1571 (same shape — accepted locally, rejected by CFN — but about a contentFilter enum value), fix(policy): deploy --enforcement-mode through CDK #1910 (EnforcementMode not emitted by the CDK package), bug(policy): --generate flag fails to find gateway in deployed state #1658 (--generate gateway lookup, closed).
• Docs for this area are still open as docs: write docs/policies.md (Cedar policy engine + Bedrock guardrails) #1581, which is why the correct action-id and resource-scope forms are not discoverable today.