Claude Code Input Pipeline: Three Paths Before the Model Runs

The agent loop starts when the model runs.

That is the wrong frame.

In Claude Code, a significant amount of work happens before the model is called — routing input, pre-executing likely continuations, and generating suggestions for what the user might type next.

File structure

src/
└── utils/
    ├── processUserInput/
    │   └── processUserInput.ts
    ├── promptSuggestion/
    │   ├── generatePromptSuggestions.ts
    │   └── promptSuggestionState.ts
    ├── speculation/
    │   ├── speculativeExecute.ts
    │   └── speculations.ts

The pre-turn pipeline

The 3-path router matters for permissions

The reason processUserInput is 606 lines is not routing complexity alone.

Each path carries its own trust and permission model:

Text path: Goes to the query loop. The model decides what tools to call. Permissions apply at tool execution time.

!bash path: Executes a shell command directly. Requires the user to be in a trust context that allows arbitrary shell commands — a different check than tool permissions.

/slash path: Resolves a command from the command registry. Must verify the command exists and is available in the current context (not all commands are available in non-interactive mode, pipe mode, or bridge sessions).

Merging these paths into one would mean applying the least-restrictive permission model to all three, which would let /slash and !bash bypass tool permission gates, or force text input through unnecessary checks.

The split is the correct design.

Why speculation needs a discard path

Speculative execution is only safe if the discard path is clean.

The risk: a speculative turn calls a tool — writes a file, runs a shell command, makes an API call — and then the user's actual input does not match the speculation.

Claude Code handles this by restricting what speculative turns can do.

Speculation runs a model call but does not allow side-effectful tool execution. Read-only operations (file reads, search) are safe to speculate. Write operations and shell commands are not.

The SpeculationState in AppState tracks whether a speculative call is in flight, so the UI can show a loading indicator without revealing which specific completion was being speculatively computed.

Suggestions as latency infrastructure

The prompt suggestion pipeline is easy to dismiss as a UI convenience.

It is actually latency infrastructure.

The suggestion pipeline runs during idle time — after a turn completes but before the user types their next input. If the user's next input matches a suggestion, speculation may have already completed the corresponding turn.

That is the full loop:

1. turn completes
2. suggestions generated in background
3. speculation starts on top suggestion
4. user submits — if it matches, result is promoted; if not, discard and run fresh

The latency benefit only materializes when the suggestion accurately predicted what the user would type. That accuracy depends on the quality of the suggestion prompt and the consistency of the user's working patterns.

type InputPath = 'text' | 'bash' | 'slash'

interface ClassifiedInput {
path: InputPath
raw: string
payload: string  // stripped of prefix for bash/slash
}

function classifyInput(raw: string): ClassifiedInput {
if (raw.startsWith('!')) {
  return { path: 'bash', raw, payload: raw.slice(1).trim() }
}
if (raw.startsWith('/')) {
  return { path: 'slash', raw, payload: raw.slice(1).trim() }
}
return { path: 'text', raw, payload: raw }
}

async function processUserInput(
raw: string,
context: SessionContext
): Promise<ProcessResult> {
const classified = classifyInput(raw)

switch (classified.path) {
  case 'bash': {
    // Check shell permission before executing
    checkPermission(context, 'shell_execute')
    return executeBashCommand(classified.payload, context)
  }
  case 'slash': {
    // Resolve command from registry — fails if not available in this context
    const command = resolveCommand(classified.payload, context)
    return executeSlashCommand(command, context)
  }
  case 'text': {
    // Check if speculative execution already has a result
    const promoted = tryPromoteSpeculation(classified.payload, context)
    if (promoted) return promoted
    // Otherwise enter the query loop
    return enterQueryLoop(classified.payload, context)
  }
}
}

// Speculation: starts before user submits
async function speculativeExecute(
suggestion: string,
context: SessionContext
): Promise<SpeculationResult> {
const state = getSpeculationState()
if (state.inFlight) return // only one speculation at a time

setSpeculationState({ inFlight: true, target: suggestion })

try {
  // Model call with read-only tool restriction
  const result = await runQueryLoopReadOnly(suggestion, context)
  setSpeculationState({ inFlight: false, result, target: suggestion })
  return result
} catch {
  setSpeculationState({ inFlight: false, result: null, target: null })
  throw
}
}