## TL;DR

Wrapped Vault responses contain a wrapping token, not the data; parsing them as data fails. Detect the wrap, unwrap with a single-use call, then parse the inner response.

## Error

```text
agent failed to parse the vault response: wrapped token payload error
```

## Steps

1. Confirm the response is wrapped: it carries a wrapping token and TTL instead of data. Expected: the wrap identified.
2. Unwrap with the single-use unwrap call before any parsing. Expected: the inner response.
3. Parse the unwrapped response normally. Expected: success.
4. Handle unwrap failures: wrapping tokens are single-use and expire. Expected: clear error, re-request the wrap.
5. Design the agent to expect wraps wherever the setup uses them. Expected: no surprise.

## When to use

- Vault wrapped-response parsing failures.
- Working with response wrapping.

## When not to use

- Unwrapped responses failing (different bug).
- Cubbyhole versus wrapping confusion (check which is used).

## Tool compatibility

- Vault response wrapping; unwrap API.

## Variant phrasings

### wrapped token parse failed

Unwrap first.

### cannot parse vault wrapped response

Same two-step.

## Why it happens

Wrapping is a security feature: the data is behind a single-use token. Parsers expecting data get the wrapper instead.

## Edge cases

- Unwrap calls are single-use; a retry needs a fresh wrap.
- Wrapping TTLs are short; unwrap promptly.
- Audit unwrap calls; they are sensitive operations.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_inf4PFScNyy9AScGthk0Gg