docs: steer agents to the structured contract tool, not Bash-composed egg-contract

sandbox/agent-config/rules/checkpoint.md

@@ -2,6 +2,23 @@
 
 Use `egg-checkpoint` to browse agent checkpoints (transcripts, tool calls, files, token usage). Full reference: `$EGG_REPO_PATH/docs/reference/checkpoint-browser.md`
 
+**Use the structured checkpoint tools — do not compose an `egg-checkpoint`
+command for the `Bash` tool.** The `search --text <t>` query and other
+free-text inputs are silently corrupted by shell metacharacters
+(backticks, `$(...)`, `$VAR`, `<`, `>`, `;`, `|`, `&`) when routed
+through a `Bash` command string, and a backtick or `$(...)` span is
+*executed* as a command rather than searched. The structured tools pass
+each field as data and never touch a shell:
+
+- **`claude_agent_sdk` harness** — the `mcp__checkpoint__*` tools
+  (mapped below).
+- **`EGG_HARNESS=egg`** — the `EggCheckpoint` tool: subcommand as
+  `command`, each flag and value as a separate `args` element.
+
+The `egg-checkpoint` commands below are the reference for what each
+operation does and stay available to human operators; agents invoke them
+through the structured tool.
+
 **Commands**: `list`, `show <id>`, `browse --issue <n>`, `context`, `cost`, `search --text <t>`. All support `--json`.
 
 **Common filters**: `--issue N`, `--pipeline ID`, `--agent-type TYPE`, `--phase PHASE`, `--status STATUS`
@@ -20,14 +37,15 @@ egg-checkpoint search --text "error" --status failed --limit 10
 
 **Empty results**: The CLI prints which repo/branch was searched to stderr. With `--json`, empty results produce valid JSON (`[]` or structured empty object).
 
-## Prefer MCP tools over the CLI
+## MCP tool equivalents (`claude_agent_sdk` harness)
 
-Sandbox agents on the default harness should call the in-process MCP
-tools instead of shelling out — they share the same `collect_checkpoints`
-/ `load_checkpoint` / `search_checkpoints` helpers the CLI uses
-(drift-gate enforced) and avoid a subprocess + JSON parsing step.
-Iteration-2 ([#1917](https://github.com/jwbron/egg/issues/1917)) added
-the **core 3** verbs (per decision-3) — `browse`, `context`, and
+On the `claude_agent_sdk` harness the operations above are also exposed
+as in-process MCP tools, which share the same `collect_checkpoints` /
+`load_checkpoint` / `search_checkpoints` helpers the CLI uses
+(drift-gate enforced). Prefer them for the reason in the callout above:
+free-text routed to the CLI through the `Bash` tool is mangled by the
+shell. Iteration-2 ([#1917](https://github.com/jwbron/egg/issues/1917))
+added the **core 3** verbs (per decision-3) — `browse`, `context`, and
 `cost` are still CLI-only and tracked for a follow-up.
 
 - `mcp__checkpoint__list` — Prefer this over `egg-checkpoint list`. Returns `{items, next_cursor}` paginated by `limit` (default 100) + opaque `cursor`.

sandbox/agent-config/rules/contract.md

@@ -1,6 +1,25 @@
 # SDLC Contract
 
-Use `egg-contract` to track SDLC pipeline progress. Full reference: `$EGG_REPO_PATH/docs/reference/sdlc-contract.md`
+Track SDLC pipeline progress through the contract. Full reference:
+`$EGG_REPO_PATH/docs/reference/sdlc-contract.md`
+
+**Use the structured contract tool — do not compose an `egg-contract`
+command for the `Bash` tool.** The free-text fields (`--question`,
+`--options`, `--notes`) carry LLM-authored prose. In a `Bash` command
+string the shell interprets backticks, `$(...)`, `$VAR`, `<`, `>`, `;`,
+`|`, and `&` — so prose that contains them (a markdown code span, a
+URL, a `<` comparison) is silently corrupted, and a backtick or
+`$(...)` span is *executed* as a command rather than stored. The
+structured tool passes each field as data and never touches a shell:
+
+- **`claude_agent_sdk` harness** — the `mcp__sdlc__*` / `mcp__task__*` /
+  `mcp__phase__*` tools (mapped below).
+- **`EGG_HARNESS=egg`** — the `EggContract` tool: subcommand as
+  `command`, each flag and value as a separate `args` element.
+
+The `egg-contract` commands below are the reference for what each
+operation does and stay available to human operators; agents invoke
+them through the structured tool.
 
 **Commands:**
 
@@ -19,13 +38,14 @@ Use `egg-contract` to track SDLC pipeline progress. Full reference: `$EGG_REPO_P
 
 **Env**: `EGG_ISSUE_NUMBER`, `EGG_REPO_PATH` (auto-set).
 
-## Prefer MCP tools over the CLI
+## MCP tool equivalents (`claude_agent_sdk` harness)
 
-Sandbox agents on the default harness should call the in-process MCP
-tools instead of shelling out — they share the same handler the CLI
-uses (drift-gate enforced) and avoid a subprocess + JSON parsing step.
-Iteration-2 ([#1917](https://github.com/jwbron/egg/issues/1917)) added
-the contract verbs that iteration-1 left as Bash-only:
+On the `claude_agent_sdk` harness the operations above are also exposed
+as in-process MCP tools, which share the same handler the CLI uses
+(drift-gate enforced). Prefer them for the reason in the callout above:
+free-text routed to the CLI through the `Bash` tool is mangled by the
+shell. Iteration-2 ([#1917](https://github.com/jwbron/egg/issues/1917))
+added the contract verbs that iteration-1 left as Bash-only:
 
 - `mcp__sdlc__show_contract` — Prefer this over `egg-contract show`. Returns the contract dict (optional `fields=[…]` projection; unknown field raises).
 - `mcp__task__add_commit` — Prefer this over `egg-contract add-commit`. Links a commit SHA to a task; does not mark the task complete.

sandbox/agent-config/rules/orchestrator.md

@@ -2,6 +2,26 @@
 
 Run `egg-orch --help` for full usage. All commands support `--json`. Full reference: `$EGG_REPO_PATH/docs/reference/orchestrator-cli.md`
 
+**Use the structured orchestrator tools — do not compose an `egg-orch`
+command for the `Bash` tool.** Several subcommands carry LLM-authored
+free text — `overseer alert --summary "…" --detail "…" --recommend "…"`,
+`progress emit --step "…" --detail "…" --blocker "…"`,
+`signal error --error "…"`, `anchor init --task "…"`. In a `Bash`
+command string the shell interprets backticks, `$(...)`, `$VAR`, `<`,
+`>`, `;`, `|`, and `&` — so prose that contains them (a markdown code
+span, a URL, a `<` comparison) is silently corrupted, and a backtick or
+`$(...)` span is *executed* as a command rather than stored. The
+structured tools pass each field as data and never touch a shell:
+
+- **`claude_agent_sdk` harness** — the `mcp__brc__*` / `mcp__progress__*`
+  tools (mapped below).
+- **`EGG_HARNESS=egg`** — the `EggOrch` tool: subcommand as `command`,
+  each flag and value as a separate `args` element.
+
+The `egg-orch` commands below are the reference for what each operation
+does and stay available to human operators; agents invoke them through
+the structured tool.
+
 **Essential commands:**
 
 | Command | Purpose |
@@ -30,11 +50,13 @@ Pipeline ID/agent role can be omitted when `EGG_PIPELINE_ID`/`EGG_AGENT_ROLE` ar
 
 **Related CLIs**: `egg-contract`, `egg-pipeline-watch`, `egg-checkpoint`
 
-## Prefer MCP tools over the CLI
+## MCP tool equivalents (`claude_agent_sdk` harness)
 
-Sandbox agents on the default harness should call the in-process MCP
-tools instead of shelling out — they share the same handler the CLI
-uses (drift-gate enforced) and avoid a subprocess + JSON parsing step.
+On the `claude_agent_sdk` harness the operations above are also exposed
+as in-process MCP tools, which share the same handler the CLI uses
+(drift-gate enforced). Prefer them for the reason in the callout above:
+free-text routed to the CLI through the `Bash` tool is mangled by the
+shell.
 
 BRC consensus + heartbeats:
 

sandbox/egg_lib/data/hitl_editing_rules.md

@@ -19,7 +19,7 @@ You are helping a human review and edit an SDLC pipeline draft document.
 - `egg-contract show` — view the current contract state, including pending questions and tasks
 - Read/edit the draft file directly
 
-## MCP-tool equivalents (HITL-edit harness)
+## MCP tool equivalents (HITL-edit harness)
 
 If the harness exposes the in-process MCP tools (default for the
 `claude_agent_sdk` harness), prefer those for contract reads — they

shared/egg_harness_integration/egg_tools.py

@@ -122,20 +122,38 @@ async def _handler(tool_input: dict[str, Any]) -> ToolResult:
 _EGG_TOOL_SPECS: list[tuple[str, str, str]] = [
     (
         "EggOrch",
-        "Execute egg-orch CLI commands for orchestrator interactions "
-        "(pipeline status, signaling, health checks, anchor management).",
+        "Orchestrator interactions via egg-orch subcommands: pipeline "
+        "status, signaling, health checks, progress events, overseer "
+        "alerts, anchor management, and message waits. Use this tool "
+        "for every egg-orch operation; pass the subcommand as `command` "
+        "and each flag and value as a separate `args` element. Never "
+        "invoke egg-orch through the Bash tool: free-text fields such "
+        "as --summary, --detail, --recommend, --step, --blocker, "
+        "--error, and --task are corrupted (or executed) by shell "
+        "metacharacters there.",
         "egg-orch",
     ),
     (
         "EggContract",
-        "Execute egg-contract CLI commands for SDLC contract tracking "
-        "(task completion, phase management, decisions).",
+        "SDLC contract tracking via egg-contract subcommands: show, "
+        "add-commit, complete-task, complete-phase, update-notes, "
+        "verify-criterion, add-decision, and add-feedback. Use this "
+        "tool for every egg-contract operation; pass the subcommand as "
+        "`command` and each flag and value as a separate `args` "
+        "element. Never invoke egg-contract through the Bash tool: "
+        "free-text fields such as --question, --options, and --notes "
+        "are corrupted (or executed) by shell metacharacters there.",
         "egg-contract",
     ),
     (
         "EggCheckpoint",
-        "Execute egg-checkpoint CLI commands for browsing agent checkpoints "
-        "(transcripts, tool calls, files, token usage).",
+        "Browse agent checkpoints (transcripts, tool calls, files, "
+        "token usage) via egg-checkpoint subcommands. Use this tool "
+        "for every egg-checkpoint operation; pass the subcommand as "
+        "`command` and each flag and value as a separate `args` "
+        "element. Never invoke egg-checkpoint through the Bash tool: "
+        "free-text fields such as --text are corrupted (or executed) "
+        "by shell metacharacters there.",
         "egg-checkpoint",
     ),
     (