preToolUse: additional_context works but isn't documented — is it officially supported?

Support Help
,
1

Hi,

We’re building a solution that uses hook-provided additional_contextfield to guide the agent’s next actions.

This behavior works in both Claude and Cursor, but Cursor doesn’t currently document support for additional_context in preToolUse. We’d like to confirm whether this behavior is officially supported before relying on it.

We noticed a mismatch between the documentation and the actual behavior.

image
image754×1005 73 KB

Documentation

According to the documentation, preToolUse supports the following output fields:

  • permission

  • user_message

  • agent_message

  • updated_input

additional_context is documented only for postToolUse and sessionStart, not for preToolUse.

What we observed

Our preToolUse hook returns:

{
  "permission": "deny",
  "additional_context": "<instructions + random nonce>"
}

The tool call is denied, and the model clearly receives the additional_context.

To verify this, we generate a new random nonce on every hook invocation and store it only in an external log outside the workspace. The agent later repeats that nonce and follows the supplied instructions, confirming that the information could only have been received through additional_context.

Question

Is additional_context officially supported for preToolUse, with the documentation simply being out of date, or is the current behavior incidental and not something we should rely on?

5

Hey, thanks for the detailed write-up, especially for checking via the nonce. That’s exactly what clears up all the questions.

Yep, additional_context in preToolUse is officially supported and intentional behavior, including the deny path ({"permission": "deny", "additional_context": ...}). You can rely on it. Your nonce check correctly confirms what should be happening, the context makes it to the model end to end.

The mismatch is in the docs. The preToolUse output table is outdated and doesn’t list additional_context. I’ve passed this to the team so they can fix the hooks page. I’ll reply here once the docs are updated.

Let me know if any other integration questions come up.