@event4u/agent-config 17.1.0 → 17.2.0

package/src/scripts/hook_manifest.yaml

@@ -1364,6 +1364,19 @@ concerns:
   #
   # Never blocks, never warns: exit 0 on every path including a malformed
   # payload or an unwritable disk. fail_closed: false.
+  # road-to-a-setup-that-decides-itself step 1.1 — the instructions-loaded
+  # observer. CAPTURE ONLY: one classified line per loaded file into
+  # `<machine root>/runtime/arrivals/<session>.jsonl`, the input of the arrival
+  # record the computed layer form reads. Emits nothing to the model; exit 0 on
+  # every path. Loaded from its own conditional chunk, never inlined.
+  # Kill switch: `AGENT_CONFIG_INSTRUCTIONS_OBSERVER=off`, or remove the
+  # `instructions_loaded` row under `platforms.claude` and reinstall.
+  instructions-observer:
+    script: src/scripts/hooks/instructions_observer_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    effect: telemetry
   subagent-ledger:
     script: src/scripts/hooks/subagent_ledger_hook.ts
     args: []
@@ -1640,6 +1653,10 @@ platforms:
     subagent_start:   [subagent-ledger, journal-record]
     subagent_stop:    [subagent-ledger, journal-record]
     agent_error:      [host-rate-marker]
+    # Observe-only; the host runs this event asynchronously, once per loaded file.
+    # `journal-record` is deliberately not bound here: the event is recordable
+    # (RECORDED_EVENTS), but its capture lives under runtime/arrivals/.
+    instructions_loaded: [instructions-observer]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
   # on top of the Claude Code CLI. Same lifecycle vocabulary, same
@@ -1796,6 +1813,9 @@ native_event_aliases:
     # agents/evidence/investigations/subagent-lifecycle-phase0-host-pin.md.
     SubagentStart:     subagent_start
     SubagentStop:      subagent_stop
+    # Present on the installed binary (exact-token count 9):
+    # agents/evidence/investigations/standing-context-40k-host-and-machine-probes.md § 1.
+    InstructionsLoaded: instructions_loaded
     # StopFailure fires on an API failure and carries its class in `error`
     # (observed on 2.1.308 with `server_error`; `rate_limit` is the host's
     # documented value for the plan limit and has not been observed live, so a

package/src/scripts/hooks/dispatch_hook.ts

@@ -118,8 +118,8 @@ export const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
   "stop",
   "pre_compact",
   "agent_error",
-  "subagent_start",
-  "subagent_stop",
+  "subagent_start", "subagent_stop",
+  "instructions_loaded",
 ]);
 
 const _SEVERITY_BY_EXIT: Record<number, string> = {

package/src/scripts/hooks/instructions_observer_hook.ts

@@ -46,19 +46,20 @@
  * the observer has written since. A failure that also prevents writing the mark
  * — the machine root itself unwritable — leaves none.
  *
- * NOT YET BOUND. No manifest row runs this concern, and it is not in the
- * dispatcher's concern registry, so it adds nothing to the hook bundle until
- * its binding lands; the binding needs bundle headroom it does not have today.
+ * BOUND ON `claude` ALONE, FROM ITS OWN CHUNK. The manifest runs it on
+ * `instructions_loaded`; the dispatcher loads it through `LAZY_CONCERNS`, so its
+ * body is not inlined into the dispatch bundle. The binding itself is: one
+ * registry row and the event name, 237 bytes (`hook-bundle-budget.json`).
  *
  * KILL SWITCH. `AGENT_CONFIG_INSTRUCTIONS_OBSERVER=off` makes it a no-op without
- * a reinstall; once the binding above lands, removing that one
- * `instructions_loaded` row from `hook_manifest.yaml` and reinstalling removes
- * it entirely. Either is the
+ * a reinstall; removing the one `instructions_loaded` row from
+ * `hook_manifest.yaml` and reinstalling removes it entirely. Either is the
  * response to hook failures, duplicate events, a session-start regression or an
  * unexplained test break.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { event4u_root } from '../_lib/user_global_paths.js';
 import { captureInstructionsLoaded, isSessionFile } from '../_lib/instructions_loaded_event.js';
@@ -168,3 +169,21 @@ export function main(): number {
         return EXIT_ALLOW;
     }
 }
+
+// The spawn fallback runs this file as a script, so it needs an entry; inside a
+// bundle or chunk every module shares one `import.meta.url`, so it must never fire there.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());

package/src/scripts/hooks/lazy_concern.ts

@@ -68,6 +68,10 @@ export const LAZY_CONCERNS: Readonly<Record<string, { readonly chunk: string; re
             chunk: 'chat_history.chunk.cjs',
             source: path.join('..', 'chat_history'),
         }),
+        'src/scripts/hooks/instructions_observer_hook.ts': Object.freeze({
+            chunk: 'instructions_observer.chunk.cjs',
+            source: 'instructions_observer_hook',
+        }),
     });
 
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;

package/src/scripts/install-hooks.sh

@@ -674,6 +674,11 @@ if [ -f "$cg_cache" ] && [ -x ./agent-config ]; then
         (
             trap 'rmdir "$cg_lock" 2>/dev/null || true' EXIT
             ./agent-config code-graph refresh --budget-seconds 60 >/dev/null 2>&1 || true
+            # The map follows the index it is drawn from, but only for a
+            # project that asked for one: no agents/map/, no map (ADR-297).
+            if [ -d agents/map ]; then
+                ./agent-config code-graph map --no-verify --no-build >/dev/null 2>&1 || true
+            fi
         ) >/dev/null 2>&1 &
     fi
 fi

package/src/scripts/lint_agents_layout.ts

@@ -62,6 +62,7 @@ const ALLOWED_SOURCE_DIRS: ReadonlySet<string> = new Set([
     'evidence',
     'features',
     'knowledge',    // * consumer
+    'map',          // * consumer — code-graph map, local-only, gitignored (ADR-297)
     'memory',       // * consumer
     'notes',        // legacy; new files go to evidence/notes/
     'reports',      // legacy; new files go to evidence/reports/ (see agents-layout.md)
@@ -91,6 +92,7 @@ const CONSUMER_EXPECTED_ENTRIES: ReadonlySet<string> = new Set([
     '.gitkeep',
     // Optional but legitimate consumer entries (will not trigger warnings)
     'knowledge',
+    'map',
     'memory',
     'proposals',
     'roadmaps',

package/src/scripts/lint_hook_manifest.ts

@@ -93,6 +93,7 @@ const EVENT_VOCABULARY: ReadonlySet<string> = new Set([
   "agent_error",
   "subagent_start",
   "subagent_stop",
+  "instructions_loaded",
 ]);
 
 // Known platform identifiers.

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -93,7 +93,7 @@
     },
     {
       "name": "chat_history_read",
-      "description": "Read recent entries back from the consumer project's chat-history JSONL (`agents/runtime/.agent-chat-history`; `agents/.agent-chat-history` accepted for back-compat). Use to recover context from an earlier session — decisions, notes, phase markers — at the start of a new task. Read-only. Returns the resolved file path plus a list of matching entries (newest last). Combine `session`, `last`, and `entry_type` to narrow the result.",
+      "description": "Read recent entries from the chat-history JSONL (`agents/runtime/.agent-chat-history`; legacy `agents/.agent-chat-history` accepted) to recover decisions, notes and phase markers from an earlier session. Returns the resolved path and matching entries, newest last.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -116,7 +116,7 @@
           },
           "path": {
             "type": "string",
-            "description": "Optional history-file path override; defaults to the standard chat-history location under the project root."
+            "description": "History-file override; default is the standard location."
           },
           "around": {
             "type": "integer",
@@ -142,7 +142,7 @@
               "full"
             ],
             "default": "full",
-            "description": "'index' returns compact rows (ref, t tag, ~100-char preview, tokens_estimate) instead of full entries — scan first, then re-read the refs you need via `around` or a narrowed filter. History entries are large, so index mode pays off here. 'full' (default) returns complete entries."
+            "description": "'index' returns compact rows (ref, t tag, preview, tokens_estimate) — scan, then re-read refs via `around` or a filter. 'full' (default) returns whole entries."
           }
         },
         "additionalProperties": false
@@ -222,6 +222,29 @@
         "readOnlyHint": true
       }
     },
+    {
+      "name": "graph_area",
+      "description": "One code-map area by id, exact name or member file: files, hubs, dependencies. Else refused.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "area"
+        ],
+        "properties": {
+          "area": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
     {
       "name": "graph_dead",
       "description": "Symbols with no accepted reference that no declared entry point names. REFUSES (status `refused`) while a source is unreadable: with no exportedness recorded, an exported-but-unimported symbol is indistinguishable from a dead one. Never a deletion recommendation.",
@@ -283,6 +306,22 @@
         "readOnlyHint": false
       }
     },
+    {
+      "name": "graph_map_status",
+      "description": "Is there a code map (agents/map/)? Its freshness, counts and MAP.md path.",
+      "side_effect": "ro",
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
+    },
     {
       "name": "graph_node",
       "description": "One symbol in full: where it is declared, what reaches it, what it reaches, and how connected it is. Resolves EXACTLY (node id, then label) and refuses anything it cannot — it never scores free text, so an answer is always about the node you named.",
@@ -325,7 +364,15 @@
               "uses",
               "inherits",
               "member",
-              "tests"
+              "tests",
+              "routes-to",
+              "renders",
+              "includes",
+              "reads",
+              "migrates",
+              "persists",
+              "relates",
+              "documents"
             ],
             "description": "Restrict to one relation. Omit for all of them."
           }
@@ -527,7 +574,7 @@
     },
     {
       "name": "memory_lookup",
-      "description": "Retrieve engineering-memory entries for one or more memory types, optionally narrowed to specific anchor paths. Use before editing a security-sensitive or historically buggy file to surface prior incidents, ownership, and patterns tied to it. WORKFLOW: call with detail:\"index\" FIRST — each row carries id, title and tokens_estimate (the cost of fetching it) — then fetch full bodies via memory_get ONLY for the ids you will actually use, batching multiple ids into one call. Reads `agents/memory/<type>/*.yml` plus the `agents/memory/intake/*.jsonl` signal log. Read-only. Returns the v1 retrieval envelope: a `status` field plus per-type `slices` carrying the matched entries.",
+      "description": "Engineering-memory entries for one or more types, optionally narrowed to anchor paths — use before editing a security-sensitive or historically buggy file. Call with detail:\"index\" FIRST (rows carry id, title, tokens_estimate), then memory_get only the ids you will use, batched. Reads `agents/memory/<type>/*.yml` and `agents/memory/intake/*.jsonl`. Returns a `status` plus per-type `slices`.",
       "side_effect": "ro",
       "implemented_on": [
         "stdio"
@@ -568,7 +615,7 @@
           "token_budget": {
             "type": "integer",
             "minimum": 1,
-            "description": "Optional token budget. When set, entries are rendered as one-line compact rows (id, type, confidence, `line`) and the row set is hard-cut at token_budget × 4 chars; omitted hits appear as a top-level `truncation` hint naming a concrete next step. Absent → the envelope is unchanged."
+            "description": "Optional: render compact rows (id, type, confidence, `line`) hard-cut at token_budget × 4 chars; omitted hits yield a top-level `truncation` hint."
           }
         },
         "required": [

package/src/scripts/mcp_server/graph_tools.ts

@@ -62,6 +62,7 @@ import {
     testsFor,
     untested,
 } from '../code_graph/verbs.js';
+import { areaReport, readMap } from '../code_graph/map.js';
 import type { BuiltinTool } from './tools.js';
 
 /** The `no graph here` answer, in one place so all five agree on its shape. */
@@ -119,7 +120,22 @@ function str(args: Record<string, unknown>, key: string): string {
  * drift. An enum that silently lost a value would turn a legal filter into a
  * rejected argument.
  */
-const RELATIONS = ['calls', 'imports', 'uses', 'inherits', 'member', 'tests'] as const;
+const RELATIONS = [
+    'calls',
+    'imports',
+    'uses',
+    'inherits',
+    'member',
+    'tests',
+    'routes-to',
+    'renders',
+    'includes',
+    'reads',
+    'migrates',
+    'persists',
+    'relates',
+    'documents',
+] as const;
 
 function num(args: Record<string, unknown>, key: string, dflt: number): number {
     const v = args[key];
@@ -360,4 +376,60 @@ export const GRAPH_TOOLS: Record<string, BuiltinTool> = {
             }));
         },
     },
+    graph_map_status: {
+        name: 'graph_map_status',
+        side_effect: 'ro',
+        description: 'Is there a code map (agents/map/)? Its freshness, counts and MAP.md path.',
+        input_schema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async (_args, root) => {
+            const staleness = graphState(root);
+            const map = readMap(root);
+            if (!map) {
+                return {
+                    status: 'unavailable',
+                    staleness,
+                    map: 'absent',
+                    hint: 'run `agent-config code-graph map` to draw it into agents/map/',
+                };
+            }
+            const m = map.model;
+            return {
+                status: 'ok',
+                staleness,
+                map: 'present',
+                drawn_at_commit: map.meta.commit,
+                graph_state_when_drawn: map.meta.state,
+                files: m.files.length,
+                areas: m.areas.length,
+                trusted_links: m.analyses.trustedEdges,
+                guess_share: m.analyses.guessShare,
+                request_paths: m.analyses.requestPathsTotal,
+                largest_areas: m.areas.slice(0, 5).map((a) => `${a.id} ${a.name} (${a.files.length})`),
+                map_md: 'agents/map/MAP.md',
+                index_html: 'agents/map/index.html',
+            };
+        },
+    },
+    graph_area: {
+        name: 'graph_area',
+        side_effect: 'ro',
+        description: 'One code-map area by id, exact name or member file: files, hubs, dependencies. Else refused.',
+        input_schema: {
+            type: 'object',
+            required: ['area'],
+            properties: {
+                area: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        handler: async (args, root) => {
+            const q = str(args, 'area');
+            if (q === '') return { status: 'error', error: 'area must be a non-empty string' };
+            const map = readMap(root);
+            if (!map) return { status: 'unavailable', error: 'no map — run `agent-config code-graph map`' };
+            const r = areaReport(map.model, q);
+            if ('refusal' in r) return { status: 'refused', refusal: r.refusal, candidates: r.candidates };
+            return { status: 'ok', drawn_at_commit: map.meta.commit, ...r };
+        },
+    },
 };

package/src/scripts/mcp_server/tools.ts

@@ -1298,15 +1298,11 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
         name: 'chat_history_read',
         side_effect: 'ro',
         description:
-            "Read recent entries back from the consumer project's " +
-            'chat-history JSONL ' +
-            '(`agents/runtime/.agent-chat-history`; ' +
-            '`agents/.agent-chat-history` accepted for back-compat). Use ' +
-            'to recover context from an earlier session — decisions, ' +
-            'notes, phase markers — at the start of a new task. ' +
-            'Read-only. Returns the resolved file path plus a list of ' +
-            'matching entries (newest last). Combine `session`, `last`, ' +
-            'and `entry_type` to narrow the result.',
+            'Read recent entries from the chat-history JSONL ' +
+            '(`agents/runtime/.agent-chat-history`; legacy ' +
+            '`agents/.agent-chat-history` accepted) to recover decisions, ' +
+            'notes and phase markers from an earlier session. Returns the ' +
+            'resolved path and matching entries, newest last.',
         input_schema: {
             type: 'object',
             properties: {
@@ -1328,9 +1324,7 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
                 path: {
                     type: 'string',
                     description:
-                        'Optional history-file path override; defaults to ' +
-                        'the standard chat-history location under the ' +
-                        'project root.',
+                        'History-file override; default is the standard location.',
                 },
                 around: {
                     type: 'integer',
@@ -1359,12 +1353,9 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
                     enum: ['index', 'full'],
                     default: 'full',
                     description:
-                        "'index' returns compact rows (ref, t tag, ~100-char " +
-                        'preview, tokens_estimate) instead of full entries — ' +
-                        'scan first, then re-read the refs you need via ' +
-                        '`around` or a narrowed filter. History entries are ' +
-                        "large, so index mode pays off here. 'full' " +
-                        '(default) returns complete entries.',
+                        "'index' returns compact rows (ref, t tag, preview, " +
+                        'tokens_estimate) — scan, then re-read refs via ' +
+                        "`around` or a filter. 'full' (default) returns whole entries.",
                 },
             },
             additionalProperties: false,
@@ -1375,18 +1366,13 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
         name: 'memory_lookup',
         side_effect: 'ro',
         description:
-            'Retrieve engineering-memory entries for one or more memory ' +
-            'types, optionally narrowed to specific anchor paths. Use ' +
-            'before editing a security-sensitive or historically buggy ' +
-            'file to surface prior incidents, ownership, and patterns ' +
-            'tied to it. WORKFLOW: call with detail:"index" FIRST — each ' +
-            'row carries id, title and tokens_estimate (the cost of ' +
-            'fetching it) — then fetch full bodies via memory_get ONLY ' +
-            'for the ids you will actually use, batching multiple ids ' +
-            'into one call. Reads `agents/memory/<type>/*.yml` plus the ' +
-            '`agents/memory/intake/*.jsonl` signal log. Read-only. ' +
-            'Returns the v1 retrieval envelope: a `status` field plus ' +
-            'per-type `slices` carrying the matched entries.',
+            'Engineering-memory entries for one or more types, optionally ' +
+            'narrowed to anchor paths — use before editing a ' +
+            'security-sensitive or historically buggy file. Call with ' +
+            'detail:"index" FIRST (rows carry id, title, tokens_estimate), ' +
+            'then memory_get only the ids you will use, batched. Reads ' +
+            '`agents/memory/<type>/*.yml` and `agents/memory/intake/*.jsonl`. ' +
+            'Returns a `status` plus per-type `slices`.',
         input_schema: {
             type: 'object',
             properties: {
@@ -1426,12 +1412,9 @@ export const ALLOWLIST: Record<string, BuiltinTool> = {
                     type: 'integer',
                     minimum: 1,
                     description:
-                        'Optional token budget. When set, entries are ' +
-                        'rendered as one-line compact rows (id, type, ' +
-                        'confidence, `line`) and the row set is hard-cut at ' +
-                        'token_budget × 4 chars; omitted hits appear as a ' +
-                        'top-level `truncation` hint naming a concrete next ' +
-                        'step. Absent → the envelope is unchanged.',
+                        'Optional: render compact rows (id, type, confidence, ' +
+                        '`line`) hard-cut at token_budget × 4 chars; omitted ' +
+                        'hits yield a top-level `truncation` hint.',
                 },
             },
             required: ['types'],

package/src/vendor/grammars/README.md

@@ -10,9 +10,11 @@ with no manual parser install (ADR-259).
 
 `tree-sitter-wasms` carries 36 grammars (49 MiB on disk). Depending on it at
 runtime would hand every consumer all 36, which is the option ADR-259 §
-Alternatives rejects on exactly that measurement. Only the three grammars below
+Alternatives rejects on exactly that measurement. Only the six grammars below
 are loadable by the engine — `GRAMMAR_WASM` in `src/scripts/code_graph/types.ts`
-has three entries — so the other 33 would be payload with no reader.
+has six entries — so the other 30 would be payload with no reader. Vue needs no
+grammar of its own: the extractor blanks a component's template and parses its
+`<script>` with the TypeScript grammar.
 
 **No grammar is ever fetched at runtime** (Kill register K1). These files are in
 the tarball; the loader reads them from disk.
@@ -24,8 +26,11 @@ the tarball; the loader reads them from disk.
 | php | `tree-sitter-php.wasm` | `55bb617b6f01e14bab997861f0b20a2420cf6ba3199ffeb295b9ec398966d8a3` |
 | typescript (also serves `.tsx`) | `tree-sitter-typescript.wasm` | `8515404dceed38e1ed86aa34b09fcf3379fff1b4ff9dd3967bcd6d1eb5ac3d8f` |
 | javascript | `tree-sitter-javascript.wasm` | `63812b9e275d26851264734868d27a1656bd44a2ef6eb3e85e6b03728c595ab5` |
+| python | `tree-sitter-python.wasm` | `9056d0fb0c337810d019fae350e8167786119da98f0f282aceae7ab89ee8253b` |
+| go | `tree-sitter-go.wasm` | `9963ca89b616eaf04b08a43bc1fb0f07b85395bec313330851f1f1ead2f755b6` |
+| java | `tree-sitter-java.wasm` | `637aac4415fb39a211a4f4292d63c66b5ce9c32fa2cd35464af4f681d91b9a1f` |
 
-All three are built against **grammar ABI 14** (`EXPECTED_GRAMMAR_ABI` in
+All six are built against **grammar ABI 14** (`EXPECTED_GRAMMAR_ABI` in
 `src/scripts/code_graph/types.ts`). The loader asserts the ABI on every load, so
 a drifted grammar fails loudly rather than parsing wrongly.
 
@@ -68,7 +73,7 @@ The pair is ABI-coupled and must move together:
 
 ```bash
 npm i -D web-tree-sitter@<v> tree-sitter-wasms@<v>
-for g in php typescript javascript; do
+for g in php typescript javascript python go java; do
   cp node_modules/tree-sitter-wasms/out/tree-sitter-$g.wasm src/vendor/grammars/
 done
 shasum -a 256 src/vendor/grammars/*.wasm   # update the table above
@@ -76,7 +81,7 @@ shasum -a 256 src/vendor/grammars/*.wasm   # update the table above
 
 Then update, in the same change:
 
-- the three entries in `src/config/packed-binary-manifest.json` (they are
+- the six entries in `src/config/packed-binary-manifest.json` (they are
   path-, sha256- and size-bound, so any refresh invalidates them by design).
   This used to name `BINARY_PAYLOAD_EXCEPTIONS` in `src/scripts/check_pack_size.ts`,
   a constant that no longer exists — `grep -rn BINARY_PAYLOAD_EXCEPTIONS` returned