@enderfga/claw-orchestrator 6.4.0 → 7.0.0

package/skills/references/multi-engine.md

@@ -36,6 +36,12 @@ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Cla
 - Full cost tracking from API usage data
 - Cross-session peer messaging (`crossSessionInbound`): sets this session's policy for messages sent from other Claude Code sessions on the same machine — `accept` delivers straight in, `hold` waits for a human to approve it in that session's terminal, `refuse` rejects it. There is no CLI flag for this; it is a settings key, delivered through the `--settings` merge. Worth setting explicitly for orchestrated sessions: with no value the CLI decides from the two sides' permission modes and holds when they differ, and an orchestrated session (`bypassPermissions` / `acceptEdits`) versus a human terminal (prompting) is exactly that case — so the message parks waiting for approval in a terminal nobody is watching. Sessions started by the orchestrator do register as addressable peers and do receive messages (verified against 2.1.232 by sending to a live one and getting a reply). Note that a user-level `~/.claude/settings.json` value may take precedence over the per-session one; only the `accept` path has been confirmed end-to-end here.
 - Hook lifecycle events (`includeHookEvents`), subagent output forwarding (`forwardSubagentText`), permission delegation (`permissionPromptTool`), prompt cache optimization (`bare` + `excludeDynamicSystemPromptSections` + `enablePromptCaching1H`), debug control, `--from-pr` resume, and MCP channel subscriptions
+- `--permission-prompts none` is passed whenever no `permissionPromptTool` is configured (CLI
+  2.1.259+). This spawn shape has no TTY and, without a prompt tool, no host to answer a permission
+  prompt — so before this a tool call the permission mode did not already decide sat waiting for an
+  answer that could never come, until the turn timeout. `none` denies it instead; the model sees the
+  denial and can adapt, and the permission mode still decides everything else. With a prompt tool
+  configured the CLI's default (`host`) is left in place so the tool is asked
 - `restricted` → `--restricted` (CLI 2.1.249+): removes the command- and code-running tools and
   `WebFetch` from the session, and ignores user/project/local settings files. Not folded into
   `sandboxMode: 'read-only'`, which maps to plan mode — measured against 2.1.251, plan mode alone
@@ -99,7 +105,7 @@ Wraps `codex app-server --listen stdio:// --enable goals` as a long-running JSON
 - Cumulative token tracking from `thread/tokenUsage/updated` notifications. The same notification's `last` breakdown and `modelContextWindow` drive `contextPercent`, so it reports live occupancy against the window the server actually enforces (258,400 on 0.147.0) rather than a running total over the model's published window
 - Goal lifecycle observation via `thread/goal/updated` and `thread/goal/cleared` notifications
 - Goal control via the `codex_goal_*` tools (which internally send the `/goal` slash command as user text — see [tools.md](./tools.md#codex-13))
-- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_threads` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
+- v2 RPC tools (Codex 0.137): `codex_interrupt` (`turn/interrupt`), `codex_steer` (`turn/steer`), `codex_fork` (`thread/fork`), `codex_rollback` (`thread/rollback`), `codex_models` (`model/list`), `codex_thread_list` (`thread/list`). A `turn/completed` with `status: 'failed'` rejects the turn and increments `toolErrors`.
 - Thread resume: starting with `resumeSessionId` loads the existing thread via `thread/resume` instead of `thread/start`.
 
 > **Feature-flag risk.** The `goals` feature is marked "under development" in Codex 0.128.0 and has known bugs (e.g. issue #20591). The session class always passes `--enable goals` so it works the moment upstream stabilizes the feature, but during the transition period some goal commands may fail or be silently dropped on the server side. The wrapper layer is unaffected.
@@ -135,7 +141,7 @@ in print mode. Verified against `agy` **1.1.13**.
   `getStats().agyConversationId`.
 - **Reasoning effort**: session `effort` and per-turn `session_send` overrides map
   to `--effort`. agy accepts `low`, `medium`, and `high`; everything above that
-  (`xhigh`, `max`, `ultra`) clamps to `high`. agy 1.1.21 requires an effort with unsuffixed base
+  (`xhigh`, `max`, `ultra`) clamps to `high`. agy 1.1.25 requires an effort with unsuffixed base
   slugs such as `gemini-3.7-flash`, so `auto` resolves those to `high`; a model
   already ending in `-low`, `-medium`, or `-high` keeps that qualified effort.
   Per-turn overrides also work with qualified slugs: the adapter removes a
@@ -223,6 +229,12 @@ plan`. It refuses a direct write and a shell write, then loses to the third prom
   `--no-subagents`, the obvious next probe, deliberately not wired: the run that would have
   confirmed it hit the account's free-tier limit, and a probe that fails for lack of quota writes no
   file either. A read-only grok session throws rather than running writable under a read-only label.
+- **On a spent free tier, `grok -p` can hang silently instead of erroring.** Earlier in the same
+  session it printed a usage-limit message to stderr and exited 1; later invocations produced nothing
+  on either stream and never exited — in any directory, with or without `--no-leader`. The session's
+  turn timeout is what ends such a turn, so a caller on that tier pays the full timeout before seeing
+  a failure. Nothing in this wrapper can distinguish that hang from a slow turn; check `grok -p` by
+  hand when a grok session times out with no output.
 - Binary: `grok` (set `GROK_BIN` to override). Not `agent`: xAI's installer claims that name too,
   and so did Cursor's.
 - Requires Grok Build: see `x.ai/cli`.

package/skills/references/tools.md

@@ -43,7 +43,7 @@ Start a persistent coding session with full CLI flag support.
 | `crossSessionInbound`                | string                                                                                        | `accept` / `hold` / `refuse` — policy for peer messages from other Claude Code sessions on this machine (Claude engine). Delivered as a settings key; there is no CLI flag. Without it the CLI holds messages whose two sides run different permission modes, which is the usual orchestrated-session-to-human-terminal case                                                                                                                                                           |
 | `includeHookEvents`                  | boolean                                                                                       | Stream hook lifecycle events (PreToolUse/PostToolUse) as `system` events                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `forwardSubagentText`                | boolean                                                                                       | Forward subagent text and thinking into the output stream (Claude engine, CLI 2.1.211+). Without it the parent stream stays quiet while a subagent works                                                                                                                                                                                                                                                                                                                               |
-| `permissionPromptTool`               | string                                                                                        | MCP tool name to delegate permission prompts to (non-interactive use)                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `permissionPromptTool`               | string                                                                                        | MCP tool name to delegate permission prompts to (non-interactive use) When omitted, the session runs with `--permission-prompts none`: a prompt nobody could answer is denied rather than left waiting until the turn timeout. |
 | `excludeDynamicSystemPromptSections` | boolean                                                                                       | Move cwd/env/git context from system prompt to user message for better prompt cache hits; auto-enabled with `bare: true`                                                                                                                                                                                                                                                                                                                                                               |
 | `enablePromptCaching1H`              | boolean                                                                                       | Enable 1-hour prompt cache TTL (vs default 5-min); auto-enabled with `bare: true`                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `debug`                              | string                                                                                        | Debug categories to enable (comma-separated, e.g. `"api,mcp"`)                                                                                                                                                                                                                                                                                                                                                                                                                         |
@@ -300,7 +300,7 @@ Codex app-server v2 RPCs (require `engine: "codex-app"`). Method names + param s
 | `codex_fork`      | `thread/fork`     | `name`                                                          | `{ ok, threadId }` — branches the thread; returns the forked id                                              |
 | `codex_rollback`  | `thread/rollback` | `name`, `numTurns`                                              | `{ ok, numTurns }` — drops the last N turns                                                                  |
 | `codex_models`    | `model/list`      | `name`                                                          | `{ ok, models }` — incl. each model's `supportedReasoningEfforts`                                            |
-| `codex_threads`   | `thread/list`     | `name`, `searchTerm?`, `cwd?`, `archived?`, `cursor?`, `limit?` | `{ ok, data, nextCursor }` — list threads with filters + pagination                                          |
+| `codex_thread_list` | `thread/list`     | `name`, `searchTerm?`, `cwd?`, `archived?`, `cursor?`, `limit?` | `{ ok, data, nextCursor }` — list threads with filters + pagination                                          |
 
 To **resume** a codex-app thread, start a session with `engine: "codex-app"` and
 `resumeSessionId: "<threadId>"` — it loads the existing thread via `thread/resume` instead of
@@ -557,7 +557,9 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
 | `reviewer_engine`        | EngineType |          | Default Reviewer engine (default `claude`)                                                       |
 | `reviewer_model`         | string     |          | Default Reviewer model (Claude default `sonnet`)                                                 |
 | `reviewer_custom_engine` | object     |          | Trusted config when Reviewer may use `custom`. **Local callers only**                            |
-| `send_timeout_ms`        | number     |          | Per-message timeout (default 600000)                                                             |
+| `send_timeout_ms`        | number     |          | Per-agent send cap in ms (default 600000; inclusive 5000–7200000)                                |
+| `activity_lease_ms`      | number     |          | Inactivity lease in ms (default 1800000; inclusive 60000–7200000)                                |
+| `autoloop_hard_timeout_ms` | number   |          | Absolute run cap in ms (default 86400000; inclusive 600000–259200000)                             |
 
 > **Custom engines are local-only.** A `CustomEngineConfig` names an executable to
 > spawn plus its argv and env, so it may only be supplied by a caller that already
@@ -587,6 +589,25 @@ Start a chat-mode autoloop. Planner starts immediately; Coder + Reviewer start o
 
 Custom configs are not persisted or accepted from Planner output. See [`multi-engine.md`](./multi-engine.md) for their shape.
 
+The three timeout controls form a hierarchy. `send_timeout_ms` caps one
+Planner, Coder, or Reviewer delivery. A genuine send timeout is not retried:
+the run pauses in `awaiting_resume` with a stable pending dispatch identity.
+`activity_lease_ms` bounds inactivity and is renewed only by validated user or
+agent progress, never by timer checks or runner bookkeeping.
+`autoloop_hard_timeout_ms` is anchored to run start and never renews; it wins
+when it coincides with lease expiry.
+
+Recovery is exposed by `POST /autoloop/<id>/resume`, not by an MCP resume tool.
+Its timeout body is limited to `send_timeout_ms` plus
+`pending_dispatch_id`. The send timeout must be finite, in range, and strictly
+larger than the run's latest effective value (legacy baseline: 600000). Equal
+or smaller values are rejected, and there is deliberately no
+`allow_decrease`. Lease and hard-cap overrides are not accepted on resume.
+Each successful increase appends one migration row to `decisions.jsonl`; the
+original run spec, history, and prior audit bytes are not rewritten. The
+matching live awaiting-resume condition is advanced without replaying the
+timed-out logical dispatch.
+
 ### `autoloop_chat`
 
 Send a message into the Planner conversation.