Keeping the Original Plan Clean While Another Agent Handles Command Trial and Error

Keeping the Original Plan Clean While Another Agent Handles Command Trial and Error

A good plan can get buried under command experiments. One minute the plan is crisp: check the source, change one path, run the focused test. Ten minutes later the same thread is full of quoting mistakes, failed shell syntax, half-correct paths, stale assumptions, and recovery notes. That noise is useful while debugging, but it is not always useful inside the original planning context.

AxiOwl supports a cleaner operator workflow: keep the planning session responsible for the intended path, then hand command trial and error to a separate provider session. The separation is not automatic memory cleanup. AxiOwl does not erase context from a chat or decide which attempts are noise. The useful behavior is more concrete: independent sessions can be addressed by name, messages cross explicit handoff boundaries, replies come back through the same routing model, and receipts say only what AxiOwl can prove.

Sources read

The clean-plan role

The original planning session should hold the problem statement, constraints, acceptance criteria, and chosen route. Its job is to keep the shape of the work stable. If it also becomes the place where every command typo and failed probe is recorded, the plan can become harder to audit. The operator may lose track of what was decided versus what was merely tried.

In AxiOwl terms, the planner is just one registered provider session. The registry maps a display name and aliases to a provider, provider session id, node id, sendable state, source, timestamps, and error state. That means the operator can target a planning session by name without pretending every other chat shares the same context.

The trial session is a separate target. It can be created or selected for messy work: trying command forms, testing quoting, confirming which provider-specific path works, or reducing a failed attempt into a working recipe. When it has something worth sending back, it replies through AxiOwl as a separate message.

That distinction matters. The original plan stays clean because the operator chooses what to forward back into it. AxiOwl provides the message transport and identity boundary; it does not sanitize the plan on its own.

What AxiOwl actually hands off

The product contract is intentionally narrow: a named sender sends a text body to a named target, AxiOwl resolves both names, builds one final visible message, selects one provider edge, records evidence, and returns an honest receipt.

The current implementation follows that shape through the CLI and MCP server. The CLI supports direct sends:

axiowl send --to "Command Trial Agent" --body "Try the command variants and report the smallest working command plus the failed forms that mattered."

For longer handoffs, the documented path is stdin:

@'
The original plan is:
1. Inspect the provider routing path.
2. Make the smallest scoped change.
3. Run the focused test.

Please handle command trial and error outside the planning thread.
Return only:
- the final command that worked
- the important failure reason
- any blocker the planner must know
'@ | axiowl send --to "Command Trial Agent" --stdin

When the request enters MessagePipeline::send(), AxiOwl validates the target and body, resolves sender identity, resolves the target registry row, optionally runs one targeted discovery repair, builds the final visible body, then hands the provider request to the delivery worker. Provider dispatch is selected from the registry row through provider_edges.cpp; provider adapters do not get to choose a different family silently.

That is the operational handoff. The trial agent receives a visible message with the actual work request and a reply path. The planner does not need to carry every failed shell experiment unless the operator sends those details back.

Creating a separate trial session

AxiOwl also has an explicit create path. The CLI usage includes:

axiowl create --provider <provider> --name <agent> [--body <message> | --stdin] [--from <agent>] [--from-node <node>] [--model <model>] [--cwd <cwd>]

That path builds a CreateRequest, records create lifecycle events, calls create_with_provider(), and enrolls the returned provider session in the registry when the provider supplies a usable session id. The create result tracks fields such as provider, state, method used, evidence, provider display name, provider session id, correlation state, and whether a rename is recommended.

For a CLI-created trial session with an initial body, sender identity matters. The current run_create implementation rejects raw CLI create with an initial message unless the sender can be resolved or --from is provided, except for the special Antigravity CLI raw-provider-create branch. That is a useful guardrail for this workflow: the trial session should know who asked for the probe, and the reply route should be explicit.

MCP hosts get a more direct operator surface. The MCP server advertises axiowl_create_agent for creating provider chats and axiowl_send_message for sending messages. Its initialization instructions tell provider hosts to use those typed tools, require the host MCP session id as the stable sender identity key, and not construct raw command lines or invent session ids. That is exactly the kind of boundary a clean-plan workflow needs.

Receipts prevent false confidence

The clean-plan workflow depends on not overstating what happened.

AxiOwl's docs and code separate local acceptance from provider proof. The CLI prints an "AxiOwl handoff receipt" when the pipeline accepts a request. If the receipt state is accepted_by_axiowl, the output explicitly says provider delivery, provider wake-up, and provider reply are not implied. The delivery log is the place to inspect the next stages.

The tests enforce that boundary. The send pipeline test expects a successful send to return accepted_by_axiowl, not provider acceptance, and checks that the log records the receipt boundary before delivery worker or provider work. It also expects the sender receipt path not to wait for provider delivery results.

That makes the handoff usable without turning it into a false conclusion. The planner can record: "I handed command probing to the trial agent." It should not record: "The trial agent finished" until a real reply comes back. A response over MCP with provider-owned sender identity is the stronger evidence that the target session received the message and acted on it.

Why this keeps trial and error out of the plan

Command trial and error is often exploratory. The agent may need to discover whether a local command expects PowerShell or Bash syntax, whether a provider CLI accepts stdin, whether an installed binary is on PATH, or whether a quoted argument must be escaped differently. Those attempts can be valuable in the trial session, but they are not all plan decisions.

With AxiOwl, the operator can split the work like this:

  1. The planner writes the intended approach and constraints.
  2. The operator sends only the command-risk portion to a separate trial session.
  3. The trial session tries commands, captures relevant failures, and finds the working form.
  4. The trial session replies through AxiOwl with the distilled result.
  5. The planner receives only the result needed to update or execute the plan.

The important part is step 4. Replies are not part of the original send receipt. The message pipeline docs call this out directly: if the receiver replies, it starts a new pipeline, and the original sender becomes the target. There is no special response pipeline.

That means the trial session's answer is an explicit event. It can include a message id, run id, receipt correlation, and sender identity, rather than being an invisible update to shared memory.

The final visible body matters

AxiOwl builds a final visible body after sender and target resolution. When the sender is resolved, the body identifies the sender, includes the original message, and appends an exact MCP reply instruction back to the sender. When the sender is unresolved, the body uses an unresolved sender warning and does not attach a return command.

For this workflow, that is more than formatting. It prevents the trial agent from guessing where to report the result. The clean planning session is not relying on a vague instruction such as "tell me later." The visible handoff gives the receiving session a concrete way to answer.

The current MCP server reinforces the same rule. axiowl_send_message uses the host MCP session id as the stable sender identity key, registers sender identity when it has usable metadata, and refuses no-session sends when required identity is missing. It logs inbound MCP send receipts with target, body size, sender session id, sender name, provider, host kind, identity source, run id, receipt correlation, CLI exit code, and receipt boundary.

That is the difference between a clean plan and a magical-cleanup claim. AxiOwl is not filtering the trial transcript. It is making the handoff and return path explicit enough that the operator can keep only the useful result in the planning context.

A practical operator pattern

For command-heavy work, name the roles plainly.

Use the planning session for stable material:

Use the trial session for volatile material:

Then require the trial session to reply with a compact report:

Working command:
<command>

Important failures:
<only failures that affect the plan>

Plan impact:
<keep/change/block>

That reply is what belongs back in the planning thread. The failed attempts can stay in the trial session unless they are needed for audit or debugging.

What AxiOwl is careful not to promise

AxiOwl does not claim that independent sessions are isolated operating-system sandboxes. It does not prevent an agent from running a bad command if that agent has command access in its own environment. It does not automatically summarize command attempts or remove noisy context from the original plan.

The real product behavior is narrower and more useful: local registry-backed addressing, explicit sender and target resolution, provider-specific edges, MCP tool surfaces, create and rename lifecycle records, background delivery handoffs, and receipts that distinguish local acceptance from provider proof.

That is enough to support the clean-plan pattern. The operator can keep the original plan focused, move risky command exploration to another agent, and bring back only the evidence needed to proceed.

Closing

Keeping the original plan clean is an operations discipline, not a hidden AxiOwl cleanup feature. AxiOwl enables the discipline by treating provider sessions as addressable, independent participants and by moving work between them through explicit handoffs.

For command trial and error, that is the right level of control. Let one session preserve the plan. Let another session absorb the messy attempts. Bring the result back through AxiOwl only when it is clear enough to update the plan.

Image prompt:

Create a polished graphic image related to: keeping a planning session clean while a separate agent handles command trial and error.

Subject: a clean technical planning clipboard behind a clear divider, connected by a narrow handoff tray to a separate terminal workstation showing abstract command blocks and error/status symbols with no readable text.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no watermark.

Tagged