fix(docs): document lambda:InvokeFunction for code-based evaluators

[jariy17]

Problem

run eval against a code-based evaluator fails with AccessDeniedException for anyone using the documented user policy:

Access denied when invoking Lambda function: An error occurred (AccessDeniedException)
when calling the Invoke operation (reached max retries: 0): User: ... is not authorized
to perform: lambda:InvokeFunction on resource:
arn:aws:lambda:us-east-1:...:function:E2e3pEval30379817-eval-answer_relevancy
because no identity-based policy allows the lambda:InvokeFunction action

This broke e2e (5/5) on main — 2 of 58 tests in third-party-eval-lifecycle.test.ts, retried 18× over ~250s with the same denial each time, so not a flake: run 30663047263

Root cause

bedrock-agentcore:Evaluate invokes the evaluator's Lambda using the caller's identity, so the caller needs lambda:InvokeFunction. A resource-based policy on the function alone does not cover this. (The error is botocore-formatted — reached max retries: 0 — and the wrapper string Access denied when invoking Lambda function: appears nowhere in this repo, confirming it originates service-side.)

Neither docs/policies/iam-policy-user.json (zero lambda:* actions) nor the PERMISSIONS.md Evaluation table granted or mentioned it. It went unnoticed because until the DeepEval/Autoevals tests added in #1828, every eval path exercised was Builtin.* (evals-lifecycle.test.ts:143) or llm-as-a-judge — neither touches Lambda. third-party-eval-lifecycle.test.ts is the first test to run --type code-based, which deploys a real Lambda per evaluator.

This is a user-facing gap, not just CI: anyone following the documented policy hits the identical denial.

Changes

• docs/policies/iam-policy-user.json — add CodeBasedEvaluatorInvocation statement
• docs/PERMISSIONS.md — add the action to the Evaluation table + explain why the caller (not the function) needs it

Scoped to arn:*:lambda:*:*:function:*-eval-* — matches the <AgentName>-eval-<evaluatorName> naming, uses the partition wildcard per the multi-partition rules in AGENTS.md, and avoids Resource: "*".

Also applied outside this repo

The e2e-github-actions role in the E2E account had no lambda:InvokeFunction on any of its 9 policies. Added the equivalent statement (account-scoped) to its e2e-permissions inline policy — statements 22 → 23, none lost. Verified with simulate-principal-policy:

Resource	Decision
E2e3pEval30379817-eval-answer_relevancy	allowed
E2e3pEval30379817-eval-exact_match	allowed
unrelated function, same account	implicitDeny
*-eval-* in a different account	implicitDeny

Testing

• prettier --check + secretlint + typecheck pass (pre-commit)
• IAM grant proven at the policy-evaluation layer via simulate-principal-policy on the two exact ARNs that were denied

Not yet proven end-to-end. These tests only run on the CodeBuild-hosted runners in the E2E account (runs-on: codebuild-agentcore-e2e-...), so they can't be reproduced locally, and gh run rerun --failed on the original run is refused while its attempt 2 still has a job in progress. The two failing tests should be re-run to confirm.

Out of scope — two separate issues found while investigating

1. Clone flake. e2e (1/5) on attempt 1 and e2e (5/5) on attempt 2 both died much earlier, at Clone CDK repository: remote: Repository not found / exit 128, despite the app-token step reporting success. Different shards each time, other shards clone fine in the same run — an infra flake in the app-token → clone handoff (.github/workflows/e2e-tests-full.yml:83-105) worth a retry wrapper.
2. The e2e check showed skipping on feat: add --model-provider flag for keyless Bedrock LLM judge evaluators #1828, so this test merged without ever running against a real role. That process hole is why the gap reached main.

[agentcore-devx-automation]

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

[github-actions]

Package Tarball

aws-agentcore-0.25.0.tgz

How to install

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

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	40.44%	15151 / 37462
🔵	Statements	39.71%	16158 / 40680
🔵	Functions	34.69%	2596 / 7482
🔵	Branches	33.82%	10108 / 29882

Generated in workflow #4286 for commit d422f00 by the Vitest Coverage Report Action