gcf-harness-aif-ext 0.8.9 → 0.9.0

package/README.md

@@ -47,6 +47,14 @@ Updating keeps the hook entry valid — it points into the extension's install d
 
 0.5.1 is a fix release. During a run, `gcf/config.yml` is always readable, and a Grep inside `gcf/` reads only readset files. An import breaks a `depends:` cycle the pair checks closed and asks a D1 about it. It cuts a section longer than a segment at paragraphs, and lens and pair prompts carry a window around the quote. `/gcf-run` checks the plan against each pillar's invariant and asks each pillar's review question over the diff. Use it with core 0.4.1, which brings the parent feature into the readset.
 
+0.9.0, to update together with core 0.7.6:
+- The harness's own agent runs with `--permission-mode bypassPermissions`: it may do everything but the project's deny rules, which hold in every mode. The rules come from the deny groups of `gcf/config.yml` (`ai-factory gcf permissions`, or the board): git history and uncommitted work, recursive delete, publishing, the human's GCF moves and the guards are on by default; secrets, changes outside the project and killing processes are off. `git push` is allowed. Deny rules match the command as written: they catch accidents, not a rewording, and `/gcf-run` makes a refused command a stop with `needs permission: <command>`.
+- A run loads the project's settings and MCP servers only (`--setting-sources project,local --strict-mcp-config --mcp-config .mcp.json`): the operator's plugins, hooks and claude.ai connectors stay out. So does `env` or `apiKeyHelper` in `~/.claude/settings.json`: an operator who logs in through them, not `claude login`, names the agent with `--agent`. The deny rules and the handoff guard come in `.gcf-session/runs/agent-settings.json` (`--settings`), so a worktree gets them without a commit.
+- Context handoff: past `context_handoff_pct` (60 by default) of the window, or at a compaction, the run flags the session; the handoff guard then denies every call of the main agent but the plan's read and edit with the instruction to write `## Handoff` into the plan and end. The run starts a fresh session with `/gcf-run <id> --handoff`, which goes on from the plan: the ticked tasks stay done. A session that works on past its flag is stopped; after 3 handoffs in a row the item is blocked with `context handoff limit`. The window is `context_window`, else the one a result of the same model reported (`.gcf-session/runs/windows.json`); with neither, the first session of a model runs without a handoff and says so. The sessions of an item share one timeout, and their costs add up; `--json` gives `handoffs`.
+- `auto_compact_pct` sets the agent's `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`, at least 15 points above the handoff share.
+- The readset-guard reads the manifest of the directory the session started in (`CLAUDE_PROJECT_DIR`): an agent's `cd` no longer lifts the readset.
+- `/gcf-run` writes a plan task's code through aif-implement, so the plan ticks show the item's progress, and answers aif-implement's questions itself: no commit, stash or merge.
+
 0.8.0, to update together with core 0.7.0:
 - `run_mode: main` in `gcf/config.yml` (or `run --mode main`): items run one after another in the main checkout, for an agent that works through an editor bound to the project folder. The item carries the core's session mark (`gcf claim`), not a run lock, so the agent records its own move; one run works the checkout at a time (`.gcf-session/runs/.main-run.lock`).
 - `gcf-harness next [N] --json`: the ready items that can run together now, by priority; each is taken while the batch with it passes the gate.

package/commands/activity.js

@@ -38,7 +38,8 @@ const resultText = (content) =>
   Array.isArray(content) ? content.map((c) => c?.text ?? '').join('\n') : String(content ?? '');
 
 /** `1.2M`, `85k`, `950`: one decimal below ten of its unit. */
-const count = (n) => (n >= 1e6 ? scaled(n / 1e6, 'M') : n >= 1e3 ? scaled(n / 1e3, 'k') : `${n}`);
+export const count = (n) =>
+  n >= 1e6 ? scaled(n / 1e6, 'M') : n >= 1e3 ? scaled(n / 1e3, 'k') : `${n}`;
 const scaled = (v, unit) => `${v < 10 ? v.toFixed(1) : Math.round(v)}${unit}`;
 
 /** `8s`, `34m`, `1h 12m`. */
@@ -106,7 +107,12 @@ function limitIn(text, whole = true) {
  * final text, a summary line and the cost. `session_id` comes with the init event, `limit` with
  * the usage-limit message, in whatever form it arrives: the session can be resumed after either.
  * @param {string} line
- * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null}}}
+ * The main agent's turns also carry `context`, the tokens its window holds (a subagent's turns,
+ * `parent_tool_use_id` set, fill a window of their own); the init names the `model`, the result
+ * the `windows` of its models, and a compaction says `compacted`.
+ * @returns {{lines: string[], cost?: Cost, session_id?: string, limit?: {resets: string | null},
+ *   context?: number, turn?: string, model?: string, windows?: Record<string, number>,
+ *   compacted?: boolean}}
  */
 export function activity(line, now = new Date()) {
   let e;
@@ -120,8 +126,8 @@ export function activity(line, now = new Date()) {
 
   const at = `[${clock(now)}]`;
   const content = Array.isArray(e.message?.content) ? e.message.content : [];
-  if (e.type === 'system') return system(e);
-  if (e.type === 'assistant') return said(content, at);
+  if (e.type === 'system') return system(e, at);
+  if (e.type === 'assistant') return { ...said(content, at), ...contextOf(e) };
   if (e.type === 'user')
     return {
       lines: content
@@ -133,11 +139,33 @@ export function activity(line, now = new Date()) {
   return { lines: [] };
 }
 
-/** A system event: the init names the session; the rest (hooks, thinking) give nothing. */
-const system = (e) =>
-  e.subtype === 'init' && typeof e.session_id === 'string'
-    ? { lines: [], session_id: e.session_id }
-    : { lines: [] };
+/**
+ * A system event: the init names the session and its model; a compaction is a line, the
+ * agent's context summarized; the rest (hooks, thinking) give nothing.
+ */
+function system(e, at) {
+  if (e.subtype === 'compact_boundary')
+    return { lines: [`${at} compacted: the agent's context was summarized`], compacted: true };
+  if (e.subtype !== 'init' || typeof e.session_id !== 'string') return { lines: [] };
+
+  return {
+    lines: [],
+    session_id: e.session_id,
+    ...(typeof e.model === 'string' ? { model: e.model } : {}),
+  };
+}
+
+/** The tokens a main-agent turn holds in its window: its input, read from cache or written. */
+function contextOf(e) {
+  const u = e.message?.usage;
+  if (e.parent_tool_use_id != null || !u) return {};
+  const tokens =
+    Number(u.input_tokens ?? 0) +
+    Number(u.cache_read_input_tokens ?? 0) +
+    Number(u.cache_creation_input_tokens ?? 0);
+
+  return { context: tokens, ...(e.message.id ? { turn: String(e.message.id) } : {}) };
+}
 
 /** An assistant turn: its tool calls and its text, which may be the usage-limit message. */
 function said(content, at) {
@@ -162,9 +190,15 @@ function ended(e, at) {
   // An error result counts the message anywhere in it; any other only as the whole text.
   const limit = limitIn(e.result, !e.is_error);
 
+  // The window of each model the session used: its subagents may run on another.
+  const windows = Object.entries(e.modelUsage ?? {})
+    .map(([m, u]) => [m, Number(u?.contextWindow)])
+    .filter(([, n]) => n > 0);
+
   return {
     lines: [...text, `${at} ${summary(e, cost, Boolean(limit.limit))}`],
     cost,
     ...limit,
+    ...(windows.length ? { windows: Object.fromEntries(windows) } : {}),
   };
 }

package/commands/harness.js

@@ -4,11 +4,11 @@
 // allows what a headless agent run needs (AGENT_ALLOW).
 // `ai-factory gcf-harness gate <ids…>` — the /gcf-run gate as code (Harness-PRD §4.3).
 import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN } from './run.js';
+import { run, cliCore, DEFAULT_AGENT, DEFAULT_TIMEOUT_MIN, MAIN_RUN, stopOf } from './run.js';
 
 const EXT_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MARKER = 'gcf-readset-guard';
@@ -214,6 +214,9 @@ function registerGuard(settings, command) {
 // What a headless `claude -p` run needs at least: it cannot ask, so anything not allowed is
 // denied. The engine's own tools (an editor's MCP server) are the project's to add. On Windows
 // the agent runs commands through its PowerShell tool, which Bash rules do not cover.
+// The harness's own agent runs with bypassPermissions and the project's deny rules (run.js
+// runFlags), where allow rules do nothing: these serve an agent named with `--agent` and a
+// manual session. shortcut: the list stays this short; grow the deny groups, not this.
 const AGENT_ALLOW = [
   'Edit',
   'Write',
@@ -379,8 +382,16 @@ export function stopRun(projectDir, id, core = cliCore(projectDir)) {
   const runs = path.join(path.resolve(projectDir), '.gcf-session', 'runs');
   const main = lockOf(path.join(runs, `${MAIN_RUN}.lock`));
   const lock = lockOf(path.join(runs, `${id}.lock`)) ?? (main?.item === id ? main : null);
+  // Between two sessions of the item (a context handoff) the lock names none: the mark keeps
+  // the run from starting the next one.
+  if (lock?.item === id)
+    writeFileSync(
+      stopOf(runs, id),
+      `${Date.now()}
+`,
+    );
   if (lock && lock.session && alive(lock.session)) killTree(lock.session, true);
-  else if (lock) killTree(lock.run, false);
+  else if (lock && lock.item !== id) killTree(lock.run, false);
   core(['release', id]);
 
   return lock ? `stopped the run of ${id}; it stays ready` : `no run drives ${id}`;

package/commands/run.js

@@ -3,14 +3,97 @@
 // verified branches a dead run left; an agent that needs the human leaves `outcome.json` in its
 // worktree, and the block is recorded on main — a worktree never writes gcf/ status.
 import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, utimesSync, writeFileSync, writeSync } from 'node:fs';
+import { existsSync, mkdirSync, utimesSync, writeFileSync, writeSync } from 'node:fs';
 import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { activity, clock } from './activity.js';
+import { fileURLToPath } from 'node:url';
+import { activity, clock, count } from './activity.js';
 
 // The event stream, not the final answer alone: the log shows the session at work as it goes.
 export const DEFAULT_AGENT = 'claude -p --output-format stream-json --verbose';
 
+const HOOKS = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'hooks');
+
+/**
+ * What the harness's own agent runs with (Harness-PRD §7): everything allowed but the project's
+ * deny rules, which hold in every mode; the project's settings and MCP servers only, so the
+ * operator's plugins, hooks and connectors stay out of the run; and `settingsFile`, the deny
+ * rules and the handoff guard. An agent the operator names (`--agent`) gets none of it.
+ */
+export function runFlags(dir, settingsFile) {
+  const mcp = existsSync(path.join(dir, '.mcp.json')) ? ' --mcp-config .mcp.json' : '';
+
+  return (
+    '--permission-mode bypassPermissions --setting-sources project,local ' +
+    `--strict-mcp-config${mcp} --settings "${settingsFile}"`
+  );
+}
+
+/** `.gcf-session/runs/agent-settings.json`: the deny rules of `gcf board`, the handoff guard. */
+export async function writeAgentSettings(logs, agent) {
+  const file = path.join(logs, 'agent-settings.json');
+  const guard = path.join(HOOKS, 'handoff-guard.js').replaceAll('\\', '/');
+  const settings = {
+    permissions: { deny: agent?.deny ?? [], allow: agent?.allow ?? [] },
+    hooks: {
+      PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: `node "${guard}"` }] }],
+    },
+  };
+  await writeFile(file, `${JSON.stringify(settings, null, 2)}\n`);
+
+  return file;
+}
+
+// The window of a model a run met before: `<model>: tokens`, from the result of its sessions.
+const windowsOf = (logs) => path.join(logs, 'windows.json');
+
+/**
+ * The context window a session's share is taken of: the project's `context_window`, the one a
+ * result of the same model reported, then a `[1m]` model; null when none says it.
+ */
+export function windowFor(model, configured, learned) {
+  if (configured > 0) return configured;
+  if (model && learned?.[model] > 0) return learned[model];
+
+  return /\[1m\]$/i.test(model ?? '') ? 1_000_000 : null;
+}
+
+/** Keep the window a session's result reported for its model. */
+async function learnWindow(logs, learned, ran) {
+  if (!ran.model || !(ran.window > 0) || learned[ran.model] === ran.window) return;
+  learned[ran.model] = ran.window;
+  await writeFile(windowsOf(logs), `${JSON.stringify(learned, null, 2)}\n`).catch(() => {});
+}
+
+// The flag the handoff guard reads, in the session's own checkout.
+const HANDOFF_FLAG = path.join('.gcf-session', 'handoff.json');
+// Fresh sessions one item may take in a row; the next handoff blocks it.
+export const MAX_HANDOFFS = 3;
+const HANDOFF_LIMIT =
+  `context handoff limit: ${MAX_HANDOFFS} fresh sessions did not finish the item - ` +
+  'split it, or raise context_handoff_pct';
+// A session that keeps on working past its flag: main-agent turns, or points over the share.
+const HARD_TURNS = 8;
+const HARD_OVER = 15;
+
+/** Two costs as one: what an item's sessions spent together. */
+function addCost(a, b) {
+  if (!a || !b) return a ?? b;
+  const t = (k) => a.tokens[k] + b.tokens[k];
+
+  return {
+    cost_usd: a.cost_usd + b.cost_usd,
+    tokens: {
+      input: t('input'),
+      output: t('output'),
+      cache_read: t('cache_read'),
+      cache_creation: t('cache_creation'),
+    },
+    turns: a.turns + b.turns,
+    duration_ms: a.duration_ms + b.duration_ms,
+  };
+}
+
 /** The core CLI: the same ai-factory that runs this command, in the project. */
 export function cliCore(projectDir) {
   return (args) => {
@@ -104,9 +187,11 @@ function byLine(stream, take) {
     rest = lines.pop() ?? '';
     for (const l of lines) take(l);
   });
+  // Cleared before the take: a take that ends the session flushes again, and must find nothing.
   const flush = () => {
-    if (rest) take(rest);
+    const last = rest;
     rest = '';
+    if (last) take(last);
   };
 
   stream.on('end', flush);
@@ -123,10 +208,16 @@ const NO_SESSION = /No conversation found with session ID/;
  * good. Its stdout reaches the log through `activity`, its stderr as it is; `cost` is what a
  * Claude session reported at its end, `session_id` the id a rerun resumes it by, `limit` the
  * usage limit that ended it, `gone` that the session it was to resume does not exist.
+ *
+ * `handoff` ({pct, windowOf(model), plan}) watches the main agent's context: past `pct` of the
+ * window, or at a compaction, the session gets `.gcf-session/handoff.json`, and the handoff
+ * guard turns its tool calls into the instruction to hand over; one that keeps on working is
+ * stopped. `handoff: true` says the session was told to hand over.
  * @returns {Promise<{code: number | string, cost?: import('./activity.js').Cost,
- *   session_id?: string, limit?: {resets: string | null}, gone: boolean}>}
+ *   session_id?: string, limit?: {resets: string | null}, gone: boolean, handoff: boolean,
+ *   model?: string, window?: number}>}
  */
-function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
+function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn, env = {}, handoff }) {
   return new Promise((resolve) => {
     const command = `${agent} "${prompt}"`;
     // A line before the agent's first: the log's time says the session is alive from its start.
@@ -135,7 +226,8 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
       cwd: dir,
       shell: true,
       // The session's own gate must not refuse the item this run marked as running.
-      env: { ...process.env, GCF_RUN_ITEM: id },
+      // The guards read the session's own checkout, not one an outer Claude session named.
+      env: { ...process.env, ...env, GCF_RUN_ITEM: id, CLAUDE_PROJECT_DIR: dir },
       detached: !WIN,
       windowsHide: true,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -147,6 +239,13 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
     let sessionId;
     let limit;
     let gone = false;
+    let model;
+    let window;
+    let context = 0;
+    let flagged = false;
+    let unknown = false;
+    let turn;
+    let after = 0;
     const write = (lines) => {
       try {
         if (open && lines.length) writeSync(fd, lines.map((l) => `${l}\n`).join(''));
@@ -155,12 +254,50 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
       }
     };
 
+    /** The handoff watch of one event: flag the session past its share, stop it past more. */
+    const watch = (compacted) => {
+      if (!handoff?.pct || !open) return;
+      const win = handoff.windowOf(model);
+      const pct = win ? Math.round((100 * context) / win) : null;
+      if (pct === null && !compacted && !unknown) {
+        unknown = true;
+        write([`[${clock()}] handoff: off, the window of ${model ?? 'the model'} is unknown`]);
+      }
+      if (!flagged && (compacted || (pct !== null && pct >= handoff.pct))) {
+        flagged = true;
+        const flag = { pct, tokens: context, window: win, plan: handoff.plan ?? null };
+        try {
+          mkdirSync(path.join(dir, '.gcf-session'), { recursive: true });
+          writeFileSync(path.join(dir, HANDOFF_FLAG), `${JSON.stringify(flag)}\n`);
+        } catch {
+          // No flag: the turns past it stop the session all the same.
+        }
+        const at = compacted ? 'a compaction' : `context ${pct}%`;
+        const of = win && !compacted ? ` (${count(context)} of ${count(win)})` : '';
+        write([`[${clock()}] handoff: ${at}${of}, the session hands over`]);
+      }
+      if (flagged && (after > HARD_TURNS || (pct !== null && pct >= handoff.pct + HARD_OVER))) {
+        write([`[${clock()}] handoff: the session went on past its flag, stopped`]);
+        killTree(child);
+        end('handoff');
+      }
+    };
+
     const flushOut = byLine(child.stdout, (line) => {
       const a = activity(line);
       cost = a.cost ?? cost;
       sessionId = a.session_id ?? sessionId;
       limit = a.limit ?? limit;
+      model = a.model ?? model;
+      // The init model's window; the largest when the result does not name that model.
+      if (a.windows) window = a.windows[model] ?? Math.max(...Object.values(a.windows));
       write(a.lines);
+      if (a.context !== undefined) {
+        context = a.context;
+        if (flagged && a.turn !== turn) after++;
+        turn = a.turn;
+      }
+      if (a.context !== undefined || a.compacted) watch(Boolean(a.compacted));
     });
     const flushErr = byLine(child.stderr, (line) => {
       gone ||= NO_SESSION.test(line);
@@ -177,7 +314,20 @@ function startAgent(agent, prompt, dir, { fd, timeoutMs, id, onSpawn }) {
       open = false;
       sessions.delete(child);
       clearTimeout(timer);
-      resolve({ code, cost, session_id: sessionId, limit, gone });
+      // Told to hand over, and it went on past the flag: it read the guard's instruction, or the
+      // run stopped it. A flag on its last turn found a session already done.
+      const handedOver = flagged && (after > 0 || code === 'handoff');
+      resolve({
+        code,
+        cost,
+        session_id: sessionId,
+        limit,
+        gone,
+        handoff: flagged,
+        handedOver,
+        model,
+        window,
+      });
     }
 
     child.on('error', () => end(-1));
@@ -369,6 +519,9 @@ async function prepare({ claimed, failed }, core, agentOf) {
   return { ready, failed };
 }
 
+/** `<id>.stop`: `gcf-harness stop` between two sessions of the item: no fresh one starts. */
+export const stopOf = (logs, id) => path.join(logs, `${id}.stop`);
+
 /** `<id>.agent.json`: the agent session an item's last run left unfinished, for a rerun. */
 const recordOf = (logs, id) => path.join(logs, `${id}.agent.json`);
 
@@ -380,7 +533,10 @@ async function kept(logs, id) {
   try {
     const rec = JSON.parse(await readFile(recordOf(logs, id), 'utf8'));
 
-    return SESSION_ID.test(String(rec?.session_id)) ? rec : null;
+    if (SESSION_ID.test(String(rec?.session_id))) return rec;
+
+    // A handoff needs no session: the rerun starts fresh. An id that is not one is dropped.
+    return rec?.ended === 'handoff' ? { ...rec, session_id: undefined } : null;
   } catch {
     return null;
   }
@@ -393,12 +549,26 @@ async function kept(logs, id) {
 async function remember(logs, r, item) {
   if (item.result === 'error') return;
   if (!STAYED.test(item.result) || r.lost) return rm(recordOf(logs, r.id), { force: true });
-  if (!r.session_id) return;
-  const ended = r.limit ? 'limit' : r.code === 'timeout' ? 'timeout' : `exit ${r.code}`;
+  if (!r.session_id && !r.handoffPending && !r.handoffs) return;
+  // A session that handed over is not resumed: the rerun starts fresh from the plan. So does
+  // one after a handoff that reported no id: the full session before it is never resumed.
+  const ended =
+    r.handoffPending || !r.session_id
+      ? 'handoff'
+      : r.limit
+        ? 'limit'
+        : r.code === 'timeout'
+          ? 'timeout'
+          : `exit ${r.code}`;
   const rec = {
-    session_id: r.session_id,
+    ...(r.session_id ? { session_id: r.session_id } : {}),
     ended,
     ...(r.limit?.resets ? { resets: r.limit.resets } : {}),
+    // The handoffs so far: the cap holds across runs.
+    ...(r.handoffs ? { handoffs: r.handoffs } : {}),
+    // The fresh session a counted handoff started ended with no id: the next one is no new
+    // handoff, only the same fresh start again.
+    ...(!r.handoffPending && !r.session_id ? { counted: true } : {}),
     at: new Date().toISOString(),
   };
   await writeFile(recordOf(logs, r.id), `${JSON.stringify(rec, null, 2)}\n`);
@@ -416,6 +586,17 @@ function noResult(r, rerun) {
         `no result (its session could not be resumed, agent exit ${r.code}): ` +
         `${r.id} stays ready, a rerun starts fresh`,
     };
+  if (r.handoffPending) {
+    const limit = r.limit
+      ? `usage limit${r.limit.resets ? `, resets ${r.limit.resets}` : ''}; `
+      : '';
+
+    return {
+      id: r.id,
+      result: `paused (${limit}context handoff): ${r.id} stays ready, a rerun goes on from the plan`,
+      ...(r.limit ? { limit_resets: r.limit.resets } : {}),
+    };
+  }
   const again = r.session_id ? 'a rerun resumes its session' : rerun;
   if (r.limit) {
     const resets = r.limit.resets ? `, resets ${r.limit.resets}` : '';
@@ -434,16 +615,20 @@ function noResult(r, rerun) {
 
 const STAYED = / stays ready, a rerun /;
 
+const taskOf = (r) => (r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`);
+
 /**
  * The agent command and prompt of an item's session: `/gcf-run`, or the resume of the session
  * its last run kept (`--resume`, in the same directory, so the agent finds it) unless `fresh`.
  */
 async function commandOf(r, logs, fresh) {
-  const task = r.main ? `/gcf-run ${r.id}` : `/gcf-run ${r.id} --worktree`;
+  const task = taskOf(r);
   if (fresh) await rm(recordOf(logs, r.id), { force: true });
+  const rec = fresh ? null : await kept(logs, r.id);
+  // A session that handed over goes on in a fresh one, whatever the agent.
+  if (rec?.ended === 'handoff') return { agent: r.agent, prompt: `${task} --handoff`, rec };
   // `--resume` is a flag of `claude`: another agent gets the task, and the record stays.
-  const rec = fresh || !/^claude(\s|$)/.test(r.agent) ? null : await kept(logs, r.id);
-  if (!rec) return { agent: r.agent, prompt: task, rec };
+  if (!rec || !/^claude(\s|$)/.test(r.agent)) return { agent: r.agent, prompt: task, rec: null };
   // One plain line: the prompt goes into the shell command in double quotes.
   const ended = String(rec.ended).replace(/[^\w -]/g, '');
 
@@ -458,36 +643,113 @@ async function commandOf(r, logs, fresh) {
  * One session per item, its output in `.gcf-session/runs/<id>.log`. In a worktree the skill runs
  * its worktree mode; on main it records the item's move itself.
  */
-async function session(r, logs, timeoutMs, fresh) {
+async function session(r, { logs, timeoutMs, fresh, launch }) {
   /** @type {import('node:fs/promises').FileHandle | null} */
   let log = null;
   // The lock names the item and its session: `stop <id>` ends that session alone, not the run.
   const lock = path.join(logs, `${r.main ? MAIN_RUN : r.id}.lock`);
-  const onSpawn = (pid) => writeFileSync(lock, `${process.pid}\n${r.id}\n${pid}\n`);
+  const onSpawn = (pid) => {
+    writeFileSync(lock, `${process.pid}\n${r.id}\n${pid}\n`);
+    // A stop that came while the lock named no session left only its mark: it ends this one.
+    if (existsSync(stopOf(logs, r.id))) killTree({ pid });
+  };
   // On main the item carries a session mark; a stage with no gcf command must not expire it.
   const mark = path.join(logs, `${r.id}.session`);
   const keep = r.main ? setInterval(() => touch(mark), 5 * 60_000) : null;
+  const flag = path.join(r.dir, HANDOFF_FLAG);
+  await rm(stopOf(logs, r.id), { force: true });
   try {
-    const { agent, prompt, rec } = await commandOf(r, logs, fresh);
+    let { agent, prompt, rec } = await commandOf(r, logs, fresh);
     log = await open(path.join(logs, `${r.id}.log`), 'a');
-    const opts = { fd: log.fd, timeoutMs, id: r.id, onSpawn };
-    const ran = await startAgent(agent, prompt, r.dir, opts);
+    const fd = log.fd;
+    const flags = launch?.flags(r.dir);
+    const handoff = launch?.handoff && { ...launch.handoff, plan: launch.planOf?.(r.id) };
+    // One deadline for the item, however many sessions it takes.
+    const deadline = Date.now() + timeoutMs;
+    let handoffs = Number(rec?.handoffs) || 0;
+    let cost;
+    let ran = null;
+    let lost = false;
+    let handoffLimit = false;
+    const stopped = () => existsSync(stopOf(logs, r.id));
+    // The cap counts each handoff once, the one a kept record still owes a session included.
+    const capped = async () => {
+      if (handoffs < MAX_HANDOFFS) {
+        handoffs++;
+
+        return false;
+      }
+      handoffLimit = true;
+      // A worktree records no move: the main checkout reads the block from its outcome.
+      if (!r.main) {
+        await mkdir(path.join(r.dir, '.gcf-session'), { recursive: true });
+        await writeFile(
+          path.join(r.dir, '.gcf-session', 'outcome.json'),
+          `${JSON.stringify({ block: HANDOFF_LIMIT })}
+`,
+        );
+      }
 
-    // A resume that claude answered with `No conversation found`: the session is gone, and the
-    // next run starts fresh rather than fail on it again. Any other early end (a stop, a crash,
-    // no network) keeps it for the next try.
-    const lost = Boolean(rec) && ran.gone;
+      return true;
+    };
+    // A record whose handoff its own run already counted (`counted`) owes none.
+    const fromHandoff = rec?.ended === 'handoff';
+    const owed = fromHandoff && !rec.counted;
+    for (let first = true; !(first && owed && (await capped())); first = false) {
+      await rm(flag, { force: true });
+      const command = flags ? `${agent} ${flags}` : agent;
+      const left = Math.max(deadline - Date.now(), 1000);
+      const opts = { fd, timeoutMs: left, id: r.id, onSpawn, env: launch?.env, handoff };
+      ran = await startAgent(command, prompt, r.dir, opts);
+      await rm(flag, { force: true });
+      // Between two sessions the lock names none: a stop then marks the item, not the run.
+      writeFileSync(
+        lock,
+        `${process.pid}
+${r.id}
+`,
+      );
+      cost = addCost(cost, ran.cost);
+      if (launch?.learned) await learnWindow(logs, launch.learned, ran);
+      // A resume that claude answered with `No conversation found`: the session is gone, and
+      // the next run starts fresh rather than fail on it again. Any other early end (a stop, a
+      // crash, no network) keeps it for the next try.
+      if (first) lost = Boolean(rec) && !fromHandoff && ran.gone;
+      // The resumed session's id stands in for one its own run did not report; a fresh session
+      // after a handoff has none to borrow: the full one is never resumed.
+      if (first && !fromHandoff && !lost) ran.session_id ??= rec?.session_id;
+
+      // Only a session that handed over as told goes on: one that saw its flag and ended its
+      // reply, or that the run stopped past it. A stop, a limit or the deadline leaves the
+      // handoff to the next run.
+      const over = ran.handedOver && (ran.code === 0 || ran.code === 'handoff') && !ran.limit;
+      if (!over || Date.now() >= deadline || stopped() || (await r.done?.())) break;
+      if (await capped()) break;
+      writeSync(
+        fd,
+        `[${clock()}] handoff ${handoffs}: a fresh session goes on from the plan
+`,
+      );
+      agent = r.agent;
+      prompt = `${taskOf(r)} --handoff`;
+    }
 
     return {
       ...r,
-      ...ran,
-      session_id: ran.session_id ?? (lost ? undefined : rec?.session_id),
+      ...(ran ?? { code: 0 }),
+      cost,
+      handoffs,
+      handoffLimit,
+      // The session was told to hand over and no fresh one took it: the next run does.
+      // A limit there too: the rerun after the reset starts fresh, it does not resume the full one.
+      handoffPending: Boolean(ran?.handoff) && !handoffLimit,
       lost,
     };
   } catch (e) {
     return { ...r, code: null, error: e.message };
   } finally {
     if (keep) clearInterval(keep);
+    await rm(stopOf(logs, r.id), { force: true });
     await log?.close();
     await r.release();
   }
@@ -569,6 +831,34 @@ function resultOf(run, integrated) {
 
 export const DEFAULT_TIMEOUT_MIN = 120;
 
+/**
+ * How the run starts its sessions (Harness-PRD §7): a `managed` agent, the harness's own, gets
+ * the run flags, the settings file and the handoff watch, which needs the guard those settings
+ * bring; every agent gets the compaction share. A core that reports no deny rules is refused:
+ * bypass with none would allow everything.
+ */
+async function launchOf(logs, managed, board) {
+  if (managed && !Array.isArray(board.agent?.deny))
+    throw new Error('gcf board reports no agent deny rules: update gcf-aif-ext to 0.7.6 or later');
+  const settings = managed ? await writeAgentSettings(logs, board.agent) : null;
+  const ctx = board.context ?? {};
+  const learned = await readFile(windowsOf(logs), 'utf8')
+    .then((t) => JSON.parse(t) ?? {})
+    .catch(() => ({}));
+
+  return {
+    flags: (dir) => (settings ? runFlags(dir, settings) : ''),
+    env: ctx.compact_pct > 0 ? { CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: String(ctx.compact_pct) } : {},
+    handoff: managed &&
+      ctx.handoff_pct > 0 && {
+        pct: ctx.handoff_pct,
+        windowOf: (model) => windowFor(model, ctx.window, learned),
+      },
+    learned,
+    planOf: () => null,
+  };
+}
+
 // The move an item's status shows after a run on main: the agent recorded it itself.
 const MOVE_OF = {
   'awaiting-verdict': 'submit',
@@ -619,30 +909,47 @@ async function runMain(projectDir, ids, ctx) {
 }
 
 /** One item of a main run: marked, its session, its mark cleared, its result read. */
-async function mainItem(projectDir, id, { core, logs, agentOf, timeoutMs, fresh }) {
+async function mainItem(projectDir, id, ctx) {
+  const { core, logs, agentOf } = ctx;
   let r;
   try {
     const claimed = await core(['claim', id]);
     if (!claimed.ok) throw new Error((claimed.err || claimed.out).trim());
     const none = async () => {};
+    // The agent recorded the item's move: no fresh session takes it over.
+    // A board that cannot be read is no move: the run goes on, and the result read says why.
+    const done = async () => {
+      try {
+        const items = json(await core(['board', '--json']), 'board').items;
 
-    const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true };
-    r = await session(s, logs, timeoutMs, fresh);
+        return items?.find((i) => i.id === id)?.status !== 'ready';
+      } catch {
+        return false;
+      }
+    };
+
+    const s = { id, dir: projectDir, agent: agentOf(id), release: none, main: true, done };
+    r = await session(s, ctx);
   } catch (e) {
     r = { id, error: e.message };
   }
 
   await core(['release', id]);
+  if (r.handoffLimit) await core(['block', id, '--reason', HANDOFF_LIMIT]);
   const item = await mainResult(core, r);
   await remember(logs, r, item);
 
-  return { ...item, ...r.cost };
+  return { ...item, ...r.cost, ...(r.handoffs ? { handoffs: r.handoffs } : {}) };
 }
 
 /** Every claimed item in its worktree at once; blocks recorded on main, verified ones merged. */
-async function runWorktrees(claims, { core, logs, agentOf, timeoutMs, fresh }) {
+async function runWorktrees(claims, ctx) {
+  const { core, logs, agentOf } = ctx;
   const { ready, failed } = await prepare(claims, core, agentOf);
-  const runs = await Promise.all(ready.map((r) => session(r, logs, timeoutMs, fresh)));
+  // A session that verified its branch, or left an outcome, is done: no fresh one follows.
+  const done = (r) => () =>
+    verified(r.dir, r.id) || existsSync(path.join(r.dir, '.gcf-session', 'outcome.json'));
+  const runs = await Promise.all(ready.map((r) => session({ ...r, done: done(r) }, ctx)));
   const items = [...failed];
   for (const r of runs) {
     const outcome = await outcomeOf(r.dir);
@@ -665,7 +972,11 @@ async function runWorktrees(claims, { core, logs, agentOf, timeoutMs, fresh }) {
     );
 
   // What each session spent rides on its item's line, when the agent reported it.
-  return items.map((i) => ({ ...i, ...runs.find((r) => r.id === i.id)?.cost }));
+  return items.map((i) => {
+    const r = runs.find((x) => x.id === i.id);
+
+    return { ...i, ...r?.cost, ...(r?.handoffs ? { handoffs: r.handoffs } : {}) };
+  });
 }
 
 /**
@@ -683,6 +994,8 @@ export async function run(
     timeoutMs = DEFAULT_TIMEOUT_MIN * 60_000,
     mode = undefined,
     fresh = false,
+    // The harness's flags, settings and handoff watch: its own agent's by default.
+    managed = agent === DEFAULT_AGENT,
   },
 ) {
   // An id names a lock file and goes into the agent's shell command: a slug, nothing else.
@@ -693,6 +1006,8 @@ export async function run(
   await mkdir(logs, { recursive: true });
   const board = json(await core(['board', '--json']), 'board');
   const runMode = mode ?? board.run_mode ?? 'worktree';
+  // Before any item is claimed: a refusal here leaves no lock behind.
+  const launch = await launchOf(logs, managed, board);
   // The gate counts the items other runs hold locks on, so this run's locks go in with its gate.
   // shortcut: a main run marks each item only as its session starts, so the items it has yet
   // to reach do not count for another run's gate; claim them all here if main and worktree
@@ -705,12 +1020,10 @@ export async function run(
   });
   if (!passed.pass) return { orphans, gate: passed.reason, items: [] };
 
-  const agentOf = (id) =>
-    agentFor(
-      agent,
-      (board.items ?? []).find((i) => i.id === id),
-    );
-  const ctx = { core, logs, agentOf, timeoutMs, fresh };
+  const itemOf = (id) => (board.items ?? []).find((i) => i.id === id);
+  const agentOf = (id) => agentFor(agent, itemOf(id));
+  const ctx = { core, logs, agentOf, timeoutMs, fresh, launch };
+  launch.planOf = (id) => itemOf(id)?.plan_file ?? null;
   const unhook = stopWithSessions();
   try {
     const items =

package/extension.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/lee-to/ai-factory/2.x/schemas/extension.schema.json",
   "name": "gcf-harness-aif-ext",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "skills": [
     "skills/gcf-run",

package/hooks/handoff-guard.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Handoff guard (Harness-PRD §7): a PreToolUse hook the harness hands its agent runs through
+// `--settings`. When the run sees the session's context pass its handoff share it writes
+// .gcf-session/handoff.json; from then on every tool call of the main agent but the plan's
+// read and edit is denied with the handoff instruction, which the agent reads as the reason.
+// The session writes its `## Handoff` into the plan and ends; the harness starts a fresh one.
+// No flag → silent allow. A subagent's call passes: the reviewer it runs ends cleanly first.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const FLAG = path.join('.gcf-session', 'handoff.json');
+
+const PLAN_TOOLS = ['Read', 'Edit', 'Write', 'MultiEdit'];
+
+/** Whether a path is the item's plan (`flag.plan`) or a plan under `.ai-factory/plans/`. */
+function isPlan(file, projectDir, flag) {
+  if (typeof file !== 'string' || !file) return false;
+  const abs = path.resolve(projectDir, file);
+  if (typeof flag.plan === 'string' && abs === path.resolve(projectDir, flag.plan)) return true;
+  const rel = path.relative(path.join(projectDir, '.ai-factory', 'plans'), abs);
+
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+/** The instruction the denied call carries to the agent. */
+export function handoffReason(flag) {
+  const at = flag?.pct ? `${flag.pct}%` : 'its limit';
+
+  return (
+    `context at ${at} of the window: hand over now. Start no new task. Write a "## Handoff" ` +
+    "section at the end of the item's plan: the tasks done, the one in progress and where it " +
+    'stands, the next step, the open review findings and the DoD diagnosis. Put no "- [ ]" ' +
+    'line in it. Leave the task in progress unticked. Then end your reply: a fresh session ' +
+    'goes on from the plan.'
+  );
+}
+
+/**
+ * The verdict on one tool call: `{allow}` or `{allow: false, reason}`. `flag` is the parsed
+ * handoff.json, or null.
+ */
+export function decide(input, projectDir, flag) {
+  if (!flag) return { allow: true };
+  if (input?.agent_id) return { allow: true };
+  const file = input?.tool_input?.file_path;
+  if (PLAN_TOOLS.includes(input?.tool_name) && isPlan(file, projectDir, flag))
+    return { allow: true };
+
+  return { allow: false, reason: handoffReason(flag) };
+}
+
+/** The flag of the session's checkout, or null; an unreadable one still hands over. */
+export function readFlag(projectDir) {
+  let text;
+  try {
+    text = readFileSync(path.join(projectDir, FLAG), 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(text) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+// Hook entry: only runs when executed directly, so tests can import decide().
+const entry = process.argv[1]?.replaceAll('\\', '/');
+if (import.meta.url === `file://${entry}` || entry?.endsWith('handoff-guard.js')) {
+  let input = null;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    // No input: nothing to judge.
+  }
+  // The directory the session started in: `cwd` follows a `cd` of the agent.
+  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
+  const verdict = decide(input, projectDir, readFlag(projectDir));
+  if (!verdict.allow) {
+    console.error(`gcf handoff-guard: ${verdict.reason}`);
+    process.exit(2);
+  }
+
+  process.exit(0);
+}

package/hooks/readset-guard.js

@@ -141,7 +141,9 @@ export function keepSessionsAlive(projectDir, now = Date.now()) {
 const entry = process.argv[1]?.replaceAll('\\', '/');
 if (import.meta.url === `file://${entry}` || entry?.endsWith('readset-guard.js')) {
   const input = readStdin();
-  const projectDir = input?.cwd ?? process.cwd();
+  // The directory the session started in: `cwd` follows a `cd` of the agent, and a manifest
+  // not found there would allow every read.
+  const projectDir = process.env.CLAUDE_PROJECT_DIR ?? input?.cwd ?? process.cwd();
   keepSessionsAlive(projectDir);
   const verdict = decide(input, projectDir, readManifest(projectDir));
   if (!verdict.allow) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gcf-harness-aif-ext",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "description": "GCF orchestration harness for Claude Code: one-command card pipeline, readset guard",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "prepack": "node -e \"const p=require('./package.json'),e=require('./extension.json');if(p.version!==e.version)throw new Error('version mismatch: package.json '+p.version+' vs extension.json '+e.version)\""
   },
   "peerDependencies": {
-    "gcf-aif-ext": "^0.7.0"
+    "gcf-aif-ext": "^0.7.6"
   },
   "files": [
     "extension.json",

package/skills/gcf-run/SKILL.md

@@ -14,6 +14,7 @@ purpose:
 inputs:
 - 1 or more work item or design unit ids; a batch shares one build and one playtest list
 - `--worktree` when `ai-factory gcf-harness run` started this session inside the item's worktree
+- `--handoff` when the harness started this session after the last one filled its context: the plan's `## Handoff` says where it stopped
 
 preconditions:
 - `gcf/` exists and `ai-factory gcf audit` runs (the gcf-aif-ext extension provides it)
@@ -37,6 +38,9 @@ forbidden_behaviors:
 - do not write a refused command into a DoD command or a config that `ai-factory gcf` runs
 - a dedicated tool doing the same job (Read, Grep, Glob, Edit) is no wrapper, nor is a refused pipe or `;` chain split into single allowed commands
 - a refusal none of those replaces is a stop: run `ai-factory gcf block <id> --reason "needs permission: <command>"` and stop the item; under `--worktree` step 22 records it instead
+- a call the handoff guard denies with "context at" is no refusal: block nothing, write the `## Handoff` it asks for and end the reply
+- a read the readset guard denies is no refusal either: drop that read, and widen the readset only through the item's `system:` or `depends:`
+- delete one file with `rm -f <file>` or `Remove-Item -Force <file>`, never with `-r`: the deny rules refuse a recursive delete
 
 workflow:
 1. session ritual: delete a `.gcf-session/readset.json` left by a killed run; run `ai-factory gcf integrate` to merge the verified branches a dead run left; run `ai-factory gcf audit --json`; read `gcf/INDEX.md`; report the audit first line
@@ -63,6 +67,8 @@ workflow:
 22. with `--worktree`, every stop - a failed gate, an over budget readset, a failed plan check, a refused command, steps 11, 12, 14, 18 - writes `{"block": "<reason>"}` to `.gcf-session/outcome.json` and ends the session
 23. with `--worktree`, run no `ai-factory gcf block`, `submit` or `close`: the core refuses them on a `work/` branch, and the harness records the move on main
 24. with `--worktree`, step 17 is: commit everything but `gcf/.metrics`, then run `ai-factory gcf verify <id> --mark`; the harness merges the branch
+25. with `--handoff`: run steps 1, 5 and 6, read the plan's `## Handoff`, skip steps 7-11 unless it says the plan passes were not done, then go on at step 13; a plan with no `## Handoff` goes on at step 13 from its ticks
+26. with `--handoff`, take the review findings and the DoD diagnosis of `## Handoff` into steps 13-15, and delete the section before the commit of step 16
 
 invocation:
 - run when the user names a work item or a unit to drive; batches share steps 1 and 19