Skip to content

Latest commit

 

History

History
1387 lines (1209 loc) · 108 KB

command-line.md

File metadata and controls

1387 lines (1209 loc) · 108 KB
id CMDLINE
title command lines
status proposed
governs
crates/agent/src/cmdline.rs
crates/agent/src/exec.rs
crates/agent/src/tools.rs
crates/agent/src/tools/offered.rs
crates/agent/src/turn.rs
crates/agent/src/turn/hooked.rs
crates/agent/src/turn/result.rs
crates/agent/src/turn/delegate_end.rs
crates/agent/src/turn/setup.rs
crates/agent/src/turn/round_steps.rs
crates/agent/src/turn/prompts.rs
crates/agent/src/turn/task.rs
crates/agent/src/turn/sentences.rs
crates/agent/src/programs.rs
crates/core/src/command.rs
crates/core/src/pure.rs
crates/core/src/permissions.rs
crates/core/src/policy.rs
crates/agent/src/confirm.rs
crates/tui/src/confirm.rs
crates/tui/src/confirm/run.rs
crates/ui-bridge/src/wire.rs
guards
symbol
cmdline::compile
symbol
Policy::before_plan
symbol
Policy::read_output
documented-by docs/website/docs/reference/tools.md

Scope

Letting the planner express a command the way a person would write one, and what that costs. Replaces the argv-array surface of run.md as the planner's spelling, keeps every effect that spelling had, and adds the three things its absence made impossible: filtering at the source, reading a result without a second round trip, and running something long without holding the turn.

Shell mode, the ! prompt, is shell-mode.md and is untouched. It runs a line through a real shell because a person typed it. Nothing here does that.

The parity target

What the equivalent tool in Claude Code offers, as the list this spec is measured against:

Claude Code run today This spec
Command spelling one shell string array of argv stages one command line, compiled
|, &&, ||, ; yes pipe only yes
Redirection yes no yes, as a write destination
Globs yes, by the shell no yes, by the harness
$(...), backticks yes no refused, except NAME="$(cmd)" prog in the assignment prefix under bypass (CMDLINE-17)
$VAR yes no refused, except NAME=$VAR prog in the assignment prefix under bypass (CMDLINE-17)
Output to the model direct text reference, then a second call direct where the label allows
Truncation head and tail kept none head and tail kept
Deadline per call, 2min default, 10min ceiling fixed 300s per call, ceiling
Background yes, wakes on exit no yes, wakes on exit
Working directory persists between calls per call persists between calls
Shell state (export, functions) does not persist n/a does not persist
Permission rules per sub-command prefix per stage per compiled stage

The two rows in bold are where parity is refused on purpose, and CMDLINE-2 says why. The one exception is narrow, exists only in bypass mode, and is CMDLINE-17. Everything else is adopted.

Why the shell exclusion said never, and what changes

shell-mode.md ends with a clause saying the planner gets no shell tool, ever, "not behind a capability, not behind an approval prompt". run.md gives the reasoning: a shell string is destination and payload at once, so there is nothing in it a person could approve on its own, and a parser that tried to work out what it means would be racing a shell it does not control.

Both halves of that are about handing a string to an interpreter. Neither is about the syntax. The move here is to keep the ban on the interpreter and drop the ban on the notation:

The planner does not get a shell. It gets shell syntax, which the harness compiles into the same argv stages run executes today, and refuses to compile when it cannot say exactly what would happen.

Nothing is ever passed to sh -c. The compiled plan is what runs. Each stage is spawned with an argument vector by the absolute path its name was found by, after a check that the path still leads to the binary it resolved to, through the same process plumbing as today. So:

  • The routing field exists again. It is the compiled plan: a list of stages with resolved binaries and literal argv, plus every file the plan would write. That is a thing a person can read and endorse, which is the property run.md protects by having a person endorse argv, and the property a raw string lacked.
  • The parser is not racing anything. It is not predicting what a shell will do with a string, because no shell will ever see the string. It is the only thing that reads it, and its output is the whole of what happens.
  • Ambiguity is refused, never guessed. A construct the compiler cannot fully resolve is an error, and there is no path from that error to running the line anyway.

The distinction to hold onto is the same one run.md already draws, moved one step: it is not that shell strings turned out to be acceptable, it is that the exclusion was about interpretation and a compiled plan is not interpreted.

Clauses

CMDLINE-1: the planner sends a command line, and it is compiled rather than interpreted

run { command: "grep -rn kBraveWalletDisabledByPolicy components/ | head -30" }

The line is parsed by this repository's own grammar into an ordered plan of stages, each a resolved absolute path and a literal argument vector, together with the plan's write set, its read set, and its control flow. That plan is what executes, through the existing argv spawner. No shell is started at any point, and no part of the line is ever concatenated back into a string that something else parses.

An argument that survives compilation is final. ; rm -rf / inside quotes is one argument and arrives as one argument, because the only thing that ever split the line was the compiler, and it already ran.

verified-by: bravebot_agent::tools::run_takes_one_command_line_and_nothing_else verified-by: bravebot_agent::turn::a_line_with_a_pipe_is_compiled_into_its_steps verified-by: bravebot_agent::exec::a_command_line_runs_as_the_plan_it_compiled_to verified-by: bravebot_agent::exec::a_command_line_chains_its_steps verified-by: bravebot_agent::exec::a_metacharacter_inside_quotes_reaches_the_program_as_one_argument verified-by: bravebot_agent::exec::a_redirection_inside_quotes_writes_no_file verified-by: bravebot_agent::cmdline::a_step_carries_the_file_its_name_resolved_to

CMDLINE-2: the grammar is closed, and a refusal is never a fallback

Accepted, and nothing else:

Construct Form
Simple command word...
Pipeline cmd | cmd | …
Sequencing &&, ||, ;
Grouping ( … ) for sequencing only, no subshell semantics
Quoting '…', "…", \
Redirection >, >>, <, 2>, 2>>, 2>&1, &> with a literal target
Globs *, ?, […], ** in operand position
Brace expansion {a,b}, {1..9}
Home leading ~
Per-command environment NAME=literal cmd
Per-command environment from a variable or a command, bypass mode only NAME=$VAR cmd, NAME=${VAR} cmd, NAME=a-$VAR-b cmd, NAME="$(cmd)" cmd, NAME=$(cmd) cmd, in the assignment prefix of a program and nowhere else (CMDLINE-17)

Refused, as a compile error with the offending span named:

Construct Why
$(…), `…` a command whose text is computed is a destination nobody saw; inside double quotes it is still one, and the refusal says single quotes pass it as text. Outside bypass mode this holds everywhere; in bypass mode $(…) is accepted as the value of an assignment in front of a program (CMDLINE-17) and refused everywhere else, and a backtick is refused everywhere, an assignment value included
<(…), >(…) same, plus a file descriptor nobody named
$VAR, ${…} the value is not in the line, so the plan is not in the line; a $ followed by no name, brace, parenthesis, special parameter or quote (the end anchor in grep -E "x$") is an ordinary character, and a literal one before a name is written '$' or \$. In bypass mode only, and only in the value of an assignment in front of a program, $NAME and ${NAME} are accepted (CMDLINE-17); ${X:-y}, ${#X}, $1 and the like stay refused
$? the exit status of an earlier step is not in the line; the refusal names the whole $? and says the run result already reports how each step ended (RUN-13) and that single quotes pass the characters as text
$$, $@, $*, $#, $-, $! no shell holds parameters between the steps of a line, so there is no value for these to stand for; the refusal names both characters and says single quotes pass the text as one argument
$'…', $"…" a quote after a $ asks a shell to read escapes, and escapes are not read; the refusal names the whole quoted text (to the end of the line where it is never closed, a backslash keeping the next character inside it) and says a newline comes from a file or from standard input
$((…)) arithmetic is a language, and a language needs an interpreter; inside double quotes it is still one, and the refusal says single quotes pass it as text
& backgrounding is a parameter of the call, not a token in the line
<<, <<< here-documents are content wearing the shape of syntax
eval, source, ., exec, trap reintroduce interpretation by name
cd, pushd, popd, export each stage is spawned fresh, so a stage of these names changes nothing for the stages after it; the refusal says the call's directory argument is how a line runs elsewhere and that NAME=value in front of a program sets a variable for it
ulimit, umask, unset, alias, unalias, hash, wait each is a shell builtin whose effect stays in the shell that runs it, and a host may ship a program of the name that runs it in a shell of its own and exits zero; a stage of these names changes nothing for the stages after it, in any form including a read. The refusal says so and, for ulimit and umask, that the whole line is written as sh -c '... ulimit ...', which is approved as one line; for alias and unalias that an alias defined in one stage is not seen by the other stages and the host shell does not expand aliases in a non-interactive script, so the command is written out; for the others it says the whole script goes inside sh -c '...'
if, while, for, case, function control flow is a program
! history expansion is text the user typed reaching a line the planner wrote
( or ) written onto the end of an argument grouping is syntax, so an argument holding a parenthesis has to be quoted, and the refusal says so
a glob in program position a program worked out from what is on disk is a program that changes when the tree does

A refusal returns an error and runs nothing. There is no degraded mode, no "fall back to sh -c", no "run the prefix that did compile". A compiler that can be made to give up and hand the string to a shell is a shell with extra steps, and it is the single change that would void every clause here.

Why $VAR is refused when a shell would allow it. The plan a person endorses has to be the plan that runs. rm -rf "$D/build" is endorsable only if D is known at the prompt, and if it is known then the planner could have written it. Substituting it before the prompt makes the feature pointless; substituting it after makes the endorsement a lie. A closed set of harness-supplied names (the workspace root, say) could be admitted later by expanding them at compile time, which is the same thing as the planner having written them.

The one exception, bypass mode only. Under bypass nobody endorses a plan, so the objection above has no prompt to make false, and a value taken from the environment or from a command in the assignment prefix is admitted there and nowhere else. The exception is CMDLINE-17, it covers the assignment prefix of a program and nothing more, and outside bypass every form in the tables above is refused exactly as written.

verified-by: bravebot_agent::cmdline::a_simple_command_is_its_program_and_its_operands verified-by: bravebot_agent::cmdline::a_pipeline_keeps_its_stages_in_order verified-by: bravebot_agent::cmdline::and_binds_tighter_than_a_semicolon verified-by: bravebot_agent::cmdline::parentheses_group_a_sequence verified-by: bravebot_agent::cmdline::a_backslash_makes_the_next_character_ordinary verified-by: bravebot_agent::cmdline::each_redirection_form_is_read_as_the_stream_it_names verified-by: bravebot_agent::cmdline::a_glob_survives_as_a_pattern_and_a_quoted_one_does_not verified-by: bravebot_agent::cmdline::braces_are_alternatives_or_a_range verified-by: bravebot_agent::cmdline::a_leading_tilde_stands_for_a_home_and_a_later_one_does_not verified-by: bravebot_agent::cmdline::an_assignment_in_front_of_the_program_is_environment verified-by: bravebot_agent::cmdline::a_command_whose_text_would_be_computed_is_refused verified-by: bravebot_agent::cmdline::process_substitution_is_refused verified-by: bravebot_agent::cmdline::a_variable_is_refused verified-by: bravebot_agent::cmdline::a_dollar_that_names_nothing_is_an_ordinary_character verified-by: bravebot_agent::cmdline::a_dollar_that_opens_an_expansion_is_still_refused verified-by: bravebot_agent::cmdline::a_refused_special_parameter_or_quoted_text_is_named_whole verified-by: bravebot_agent::cmdline::the_exit_status_refusal_says_the_run_result_reports_each_steps_status verified-by: bravebot_agent::cmdline::the_special_parameter_refusal_says_no_parameters_are_kept_and_single_quotes_pass_the_text verified-by: bravebot_agent::cmdline::the_dollar_quote_refusal_says_escapes_are_not_read_and_a_newline_comes_from_a_file verified-by: bravebot_agent::tools::the_run_description_names_the_special_parameters_and_the_dollar_quote_as_refused verified-by: bravebot_agent::cmdline::the_variable_refusal_names_the_quoting_that_works verified-by: bravebot_agent::cmdline::the_substitution_and_arithmetic_refusals_name_single_quotes verified-by: bravebot_agent::cmdline::arithmetic_is_refused verified-by: bravebot_agent::cmdline::backgrounding_is_refused verified-by: bravebot_agent::cmdline::a_here_document_is_refused verified-by: bravebot_agent::cmdline::a_program_that_reintroduces_interpretation_is_refused verified-by: bravebot_agent::cmdline::a_word_that_sets_shell_state_is_refused_wherever_it_stands verified-by: bravebot_agent::cmdline::a_word_that_only_looks_like_shell_state_is_not_refused verified-by: bravebot_agent::cmdline::a_shell_builtin_is_refused_wherever_it_stands verified-by: bravebot_agent::cmdline::the_ulimit_refusal_says_to_put_the_whole_line_in_sh_c verified-by: bravebot_agent::cmdline::the_other_builtin_refusals_say_what_is_true_of_them verified-by: bravebot_agent::cmdline::a_word_that_only_looks_like_a_shell_builtin_is_not_refused verified-by: bravebot_agent::cmdline::a_word_that_opens_control_flow_is_refused verified-by: bravebot_agent::cmdline::an_unquoted_exclamation_mark_is_refused verified-by: bravebot_agent::cmdline::an_unquoted_parenthesis_written_onto_an_argument_says_to_quote_the_argument verified-by: bravebot_agent::cmdline::a_parenthesis_not_written_onto_an_argument_keeps_the_general_refusal verified-by: bravebot_agent::cmdline::a_pattern_in_program_position_is_refused verified-by: bravebot_agent::cmdline::quoting_makes_a_refused_construct_ordinary_text verified-by: bravebot_agent::cmdline::a_line_that_half_compiles_yields_nothing

CMDLINE-3: what a person endorses is the compiled plan, not the line they were sent

The prompt shows the plan: each stage's resolved binary and argv with argument boundaries visible, each file the plan may write, and the directory it runs in. The line as the planner spelled it is shown as well, above the plan, as context, but it is not what the endorsement binds to.

An endorsement binds to the plan. Two different lines that compile to the same plan are the same endorsement; one line that compiles to two different plans on two occasions, which glob expansion makes possible, is two endorsements.

Why. The routing field is the thing that decides where an effect lands, and after compilation that is the plan. Binding to the text would let a change in the working tree change what a prior approval covers without the text changing at all.

verified-by: bravebot_tui::confirm::run::a_run_prompt_shows_the_plan_it_would_endorse verified-by: bravebot_tui::confirm::run::a_run_prompt_shows_the_line_the_model_wrote_as_context verified-by: bravebot_tui::confirm::run::a_run_prompt_lists_every_file_the_line_would_write verified-by: bravebot_ui_bridge::wire::a_run_prompt_carries_the_line_the_planner_wrote_beside_the_plan_it_compiled_to verified-by: bravebot_ui_bridge::wire::a_call_that_was_never_spelled_as_a_line_says_so_rather_than_leaving_the_field_out verified-by: bravebot_core::command::a_plan_shows_its_resolved_binaries_and_argument_boundaries verified-by: bravebot_core::command::two_plans_never_encode_alike verified-by: bravebot_core::command::the_line_a_plan_came_from_is_not_part_of_what_it_encodes verified-by: bravebot_core::policy::an_endorsement_does_not_authorise_a_differently_joined_plan verified-by: bravebot_core::policy::an_endorsement_does_not_authorise_a_plan_that_writes_elsewhere

CMDLINE-4: globs are expanded by the harness, before the prompt, and bounded

Expansion happens against the workspace at compile time, so the person sees the file list rather than the pattern. A pattern matching no file is passed to the program as written, as a shell without failglob does, so find . -name *.md gives find the pattern *.md when no .md file is where it runs, and the plan shows *.md. A pattern that matches is replaced by the files it matches, so a pattern meant for the program is written quoted, as in find . -name '*.md'.

An option carrying a value is not a file pattern. A word that starts with a dash and names the option before an = that comes ahead of any pattern, such as --include=*.md, stands for itself. It is never looked up, so it is passed as written whether or not anything matches it, and a file named like it cannot change what the program receives. A dash with no name before the =, a pattern ahead of the =, and a dash with no = are still patterns.

Expansion is bounded. Past the bound the compile fails and says the count, rather than putting a thousand paths in front of a reader who will approve them unread.

The names a pattern matched are for the person, not the planner. What is said to the planner about a line is said in the words the planner wrote: the result of a run, the account of a job that started, moved or ended, an error that the line did not start or run, and a refusal by a deny rule, which names the program and not its operands. The expanded plan is what the person is shown and endorses, so a file name read out of a directory nobody vouched for is never spelled into a sentence the driver writes to the planner. The names are drawn with a control character, a character that draws as nothing and the other characters PROMPT-1 lists written as \u{..}, so a name holding one does not draw as another name.

The directory the line ran in and the file each redirection names are told in the words the planner wrote, with a .. that lands in an added directory told as the workspace spells it for the file tools. Where a link in that tree led is a name whoever wrote the tree chose, so it is drawn for the person and never spelled into a sentence for the planner. That holds for a file a substitution's own line could not open as well (CMDLINE-17): it is named once, under the directory as typed.

A name a pattern matched is a path only where the program reads it as one. The compiled plan records which arguments a pattern produced. Such an argument counts toward the proof of CMDLINE-8 only in a position where the audited program reads it as a file, and then the trust map's answer for that path is its label. In any other position, such as an instruction operand like basename's or grep's pattern, an option, or an option's value, the program may print the name, and no path in the read set answers for it. The step is then not read-proven, so the line is asked about and its output is untrusted. basename incoming/* asks and its output is quarantined; basename 'incoming/*' passes the pattern as written and keeps the proof road; and cat incoming/* takes its label from what the map says about incoming/. A matched name starting with -, such as a file called --format=x matched by stat -c %s *, is read as an option and refuses the proof the same way.

Ignored directories are ignored the way the tree walk ignores them, so ** does not descend into .git or node_modules.

A leading ~ stands for the person's home directory, which is the directory ~/.bravebot sits inside and never that directory itself. run is given it separately from the state directory it is given everything else, because a home-relative path the planner writes names a file of the person's own: resolved against the state directory, every one of them would instead name a file in the directory holding this program's settings, credentials and session records. A delegate resolves a ~ against the directory its parent did, and the interface expands a ~ somebody types against the same answer, so the two spellings cannot name different files. A machine naming no home directory refuses the ~ rather than inventing one.

Why bounded. An approval prompt long enough that nobody reads it is a prompt that grants everything and asks nothing.

verified-by: bravebot_agent::cmdline::a_pattern_becomes_the_files_it_matches verified-by: bravebot_agent::cmdline::a_pattern_matches_within_one_segment_and_a_tree_across_them verified-by: bravebot_agent::cmdline::a_pattern_matching_nothing_is_passed_through_as_written verified-by: bravebot_agent::cmdline::a_pattern_for_find_matching_nothing_here_reaches_find_as_written verified-by: bravebot_agent::cmdline::an_option_value_pattern_is_passed_through_as_written verified-by: bravebot_agent::cmdline::an_option_value_pattern_is_not_replaced_by_a_file_named_like_it verified-by: bravebot_agent::cmdline::an_option_value_with_braces_is_passed_through_for_each_spelling verified-by: bravebot_agent::cmdline::only_an_option_carrying_a_value_is_passed_through verified-by: bravebot_agent::tools::the_run_description_says_when_a_pattern_for_the_program_is_quoted verified-by: bravebot_agent::cmdline::expansion_is_bounded_and_the_refusal_says_the_count verified-by: bravebot_agent::cmdline::a_tree_pattern_does_not_descend_into_an_ignored_directory verified-by: bravebot_agent::cmdline::a_dot_file_is_matched_only_by_a_pattern_that_writes_the_dot verified-by: bravebot_agent::cmdline::a_class_matches_the_characters_it_names verified-by: bravebot_agent::cmdline::a_word_with_no_pattern_names_a_file_that_need_not_exist verified-by: bravebot_agent::cmdline::a_quoted_pattern_is_not_expanded verified-by: bravebot_agent::cmdline::braces_multiply_a_word verified-by: bravebot_agent::cmdline::a_plan_is_told_to_the_planner_with_each_pattern_as_it_was_written verified-by: bravebot_core::command::an_argument_holding_an_invisible_character_is_spelled verified-by: bravebot_tui::confirm::run::a_run_prompt_draws_names_that_differ_in_an_invisible_character_apart verified-by: bravebot_agent::turn::a_run_result_does_not_spell_the_names_a_glob_matched_to_the_planner verified-by: bravebot_agent::turn::a_finished_jobs_account_does_not_spell_the_names_a_glob_matched_to_the_planner verified-by: bravebot_agent::turn::a_deny_rule_refusal_does_not_spell_the_names_a_glob_matched_to_the_planner verified-by: bravebot_agent::cmdline::a_redirection_is_told_to_the_planner_with_its_file_as_it_was_written verified-by: bravebot_core::command::what_the_planner_is_told_names_a_program_by_its_link_alone verified-by: bravebot_agent::turn::a_run_result_names_the_directory_as_typed_and_not_where_a_link_led verified-by: bravebot_agent::turn::a_finished_jobs_account_names_the_directory_as_typed_and_not_where_a_link_led verified-by: bravebot_agent::turn::a_background_line_that_did_not_start_names_the_directory_as_typed verified-by: bravebot_agent::turn::a_credential_refusal_names_the_redirection_under_the_directory_as_typed verified-by: bravebot_agent::turn::a_refused_redirection_is_named_under_the_directory_as_typed verified-by: bravebot_agent::turn::an_unopened_redirection_is_named_under_the_directory_as_typed verified-by: bravebot_agent::turn::an_unopened_file_inside_a_substitution_is_named_under_the_directory_as_typed verified-by: bravebot_agent::turn::a_redirection_refused_inside_a_substitution_is_named_once_under_the_directory_as_typed verified-by: bravebot_agent::exec::a_substitution_that_cannot_open_a_file_keeps_the_error_and_its_path verified-by: bravebot_agent::tools::a_failure_inside_a_substitution_is_respelled_under_the_directory_as_typed verified-by: bravebot_agent::tools::a_redirection_a_hook_made_inside_a_substitution_is_not_respelled_again verified-by: bravebot_agent::confine::neither_a_policy_row_nor_a_refusal_depends_on_the_directory_a_stage_starts_in verified-by: bravebot_agent::cmdline::a_range_counts_and_keeps_the_padding_it_was_written_with verified-by: bravebot_agent::cmdline::a_leading_tilde_becomes_the_home_directory verified-by: bravebot_agent::cmdline::a_tilde_with_no_home_to_stand_for_is_refused verified-by: bravebot_agent::home::the_profile_directory_is_the_home_itself_rather_than_the_state_directory verified-by: bravebot_agent::home::an_absent_home_names_no_profile_directory_for_a_tilde verified-by: bravebot_agent::turn::a_tilde_in_a_command_line_stands_for_the_home_directory_and_not_the_state_directory verified-by: bravebot_agent::turn::a_delegate_resolves_a_tilde_against_the_home_its_parent_did verified-by: bravebot_tui::app::a_typed_tilde_and_a_compiled_one_stand_for_the_same_directory verified-by: bravebot_ui_bridge::retention::worker::a_tilde_in_a_desktop_run_line_stands_for_the_home_directory verified-by: bravebot_agent::cmdline::each_argument_records_whether_a_pattern_matched_it verified-by: bravebot_core::command::a_matched_list_of_another_length_marks_every_argument verified-by: bravebot_core::policy::a_name_a_pattern_matched_in_an_unvouched_directory_is_not_proven_by_basename verified-by: bravebot_core::policy::a_pattern_produced_word_the_program_does_not_read_as_a_file_is_not_proven verified-by: bravebot_core::policy::a_pattern_produced_word_in_an_option_position_is_not_proven verified-by: bravebot_core::policy::a_pattern_produced_path_the_program_reads_stays_proven verified-by: bravebot_agent::turn::a_name_a_pattern_matched_in_an_unvouched_directory_reaches_the_planner_quarantined

CMDLINE-5: a redirection target is a write destination and takes the write gates

> out.txt is a file this plan creates or truncates. It is routing, it appears in the plan's write set, it is shown at the prompt, and it is subject to every rule that governs writing a file: the permission rules, the trust map's answer for that path, and the confinement that keeps a write inside the workspace.

That confinement is applied when the line is compiled and again immediately before each destination is opened, including one the line has already opened once. The parts of the line before it have run by then, and a program in one of them can have left a link at the name the person approved. A destination that lands outside the workspace and every opened directory at that moment is not opened, and the line stops there. The window between that check and the open is the one the known costs of trust-map.md accept for every write.

The one line it is not applied to is a line whose programs start with no profile: one the person approved with no sandbox (SANDBOX-29), and any line under the mode off (SANDBOX-22), but not a delegate's. This process opens a destination in place of the stage, so the confinement is what keeps a redirection from reaching what the stage's profile holds its programs back from. Where the programs have no profile there is nothing for it to hold back, and a program in the same line can already write the same file. The prompt lists every destination, the person's deny rules still refuse a path, and a destination that is outside every opened directory is asked about under the name it was written with (TRUST-18). When the line is refused for leaving the workspace in a session that would accept the request, the refusal says that unconfined is the argument that makes the write possible.

What a refused destination is told. A destination refused for leaving the workspace is given the remedy a file tool's write to the same path is given (TRUST-10), chosen from where the destination lands: the directory it is in, or the directory itself, to open with /add-dir, with the warning when that directory holds the working directory. It is given no directory where permissions.readsStayInWorkspace holds, where the directory is or lies inside a credential location, for the stores, where the path climbs with .. above the top of the file system, where it lands on a name that is not UTF-8, and where the path as the line wrote it, with each .. taken out, is inside the workspace or an opened directory, which means a link carried it out. A destination in a directory the remedy names is let through once that directory is opened. It names no request_path, whose grant a redirection does not pass. Where nobody can be asked in the run (CLI-1), a remedy that opens a directory is given as none, and the planner is told to say in its reply which path the work needs. A file tool's refusal for leaving the workspace is worded the same way (TRUST-10). The unconfined sentence above is said with every remedy, a credential location's included, where the session accepts that argument and only there. The trail records the remedy the planner was told. The choice reads the line's path, the file system and the session's settings, never a byte a file or a program holds.

A redirection inside a shell's command string, as in sh -c 'echo hi >> file', is not a destination of the line: the confined shell opens it, and the sandbox refuses it outside the directories the stage writes. The driver holds no path for it, so the sentence after such a failed step (SANDBOX-19) names none and says to write the redirection on the run line itself.

verified-by: bravebot_agent::tools::tests::confinement::a_redirection_outside_the_workspace_is_recorded_as_a_refusal verified-by: bravebot_agent::tools::tests::confinement::a_redirection_into_a_credential_location_names_the_unconfined_line_only_where_accepted verified-by: bravebot_agent::tools::tests::confinement::a_redirection_outside_with_nobody_to_ask_names_no_route_and_asks_for_the_path verified-by: bravebot_agent::workspace::a_redirection_climbing_above_the_top_of_the_file_system_is_offered_nothing verified-by: bravebot_agent::workspace::a_redirection_onto_a_name_that_is_not_utf8_is_offered_nothing verified-by: bravebot_agent::workspace::a_refused_redirection_is_let_through_once_the_directory_it_names_is_opened verified-by: bravebot_agent::confine::a_failed_shell_step_says_a_redirection_inside_it_is_opened_by_the_sandboxed_shell verified-by: bravebot_agent::workspace::a_redirection_outside_is_offered_the_directory_the_file_tools_offer verified-by: bravebot_agent::workspace::a_redirection_into_a_directory_holding_the_root_says_it_ends_checkouts verified-by: bravebot_agent::workspace::a_redirection_into_a_credential_location_is_offered_no_directory verified-by: bravebot_agent::workspace::a_redirection_a_link_carries_out_or_into_the_stores_is_offered_nothing verified-by: bravebot_agent::workspace::a_redirection_outside_where_reads_stay_inside_is_offered_no_directory verified-by: bravebot_agent::tools::tests::confinement::a_redirection_outside_is_given_the_open_remedy_and_one_into_credentials_the_credential_remedy verified-by: bravebot_agent::tools::tests::confinement::a_refused_redirection_writes_its_file_once_the_directory_it_names_is_added verified-by: bravebot_agent::tools::tests::confinement::read_file_and_a_redirection_of_the_same_outside_path_are_offered_the_same_remedy

Where the permission mode reaches a path. While the mode that answers every permission question is in force (MODE-4), a destination in a directory outside the workspace that the file tools reach (PATHREQ-7) is not refused for leaving it, so the line needs no unconfined argument there. The refusals that hold for a granted request still refuse a destination, the check is made again at each open, and a delegate's destination is held to its definition's writes: limit as a tool's write is (DELEGATE-28).

verified-by: bravebot_agent::turn::under_bypass_the_file_tools_reach_a_sibling_directory_with_no_request verified-by: bravebot_agent::turn::a_limited_delegate_of_a_bypass_turn_is_refused_a_sibling_directory_its_patterns_do_not_cover verified-by: bravebot_agent::turn::an_approved_unconfined_line_may_redirect_into_a_file_outside_the_workspace verified-by: bravebot_agent::turn::a_line_under_off_may_redirect_into_a_file_outside_the_workspace verified-by: bravebot_agent::tools::a_redirection_may_leave_the_workspace_only_where_the_line_has_no_profile

verified-by: bravebot_agent::turn::a_redirection_an_earlier_part_of_its_line_linked_out_of_the_workspace_is_refused_when_opened verified-by: bravebot_agent::turn::a_destination_reopened_after_an_earlier_part_linked_it_out_of_the_workspace_is_refused verified-by: bravebot_agent::turn::a_redirection_into_an_added_directory_is_confined_again_when_it_is_opened verified-by: bravebot_agent::turn::a_redirection_an_earlier_part_linked_inside_the_workspace_lands_at_the_link_target

The rules written in advance are asked again at the same moments, and not the confinement alone. The permission rules (PERM-7) and a delegate's writes: limit (DELEGATE-28) are asked about a destination immediately before each open, including one the line has already opened once, and whether or not the line has a profile. They are asked about the file the name lands on at that moment and about each other name that file has, a hard link included, as they were asked when the line was compiled. A link or a hard link that an earlier part of the line left at the name approved therefore reaches the same refusal as the file named directly. A rule or limit that covers the file refuses the open and the line stops there. The planner is told what the check before the line would have told it, under the destination as the line spelled it under the directory as typed and not under the file it landed on. A destination inside a command substitution is opened by the same run and takes the same check. A < source takes the Read rules again in the same way. The asks are made at every open and are not remembered, so the search for a file's other names is repeated for each; that cost is accepted. The check compares names, settings and file-system identity, never the bytes of a file.

verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_redirection_through_a_link_an_earlier_part_made verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_redirection_through_a_hard_link_an_earlier_part_made verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_redirection_that_reads_through_a_link_an_earlier_part_made verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_destination_reopened_after_an_earlier_part_linked_it_to_the_file verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_redirection_through_a_link_when_the_sandbox_is_off verified-by: bravebot_agent::turn::a_deny_rule_refuses_a_redirection_inside_a_substitution_through_a_link_an_earlier_part_made verified-by: bravebot_agent::turn::a_limited_delegate_cannot_redirect_through_a_link_its_own_line_made_out_of_its_files verified-by: bravebot_agent::tools::tests::arguments::a_redirection_writing_into_the_stores_is_refused_when_it_is_opened

>> is a write. < is a read and joins the read set, and it is standard input as well: the file's bytes go into a program, so the plan reports it as private input and it takes the standard-input gate of run.md whichever file it names. 2>&1 renames a descriptor and touches no file.

Neither does an output redirection to /dev/null, spelled exactly so. It discards the stream: the route stays in the plan and at the prompt, but the path joins no write set, takes none of the write gates, and enters no effect, because there is no file to confine, endorse or distrust. Any other spelling of the device, and any link to it, is an ordinary path and is held to all of the above.

Immediately before a destination may be opened for writing, the shared file authority marks it untrusted and reserves that path until the process has stopped. Reads during execution cannot use the old grant. Other paths remain available, and no lock spans the process wait. Every early exit stops already-started stages before releasing their reservations.

An untrusted line leaves its opened destinations untrusted. A complete successful trusted line may retain a destination's prior trust, but cannot raise it: >> can retain untrusted bytes. Failure, cancellation or an error after entry leaves explicit distrust. An untaken branch enters no effect and changes no decision. A failed attempt to open a destination is conservative about its possible effects; an approval alone changes nothing.

verified-by: bravebot_agent::turn::foreground_redirection_quarantines_live_reads_and_all_endings verified-by: bravebot_agent::tools::tests::arguments::a_foreground_line_whose_substitution_writes_through_a_link_into_the_stores_is_refused verified-by: bravebot_agent::tools::tests::arguments::a_foreground_line_whose_substitution_redirects_a_script_s_output_leaves_it_untrusted verified-by: bravebot_agent::tools::tests::arguments::a_substitutions_redirection_in_a_foreground_line_leaves_its_destination_untrusted verified-by: bravebot_agent::tools::tests::arguments::a_foreground_line_whose_substitution_writes_into_an_opened_directory_still_writes_it verified-by: bravebot_agent::tools::tests::arguments::a_line_naming_the_stores_directly_or_through_an_existing_link_is_refused_before_it_runs verified-by: bravebot_agent::tools::tests::arguments::a_background_line_whose_substitution_writes_through_a_link_into_the_stores_is_refused

What the one direction costs. A destination a vouched-for line overwrote stays untrusted until a person says otherwise, so reading it back is quarantined and costs a prompt. Recording a path as trusted on a write nobody can establish happened would be the round trip trust-map.md exists to close.

A redirection whose target is a glob, or anything else that does not compile to one literal path, is a compile error.

Why. This is the construct that most obviously fuses destination with payload in a raw string, and it is exactly the one that becomes safe once the destination is a named field. Refusing redirection while allowing pipes would be refusing the easy half.

verified-by: bravebot_agent::cmdline::a_redirection_joins_the_write_set verified-by: bravebot_agent::turn::a_redirection_carrying_untrusted_output_distrusts_the_file_it_wrote verified-by: bravebot_agent::turn::a_line_a_person_vouched_for_does_not_trust_the_file_it_wrote verified-by: bravebot_agent::turn::a_branch_that_does_not_run_leaves_its_destination_as_it_was verified-by: bravebot_agent::exec::a_line_reports_the_destinations_it_opened_and_no_others verified-by: bravebot_agent::exec::a_destination_that_cannot_be_opened_is_still_reported verified-by: bravebot_agent::cmdline::an_append_writes_and_an_input_reads verified-by: bravebot_agent::cmdline::an_input_redirection_is_private_input verified-by: bravebot_agent::cmdline::a_line_that_only_writes_releases_nothing verified-by: bravebot_agent::cmdline::joining_the_streams_writes_no_file verified-by: bravebot_agent::cmdline::discarding_a_stream_writes_no_file verified-by: bravebot_agent::cmdline::another_spelling_of_the_null_device_is_a_write verified-by: bravebot_agent::exec::a_discarded_stream_is_dropped_and_opens_nothing verified-by: bravebot_agent::turn::a_line_discarding_its_output_runs_and_names_no_file_to_write

CMDLINE-6: every branch that could run is endorsed before anything runs

a && b may run b. a || b may run b. a ; b runs b. All of them are in the plan, all of them are shown, and all of them are endorsed up front. Nothing is approved lazily part-way through a line, because a person answering a second prompt in the middle of a running line cannot tell what state the first half left behind.

A stage that does not run because a branch was not taken is not an effect and needs no separate answer. It was still endorsed, and that is the conservative direction.

So a line cannot run a program an earlier step in it creates. Every step's program is found when the line is compiled, before anything runs, so python3 -m venv v && v/bin/python x.py is refused for v/bin/python. The refusal for a program named by a path says nothing is runnable at that path and that the step creating it has to run on its own first. It does not mention $PATH, which a path does not consult. Whether the name is a path is read from the planner's own word, which is trusted.

verified-by: bravebot_agent::cmdline::every_branch_that_could_run_is_in_the_plan verified-by: bravebot_agent::cmdline::a_program_named_by_a_path_that_is_not_there_says_to_create_it_first verified-by: bravebot_agent::cmdline::a_program_that_cannot_be_found_is_refused verified-by: bravebot_core::command::a_plan_lists_every_step_that_could_run verified-by: bravebot_core::policy::an_endorsement_does_not_authorise_a_differently_joined_plan verified-by: bravebot_agent::exec::the_right_side_of_and_runs_only_when_the_left_succeeded verified-by: bravebot_agent::exec::the_right_side_of_or_runs_only_when_the_left_failed verified-by: bravebot_agent::exec::a_semicolon_runs_both_sides_whatever_the_first_did verified-by: bravebot_agent::exec::a_group_sequences_the_steps_it_holds

CMDLINE-7: permission rules match compiled stages, one at a time

A rule's command specifier is matched against each stage of the compiled plan, as its program word and argv with each word kept whole (PERM-5). A quoted program word is one word however many spaces it holds, so an allow rule's space never falls inside it: Bash(ls *) does not cover "ls /x". Restricting any one stage restricts the whole line. Granting the line needs every stage granted.

This is the rule that already governs pipelines, applied to a longer plan. What changes is that the splitting is now done by the compiler rather than being impossible; what does not change is that an argument is never re-split, so a denied program cannot be smuggled inside one.

A rule may also name a write destination, and a redirection target is matched as a path the same way write_file's destination is.

verified-by: bravebot_core::policy::a_denied_step_refuses_the_whole_line verified-by: bravebot_core::policy::a_rule_denying_a_path_denies_a_redirection_to_it verified-by: bravebot_core::policy::a_rule_denying_a_path_denies_reading_it_into_a_line verified-by: bravebot_core::policy::a_denied_program_cannot_be_smuggled_inside_an_argument verified-by: bravebot_core::permissions::a_pipeline_is_allowed_only_when_every_stage_is verified-by: bravebot_core::permissions::restricting_one_stage_restricts_the_whole_pipeline verified-by: bravebot_core::policy::an_allow_rule_does_not_cover_a_program_whose_name_holds_a_space verified-by: bravebot_agent::turn::an_allow_rule_does_not_run_a_program_whose_name_holds_a_space_unasked

CMDLINE-8: a plan may prove its output's label from what it read

The audited table covers plans that name files and not only stdin-only filters. A stage is read-proven when its resolved program is in the table and, for the exact argv given, the table's audit establishes all four:

  1. it writes no file;
  2. it executes nothing and starts no process;
  3. it opens no socket;
  4. every byte it reads comes from stdin or from a path in its operands.

An entry lists the options a call may use, and anything else refuses the call. A list of options to reject fails open, because an option nobody thought of reads as harmless and one of them makes a walk follow symlinks out of the tree it was pointed at. Spellings are matched whole, so an abbreviation of a long option is not that option: deciding what --recursi abbreviates is the parsing this road exists to avoid. An option that takes a value says so, and its value is skipped whether it is attached or is the next word, so it is never counted as an operand. An option is listed only where the GNU and the BSD implementation both give it a value or both do not: where one makes the value optional, a separate word after it is the value to one and an operand to the other.

An option written after an operand proves nothing. GNU reads it as an option, while BSD head, tail, wc and cut, and GNU with POSIXLY_CORRECT set, stop reading options at the first operand and open every later word as a file, -- included. - alone is not such a word: both read it as an operand wherever it is written. What it names differs instead: GNU and BSD cut and grep read standard input for it, and BSD head, tail and wc open a file called -, so for those three it is counted as a path.

sort and uniq are in the table, and what writes is refused by the entry. sort lists no option that names an output file, runs a program or names a file of names (-o, --output, --compress-program, -T, --temporary-directory, --files0-from, --random-source), and uniq admits one operand because the second is the file it writes. That operand is counted whatever it is spelled, so uniq - out is refused. diff admits two paths and never -r, -l, -X or --from-file. ls, stat and du must name a path and exclude the options that follow a link (-L, -H). cat, ls, diff and stat report only on the paths they are given, the same claim as the other entries. sort spills to scratch files under TMPDIR holding bytes it was given, named by the program rather than by the call. BSD cat connects to a Unix socket named as an operand, which the table cannot see because it has no file types to look at.

A stage whose program resolves to a file inside the workspace, or inside any directory that is not the system's, is not read-proven, and neither is one whose line named a path rather than a program, one carrying an environment assignment, or one opening a file for a stream. The table's entries are claims about the programs a system provides under those names and are matched on the name a program resolved to, which identifies no file: so a file called wc in the tree being inspected would answer as the audited one, and it reaches that answer whether the line pointed at it or a name did. The name is compared as written, with no fold of case or of letters: the table grants an answer, so a spelling it does not list keeps the opaque default, and \u{17f}ort is not sort here as it is in a deny rule (PERM-5). $PATH decides what a name means, so a project directory on it is enough for a file a contributor added to be what an audited name runs, and PATH_add bin in a project's own .envrc puts one there. The directories that are not the system's are the working directory, the checkout holding it (a session begun in a subdirectory has the bin above it on $PATH), every directory added by name or left with /cd, a directory a stage was granted to write, and, for a delegate working in a checkout, the working directory the checkout was made from (see checkouts). The checkout is the nearest of the directory and its ancestors that holds a .git, found as SANDBOX-30 finds the one it leaves out of the search for programs. Only the nearest is taken, because every ancestor with a .git would also take in an outer repository that merely contains the checkout, such as the repository a submodule is part of or a dotfiles repository at the home directory, and every program under it would then be outside the proof. A directory with no .git above it, or one marked by .hg or .jj only, has no checkout and only the directory itself is in the set. The agent computes the set from the directories the person opened and hands it to the policy as it hands the root. The test is made against the path the driver resolved and will execute rather than against the spelling that reached it: those are two values, and only the first says where the file is. An assignment decides what a program loads and reads before its own arguments are looked at, and a redirection opens a file the argv does not name, so neither is covered by an audit of an option surface. Joining standard error to standard output renames a descriptor and opens nothing, so it is not a redirection for this purpose.

A $PATH directory outside that set is honoured whatever the trust map holds about it, since the audited utilities live in one: Homebrew installs to its own prefix and Nix to a store path, and neither is a directory anybody wrote a rule about.

A plan running in any directory other than the one the trust map's rules are written against is not read-proven, since its operands and the map's rules would be spelled relative to different places. A plan with no steps is not read-proven either: the answer to what it read is that there was no proof.

The plan's read set is those operand paths, glob-expanded. A name a pattern matched belongs to it only where the program reads that name as a file. A step holding a pattern-produced word anywhere else, in an instruction operand, an option or an option's value, is not read-proven (CMDLINE-4). The output's first label is the meet of the labels over the read set and over stdin, which is the ordinary rule for a derived value, applied to a process, and is not a relabel and grants nothing.

Where every stage is read-proven and every path in the read set is one the trust map answers for, the output is trusted and the planner reads it. Where any stage is not, or any path is outside what the trust map covers, the output is untrusted and private, which is the default every other run gets.

A path is one the map answers for when the map covers it and everything beneath it: a directory read as a tree is read whole, so a directory the user refused inside a project they vouched for decides the answer about that project. A path with a .. component is outside what the map answers for whatever a rule spelled the same way says, because the map compares names by segment and a climbing path names a file through a directory nobody wrote a rule about.

Each path is asked about under every name the map may hold a rule about it by, and answers as the weakest of them. A name is reduced to the open directory it lands in before the map sees it, and that reduction needs a filesystem (trust-map.md), which this road does not have: so a file inside the workspace is asked about under the relative name and the full one both, and the spelling a line happened to use is not a decision anybody made about the file. A directory the project sits in is trusted by an answer about that directory (TRUST-9), so an absolute name answered alone would give a project file the label of a directory it is merely reachable through, and a relative name answered alone would skip the rule a write through a link out of the project left behind. An operand naming a directory that holds the workspace is asked about the project as well, since a line reading that directory whole reads every file the project's own rules bear on. Nothing here is resolved, only re-spelled, so an operand outside the workspace keeps the name the line gave it and the rule about the directory holding it decides. Answering under every name can only cost a question and never grant trust, which is what makes it the right form for a road with no filesystem to settle a name with. A plain line the sandbox holds is asked about the words of its argument list the same way, unless the audited table proves the whole line read-only (RUN-5), and a word naming a path the map holds untrusted makes any other such line ask.

This is the proof road, and it is not the assertion road. A person vouching for a command is a person taking responsibility for it. This is a claim about a program, checked against that program's option surface by hand, and nothing a user says extends the table.

grep -r is provable, and that is the point. Recursion is provable exactly as far as the read set names what is walked: with a directory in the operands the label comes from that directory, and the single most useful exploration command in a large repository is not opaque. A recursive call naming no path is not proven, because what it walks is then the working directory under one implementation's convention and stdin under another's, and the difference is the whole of what the label would be taken from. -R is not proven either: it follows every symlink it meets, so the tree it reads is not the tree the read set names.

git is not provable and does not go in the table. A repository's own config can define an alias that runs a command and a pager that runs a command, so git log is an interpreter whose program is a file in the tree being inspected. It stays on the assertion road, where a person vouches for it. Recognising a safe git invocation means reading .git/config, which is content, to decide routing, and that is the thing that is never allowed. History is read with nobody asked by read_git instead, which starts no program and reads nothing under .git until the trust map vouches for all of it.

sed and awk never enter the table, for the reason they are excluded today: they are interpreters, and awk's system() reaches the shell this repository excludes.

verified-by: bravebot_core::pure::a_named_file_is_the_answer_rather_than_a_refusal verified-by: bravebot_core::pure::a_recursive_search_answers_with_the_trees_it_walks verified-by: bravebot_core::pure::recursion_naming_no_path_proves_nothing verified-by: bravebot_core::pure::recursion_that_follows_symlinks_proves_nothing verified-by: bravebot_core::pure::an_unlisted_option_proves_nothing verified-by: bravebot_core::pure::an_abbreviated_long_option_proves_nothing verified-by: bravebot_core::pure::an_option_value_is_never_counted_as_a_path verified-by: bravebot_core::pure::a_context_option_given_its_value_apart_proves_nothing verified-by: bravebot_core::pure::an_option_after_an_operand_proves_nothing verified-by: bravebot_core::pure::an_option_bundled_with_others_is_still_looked_up verified-by: bravebot_core::pure::an_excluded_option_is_refused verified-by: bravebot_core::pure::no_option_is_both_listed_and_excluded verified-by: bravebot_core::pure::a_flag_that_supplies_the_pattern_proves_nothing verified-by: bravebot_core::pure::a_flag_naming_a_file_of_names_proves_nothing verified-by: bravebot_core::pure::a_word_past_the_end_of_flags_marker_is_an_operand verified-by: bravebot_core::pure::a_dash_occupies_an_operands_place verified-by: bravebot_core::pure::a_lone_dash_is_a_path_where_bsd_opens_a_file_by_that_name verified-by: bravebot_core::pure::an_operand_a_program_has_no_reading_for_proves_nothing verified-by: bravebot_core::pure::interpreters_never_qualify_however_harmless_they_look verified-by: bravebot_core::pure::a_sort_or_uniq_call_that_names_an_output_file_proves_nothing verified-by: bravebot_core::pure::sort_and_uniq_reading_one_input_answer_with_it verified-by: bravebot_core::pure::diff_compares_two_paths_and_never_walks_a_tree verified-by: bravebot_core::pure::a_reporting_program_with_no_path_proves_nothing verified-by: bravebot_core::pure::a_reporting_program_following_links_or_reading_a_list_proves_nothing verified-by: bravebot_core::pure::cat_answers_with_the_files_it_reads verified-by: bravebot_core::pure::a_program_spelled_with_a_folded_letter_is_not_in_the_table verified-by: bravebot_core::policy::a_pipeline_of_sort_uniq_cat_and_ls_over_vouched_paths_does_not_ask verified-by: bravebot_core::trust::a_subtree_is_trusted_only_when_nothing_beneath_it_is_not verified-by: bravebot_core::policy::a_line_that_only_reads_vouched_for_paths_comes_back_trusted verified-by: bravebot_core::policy::a_line_reading_an_unvouched_path_still_asks verified-by: bravebot_core::policy::a_line_bsd_and_gnu_read_different_files_from_still_asks verified-by: bravebot_core::policy::a_line_reading_a_refused_file_called_dash_still_asks verified-by: bravebot_core::policy::a_name_a_pattern_matched_in_an_unvouched_directory_is_not_proven_by_basename verified-by: bravebot_core::policy::a_pattern_produced_word_the_program_does_not_read_as_a_file_is_not_proven verified-by: bravebot_core::policy::a_pattern_produced_word_in_an_option_position_is_not_proven verified-by: bravebot_core::policy::a_pattern_produced_path_the_program_reads_stays_proven verified-by: bravebot_agent::turn::a_name_a_pattern_matched_in_an_unvouched_directory_reaches_the_planner_quarantined verified-by: bravebot_core::policy::a_recursive_search_takes_its_label_from_the_whole_subtree verified-by: bravebot_core::policy::one_step_nothing_can_account_for_makes_the_whole_line_opaque verified-by: bravebot_core::policy::an_environment_assignment_leaves_a_step_unproven verified-by: bravebot_core::policy::a_redirection_leaves_a_step_unproven_and_a_descriptor_rename_does_not verified-by: bravebot_core::policy::a_program_named_by_path_is_not_proven verified-by: bravebot_core::policy::a_program_resolving_inside_the_project_is_not_proven verified-by: bravebot_core::policy::a_line_running_outside_the_project_root_is_not_proven verified-by: bravebot_core::policy::a_program_started_by_another_name_or_from_the_project_is_not_proven verified-by: bravebot_core::policy::a_program_in_the_checkout_above_the_working_directory_is_not_proven verified-by: bravebot_core::policy::a_delegate_in_a_checkout_is_refused_programs_from_the_directory_it_was_made_from verified-by: bravebot_core::policy::a_program_in_a_directory_the_session_left_is_not_proven verified-by: bravebot_core::policy::the_set_leaves_the_results_for_the_directory_alone_as_they_were verified-by: bravebot_agent::workspace::the_directories_a_program_may_not_resolve_into_follow_the_session verified-by: bravebot_agent::workspace::a_delegate_in_a_checkout_may_not_resolve_a_program_into_the_working_directory verified-by: bravebot_agent::tools::tests::arguments::a_directory_a_remembered_grant_lets_a_stage_write_is_in_the_unproven_set verified-by: bravebot_agent::proof_road_checkout::a_program_reached_through_a_link_into_the_checkout_above_the_directory_is_asked_about verified-by: bravebot_agent::proof_road_checkout::a_program_in_a_directory_a_remembered_grant_lets_a_stage_write_is_asked_about verified-by: bravebot_agent::programs::a_relative_path_entry_is_read_under_the_working_directory verified-by: bravebot_core::policy::a_plan_with_no_steps_proves_nothing verified-by: bravebot_core::policy::a_project_file_named_absolutely_is_answered_by_the_project_rule verified-by: bravebot_core::policy::a_line_reading_a_directory_holding_the_project_answers_for_the_project verified-by: bravebot_core::policy::a_line_reading_a_tree_the_map_says_nothing_about_still_asks verified-by: bravebot_core::policy::a_line_reading_a_vouched_for_tree_above_the_project_does_not_ask verified-by: bravebot_core::policy::a_climbing_operand_is_untrusted_under_a_root_spelled_with_a_climb verified-by: bravebot_core::policy::a_held_line_is_asked_about_every_name_of_a_word_and_fails_closed verified-by: bravebot_core::policy::a_held_recursive_copy_of_a_directory_holding_an_untrusted_file_asks

CMDLINE-9: a read-proven plan does not prompt

Where every stage of a plan is read-proven under CMDLINE-8, the plan's write set is empty, and its read set lies inside what the trust map answers for, the line runs without asking.

This is a narrowing of the rule that every run asks. That rule's reason is that foo --bar might write to disk and nothing here can tell. For an entry in the audited table, with an audited argv, something here can tell, and the table is the record of having checked. The proof is the only thing that may answer the prompt: never a declaration by a stage, never a property inferred from a program's name, never anything derived from what a program printed.

A permission rule that says ask or deny for a stage still decides. Proof removes the default prompt; it does not overrule a rule a person wrote.

Why this clause is the risky one. It is the only place in this spec where a proof stops a human from being asked, and if the table is wrong somewhere then something ran that nobody saw. The mitigations are that the table is small, hand-audited per program against its full option list, and fails closed on any argv it does not fully recognise. A file name match is not one of them and is not sufficient on its own: a name is not a program, so the file the name resolved to has to lie outside the workspace and the rest of the set CMDLINE-8 lists as well, and only where the line named a program rather than a path. CMDLINE-8 stands on its own without this clause and still removes the second round trip; what this clause adds is the first prompt, not the readable output.

verified-by: bravebot_agent::turn::a_line_that_only_reads_vouched_for_files_needs_no_prompt verified-by: bravebot_core::policy::a_line_that_only_reads_vouched_for_paths_does_not_ask verified-by: bravebot_core::policy::a_line_reading_an_unvouched_path_still_asks verified-by: bravebot_core::policy::a_line_bsd_and_gnu_read_different_files_from_still_asks verified-by: bravebot_core::policy::a_line_reading_a_refused_file_called_dash_still_asks verified-by: bravebot_core::policy::a_recursive_search_takes_its_label_from_the_whole_subtree verified-by: bravebot_core::policy::a_path_climbing_out_of_the_project_still_asks verified-by: bravebot_core::policy::a_line_reading_a_tree_the_map_says_nothing_about_still_asks verified-by: bravebot_core::policy::a_line_reading_a_vouched_for_tree_above_the_project_does_not_ask verified-by: bravebot_core::policy::a_read_proven_line_that_also_writes_still_asks verified-by: bravebot_core::policy::private_input_still_asks_about_a_read_proven_line verified-by: bravebot_core::policy::an_ask_rule_still_asks_about_a_read_proven_line verified-by: bravebot_core::policy::a_deny_rule_still_refuses_a_read_proven_line verified-by: bravebot_core::policy::one_step_nothing_can_account_for_makes_the_whole_line_opaque verified-by: bravebot_core::policy::an_environment_assignment_leaves_a_step_unproven verified-by: bravebot_core::policy::a_program_named_by_path_is_not_proven verified-by: bravebot_core::policy::a_program_resolving_inside_the_project_is_not_proven verified-by: bravebot_core::policy::a_line_running_outside_the_project_root_is_not_proven verified-by: bravebot_core::policy::a_program_in_the_checkout_above_the_working_directory_is_not_proven verified-by: bravebot_core::policy::a_program_started_by_another_name_or_from_the_project_is_not_proven

CMDLINE-10: output comes back as text whenever the planner may read it

A result the planner is allowed to read is returned in the tool result, in full, up to the bound in CMDLINE-11. Not as a reference to be fetched by a second call.

That covers output that is trusted by proof under CMDLINE-8 and output of a command a person vouched for, which is already trusted today and is already returned as text. What changes is that the trusted case stops being rare.

Output the planner may not read is quarantined as a reference, and asking to see it is unchanged.

Standard error comes back with standard output, separated and labelled, under the same rule. A run that failed put its explanation on stderr, and a planner that cannot see it reports that the command worked.

Why this matters more than it looks. A reference plus a second call is one extra model round trip per command. In the session that motivated this spec, a round trip cost between five and a hundred and fifty seconds. A tool that costs two of those to answer which files mention this symbol is a tool nobody can afford to use, which is why the harness's own guidance had steered the planner away from it.

verified-by: bravebot_agent::turn::a_vouched_commands_output_reaches_the_planner verified-by: bravebot_agent::turn::a_quarantined_run_says_what_would_make_it_visible verified-by: bravebot_agent::exec::standard_error_comes_back_labelled_beside_standard_output verified-by: bravebot_agent::exec::a_background_run_labels_standard_error_as_a_waited_for_one_does verified-by: bravebot_agent::exec::what_a_background_run_hands_over_incrementally_labels_each_delivery_of_standard_error verified-by: bravebot_agent::turn::a_finished_jobs_wake_up_labels_its_standard_error verified-by: bravebot_agent::turn::job_output_labels_standard_error

CMDLINE-11: output is bounded, and what was dropped is said

A result returned as text is capped. Past the cap the head and the tail are kept and the middle is dropped, with a line in between naming how many bytes and lines went. Head and tail rather than head alone, because a build log's verdict is at the end and its first error is near the beginning.

The cap is on what enters the conversation, not on what the command printed. The whole output stays available as a reference, so a planner that needs the middle can hand it to a processor or write it to a file without running the command again.

The cap is a context-budget decision and belongs beside the other ones: a single tool result must never be able to spend a large fraction of the conversation.

verified-by: bravebot_agent::tools::a_capped_output_keeps_its_head_and_its_tail verified-by: bravebot_agent::tools::an_output_inside_the_cap_is_left_alone verified-by: bravebot_agent::tools::a_capped_output_says_how_many_bytes_and_lines_went verified-by: bravebot_core::policy::content_the_planner_saw_a_sample_of_is_kept_whole verified-by: bravebot_agent::turn::the_middle_of_a_capped_output_stays_reachable verified-by: bravebot_agent::turn::the_middle_of_a_capped_job_output_stays_reachable

CMDLINE-12: the working directory persists across calls, and shell state does not

A call may name a directory to run in, inside the workspace or inside a directory the user added. Absent one, a line runs where the last one ran, and the first runs at the workspace root.

Nothing else carries over. NAME=value on one line does not affect the next, because there is no shell process between calls to hold it: each stage is spawned fresh with the process environment, less this agent's own credentials and with the session's own directory named (TRUST-17). A planner that needs a variable set puts it on the line that needs it.

Under bypass the value on that line may come from a variable or a command (CMDLINE-17); that is still the line's own assignment, set for one program and not carried to the next call.

A stage whose program is cd, pushd, popd or export is refused when the line is compiled, wherever it stands in the line and whether or not the host has a program of that name, because it would change nothing for the stages after it. The refusal says that the directory argument of the call is how a line runs elsewhere. Nothing runs and nobody is asked.

A stage whose program is ulimit, umask, unset, alias, unalias, hash or wait is refused the same way, in the same positions, whether or not the host has a program of that name. These are shell builtins whose effect stays in the shell that runs them. A host may ship a program of the name (macOS has /usr/bin/ulimit) that runs the builtin in a shell of its own and exits zero, so the stage would be planned, approved and run, and change nothing for the stages after it. The refusal says so. For ulimit and umask it says the whole line is written as sh -c '... ulimit ...', which is approved as one line. For alias and unalias it says that an alias defined in one stage is not seen by the other stages and that the host shell does not expand aliases in a non-interactive script, so the command is written out. For the others it says the whole script goes inside sh -c '...'. It does not give the directory or NAME=value advice, which is about cd and export.

The refusal covers every form of these words, a read such as ulimit -a or umask with no operand included. A host program of that name prints the limits of the shell it starts for itself, not those of any other stage, so a read is as misleading as a set, and the answer does not depend on whether the host has the program. A limit or a mask is read the way it is set, inside sh -c, which is not refused. A program that only has such a word as an operand, a longer name, or a path (./ulimit) is an ordinary program.

Why the asymmetry. A directory is a routing field, shown at every prompt and endorsed with the plan, so carrying it is visible. An environment that accumulated invisibly across calls would change what a later plan does without appearing in that plan.

A directory that is not the workspace root is asked about unless a vouched entry names that exact tree, and what the line prints is (U,priv) unless one does. RUN-8 is where that is settled: an entry records the tree the answer was given in, so an answer given about sub/ answers for sub/ and for no other directory, including the root. The carrying is what this clause grants; a standing answer is not.

A directory that no longer exists is refused with a message saying so, a carried one as a named one, before the line is compiled and before anyone is asked, and a carried one is reset to the workspace root. The directory is checked again immediately before the first stage is spawned, because an approval can wait for hours, and a directory removed in that time is reported as removed rather than as a program that could not be started.

The person is shown the directory the line runs in, where a symbolic link in the tree led. The planner is told the directory in the words it named it with, or in the words of the call that named the one it carried, and a .. that lands in an added directory as the workspace spells it for the file tools. That spelling is used in the account of the line, in the origin of what it printed and of what a job printed, and in every refusal and failure about the line, including the sentence about a carried directory that no longer exists. A link in a tree nobody vouched for chooses the name it leads to (LABEL-3, CMDLINE-4). The auto mode's classifier is a model, and is shown the same spelling (AUTO-5).

A program named by a relative path that is not there is refused, and the refusal says where the path was looked for: in the directory as told above, or at the workspace root. Where the call named no directory and the line would have run in one an earlier call named, it says the directory was carried from that call and that passing directory changes it. At the root it says to pass directory to look elsewhere. A bare name is looked for on $PATH and an absolute path names its own place, so their refusals name no directory. What decides the sentence is the planner's line and whether this call named a directory, and nothing read from the tree.

The carrying lasts a turn. It is not written into the session record, so the next turn starts at the root again. That is short of what this clause describes, and is left to the change that gives a session somewhere to keep one (RUN-9).

verified-by: bravebot_agent::turn::the_working_directory_persists_across_calls verified-by: bravebot_agent::turn::the_working_directory_can_be_an_added_directory verified-by: bravebot_agent::turn::a_directory_escaping_the_workspace_is_refused verified-by: bravebot_agent::turn::a_nonexistent_directory_is_an_error_and_does_not_mutate verified-by: bravebot_agent::turn::a_directory_that_is_not_a_string_is_refused verified-by: bravebot_agent::turn::what_is_reported_about_a_line_says_which_directory_it_ran_in verified-by: bravebot_agent::turn::a_refused_run_directory_does_not_persist verified-by: bravebot_agent::turn::a_carried_directory_that_was_removed_is_refused_before_asking verified-by: bravebot_agent::turn::a_carried_directory_is_told_as_typed_and_not_where_a_link_led verified-by: bravebot_agent::turn::a_carried_directory_that_is_gone_is_told_as_typed_and_not_where_a_link_led verified-by: bravebot_agent::turn::a_run_refusal_for_a_removed_directory_names_it_as_typed_and_not_where_a_link_led verified-by: bravebot_agent::turn::a_run_in_a_directory_typed_with_a_climb_is_told_as_the_workspace_spells_it verified-by: bravebot_agent::turn::a_cd_stage_is_refused_before_asking_and_the_directory_argument_still_works verified-by: bravebot_agent::turn::a_ulimit_stage_is_refused_before_asking_and_the_sh_c_form_is_put_to_the_person_as_one_line verified-by: bravebot_agent::cmdline::a_word_that_sets_shell_state_is_refused_wherever_it_stands verified-by: bravebot_agent::cmdline::a_shell_builtin_is_refused_wherever_it_stands verified-by: bravebot_agent::cmdline::the_ulimit_refusal_says_to_put_the_whole_line_in_sh_c verified-by: bravebot_agent::cmdline::the_other_builtin_refusals_say_what_is_true_of_them verified-by: bravebot_agent::cmdline::a_word_that_only_looks_like_a_shell_builtin_is_not_refused verified-by: bravebot_agent::turn::a_directory_removed_during_the_approval_is_reported_as_removed verified-by: bravebot_agent::turn::a_vouched_line_is_asked_about_again_when_a_directory_is_named verified-by: bravebot_agent::turn::a_program_named_by_a_relative_path_that_is_not_found_says_where_it_was_looked_for verified-by: bravebot_agent::turn::a_bare_name_or_an_absolute_path_that_is_not_found_names_no_directory verified-by: bravebot_agent::turn::a_relative_program_not_found_in_a_carried_directory_is_told_as_typed verified-by: bravebot_agent::turn::a_relative_program_not_found_in_a_link_to_the_root_is_told_as_typed verified-by: bravebot_agent::turn::a_relative_program_not_found_inside_a_substitution_says_where_it_was_looked_for

CMDLINE-13: a call may name its own deadline, under a ceiling

The default is short enough that a hung program is noticed and long enough for an ordinary build step. A call may raise it up to a ceiling it cannot exceed.

Neither figure is fixed at what was compiled in. A settings file may name both, and RUN-23 is what it names and what the two come to together; the planner is told the ones in force, since a ceiling it was not told about is one it never asks for. The floor is not among them.

Reaching the deadline ends the run rather than failing it, exactly as the fixed limit does today: the stages are stopped as RUN-11 says, what they printed is collected and returned under whatever label it had earned, and the stop is reported as structure so a caller can tell the two apart without reading a byte. Collection after a stop stays abandonable, because a stage can leave a child holding the write end of the pipe.

Not a safety property. A program that finishes in time is no safer than one that does not.

A run stopped at a deadline equal to the ceiling in force is reported separately from one stopped below it. A longer deadline cannot be asked for there, so the sentence says so and says to start the line again with background: true, which a deadline does not stop. The choice compares the deadline the run was given with the ceiling in force, two figures a person set, and reads nothing the program printed. The description of run also says that a build or test gate that may outlast the ceiling starts in the background.

verified-by: bravebot_agent::turn::a_run_is_stopped_at_the_deadline_its_call_named verified-by: bravebot_agent::turn::a_run_stopped_at_the_ceiling_in_force_is_told_so_and_one_below_it_is_not verified-by: bravebot_agent::report::a_run_stopped_at_the_ceiling_is_sent_to_the_background_and_one_below_it_is_not verified-by: bravebot_agent::tools::the_run_tool_says_a_gate_that_may_outlast_the_ceiling_starts_in_the_background verified-by: bravebot_agent::turn::a_null_deadline_takes_the_default verified-by: bravebot_agent::turn::a_negative_deadline_is_clamped_to_floor verified-by: bravebot_agent::tools::run_deadline_is_held_to_bounds_and_defaults_cleanly

CMDLINE-14: a call may run in the background, and its finish wakes the turn

A call may say it should not be waited for. It is endorsed the same way, starts the same way, and answers immediately with a handle. The turn carries on.

When it exits, the turn is told: the handle, the status, and the output under the label the plan earned. A background run that is still going when the turn ends is killed, except in an interactive session, where it is left running and is killed when the session ends (RUN-15). A job that ended between two turns is told at the next turn's first round.

The output of a background run obeys every other clause here. Backgrounding changes when the planner is told, never what it is allowed to read.

How the turn is told. The turn asks its jobs between rounds whether any has ended, and puts the handle, the exit status and what it printed since the previous look (since the job started, where nobody looked before) into the conversation as a message of its own. Where the output is quarantined, the account states how many lines of the job's whole output begin in its reference and the number the first of them has, in the words every look uses, and lists the references of the earlier looks at the job, as a job_output look does (RUN-17), and a later look at the job lists the account's reference too. Asking is polling and costs nothing: a job still running answers immediately, and nothing waits here, because a background job is for the program meant to keep going and a turn that waited would wait out a server. The account is given once, by whichever of the two routes got there first: a job_output call that already said the job had ended is the account, and the look between rounds passes over it rather than repeating it with the output gone.

Why this is a parameter and not the & token. As syntax it would be one more thing the compiler has to model and one more thing a reader has to spot in a line. As a parameter it is a field on the call, visible in the prompt, and impossible to hide inside an argument.

verified-by: bravebot_agent::turn::a_background_jobs_finish_reaches_the_turn_without_the_planner_asking verified-by: bravebot_agent::turn::a_silent_background_jobs_exit_code_reaches_the_turn_by_itself verified-by: bravebot_agent::turn::what_an_ended_job_printed_is_quarantined_where_nobody_vouched_for_the_line verified-by: bravebot_agent::turn::what_an_ended_job_printed_is_capped_with_the_whole_of_it_kept verified-by: bravebot_agent::turn::the_account_of_an_ended_job_after_an_earlier_look_names_its_range_and_that_look verified-by: bravebot_agent::tools::the_account_of_an_ended_job_continues_the_count_of_the_looks_before_it

CMDLINE-15: a program that wants a terminal is refused before it starts

Standard input is empty, as it is today, so a program that reads it gets nothing rather than the terminal. Beyond that, invocations known to require interaction are refused at compile time with a message naming the alternative: git rebase -i, git add -i, an editor, a pager without --no-pager, anything that would open /dev/tty. The refusal of an editor names edit_file as the alternative only where the turn's list holds it (TOOL-6).

git commit is refused when it supplies no message, because git then opens an editor. A message source lets it through: -m, -F, -C, --message, --file, --reuse-message or --no-edit. A plain --fixup=<commit> or --fixup <commit> is not refused either, because git writes the fixup! <subject> message itself. --fixup=amend:<commit> and --fixup=reword:<commit>, and their two-word spellings, open an editor and are refused unless a message source is also given. --squash=<commit> and a bare git commit are refused.

A line that names the editor outright is not refused for opening one. The editor is named by a variable written in front of the git step itself (GIT_SEQUENCE_EDITOR=<command> or GIT_EDITOR=<command>) or by git -c sequence.editor=<command> or -c core.editor=<command>, and the value must be literal text in the line. The setting git reads first decides, as git does: a sequence editor, then the editor of a message. A value that is empty, that is computed when the step starts (only possible in bypass mode), or that is a program this list refuses as an editor (vim, nano) names none, and the line is refused as it would be without the setting. An assignment in front of another step, or of any other variable, does not lift the refusal. GIT_SEQUENCE_EDITOR and sequence.editor lift only the refusal of git rebase -i. GIT_EDITOR and core.editor also lift the refusal of a git commit that supplies no message, including --squash=<commit> and --fixup=amend: or --fixup=reword:, because git runs the named editor on the message. git add -i and git add -p are never lifted. The subcommand is found past -c <key=value> and -C <dir>, so options in front of it do not hide it from this check. The decision reads only the words of the line and never a file.

The refusal of git rebase -i names the routes that work: GIT_SEQUENCE_EDITOR=<command> git rebase -i <base>, git rebase --autosquash <base> without -i to fold fixup commits, and git commit --fixup=reword:<sha> -m <message> followed by git rebase --autosquash <base> to change a subject.

The list is a convenience rather than a guarantee. Something interactive that is not on it hits the deadline and returns what it printed, which is the same outcome by a slower road.

verified-by: bravebot_agent::cmdline::a_program_that_wants_a_terminal_is_refused_before_it_starts verified-by: bravebot_agent::cmdline::a_line_that_names_the_terminal_device_is_refused verified-by: bravebot_agent::cmdline::the_same_program_without_the_interactive_part_is_not_refused verified-by: bravebot_agent::cmdline::the_refusal_of_an_editor_names_edit_file_only_where_the_list_holds_it verified-by: bravebot_agent::cmdline::a_line_that_names_the_editor_outright_is_not_refused verified-by: bravebot_agent::cmdline::an_editor_whose_name_is_computed_does_not_lift_the_refusal verified-by: bravebot_agent::cmdline::the_refusal_of_an_interactive_rebase_names_the_routes_that_work verified-by: bravebot_agent::exec::a_stage_that_reads_stdin_is_given_nothing_rather_than_the_terminal

CMDLINE-16: the tool's own description tells the planner to filter at the source

The description must say that narrowing a result inside the command is the cheapest thing the planner can do, and must give the shapes: | head -n, -l for names only, -c for a count, a line range rather than a whole file.

It must not tell the planner to prefer the dedicated read and search tools over a command line for exploration. That instruction is in the current description, and it is backwards in a large tree: a capped structured search returns thousands of tokens of truncated matches where grep -rl returns a dozen lines, and the planner following the instruction pays the difference every round.

What the description should say instead is the true thing: use whichever returns less, and a command that filters usually returns less.

The description must also say that a cd step is refused because it moves nothing for the steps after it, and that the directory argument is how a line runs elsewhere. It must say that a ulimit, umask, unset, alias, unalias, hash or wait step is refused because it changes nothing for the steps after it, and that a program is run under a limit or a mask by writing the whole line as sh -c '... ulimit ...', which is approved as one line.

Why a clause about wording. A tool's description is the only instruction the planner reliably reads, and an instruction to reach for the structured tools instead measurably steers a session into the expensive path. Wording that changes behaviour is behaviour.

verified-by: bravebot_agent::tools::the_run_description_tells_the_planner_to_filter_at_the_source verified-by: bravebot_agent::tools::the_run_description_does_not_send_the_planner_to_the_other_tools_instead verified-by: bravebot_agent::tools::only_run_takes_a_command_line verified-by: bravebot_agent::tools::the_run_description_says_cd_moves_nothing_and_directory_is_how_a_line_runs_elsewhere verified-by: bravebot_agent::tools::the_run_description_says_a_limit_or_mask_step_is_refused_and_goes_inside_sh_c

CMDLINE-17: under bypass, an assignment in front of a program may take a variable or a command

Outside bypass mode every form below is refused exactly as CMDLINE-2 says. Under bypass (tools.permission_mode is Bypass) the compiler accepts these, and only these, and only in the NAME=value prefix in front of a program (the words since the start of the line or the last |, &&, ||, ; or ( that are all assignments):

Form Meaning
NAME=$VAR cmd, NAME=${VAR} cmd, NAME="$VAR" cmd, NAME=a-$VAR-b cmd the value is the text with each named variable's value put in
NAME="$(cmd)" cmd, NAME=$(cmd) cmd the value is what cmd printed on standard output, trailing newlines trimmed

Several assignments may each carry one, and so may the prefix of a later stage (a | NAME=$X b). Everything else stays refused with the reasons it has today: a bare $VAR or $(…) as an argument or as the program, backticks anywhere (an assignment value included), eval, a pattern in an assignment value (FOO=*.rs cmd), $1, $?, $$, ${X:-y} and ${#X}. In single quotes a $ is text in both modes (NAME='$X' cmd).

The plan carries the source, never the value. The step holds the text as written ($X, $(cmd)) and the compiled steps of cmd. The plan text, its canonical form and key, the trail, the history, an error and anything the planner is told are made from that source alone. The value is resolved when the pipeline holding the step is about to start, before any stage of that pipeline is spawned: in a | NAME=$(cmd) b, cmd runs before a does. A variable that is unset or withheld, or a substitution that fails, refuses the pipeline with none of its stages started. The value is put in that one process's environment after the line's literal assignments, and then the environment is withheld from again, so a removed credential is not brought back. It is held in no structure that is written or printed.

The command is compiled by the same compiler. cmd goes through the same program resolution, permission checks, redirection and write-set handling as any stage, and what it reads and writes is in the plan's sets. It runs as an earlier stage, in the same directory, under the same deadline, cancellation, confinement and scrubbed environment as the stage that uses it, with no standard input. A job started in the background, where the line may be one (RUN-15), works its substitutions out before its first stage starts, under the run call's own cancellation and deadline: a cancel ends the substitution and starts nothing, and one that outlasts the deadline is refused naming its source. The job it starts is not held to that deadline. It is one level deep: a $VAR, $(…) or backtick inside cmd is refused. A refusal inside cmd is reported as that refusal.

A redirection inside a substitution is a redirection of the line. cmd opens its destinations and sources at the same moment the line's own stages do. The checks made when one is opened (CMDLINE-5), the refusal to read a store (RECALL-8) and the trust map's entry for a destination are made on the path a foreground line takes when it cannot be moved, and the path of a background job and of a movable line does not make them. A line with a >, >>, < or 2>&1 inside a substitution is therefore refused with background: true like a line with one of its own, and it is not offered to be moved to the background (RUN-25). A substitution with no redirection changes neither answer.

A variable that is withheld is refused. A name bravebot_config::scrub::withheld() returns, which includes this agent's own credentials and the names in run.scrubEnv, is refused when the line is compiled and again when the step is spawned. A variable that is unset, or whose value is not valid Unicode, is refused when the step is spawned, naming the variable and nothing else. A variable set to v-\xff is refused as not valid text; one set to v-\u{FFFD} is valid text and reaches the program unchanged.

A failure says what ran and how it ended, not what it printed. A substitution that fails to start, is stopped or exits non-zero fails the line before the stage that uses it, naming the source text and the exit status. Neither its standard output nor its standard error is in the message. A substitution whose own line fails to open a file, a redirection's source or destination, says so with the file named once, under the directory the line was run in as the planner wrote it. The message never carries the place a link in that tree led, which whoever wrote the tree chose (CMDLINE-4).

The output is the value, and the driver decides nothing from it. cmd may be a program nobody vouched for, so what it printed is untrusted (RUN-4). Its length and its encoding are not looked at: 65537 bytes and a \xff reach the program as they were printed, and a U+FFFD arrives as its own three bytes. The bytes are the ones the pipe delivered, not the lossy text made of them for display. The one change made to them is that trailing \n and \r\n are cut, as a shell does, and that cut depends on the line ends and on nothing else. A value the operating system will not put in an environment, a NUL byte or more than it holds, fails the start of the stage that would receive it, and that error names the program and the operating system's words, never the value. On Windows an environment value is text, so the bytes are read as UTF-8 and each sequence that is not valid is replaced by U+FFFD. That is a change to the value that depends on no outcome the driver takes, where a refusal would be a decision taken from what an unvouched program printed.

Nothing remembered covers such a line. A line carrying an expansion is treated as a line with an environment assignment is: a remembered answer, a grant or an allow rule is not matched against it, and it is not offered the keys that remember a line, because what it will run depends on a value nobody was shown. (Under bypass no prompt is drawn at all; this is what holds for the same plan if it reaches one.)

verified-by: bravebot_agent::cmdline::a_variable_is_refused verified-by: bravebot_agent::cmdline::an_assignment_in_front_of_the_program_is_environment verified-by: bravebot_agent::cmdline::bypass_expansions_are_refused_outside_bypass_mode verified-by: bravebot_agent::cmdline::bypass_assignment_variables_are_kept_as_source verified-by: bravebot_agent::cmdline::bypass_assignment_substitution_runs_as_an_earlier_stage verified-by: bravebot_agent::cmdline::bypass_assignment_may_precede_a_later_pipeline_stage_or_a_second_assignment verified-by: bravebot_agent::cmdline::bypass_leaves_every_other_expansion_refused verified-by: bravebot_agent::cmdline::bypass_refuses_backticks_everywhere_including_an_assignment_value verified-by: bravebot_agent::cmdline::bypass_refuses_a_withheld_variable verified-by: bravebot_agent::cmdline::bypass_substitution_is_one_level_deep_and_inner_refusals_propagate verified-by: bravebot_agent::cmdline::bypass_substitution_is_judged_by_the_rules_like_any_step verified-by: bravebot_agent::exec::an_expanded_variable_reaches_the_spawned_program verified-by: bravebot_agent::exec::an_expanded_substitution_reaches_the_spawned_program_with_trailing_newlines_trimmed verified-by: bravebot_agent::exec::an_expansion_reaches_a_job_started_in_the_background verified-by: bravebot_agent::exec::an_unset_variable_is_refused_naming_the_variable_and_nothing_runs verified-by: bravebot_agent::exec::a_failing_substitution_is_refused_naming_its_source_and_status_but_not_its_output verified-by: bravebot_agent::exec::a_substitution_printing_a_nul_byte_fails_the_start_naming_the_program_and_not_the_value verified-by: bravebot_agent::exec::a_substitution_that_cannot_open_a_file_keeps_the_error_and_its_path verified-by: bravebot_agent::tools::a_failure_inside_a_substitution_is_respelled_under_the_directory_as_typed verified-by: bravebot_agent::tools::a_redirection_a_hook_made_inside_a_substitution_is_not_respelled_again verified-by: bravebot_agent::turn::an_unopened_file_inside_a_substitution_is_named_under_the_directory_as_typed verified-by: bravebot_agent::turn::a_redirection_refused_inside_a_substitution_is_named_once_under_the_directory_as_typed verified-by: bravebot_agent::confine::neither_a_policy_row_nor_a_refusal_depends_on_the_directory_a_stage_starts_in verified-by: bravebot_agent::exec::a_variable_that_is_not_unicode_is_refused_and_one_holding_the_replacement_character_is_not verified-by: bravebot_agent::exec::a_substitution_printing_bytes_that_are_not_text_reaches_the_program_byte_for_byte verified-by: bravebot_agent::exec::the_trailing_line_ends_of_a_substitution_are_cut_from_its_bytes_and_nothing_else verified-by: bravebot_agent::exec::a_background_start_is_cancelled_while_its_substitution_runs verified-by: bravebot_agent::exec::a_background_start_holds_its_substitution_to_the_calls_deadline verified-by: bravebot_agent::exec::a_substitution_printing_more_than_65536_bytes_reaches_the_program_whole verified-by: bravebot_agent::exec::a_substitution_printing_more_than_the_system_takes_fails_the_start_naming_the_program verified-by: bravebot_agent::exec::an_expanded_secret_appears_in_no_plan_text_error_or_result verified-by: bravebot_agent::tools::tests::arguments::a_variable_assignment_runs_in_bypass_and_is_refused_in_every_other_mode verified-by: bravebot_agent::tools::tests::arguments::a_background_run_is_cancelled_while_its_substitution_runs_and_one_that_outlasts_the_deadline_is_refused verified-by: bravebot_agent::tools::tests::arguments::a_background_line_whose_substitution_has_no_redirection_still_starts verified-by: bravebot_agent::tools::tests::arguments::a_background_line_whose_substitution_redirects_a_script_s_output_is_refused verified-by: bravebot_agent::tools::tests::arguments::a_delegates_background_line_with_a_redirection_in_a_substitution_is_refused verified-by: bravebot_agent::tools::tests::arguments::a_foreground_line_with_a_redirection_in_a_substitution_is_not_offered_to_be_moved verified-by: bravebot_core::command::a_route_inside_a_substitution_is_a_route_of_the_line verified-by: bravebot_agent::exec::a_withheld_variable_is_refused_at_spawn_and_its_value_is_not_in_the_error verified-by: bravebot_agent::exec::an_expanded_secret_appears_in_no_plan_text_error_or_result verified-by: bravebot_core::remembered::a_step_carrying_an_expansion_is_not_covered_by_an_entry verified-by: bravebot_core::remembered::a_line_carrying_an_expansion_is_covered_by_no_entry_and_no_scope verified-by: bravebot_core::remembered::a_line_carrying_an_expansion_is_offered_no_scope verified-by: bravebot_core::command::an_expansion_counts_as_an_assignment_and_keeps_a_line_from_being_remembered verified-by: bravebot_core::policy::a_vouched_line_carrying_an_expansion_is_asked_about verified-by: bravebot_core::policy::output_of_a_vouched_line_carrying_an_expansion_is_untrusted verified-by: bravebot_core::policy::an_expansion_asks_even_for_a_line_a_rule_allows verified-by: bravebot_core::policy::a_remembered_line_carrying_an_expansion_is_asked_about_and_offered_no_key verified-by: bravebot_core::policy::an_expansion_leaves_a_step_unproven verified-by: bravebot_agent::exec::an_expanded_secret_appears_in_nothing_bravebot_shows_about_a_background_start verified-by: bravebot_agent::tools::tests::arguments::an_expanded_secret_reaches_neither_the_trail_nor_what_run_reports_about_the_call verified-by: bravebot_core::command::an_expansion_is_drawn_from_its_source verified-by: bravebot_core::command::a_step_with_an_expansion_draws_it_in_front_of_its_program verified-by: bravebot_core::command::the_steps_of_a_plan_list_a_substituted_command_before_the_step_using_it verified-by: bravebot_core::command::two_plans_differing_only_in_an_expansion_never_encode_alike verified-by: bravebot_agent::cmdline::a_plan_holding_a_substituted_command_is_still_paired_with_the_operands_of_the_line verified-by: bravebot_agent::confirm::a_summary_counts_the_command_inside_a_substitution

The command inside NAME="$(cmd)" is a step of the plan, so the prompt's step count and its rows include it, in the order it runs. The operands the planner is told are paired with the commands of the line's shape, which the substituted command is not one of.

The guarantee covers what bravebot shows or writes. It does not cover a program that prints the value it was handed: bravebot cannot tell that it did, so that output is the line's output, which is (U,priv) under an expansion, and the planner reads it only where it may read such output. verified-by: bravebot_agent::exec::a_program_that_prints_an_expanded_value_puts_it_in_its_own_output_only verified-by: bravebot_core::policy::output_of_a_vouched_line_carrying_an_expansion_is_untrusted

Amendments to existing specs

This spec cannot land without these. Each is a real change to a normative clause and none should be made quietly.

Each is named by what the clause says rather than by its id, because an id from another file means nothing until you have opened that file.

Spec The clause Change
run.md run takes a pipeline of argv stages, never a command string Amended. The planner's spelling becomes a command line; the execution path stays argv-only, which is the half that carries the property. The clause's second paragraph survives verbatim and is the load-bearing one.
run.md argv is routing and must be endorsed by a person Amended. Routing is the compiled plan rather than the argv the planner wrote. (T,pub) and exact binding are unchanged.
run.md the table of what output is labelled Extended. A fourth row: output of a read-proven plan, labelled from its read set. The default is untouched.
run.md every run asks unless every stage was vouched for Narrowed by CMDLINE-9. "There is no read-only category" becomes "there is no declared read-only category, and one narrow proven one".
run.md the vouched-for list is not an allowlist Unchanged and reaffirmed. The audited table is not an allowlist either: it decides a label and a prompt, never whether something may run. Nothing is refused for being absent from it.
run.md a run has a wall-clock limit, and reaching it ends the run rather than failing it Superseded by CMDLINE-13, which keeps that behaviour and makes the limit per call.
shell-mode.md the planner gets no shell tool, ever Amended, and this is the big one. "The planner gets no shell tool" stands: no shell process is started for anything the planner wrote. What is withdrawn is the reading that also banned the notation. The clause should be restated as the planner's line is never interpreted, which is what it was protecting.
permissions.md every stage of a pipeline is judged on its own Amended. Stages come from the compiler rather than from an array. Its closing sentence, that there is no shell to do the splitting and so this holds rather than being a matter of parsing carefully, must be replaced with the honest version: the splitting is done once, here, and nothing re-splits afterwards.
tools/read-output.md letting a person release quarantined output Unchanged, and used less. It remains the route for output no proof and no person has covered.
trust-map.md what a write asks, and what it records Read one way for a redirection, per CMDLINE-5. The rows recording a path as trusted do not fire, since an append keeps what the file already held. The question put before the write is the run prompt of CMDLINE-3, which shows every destination and is put whatever the map says about them, rather than the map's own question about a path that is about to stop being trusted.

What is deliberately not adopted

  • Command substitution and parameter expansion. CMDLINE-2. These are the whole of what makes a shell string unendorsable, and adopting them would give up the property the rest of the spec is built to keep. The sole exception is the bypass-only assignment prefix of CMDLINE-17: $NAME, ${NAME} and one level of $(cmd) as the value of NAME= in front of a program. As an argument, as a program, nested, or outside bypass, they stay refused.
  • A fallback to a real shell when compilation fails. The single change that voids this spec.
  • Aliases and profile loading. A line's meaning must be in the line. Shell mode loads the user's syntax because a person typed it; nothing here does.
  • Confinement of children. Out of scope of this spec: what a program may reach is ../sandboxing.md's (SANDBOX-17).
  • git in the audited table. CMDLINE-8.

Open questions

  • Whether a closed set of harness-supplied variables (workspace root, current directory) should be expanded at compile time. It is the same thing as the planner having written the value, so the objection in CMDLINE-2 does not obviously reach it.
  • Whether the read set should extend to a directory the plan walks but does not name, which is what find . -name x does. Naming . makes the read set the whole workspace, which is correct but coarse.
  • Whether a background run's wake-up should be allowed to interrupt a round in flight or only land between rounds.

Known costs

  • A compiler is a thing that can be wrong. It is smaller than a shell and it is the only reader of the line, so a bug is a wrong plan rather than a divergence between two interpreters, but a wrong plan is still shown to a person as if it were right. The mitigation is that the plan, not the line, is what is displayed: a reader endorsing a plan that does not match the line they can see above it will notice.
  • The audited table is maintenance, and it goes stale towards the prompt. Every entry is a claim checked against one program's option surface, and option surfaces change with versions and with implementations. An entry lists what it recognises, so a version that adds an option refuses the calls that use it rather than accepting them, and only the options both the GNU and the BSD spelling agree on can be listed at all. An option after an operand is refused for the same reason, so grep -r TODO src -n asks where grep -rn TODO src does not. The cost is a prompt for a call that would have been fine, which is the right direction and is still work.
  • The audited table was read against the option lists of GNU, BSD, busybox and uutils, and run against none of them but the BSD tools of macOS. The matcher compares an option by its exact spelling, so a GNU abbreviation (--outp=x, --files0) is refused whichever program would have accepted it, and an attached value on an option that takes none, a cluster holding an option that is not listed or that takes a value, and any option after an operand are refused as well. After -- a word is an operand, as it is for the programs. No listed option is known to write a file or run a program in GNU, busybox or uutils. An option that one of them gives a meaning its BSD namesake does not have is unchecked there, because the table is run against the BSD tools only. ls -l and ls -n also read the user and group databases, which no answer names.
  • A name is refused where it lands in the workspace or the rest of that set, and no name is ever positively identified. The audited utilities are supplied by the operating system and differ by platform, distribution and package manager, so no hash or signature can be pinned for one: an entry is a claim about a program under a name, checked against one implementation's option surface, and what runs is whatever $PATH reached. Refusing a resolution inside the workspace or the rest of that set closes the route a file in the tree takes to an entry. It leaves the case with no attacker in it: where grep means ugrep, an implementation with a far larger option surface, the entry describes a different program than the one that runs and an option the two read differently is proven against the wrong audit. Refusing every $PATH directory the trust map is silent about would cover more of the category and would also refuse the genuine utilities under the layouts above, which is a prompt on every audited call.
  • A checkout at the account home or at / puts every program under it in the set. Where the home directory holds a .git, such as a dotfiles repository, a session opened below the home with no nearer .git has the home as its checkout. An audited name that resolves to a file anywhere under the home, such as a ~/.cargo/bin or a ~/bin, then asks, and its output is untrusted. A checkout at / does the same for every program, and the system's /usr/bin is then under it. Only the nearest checkout is taken, so an outer repository that contains the checkout adds nothing. A checkout marked by something other than a .git, such as .hg or .jj, is not in the set, and neither is a checkout in a layout with no .git above the directory: there only the directory itself is. A program kept in a checkout of that kind is judged as any other program is, by the trust map and the system's directories. The cost is a prompt for a call that would have been fine, which is the right direction.
  • A toolchain's install and cache directories are not in the set. A ~/.cargo/bin or ~/.rustup that lies outside every directory the set lists is a directory a person installed into, so a program resolved there is honoured as a $PATH directory outside the set is. An install is read and never written by a confined stage (SANDBOX-15), and a cache is not searched for programs. Where such a directory lies under a checkout that holds a .git, or is a directory a stage was granted to write, it is in the set for that reason.
  • A proof is about paths, and the trust map answers about names. A symlink inside a vouched-for directory pointing at a file outside it is a name the map covers and bytes it never saw, so a read-proven line reading through one comes back trusted. The table refuses the recursion flag that follows links while walking, which closes the case where the planner never named the link; it does not close a link the planner names. Keying the map on where a path lands is what closes it, and that is a change to every rule the map holds, described under known costs in trust-map.md.
  • More expressiveness is more that can be approved carelessly. A one-line plan with eight stages and two redirections is harder to read at a prompt than git log --oneline -50. Bounding glob expansion helps; nothing fixes it entirely.