Merge pull request #735 from ruskaruma/fix/mandate-ao-cli-in-prompt

fix(core): mandate ao send and ban raw tmux in orchestrator prompt

packages/core/src/__tests__/orchestrator-prompt.test.ts

@@ -43,6 +43,18 @@ describe("generateOrchestratorPrompt", () => {
     expect(prompt).toContain("do not edit repository files or implement fixes");
   });
 
+  it("mandates ao send and bans raw tmux access", () => {
+    const prompt = generateOrchestratorPrompt({
+      config,
+      projectId: "my-app",
+      project: config.projects["my-app"]!,
+    });
+
+    expect(prompt).toContain("Always use `ao send`");
+    expect(prompt).toContain("never use raw `tmux send-keys`");
+    expect(prompt).toContain("ao send --no-wait");
+  });
+
   it("pushes implementation and PR claiming into worker sessions", () => {
     const prompt = generateOrchestratorPrompt({
       config,

packages/core/src/orchestrator-prompt.ts

@@ -34,7 +34,9 @@ Your role is to coordinate and manage worker agent sessions. You do NOT write co
 - Investigations from the orchestrator session are **read-only**. Inspect status, logs, metadata, PR state, and worker output, but do not edit repository files or implement fixes from the orchestrator session.
 - Any code change, test run tied to implementation, git branch work, or PR takeover must be delegated to a **worker session**.
 - The orchestrator session must never own a PR. Never claim a PR into the orchestrator session, and never treat the orchestrator as the worker responsible for implementation.
-- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.`);
+- If an investigation discovers follow-up work, either spawn a worker session or direct an existing worker session with clear instructions.
+- **Always use \`ao send\` to communicate with sessions** — never use raw \`tmux send-keys\` or \`tmux capture-pane\`. Direct tmux access bypasses busy detection, retry logic, and input sanitization, and breaks multi-line input for some agents (e.g. Codex).
+- When a session might be busy, use \`ao send --no-wait <session> <message>\` to send without waiting for the session to become idle.`);
 
   // Project Info
   sections.push(`## Project Info
@@ -88,6 +90,7 @@ ao open ${projectId}
 | \`ao session kill <session>\` | Kill a specific session |
 | \`ao session cleanup [-p project]\` | Kill completed/merged sessions |
 | \`ao send <session> <message>\` | Send a message to a running session |
+| \`ao send --no-wait <session> <message>\` | Send without waiting for session to become idle |
 | \`ao dashboard\` | Start the web dashboard (http://localhost:${config.port ?? 3000}) |
 | \`ao open <project>\` | Open all project sessions in terminal tabs |`);