pi-claude-supervisor 0.6.0 → 0.7.0

package/docs/architecture.md

@@ -79,9 +79,13 @@ one capability from the other.
 This is a control-boundary fixture and headless transport. It does not emulate a
 terminal. Manual compatibility mode remains `process-pipe`; automatic mode
 (`PI_CLAUDE_SUPERVISOR_MODE=auto`) defaults to Claude JSONL and can select the
-Supervisor-owned tmux bridge. The bridge uses the CLI contract validated by the
+tmux transport, which by default drives the real interactive Claude TUI through
+Claude Code hooks (`PI_CLAUDE_SUPERVISOR_TMUX_MODE=interactive`, see "Interactive
+tmux transport" below) and can fall back to the Supervisor-owned bridge
+(`TMUX_MODE=bridge`). The bridge uses the CLI contract validated by the
 fixed-version spike, renders the stream in the pane and carries structured records
-through private framing on the same PTY; explicit adoption remains manual-only.
+through private framing on the same PTY; the bridge cannot adopt an existing
+session, whereas the interactive mode adopts one through the user-level hook relay.
 
 A worker exit automatically triggers cleanup, and terminal status waits for
 that cleanup to be confirmed (or reports a cleanup error). Automatic Claude
@@ -185,6 +189,88 @@ private tmux server teardown, including after partial session creation, and a
 confirmed `kill-server` is sufficient cleanup evidence. A normal Claude
 `--resume` starts another process from history and is not a live PTY migration.
 
+### Interactive tmux transport
+
+`PI_CLAUDE_SUPERVISOR_TMUX_MODE=interactive` (the default when `TRANSPORT=tmux`)
+runs the real Claude Code TUI in the tmux pane instead of the structured
+stream-json bridge described above (`bridge` mode is the pre-existing
+transport, kept as an opt-out). `TmuxWorkerAdapter.start({ automatic: true,
+interactive: true, ... })` selects it; `interactive` and `structured` (bridge)
+are mutually exclusive sub-modes of the automatic tmux transport.
+
+**Hook relay and server.** Claude Code hooks (`SessionStart`, `PreToolUse`,
+`PermissionRequest`, `Stop`, `Notification`, `UserPromptSubmit`, `SessionEnd`)
+are configured to run a small embedded relay script
+(`src/hooks/relay.ts`'s `HOOK_RELAY_SCRIPT`, written to
+`<stateDir>/hooks/relay.js`). The relay reads the hook event JSON from stdin,
+hashes the event's `cwd` to find `<stateDir>/hooks/by-cwd/<sha256(cwd)>` — a
+symlink to a `HookServer`'s unix socket, created only while a Supervisor holds
+that cwd — and forwards the event over the socket, printing the reply as
+Claude's hook output. A cwd with no owning Supervisor is a fast no-op: the
+relay `stat`s the symlink path and returns before touching `net`. Non-blocking
+events (`SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`) are
+fire-and-forget; `PreToolUse`, `PermissionRequest` and `Stop` block Claude for
+up to `HOOK_TIMEOUT_SECONDS` (180s) waiting for a reply, and an unanswered
+request fails open to "no decision" so a relay or Supervisor bug never wedges
+Claude. `HookServer` (`src/hooks/server.ts`) is one socket per Pi process, with
+`subscribe(cwd, handler)` installing the per-cwd symlink; a Supervisor session
+subscribes for the lifetime of its task and unsubscribes on stop/release.
+`installUserHooks`/`uninstallUserHooks` (`src/hooks/install.ts`, exposed as
+`/supervise install-hooks`/`uninstall-hooks`) register the relay for all seven
+events in the user's real `~/.claude/settings.json` (or
+`$CLAUDE_CONFIG_DIR/settings.json`), required once for `adopt-tmux`; an owned
+launch instead writes a standalone settings file
+(`writeHookSettingsFile`, `src/hooks/settings.ts`) passed as Claude's
+`--settings <path>`, so it never touches the user's own configuration.
+
+**Two permission phases.** `PreToolUse` fires before Claude's own permission
+mode runs and is the enforced boundary: the Supervisor answers a policy denial
+there (a `PreToolUse` deny is reported to block a tool such as `git push`
+even under `permissions.defaultMode: auto`), forwards `AskUserQuestion` to the
+Decision Worker, and otherwise returns no decision (`defer: true`) so Claude's
+own permission mode decides — every other tool call is intentionally not
+audited at this phase, since it
+would just reproduce Claude's own prompt. `PermissionRequest` fires only when
+Claude is about to show a human a permission prompt (i.e. its own mode did not
+already decide); the Supervisor's existing hybrid/policy/Decision-Worker
+authority answers it exactly as before. `WorkerPermissionRequest.phase` is
+`"pre" | "prompt"` for an interactive session and `undefined` for the
+stream-json bridge or process-pipe transports. `AskUserQuestion` is always
+answered by the Decision Worker as a permission deny whose message is
+`Supervisor answer: <reason>` — Claude reads a `PreToolUse`/`PermissionRequest`
+deny's message as the reason the tool did not run, so the chosen answer and
+its rationale reach the model as ordinary text and the turn continues.
+
+**Human coexistence.** A prompt Claude receives that the Supervisor did not
+send (a human typing into the attached tmux pane) surfaces as a `human_input`
+Worker event; the Supervisor appends a bounded `human_input` event, enters
+human takeover (`human_takeover` with `data.source: "worker_prompt"`) if not
+already active, and pauses Decision Worker notification of further
+`turn_completed` events (they are still recorded so `resume-auto` can replay
+the last one) until `/supervise resume-auto`. A `pre`-phase request is still
+answered automatically during a human takeover (policy deny or defer) since it
+is not something a human is expected to approve; only a `prompt`-phase request
+pends for `/supervise approve`.
+
+**What stays scraped.** `pipe-pane`/`capture-pane` still provide the raw
+output log and a stable-prompt readiness signal for owned startup
+(`#waitForInteractiveReady`); no permission or completion decision is ever
+derived from screen text in interactive mode — `Stop` (→ `turn_completed`,
+`result.result` the last assistant message, `subtype: "stop"`) and the two
+permission hooks are the only structured signals. `--max-budget-usd` has no
+effect on the interactive TUI (Claude Code only enforces it under `-p`), so
+`automaticClaudeArgs`'s injected `--permission-mode default` and
+`--max-budget-usd` are stripped for an interactive launch; the Supervisor's own
+cumulative cost check (`#recordWorkerUsage`) is the only budget enforcement
+left, and it tolerates a `Stop` result with no `total_cost_usd`/`usage` (turn
+count still increments).
+
+A completed task normally releases (not stops) an interactive Worker,
+leaving the session open for the operator to review or continue by hand;
+`PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION=1` restores the old
+close-on-completion behavior. A blocked or failed outcome always stops the
+Worker as before.
+
 ## State machine
 
 ```text
@@ -202,7 +288,11 @@ updates run through one serial queue, so concurrent `poll`, `send`, `stop`,
 watchdog and shutdown work cannot produce duplicate terminal transitions. If a
 lifecycle event append fails after the state transition, it remains pending and
 is retried before the next lifecycle operation; output events restore their
-chunks for a lossless retry.
+chunks for a lossless retry. Worker lifecycle events (`turn_completed`,
+`permission_request`, `exited`) whose processing fails are kept in a deferred
+set and retried both by the watchdog tick and by `poll`, so an unattended task
+cannot lose its exit or turn result. `worker_output` events are size-capped
+(per-chunk and per-event) while the in-memory Reviewer tail stays complete.
 
 ### Cross-process cwd leases and startup cancellation
 
@@ -234,14 +324,40 @@ is alive; the extension periodically rechecks released sessions and removes the
 lease only after the pane is confirmed gone. If that check fails, the lease is
 retained rather than allowing a cwd overlap.
 
+A lease record that cannot be read (corrupt JSON, unexpected shape) is
+quarantined into `<leaseDir>/quarantine/` instead of blocking every other cwd
+lookup; `/supervise sessions` lists the current quarantined records so an
+operator can inspect and clean them up. A lease whose own directory has since
+disappeared is not treated the same as an unreadable record: it still fails
+closed for its own (possibly reused) path, but a directory that merely
+disappeared does not block lookups for unrelated, non-overlapping cwds.
+Releasing a retained cgroup removes verified-empty nested child cgroups
+bottom-up, since systemd/Claude can create child cgroups under a Worker's own
+cgroup that would otherwise leave the parent non-empty.
+
 Before model or Worker execution, automatic starts validate a full existing Git
-baseline, a non-bare worktree, a readable non-protected branch, the direct bare
+baseline, a non-bare worktree, a readable branch, the direct bare
 `claude`/`claude.exe` command name, JSONL transport, runtime state/lease directories
-and, when requested, the real writable cgroup-v2 boundary. The resolved Claude
+and, when requested, the real writable cgroup-v2 boundary. The task is anchored to
+this baseline commit, not to the branch name: any branch, including `main`, may
+start or host a supervised task, since Claude Code's own "branch first" guidance is
+advisory and the Worker commonly branches mid-task on its own. A protected branch
+name (`main`, `master`, `trunk`, `integration`, `develop`) is never itself a reason
+to refuse a start or park a candidate; only a remote push/merge/PR or a destructive
+rewrite of a protected branch (`reset`, `update-ref`, `symbolic-ref`, or `branch`
+with a delete/move/force flag) remains denied by policy. The resolved Claude
 executable is checked for an operator-owned, non-writable path and then pinned by
 absolute path; `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` can pin the expected identity. The initial repository HEAD is captured, and the repository boundary immediately
 before the Worker adapter starts must report that exact same HEAD (recovery captures
 and compares its current HEAD separately while retaining the persisted baseline).
+Every boundary check, and candidate verification itself, also requires the recorded
+baseline commit to remain an ancestor of the current HEAD; if history was rewritten
+out from under it, the boundary check fails closed and a candidate is parked rather
+than accepted. A branch name change (the Worker moving off its starting branch, most
+often onto a fresh feature branch) is recorded once as a `worker_branch_changed`
+event rather than rejected; the task context keeps the original starting branch,
+and a candidate notice reports the branch a candidate currently lives on together
+with whether it is protected, purely for information.
 Automatic lease acquisition also persists a no-spawn startup marker. Automatic
 adapters then persist the generated Worker/cgroup identity and clear that marker
 before the actual Worker spawn, closing the startup-registration crash window;
@@ -271,8 +387,12 @@ work, and the Supervisor rechecks cancellation before reporting `running`; a can
 Events are JSONL with a monotonic sequence number, timestamp, task ID and worker
 ID. Appends use a per-log atomic lock directory with owner PID, bounded waiting
 and stale-owner detection. Each append refreshes the sequence from disk while
-holding the lock, so independent Pi processes cannot reuse sequence numbers.
-The log is diagnostic evidence, not an authorization mechanism. Log contents
+holding the lock, so independent Pi processes cannot reuse sequence numbers;
+that refresh reads only the file's tail for the last sequence number rather
+than the whole log, keeping appends O(1) in log size. `events.jsonl` rotates to
+a timestamped sibling (`events.jsonl.<stamp>`) before an append that would
+exceed `PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES` (default 64 MiB), keeping the
+5 most recent rotated files. The log is diagnostic evidence, not an authorization mechanism. Log contents
 must be treated as sensitive because worker output may contain repository data.
 
 For Claude JSONL, the adapter tracks `activeRequests`, `lastInputAt` and
@@ -292,16 +412,76 @@ and task mapping are persisted under the supervisor state directory. After an
 unclean Pi restart, recovery is explicit: `/supervise recover [--takeover]
 <task-id>` restores
 the Decision Worker context and starts a new Claude Worker. It does not silently
-resume or duplicate a task. It does not poll to detect turn completion. A watchdog timer remains only as a deadlock safety
-fallback. Permission and other actions pass through the configured autonomy policy and
+resume or duplicate a task. It does not poll to detect turn completion. In automatic
+mode the watchdog is always armed: besides the deadline and no-output timeouts, it
+retries deferred lifecycle events, classifies a Worker that exited without an exit
+event, and starts verification for it. Permission and other actions pass through the configured autonomy policy and
 are recorded. The local development loop must not require synchronous human
 approval for ordinary actions; a task that cannot safely produce a candidate is
-parked or failed without granting remote/main authority. If the Decision Worker
+parked or failed without granting remote/main authority. Model/API failures are
+detected from the Pi `stopReason` (a provider error resolves the prompt normally
+rather than throwing); if the Decision Worker
 API/model call fails, the system records `decision_worker_failed`, applies the
-bounded retry/park policy and preserves the candidate evidence. Optional alert
+bounded retry/park policy and preserves the candidate evidence. An abort is never
+retried, and a `noop` reply on a completed turn or a permission request parks the
+candidate rather than being treated as a resolved decision, while a `noop` on a
+clean Worker exit proceeds to verification. Optional alert
 delivery remains independent from event-log persistence, but notification is not
 the control boundary.
 
+Permission requests are not all routed to the Decision Worker model. `autonomy.permissionAuthority`
+(`policy` | `hybrid`, default | `decision-worker`) chooses the authority: `policy` answers
+every request from the deterministic policy alone, `decision-worker` sends every
+request to the model, and the `hybrid` default answers a request from policy alone
+only when the policy already denies it or `isRoutinePermission` in `src/policy.ts`
+recognizes it as a routine in-cwd file edit or a local read-only/dev shell command
+it can fully account for; anything it does not recognize is not routine and still
+goes to the Decision Worker. The shell classifier is deliberately narrow: every
+pipeline segment must start with an allow-listed utility (`ls`, `grep`, `sed -n`,
+`git status/diff/log/add/commit`, `npm test|run`, `node ./script`, `tsc`, ...),
+inline scripts (`node -e`), programs named by path, `$(...)`/backticks, process
+substitution, `env`, `xargs`, `sort` and every other utility that can run a
+program from an option, git shapes that discard or relocate work
+(`checkout`/`restore`/`reset`, `stash drop`, `-C` outside the cwd, `-c`,
+`--git-dir`, `--ext-diff`/`--textconv`), file-writing modes of
+`sed`/`awk`/`find`/`tsc`, any argument that names a path outside the cwd (reads
+of `/etc` or `~/.ssh` included), and any redirection whose target is outside the
+cwd (after resolving `..`, `~` and symlinks) are never routine. Executing repository code (`npm run <script>`,
+`node ./x.js`) is routine by design: it is reviewed repository content and the
+Worker could run it through the allowed file tools regardless. A policy denial always wins regardless of authority; the
+classifier only ever narrows what reaches the model, never what the policy refuses.
+An explicit human takeover suspends this local fast path entirely, so every
+permission request stays pending for the human once takeover is active, even one
+the policy would otherwise have answered alone.
+
+The persistent Decision Worker session is kept small by construction, not by an
+after-the-fact trim: the task/spec/cwd live once in the startup instructions, and
+every subsequent prompt sends only a bounded event summary (`summarizeEvent` in
+`src/decision-worker.ts`, capping a `turn_completed` result or `permission_request`
+input that can otherwise run to tens of kilobytes) plus the small pieces of state
+that actually change turn to turn. On top of that, the session proactively calls
+`AgentSession.compact()` between decisions once its estimated context passes
+`PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS` (default 60,000 tokens; `0` disables
+it), asking Pi to preserve the task specification, the permission/boundary rules,
+the current state and the last three decisions with their reasons. A compaction
+failure never fails the decision that already succeeded. Because compaction can
+drop context a decision might otherwise assume, the next primary prompt after a
+successful compaction re-sends the startup instructions exactly once (tracked by an
+internal "instructions stale" flag), then reverts to the compact event summary.
+
+Every Worker `result` record and every Decision Worker/Reviewer model call is
+accounted for, not just logged: a `result` becomes a `worker_usage` event carrying
+its incremental and cumulative cost and token counts, and a Pi-side call becomes a
+`pi_usage` event; both accumulate into `session.usage` (`SupervisorTokenUsage`),
+which `/supervise status`, progress notifications (`SupervisorProgress.costUsd`/
+`.piTokens`) and candidate notifications (`CandidateNotice.usage`) all read from.
+`autonomy.maxWorkerCostUsd` (`PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD`) is
+enforced twice: it is passed to Claude as `--max-budget-usd` so the Worker can stop
+itself first (surfaced as the `result` subtype `error_max_budget_usd`), and the
+Supervisor independently parks the candidate once its own cumulative
+`workerCostUsd` crosses the same limit, so a Worker that does not honor its own cap
+is still bounded.
+
 ## Acceptance, review and repair loop
 
 A task may provide a structured `TaskSpec` with `goal`, `scope`, `constraints`,
@@ -319,7 +499,11 @@ conversation or control channel. It can inspect only `read`, `grep`, `find` and
 `pass`, `revise` or `human` with bounded structured findings. Invalid Reviewer
 output, incomplete evidence or a Reviewer API failure must prevent a candidate
 from crossing the remote/main boundary; the local system may retry, repair or
-park it without requiring a human to be online.
+park it without requiring a human to be online. The Reviewer retries a provider
+error once within a total review budget
+(`PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS`, default 10 minutes). Truncated
+(oversize) evidence requests a bounded repair before parking, while incomplete
+evidence still parks.
 
 A `revise` result produces an audited repair round and sends a bounded corrective
 instruction to a still-live `repairableSession` Worker. Checks and review then run again.

package/docs/testing.md

@@ -146,11 +146,12 @@ Pi Decision Worker. Setting `PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux` selects the
 Supervisor-owned live bridge, which carries the same structured records through
 private framing on the PTY rather than an independent JSONL sidecar. Task autonomy
 defaults to unattended local work, a required
-local commit on a non-protected task branch and two bounded Decision Worker retries. Configure
+local commit on the task branch (any branch, anchored to the baseline commit) and two bounded Decision Worker retries. Configure
 `PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT=0` or task `autonomy.requireLocalCommit`
 only to disable the local-commit deliverability check; automatic mode still requires a Git
-baseline and non-protected worktree. Adopted tmux sessions remain manual-only; the automatic bridge requires
-Supervisor ownership. `process-pipe` remains the manual compatibility mode. Candidate/failure notification is optional and outbound-only through
+baseline (any branch, including `main`; the candidate must descend from it). The tmux bridge
+requires Supervisor ownership; the interactive tmux mode (the default `TMUX_MODE`) also adopts an
+existing session through the user-level hook relay. `process-pipe` remains the manual compatibility mode. Candidate/failure notification is optional and outbound-only through
 `PI_CLAUDE_SUPERVISOR_HUMAN_WEBHOOK_URL`; it is not a synchronous approval
 callback. Approval callbacks are deliberately not accepted without a separately
 authenticated endpoint.
@@ -168,7 +169,7 @@ there is no injected sandbox or automatic tool allowlist. The only automatic CLI
 safety addition is a `default` permission mode when none was supplied; Bash
 preauthorization through `--allowedTools` or loaded settings is rejected so Bash
 requests remain visible to Supervisor policy. Automatic startup also requires
-a full existing Git baseline, non-bare non-protected worktree and the bare
+a full existing Git baseline, a non-bare worktree on any branch and the bare
 `claude`/`claude.exe` command name. It resolves and pins an
 operator-owned, non-writable executable path (or the path configured by
 `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE`), rejects explicit/custom executable paths, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {

package/src/acceptance.ts

@@ -85,16 +85,22 @@ function normalizeRepairRounds(value: unknown): number {
 }
 
 function normalizeAutonomy(value: unknown): TaskSpec["autonomy"] {
-  if (value === undefined) return { unattended: true, requireLocalCommit: true, maxDecisionRetries: 2 };
+  if (value === undefined) return { unattended: true, requireLocalCommit: true, maxDecisionRetries: 2, permissionAuthority: "hybrid" };
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("task spec autonomy must be an object");
   const source = value as Record<string, unknown>;
   if (source.unattended !== undefined && typeof source.unattended !== "boolean") throw new Error("task spec autonomy.unattended must be boolean");
   if (source.requireLocalCommit !== undefined && typeof source.requireLocalCommit !== "boolean") throw new Error("task spec autonomy.requireLocalCommit must be boolean");
   const retries = source.maxDecisionRetries ?? 2;
   if (typeof retries !== "number" || !Number.isSafeInteger(retries) || retries < 0 || retries > 10) throw new Error("task spec autonomy.maxDecisionRetries must be between 0 and 10");
+  const authority = source.permissionAuthority ?? "hybrid";
+  if (authority !== "policy" && authority !== "hybrid" && authority !== "decision-worker") throw new Error("task spec autonomy.permissionAuthority must be policy, hybrid or decision-worker");
+  const maxWorkerCostUsd = source.maxWorkerCostUsd;
+  if (maxWorkerCostUsd !== undefined && (typeof maxWorkerCostUsd !== "number" || !Number.isFinite(maxWorkerCostUsd) || maxWorkerCostUsd <= 0)) throw new Error("task spec autonomy.maxWorkerCostUsd must be a positive number");
   return {
     unattended: source.unattended !== false,
     requireLocalCommit: source.requireLocalCommit !== false,
     maxDecisionRetries: retries,
+    permissionAuthority: authority,
+    ...(maxWorkerCostUsd !== undefined ? { maxWorkerCostUsd } : {}),
   };
 }

package/src/config.ts

@@ -2,14 +2,19 @@ import { chmodSync, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { redactSensitive } from "./redaction.ts";
+import type { PermissionAuthority } from "./types.ts";
 
 const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_MODE",
   "PI_CLAUDE_SUPERVISOR_AUTOMATION",
   "PI_CLAUDE_SUPERVISOR_TRANSPORT",
+  "PI_CLAUDE_SUPERVISOR_TMUX_MODE",
+  "PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS",
+  "PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION",
   "PI_CLAUDE_SUPERVISOR_CGROUP_MODE",
   "PI_CLAUDE_SUPERVISOR_TMUX_SOCKET",
   "PI_CLAUDE_SUPERVISOR_WORKER",
+  "PI_CLAUDE_SUPERVISOR_NODE",
   "PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE",
   "PI_CLAUDE_SUPERVISOR_STATE_DIR",
   "PI_CLAUDE_SUPERVISOR_CWD_LEASE_DIR",
@@ -20,12 +25,28 @@ const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_UNATTENDED",
   "PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT",
   "PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES",
+  "PI_CLAUDE_SUPERVISOR_PERMISSION_AUTHORITY",
+  "PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD",
+  "PI_CLAUDE_SUPERVISOR_WORKER_MODEL",
+  "PI_CLAUDE_SUPERVISOR_WORKER_AUTOCOMPACT_TOKENS",
+  "PI_CLAUDE_SUPERVISOR_WORKER_MCP_CONFIG",
+  "PI_CLAUDE_SUPERVISOR_DECISION_MODEL",
+  "PI_CLAUDE_SUPERVISOR_REVIEWER_MODEL",
+  "PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS",
+  "PI_CLAUDE_SUPERVISOR_PROGRESS_HEARTBEAT_MS",
+  "PI_CLAUDE_SUPERVISOR_DECISION_SESSION_RETENTION_DAYS",
+  "PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_BYTES",
+  "PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES",
+  "PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS",
+  "PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES",
 ]);
 
 export interface AutonomyDefaults {
   unattended: boolean;
   requireLocalCommit: boolean;
   maxDecisionRetries: number;
+  permissionAuthority: PermissionAuthority;
+  maxWorkerCostUsd?: number;
 }
 
 export function autonomyDefaults(env: NodeJS.ProcessEnv = process.env): AutonomyDefaults {
@@ -33,9 +54,61 @@ export function autonomyDefaults(env: NodeJS.ProcessEnv = process.env): Autonomy
     unattended: readBoolean(env.PI_CLAUDE_SUPERVISOR_UNATTENDED, true),
     requireLocalCommit: readBoolean(env.PI_CLAUDE_SUPERVISOR_REQUIRE_LOCAL_COMMIT, true),
     maxDecisionRetries: readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_MAX_DECISION_RETRIES, 2, 0, 10),
+    permissionAuthority: readPermissionAuthority(env.PI_CLAUDE_SUPERVISOR_PERMISSION_AUTHORITY),
+    ...(readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) !== undefined ? { maxWorkerCostUsd: readPositiveNumber(env.PI_CLAUDE_SUPERVISOR_WORKER_MAX_BUDGET_USD) } : {}),
   };
 }
 
+export function reviewTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS, 600_000, 30_000, 3_600_000);
+}
+
+export function eventLogMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES, 64 * 1024 * 1024, 1024 * 1024, 1024 * 1024 * 1024);
+}
+
+export function workerModel(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return readTrimmedString(env.PI_CLAUDE_SUPERVISOR_WORKER_MODEL);
+}
+
+/** The 200_000 default applies only in automatic mode; "0" is an explicit opt-out that omits --autocompact. */
+export function workerAutocompactTokens(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_WORKER_AUTOCOMPACT_TOKENS, 200_000, 100_000, 1_000_000);
+}
+
+export function workerMcpConfigPath(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return readTrimmedString(env.PI_CLAUDE_SUPERVISOR_WORKER_MCP_CONFIG);
+}
+
+export function decisionModel(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return readTrimmedString(env.PI_CLAUDE_SUPERVISOR_DECISION_MODEL);
+}
+
+export function reviewerModel(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  return readTrimmedString(env.PI_CLAUDE_SUPERVISOR_REVIEWER_MODEL);
+}
+
+/** "0" is an explicit opt-out that disables Decision Worker session compaction. */
+export function decisionCompactionTokens(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedIntegerWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DECISION_COMPACT_TOKENS, 60_000, 10_000, 500_000);
+}
+
+export function progressHeartbeatMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_PROGRESS_HEARTBEAT_MS, 60_000, 5_000, 3_600_000);
+}
+
+export function decisionSessionRetentionDays(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_DECISION_SESSION_RETENTION_DAYS, 30, 0, 3650);
+}
+
+export function evidenceMaxBytes(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_BYTES, 1024 * 1024, 64 * 1024, 64 * 1024 * 1024);
+}
+
+export function evidenceMaxUntrackedFiles(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES, 512, 16, 10_000);
+}
+
 export function loadSupervisorEnvironment(): string | undefined {
   const path = process.env.PI_CLAUDE_SUPERVISOR_ENV_FILE ?? join(homedir(), ".config", "pi-claude-supervisor", "env");
   if (!existsSync(path)) return undefined;
@@ -68,3 +141,40 @@ function readBoundedInteger(value: string | undefined, fallback: number, minimum
   const parsed = Number(value);
   return Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum ? parsed : fallback;
 }
+
+/** Like readBoundedInteger, but the literal "0" is always honored as an opt-out below the normal minimum. */
+function readBoundedIntegerWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+  if (value !== undefined && value.trim() === "0") return 0;
+  return readBoundedInteger(value, fallback, minimum, maximum);
+}
+
+function readTrimmedString(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readPermissionAuthority(value: string | undefined): PermissionAuthority {
+  const normalized = value?.trim().toLowerCase();
+  return normalized === "policy" || normalized === "decision-worker" ? normalized : "hybrid";
+}
+
+function readPositiveNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value.trim() === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+/** How automatic tmux supervision drives Claude: the real TUI through hooks (default) or the stream-json bridge. */
+export function tmuxMode(env: NodeJS.ProcessEnv = process.env): "interactive" | "bridge" {
+  return env.PI_CLAUDE_SUPERVISOR_TMUX_MODE?.trim().toLowerCase() === "bridge" ? "bridge" : "interactive";
+}
+
+/** Exit the interactive Worker and its tmux session once a task completes; default keeps it open for the operator. */
+export function closeWorkerOnCompletion(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readBoolean(env.PI_CLAUDE_SUPERVISOR_CLOSE_WORKER_ON_COMPLETION, false);
+}
+
+/** Install the user-level Claude Code hook entries automatically when the interactive tmux mode is configured. */
+export function autoInstallHooks(env: NodeJS.ProcessEnv = process.env): boolean {
+  return readBoolean(env.PI_CLAUDE_SUPERVISOR_AUTO_INSTALL_HOOKS, true);
+}