forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/github-context.js

@@ -0,0 +1,308 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const ACCOUNT_KEY = 'github.account';
+const HOST = 'github.com';
+const LOGIN_RE = /^(?=.{1,39}$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+const GITHUB_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_host', 'gh_repo']);
+const GITHUB_SECRET_ENV_NAMES = new Set(['gh_token', 'github_token']);
+
+class GithubContextError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'GithubContextError';
+    this.code = code;
+  }
+
+  toJSON() {
+    return { code: this.code, message: this.message };
+  }
+}
+
+function validateGithubLogin(login) {
+  return typeof login === 'string' && LOGIN_RE.test(login);
+}
+
+function safeLogin(login) {
+  return validateGithubLogin(login) ? login : null;
+}
+
+function runnerFor(options) {
+  return options.runner || options._runner || options._exec || options.execFileSync || defaultRunner;
+}
+
+function defaultRunner(command, args, options = {}) {
+  return execFileSync(command, args, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+    ...options,
+  });
+}
+
+function errorText(error) {
+  return [error?.message, error?.stderr?.toString?.(), error?.stdout?.toString?.()]
+    .filter(Boolean)
+    .join(' ')
+    .toLowerCase();
+}
+
+function isUnsupportedTokenCapability(error) {
+  const text = errorText(error);
+  return /unknown (?:flag|option)|invalid (?:flag|option)|unexpected argument|does not support/.test(text)
+    && /user|hostname/.test(text);
+}
+
+function safeCommandFailure(code, message) {
+  return new GithubContextError(code, message);
+}
+
+function safeGithubCommandFailure(error) {
+  const text = errorText(error);
+  const failure = safeCommandFailure(
+    'GITHUB_COMMAND_FAILED',
+    /rate limit|secondary rate/.test(text)
+      ? 'The GitHub CLI command was rate limited.'
+      : 'The GitHub CLI command failed without exposing its output.',
+  );
+  const matchedStatus = /\bhttp\s+(401|403|429)\b/.exec(text)?.[1];
+  let httpStatus;
+  if ([401, 403, 429].includes(error?.httpStatus)) httpStatus = error.httpStatus;
+  else if ([401, 403, 429].includes(error?.status)) httpStatus = error.status;
+  else httpStatus = Number(matchedStatus) || undefined;
+  const retryAfter = Number(error?.retryAfter);
+  if (httpStatus) failure.httpStatus = httpStatus;
+  if (Number.isFinite(retryAfter) && retryAfter > 0) failure.retryAfter = retryAfter;
+  return failure;
+}
+
+function gitConfig(projectRoot, args, options, absentIsOkay = false) {
+  try {
+    return runnerFor(options)('git', ['config', '--local', ...args], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (absentIsOkay && (error?.status === 1 || /key does not contain|not found|no such key/i.test(errorText(error)))) {
+      return '';
+    }
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to read this clone-local GitHub account binding.');
+  }
+}
+
+function readGithubAccount(projectRoot, options = {}) {
+  const output = gitConfig(projectRoot, ['--get', ACCOUNT_KEY], options, true);
+  const value = output == null ? '' : output.toString().trim();
+  return value || null;
+}
+
+function writeGithubAccount(projectRoot, login, options = {}) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  try {
+    runnerFor(options)('git', ['config', '--local', '--replace-all', ACCOUNT_KEY, login], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (_error) {
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to write the clone-local GitHub account binding.');
+  }
+}
+
+function unsetGithubAccount(projectRoot, options = {}) {
+  try {
+    runnerFor(options)('git', ['config', '--local', '--unset-all', ACCOUNT_KEY], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (error?.status === 5 || /key does not contain|not found|no such key/i.test(errorText(error))) return;
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to remove the clone-local GitHub account binding.');
+  }
+}
+
+function withoutGithubEnvironment(environment) {
+  const result = {};
+  for (const [key, value] of Object.entries(environment || {})) {
+    if (!GITHUB_ENV_NAMES.has(key.toLowerCase())) result[key] = value;
+  }
+  return result;
+}
+
+function selectedEnvironment(baseEnv, token, additions = {}) {
+  const result = withoutGithubEnvironment(baseEnv);
+  Object.assign(result, withoutGithubEnvironment(additions));
+  result.GH_TOKEN = token;
+  result.GITHUB_TOKEN = token;
+  result.GH_HOST = HOST;
+  return result;
+}
+
+function passthroughEnvironment(baseEnv, additions = {}) {
+  return { ...baseEnv, ...additions };
+}
+
+function retrieveGithubToken(login, options) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = options.baseEnv || options.env || process.env;
+  let output;
+  try {
+    output = runnerFor(options)('gh', ['auth', 'token', '--hostname', HOST, '--user', login], {
+      env: withoutGithubEnvironment(baseEnv),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+  } catch (error) {
+    if (isUnsupportedTokenCapability(error)) {
+      throw safeCommandFailure('GITHUB_CLI_UNSUPPORTED', 'Upgrade GitHub CLI, then authenticate the account with gh auth login.');
+    }
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+
+  const token = output == null ? '' : output.toString().trim();
+  if (!token) {
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'GitHub account is not authenticated; run gh auth login for this account.');
+  }
+  return token;
+}
+
+function loginFromOutput(output) {
+  const text = output == null ? '' : output.toString().trim();
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return safeLogin(parsed?.login);
+  } catch {
+    // `gh --jq` normally returns plain text; JSON is only a compatibility path.
+    return safeLogin(text.split(/\r?\n/, 1)[0].trim());
+  }
+}
+
+function resolveGithubLogin(token, baseEnv, options) {
+  try {
+    const output = runnerFor(options)('gh', ['api', '--hostname', HOST, 'user', '--jq', '.login'], {
+      env: selectedEnvironment(baseEnv, token),
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const login = loginFromOutput(output);
+    if (!login) throw new Error('missing login');
+    return login;
+  } catch {
+    // Provider errors may contain response bodies or credentials; expose only a safe diagnosis.
+    throw safeCommandFailure('GITHUB_AUTH_FAILED', 'Unable to verify the selected GitHub account; run gh auth login and try again.');
+  }
+}
+
+function prepareGithubAccount(_projectRoot, account, options = {}) {
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const token = retrieveGithubToken(account, { ...options, baseEnv });
+  const login = resolveGithubLogin(token, baseEnv, options);
+  if (login.toLowerCase() !== account.toLowerCase()) {
+    throw safeCommandFailure('GITHUB_ACCOUNT_MISMATCH', `GitHub account mismatch: expected ${account}, received ${login}.`);
+  }
+  return createPublicContext(publicStatus('ready', account, login), token, baseEnv, options);
+}
+
+function publicStatus(state, account, login) {
+  return Object.freeze({ state, account: account || null, login: login || null });
+}
+
+function createPublicContext(status, token, baseEnv, options) {
+  const context = {
+    status,
+    bound: status.state !== 'unbound',
+    account: status.account,
+    login: status.login,
+  };
+  const secrets = (status.state === 'unbound'
+    ? Object.entries(baseEnv)
+      .filter(([key]) => GITHUB_SECRET_ENV_NAMES.has(key.toLowerCase()))
+      .map(([, value]) => value)
+    : [token])
+    .filter((value) => typeof value === 'string' && value);
+  const environmentForChild = (additions = {}) => status.state === 'unbound'
+    ? passthroughEnvironment(baseEnv, additions)
+    : selectedEnvironment(baseEnv, token, additions);
+  const childRunner = options.childRunner || options._childRunner || runnerFor(options);
+  const runChild = (command, args, runOptions = {}) => {
+    if (typeof command !== 'string' || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      return childRunner(command, args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+      });
+    } catch (_error) {
+      throw safeCommandFailure('GITHUB_COMMAND_FAILED', 'The GitHub CLI command failed without exposing its output.');
+    }
+  };
+  const runGh = (args, runOptions = {}) => {
+    if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) {
+      throw safeCommandFailure('INVALID_GH_ARGUMENTS', 'GitHub CLI arguments must be an array of strings.');
+    }
+    try {
+      const output = runnerFor(options)('gh', args, {
+        ...runOptions,
+        env: environmentForChild(runOptions.env),
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+      });
+      return redactTokens(output, secrets);
+    } catch (error) {
+      throw safeGithubCommandFailure(error);
+    }
+  };
+  Object.defineProperties(context, {
+    runChild: { value: runChild, enumerable: false },
+    runGh: { value: runGh, enumerable: false },
+    getStatus: { value: () => ({ ...status }), enumerable: false },
+  });
+  return context;
+}
+
+function redactTokens(value, tokens) {
+  if (value == null) return value;
+  return tokens.slice().sort((left, right) => right.length - left.length)
+    .reduce((redacted, token) => redacted.split(token).join('[REDACTED]'), value.toString());
+}
+
+function createGithubContext(projectRoot, options = {}) {
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const account = readGithubAccount(projectRoot, options);
+  if (!account) return createPublicContext(publicStatus('unbound', null, null), null, baseEnv, options);
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'The clone-local github.account value is not a valid GitHub login.');
+  }
+  return prepareGithubAccount(projectRoot, account, { ...options, baseEnv });
+}
+
+module.exports = {
+  ACCOUNT_KEY,
+  GithubContextError,
+  createGithubContext,
+  prepareGithubAccount,
+  prepareGithubContext: createGithubContext,
+  readGithubAccount,
+  resolveGithubLogin,
+  unsetGithubAccount,
+  validateGithubLogin,
+  writeGithubAccount,
+};

package/lib/global-flags.js

@@ -37,6 +37,7 @@ const GLOBAL_BOOLEAN_FLAGS = new Set([
   '--verbose',
   '--dry-run',
   '--symlink',
+  '--skills-only', '--no-hooks',
   '--sync',
   '--interview',
 ]);

package/lib/harness-capability-matrix.js

@@ -13,7 +13,7 @@ const CAPABILITY_IDS = [
   'commands',
   'agents',
   'stages',
-  'beads',
+  'issueState',
   'typedMemory',
   'patchOverrides',
   'marketplaceTrust',
@@ -157,7 +157,7 @@ const CAPABILITY_ROWS = [
     ['codex', target('skill-first', '$CODEX_HOME/skills/<stage>/SKILL.md', { role: 'generated at setup from canonical skills/', evidence: ['S5'], knownIssue: 'Repo-local Codex discovery uses .agents/skills/<stage>/SKILL.md, the committed mirror (generated from skills/, kept in sync by a pre-commit hook + drift gate) (kernel issue 55dfeccf).' })],
     ['hermes', target('forge-owned', '.hermes/skills/<stage>/SKILL.md', { role: 'Forge-owned stage-skill projection consumed via forge orient/recap' })],
   ]),
-  row('beads', 'state-and-memory', 'issue and audit state authority', HARNESS_IDS.map(id => [id, target('forge-owned', 'forge CLI + bd adapter')])),
+  row('issueState', 'state-and-memory', 'issue and audit state authority', HARNESS_IDS.map(id => [id, target('forge-owned', 'forge CLI + Forge Kernel store')])),
   row('typedMemory', 'state-and-memory', 'typed memory projection', [
     ['claude', target('not-delivered', null, { knownIssue: 'Typed memory is WRITE-ONLY (insights.js); no generator projects a memory section into any Claude instruction/rule file. Tracked as kernel issue dce9da46 (epic 90f2f631).' })],
     ['cursor', target('not-delivered', null, { knownIssue: 'Typed memory is write-only; no memory-projection renderer emits a Cursor memory section. Tracked as kernel issue dce9da46 (epic 90f2f631).' })],
@@ -312,7 +312,7 @@ const RENDERER_FAMILIES = [
   ['commands', 'Forge command shim manifest', ['shim points to canonical skill', 'no duplicated stage body']],
   ['agents', 'Forge agent role spec', ['role mapping', 'parallelism or fallback policy']],
   ['stage-graph', 'Forge skills-first stage graph', ['super skill target', 'subskill target list', 'gate mapping']],
-  ['state-and-memory', 'Beads, typed memory, and patch override manifests', ['state authority', 'projection provenance', 'protected path policy']],
+  ['state-and-memory', 'Kernel issue state, typed memory, and patch override manifests', ['state authority', 'projection provenance', 'protected path policy']],
   ['distribution', 'Forge extension manifest and lock metadata', ['lock hash', 'trusted source', 'generated target inventory']],
   ['safety', 'Forge safety-surface manifest (permissions, ignore, sandbox)', ['permission scope (allow/deny/ask)', 'read/index ignore boundary', 'sandbox/approval policy or global-scope deferral note']],
 ];

package/lib/hook-renderer.js

@@ -33,14 +33,14 @@
  * the protected-path set, and delegates the TDD gate to the real `check-tdd.js`.
  *
  * Dependency-free (JSON only; no TOML lib) so it runs under `bun test` and the
- * release gates. Reuses the MCP renderer's `backupFile` for the data-loss guard.
+ * release gates.
  *
  * @module hook-renderer
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
-const { backupFile } = require('./mcp-config-renderer');
+const { assertNoAncestorSymlinkEscape, assertNoSymlinkEscape } = require('./protected-state-surfaces');
 
 const HARNESS_HOOK_FILES = {
   claude: '.claude/settings.json',
@@ -83,6 +83,7 @@ const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
 // The memory-recall context hook (UserPromptSubmit tier). Its own idempotency marker so a
 // re-render recognizes and REPLACES the Forge-owned entry in place rather than duplicating it.
 const FORGE_MEMORY_RECALL_MARKER = 'hooks memory-recall';
+const FORGE_READ_ATTENTION_MARKER = 'hooks read-attention';
 // The capture-on-exit context hook (PreCompact + Stop tier). A THIRD context marker so a
 // re-merge recognizes + replaces the Forge-owned PreCompact/Stop entries in place. Both
 // events share this one marker (they differ only by a --trigger suffix on the command).
@@ -134,6 +135,13 @@ const USER_PROMPT_SUBMIT_SUPPORT = Object.freeze({
   hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
 });
 
+const READ_ATTENTION_SUPPORT = Object.freeze({
+  claude: Object.freeze({ rendered: true }),
+  cursor: Object.freeze({ rendered: false, reason: 'no-read-context-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
+  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+});
+
 // Per-harness session-END (capture-on-exit) capability. Only Claude exposes native
 // PreCompact + Stop hook surfaces where Forge can snapshot session learnings BEFORE
 // context is compacted or the session ends. Cursor 1.7 hooks are deny-oriented with no
@@ -161,7 +169,7 @@ function adapterInvocation(harness) {
  * (per-commit) so the rendered Claude PreToolUse groups read write-guard first.
  */
 const FORGE_HOOK_CONTRACT = Object.freeze({
-  schemaVersion: '1.2.0',
+  schemaVersion: '1.3.0',
   kind: 'forge.hookContract',
   adapter: FORGE_HOOK_ADAPTER,
   intents: Object.freeze([
@@ -215,6 +223,14 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks memory-recall`,
     }),
+    Object.freeze({
+      id: 'read-attention',
+      kind: 'context',
+      cliAction: 'read-attention',
+      enforces: 'Read attention: on supported PreToolUse:Read surfaces, inject only memory explicitly scoped to the path being opened. Content is fenced as untrusted, capped, additive, fail-open, and never mutates authority.',
+      lifecycle: 'pre-tool-read',
+      command: `${FORGE_CLI} hooks read-attention`,
+    }),
     Object.freeze({
       id: 'shepherd-events',
       kind: 'context',
@@ -294,6 +310,10 @@ function userPromptSubmitCapability(harness) {
   return USER_PROMPT_SUBMIT_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
 }
 
+function readAttentionCapability(harness) {
+  return READ_ATTENTION_SUPPORT[harness] || { rendered: false, reason: 'unknown-harness' };
+}
+
 /**
  * Report the per-harness session-END (capture-on-exit) capability (the honest matrix for
  * the PreCompact + Stop capture tier).
@@ -321,6 +341,10 @@ function renderClaudeHooks(contract) {
         matcher: 'Bash',
         hooks: [{ type: 'command', command: harnessCommand(contract, 'tdd-gate', 'claude') }],
       },
+      {
+        matcher: 'Read',
+        hooks: [{ type: 'command', command: harnessCommand(contract, 'read-attention', 'claude') }],
+      },
     ],
     // SessionStart context injection (memory push). No matcher → applies to every
     // session source; the command emits { hookSpecificOutput.additionalContext }.
@@ -438,6 +462,7 @@ function isForgeCommand(command) {
       || command.includes(FORGE_INBOX_CONTEXT_MARKER)
       || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
       || command.includes(FORGE_MEMORY_RECALL_MARKER)
+      || command.includes(FORGE_READ_ATTENTION_MARKER)
       || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
@@ -447,10 +472,30 @@ function isForgeClaudeGroup(group) {
   return hooks.some(h => isForgeCommand(h?.command));
 }
 
+function withoutForgeCommands(group) {
+  const hooks = Array.isArray(group?.hooks) ? group.hooks : [];
+  const userHooks = hooks.filter(hook => !isForgeCommand(hook?.command));
+  if (userHooks.length === hooks.length) return group;
+  if (userHooks.length === 0) return null;
+  return { ...group, hooks: userHooks };
+}
+
 function isForgeCursorEntry(entry) {
   return isForgeCommand(entry?.command);
 }
 
+function groupContains(actual, expected) {
+  if ((actual?.matcher || '') !== (expected?.matcher || '')) return false;
+  const actualHooks = Array.isArray(actual?.hooks) ? actual.hooks : [];
+  const expectedHooks = Array.isArray(expected?.hooks) ? expected.hooks : [];
+  const forgeHooks = actualHooks.filter(hook => isForgeCommand(hook?.command));
+  return forgeHooks.length === expectedHooks.length
+    && expectedHooks.every(expectedHook =>
+      forgeHooks.filter(actualHook =>
+        actualHook?.type === expectedHook?.type
+        && actualHook?.command === expectedHook?.command).length === 1);
+}
+
 function parseJsonConfig(existingText) {
   if (!existingText || !existingText.trim()) return {};
   let obj;
@@ -479,12 +524,55 @@ function mergeClaudeSettings(existingText, contract) {
   const rendered = renderClaudeHooks(contract);
   for (const [event, forgeGroups] of Object.entries(rendered)) {
     const existingGroups = Array.isArray(obj.hooks[event]) ? obj.hooks[event] : [];
-    const userGroups = existingGroups.filter(group => !isForgeClaudeGroup(group));
+    const userGroups = existingGroups.map(withoutForgeCommands).filter(Boolean);
     obj.hooks[event] = [...userGroups, ...forgeGroups];
   }
   return JSON.stringify(obj, null, 2) + '\n';
 }
 
+function hasForgeClaudeHooks(existingText, contract) {
+  const obj = parseJsonConfig(existingText);
+  const hooks = obj.hooks && typeof obj.hooks === 'object' && !Array.isArray(obj.hooks)
+    ? obj.hooks
+    : {};
+  return Object.entries(renderClaudeHooks(contract)).every(([event, expectedGroups]) => {
+    const actualGroups = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const forgeGroups = actualGroups.filter(isForgeClaudeGroup);
+    return forgeGroups.length === expectedGroups.length
+      && expectedGroups.every(expected =>
+        forgeGroups.filter(actual => groupContains(actual, expected)).length === 1);
+  });
+}
+
+function backupHookConfig(filePath) {
+  const source = fs.readFileSync(filePath);
+  const sourceStat = fs.statSync(filePath);
+  for (let suffix = 0; ; suffix += 1) {
+    const candidate = `${filePath}.bak${suffix ? `.${suffix}` : ''}`;
+    let candidateStat;
+    try {
+      candidateStat = fs.lstatSync(candidate);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      try {
+        fs.copyFileSync(filePath, candidate, fs.constants.COPYFILE_EXCL);
+        return candidate;
+      } catch (copyError) {
+        if (copyError.code === 'EEXIST') continue;
+        throw copyError;
+      }
+    }
+    if (candidateStat.isSymbolicLink()) continue;
+    if (sourceStat.dev != null && sourceStat.ino != null
+      && sourceStat.dev === candidateStat.dev && sourceStat.ino === candidateStat.ino) continue;
+    try {
+      if (source.equals(fs.readFileSync(candidate))) return candidate;
+    } catch {
+      // An unreadable backup cannot prove the source is already safe.
+    }
+  }
+}
+
 /**
  * Merge Forge's hooks into an existing `.cursor/hooks.json` string.
  * Forces `version: 1`, preserves all non-Forge events and the user's own entries;
@@ -511,6 +599,26 @@ const MERGERS = {
   cursor: mergeCursorHooks,
 };
 
+function assertSafeHookConfigPath(targetRoot, filePath) {
+  const escape =
+    assertNoAncestorSymlinkEscape(targetRoot, filePath) ||
+    assertNoSymlinkEscape(targetRoot, filePath);
+  if (escape) throw new Error(`Refusing to render hook config: ${escape.reason}`);
+  if (hasMultipleHardLinks(filePath)) {
+    throw new Error('Refusing to render hardlinked hook config');
+  }
+}
+
+function hasMultipleHardLinks(filePath) {
+  try {
+    const stat = fs.lstatSync(filePath);
+    return stat.isFile() && stat.nlink > 1;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
 /**
  * Render (merge) Forge's native hooks into one harness's native config on disk.
  * Read → merge → write. Unparseable existing file → BACKED UP + left untouched
@@ -537,7 +645,9 @@ function renderHookConfig({ harness, targetRoot, contract = FORGE_HOOK_CONTRACT
   if (!merge || !rel) throw new Error(`Unknown hook harness: ${harness}`);
 
   const filePath = path.join(targetRoot, rel);
+  assertSafeHookConfigPath(targetRoot, filePath);
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  assertSafeHookConfigPath(targetRoot, filePath);
   const existed = fs.existsSync(filePath);
   const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
 
@@ -546,12 +656,14 @@ function renderHookConfig({ harness, targetRoot, contract = FORGE_HOOK_CONTRACT
     merged = merge(existing, contract);
   } catch (err) {
     if (err instanceof HookConfigParseError && existed) {
-      const backup = backupFile(filePath);
+      assertSafeHookConfigPath(targetRoot, filePath);
+      const backup = backupHookConfig(filePath);
       return { file: filePath, existed, skipped: true, wrote: false, backup };
     }
     throw err;
   }
 
+  assertSafeHookConfigPath(targetRoot, filePath);
   fs.writeFileSync(filePath, merged, 'utf-8');
   return { file: filePath, existed, skipped: false, wrote: true };
 }
@@ -564,13 +676,16 @@ module.exports = {
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
   FORGE_MEMORY_RECALL_MARKER,
+  FORGE_READ_ATTENTION_MARKER,
   FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
   BOOTSTRAP_DELIVERY,
   USER_PROMPT_SUBMIT_SUPPORT,
+  READ_ATTENTION_SUPPORT,
   SESSION_END_SUPPORT,
   sessionStartCapability,
   userPromptSubmitCapability,
+  readAttentionCapability,
   sessionEndCapability,
   HookConfigParseError,
   renderClaudeHooks,
@@ -578,6 +693,8 @@ module.exports = {
   renderCodexHooksToml,
   renderHermesHooksYaml,
   mergeClaudeSettings,
+  hasForgeClaudeHooks,
+  hasMultipleHardLinks,
   mergeCursorHooks,
   renderHookConfig,
 };