portable-agent-layer 0.114.0 → 0.115.0-canary.1

package/README.md

@@ -95,6 +95,8 @@ pal cli status        # check your setup
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli patterns` | How you work across projects, read from the event log |
 | `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. The active node rides along in every session and prompt, and your own commits attach to it at turn end |
+| `pal cli timebox [start\|status\|end]` | Stop work at a deadline: `start --for 15m` or `--until 18:00`. After the deadline every working tool call is refused except `pal cli` and edits to the report, so the agent stops and reports what it has |
+| `pal cli unattended [start\|log\|status\|done\|end]` | Work without you until a deadline: `start --until 05:30 --task … --fallback …`. Questions and subagents are refused, the agent cannot stop while approved tasks are left, and the rules, tasks and log come back after a compaction |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |

package/assets/skills/timebox/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: timebox
+license: MIT
+description: "Works on a task under a user-given time limit and stops at the deadline with a report of what was found or done so far. Use when the request names a duration or a clock time for the work (\"stop in 15 minutes\", \"spend at most an hour\", \"stop at 6 PM\", \"timebox this\")."
+argument-hint: <duration or HH:MM> <task>
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "timebox"
+    - "time box"
+    - "stop in"
+    - "spend at most"
+    - "stop at"
+    - "time limit"
+---
+
+# Timebox
+
+Work on $ARGUMENTS until the deadline the user set, then stop and report, wherever the work stands. PAL enforces the deadline for the current project or folder through its hooks; this skill is how to work inside it.
+
+## Workflow
+
+1. **Parse the limit** from the request. A duration ("15 minutes", "an hour and a half") becomes `--for 15m` or `--for 1h30m`; a clock time ("by 6 PM", "at 18:00") becomes `--until 18:00`, the next such local time. If no limit is clear, this is not the skill — do the task normally.
+2. **Start the box** before any other work:
+   ```bash
+   pal cli timebox start --for <15m|2h|1h30m> --task "<short task name>"
+   pal cli timebox start --until <HH:MM> --task "<short task name>"
+   ```
+   Add `--report <path>` only when the user asked for the result in a file. The command fails if a box is already running for this folder; then ask whether to replace it (`pal cli timebox end`, then start) or work inside the one that exists.
+3. **Work in small steps.** Run `pal cli timebox status` between steps; it prints the end time and the minutes left. Each user prompt during the box also carries "Time box until HH:MM, N min left". Plan the last step so it finishes before the deadline. Start nothing that cannot finish in the time left — a long build, a large download, a deep research pass — because a hook cannot interrupt a running command.
+4. **Stop at the deadline.** After it, PAL's PreToolUse hook refuses shell, edit and write, web search and fetch, subagent and question calls with a message starting "Time box ended at HH:MM … Stop working now". Only `pal cli …` commands (optionally piped into `head` or `tail`) and writes to the `--report` path still run. Read-only tools may still answer, but do not keep working with them. Do not work around a refusal; move straight to the report.
+5. **Report** in the final message, or in the report file when `--report` was given. Keep it short.
+6. **End the box**: `pal cli timebox end`. A user prompt sent after the deadline clears it automatically; run `end` anyway so the state is explicit.
+
+If the task finishes before the deadline, report then and run `pal cli timebox end` right away.
+
+## Output format
+
+The final message (or report file) has five parts, each one line or a short list:
+
+- **Done / found** — the concrete results so far.
+- **Not covered** — what the box cut off, or what was never reached.
+- **Next** — the first steps to take if the work resumes, with the box ended.
+- **Confidence** — a one-line judgment and its weakest point.
+- **Box** — `started HH:MM, ended HH:MM` and whether the task finished early or was cut at the deadline.
+
+## When to use
+
+- The user gives a duration or clock time for the work: "research this but stop in 15 minutes", "spend at most an hour on the refactor", "stop at 6 PM", "timebox this to 30 minutes".
+- The user says "timebox" or "time box" for any task.
+
+## Do NOT use
+
+- No time limit was given. Do the task normally; a time box without a user-stated limit is an invention.
+- The user is leaving and nobody will answer questions — that is the `unattended` skill, which sets its own deadline and handles the absence.
+- The user wants a reminder or an alarm with no work attached to it.

package/assets/skills/unattended/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: unattended
+license: MIT
+description: "Runs an approved list of tasks while the user is away — asleep, in a meeting, out for the afternoon — with nobody there to answer, then leaves a report for their return. Proposes finishable tasks and fallbacks, gets approval and a return time, starts the run with pal cli unattended, logs every decision, and finalises the report at the deadline. Use when the user says they are leaving and wants work to continue unattended, overnight, while they sleep, or until they are back."
+argument-hint: "[return time] [tasks or goal]"
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "unattended"
+    - "while I'm away"
+    - "work on this while I sleep"
+    - "overnight tasks"
+    - "night task"
+    - "until I'm back"
+    - "I'm going to bed"
+---
+
+# Unattended run
+
+Work through approved tasks with nobody present to answer, then hand back a report. Three phases: propose, run, report. Do not start the run until the user has approved the plan.
+
+## Phase A — Propose (before the user leaves)
+
+1. Resolve the current project from the working folder (`pal cli project resume <slug>` when the user names one). Read its notes, open progress nodes and recent sessions: tasks come only from this project.
+2. Draft candidate tasks. Keep a task only if it can be finished alone, with no decision that only the user can make. For each kept task write: what it produces, how it will be checked (tests or a build when the project has them, a visual comparison, sources cited, a reread against the brief), rough time, and resource cost (memory, network, paid APIs). Flag dropped tasks with the decision they need.
+3. Propose 1-2 fallback tasks the run takes when the approved list is finished early: deterministic, low-risk work such as fixing lint warnings, adding missing tests, or updating documentation.
+4. Ask, in one question with your agent's ask tool: the return time, where the report goes (a file path, a page the project serves, or an artifact), and extra rules. Suggest the rule categories: no paid or keyed APIs, no downloads, memory caps on heavy commands, files or services that are off-limits.
+5. Repeat back in short form: tasks in order, fallbacks, return time, report location, extra rules on top of the defaults listed below. STOP and wait for explicit approval. Edits to the list return to step 5.
+
+Default rules every run carries (`pal cli unattended start` stores them; `--rule` adds more):
+- Never ask. Decide, log the decision and its reason, list the question in the report.
+- Check notes and earlier sessions before listing a question.
+- Approved tasks, then fallbacks, nothing else. Other ideas become suggestions in the report.
+- Never delete, push, deploy or publish anything except the report.
+- One heavy process at a time. No subagents, no workflows.
+- Verify each step as if the user were present.
+- Only in a git repository: work on a branch, one logical step per commit, stage only your own changes, never push.
+
+## Phase B — Run (after approval)
+
+1. Set the deadline about 30 minutes before the return time so the report is final when the user is back. Start the run:
+   ```bash
+   pal cli unattended start --until <HH:MM> --task "<task 1>" --task "<task 2>" --fallback "<fallback>" --rule "<extra rule>" --report <path|url>
+   ```
+   Then `pal cli progress open "<run title>"` for the run's progress node.
+2. In a git repository, create the work branch. Take tasks in the approved order, one at a time.
+3. For each task: do it; verify it the way Phase A agreed (when the project has tests, run them twice and break-check every new test; when it has a build, run it); in a git repository, commit. Then `pal cli unattended log "<result> and how it was verified"` and `pal cli progress stopped "<next step>"`. Commits attach to the progress node on their own; do not attach them by hand.
+4. Log every non-obvious decision with its reason at the moment of deciding: `pal cli unattended log "<decision>: <reason>"`.
+5. Run `pal cli unattended status` between steps. Compare the minutes left with the estimated length of the next step; never start a step that cannot finish before the deadline, because a hook cannot interrupt a running command. Pick a shorter step or move to the report instead.
+6. Write the report to the agreed location as soon as the first task lands, with "(draft)" in its title. Update it after every task so a crash leaves a usable report behind.
+7. When the approved tasks are finished, take the fallbacks in order. The Stop hook refuses to end the turn before `pal cli unattended done`, so finishing early means moving on, not idling.
+8. Treat every refused tool call as a rule: questions to the user and subagent or workflow calls are refused during the run, and after the deadline every working tool is refused except `pal cli` and writes to the report path. The refusal depends on the agent's tool names being known to PAL, so never ask or delegate even when no hook stops you. Never work around a refusal; log it and continue with the next permitted step.
+9. After a context compaction, run `pal cli unattended status` and resume from the last logged step. Agents with a compaction hook also get the run's rules, tasks and log re-injected; re-read them first.
+
+## Phase C — Report (at the deadline)
+
+1. Finalise the report, removing "(draft)". Sections, in order:
+   - **Done** — each task, how it was verified, and its commits, test counts and build result where the project has them.
+   - **Comparisons** — for visual work, reference next to result, with an honest "falls short" note where it does.
+   - **Failed, skipped, reverted** — what, why, and what was reverted.
+   - **Questions for the user** — each answerable in one line; only questions the notes could not answer.
+   - **Unfinished work** — files left mid-change and what state they are in; in a git repository, the branch and its uncommitted files.
+   Label every inference of your own as such ("my reading:", "unverified:").
+2. If the report is served somewhere, open the served copy (the `playwright` skill, or fetch the URL) and confirm it matches the local file.
+3. `pal cli progress done`, then `pal cli unattended done`.
+4. When the user returns, reply first with a summary under 100 words: what landed, the report location, and the open questions. Then run `pal cli unattended end`.
+
+## Output format
+
+- Phase A ends with the short-form plan (tasks, fallbacks, return time, report location, extra rules) followed by one approval question. Nothing runs before the answer.
+- Phase B produces the task results (commits on the branch in a git repository), `pal cli unattended log` entries, progress-tree updates, and the draft report at the agreed location.
+- Phase C produces the final report with the five sections above and, on the user's return, a summary under 100 words naming the report location and the open questions.
+
+## When to use
+
+- The user is leaving (sleep, meeting, travel, the rest of the day) and wants work to continue with nobody there to answer.
+- The user asks for an overnight or night task, or wants the work to keep going while they are away or until they are back.
+- A list of self-contained tasks exists, or can be drawn from the current project, that needs no user decision mid-way.
+
+## Do NOT use
+
+- The user stays at the keyboard and only wants a time limit on the work: that is the `timebox` skill.
+- A single long-running command that should run in the background and be checked later.
+- Tasks that hinge on a decision only the user can make: propose them, flag the decision, and leave them out of the run.

package/assets/templates/settings.claude.json

@@ -112,7 +112,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|Write|Edit",
+        "matcher": "Bash|Write|Edit|NotebookEdit|WebSearch|WebFetch|AskUserQuestion|Agent|Task|Workflow",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.114.0",
+  "version": "0.115.0-canary.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/run-mode.ts

@@ -0,0 +1,214 @@
+/**
+ * pal cli timebox / pal cli unattended — start, inspect and end a run with a
+ * deadline for the current project or folder. The hooks enforce it.
+ */
+
+import { scopeOf } from "../hooks/lib/progress-tree";
+import {
+  clearRun,
+  deadlineFrom,
+  describeRun,
+  newRun,
+  type Run,
+  type RunKind,
+  readRun,
+  unattendedRules,
+  untilLabel,
+  writeRun,
+} from "../hooks/lib/run-mode";
+import { isInGitRepo } from "../hooks/lib/session-events";
+import { group, leaf, UsageError } from "../tools/lib/command";
+
+const FOR = {
+  type: "string",
+  value: "<duration>",
+  description: "How long, e.g. 15m, 2h or 1h30m",
+} as const;
+const UNTIL = {
+  type: "string",
+  value: "<HH:MM>",
+  description: "Local time it ends (the next one), or an ISO time",
+} as const;
+const REPORT = {
+  type: "string",
+  value: "<path|url>",
+  description:
+    "Where the report goes; edits to a local path still run after the deadline",
+} as const;
+
+function currentScope(): string {
+  return scopeOf(process.cwd());
+}
+
+function deadline(values: { for?: string; until?: string }): Date {
+  try {
+    return deadlineFrom(values);
+  } catch (err) {
+    throw new UsageError((err as Error).message);
+  }
+}
+
+function runOf(kind: RunKind): Run | null {
+  const run = readRun(currentScope());
+  return run?.kind === kind ? run : null;
+}
+
+function noRun(kind: RunKind): number {
+  console.error(`No ${kind} run in ${currentScope()}.`);
+  return 1;
+}
+
+function refuseIfRunning(): void {
+  const run = readRun(currentScope());
+  if (run)
+    throw new UsageError(
+      `A ${run.kind} run until ${untilLabel(run)} is already on here; end it first`
+    );
+}
+
+function printStatus(kind: RunKind): number {
+  const run = runOf(kind);
+  if (!run) return noRun(kind);
+  console.log(describeRun(run));
+  return 0;
+}
+
+function endRun(kind: RunKind): number {
+  const run = runOf(kind);
+  if (!run) return noRun(kind);
+  clearRun(run.scope);
+  console.log(`Ended the ${kind} run that was due at ${untilLabel(run)}.`);
+  return 0;
+}
+
+function startTimebox(values: {
+  for?: string;
+  until?: string;
+  task?: string;
+  report?: string;
+}): number {
+  refuseIfRunning();
+  const run = newRun({
+    kind: "timebox",
+    scope: currentScope(),
+    until: deadline(values),
+    task: values.task,
+    report: values.report,
+  });
+  writeRun(run);
+  console.log(
+    `Time box set: ends at ${untilLabel(run)}. After that only \`pal cli\` and report edits run.`
+  );
+  return 0;
+}
+
+function startUnattended(values: {
+  until?: string;
+  for?: string;
+  task?: string[];
+  fallback?: string[];
+  rule?: string[];
+  report?: string;
+}): number {
+  refuseIfRunning();
+  if (!values.task?.length) throw new UsageError("give each approved task with --task");
+  const run = newRun({
+    kind: "unattended",
+    scope: currentScope(),
+    until: deadline(values),
+    report: values.report,
+    tasks: values.task,
+    fallbacks: values.fallback ?? [],
+    rules: unattendedRules(isInGitRepo(process.cwd()), values.rule),
+  });
+  writeRun(run);
+  console.log(describeRun(run));
+  return 0;
+}
+
+function logEntry(text: string): number {
+  const run = runOf("unattended");
+  if (!run) return noRun("unattended");
+  writeRun({ ...run, log: [...run.log, { at: new Date().toISOString(), entry: text }] });
+  console.log(`Logged (${run.log.length + 1} entries).`);
+  return 0;
+}
+
+function markDone(): number {
+  const run = runOf("unattended");
+  if (!run) return noRun("unattended");
+  writeRun({ ...run, done: true });
+  console.log("Marked done: the agent may stop. The run ends when the user is back.");
+  return 0;
+}
+
+export const timeboxCommand = group({
+  summary: "Stop work at a deadline and report what was found",
+  commands: {
+    start: leaf({
+      summary: "Start a time box for the current project or folder",
+      options: {
+        for: FOR,
+        until: UNTIL,
+        task: { type: "string", value: "<text>", description: "What is being done" },
+        report: REPORT,
+      },
+      run: ({ values }) => startTimebox(values),
+    }),
+    status: leaf({
+      summary: "Show the time box and the time left",
+      run: () => printStatus("timebox"),
+    }),
+    end: leaf({ summary: "End the time box", run: () => endRun("timebox") }),
+  },
+});
+
+export const unattendedCommand = group({
+  summary: "Work without the user until a deadline: no questions, approved tasks only",
+  commands: {
+    start: leaf({
+      summary: "Start an unattended run with the approved tasks",
+      options: {
+        until: UNTIL,
+        for: FOR,
+        task: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "An approved task, in order (repeat)",
+        },
+        fallback: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "A pre-approved task for when the tasks run out (repeat)",
+        },
+        rule: {
+          type: "string",
+          multiple: true,
+          value: "<text>",
+          description: "A rule on top of the defaults (repeat)",
+        },
+        report: REPORT,
+      },
+      run: ({ values }) => startUnattended(values),
+    }),
+    log: leaf({
+      summary: "Append a timestamped entry to the run's log",
+      args: "<entry...>",
+      run: ({ positionals }) => logEntry(positionals.join(" ")),
+    }),
+    status: leaf({
+      summary: "Show the rules, tasks, log and time left",
+      run: () => printStatus("unattended"),
+    }),
+    done: leaf({
+      summary: "Every task and fallback is finished and the report is written",
+      run: markDone,
+    }),
+    end: leaf({
+      summary: "End the run (the user is back)",
+      run: () => endRun("unattended"),
+    }),
+  },
+});

package/src/cli/tree.ts

@@ -27,6 +27,7 @@ import { patternsCommand } from "./patterns";
 import { telosCommand, timezoneCommand } from "./personal-context";
 import { progressCommand } from "./progress";
 import { ruleCommand } from "./rule";
+import { timeboxCommand, unattendedCommand } from "./run-mode";
 import { serverCommand } from "./server";
 import { skillCommand } from "./skill";
 import { subagentCommand } from "./subagent";
@@ -187,6 +188,8 @@ export function cliTree(admin: AdminHandlers): Group {
       rule: ruleCommand,
       correction: correctionCommand,
       progress: progressCommand,
+      timebox: timeboxCommand,
+      unattended: unattendedCommand,
       server: serverCommand,
       skill: skillCommand,
       subagent: subagentCommand,

package/src/hooks/CompactRecover.ts

@@ -15,7 +15,9 @@ import {
   type SavedExchange,
 } from "./lib/compact-recall";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
+import { enterHookWorkspace } from "./lib/hook-turn";
 import { logDebug, logError } from "./lib/log";
+import { runModeRecall } from "./lib/run-mode-gate";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -38,19 +40,26 @@ try {
     process.exit(0);
   }
 
+  enterHookWorkspace(input);
   const sessionId = input?.session_id;
+  const run = runModeRecall(process.cwd());
   const file = findSavedExchange(sessionId);
-  if (!file) {
-    logDebug("CompactRecover", "No saved exchange found — silent no-op");
+  if (!file && !run) {
+    logDebug("CompactRecover", "No saved exchange or run found — silent no-op");
     process.exit(0);
   }
 
-  const saved = JSON.parse(await readFile(file, "utf-8")) as SavedExchange;
-  const out = buildRecall(saved);
+  const exchange = file
+    ? buildRecall(JSON.parse(await readFile(file, "utf-8")) as SavedExchange)
+    : "";
+  const out = [run, exchange].filter(Boolean).join("\n\n");
   process.stdout.write(isCursor() ? JSON.stringify({ additional_context: out }) : out);
-  logDebug("CompactRecover", `Re-injected ${out.length} chars from ${file}`);
+  logDebug(
+    "CompactRecover",
+    `Re-injected ${out.length} chars from ${file ?? "run mode"}`
+  );
 
-  if (isConsumable(file, sessionId)) await unlink(file);
+  if (file && isConsumable(file, sessionId)) await unlink(file);
 } catch (err) {
   logError("CompactRecover", err);
 }

package/src/hooks/StopOrchestrator.ts

@@ -6,18 +6,18 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
-import { watchReplyRules } from "./lib/adaptation-steering";
 import { stopBlockResponse } from "./lib/agent";
 import {
   type AntigravityStopFields,
   isSideStop,
   withTranscriptReply,
 } from "./lib/antigravity-transcript";
-import { watchClaims } from "./lib/claim-log";
 import { duplicatesCursorHooks } from "./lib/cursor-shadow";
 import { enterHookWorkspace } from "./lib/hook-turn";
 import { logError } from "./lib/log";
 import { stopProgressTree } from "./lib/progress-tree-stop";
+import { replySendBack } from "./lib/reply-checks";
+import { unattendedStopReason } from "./lib/run-mode-gate";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 import { type StopTurnPayload, stopTurn } from "./lib/stop";
@@ -30,6 +30,14 @@ if (isSideStop(received)) process.exit(0);
 const payload = withTranscriptReply(received);
 enterHookWorkspace(payload);
 
+// First: it reads only git and PRs, so every stop attempt attaches new commits, even one a block below refuses.
+try {
+  stopProgressTree(payload);
+} catch (err) {
+  logError("StopOrchestrator:progress-tree", err);
+}
+
+// Fix requests come before the keep-working block; the README first, as it blocks every attempt until fixed.
 try {
   // A block carrying no reason stops the turn without telling the model why, so it
   // is worth less than not blocking at all — require the reason to raise one.
@@ -42,27 +50,25 @@ try {
   logError("StopOrchestrator:readme-sync", err);
 }
 
+// Reply checks next, claims before style rules: one send-back per reply, so the corrected reply goes through.
 try {
-  const sendBack = watchClaims(payload);
+  const sendBack = replySendBack(payload);
   if (sendBack) {
     process.stdout.write(stopBlockResponse(sendBack));
     process.exit(0);
   }
 } catch (err) {
-  logError("StopOrchestrator:claim-check", err);
+  logError("StopOrchestrator:reply-checks", err);
 }
+// After the reply checks: a reply that needs fixing goes back for the fix, not for the next task.
 try {
-  const sendBack = watchReplyRules(payload);
-  if (sendBack) {
-    process.stdout.write(stopBlockResponse(sendBack));
+  const keepGoing = unattendedStopReason(process.cwd());
+  if (keepGoing) {
+    process.stdout.write(stopBlockResponse(keepGoing));
     process.exit(0);
   }
 } catch (err) {
-  logError("StopOrchestrator:adaptation-rules", err);
-}
-try {
-  stopProgressTree(payload);
-} catch (err) {
-  logError("StopOrchestrator:progress-tree", err);
+  logError("StopOrchestrator:unattended", err);
 }
+// Last: it writes to the terminal and starts inference, which only a stop that really ends may do.
 await stopTurn(payload);

package/src/hooks/handlers/inject-retrieval.ts

@@ -16,6 +16,7 @@ import { parkPromptContext } from "../lib/parked-context";
 import { progressTreePromptLine } from "../lib/progress-tree-context";
 import { isSystemText } from "../lib/prompt-text";
 import { getRepoStateReminder } from "../lib/repo-state";
+import { runModePromptLine } from "../lib/run-mode-gate";
 import { isEnabled } from "../lib/settings";
 import { getSkillReminder } from "../lib/skill-match";
 import { getSteeringReminder } from "../lib/steering";
@@ -62,6 +63,7 @@ export async function getPromptContext(
   const userText = isSystemText(prompt) ? "" : prompt;
   const parts = [
     getWallClockReminder(),
+    withinBudget(() => runModePromptLine(process.cwd()), BUDGET_MS),
     userText && withinBudget(() => promptRulesReminder(userText, sessionId), BUDGET_MS),
     withinBudget(() => getRepoStateReminder(), BUDGET_MS),
     withinBudget(() => progressTreePromptLine(userText, undefined, sessionId), BUDGET_MS),

package/src/hooks/lib/adaptation-steering.ts

@@ -11,10 +11,10 @@ import {
   type RuleTrigger,
   readRules,
 } from "./adaptation-rules";
-import { alreadySentBack } from "./claim-log";
 import { hookFinalReply, hookSessionId } from "./hook-turn";
 import { replyEnd } from "./interaction-samples";
 import { ruleEventsPath } from "./rule-effect";
+import { alreadySentBack } from "./send-back-guard";
 import { isEnabled } from "./settings";
 import type { StopTurnPayload } from "./stop";
 

package/src/hooks/lib/claim-log.ts

@@ -18,6 +18,7 @@ import {
 } from "./claim-check";
 import { hookFinalReply, hookSessionId } from "./hook-turn";
 import { ensureDir, paths } from "./paths";
+import { alreadySentBack } from "./send-back-guard";
 import { isEnabled, isOptedIn } from "./settings";
 import type { StopTurnPayload } from "./stop";
 import { readTranscriptTail } from "./transcript";
@@ -81,14 +82,6 @@ function record({ check, commands, session, blocked }: Watched, now: Date) {
   appendFileSync(monthFile(now), `${JSON.stringify(line)}\n`);
 }
 
-export function alreadySentBack(payload: StopTurnPayload): boolean {
-  return (
-    payload.stop_hook_active === true ||
-    (payload.loop_count ?? 0) > 0 ||
-    (payload.executionNum ?? 0) > 0
-  );
-}
-
 function sendsBack(payload: StopTurnPayload, check: ClaimCheck): boolean {
   return (
     check.verdict === "unbacked" &&

package/src/hooks/lib/reply-checks.ts

@@ -0,0 +1,24 @@
+import { watchReplyRules } from "./adaptation-steering";
+import { watchClaims } from "./claim-log";
+import { logError } from "./log";
+import { rememberSendBack } from "./send-back-guard";
+import type { StopTurnPayload } from "./stop";
+
+function skippedOnError(label: string, check: () => string | null): string | null {
+  try {
+    return check();
+  } catch (err) {
+    logError(`StopOrchestrator:${label}`, err);
+    return null;
+  }
+}
+
+/** The claim check, then the approved reply rules; the first reason to send the reply back wins. */
+export function replySendBack(payload: StopTurnPayload | null): string | null {
+  if (!payload) return null;
+  const reason =
+    skippedOnError("claim-check", () => watchClaims(payload)) ??
+    skippedOnError("adaptation-rules", () => watchReplyRules(payload));
+  rememberSendBack(payload, reason !== null);
+  return reason;
+}

package/src/hooks/lib/run-mode-gate.ts

@@ -0,0 +1,130 @@
+/**
+ * What the hooks do while a run is on: refuse tool calls past the deadline,
+ * refuse questions and delegation while unattended, keep an unattended agent
+ * from stopping with work left, and say where the run stands.
+ */
+
+import { resolve } from "node:path";
+import { scopeOf } from "./progress-tree";
+import {
+  clearRun,
+  describeRun,
+  isOver,
+  minutesLeft,
+  type Run,
+  readRun,
+  untilLabel,
+  writeRun,
+} from "./run-mode";
+import { runsOnlyPalCli } from "./security";
+
+export interface RunToolCall {
+  tool: string;
+  command?: string;
+  filePath?: string;
+}
+
+const ASK_TOOLS = new Set([
+  "askuserquestion",
+  "ask_user",
+  "askuser",
+  "ask_followup_question",
+  "request_user_input",
+]);
+const DELEGATE_TOOLS = new Set(["agent", "task", "workflow", "spawn_agent"]);
+export const MAX_STOP_BLOCKS = 20;
+
+function runIn(cwd: string, now: Date): Run | null {
+  return readRun(scopeOf(cwd), now);
+}
+
+function writesTheReport(run: Run, call: RunToolCall, cwd: string): boolean {
+  if (!run.report || !call.filePath) return false;
+  return resolve(cwd, call.filePath) === resolve(cwd, run.report);
+}
+
+function finishesTheRun(run: Run, call: RunToolCall, cwd: string): boolean {
+  return (
+    (call.command !== undefined && runsOnlyPalCli(call.command)) ||
+    writesTheReport(run, call, cwd)
+  );
+}
+
+function closeCommand(run: Run): string {
+  return run.kind === "unattended" ? "pal cli unattended done" : "pal cli timebox end";
+}
+
+function deadlineMessage(run: Run): string {
+  const task = run.task ? ` (${run.task})` : "";
+  const report = run.report ? ` Finish the report at ${run.report}.` : "";
+  return `Time box ended at ${untilLabel(run)}${task}. Stop working now: report what you found, what is unfinished and what comes next.${report} Only \`pal cli\` and edits to the report still run. Then run \`${closeCommand(run)}\`.`;
+}
+
+function unattendedRefusal(tool: string): string | null {
+  const name = tool.toLowerCase();
+  if (ASK_TOOLS.has(name))
+    return "Unattended run: nobody can answer. Decide, log it with `pal cli unattended log`, and put the question in the report.";
+  if (DELEGATE_TOOLS.has(name))
+    return "Unattended run: one process at a time, so no subagents or workflows. Do the step yourself.";
+  return null;
+}
+
+/** Why this call may not run under the scope's run, or null to let it through. */
+export function runModeRefusal(
+  call: RunToolCall,
+  cwd: string,
+  now: Date = new Date()
+): string | null {
+  const run = runIn(cwd, now);
+  if (!run) return null;
+  if (isOver(run, now))
+    return finishesTheRun(run, call, cwd) ? null : deadlineMessage(run);
+  return run.kind === "unattended" ? unattendedRefusal(call.tool) : null;
+}
+
+function reportPlace(run: Run): string {
+  return run.report ? ` at ${run.report}` : "";
+}
+
+function stopMessage(run: Run, now: Date): string {
+  if (isOver(run, now))
+    return `Unattended run ended at ${untilLabel(run)}. Finalise the report${reportPlace(run)}, then run \`pal cli unattended done\`.`;
+  return `Unattended until ${untilLabel(run)} (${minutesLeft(run, now)} min left): the user is not here to take a reply. Log the step you finished, then take the next approved task, or a fallback when none is left. Keep the draft report current. When every task and fallback is finished and the report is written, run \`pal cli unattended done\`.`;
+}
+
+/** The reason to keep an unattended agent going, or null to let it stop. Counts each block. */
+export function unattendedStopReason(cwd: string, now: Date = new Date()): string | null {
+  const run = runIn(cwd, now);
+  if (!run || run.kind !== "unattended" || run.done) return null;
+  if (run.stopBlocks >= MAX_STOP_BLOCKS) return null;
+  writeRun({ ...run, stopBlocks: run.stopBlocks + 1 });
+  return stopMessage(run, now);
+}
+
+function taskSuffix(run: Run): string {
+  return run.task ? `: ${run.task}` : "";
+}
+
+function promptLine(run: Run, now: Date): string {
+  if (run.kind === "timebox")
+    return `Time box until ${untilLabel(run)}, ${minutesLeft(run, now)} min left${taskSuffix(run)}. Stop and report at the deadline.`;
+  return `Unattended run until ${untilLabel(run)}, but the user just wrote: answer them. If they are back, run \`pal cli unattended end\`.`;
+}
+
+/** The per-prompt line for the scope's run. A user prompt after the deadline means the run is over, so it is cleared. */
+export function runModePromptLine(cwd: string, now: Date = new Date()): string | null {
+  const run = runIn(cwd, now);
+  if (!run) return null;
+  if (isOver(run, now)) {
+    clearRun(run.scope);
+    return null;
+  }
+  return `<system-reminder>${promptLine(run, now)}</system-reminder>`;
+}
+
+/** The run in full, for the context restored after a compaction. */
+export function runModeRecall(cwd: string, now: Date = new Date()): string | null {
+  const run = runIn(cwd, now);
+  if (!run) return null;
+  return `<system-reminder>\n## Active run — re-read before doing anything else\n${describeRun(run, now)}\n</system-reminder>`;
+}

package/src/hooks/lib/run-mode.ts

@@ -0,0 +1,202 @@
+/**
+ * A run with a deadline, kept per scope (a registered project, or the folder).
+ * A timebox ends work at the deadline; an unattended run also means nobody is
+ * there to answer until then. The hooks read this file; `pal cli timebox` and
+ * `pal cli unattended` write it.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { ensureDir, paths } from "./paths";
+import { localHourMinute, localMinuteOfDay } from "./wall-clock";
+
+export type RunKind = "timebox" | "unattended";
+
+interface RunLogEntry {
+  at: string;
+  entry: string;
+}
+
+export interface Run {
+  kind: RunKind;
+  scope: string;
+  startedAt: string;
+  until: string;
+  task: string | null;
+  report: string | null;
+  tasks: string[];
+  fallbacks: string[];
+  rules: string[];
+  log: RunLogEntry[];
+  done: boolean;
+  stopBlocks: number;
+}
+
+const MINUTE_MS = 60_000;
+const DAY_MINUTES = 1440;
+const FORGOTTEN_AFTER_MS = 12 * 60 * MINUTE_MS;
+
+export const DEFAULT_UNATTENDED_RULES = [
+  "Nobody can answer until the deadline: never ask. Decide, log the decision and why with `pal cli unattended log`, and list open questions in the report.",
+  "Before listing a question, search the project's notes and earlier sessions for an answer.",
+  "Do only the approved tasks, then the fallbacks. Anything else goes in the report as a suggestion.",
+  "Never delete, push, deploy or publish anything other than the report.",
+  "One heavy process at a time. No subagents or workflows.",
+  "Verify each step as you would with the user present, and log it when it lands.",
+];
+
+export const GIT_RULE =
+  "Work on a branch, one logical step per commit, staging only your own changes. Never push.";
+
+/** The default rules, plus the commit rule when the work happens in a git repository. */
+export function unattendedRules(inGitRepo: boolean, extra: string[] = []): string[] {
+  return [...DEFAULT_UNATTENDED_RULES, ...(inGitRepo ? [GIT_RULE] : []), ...extra];
+}
+
+function runDir(): string {
+  return ensureDir(resolve(paths.state(), "run-mode"));
+}
+
+function runFile(scope: string): string {
+  const key = createHash("sha1").update(scope).digest("hex").slice(0, 16);
+  return resolve(runDir(), `${key}.json`);
+}
+
+function parseRun(file: string): Run | null {
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as Run;
+  } catch {
+    return null;
+  }
+}
+
+function isForgotten(run: Run, now: Date): boolean {
+  return now.getTime() - Date.parse(run.until) > FORGOTTEN_AFTER_MS;
+}
+
+/** The scope's run, or null when there is none or it ended long enough ago to be forgotten. */
+export function readRun(scope: string, now: Date = new Date()): Run | null {
+  const file = runFile(scope);
+  if (!existsSync(file)) return null;
+  const run = parseRun(file);
+  return run && !isForgotten(run, now) ? run : null;
+}
+
+export function writeRun(run: Run): void {
+  writeFileSync(runFile(run.scope), `${JSON.stringify(run, null, 2)}\n`);
+}
+
+export function clearRun(scope: string): boolean {
+  const file = runFile(scope);
+  if (!existsSync(file)) return false;
+  rmSync(file);
+  return true;
+}
+
+export function isOver(run: Run, now: Date = new Date()): boolean {
+  return now.getTime() >= Date.parse(run.until);
+}
+
+function parseDuration(text: string): number | null {
+  const m = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/.exec(text.trim());
+  if (!m) return null;
+  const [, h = "0", min = "0", s = "0"] = m;
+  const ms = (Number(h) * 3600 + Number(min) * 60 + Number(s)) * 1000;
+  return ms > 0 ? ms : null;
+}
+
+function nextLocalTime(text: string, now: Date): Date | null {
+  const m = /^(\d{1,2}):(\d{2})$/.exec(text.trim());
+  if (!m) return null;
+  const [hour, minute] = [Number(m[1]), Number(m[2])];
+  if (hour > 23 || minute > 59) return null;
+  const target = hour * 60 + minute;
+  const ahead =
+    (target - localMinuteOfDay(now) + DAY_MINUTES) % DAY_MINUTES || DAY_MINUTES;
+  const minuteStart = now.getTime() - (now.getTime() % MINUTE_MS);
+  return new Date(minuteStart + ahead * MINUTE_MS);
+}
+
+/** `--for 15m` / `1h30m`, or `--until 18:00` (the next such local time) or an ISO time. */
+export function deadlineFrom(
+  spec: { for?: string; until?: string },
+  now: Date = new Date()
+): Date {
+  if (spec.for !== undefined) {
+    const ms = parseDuration(spec.for);
+    if (ms === null)
+      throw new Error(`Not a duration: "${spec.for}". Use 15m, 2h or 1h30m.`);
+    return new Date(now.getTime() + ms);
+  }
+  if (spec.until !== undefined) {
+    const at = nextLocalTime(spec.until, now) ?? new Date(spec.until);
+    if (Number.isNaN(at.getTime()) || at <= now)
+      throw new Error(`Not a future time: "${spec.until}". Use HH:MM or an ISO time.`);
+    return at;
+  }
+  throw new Error("Give --for <duration> or --until <HH:MM>.");
+}
+
+export function newRun(fields: {
+  kind: RunKind;
+  scope: string;
+  until: Date;
+  now?: Date;
+  task?: string | null;
+  report?: string | null;
+  tasks?: string[];
+  fallbacks?: string[];
+  rules?: string[];
+}): Run {
+  return {
+    kind: fields.kind,
+    scope: fields.scope,
+    startedAt: (fields.now ?? new Date()).toISOString(),
+    until: fields.until.toISOString(),
+    task: fields.task ?? null,
+    report: fields.report ?? null,
+    tasks: fields.tasks ?? [],
+    fallbacks: fields.fallbacks ?? [],
+    rules: fields.rules ?? [],
+    log: [],
+    done: false,
+    stopBlocks: 0,
+  };
+}
+
+export function untilLabel(run: Run): string {
+  return localHourMinute(new Date(run.until));
+}
+
+export function minutesLeft(run: Run, now: Date = new Date()): number {
+  return Math.max(0, Math.ceil((Date.parse(run.until) - now.getTime()) / MINUTE_MS));
+}
+
+function numbered(items: string[]): string[] {
+  return items.map((item, i) => `  ${i + 1}. ${item}`);
+}
+
+function logLines(run: Run): string[] {
+  return run.log.map((l) => `  - ${localHourMinute(new Date(l.at))} ${l.entry}`);
+}
+
+function timeLine(run: Run, now: Date): string {
+  const name = run.kind === "unattended" ? "Unattended" : "Time box";
+  return isOver(run, now)
+    ? `${name} ended at ${untilLabel(run)}.`
+    : `${name} until ${untilLabel(run)} (${minutesLeft(run, now)} min left).`;
+}
+
+/** The whole run as text: what `status` prints and what compaction recovery injects. */
+export function describeRun(run: Run, now: Date = new Date()): string {
+  const lines = [timeLine(run, now)];
+  if (run.task) lines.push(`Task: ${run.task}`);
+  if (run.report) lines.push(`Report: ${run.report}`);
+  if (run.rules.length) lines.push("Rules:", ...numbered(run.rules));
+  if (run.tasks.length) lines.push("Tasks, in order:", ...numbered(run.tasks));
+  if (run.fallbacks.length) lines.push("Fallbacks:", ...numbered(run.fallbacks));
+  if (run.log.length) lines.push("Log:", ...logLines(run));
+  if (run.done) lines.push("Marked done.");
+  return lines.join("\n");
+}

package/src/hooks/lib/security-gate.ts

@@ -9,6 +9,7 @@
 
 import { ANTIGRAVITY_WRITE_TOOLS, FILE_TARGET_KEYS, normalizeToolUse } from "./agent";
 import { logDebug } from "./log";
+import { type RunToolCall, runModeRefusal } from "./run-mode-gate";
 import { checkBashCommand, checkFilePath } from "./security";
 
 /** beforeShellExecution (Cursor only) — flat, no tool-name wrapper. */
@@ -100,8 +101,27 @@ function writesFile(toolName: string): boolean {
  * `cwd` is passed rather than read so a test can pin the target of a refused
  * command, which has no file of its own to name.
  */
+function runModeGateRefusal(
+  call: RunToolCall,
+  cwd: string,
+  hookEventName?: string
+): GateRefusal | null {
+  const message = runModeRefusal(call, cwd);
+  if (!message) return null;
+  return {
+    tool: call.tool,
+    target: call.filePath ?? cwd,
+    command: call.command,
+    reason: "run mode",
+    message,
+    hookEventName,
+  };
+}
+
 export function decideRefusal(input: SecurityInput, cwd: string): GateRefusal | null {
   if (isShellExec(input)) {
+    const runRefusal = runModeGateRefusal({ tool: "shell", command: input.command }, cwd);
+    if (runRefusal) return runRefusal;
     const reason = checkBashCommand(input.command);
     if (!reason) return null;
     return {
@@ -129,6 +149,18 @@ export function decideRefusal(input: SecurityInput, cwd: string): GateRefusal |
     "CommandLine",
     "script",
   ]);
+  const filePath = firstStringArg(toolUse.toolInput, FILE_TARGET_KEYS);
+  const runRefusal = runModeGateRefusal(
+    {
+      tool: toolUse.toolName,
+      command: runsShellCommand(toolUse.toolName) ? command : undefined,
+      filePath: writesFile(toolUse.toolName) ? filePath : undefined,
+    },
+    cwd,
+    toolUse.hookEventName
+  );
+  if (runRefusal) return runRefusal;
+
   if (runsShellCommand(toolUse.toolName) && command) {
     const reason = checkBashCommand(command);
     // "No output" from a downstream tool is indistinguishable between "denied,
@@ -148,7 +180,6 @@ export function decideRefusal(input: SecurityInput, cwd: string): GateRefusal |
     }
   }
 
-  const filePath = firstStringArg(toolUse.toolInput, FILE_TARGET_KEYS);
   if (writesFile(toolUse.toolName) && filePath) {
     const reason = checkFilePath(filePath);
     if (reason) {

package/src/hooks/lib/security.ts

@@ -297,6 +297,22 @@ function withoutPalCliInvocations(cmd: string): string {
     .join("");
 }
 
+const STREAM_REDIRECT = /\d?>&\d/g;
+const OUTPUT_FILTER = /^\s*(?:head|tail)\b/;
+
+/** True when the command is `pal cli …`, optionally chained to more of it or piped into head/tail. */
+export function runsOnlyPalCli(cmd: string): boolean {
+  const pieces = splitOnUnquotedSeparators(cmd.replace(STREAM_REDIRECT, " "))
+    .map((piece) => piece.text)
+    .filter((text) => text.trim() !== "");
+  const [first, ...rest] = pieces;
+  return (
+    first !== undefined &&
+    isPalCliInvocation(first) &&
+    rest.every((text) => isPalCliInvocation(text) || OUTPUT_FILTER.test(text))
+  );
+}
+
 function unquotedSegments(cmd: string): string[] {
   return splitOnUnquotedSeparators(cmd).map((piece) => piece.text.trim());
 }

package/src/hooks/lib/send-back-guard.ts

@@ -0,0 +1,37 @@
+/**
+ * One send-back per reply: the stop right after a reply check sent a reply back
+ * lets the corrected reply through. A stop held for any other reason, such as an
+ * unattended run, leaves the next reply checked again.
+ */
+
+import { existsSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { hookSessionId } from "./hook-turn";
+import { ensureDir, paths } from "./paths";
+import type { StopTurnPayload } from "./stop";
+
+function isContinuedStop(payload: StopTurnPayload): boolean {
+  return (
+    payload.stop_hook_active === true ||
+    (payload.loop_count ?? 0) > 0 ||
+    (payload.executionNum ?? 0) > 0
+  );
+}
+
+function markerOf(session: string): string {
+  const dir = ensureDir(resolve(paths.state(), "reply-sent-back"));
+  return resolve(dir, session.replace(/[^\w-]/g, "_"));
+}
+
+export function alreadySentBack(payload: StopTurnPayload): boolean {
+  if (!isContinuedStop(payload)) return false;
+  const session = hookSessionId(payload);
+  return session ? existsSync(markerOf(session)) : true;
+}
+
+export function rememberSendBack(payload: StopTurnPayload, sentBack: boolean): void {
+  const session = hookSessionId(payload);
+  if (!session) return;
+  if (sentBack) writeFileSync(markerOf(session), "");
+  else rmSync(markerOf(session), { force: true });
+}

package/src/hooks/lib/session-events.ts

@@ -74,6 +74,10 @@ function gitDirOf(start: string): string | null {
   }
 }
 
+export function isInGitRepo(cwd: string): boolean {
+  return gitDirOf(cwd) !== null;
+}
+
 export function gitBranchOf(cwd: string): string | null {
   try {
     const gitDir = gitDirOf(cwd);

package/src/hooks/lib/wall-clock.ts

@@ -71,6 +71,18 @@ export function localClock(now: Date = new Date()): { hour: number; weekday: str
   return { hour: Number(f.hour), weekday: f.weekday };
 }
 
+/** Minutes since local midnight in the principal's timezone. */
+export function localMinuteOfDay(now: Date = new Date()): number {
+  const f = fieldsIn(now, zoneOrUtc(identity().principal.timezone));
+  return Number(f.hour) * 60 + Number(f.minute);
+}
+
+/** HH:MM in the principal's timezone. */
+export function localHourMinute(at: Date): string {
+  const f = fieldsIn(at, zoneOrUtc(identity().principal.timezone));
+  return `${f.hour}:${f.minute}`;
+}
+
 export function getWallClockReminder(now: Date = new Date()): string | null {
   if (!isEnabled("wallClock")) return null;
   const line = wallClockLine(now, identity().principal.timezone);