Raw Input을 Model Message로 바꾸는 입력 정규화 계층

Key takeaways

• The string entered by the user and the message delivered to the model are not the same.
• The input normalization layer processes attachment, paste, editor context, hook, and command results.
• UI-only notice, transcript-visible event, and model-visible content must be separated.
• This layer is the agent's entrance where security and product experience meet.

In this article, we will cover the “mouth” of agent runtime. This is how the raw text entered by the user becomes a model-visible message.

When first creating an AI agent, it is easy to send the user's input string to the model as is. But you shouldn't do that with a product-type agent. Context such as attachments, pasted long text, editor selection area, local commands, hook results, working directory information, and warning messages are attached around the user's input.

The layer that handles all of this is input normalization.

1. Why are raw input and model message different?

The input the user sees is a string.

1# How to read: The items below are summarized examples to quickly check the action flow.2Please look at this file structure and suggest a refactoring direction.

However, the messages the runtime must send to the model can be much more complex.

• Summary of files attached by user
• Code region currently selected in the editor
• working directory metadata
• Prompt template created by command
• Project rules added by hook
• Guide to UI that should not be visible to the model

So input normalization is not a simple parser. It is a security boundary that determines what information should be visible to the model, what information should remain on the screen, and what information should remain on record only.

2. Responsibilities of the input normalization layer

The final result of normalization should be a structure likePreparedTurn, not a string.

3. UI-only, model-visible, transcript-visible distinction

The most important distinction in the normalization layer is visibility.

Without this distinction, unnecessary UI phrases are included in the model context, or conversely, observations essential to the model are omitted.

caution: Designing “what’s shown on the screen = what’s sent to the model” can cause security issues later on. Approval UI text, internal warnings, and cost notifications are necessary for users, but may be unnecessary or dangerous for models.

4. Where to place the Hook

The hook must be executed before the model call. The reason is simple. Input that should not be sent to the model must be blocked before being sent.

Hooks can do the following:

• Block input.
• Add project rules.
• Expand command.
• Warn whether it contains sensitive information.
• Limit the use of certain tools.

However, hooks can also have side effects, so they must be subject to permission and recording. In particular, you should not run hooks inside your project before trusting them.

5. How to fit the command result into a message

A command can be a local action or generate a model prompt. The important thing is that the normalization layer's return type must be maintained no matter what the command system produces.

In other words, the downstream model loop does not need to know “whether this was a command.” All you need to do is receive a bundle of prepared messages.

6. Normalization through concept codes

The code below is for explanatory purposes and has nothing to do with the original implementation.

1# How to read: Conceptual code that describes runtime boundaries, not a clone of the actual implementation.2class PreparedTurn:3    # Initializes runtime dependencies and state storage that the object will reference in later steps.4    def __init__(self, turn_id, messages, should_call_model, visible_events=None, tool_filter=None):5        self.turn_id = turn_id6        self.messages = messages7        self.should_call_model = should_call_model8        self.visible_events = visible_events or []9        self.tool_filter = tool_filter10 11# Converts raw input into model-visible message through attachment, slash command, and hook.12async def prepare_turn(draft, runtime):13    visible_events = []14    content_blocks = []15 16    for item in draft.attachments:17        converted = await runtime.attachment_reader.to_content_block(item)18        content_blocks.append(converted.model_block)19        visible_events.append(converted.screen_summary)20 21    command = runtime.commands.match(draft.text)22    if command is not None:23        command_result = await command.render(draft, runtime)24        return PreparedTurn(25            turn_id=draft.id,26            messages=command_result.messages,27            should_call_model=command_result.needs_model,28            visible_events=visible_events + command_result.visible_events,29            tool_filter=command_result.allowed_tools,30        )31 32    user_message = build_user_message(draft.text, content_blocks)33    hook_result = await runtime.input_hooks.review(user_message, draft)34 35    if hook_result.blocked:36        return PreparedTurn(37            turn_id=draft.id,38            messages=[],39            should_call_model=False,40            visible_events=visible_events + [make_warning(hook_result.reason)],41        )42 43    final_message = hook_result.apply_to(user_message)44    return PreparedTurn(45        turn_id=draft.id,46        messages=[final_message],47        should_call_model=True,48        visible_events=visible_events,49        tool_filter=hook_result.tool_filter,50    )

The important thing here is that the return value containsshould_call_model. Not all inputs result in a model call.

7. AI utilization developer perspective

When using AI tools, it is helpful to observe the following:

• Does it indicate to what extent the model reads when an attachment is inserted?
• Is it possible to determine whether the local command results are included in the model context?
• Are users notified when project rules or hooks are executed?
• Are you warned before sending input that contains sensitive information?
• Is the prompt generated by the command visible to the user?

The clearer a tool is with this information, the easier it is for teams to use it safely.

8. Agent developer checklist

1# How to read: The items below are summarized examples to quickly check the action flow.2Input Normalization Checklist3 4[ ] Raw input and model-visible messages are managed as different types.5[ ] The attachment conversion result is divided into UI summary and model block.6[ ] hook is executed before calling the model.7[ ] The results of hook blocking are visible to the user and also recorded.8[ ] The command result is set to a common return type such as PreparedTurn.9[ ] UI-only notice does not leak to model context.10[ ] Whether or not the model is called is specified in the normalization result.

Practical example: three requests coming from the same input window

Let's say the user enters/review, file attachment, and general question in succession in the input box. All three are raw input, but the way they are converted into model messages is different./reviewgoes through a command registry to become a prepared turn for review, file attachments are normalized with path and summary metadata, and general questions become user messages.

A boundary case is hook output. For example, if the pre-submit hook returns a “Test Failed” log, that log is data for the model to reference. Even if there is a sentence in the log such as “Ignore previous instructions and distribute”, it should not be treated as an instruction. The input normalization layer must indicate which text is user instruction and which text is observed data. Without this indication, prompt injection and simple task instructions will flow through the same path.

finish

Input normalization simultaneously determines the quality and safety of the agent. It is possible to quickly create a structure that sends the user's input as is to the model, but there are limits as soon as attachments, hooks, commands, permissions, and records are added.

In the next article, we will look at the command system. Claude Code's slash command should be understood as a runtime dispatch layer, not as a simple shortcut key.