fix(toolkit-lib): hooks without annotations fail deployments without showing failure details

[mrgrain]

Fixes #

CloudFormation Hooks that don't emit annotations — notably AWS::Hooks::LambdaHook and other custom hooks — failed deployments without ever showing the user why. The detailed failure reason lives in the HookStatusReason of the GetHookResult response, but the CLI only extracted failed Guard Hook annotations from that response and discarded everything else, so users were left with the generic "see hook results for details" message from the stack event. Hooks that fail change set creation (TargetType: CHANGE_SET) were worse off still: that code path never consulted the hook result APIs at all and reported only the change set's status reason.

The annotation formatting is extracted into a shared helper that falls back to the hook result's own HookStatusReason when there are no failed annotations, because for non-Guard hooks that field is the only place the details exist. The stack activity monitor uses this helper when enriching failed hook events. The change set diagnoser gains a step that runs after DescribeEvents yields nothing: it lists failed hooks via ListHookResults, fetches each result for annotations, and reports the details as diagnosis problems before falling back to the generic change set error. Only hooks with failure mode FAIL are considered, since WARN hooks cannot have caused the change set failure. Both lookups degrade gracefully to the previous behavior when the APIs are unavailable, so no new permissions are required; the deploy role's AWSCloudFormationReadOnlyAccess policy already covers ListHookResults.

Before/After

A Lambda Hook targeting change set operations fails the deployment. Before, the user only sees which hook failed, not why (illustrative output):

❌  MyStack failed: Failed to create change set cdk-deploy-change-set: Change set creation failed. The following hook(s) failed: [Example::CFNHook::Full]

After, the detailed reason returned by the hook is fetched from the hook result APIs and included:

❌  MyStack failed: Failed to create change set cdk-deploy-change-set:
MyStack  (AWS::CloudFormation::Stack)
  Hook 'Example::CFNHook::Full' failed: Ingress must not allow 0.0.0.0/0 to non-HTTP(s) ports

The same applies to hooks failing during stack deployment (RESOURCE/STACK targets). Before, the event line carried only the generic reason:

MyStack | 0/2 | 2:34:30 PM | CREATE_IN_PROGRESS | AWS::EC2::SecurityGroup | IngressSG Hook failed with message: see hook results for details

After, the event is enriched with the hook result's status reason, the same way Guard Hook annotations already were:

MyStack | 0/2 | 2:34:30 PM | CREATE_IN_PROGRESS | AWS::EC2::SecurityGroup | IngressSG Ingress must not allow 0.0.0.0/0 to non-HTTP(s) ports

Testing

Verified with unit tests for both code paths (a repro test using the reported hook result payload failed before the fix and passes after; the full toolkit-lib suite passes), and a new integration test that deploys a real Lambda Hook targeting change set operations and asserts the detailed reason appears in the cdk deploy output. The integration test has not been run against AWS yet and will be exercised by the PR build.

Checklist

• This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed
  • Release notes for the new version:

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None