With verbatim_prompts turned on, can Claude still understand file paths mentioned in user input?
Yes, but differently. With expansion disabled, Claude receives the literal @path/to/file text and can still understand it semantically as "the user is referring to this path" — it just won't automatically fetch the file's contents and splice them into the prompt for you. If your application needs Claude to actually read a given file's contents, with verbatim_prompts on you'd need to accomplish that through a tool call (for example, having Claude explicitly invoke a file-reading tool) rather than relying on message formatting to trigger it automatically.
That distinction is actually a good thing: file reading becomes an explicitly authorizable, loggable, even scope-limitable tool call, rather than an implicit behavior hidden inside text formatting.
If part of my application's message is written by the developer and part is spliced from user input, can I turn on verbatim_prompts for just the user-input portion?
No — verbatim_prompts is a setting at the level of the entire session or each query() call, not a toggle that applies to a specific segment within a message. If your prompt-assembly logic mixes developer-written text with user input in the same message, enabling this option means the entire message skips @path and slash-command parsing, including any portion where the developer intended it to apply.
The more robust approach is to redesign your prompt-assembly logic: move any developer-intended file-expansion or slash-command triggering into explicit tool calls or program logic instead of relying on message formatting itself, so that turning verbatim_prompts on globally doesn't sacrifice any functionality you actually need.
Does turning on verbatim_prompts affect the quality or behavior of Claude's responses?
By design, no — not directly to the model's own understanding or response quality. This option operates on the prompt-preprocessing layer between the SDK and the CLI, not on the model's reasoning behavior. The only difference shows up in functionality that previously relied on @path expansion or slash-command dispatch to work: if your workflow depended on those mechanisms to automatically fetch files or trigger commands, that automation stops working once the option is on, and you'd need to replace it with explicit tool calls.
If your application never relied on either auto-expansion mechanism to begin with, turning this option on should be invisible to the user experience — purely an added layer of protection.
If I'm just using the Claude Agent SDK for an internal tool where all users are my own team members, do I still need verbatim_prompts?
The key risk factor isn't "who the users are" but "whether all the text content in the message was produced by a trusted party." Even if users are your own team members, if the application's message-assembly logic mixes in text from an external source — pasted customer email content, scraped web text, a field returned by a third-party system — that external text could still inadvertently contain a sequence matching the @path or slash-command format, causing unintended behavior. It doesn't need to be a malicious attack; a sheer formatting coincidence can trigger it.
So the right test is "does any text in this message come from something other than the developer's own typing," not "can the people using this tool be trusted."
A common architecture pattern in applications built with the Claude Agent SDK is assembling user input, database fields, or text pulled from an external API directly into the prompt string sent to the Claude CLI. The problem is that the SDK's default prompt-handling behavior interprets certain patterns in a message as "commands" — a sequence like @path/to/file gets expanded into file contents, and a string starting with / can get dispatched as a slash command. If that text wasn't typed by the developer but instead comes from an untrusted source (user-pasted content, a field returned by a third-party system), this creates a concrete injection risk: someone only needs to slip @/etc/passwd or a string disguised as a slash command into their input to have a shot at triggering unintended file reads or command dispatch.
The new ClaudeAgentOptions.verbatim_prompts option (default False) means that, once enabled, user messages are delivered to the CLI exactly as written — no @path file expansion, no slash-command dispatch. In other words, no matter what command-like formatting appears in a Block of text, what Claude receives is plain text itself, with no file-access or command-execution side effect triggered by coincidental formatting. The option works with both the query() function call and the interactive ClaudeSDKClient.connect()/ClaudeSDKClient.query() connection mode, covering both string inputs and async-iterable inputs. One caveat worth noting: this feature requires CLI 2.1.248 or later — enabling the option on an older CLI logs a warning but doesn't halt execution, which means that if your deployment pins an older CLI version, this protection won't actually be active, and you need to separately verify the version number.
If your application's architecture assembles every prompt sent to Claude entirely from developer-controlled text, with no raw external input anywhere in it, verbatim_prompts makes little practical difference, since there's no attacker-controlled input channel to begin with. But the moment any part of your architecture feeds user input, scraped web content, or third-party API responses directly into the message string sent to the CLI without processing, that's a real injection surface — a pattern common in customer-support bots, document-summarization tools, or any application that "reads external content and then answers." Applications like these should treat verbatim_prompts=True as a default protection to turn on, not something patched in after an incident.
It needs to be said plainly that verbatim_prompts solves a specific, concrete attack surface: unintended file reads or command dispatch triggered through @path expansion and slash-command formatting. It doesn't address the broader prompt-injection problem — for instance, an attacker using natural language within input text to persuade the model to ignore prior instructions, or to induce output it shouldn't produce. Those problems still require other mitigations like system-prompt design and output validation. Treating verbatim_prompts as the only line of defense would be a misunderstanding — it's one layer in a defense-in-depth strategy, not the whole defense.
If your team is building applications with the Claude Agent SDK that touch external input — customer-support systems, content-analysis tools, or any architecture that feeds third-party text into a prompt — now is the time to audit which message-assembly paths contain untrusted raw text, then turn on verbatim_prompts for those paths, while confirming the deployment's CLI version is 2.1.248 or later, since otherwise the switch won't actually take effect. Security options like this are cheap (a single boolean parameter), but waiting until an actual incident to add them usually costs far more than the ten minutes it takes to check now.