Ask Before Acting: a Structured Question Tool, a Read-Only Exploration Mode, and Plan Approval

Structured questions: why asking must be a tool

The easiest approach lets the model ask in prose: "do you want it to throw or return null?" It looks entirely sufficient. Three reasons it is not.

One: a question in prose has no boundary. After that sentence the loop receives finish_reason: stop — identical to "I am done." The program cannot distinguish "this turn ended" from "this turn is waiting for someone," and the user assumes the Agent hung.

Two: the answer cannot return to the right place. The user's next sentence is a new user message while the question sits in the previous assistant message, a whole turn apart, and binding depends on the model's recollection. As a tool, the answer is a tool message whose toolCallId points back at that question — the binding is structural.

Three, and most valuable: free text asks unclearly. A prose question always ends up shaped like "what do you want to do?", which cannot be answered. A tool has a parameter table:

parameters: {
  type: 'object',
  properties: {
    question: { type: 'string', description: 'one sentence; do not ask two things at once' },
    options: {
      type: 'array',
      description: 'choices, each with value (the short value fed back to you) and label (for the human)',
      items: { type: 'object', required: ['value', 'label'] },
    },
    default: { type: 'string', description: 'the value chosen when the user just presses enter' },
    multi: { type: 'boolean', description: 'allow multiple selections' },
  },
  required: ['question'],
  additionalProperties: false,
},
readOnly: true,

PARAMETERS = {
    "type": "object",
    "properties": {
        "question": {"type": "string", "description": "one sentence; do not ask two things at once"},
        "options": {
            "type": "array",
            "description": "choices, each with value (fed back to you) and label (for the human)",
            "items": {"type": "object", "required": ["value", "label"]},
        },
        "default": {"type": "string", "description": "the value chosen on a bare enter"},
        "multi": {"type": "boolean", "description": "allow multiple selections"},
    },
    "required": ["question"],
    "additionalProperties": False,
}
READ_ONLY = True

Having to fill options forces it to work out the available approaches before it can ask. The parameter table is the floor on question quality, and the schema gives you that floor for free, with no prompt engineering.

readOnly being true is worth a sentence too: asking changes no files, so day five's gate lets it straight through. Making a question require approval creates the absurd chain of asking a question in order to ask a question.

Answer parsing has three traps, all forced by how users actually reply. One: an empty answer is not the absence of an answer — their most common action is pressing enter, meaning "go with the default you named"; take default if there is one, and only otherwise count it as skipped, while still explicitly feeding back "the user did not answer" rather than pretending they picked the first option. Two: accept both an index and an option name — the most natural input is "2," while the model recognizes its own value. Three: feed unrecognized input back verbatim as the answer — the model listed those options and often lists them incompletely, and passing "none of these, I want NaN" back is far more useful than forcing the user to pick among three wrong choices.

As for when to ask, one criterion: ask only when two reasonable readings lead to entirely different changes, and never ask what reading the code would answer. Both extremes cost: ask too much and the user starts pressing enter throughout (so the asking is worthless); ask nothing and you pay in rework.

Read-only exploration mode: a preset of the permission rules

The second part is exploring read-only first. This is the easiest place to go wrong, so the conclusion first:

Read-only exploration mode is not a new permission system; it is a preset of day five's rule table.

Concretely, entering exploration mode does one thing — replace the whole rule table with two rules:

{ decision: 'deny' }                          nothing is permitted
{ tool: 'submit_plan', decision: 'ask' }      except submitting a plan

And read-only tools never reach the rule table: day five's decide() starts with "read-only passes." So glob, grep, read_file and ask_user remain available. "Exploration mode" corresponds to exactly one rule-table replacement in the code.

What happens if you do it the other way: add a mode field, then check it in the loop, in the gate, and inside every write tool. You get three checks that can disagree, and the day they do, the symptom is "it quietly edited files in plan mode." The permission decision must have exactly one entry point in the whole course, a rule more important than any feature today.

Replacing the rule table has one detail that must be right: replace wholesale, never append.

Following from that, another rule: plan mode grants no exception to any command, not even node --test. Running tests during exploration is indeed harmless, but "which commands count as read-only" is an unenumerable judgment — does running tests write snapshot files? does it touch a cache directory? And this mode's entire value lies in a boundary simple enough to state in one sentence: read-only tools all pass, everything else is blocked. Want to run tests? Submit a plan first.

What a blocked call looks like was fixed on day five: the gate returns a tool result with ok false, stating what was refused, why, and which route remains. So the refusal must be written so the model can reroute — in the lab it goes like this:

> run_command({"command":"node --test"})
x run_command fed back 149 chars - this run_command call did not run: this is read-only exploration mode; you may read files, search content and ask the user, but not edit files or run commands.
This is read-only exploration mode and running commands was blocked, so I will read the code with read-only tools.
> read_file({"path":"src/calc.js"})

The third line is the model speaking after reading that refusal. It took another route rather than retrying the same call — day five's "write refusals so it can reroute" pays off today.

What a plan looks like: checkability is the only criterion

The third part is the plan, and its format has one criterion: checkable.

A natural-language plan reads best: "optimize the division's edge handling and add corresponding tests." The problem is that changing one file and changing five both satisfy it. So a plan is four structured fields, each checkable against what actually happened:

verify is the most often omitted: a plan with no verification method can only be judged by eye after execution, while "run node --test, all four cases green" gives execution a hard criterion. files inside steps is the most often fudged — the whole mechanism rests on it, and without it none of the later checking works.

What about a substandard plan? Reject the whole thing; do not fill in the gaps.

There is an ordering issue too: the gate sits before tool execution, so when the user sees the plan the program has not validated it yet. A malformed plan should not disturb the user, so validation moves earlier, into the asking step — a parse failure counts as "the user refused," with the reason fed back for the model to resubmit. That is a pre-check, using the same validation function.

After approval: what is approved is this plan, not unlimited authority

Now today's most elegant part — plan approval introduces no new mechanism.

submit_plan has exactly one trick: it is not read-only. So day five's gate catches it automatically. The rule table judges it ask, so the gate calls the approval callback; answer y and the gate returns null and the tool runs (that is, it really switches back to writable); answer n and the gate returns a tool result with ok false, and the model reroutes on reading "did not run."

Not one AgentEvent type was added, the render layer changed by zero lines, the loop changed by zero lines. What was added is one tool and one rule. That is the second dividend of day five's "approval is a pause inside the loop, not an exception."

Only one thing needed changing, and it belonged there anyway: what is shown to the user. Asking "Confirmation needed: submit_plan" in the terminal says nothing; what must be shown is the whole plan — a render-layer responsibility, so it lives in the render layer:

Plan: add a divide-by-zero guard to divide so the divide by zero case turns green
  1. check for a zero divisor at the top of divide and throw when it is zero  ->  src/calc.js
  2. run the tests and confirm all four cases are green  ->  (read-only, no file changes)
  Verify: run node --test, all four cases green
  Risk: callers relying on divide(1, 0) returning Infinity will start receiving an exception
Approve this plan? y approve and execute / n reject (say what to change)

Note only y and n are offered. Day five's approval had four options, of which a (this whole session) and w (write into the config) mean "stop asking about the same operation later" — and "auto-approve all future plans" erases plan mode's meaning entirely.

How much authority approval grants is this section's crux. Both extremes are wrong: granting nothing means every file in the plan is asked about again during execution — the user just approved a plan naming those files, so asking again is pure harassment, and they soon press y throughout, hollowing the gate; granting everything makes approving this plan indistinguishable from approving "change whatever," and the plan's file list becomes decoration.

The right granularity is the plan itself: allow file by file from files, and nothing more.

for (const file of plannedFiles(plan)) {
  // Judge with the original rule table before allowing: what was already deny stays deny
  const verdict = decide(writeTool, { tool: writeTool.name, path: file }, permissions)
  if (verdict.decision === 'deny') {
    refused.push(file)
    continue
  }
  permissions.rules.push({
    tool: writeTool.name,
    path: file,
    decision: 'allow',
    why: 'in the plan the user already approved',
  })
  granted.push(file)
}

for file in planned_files(plan):
    # Judge with the original rule table before allowing: what was already deny stays deny
    if decide(write_tool, Subject(tool=write_tool.name, path=file), permissions).decision == "deny":
        refused.append(file)
        continue
    permissions.rules.append(
        Rule(tool=write_tool.name, path=file, decision="allow", why="in the approved plan")
    )
    granted.append(file)

That decide check is today's line most worth guarding. Plan-based allowance must not override deny. The rule table has a hard rule against editing the test directory (because tests must not be edited green). Blindly adding an allow per file at approval time lets the model write test/calc.test.js into a plan and bypass that hard rule through one approval — and the user may not read that implication when approving.

So judge before allowing: only what was ask becomes allowed, what was deny stays deny, and the feedback explicitly says approving this plan does not lift that prohibition. The self-test pins it:

v after approval only src/calc.js is allowed; test/calc.test.js was already deny and approval does not lift it; files outside the plan are still asked about individually

Consistency checking during execution: deviations must be nameable

The last part, and the one most often omitted.

After approving a plan, the likeliest problem is not that it does nothing but that it does something else: the plan named one file and three were changed; the plan promised a verification and it declared success right after editing.

What those two deviations share is that neither is an error. Every tool succeeded, the loop ended normally, the terminal is full of ticks. So deviations must be actively checked, the same as yesterday's compaction probes: silent failures are exposed only by active checking.

Collection uses a shape this course has used three times: a transparent wrapper (day seven's persistence and day twelve's usage sampling are both this) — events pass through unchanged while a note is taken in passing, so the loop, the render layer and the tools know nothing about checking. Only writes with ok true are recorded: calls blocked by the gate and failed executions are not "actual changes."

The check table has three items, each stating "so what" rather than just marking a cross:

Plan check: the plan changes 1 file, 2 were actually changed
  v src/calc.js (in the plan)
  ! src/notes.md is not in the plan - ask it to explain why this file was changed
  ! the plan named a verification but the corresponding command was never run - "changed" is not "done"

Those lines come from the lab's deliberately deviating branch. The same plan, taken down the approve-and-follow branch, shows three ticks:

Plan check: the plan changes 1 file, 1 was actually changed
  v src/calc.js (in the plan)
  v the plan's verification was actually run

The two branches differ only in what was actually done, from one identical plan — that contrast is the evidence that plan approval is a mechanism rather than a confirmation dialog.

Two boundaries to close. One: checking looks only at what this execution did, not at whether the code is correct — "is the change right" is verify's job (running the tests), not the checker's. Two: do not print a check table on turns that changed nothing, or every turn floods the screen with "no planned files were changed," and the warning goes unread when it finally matters.

Source Reading

Hands-On Lab

Today leaves five exercises, all five "looks simpler, is worse" traps: appending the two presets after the rule table (so node --test still runs), an empty answer that neither takes the default nor accepts an index, filling in a missing verify, granting all write permissions on approval, and a check table that only counts planned files. The starter passes six of twelve unmodified, all offline.

1. Implement answer parsing: an empty answer takes the default, both index and option name are accepted, unrecognized input passes through as a free-form answer.
2. Change exploration mode to replace the rule table wholesale, and confirm both edit_file and node --test are judged deny while read-only tools pass straight through.
3. Make parsePlan reject the whole plan when verify is missing or no step names files, feeding the reason back to the model.
4. Implement per-file allowance from the plan, judging with decide first — what was already deny must not be allowed.
5. Complete the check table's three columns (outside the plan, not done, verification run or not), run MOCK=1 SELFTEST=1 pnpm start to see 12/12 passed, then use the README's three pipe commands to see approval, refusal and deviation.

Acceptance is five ticks: the self-test prints 12/12 passed; the exploration item prints "the rule table was replaced wholesale, 4 rules to 2 presets"; the end-to-end item prints six tool calls in order with the second run_command carrying blockedBy=approval; the approval item prints "only src/calc.js allowed, test/calc.test.js was already deny"; and the two check-table branches show one all-green and one catching two deviations.

Interview Questions

Today's three questions test when a human goes back in the loop and how that is implemented, not "should an Agent ask for confirmation":

1. When should an Agent stop and ask the user? What does asking too much and asking nothing each cost?
2. How is plan mode implemented? What is its relationship to the permission system?
3. Once a plan is approved, how do you ensure execution did not deviate?

Full prompts, analyses and key points are in this course's day-thirteen question bank. Question two discriminates most — most answer "add a mode field and check it around," and few can say it is merely a preset of the permission rules with exactly one decision entry point.

Checklist and Tomorrow

• I can give the three reasons asking must be a tool rather than prose, and why the third is worth most
• I can explain why the question channel is injected by closure rather than added to ToolContext
• I can name the two answer-parsing traps: empty answers take the default, and both index and option name are accepted
• I can state in one sentence how exploration mode relates to the permission rules, and why there is one decision entry point
• I can explain why the rule table is replaced wholesale rather than appended to (a more specific rule wins)
• I can recite the plan's four fields, and why a substandard plan is rejected rather than patched
• I can explain how "what is approved is this plan, not unlimited authority" is implemented, and why allowance must not override deny
• I can name the check table's three columns, and why "declaring success without running the verification" is also a deviation

Tomorrow is D14, "Checkpoints and Rewind: File Snapshots, Conversation Rollback, and Why They Must Be Independent." Today built the gate before acting; tomorrow builds the way back after acting. They pair up: today's plan tells you in advance what it will touch, tomorrow's snapshots let you restore what it touched. Tomorrow is also week two's last day, and the chapter closes by threading D8 through D14 together.