diff --git a/docs/rfds/permission-request-feedback-text.mdx b/docs/rfds/permission-request-feedback-text.mdx new file mode 100644 index 000000000..aa41b2c9f --- /dev/null +++ b/docs/rfds/permission-request-feedback-text.mdx @@ -0,0 +1,141 @@ +--- +title: "Permission Request Feedback Text" +--- + + + +Author(s): [githubhandle](url) + +## Elevator pitch + +> What are you proposing to change? + + + +Allow including additonal feedback text along with the response to a tool permission request for agents that support it. Allows approving a request while immediately providing additonal context or direction the agent might need, or alternatively declining a request while providing inline redirection. This would allow exposing functionality like Claude Code’s “Yes, and tell Claude what to do next” and “No, and tell Claude what to do differently” response options. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +The current protocol only supports reporting the selected choice (or `"cancelled"`), which no ability to include additional information for the agent. If the prompt is approved, there’s no ability to provide feedback until the next prompt turn. If the prompt is declined, the agents work is halted. The latter is fine for the main agent, as the user's next prompt can redirect it in the appropriate direction. However, when the prompt is from a subagent, it can lead to a painful choice between allowing an undesired action or throwing away all of the subagent’s work leading up to the prompt. + +## What we propose to do about it + +> What are you proposing to improve the situation? + + + +Allow an agent to opt in to receiving optional additional feedback / steering text paired with the selection outcome when supported. + +## Shiny future + +> How will things will play out once this feature exists? + + + +When approving a tool-call, the user would be able to provide relevant context / instruction to the agent, e.g., “the output of that command with be incomplete due to X” or “there’s an additional example that might be helpful at Y.” When rejecting a call, the user would be able to provide inline redirection instead of stopping the agent’s work. E.g., “please use cargo metadata to find the exact dependency in use instead of searching the whole cargo cache”. + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + + + +Extend `PermissionOption` with a fourth optional field: + +`allowFeedback: bool` (optional, default `false`) – The agent supports receiving additional free-form notes / feedback / steering along with this option. + +If the option is `true`, the client MAY provide a way for the user to enter additonal text to accompany the response. + +This is specified per option, since not all options need support feedback. (E.g., in Claude Code, the always-allow option does not.) + +If the user opts to provide additional feedback with their selection, it should be returned via a new outcome field: + +`feedback: string` (optional, default `null`) – The additional feedback provided by the user, `null` or omitted if none was provided. + +The whole round trip might then look like this: + +```json +{ + "title": "Run the test suite?", + "subject": { + "type": "command", + "command": "cargo test", + "cwd": "/home/user/project", + "toolCallId": "call_001", + "terminalId": "term_001" + }, + "options": [ + { + "optionId": "allow-once", + "name": "Allow", + "kind": "allow_once", + "allowFeedback": true + } + ] +} +``` + +```json +{ + "jsonrpc": "2.0", + "id": 5, + "result": { + "outcome": { + "outcome": "selected", + "optionId": "allow-once", + "feedback": "Please also run the test suite for the foo crate" + } + } +} +``` + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + + + +None, yet. + +### What alternative approaches did you consider, and why did you settle on this one? + + + +Naming choices: feedback, steering, note, et cetera. + +## Revision history + + + +Initial version