@@ -2768,6 +2768,45 @@ static void print_detected_agents(const cbm_detected_agents_t *a) {
27682768}
27692769
27702770/* Install Claude Code-specific configs (skills, MCP, hooks). */
2771+ /* ── Install plan recorder (issue #388) ────────────────────────────
2772+ * When g_install_plan != NULL, the install path runs as a dry-run and each
2773+ * write site records its planned target HERE — at the same point it would
2774+ * perform the write — so the emitted plan cannot drift from actual install
2775+ * behavior (it is the same code path with mutations disabled). */
2776+ typedef struct {
2777+ char agent [CLI_BUF_32 ];
2778+ char kind [CLI_BUF_32 ]; /* mcp_config | instructions | skills | hook */
2779+ char path [CLI_BUF_1K ];
2780+ } cbm_plan_entry_t ;
2781+
2782+ typedef struct {
2783+ cbm_plan_entry_t * items ;
2784+ int count ;
2785+ int cap ;
2786+ } cbm_install_plan_t ;
2787+
2788+ static cbm_install_plan_t * g_install_plan = NULL ;
2789+
2790+ static void plan_record (const char * agent , const char * kind , const char * path ) {
2791+ if (!g_install_plan || !path || !path [0 ]) {
2792+ return ;
2793+ }
2794+ cbm_install_plan_t * pl = g_install_plan ;
2795+ if (pl -> count >= pl -> cap ) {
2796+ int ncap = pl -> cap ? pl -> cap * 2 : CLI_BUF_16 ;
2797+ cbm_plan_entry_t * ni = realloc (pl -> items , (size_t )ncap * sizeof (* ni ));
2798+ if (!ni ) {
2799+ return ;
2800+ }
2801+ pl -> items = ni ;
2802+ pl -> cap = ncap ;
2803+ }
2804+ cbm_plan_entry_t * e = & pl -> items [pl -> count ++ ];
2805+ snprintf (e -> agent , sizeof (e -> agent ), "%s" , agent );
2806+ snprintf (e -> kind , sizeof (e -> kind ), "%s" , kind );
2807+ snprintf (e -> path , sizeof (e -> path ), "%s" , path );
2808+ }
2809+
27712810static void install_claude_code_config (const char * home , const char * binary_path , bool force ,
27722811 bool dry_run ) {
27732812 char config_dir [CLI_BUF_1K ];
@@ -2777,6 +2816,24 @@ static void install_claude_code_config(const char *home, const char *binary_path
27772816
27782817 char skills_dir [CLI_BUF_1K ];
27792818 snprintf (skills_dir , sizeof (skills_dir ), "%s/skills" , config_dir );
2819+
2820+ /* Plan mode: record the planned writes and return without mutating (#388). */
2821+ if (g_install_plan ) {
2822+ char p [CLI_BUF_1K ];
2823+ plan_record ("Claude Code" , "skills" , skills_dir );
2824+ snprintf (p , sizeof (p ), "%s/.mcp.json" , config_dir );
2825+ plan_record ("Claude Code" , "mcp_config" , p );
2826+ snprintf (p , sizeof (p ), "%s/.claude.json" , user_root );
2827+ plan_record ("Claude Code" , "mcp_config" , p );
2828+ snprintf (p , sizeof (p ), "%s/settings.json" , config_dir );
2829+ plan_record ("Claude Code" , "mcp_config" , p );
2830+ snprintf (p , sizeof (p ), "%s/hooks/%s" , config_dir , CMM_HOOK_GATE_SCRIPT );
2831+ plan_record ("Claude Code" , "hook" , p );
2832+ snprintf (p , sizeof (p ), "%s/hooks/%s" , config_dir , CMM_SESSION_REMINDER_SCRIPT );
2833+ plan_record ("Claude Code" , "hook" , p );
2834+ return ;
2835+ }
2836+
27802837 printf ("Claude Code:\n" );
27812838
27822839 int skill_count = cbm_install_skills (skills_dir , force , dry_run );
@@ -2831,6 +2888,14 @@ static void install_generic_agent_config(const char *label, const char *binary_p
28312888 const char * config_path , const char * instr_path ,
28322889 bool dry_run ,
28332890 int (* install_mcp )(const char * , const char * )) {
2891+ /* Plan mode: record planned writes, mutate nothing (#388). */
2892+ if (g_install_plan ) {
2893+ plan_record (label , "mcp_config" , config_path );
2894+ if (instr_path ) {
2895+ plan_record (label , "instructions" , instr_path );
2896+ }
2897+ return ;
2898+ }
28342899 printf ("%s:\n" , label );
28352900 if (!dry_run ) {
28362901 install_mcp (binary_path , config_path );
@@ -2853,6 +2918,9 @@ static void install_gemini_config(const char *home, const char *binary_path, boo
28532918 snprintf (ip , sizeof (ip ), "%s/.gemini/GEMINI.md" , home );
28542919 install_generic_agent_config ("Gemini CLI" , binary_path , cp , ip , dry_run ,
28552920 cbm_install_editor_mcp );
2921+ if (g_install_plan ) {
2922+ return ; /* config recorded by install_generic_agent_config above */
2923+ }
28562924 if (!dry_run ) {
28572925 cbm_upsert_gemini_hooks (cp );
28582926 }
@@ -2891,11 +2959,15 @@ static void install_cli_agent_configs(const cbm_detected_agents_t *agents, const
28912959 if (agents -> aider ) {
28922960 char ip [CLI_BUF_1K ];
28932961 snprintf (ip , sizeof (ip ), "%s/CONVENTIONS.md" , home );
2894- printf ("Aider:\n" );
2895- if (!dry_run ) {
2896- cbm_upsert_instructions (ip , agent_instructions_content );
2962+ if (g_install_plan ) {
2963+ plan_record ("Aider" , "instructions" , ip );
2964+ } else {
2965+ printf ("Aider:\n" );
2966+ if (!dry_run ) {
2967+ cbm_upsert_instructions (ip , agent_instructions_content );
2968+ }
2969+ printf (" instructions: %s\n" , ip );
28972970 }
2898- printf (" instructions: %s\n" , ip );
28992971 }
29002972}
29012973
@@ -2968,7 +3040,9 @@ static void install_editor_agent_configs(const cbm_detected_agents_t *agents, co
29683040static void cbm_install_agent_configs (const char * home , const char * binary_path , bool force ,
29693041 bool dry_run ) {
29703042 cbm_detected_agents_t agents = cbm_detect_agents (home );
2971- print_detected_agents (& agents );
3043+ if (!g_install_plan ) {
3044+ print_detected_agents (& agents );
3045+ }
29723046
29733047 if (agents .claude_code ) {
29743048 install_claude_code_config (home , binary_path , force , dry_run );
@@ -3027,17 +3101,98 @@ static void cbm_detect_self_path(char *buf, size_t buf_sz, const char *home) {
30273101 }
30283102}
30293103
3104+ /* Build the agent.install.plan.v1 receipt (#388): a machine-readable list of
3105+ * the config / instruction / hook files `install` WOULD write, produced by
3106+ * running the real install dispatch in record-only mode (no mutation, no
3107+ * network). Returns a heap JSON string (caller frees) or NULL. */
3108+ char * cbm_build_install_plan_json (const char * home , const char * binary_path ) {
3109+ if (!home || !binary_path ) {
3110+ return NULL ;
3111+ }
3112+
3113+ /* Same code path as a real install, but mutations disabled and every write
3114+ * site records into `plan` — so the receipt cannot drift from behavior. */
3115+ cbm_install_plan_t plan = {0 };
3116+ g_install_plan = & plan ;
3117+ cbm_install_agent_configs (home , binary_path , false, true);
3118+ g_install_plan = NULL ;
3119+
3120+ cbm_detected_agents_t det = cbm_detect_agents (home );
3121+ struct {
3122+ bool flag ;
3123+ const char * name ;
3124+ } names [] = {
3125+ {det .claude_code , "claude-code" },
3126+ {det .codex , "codex" },
3127+ {det .gemini , "gemini" },
3128+ {det .zed , "zed" },
3129+ {det .opencode , "opencode" },
3130+ {det .antigravity , "antigravity" },
3131+ {det .aider , "aider" },
3132+ {det .kilocode , "kilocode" },
3133+ {det .vscode , "vscode" },
3134+ {det .cursor , "cursor" },
3135+ {det .openclaw , "openclaw" },
3136+ {det .kiro , "kiro" },
3137+ };
3138+
3139+ yyjson_mut_doc * doc = yyjson_mut_doc_new (NULL );
3140+ yyjson_mut_val * root = yyjson_mut_obj (doc );
3141+ yyjson_mut_doc_set_root (doc , root );
3142+ yyjson_mut_obj_add_str (doc , root , "type" , "agent.install.plan.v1" );
3143+
3144+ yyjson_mut_val * agents = yyjson_mut_arr (doc );
3145+ for (size_t i = 0 ; i < sizeof (names ) / sizeof (names [0 ]); i ++ ) {
3146+ if (names [i ].flag ) {
3147+ yyjson_mut_arr_add_str (doc , agents , names [i ].name );
3148+ }
3149+ }
3150+ yyjson_mut_obj_add_val (doc , root , "agents_detected" , agents );
3151+
3152+ yyjson_mut_val * configs = yyjson_mut_arr (doc );
3153+ yyjson_mut_val * instrs = yyjson_mut_arr (doc );
3154+ yyjson_mut_val * hooks = yyjson_mut_arr (doc );
3155+ for (int i = 0 ; i < plan .count ; i ++ ) {
3156+ cbm_plan_entry_t * e = & plan .items [i ];
3157+ if (strcmp (e -> kind , "mcp_config" ) == 0 ) {
3158+ yyjson_mut_arr_add_strcpy (doc , configs , e -> path );
3159+ } else if (strcmp (e -> kind , "hook" ) == 0 ) {
3160+ yyjson_mut_val * h = yyjson_mut_obj (doc );
3161+ yyjson_mut_obj_add_strcpy (doc , h , "agent" , e -> agent );
3162+ yyjson_mut_obj_add_strcpy (doc , h , "path" , e -> path );
3163+ yyjson_mut_arr_add_val (hooks , h );
3164+ } else {
3165+ yyjson_mut_arr_add_strcpy (doc , instrs , e -> path );
3166+ }
3167+ }
3168+ yyjson_mut_obj_add_val (doc , root , "config_files_planned" , configs );
3169+ yyjson_mut_obj_add_val (doc , root , "instruction_files_planned" , instrs );
3170+ yyjson_mut_obj_add_val (doc , root , "hooks_planned" , hooks );
3171+ yyjson_mut_obj_add_bool (doc , root , "writes_started" , false);
3172+ yyjson_mut_obj_add_bool (doc , root , "network_after_install" , false);
3173+ yyjson_mut_obj_add_str (doc , root , "next_safe_command" , "codebase-memory-mcp install -y" );
3174+
3175+ char * json = yyjson_mut_write (doc , YYJSON_WRITE_PRETTY , NULL );
3176+ yyjson_mut_doc_free (doc );
3177+ free (plan .items );
3178+ return json ; /* malloc'd; caller frees */
3179+ }
3180+
30303181int cbm_cmd_install (int argc , char * * argv ) {
30313182 parse_auto_answer (argc , argv );
30323183 bool dry_run = false;
30333184 bool force = false;
3185+ bool plan = false;
30343186 for (int i = 0 ; i < argc ; i ++ ) {
30353187 if (strcmp (argv [i ], "--dry-run" ) == 0 ) {
30363188 dry_run = true;
30373189 }
30383190 if (strcmp (argv [i ], "--force" ) == 0 ) {
30393191 force = true;
30403192 }
3193+ if (strcmp (argv [i ], "--plan" ) == 0 ) {
3194+ plan = true;
3195+ }
30413196 }
30423197
30433198 const char * home = cbm_get_home_dir ();
@@ -3046,6 +3201,22 @@ int cbm_cmd_install(int argc, char **argv) {
30463201 return CLI_TRUE ;
30473202 }
30483203
3204+ /* --plan: emit the machine-readable install receipt and exit WITHOUT
3205+ * mutating anything (no config writes, no index deletion, no network) so
3206+ * an agent can inspect exactly what install would touch first (#388). */
3207+ if (plan ) {
3208+ char self_path [CLI_BUF_1K ] = {0 };
3209+ cbm_detect_self_path (self_path , sizeof (self_path ), home );
3210+ char * json = cbm_build_install_plan_json (home , self_path );
3211+ if (!json ) {
3212+ (void )fprintf (stderr , "error: failed to build install plan\n" );
3213+ return CLI_TRUE ;
3214+ }
3215+ printf ("%s\n" , json );
3216+ free (json );
3217+ return 0 ;
3218+ }
3219+
30493220 printf ("codebase-memory-mcp install %s\n\n" , CBM_VERSION );
30503221
30513222 int index_count = count_db_indexes (home );
0 commit comments