peaks-cli 1.3.2 → 1.3.4

package/dist/src/cli/commands/sub-agent-dispatch-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `peaks sub-agent-dispatch-guard` — G9.5 / RL-30 strict hook-only atom.
+ *
+ * This is the **second-layer** gate (PreToolUse hook) for the G9 forced
+ * compression threshold. It re-validates the prompt size against the
+ * threshold table in `src/services/context/threshold.ts` and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * **NO `--force` flag is exposed at this layer** (RL-30 strict). The
+ * hook is the strictest layer in the G9 chain. If the CLI is bypassed
+ * (e.g. a user manually invokes the dispatch CLI with `--force` to
+ * override the 80% threshold), the hook catches it and returns
+ * `{allow: false}` regardless.
+ *
+ * This atom is **hidden from `peaks --help`** per dev-preference
+ * "skill-first / CLI-auxiliary" + PB-2 byte-stable. It is registered
+ * via the LLM platform's PreToolUse hook chain (e.g. Claude Code's
+ * `settings.json` `PreToolUse` array) and is not a user-facing command.
+ *
+ * The `peaks hooks install` command reads `IdeAdapter.promptSizeAware`
+ * to decide whether to register this hook for a given IDE.
+ */
+import { Command } from 'commander';
+import { type ContextGuardDecision } from '../../services/context/context-guard.js';
+export declare const HOOK_GUARD_RESULT_TYPE: "peaks-hook-guard/v1";
+export interface HookGuardResult {
+    readonly schema: typeof HOOK_GUARD_RESULT_TYPE;
+    readonly allow: boolean;
+    readonly code: ContextGuardDecision['code'];
+    readonly reason: string;
+    readonly suggest: string | null;
+    readonly tier: ContextGuardDecision['evaluation']['tier'];
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export declare function evaluateHookGuard(promptSize: number): HookGuardResult;
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export declare function registerSubAgentDispatchGuard(program: Command): void;

package/dist/src/cli/commands/sub-agent-dispatch-guard.js

@@ -0,0 +1,57 @@
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+export const HOOK_GUARD_RESULT_TYPE = 'peaks-hook-guard/v1';
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export function evaluateHookGuard(promptSize) {
+    // Intentionally pass `force: false` always. The hook layer is strict.
+    const decision = evaluatePromptSize(promptSize, { force: false });
+    return {
+        schema: HOOK_GUARD_RESULT_TYPE,
+        allow: decision.allow,
+        code: decision.code,
+        reason: decision.allow
+            ? `prompt size ${promptSize} bytes within threshold (tier=${decision.evaluation.tier})`
+            : `prompt size ${promptSize} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`,
+        suggest: decision.suggest,
+        tier: decision.evaluation.tier,
+        ratio: decision.evaluation.ratio,
+        bytesUsed: decision.evaluation.bytesUsed,
+        capacityBytes: decision.evaluation.capacityBytes,
+        warnings: decision.warnings
+    };
+}
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export function registerSubAgentDispatchGuard(program) {
+    program
+        .command('sub-agent-dispatch-guard')
+        .description('INTERNAL: PreToolUse hook guard (G9.5 / RL-30 strict)')
+        .requiredOption('--prompt <text>', 'the prompt to validate (size in bytes is what gets checked)')
+        .option('--prompt-length <bytes>', 'DOGFOOD ONLY: synthesize a prompt of this size (overrides --prompt content for size only)')
+        .action((options) => {
+        let prompt = options.prompt;
+        if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+            const len = Number.parseInt(options.promptLength, 10);
+            if (Number.isInteger(len) && len > 0) {
+                prompt = 'x'.repeat(len);
+            }
+        }
+        const promptSize = Buffer.byteLength(prompt, 'utf8');
+        const result = evaluateHookGuard(promptSize);
+        // Always exit 0 — the LLM platform reads `allow` from JSON.
+        // The decision is encoded in `allow` / `code`, not the exit code.
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    });
+}

package/dist/src/cli/commands/workflow-commands.js

@@ -10,6 +10,7 @@ import { validateChangeIdOrThrow } from '../../shared/change-id.js';
 import { getEconomyAwareExecutionModelId } from '../../services/config/model-routing.js';
 import { getLocalArtifactPath } from '../../services/artifacts/workspace-service.js';
 import { getSessionId } from '../../services/session/session-manager.js';
+import { getSessionDir } from '../../services/session/getSessionDir.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { verifyPipeline } from '../../services/workflow/pipeline-verify-service.js';
 import { fail, ok } from '../../shared/result.js';
@@ -18,7 +19,7 @@ function getCurrentWorkspaceContext() {
     try {
         const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
         const sessionId = getSessionId(projectRoot);
-        return sessionId ? { sessionId, sessionDir: `.peaks/${sessionId}` } : {};
+        return sessionId ? { sessionId, sessionDir: getSessionDir(projectRoot, sessionId) } : {};
     }
     catch {
         return {};

package/dist/src/cli/commands/workspace-commands.js

@@ -264,6 +264,9 @@ export function registerWorkspaceCommands(program, io) {
             if (result.systemCleaned.length > 0) {
                 nextActions.push(`Removed ${result.systemCleaned.length} F3 system/ subdir(s).`);
             }
+            if (result.subAgentStateMigrated > 0) {
+                nextActions.push(`Migrated ${result.subAgentStateMigrated} legacy sub-agent state file(s) into .peaks/_sub_agents/.`);
+            }
             printResult(io, ok('workspace.reconcile', result, warnings, nextActions), options.json);
             if (result.errors.length > 0) {
                 process.exitCode = 1;

package/dist/src/cli/program.js

@@ -17,7 +17,10 @@ import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
 import { registerSliceCommands } from './commands/slice-commands.js';
 import { registerSopCommands } from './commands/sop-commands.js';
+import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
+import { registerSubAgentDispatchGuard } from './commands/sub-agent-dispatch-guard.js';
 import { registerGateCommands } from './commands/gate-commands.js';
+import { registerHookHandleCommand } from './commands/hook-handle.js';
 import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
@@ -92,7 +95,13 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerShadcnCommands(program, io);
     registerSliceCommands(program, io);
     registerSopCommands(program, io);
+    registerSubAgentCommands(program, io);
+    // Slice #010 G9.5: register the hook-only internal atom. Hidden from
+    // `peaks --help` (no description text); used by `peaks hooks install`
+    // to wire the PreToolUse hook chain.
+    registerSubAgentDispatchGuard(program);
     registerGateCommands(program, io);
+    registerHookHandleCommand(program, io);
     registerHooksCommands(program, io);
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);

package/dist/src/hooks/pre-tool-use-sub-agent.d.ts

@@ -0,0 +1,28 @@
+import { type HookGuardResult } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export declare function readPromptSizeFromHookStdin(stdin: unknown): number;
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export declare function runHookGuardSubprocess(prompt: string): HookGuardResult;
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export declare function runHookGuard(stdin: unknown): HookGuardResult;

package/dist/src/hooks/pre-tool-use-sub-agent.js

@@ -0,0 +1,105 @@
+/**
+ * G9.5 PreToolUse hook execution body.
+ *
+ * Wraps `peaks sub-agent-dispatch-guard` for LLM platform integration.
+ * The hook reads the prompt size from the LLM platform's hook stdin
+ * (Claude Code / Trae / etc.), invokes the guard CLI, and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * The hook is registered via `peaks hooks install` in the LLM
+ * platform's `settings.json` `PreToolUse` array. Only IDEs with
+ * `IdeAdapter.promptSizeAware: true` get the hook installed.
+ *
+ * The hook layer is the **strictest** layer in the G9 chain (RL-30).
+ * The CLI 兜底 layer (`peaks sub-agent dispatch --force`) can override
+ * the 80% threshold; the hook layer CANNOT.
+ */
+import { spawnSync } from 'node:child_process';
+import { evaluateHookGuard } from '../cli/commands/sub-agent-dispatch-guard.js';
+/**
+ * Read the prompt size from the LLM platform's hook stdin. Different
+ * LLMs send different payload shapes; we accept the most common:
+ *   - Claude Code: `{"tool_name": "Bash", "tool_input": {"command": "..."}}`
+ *   - Trae: `{"tool_name": "terminal", "tool_input": {"command": "..."}}`
+ *
+ * The hook reads the `command` (or `prompt`) field and computes the
+ * byte length. If neither field is present, returns 0 (always passes).
+ */
+export function readPromptSizeFromHookStdin(stdin) {
+    if (stdin === null || typeof stdin !== 'object') {
+        return 0;
+    }
+    const obj = stdin;
+    const toolInput = obj.tool_input;
+    if (toolInput === null || typeof toolInput !== 'object') {
+        return 0;
+    }
+    const ti = toolInput;
+    const candidates = ['command', 'prompt', 'text', 'input'];
+    for (const key of candidates) {
+        const v = ti[key];
+        if (typeof v === 'string') {
+            return Buffer.byteLength(v, 'utf8');
+        }
+    }
+    return 0;
+}
+/**
+ * Execute the hook guard via spawnSync. Returns the parsed result or
+ * a fallback (allow: true) on subprocess failure.
+ *
+ * Prefer the in-process `evaluateHookGuard` (no subprocess) when the
+ * hook is called from a TypeScript context. Use `runHookGuardSubprocess`
+ * only when the hook needs to be invoked from a non-TypeScript caller
+ * (e.g. a shell script that wraps the peaks CLI).
+ */
+export function runHookGuardSubprocess(prompt) {
+    const result = spawnSync('node', [
+        process.argv[1] ?? 'peaks',
+        'sub-agent-dispatch-guard',
+        '--prompt', prompt,
+        '--json'
+    ], { encoding: 'utf8' });
+    if (result.status !== 0) {
+        // Fallback: allow (don't block the dispatch on a guard subprocess failure).
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: `guard subprocess failed (status ${result.status}); falling through`,
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_FAILED']
+        };
+    }
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch {
+        return {
+            schema: 'peaks-hook-guard/v1',
+            allow: true,
+            code: 'OK',
+            reason: 'guard subprocess produced unparseable JSON; falling through',
+            suggest: null,
+            tier: 'ok',
+            ratio: 0,
+            bytesUsed: 0,
+            capacityBytes: 0,
+            warnings: ['HOOK_GUARD_SUBPROCESS_INVALID_JSON']
+        };
+    }
+}
+/**
+ * Main entry point for the hook. Reads the LLM platform's stdin,
+ * computes the prompt size, and returns the guard result. Used by
+ * the LLM platform's hook JSON to decide whether to allow the tool
+ * call.
+ */
+export function runHookGuard(stdin) {
+    const promptSize = readPromptSizeFromHookStdin(stdin);
+    return evaluateHookGuard(promptSize);
+}

package/dist/src/services/config/config-types.d.ts

@@ -61,7 +61,7 @@ export type PeaksConfig = {
     /**
      * Sub-agent progress surfacing knobs. The `peaks progress watch`
      * CLI (intended to be run in a separate terminal tab while the
-     * LLM is working) reads `.peaks/<sid>/system/subagent-progress.json`
+     * LLM is working) reads `.peaks/_sub_agents/<sid>/subagent-progress.json`
      * and renders elapsed / spinner / sub-step in real time. The
      * `enabled` flag is a kill-switch for users who find the watch
      * distracting; the `heartbeatIntervalMs` lets power users tune

package/dist/src/services/context/artifact-meta.d.ts

@@ -0,0 +1,72 @@
+export type ArtifactStatus = 'created' | 'finalized' | 'partial' | 'failed';
+export interface ArtifactMeta {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+    readonly status: ArtifactStatus;
+    /** Mandatory literal `false`. The type system rejects `true`. */
+    readonly contentInlined: false;
+    /** 1-2 sentence description, ≤ 200 chars. Allowed in main context. */
+    readonly summary: string | null;
+    /** ISO8601. */
+    readonly writtenAt: string;
+    /** Request id this artifact belongs to. */
+    readonly rid: string;
+    /** Sub-agent role string. */
+    readonly role: string;
+    /** Sequence number when same role is dispatched multiple times. */
+    readonly idx: number;
+}
+export interface ContextImpact {
+    readonly promptSize: number;
+    readonly artifactSizes: readonly number[];
+    readonly batchTotalSize: number;
+    /** `high` if `batchTotalSize > 4MB` OR any `artifactSize > 1MB`. */
+    readonly contextWarning: 'normal' | 'high' | 'critical';
+}
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export declare function computeSha256(filePath: string): string;
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export declare function buildArtifactMeta(opts: {
+    path: string;
+    rid: string;
+    role: string;
+    idx: number;
+    summary: string | null;
+    status?: ArtifactStatus;
+    /** Override sha256 / size (e.g. when caller already computed them). */
+    precomputed?: {
+        size: number;
+        sha256: string;
+    };
+    /** Override the writtenAt timestamp. */
+    writtenAt?: string;
+}): ArtifactMeta;
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export declare function buildContextImpact(opts: {
+    promptSize: number;
+    artifactSizes: readonly number[];
+}): ContextImpact;
+export declare const ARTIFACT_LIMITS: {
+    readonly ARTIFACT_MAX_SIZE_BYTES: number;
+    readonly BATCH_TOTAL_HIGH_BYTES: number;
+    readonly ARTIFACT_SUMMARY_MAX_CHARS: 200;
+};

package/dist/src/services/context/artifact-meta.js

@@ -0,0 +1,105 @@
+/**
+ * G7 — sub-agent context minimal-occupation (RL-17..RL-22, AC-38..AC-43).
+ *
+ * `ArtifactMeta` is what the dispatch record stores per sub-agent artifact
+ * instead of the full content. The `contentInlined: false` literal is the
+ * API contract: the type system rejects `true`, so main LLM context can
+ * never accidentally be flooded with inlined artifact bodies.
+ *
+ * The artifact's content lives on disk at `path`; the meta is ~200 chars
+ * (path + size + sha256 + status + summary), so 3 sub-agents × ~200 chars
+ * = ~600 chars net context increase per batch instead of 3MB+.
+ *
+ * Path convention (G7.4.c):
+ *   `.peaks/_sub_agents/<sid>/artifacts/<rid>-<role>-<idx>.<ext>`
+ *
+ * See: `.peaks/memory/sub-agent-context-minimal-occupation.md` for the
+ * full G7 rule.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+const ARTIFACT_MAX_SIZE_BYTES = 1024 * 1024; // 1MB
+const BATCH_TOTAL_HIGH_BYTES = 4 * 1024 * 1024; // 4MB
+/**
+ * Compute the sha256 hex digest of a file. Throws if the file does not
+ * exist or is not readable. Caller is expected to handle ENOENT as
+ * `code: 'ARTIFACT_NOT_FOUND'` and treat 0-byte files as `status: 'failed'`.
+ */
+export function computeSha256(filePath) {
+    const content = readFileSync(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Build an `ArtifactMeta` from on-disk file. Computes size + sha256.
+ *
+ * `status` semantics:
+ *   - `'created'`   — file exists, non-empty, sha256 succeeded
+ *   - `'failed'`    — file is 0 bytes (R-2 / G7.4.e: do not silently succeed)
+ *   - `'partial'`   — caller-provided (e.g. sub-agent reports unfinished work)
+ *   - `'finalized'` — caller-provided (e.g. sub-agent reports complete)
+ */
+export function buildArtifactMeta(opts) {
+    let size;
+    let sha256;
+    let status = opts.status ?? 'created';
+    if (opts.precomputed) {
+        size = opts.precomputed.size;
+        sha256 = opts.precomputed.sha256;
+    }
+    else {
+        const stat = statSync(opts.path);
+        size = stat.size;
+        if (size === 0) {
+            // 0-byte artifact: cannot compute meaningful sha256; mark as failed.
+            sha256 = '0'.repeat(64);
+            status = 'failed';
+        }
+        else {
+            sha256 = computeSha256(opts.path);
+        }
+    }
+    const summary = opts.summary;
+    if (summary !== null && summary.length > 200) {
+        throw new Error(`ArtifactMeta summary must be ≤ 200 chars (got ${summary.length})`);
+    }
+    return {
+        path: opts.path,
+        size,
+        sha256,
+        status,
+        contentInlined: false,
+        summary,
+        writtenAt: opts.writtenAt ?? new Date().toISOString(),
+        rid: opts.rid,
+        role: opts.role,
+        idx: opts.idx
+    };
+}
+/**
+ * Build a `ContextImpact` from a prompt size + artifact sizes.
+ * Computes `contextWarning` per the G7.3 rule:
+ *   - `'critical'` if any artifact > ARTIFACT_MAX_SIZE_BYTES
+ *   - `'high'`     if total > BATCH_TOTAL_HIGH_BYTES (4MB)
+ *   - `'normal'`   otherwise
+ */
+export function buildContextImpact(opts) {
+    const batchTotalSize = opts.promptSize + opts.artifactSizes.reduce((a, b) => a + b, 0);
+    let contextWarning = 'normal';
+    if (opts.artifactSizes.some((s) => s > ARTIFACT_MAX_SIZE_BYTES)) {
+        contextWarning = 'critical';
+    }
+    else if (batchTotalSize > BATCH_TOTAL_HIGH_BYTES) {
+        contextWarning = 'high';
+    }
+    return {
+        promptSize: opts.promptSize,
+        artifactSizes: opts.artifactSizes,
+        batchTotalSize,
+        contextWarning
+    };
+}
+export const ARTIFACT_LIMITS = {
+    ARTIFACT_MAX_SIZE_BYTES,
+    BATCH_TOTAL_HIGH_BYTES,
+    ARTIFACT_SUMMARY_MAX_CHARS: 200
+};

package/dist/src/services/context/context-guard.d.ts

@@ -0,0 +1,49 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { tierToCode, type ThresholdEvaluation } from './threshold.js';
+export type ContextGuardCode = 'OK' | 'CONTEXT_SOFT_WARN' | 'CONTEXT_NEAR_LIMIT' | 'PROMPT_TOO_LARGE' | 'PROMPT_EMERGENCY' | 'FORCED_OVER_THRESHOLD';
+export interface ContextGuardDecision {
+    readonly allow: boolean;
+    readonly code: ContextGuardCode;
+    readonly warnings: readonly string[];
+    readonly suggest: string | null;
+    readonly evaluation: ThresholdEvaluation;
+    /** ISO8601 timestamp when --force override was applied. null otherwise. */
+    readonly forcedAt: string | null;
+}
+export interface ContextGuardOptions {
+    /** Pass `true` to allow override at the ≥ 80% tier. CLI-only; hook layer MUST NOT set this. */
+    readonly force?: boolean;
+    /** Override the default 256K context capacity (e.g. for tests). */
+    readonly capacityBytes?: number;
+}
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export declare function evaluatePromptSize(promptSize: number, opts?: ContextGuardOptions): ContextGuardDecision;
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/src/services/context/context-guard.js

@@ -0,0 +1,91 @@
+/**
+ * G9 — forced compression gate (RL-27..RL-32).
+ *
+ * The CLI 兜底 layer. Validates prompt size against the threshold
+ * table in `threshold.ts` and returns a decision. The PreToolUse hook
+ * layer (`peaks sub-agent-dispatch-guard`) re-runs the same logic
+ * without `--force` (RL-30 strict).
+ *
+ * Decision codes:
+ *   - `OK`                          — under 50%
+ *   - `CONTEXT_SOFT_WARN`           — 50-75%, suggest --use-headroom
+ *   - `CONTEXT_NEAR_LIMIT`          — 75-80%, mandatory --use-headroom suggestion
+ *   - `PROMPT_TOO_LARGE`            — 80-90%, hard reject (allow = false)
+ *   - `PROMPT_EMERGENCY`            — ≥ 90%, hard reject + emergency
+ *   - `FORCED_OVER_THRESHOLD`       — user passed --force at CLI; allow = true
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`.
+ */
+import { CONTEXT_CAPACITY_DEFAULT_BYTES, evaluateThresholdTier, tierToCode } from './threshold.js';
+const NEAR_LIMIT_SUGGEST = 'Consider --use-headroom to compress prompt.';
+const SOFT_WARN_SUGGEST = 'Use --use-headroom to compress prompt proactively.';
+const HARD_REJECT_SUGGEST = 'Trim prompt to < 80% of context capacity. Pass --force at CLI to override (NOT allowed at hook layer).';
+const EMERGENCY_SUGGEST = 'Prompt exceeds 90% of context. Trim aggressively or split into multiple dispatches.';
+/**
+ * Evaluate a prompt size against the G9.3 threshold table.
+ *
+ * The `force` option is the **only** path that lets a ≥ 80% prompt
+ * through. The hook layer (PreToolUse) MUST NOT accept this option;
+ * it is enforced by the `peaks sub-agent-dispatch-guard` atom's
+ * command-line parser, which does not declare a `--force` flag.
+ */
+export function evaluatePromptSize(promptSize, opts = {}) {
+    const capacity = opts.capacityBytes ?? CONTEXT_CAPACITY_DEFAULT_BYTES;
+    const evaluation = evaluateThresholdTier(promptSize, capacity);
+    const tier = evaluation.tier;
+    let allow;
+    let code;
+    let suggest;
+    let forcedAt = null;
+    switch (tier) {
+        case 'ok':
+            allow = true;
+            code = 'OK';
+            suggest = null;
+            break;
+        case 'soft-warn':
+            allow = true;
+            code = 'CONTEXT_SOFT_WARN';
+            suggest = SOFT_WARN_SUGGEST;
+            break;
+        case 'near-limit':
+            allow = true;
+            code = 'CONTEXT_NEAR_LIMIT';
+            suggest = NEAR_LIMIT_SUGGEST;
+            break;
+        case 'hard-reject':
+            allow = false;
+            code = 'PROMPT_TOO_LARGE';
+            suggest = HARD_REJECT_SUGGEST;
+            break;
+        case 'emergency':
+            allow = false;
+            code = 'PROMPT_EMERGENCY';
+            suggest = EMERGENCY_SUGGEST;
+            break;
+    }
+    // --force override (CLI only; hook layer never reaches this branch)
+    if (!allow && opts.force === true) {
+        allow = true;
+        code = 'FORCED_OVER_THRESHOLD';
+        suggest = 'Override applied at CLI. Hook layer will still reject.';
+        forcedAt = new Date().toISOString();
+    }
+    const warnings = [...evaluation.warnings];
+    if (forcedAt !== null && !warnings.includes('FORCED_OVER_THRESHOLD')) {
+        warnings.push('FORCED_OVER_THRESHOLD');
+    }
+    return {
+        allow,
+        code,
+        warnings,
+        suggest,
+        evaluation,
+        forcedAt
+    };
+}
+/**
+ * Re-export of `tierToCode` for callers that want a stable mapping
+ * without depending on the threshold module directly.
+ */
+export { tierToCode };

package/dist/src/services/context/dispatch-context-guard.d.ts

@@ -0,0 +1,27 @@
+/** Build the canonical artifact path for a given session/rid/role/idx/ext. */
+export declare function artifactPath(projectRoot: string, sid: string, rid: string, role: string, idx: number, ext?: string): string;
+/** Build the canonical shared channel path. */
+export declare function sharedChannelPath(projectRoot: string, sid: string, rid: string, batchId: string): string;
+/**
+ * Assert that `artifactPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/artifacts/`. Rejects
+ * symlink/junction escapes and `..` segments.
+ *
+ * Throws an Error with `.code = 'INVALID_ARTIFACT_PATH'` on rejection.
+ */
+export declare function assertSafeArtifactPath(artifactPathInput: string, projectRoot: string): string;
+/**
+ * Assert that `channelPath` lives under
+ * `projectRoot/.peaks/_sub_agents/<sid>/shared/`. Same R-2 logic as
+ * `assertSafeArtifactPath` but with a different canonical subdir.
+ *
+ * Throws an Error with `.code = 'INVALID_SHARED_CHANNEL_PATH'` on rejection.
+ */
+export declare function assertSafeSharedChannelPath(channelPathInput: string, projectRoot: string): string;
+/**
+ * Soft-warn check on the artifact file name pattern. Returns null if
+ * the name matches `<rid>-<role>-<idx>.<ext>`, otherwise returns a
+ * warning string. Does NOT reject (the path is still in the canonical
+ * dir; the warning is for human/audit readability per G7.4.c).
+ */
+export declare function checkArtifactNameConvention(artifactPathInput: string): string | null;