Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(context): integrate generation-bound advisory suggestions (#3453)

haelyra810e5c0176cf
diff --cc docs/design/context-profile-delivery.tdd.md
index 571bd2a75,7370e07e9..e1c95b8ff
--- a/docs/design/context-profile-delivery.tdd.md
+++ b/docs/design/context-profile-delivery.tdd.md
@@@ -97,15 -97,29 +97,40 @@@ The 77-prompt routing corpus from #294
- Corpus result: zero loads outside the expected set; 19 implicit admissions become 17. The other dropped admission, `skill:cost-tracking`, now defers to the bounded proposal instead of loading.
- The existing nine-query auto/agent corpus, fallback, launch, evaluation and retrieval suites pass unchanged.
+## Isolated Claude native generations
+
+Session-only Claude discovery adapts the ownership and receipt intent of #2788 to the existing native store; it never writes a marketplace or user settings.
+
+- RED: 22 cases fail before the provider adapter (preview, prepare, version gate, nine discovery corruptions, details mismatch, static integrity, runtime-state tolerance, provider-home roots, Codex-to-Claude staleness, task launch and interactive start).
+- GREEN: all 22 pass. Codex native (39), interactive (8), launch (12), auto launch (5), evaluation (31), store (31) and profile CLI suites pass unchanged; Codex receipts keep their shape, and evaluator Claude launches without a plugin directory keep their arguments and environment.
+- Credential-free real run on Linux x64 with Claude Code 2.1.292 and the actual registry: Lean prepared ready with three skills and a 398-token always-on projection; Full prepared ready with 293 skills and 35,658 tokens; Full excluding `skill:python-patterns` verified 292 skills without it at 35,561 tokens. Switching profiles reported `stale`, and native rollback restored the Lean generation. `run --dry-run` resolved the pinned binary with `--plugin-dir`; `start --dry-run` proposed the Claude generation.
+- Claude Code auto-updated to 2.1.293 during review, and the exact 2.1.292 pin rejected it. RED: tests for later 2.1 patches fail. GREEN admits 2.1.292 and later 2.1 patches while rejecting 2.1.291, 2.2.0, prereleases and malformed output. A real 2.1.293 run prepared Lean ready at the same 398-token projection; preparation took 2.4 s (provider calls 1.2 s), an unchanged re-preparation 0.9 s and status 11 ms.
+- No authenticated model call, interactive turn or native skill invocation ran. The projection is the host's estimate for the plugin listing, not whole-context truth.
+- Maintainer credential-free macOS arm64 check, October 10: Claude Code 2.1.296 prepared Lean with three skills (~289 listing tokens), Full with the then-current 302 skills (~25,982 listing tokens), reported stale after each managed profile switch, and restored Lean through managed and native rollback. These are observed plugin-listing projections for that snapshot, not whole-context measurements.
+
+ ## Prompt suggestions
+
+ The suggest-only prompt hook from #2945 now reads a generation-bound metadata index instead of its own catalog cache.
+
+ - RED: routing-index and hook cases fail before the modules exist. GREEN adds a stored-vector key to the entry shape, a stale-source refusal and the session-start builder; all 16 cases pass, with a retrieval case proving stored vectors rank identically to computed ones.
+ - The resolver path took 300 to 500 ms per prompt from a source checkout, almost all in rehashing 293 skills and 584 files. Loading Ajv lazily and storing vectors moved the hook's own work to about 95 to 110 ms on a Full Claude index (276 entries, 1.8 MB); wrapper invocations measured 140 to 180 ms against a 71 ms disabled baseline on Linux x64.
+ - RED: on the full registry the function-word prompt still produced three unanchored suggestions. GREEN applies the routing policy v5 anchor to suggestions; the prompt now yields none and a React keyboard-focus prompt still leads with `skill:frontend-a11y`.
+ - Stored vectors moved from JSON pairs to little-endian base64 (RED: format test fails; GREEN: exact decode). The Full index shrank from 1.8 MB to 0.97 MB, its parse from 26 ms to 6 ms, and hook work to about 89 to 98 ms; wrapper invocations measured 149 to 190 ms against a 61 ms disabled baseline. The resolver's two registry reads are left intact as its source-consistency check.
+ - Selection, retrieval, profile CLI and hook-wrapper suites pass unchanged.
+ - No interactive Claude or Codex session loaded the hook; suggestion quality is bounded by the resolver ranking measured above.
+
+ Review follow-up, October 8:
+
+ - RED (15 index, hook and selection cases fail): a rollback to an indexed generation threw instead of reporting the index missing; digest-consistent entries with a non-string ID, name, description, owner or trigger, or a non-skill ID, were accepted; an oversized index was read in full; an anchored skill ranked fourth was hidden behind three unanchored matches; a skill edited mid-build was published under the stored generation; manual mode read the index before going silent; suggest mode advertised `resolve --load`, which returns no bodies there; admission denials were matched by message text, so a non-UTF-8 skill silently left the index.
+ - GREEN: a valid pointer for an earlier receipt is retired (`missing`) and the SessionStart builder rebuilds it; entries are validated against a closed key set before decoding and returned as new objects; pointer and index reads are bounded at 4 KiB, 4 MiB and 2,048 entries; suggestions filter for anchors before trimming to three; a build refuses plan or registry digests that differ from the checked carrier; the hook reads only the state binding before its manual-mode exit; suggest mode prints `ecc profile mode auto` with the current revision; denials carry `ECC_CONTEXT_*` codes and everything else propagates.
+ - Budget: a worker thread would make the 150 ms budget a hard bound but measured 135 to 150 ms for the same work (about 85 ms in process), so it would suppress most suggestions. The hook keeps in-process checks between steps, the read bounds cap the work at a real registry's size, and the documented snippet sets Claude Code's `timeout` as the outer bound.
+ - Full Claude index, auto mode, Linux x64 Node 22.22.0: wrapper invocations 108 to 122 ms against 29 to 45 ms with the hook disabled.
+
+ Review follow-up, October 9:
+
+ - RED (1 case fails): a build interrupted while writing the entries file left partial bytes under its digest name, and every later build refused them, so the index could not be restored. GREEN writes the file through the store's temporary-file-and-rename path and replaces a digest-named file whose bytes do not hash to its name.
+ - Sources edited after the entries are read: a new case pins that the published index still matches the stored generation and that the next build reports the generation stale. A final source recheck before the pointer would only discard a correct index. The triggers manifest, though, is not bound to the generation: an edit to it after `ecc profile set` reaches the next index unnoticed. Binding it is a store change, left open.
+ - Schema validation stays manual on the read path. On Windows x64, Node 24, loading Ajv took about 44 ms and compiling an index schema about 20 ms in a fresh process, against 22 ms for loading the whole routing module. That would cost the prompt-time read about 64 ms of its 150 ms budget, so Ajv stays off the prompt path, as `validateSchema` already documents.
+ - Budget: the October 8 decision stands. On the same Windows machine a prototype worker measured 64 to 77 ms against about 55 ms in process, and stopped a simulated 600 ms read at 152 ms. That gap is smaller than the Linux measurement above, so the trade-off may be worth revisiting with numbers from both platforms.
+
-These boundaries keep the shipped behavior distinct from the M1 release gate. Authenticated outcome observations, a complete Tier 2 disk diff, live-install migration, other-provider activation, whole-context token truth and release defaults remain unverified until their explicit prerequisites are available.
+These boundaries keep the shipped behavior distinct from the M1 release gate. Authenticated outcome observations, a complete Tier 2 disk diff, live-install migration, additional-provider activation, whole-context token truth and release defaults remain unverified until their explicit prerequisites are available.
diff --cc scripts/hooks/context-prompt-suggestions.js
index 000000000,8e3bf5697..3920d0276
mode 000000,100644..100644
--- a/scripts/hooks/context-prompt-suggestions.js
+++ b/scripts/hooks/context-prompt-suggestions.js
@@@ -1,0 -1,66 +1,69 @@@
+ #!/usr/bin/env node
+ 'use strict';
+
+ /**
+ * UserPromptSubmit hook: suggest up to three skills from the managed profile's
+ * routing index. Suggest-only; it loads no skill body, changes no selection,
+ * and grants nothing. Opt in by setting ECC_CONTEXT_STATE_ROOT to the store
+ * used with `ecc profile set`, and build the index with
+ * `ecc profile routing-index --state-root <store>`.
+ */
+
+ const path = require('node:path');
+
+ const MIN_PROMPT_LENGTH = 12;
+ const MAX_PROMPT_BYTES = 8192;
+ const DEFAULT_BUDGET_MS = 150;
+
+ function budgetMs(env) {
+ const value = Number(env.ECC_CONTEXT_SUGGEST_BUDGET_MS);
+ return Number.isFinite(value) && value >= 0 ? Math.min(value, 1000) : DEFAULT_BUDGET_MS;
+ }
+
+ function promptFrom(rawInput) {
+ try {
+ const input = JSON.parse(rawInput);
+ return typeof input?.prompt === 'string' ? input.prompt : null;
+ } catch {
+ return null;
+ }
+ }
+
+ function message(binding, suggestions) {
- const root = JSON.stringify(binding.root);
++ // A quoted JSON path is data, not shell escaping. Keep user-selected paths
++ // out of executable examples so metacharacters cannot become shell code.
++ const root = '<store>';
+ const action = binding.selectionMode === 'suggest'
+ ? `Suggest mode never loads bodies. To load one, switch with ecc profile mode auto --state-root ${root} --expected-revision ${binding.revision}, then resolve it by ID.`
+ : `To load one, run ecc profile resolve --state-root ${root} --task-input - --load with its ID in explicitIds or proposedIds.`;
+ return ['ECC context suggestions (advisory; nothing was loaded):',
++ `Store path (data): ${JSON.stringify(binding.root)}. Replace <store> with this path as one shell argument.`,
+ ...suggestions.map(item => `- ${item.id}: ${item.description}`), action, ''].join('\n');
+ }
+
+ function run(rawInput, _context = {}, env = process.env) {
+ const started = Date.now();
+ const stateRoot = env.ECC_CONTEXT_STATE_ROOT;
+ if (!stateRoot || !path.isAbsolute(stateRoot) || path.resolve(stateRoot) !== stateRoot) return '';
+ const prompt = promptFrom(rawInput);
+ if (!prompt || prompt.trim().length < MIN_PROMPT_LENGTH || prompt.trimStart().startsWith('/')
+ || Buffer.byteLength(prompt) > MAX_PROMPT_BYTES) return '';
+ const budget = budgetMs(env);
+ try {
+ const routing = require('../lib/context-routing-index');
+ const binding = routing.readBinding(stateRoot);
+ if (binding.selectionMode === 'manual' || Date.now() - started >= budget) return '';
+ const index = routing.readRoutingIndex(stateRoot, binding);
+ if (!index) {
+ return { stdout: '', stderr: '[ContextSuggest] No routing index for the current profile; run ecc profile routing-index --state-root <store>.' };
+ }
+ if (Date.now() - started >= budget) return '';
+ const suggestions = routing.suggestContext(index, prompt);
+ if (!suggestions.length || Date.now() - started > budget) return '';
+ return message(binding, suggestions);
+ } catch (error) {
+ return { stdout: '', stderr: `[ContextSuggest] ${String(error.message).replace(/[^\x20-\x7E]/g, '?')}` };
+ }
+ }
+
+ module.exports = { run };
diff --cc scripts/lib/context-profile-commands.js
index f855bdfc6,868fbfcb0..78f5a5f42
--- a/scripts/lib/context-profile-commands.js
+++ b/scripts/lib/context-profile-commands.js
@@@ -163,9 -167,10 +168,10 @@@ function run(argv)
const options = parse(argv);
const value = execute(options);
return { schemaVersion: 'ecc.profile-operation.v1', status: (value.launch?.status === 'failed' || value.interactive?.status === 'failed') ? 'error' : 'success',
- summary: options.command === 'start' ? 'Opt-in interactive Codex uses the verified isolated generation and inherited terminal. Context selection remains advisory.'
+ summary: options.command === 'start' ? 'Opt-in interactive session uses the verified isolated generation and inherited terminal. Context selection remains advisory.'
: options.command === 'run' ? 'Task launch uses selected context and the provider configuration. Inspect the launch result.'
: options.command === 'resolve' ? 'Task context resolved within the selected profile.'
+ : options.command === 'routing-index' ? 'Routing index inspected. Prompt suggestions stay advisory; resolve verifies sources before loading.'
: 'Managed profile generation inspected. Native activation is a separate provider boundary.',
activation: value.selection?.activation || 'unobserved', next_actions: [], artifacts: [], ...value };
}
diff --cc scripts/profile.js
index 0aefd7b06,c2286c936..f515dba8d
--- a/scripts/profile.js
+++ b/scripts/profile.js
@@@ -47,7 -47,8 +48,8 @@@ nothing is installed. Authenticate sepa
Set stages owned generations; provider discovery is verified separately.
Resolve returns context only with --load; suggest and --dry-run never return skill bodies.
Use resolve --state-root <directory> to honor the saved base, mode and exclusions.
+ Routing-index writes the metadata index read by the opt-in prompt suggestion hook; rebuild it after set, mode or rollback.
-Run with --native-root to use a verified isolated Codex generation. Existing sessions are unchanged.
+Run with --native-root to use a verified isolated Codex or Claude generation. Existing sessions are unchanged.
`;
}
diff --cc tests/hooks/context-prompt-suggestions.test.js
index 000000000,15e8b225a..4089528aa
mode 000000,100644..100644
--- a/tests/hooks/context-prompt-suggestions.test.js
+++ b/tests/hooks/context-prompt-suggestions.test.js
@@@ -1,0 -1,116 +1,136 @@@
+ 'use strict';
+
+ const assert = require('node:assert/strict');
+ const fs = require('node:fs');
+ const os = require('node:os');
+ const path = require('node:path');
+ const { spawnSync } = require('node:child_process');
+ const test = require('node:test');
+ const { withFixture } = require('../lib/helpers/context-fixture');
+ const store = require('../../scripts/lib/context-profile-store');
+ const routing = require('../../scripts/lib/context-routing-index');
+ const hook = require('../../scripts/hooks/context-prompt-suggestions');
+
+ const PROMPT = JSON.stringify({ hook_event_name: 'UserPromptSubmit', prompt: 'help with feature work in shared code' });
+
+ function fixture(callback, { mode = 'auto', index = true } = {}) {
+ return withFixture(repoRoot => {
+ const parent = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'ecc-prompt-suggest-'));
+ const stateRoot = path.join(parent, 'managed');
+ try {
+ store.applyStore({ repoRoot, stateRoot, target: 'claude', selectionMode: mode });
+ if (index) routing.writeRoutingIndex({ repoRoot, stateRoot });
+ return callback({ stateRoot, env: { ECC_CONTEXT_STATE_ROOT: stateRoot } });
+ } finally { fs.rmSync(parent, { recursive: true, force: true }); }
+ });
+ }
+
+ const stdout = result => (typeof result === 'string' ? result : result.stdout);
+
+ test('the hook is silent unless a managed store is explicitly configured', () => fixture(() => {
+ assert.equal(stdout(hook.run(PROMPT, {}, {})), '');
+ assert.equal(stdout(hook.run(PROMPT, {}, { ECC_CONTEXT_STATE_ROOT: 'relative/store' })), '');
+ }));
+
+ test('suggestions are advisory IDs with bounded descriptions and the resolve command', () => fixture(({ stateRoot, env }) => {
+ const text = stdout(hook.run(PROMPT, {}, env));
+ assert.match(text, /advisory; nothing was loaded/);
+ assert.match(text, /skill:feature/);
+ assert.match(text, /profile resolve --state-root/);
+ assert.ok(text.includes(JSON.stringify(stateRoot)));
+ assert.doesNotMatch(text, /Instructions remain on demand/);
+ assert.ok(text.split('\n').filter(line => line.startsWith('- skill:')).length <= 3);
+ assert.ok(text.split('\n').every(line => line.length <= 400));
+ }));
+
+ test('manual mode, short prompts, slash commands and malformed input stay silent', () => {
+ fixture(({ env }) => assert.equal(stdout(hook.run(PROMPT, {}, env)), ''), { mode: 'manual' });
+ fixture(({ env }) => {
+ for (const raw of [JSON.stringify({ prompt: 'fix it' }), JSON.stringify({ prompt: '/plan help with feature work' }),
+ '{not json', JSON.stringify({ prompt: 42 }), '']) {
+ assert.equal(stdout(hook.run(raw, {}, env)), '');
+ }
+ });
+ });
+
+ test('a missing index is a diagnostic, never an error or a rebuild', () => fixture(({ env }) => {
+ const result = hook.run(PROMPT, {}, env);
+ assert.equal(stdout(result), '');
+ assert.match(result.stderr, /routing-index/);
+ }, { index: false }));
+
+ test('a tampered index or exhausted budget fails open to no suggestion', () => fixture(({ stateRoot, env }) => {
+ assert.equal(stdout(hook.run(PROMPT, {}, { ...env, ECC_CONTEXT_SUGGEST_BUDGET_MS: '0' })), '');
+ const directory = path.join(stateRoot, 'routing');
+ const file = path.join(directory, fs.readdirSync(directory).find(name => name.endsWith('.json')));
+ fs.writeFileSync(file, '{"schemaVersion":"ecc.context-routing-index.v1"}');
+ const result = hook.run(PROMPT, {}, env);
+ assert.equal(stdout(result), '');
+ assert.match(result.stderr, /integrity|index/);
+ }));
+
+ test('the hook runs through run-with-flags and returns its text on stdout', () => fixture(({ env }) => {
+ const wrapper = path.join(__dirname, '../../scripts/hooks/run-with-flags.js');
+ const result = spawnSync(process.execPath, [wrapper, 'user-prompt:context-suggestions', 'scripts/hooks/context-prompt-suggestions.js'],
+ { input: PROMPT, encoding: 'utf8', env: { PATH: process.env.PATH, ...env }, timeout: 30000 });
+ assert.equal(result.status, 0);
+ assert.match(result.stdout, /skill:feature/);
+ }));
+
+ test('the session-start builder indexes the current generation once and stays silent when disabled', () => {
+ const builder = require('../../scripts/hooks/context-routing-index');
+ const parent = fs.mkdtempSync(path.join(fs.realpathSync(os.tmpdir()), 'ecc-routing-builder-'));
+ const stateRoot = path.join(parent, 'managed');
+ try {
+ assert.equal(builder.run('{}', {}, {}), '');
+ store.applyStore({ stateRoot, target: 'claude' });
+ const env = { ECC_CONTEXT_STATE_ROOT: stateRoot };
+ assert.match(builder.run('{}', {}, env).stderr, /built/);
+ assert.equal(routing.routingIndexStatus(stateRoot).status, 'current');
+ assert.equal(builder.run('{}', {}, env), '');
+ } finally { fs.rmSync(parent, { recursive: true, force: true }); }
+ });
+
+ test('manual mode is silent before the index is read, even when it is missing or corrupt', () => {
+ fixture(({ env }) => assert.deepEqual(hook.run(PROMPT, {}, env), ''), { mode: 'manual', index: false });
+ fixture(({ stateRoot, env }) => {
+ const directory = path.join(stateRoot, 'routing');
+ fs.writeFileSync(path.join(directory, fs.readdirSync(directory).find(name => name.endsWith('.json'))), '{');
+ assert.deepEqual(hook.run(PROMPT, {}, env), '');
+ }, { mode: 'manual' });
+ });
+
+ test('loading advice matches the saved mode', () => {
+ fixture(({ env }) => {
+ const text = stdout(hook.run(PROMPT, {}, env));
+ assert.match(text, /skill:feature/);
+ assert.match(text, /--load/);
+ });
+ fixture(({ stateRoot, env }) => {
+ const text = stdout(hook.run(PROMPT, {}, env));
+ assert.match(text, /skill:feature/);
+ assert.doesNotMatch(text, /--load/);
+ assert.match(text, /suggest mode/i);
- assert.ok(text.includes(`ecc profile mode auto --state-root ${JSON.stringify(stateRoot)}`));
++ assert.ok(text.includes(`ecc profile mode auto --state-root <store>`));
+ }, { mode: 'suggest' });
+ });
++
++test('shell metacharacters in a store path remain data rather than executable advice', () => {
++ const root = '/tmp/store-$(touch SHOULD_NOT_RUN)-`echo injected`-"quoted"';
++ const routingModule = require('../../scripts/lib/context-routing-index');
++ const originals = { readBinding: routingModule.readBinding, readRoutingIndex: routingModule.readRoutingIndex,
++ suggestContext: routingModule.suggestContext };
++ try {
++ routingModule.readBinding = () => ({ root, revision: 1, selectionMode: 'auto' });
++ routingModule.readRoutingIndex = () => ({ entries: [] });
++ routingModule.suggestContext = () => [{ id: 'skill:feature', description: 'Focused feature help.' }];
++ const text = stdout(hook.run(PROMPT, {}, { ECC_CONTEXT_STATE_ROOT: root }));
++ assert.ok(text.includes(`Store path (data): ${JSON.stringify(root)}`));
++ const commandLine = text.split('\n').find(line => line.startsWith('To load one'));
++ assert.ok(commandLine.includes('--state-root <store>'));
++ assert.ok(!commandLine.includes(root));
++ assert.doesNotMatch(commandLine, /touch|injected/);
++ } finally {
++ Object.assign(routingModule, originals);
++ }
++});