Coordinator emits unresolved kubectl placeholders that are guaranteed to fail the command safety gate

[MSKazemi]

Summary

A real kq session hit a deterministic planning failure while trying to solve several cluster problems. The coordinator emitted an unresolved metavariable as an actual tool argument:

You: solve ths issues
⚙ run_kubectl → Running: kubectl describe pod ml-scorer-5bc9565b96-5tskr -n shop
⚙ run_kubectl → Running: kubectl describe pod payments-api-56f659864c-28s2w -n shop
⚙ run_kubectl → Running: kubectl get nodes -o wide
⚙ run_kubectl → Running: kubectl describe node <node-name>
...
Error: LLM error: Command contains disallowed shell characters ...

run_kubectl is correct to reject < and >: they are shell metacharacters and the runner intentionally blocks them. The bug is upstream: a placeholder that exists only as planning notation reached the execution surface.

Why this is a coordinator bug, not a sanitizer bug

The v4 coordinator prompt already says dependent calls must be sequential, but its parallel-execution guidance includes a describe node example without establishing a concrete node first. In this trace the model correctly knew it needed kubectl get nodes, but incorrectly scheduled kubectl describe node <node-name> in the same batch instead of waiting for the node name.

Do not fix this by weakening _SHELL_METACHAR in app/tools/kubectl_tool.py. The safety gate should continue rejecting < / >.

Expected behavior

If a command needs an identifier that is not already present in the cluster snapshot or conversation state, the coordinator should:

1. fetch the identifier first (kubectl get nodes -o wide),
2. wait for that result,
3. emit a second tool call using the concrete node name.

No metavariable such as <node-name>, <pod>, <namespace>, $NODE, {node}, or similar planning placeholder should ever be passed to run_kubectl.

Suggested scope

• Tighten the coordinator system prompt around dependent calls and replace the ambiguous parallel describe node example.
• Add a pre-execution/model-output guard that detects unresolved metavariables in tool arguments and routes them back for replanning rather than invoking the tool.
• Prefer resolving names from the existing snapshot before doing another discovery call when possible.

Acceptance criteria

• run_kubectl continues to reject < and > as shell metacharacters.
• The coordinator never invokes run_kubectl with an unresolved placeholder/metavariable.
• A node investigation where the node name is initially unknown emits get nodes first and describe node <concrete-name> only after the result is available.
• Add a regression test reproducing the get nodes + describe node <node-name> failure mode.
• The parallel-tool prompt example cannot be interpreted as permission to parallelize a call whose resource name is still unknown.

Reproduction context

The user first asked do you see any issues in my cluster; KubeIntellect identified ImagePullBackOff, CrashLoopBackOff, and an unschedulable Pending pod in namespace shop. The next request, solve ths issues, produced the batch above and failed on the placeholder command.

[MSKazemi]

Verified still live on main (2026-09-09), with exact locations — and one contributing cause the issue does not mention.

1. The ambiguous example is still there, verbatim

app/agent/nodes/coordinator.py:331:

Parallel (always):   (get pods) + (get events) + (describe node)

Exactly as this issue describes: describe node is offered as a parallel sibling of get pods / get events, with no step that establishes a concrete node name first. A model following this literally has no node to name, and <node-name> is the natural thing to write.

2. No guard exists

Grepping app/agent/ and app/tools/ for any metavariable / placeholder / unresolved-argument check finds nothing. Nothing between the model's output and run_kubectl inspects tool arguments for planning notation.

3. The prompt teaches the exact notation it then forbids

This is the part the issue does not cover, and it may matter more than the describe node example. The same prompt uses angle-bracket metavariables as its own notation, twice:

coordinator.py:545   TARGETED: namespace=<ns>, pod=<pod>, issue=<one-line description>
coordinator.py:574   "use narrower filters (e.g. `-n <namespace>`, `-l <label>`, `--tail`)"

So the model is shown <pod> / <namespace> as the house style for "fill this in", and then expected never to emit that shape into a tool argument. Line 574 is worse than 545 because it appears inside an example kubectl command — the precise context where the placeholder must not survive.

Tightening the describe node example while leaving those two in place would fix the symptom this trace happened to hit and leave the teaching signal intact. Whoever takes this should consider whether the prompt should use a visually distinct convention for its own metavariables (or spell them out in prose), not just fix line 331.

4. Severity has dropped since this was filed — the scope is now cleaner

When this was written, one such call aborted the entire parallel batch, discarding every sibling result. That is fixed: since #184, an invalid call becomes a per-call error ToolMessage and the other six investigations survive.

So this is no longer a "one bad placeholder destroys the investigation" bug. It is now: the coordinator wastes a call and returns a confusing error where it could have planned correctly. Lower severity, and a cleaner problem — the fix is purely about not emitting the placeholder, with no pressure to also protect the batch.

Still explicitly not the fix

Unchanged and worth repeating: do not weaken _SHELL_METACHAR in app/tools/kubectl_tool.py. Rejecting < and > is correct and is a safety invariant. The bug is upstream of the gate.

Suggested split, if it helps

Two independent pieces, either of which is a complete contribution:

1. Prompt-side — fix line 331's example, and decide what to do about the <...> notation at 545/574. No new code, and arguably the higher-value half.
2. Guard-side — detect unresolved metavariables in tool arguments before invocation and route back for replanning rather than calling the tool. Needs a test proving a placeholder never reaches run_kubectl.

help wanted and unclaimed — comment here and it is yours.

[biggdawg320]

I’ll take the standalone prompt-side contribution you offered: replace the ambiguous parallel example, require concrete identifiers from the snapshot or an earlier discovery result, and remove unresolved command placeholders from the prompt examples. I’ll leave the pre-execution guard as separate work and won’t mark the whole issue fixed. Codex assistance, with local validation and no changes to the kubectl safety gate.

[MSKazemi]

Status update — the prompt-side half landed via @biggdawg320's #207 (merged), which replaced the ambiguous describe node example and grounded the angle-bracket notation at 545/574 so the model isn't taught the shape it's then forbidden from emitting. Deliberately does not close this — the guard-side half (detect an unresolved metavariable in a tool argument before invocation and route back for replanning, with a regression test) is still open and unclaimed. help wanted if anyone wants the other half.