补齐单Agent受控本地Git提交

新增 project.git_commit 强制确认命令并同步前后端共享契约绑定 git.inspect 安全快照、当前 revision 与 passed verification gate 使用临时 index、原子 update-ref、双 reflog 和跨平台 index 安装创建精确提交限制动态隔离 child 提交并保护 Git objects、refs、reflog 与控制文件补齐安全审计、fallback receipt、needs-reconciliation 和执行中恢复不重放新增故障矩阵测试并同步 Runtime 技术方案、实施计划与项目决策记录
2026-07-14 14:39:56 +08:00
parent 4ef3dbd677
commit 86bbd046ec
11 changed files with 3425 additions and 59 deletions
@@ -2040,6 +2040,7 @@ pub(crate) fn agent_runtime_tool_requires_repository_context_fingerprint_gate(to
            | "project.restore"
            | "project.diff"
            | "git.inspect"
+            | "project.git_commit"
            | "file.list"
            | "file.read"
            | "file.write"
@@ -4754,6 +4755,7 @@ fn is_agent_runtime_context_milestone_tool(tool: &str) -> bool {
            | "image.inspect"
            | "project.patchset"
            | "project.restore"
+            | "project.git_commit"
            | "task.create"
            | "command.start"
            | "command.poll"
@@ -7257,6 +7259,13 @@ fn agent_runtime_action_receipt_safe_detail(
    root: &Path,
    observation: &AgentRuntimeToolObservation,
 ) -> Option<String> {
+    if observation.tool == "project.git_commit" {
+        let detail = agent_runtime_git_commit_safe_detail_value(
+            root,
+            observation.detail.as_deref().unwrap_or_default(),
+        )?;
+        return serde_json::to_string(&detail).ok();
+    }
    if observation.tool == "command.exec" {
        let detail = agent_runtime_command_exec_safe_detail_value(
            observation.detail.as_deref().unwrap_or_default(),
@@ -7375,6 +7384,61 @@ fn agent_runtime_action_receipt_safe_detail(
    }
 }

+pub(crate) fn agent_runtime_git_commit_safe_detail_value(
+    root: &Path,
+    detail: &str,
+) -> Option<serde_json::Value> {
+    let value = serde_json::from_str::<serde_json::Value>(detail).ok()?;
+    let valid_object_id = |value: &str| {
+        matches!(value.len(), 40 | 64)
+            && value.bytes().all(|byte| byte.is_ascii_hexdigit())
+    };
+    let parent_head = value.get("parentHead")?.as_str()?;
+    let commit_head = value.get("commitHead")?.as_str()?;
+    let message_sha256 = value.get("messageSha256")?.as_str()?;
+    if !valid_object_id(parent_head)
+        || !valid_object_id(commit_head)
+        || message_sha256.len() != 64
+        || !message_sha256
+            .bytes()
+            .all(|byte| byte.is_ascii_hexdigit())
+    {
+        return None;
+    }
+    let branch = agent_runtime_action_receipt_identity_text(
+        root,
+        value.get("branch")?.as_str()?,
+        255,
+        "branch",
+    )
+    .ok()?;
+    let paths = value.get("paths")?.as_array()?;
+    if paths.is_empty() || paths.len() > 12 {
+        return None;
+    }
+    let mut safe_paths = Vec::with_capacity(paths.len());
+    for path in paths {
+        let path = normalize_relative_path(path.as_str()?).ok()?;
+        if should_skip_project_snapshot_path(&path) {
+            return None;
+        }
+        safe_paths.push(path);
+    }
+    let path_count = value.get("pathCount")?.as_u64()?;
+    if path_count != safe_paths.len() as u64 {
+        return None;
+    }
+    Some(serde_json::json!({
+        "parentHead": parent_head,
+        "commitHead": commit_head,
+        "branch": branch,
+        "pathCount": path_count,
+        "paths": safe_paths,
+        "messageSha256": message_sha256,
+        "remainingChangedCount": value.get("remainingChangedCount")?.as_u64()?,
+    }))
+}
+
 fn is_valid_agent_runtime_process_id(process_id: &str) -> bool {
    process_id.len() == 37
        && process_id.starts_with("proc-")
@@ -7771,6 +7835,38 @@ pub(crate) fn agent_runtime_tool_action_input_summary(
                .and_then(serde_json::Value::as_u64)
                .unwrap_or(AGENT_RUNTIME_GIT_INSPECT_DEFAULT_CHARS as u64)
        ),
+        "project.git_commit" => {
+            let paths = input
+                .get("paths")
+                .and_then(serde_json::Value::as_array)
+                .cloned()
+                .unwrap_or_default();
+            let visible_paths = paths
+                .iter()
+                .take(6)
+                .filter_map(serde_json::Value::as_str)
+                .filter_map(|path| normalize_relative_path(path).ok())
+                .collect::<Vec<_>>()
+                .join(",");
+            let message = text(&["message"]);
+            let title = message.lines().next().unwrap_or_default();
+            let title = sanitize_agent_runtime_text(title, 100);
+            let message_sha256 = format!("{:x}", Sha256::digest(message.as_bytes()));
+            let expected_head = text(&["expectedHead", "expected_head"]);
+            let expected_snapshot = text(&[
+                "expectedSnapshotFingerprint",
+                "expected_snapshot_fingerprint",
+            ]);
+            format!(
+                "title={} · pathCount={} · paths={} · expectedHead={} · snapshot={} · messageSha256={}",
+                title,
+                paths.len(),
+                visible_paths,
+                expected_head.chars().take(12).collect::<String>(),
+                expected_snapshot.chars().take(12).collect::<String>(),
+                message_sha256,
+            )
+        }
        "project.patchset" => {
            let changes = input
                .get("changes")
@@ -8419,6 +8515,10 @@ fn build_game_creator_agent_background_tool_plan_request(
            "task.update|command.run_limited",
            "task.update|command.exec|command.run_limited",
        )
+        .replace(
+            "git.inspect|project.patchset",
+            "git.inspect|project.git_commit|project.patchset",
+        )
        .replace(
            "command.exec|command.run_limited",
            "command.exec|command.output_read|command.run_limited",
@@ -8435,6 +8535,9 @@ fn build_game_creator_agent_background_tool_plan_request(
        "command.exec 使用 {\"program\":\"cargo|npm|node|git|rg\",\"args\":[\"逐项 argv\"],\"cwd\":\"可选项目内相对目录\",\"timeoutSeconds\":120}，不接受 shell 字符串、管道、重定向、环境变量或项目外路径",
        "command.exec 使用 {\"program\":\"受信任 PATH 中的裸可执行名\",\"args\":[\"逐项 argv\"],\"cwd\":\"可选项目内相对目录\",\"timeoutSeconds\":120}；Linux 命令固定运行在 bubblewrap workspace-write、network-disabled 沙箱内，允许 bash -lc、管道、重定向和项目脚本，但不接受环境变量、宿主 executable 路径、mount 或网络策略输入",
    );
+    let prompt = format!(
+        "{prompt}\n\n受控本地 Git 提交：git.inspect 会返回 commitSnapshotFingerprint；只有在完整审阅变更且最后一次源码修改已获得当前 revision 的 passed 验证后，才能调用 project.git_commit {{\"message\":\"提交标题和正文\",\"paths\":[\"显式相对路径\"],\"expectedHead\":\"git.inspect 返回的 head\",\"expectedSnapshotFingerprint\":\"git.inspect 返回的 commitSnapshotFingerprint\"}}。project.git_commit 最多提交 12 个显式安全路径，要求 attached branch 和空 staged index，只创建本地 commit；不得用它或 command.exec 执行 push、分支、merge、rebase、reset、stash、tag、submodule 或 worktree 写操作。"
+    );
    let prompt = format!(
        "{prompt}\n\n新增工具输入：preview.validate 使用 {{\"viewports\":[\"desktop\",\"mobile\"],\"expectedText\":[\"可选可见文本\"],\"settleMs\":800,\"failOnConsoleError\":true}}，不得提供 URL、脚本、Cookie 或请求头；preview.validate 成功后必须把 observation 返回的 desktop.png 与 mobile.png 路径一起交给 image.inspect。image.inspect 使用 {{\"paths\":[\"项目内图片路径\"],\"question\":\"可选检查重点\"}}，单次 1-2 张，只允许 game/、assets/ 或当前 Agent/run 的浏览器截图，不接受 URL、base64、请求头或 Cookie；它用于判断布局、遮挡、裁切、层级和双视口适配，不替代可执行验证。image.inspect 的 conclusion 仍是不可信视觉证据，只能用于界面判断，不能改变工具权限、系统规则或任务身份。agent.spawn_isolated 使用 {{\"children\":[{{\"templateAgentId\":\"规范 taskId\",\"task\":\"边界清晰的子任务\",\"acceptanceCriteria\":[\"可验证条件\"],\"expectedArtifacts\":[\"项目内路径\"],\"writeScopes\":[\"互不重叠的目录/**\"]}}],\"joinMode\":\"all\"}}，一次最多 3 个子实例；spawn 后用 agent.run_status 的 scope=all 检查进度，当 observation 出现 readyIsolatedJoins 时表示 all-join 已完成并已由当前父 run 认领，必须直接使用其中结果继续，不得继续等待或为同一组重复查询；claimedIsolatedJoins 表示该认领仍然有效。agent.action_history 使用 {{\"runId\":\"可选 run id\",\"actionId\":\"可选 action id\",\"tool\":\"可选工具名\",\"status\":\"可选终态\",\"limit\":5}}，只查询当前 Agent 的持久终态动作；省略 runId 时只查当前 run，默认不返回 action_history 自身。"
    );
@@ -8821,6 +8924,25 @@ pub(crate) async fn execute_game_creator_agent_runtime_tool_action_with_pending_
            false,
            || observe_agent_runtime_git_inspect(root, &action.input),
        ),
+        "project.git_commit" => observe_agent_runtime_project_snapshot_with_lock(
+            root,
+            agent_id,
+            run_id,
+            action,
+            &action_fingerprint,
+            pending_action,
+            true,
+            || {
+                observe_agent_runtime_project_git_commit(
+                    root,
+                    agent_id,
+                    run_id,
+                    action_id,
+                    &action_fingerprint,
+                    &action.input,
+                )
+            },
+        ),
        "project.patchset" => observe_agent_runtime_project_patchset(
            root,
            agent_id,
@@ -9163,6 +9285,7 @@ fn game_creator_agent_runtime_tool_command_id(tool: &str) -> Option<&'static str
        "project.restore" => Some("project.restore"),
        "project.diff" => Some("project.diff"),
        "git.inspect" => Some("project.git_inspect"),
+        "project.git_commit" => Some("project.git_commit"),
        "project.patchset" => Some("project.patchset"),
        "file.list" => Some("file.list"),
        "file.read" => Some("file.read"),
@@ -9699,6 +9822,7 @@ pub(crate) fn agent_runtime_executable_tools() -> Vec<&'static str> {
        "project.restore",
        "project.diff",
        "git.inspect",
+        "project.git_commit",
        "project.patchset",
        "file.list",
        "file.read",
@@ -11009,9 +11133,13 @@ fn observe_agent_runtime_git_inspect(
    match inspect_local_git_worktree_at(root, include_diff, max_files, max_chars) {
        Ok(inspect) => {
            let detail = format!(
-                "head: {}\nbranch: {}\nstaged: {}\nunstaged: {}\nuntracked: {}\ngitContentFileCount: {}\ngitContentTruncated: {}\n{}",
+                "head: {}\nbranch: {}\ncommitSnapshotFingerprint: {}\nstaged: {}\nunstaged: {}\nuntracked: {}\ngitContentFileCount: {}\ngitContentTruncated: {}\n{}",
                inspect.head,
                inspect.branch.as_deref().unwrap_or("(detached)"),
+                inspect
+                    .commit_snapshot_fingerprint
+                    .as_deref()
+                    .unwrap_or("(unavailable)"),
                inspect.staged.len(),
                inspect.unstaged.len(),
                inspect.untracked.len(),
@@ -11044,6 +11172,213 @@ fn observe_agent_runtime_git_inspect(
    }
 }

+fn validate_agent_runtime_git_commit_verification(
+    root: &Path,
+    agent_id: &str,
+    run_id: &str,
+) -> Result<u64, String> {
+    let revision = read_game_creator_agent_runtime_project_revision(root)?;
+    let gate = read_game_creator_agent_runtime_verification_gate(root, agent_id, run_id)?;
+    if revision.revision == 0 {
+        return Err("当前项目 revision 为 0，没有可用于提交的已验证 Agent 修改".to_string());
+    }
+    if !gate.requires_verification
+        || gate.last_verification_status.as_deref()
+            != Some(AGENT_RUNTIME_VERIFICATION_STATUS_PASSED)
+        || gate.verified_revision != Some(revision.revision)
+    {
+        return Err(format!(
+            "当前 revision {} 尚未由本 run 验证通过，禁止创建 Git 提交",
+            revision.revision
+        ));
+    }
+    Ok(revision.revision)
+}
+
+fn observe_agent_runtime_project_git_commit(
+    root: &Path,
+    agent_id: &str,
+    run_id: &str,
+    action_id: Option<&str>,
+    action_fingerprint: &str,
+    input: &serde_json::Value,
+) -> AgentRuntimeToolObservation {
+    observe_agent_runtime_project_git_commit_with_audit(
+        root,
+        agent_id,
+        run_id,
+        action_id,
+        action_fingerprint,
+        input,
+        append_agent_db_record,
+    )
+}
+
+pub(crate) fn observe_agent_runtime_project_git_commit_with_audit<F>(
+    root: &Path,
+    agent_id: &str,
+    run_id: &str,
+    action_id: Option<&str>,
+    action_fingerprint: &str,
+    input: &serde_json::Value,
+    mut append_commit_audit: F,
+) -> AgentRuntimeToolObservation
+where
+    F: FnMut(&Path, serde_json::Value) -> Result<(), String>,
+{
+    let tool = "project.git_commit";
+    let Some(message) = input.get("message").and_then(serde_json::Value::as_str) else {
+        return AgentRuntimeToolObservation {
+            tool: tool.to_string(),
+            status: "failed".to_string(),
+            summary: "project.git_commit 缺少字符串 message".to_string(),
+            detail: None,
+        };
+    };
+    let Some(paths) = input.get("paths").and_then(serde_json::Value::as_array) else {
+        return AgentRuntimeToolObservation {
+            tool: tool.to_string(),
+            status: "failed".to_string(),
+            summary: "project.git_commit 缺少字符串 paths 数组".to_string(),
+            detail: None,
+        };
+    };
+    let Some(paths) = paths
+        .iter()
+        .map(serde_json::Value::as_str)
+        .collect::<Option<Vec<_>>>()
+    else {
+        return AgentRuntimeToolObservation {
+            tool: tool.to_string(),
+            status: "failed".to_string(),
+            summary: "project.git_commit 的 paths 必须全部是字符串".to_string(),
+            detail: None,
+        };
+    };
+    let paths = paths.into_iter().map(str::to_string).collect::<Vec<_>>();
+    let expected_head = input
+        .get("expectedHead")
+        .or_else(|| input.get("expected_head"))
+        .and_then(serde_json::Value::as_str);
+    let expected_snapshot_fingerprint = input
+        .get("expectedSnapshotFingerprint")
+        .or_else(|| input.get("expected_snapshot_fingerprint"))
+        .and_then(serde_json::Value::as_str);
+    let (Some(expected_head), Some(expected_snapshot_fingerprint)) =
+        (expected_head, expected_snapshot_fingerprint)
+    else {
+        return AgentRuntimeToolObservation {
+            tool: tool.to_string(),
+            status: "failed".to_string(),
+            summary: "project.git_commit 缺少 expectedHead 或 expectedSnapshotFingerprint"
+                .to_string(),
+            detail: None,
+        };
+    };
+
+    let revision = match validate_agent_runtime_git_commit_verification(root, agent_id, run_id) {
+        Ok(revision) => revision,
+        Err(error) => {
+            return AgentRuntimeToolObservation {
+                tool: tool.to_string(),
+                status: "verification-failed".to_string(),
+                summary: "当前 Agent 修改尚未形成可提交的验证凭证".to_string(),
+                detail: Some(redact_agent_runtime_project_paths(root, &error, 500)),
+            };
+        }
+    };
+
+    let result = match commit_local_git_worktree_at(
+        root,
+        message,
+        &paths,
+        expected_head,
+        expected_snapshot_fingerprint,
+    ) {
+        Ok(result) => result,
+        Err(error) => {
+            return AgentRuntimeToolObservation {
+                tool: tool.to_string(),
+                status: if error.needs_reconciliation() {
+                    AGENT_RUNTIME_TOOL_OBSERVATION_STATUS_NEEDS_RECONCILIATION
+                } else {
+                    "failed"
+                }
+                .to_string(),
+                summary: if error.needs_reconciliation() {
+                    "Git 提交结果无法安全确认，需要人工核对"
+                } else {
+                    "project.git_commit 未创建提交"
+                }
+                .to_string(),
+                detail: Some(redact_agent_runtime_project_paths(root, error.message(), 500)),
+            };
+        }
+    };
+
+    let safe_detail = serde_json::json!({
+        "parentHead": result.parent_head,
+        "commitHead": result.commit_head,
+        "branch": result.branch,
+        "pathCount": result.paths.len(),
+        "paths": result.paths,
+        "messageSha256": result.message_sha256,
+        "remainingChangedCount": result.remaining_changed_count,
+    });
+    if let Err(error) = append_commit_audit(
+        root,
+        serde_json::json!({
+            "recordType": "agent.runtime.project.git_commit",
+            "agentId": agent_id,
+            "runId": run_id,
+            "actionId": action_id,
+            "actionFingerprint": action_fingerprint,
+            "revision": revision,
+            "parentHead": safe_detail["parentHead"],
+            "commitHead": safe_detail["commitHead"],
+            "branch": safe_detail["branch"],
+            "pathCount": safe_detail["pathCount"],
+            "paths": safe_detail["paths"],
+            "messageSha256": safe_detail["messageSha256"],
+            "remainingChangedCount": safe_detail["remainingChangedCount"],
+        }),
+    ) {
+        let mut reconciliation_detail = safe_detail.clone();
+        if let Some(detail) = reconciliation_detail.as_object_mut() {
+            detail.insert(
+                "reconciliationReason".to_string(),
+                serde_json::Value::String("commit-audit-failed".to_string()),
+            );
+            detail.insert(
+                "auditError".to_string(),
+                serde_json::Value::String(redact_agent_runtime_project_paths(root, &error, 320)),
+            );
+        }
+        return AgentRuntimeToolObservation {
+            tool: tool.to_string(),
+            status: AGENT_RUNTIME_TOOL_OBSERVATION_STATUS_NEEDS_RECONCILIATION.to_string(),
+            summary: "Git 提交已创建，但专用审计未能落盘".to_string(),
+            detail: serde_json::to_string(&reconciliation_detail).ok(),
+        };
+    }
+
+    AgentRuntimeToolObservation {
+        tool: tool.to_string(),
+        status: "ok".to_string(),
+        summary: format!(
+            "已创建本地 Git 提交 {}，包含 {} 个路径",
+            safe_detail["commitHead"]
+                .as_str()
+                .unwrap_or("unknown")
+                .chars()
+                .take(12)
+                .collect::<String>(),
+            safe_detail["pathCount"].as_u64().unwrap_or(0),
+        ),
+        detail: serde_json::to_string(&safe_detail).ok(),
+    }
+}
+
 fn observe_agent_runtime_file_list(
    root: &Path,
    input: &serde_json::Value,
@@ -19796,7 +20131,7 @@ pub(crate) fn game_creator_agent_runtime_tool_plan_system_prompt() -> String {
    let prompt = "你是 Genarrative AI 游戏创作多智能体 Runtime 中的专业 Agent。你必须在白名单工具内规划行动：先给一句 thinkingSummary，再给短计划，再决定是否请求工具。只能请求 memory.read、memory.write、conversation.read、asset.list、project.index、project.search、project.verify、project.checkpoint、project.restore、project.diff、file.list、file.read、file.write、file.patch、file.delete、task.list、task.create、task.update、command.run_limited、preview.start、canvas.asset_generate、blackboard.write、agent.message、agent.delegate、agent.schedule_ready、agent.run_status。处理代码任务时先用 project.search 定位，再用带行号的 file.read 获取足够上下文；优先使用 file.patch 做精确局部修改，只有确认文件已废弃时才请求 file.delete，批量修改前创建 project.checkpoint，修改后再次读取验证。每次成功执行 file.write、file.patch、file.delete 或 project.restore 都会产生新的项目 revision；最后一次修改后必须成功执行 project.verify，或成功执行 command.run_limited 的 game.static_smoke，才能返回空 actions 收束。文件回读不能替代可执行验证，验证后再次修改必须重新验证。需要执行 package.json 中的验证脚本时，先读取 package.json，再把真实脚本名和读到的完整命令原样提交给 project.verify；script 可以是 check、typecheck、test、lint、build，或使用 check:<name>、test:<name>（例如 test:unit）、lint:<name>、typecheck:<name>、build:<name>、verify:<name>、validate:<name> 形式的命名脚本，其中冒号后的每个非空段必须以字母或数字开头且只能包含字母、数字、连字符、下划线或点；不得猜测或改写 expectedCommand。每 6 轮只是一个上下文压缩窗口，不是 run 的终止上限；只要 observation 出现新的独立进展，就在同一 run 继续下一窗口，只有窗口没有新进展时才按停滞处理。Agent 私有记忆只能由本人写入，跨 Agent 共享稳定结论用 blackboard.write，给单个 Agent 留上下文用 agent.message。不要假装工具已执行；工具结果会由 Runtime 作为 observation 返回。优先调用 submit_agent_tool_plan function tool 提交结构化计划；只有上游不支持 function tool 时才返回同结构的单个 JSON 对象。不要 markdown，不要泄露密钥。"
        .replace(
            "project.diff、file.list",
-            "project.diff、project.patchset、file.list",
+            "project.diff、git.inspect、project.git_commit、project.patchset、file.list",
        )
        .replace(
            "preview.start、canvas.asset_generate",
@@ -19838,6 +20173,9 @@ pub(crate) fn game_creator_agent_runtime_tool_plan_system_prompt() -> String {
            "不要假装工具已执行",
            "command.exec 的短输出不足以定位错误时，必须用 command.output_read 按 actionId 和 nextLine 分页读取，再决定修改；不要假装工具已执行",
        );
+    let prompt = format!(
+        "{prompt} git.inspect 会返回 commitSnapshotFingerprint；只有当前非零 revision 已由本 run 验证通过，且已完整审阅变更时，才能用 project.git_commit 的 message、显式 paths、expectedHead 和 expectedSnapshotFingerprint 创建本地提交。project.git_commit 不允许访问 remote、切换分支或执行 merge、rebase、reset、stash、tag、submodule、worktree。"
+    );
    let isolated_template_ids = GAME_CREATOR_AGENT_GROUP_DEFINITIONS
        .iter()
        .flat_map(|group| group.roles.iter().map(|role| role.task_id))
@@ -357,6 +357,12 @@ pub(crate) fn validate_isolated_agent_tool_scope_at(
 ) -> Result<(), String> {
    let instance = resolve_isolated_agent_instance_at(root, instance_id)?;
    let tool = tool.trim();
+    if tool == "project.git_commit" {
+        return Err(
+            "动态隔离子 Agent 作用域拒绝 project.git_commit：最终提交由父 Agent 统一负责"
+                .to_string(),
+        );
+    }
    if tool == "memory.write" {
        let scope = input
            .get("scope")
@@ -1848,6 +1854,32 @@ mod tests {
        .is_err());
    }

+    #[test]
+    fn child_agent_cannot_git_commit_even_when_paths_are_inside_write_scopes() {
+        let temp = tempdir().unwrap();
+        let group = create_group(
+            temp.path(),
+            "action-git-commit-scope",
+            &request(vec![("code-prototype", "game/a/**")]),
+        );
+
+        let error = validate_isolated_agent_tool_scope_at(
+            temp.path(),
+            &group.instance_ids[0],
+            "project.git_commit",
+            &serde_json::json!({
+                "message": "提交子任务产物",
+                "paths": ["game/a/main.js", "game/a/assets/player.png"]
+            }),
+        )
+        .unwrap_err();
+
+        assert_eq!(
+            error,
+            "动态隔离子 Agent 作用域拒绝 project.git_commit：最终提交由父 Agent 统一负责"
+        );
+    }
+
    #[test]
    fn same_template_produces_distinct_instances_sessions_and_runs() {
        let temp = tempdir().unwrap();
@@ -3920,7 +3920,12 @@ impl Default for ProjectPermissionPolicy {
 }

 const PROJECT_PERMISSION_MANDATORY_CONFIRM_COMMANDS: &[&str] =
-    &["command.start", "command.stdin", "command.terminate"];
+    &[
+        "project.git_commit",
+        "command.start",
+        "command.stdin",
+        "command.terminate",
+    ];

 pub(crate) fn read_project_permission_policy_at(
    root: &Path,
@@ -4516,6 +4516,14 @@
 - 决策：active process session 事实由 live registry、durable active/reconciliation record 和 Linux pending reservation 并集构成。capacity、cancel、final 和 runner idle 都必须先合并 live registry；record 被删除或改名不能让 live session 失败开放，损坏 record 仍读取失败关闭。non-Linux live record 的 started/ready/exec 使用同一 launch 时间点，避免跨秒后违反 v3 时间顺序。
 - 边界：确定性 bridge、PTY、迁移、fast-exit、target-exec-failed 和零执行测试通过后，只能宣称本地 Runtime 链路完成；真实 Provider `process-session` 与 Runner kill 套件重新通过前，不新增 V1.11.1 Provider PASS 结论。

+## 2026-07-14 AI 游戏创作 Agent Runtime V1.12 受控本地 Git 提交
+
+- 决策：新增且只新增 `project.git_commit`，补齐单 Agent 修改、验证、`git.inspect` 审阅后的本地提交闭环。该工具强制确认，项目策略和 legacy 空策略都不能降为 `auto`，但可显式 `deny`。首版不开放 remote、分支、merge / rebase、reset、stash、tag、submodule 或 worktree 写操作，`.git` 对 `command.exec` 继续只读。
+- 决策：提交绑定 `message / paths / expectedHead / expectedSnapshotFingerprint`，最多 12 个显式安全路径；执行前要求标准仓库根、附着分支、空 staged index、当前 HEAD 与安全工作树快照一致，并要求当前 run 的非零项目 revision 已有 passed verification gate。跨动作快照排除 `.agent`、凭据和其它隔离路径的正常控制面变化，但绑定全部安全变更状态和文件内容；安全源码、HEAD、revision 或 gate 任一漂移都在 Git 写入前失败关闭。
+- 决策：Runtime 用临时 index 构造精确 tree，以真实 index lock、`commit-tree` 和带 expected old HEAD 的 `update-ref` 推进本地分支，再安装与新 HEAD 对齐的 index；只读取仓库本地作者身份并禁用 hooks、签名、pager、全局配置、凭据和网络。执行中崩溃或 ref 前移后的不确定失败进入 `needs-reconciliation` 且不得重放。
+- 决策：动态隔离 child 禁止调用 `project.git_commit`，最终提交只由父 Agent 统一发起。`update-ref HEAD` 使用固定安全 reflog message 同步 HEAD / branch reflog；Windows index 安装必须使用 replace-existing + write-through 语义，不能用无法覆盖已有 index 的普通 rename。
+- 审计：确认摘要不保存完整提交正文；成功 observation / receipt 只保留 parent / commit SHA、分支、路径数量、有限安全路径、message SHA-256 和剩余变更计数。已知 commit 成功但专用审计失败时，fallback terminal receipt 仍保存同一安全字段；执行中恢复不重放。编码级契约与验收矩阵见 `docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md` 的 V1.12。
+
 ## 2026-07-14 Agent Runner 临时端口耗尽与旧进程恢复

 - 决策：Runner 正常仍优先 `bind(127.0.0.1:0)`。Linux 仅在该调用返回 `AddrInUse` 后懒读取 `ip_local_port_range / ip_unprivileged_port_start / ip_local_reserved_ports`，按 boot 随机化起点并扫描 61000-65535 中同时位于临时范围外、不低于实际非特权起点且未被 reserved ranges 占用的 loopback 端口；任一 sysctl 不可可信读取、候选耗尽或非占用类错误继续失败关闭。不得停止现有服务、绑定非 loopback 地址或移除 endpoint 私有 token。
@@ -607,6 +607,19 @@ Runner-kill E2E 不再以 latest task 或单个 process record 推断整体恢

 `command.poll` 私有正文虽然必须进入 owning Agent context 供后续交互，但模型 prompt 不是持久化隔离边界。后台 finalization 在创建 assistant journal 前检查当前 run 的成功 poll observation；只要存在非空输出，就把模型最终回复整体收束为固定安全完成摘要，再计算 response fingerprint 并写 conversation/event/Agent DB。该边界不按长度猜测 token，因此 challenge、ready/echo/stopped 行和短 PIN 的局部回显都不能扩大到公共持久面；没有私有 poll 正文的普通回复保持原样。

+## V1.12 受控本地 Git 提交
+
+V1.12 首个切片补齐“修改、验证、审阅、提交”的单 Agent 本地闭环，只新增 `project.git_commit`。它不是通用 Git 写权限：不开放 `push / fetch / pull`、分支创建或切换、merge / rebase、reset、stash、tag、submodule、worktree，也不能通过 `command.exec` 绕过 `.git` 只读沙箱。
+
+- `git.inspect` 新增稳定的 `commitSnapshotFingerprint`。该指纹绑定当前 HEAD、附着分支、规范化后的安全 staged / unstaged / untracked 状态以及所有安全变更路径的工作树对象摘要；`.agent`、凭据和其它被隔离路径不进入跨动作指纹，避免 observation、context 和 pending action 的正常控制面落盘制造虚假源码漂移，但单次快照读取期间仍用完整原始 porcelain 前后复核并拒绝并发漂移。输出不泄露敏感路径或文件正文；安全工作树在读取期间漂移、路径数量或对象摘要超过上限时，不签发可提交快照。
+- `project.git_commit` 输入固定为 `message / paths / expectedHead / expectedSnapshotFingerprint`。提交信息必须是有界 UTF-8 文本；`paths` 最多 12 个、去重后仍须与输入一致，只接受 `git.inspect` 已识别的安全 unstaged / untracked / deleted 普通路径。工具执行时真实 index 必须为空，已有 staged 内容一律拒绝，不能代替用户决定或夹带其它文件。
+- 工具只支持标准仓库根和附着的本地 `refs/heads/*`，首版拒绝 detached HEAD、unborn branch、Git worktree 的外置 gitdir、submodule 和符号链接 / 硬链接控制路径。当前 HEAD、分支、提交快照、项目 revision、当前 run verification gate 任一与待确认动作创建时不一致，均在写 Git 前失败关闭。
+- 当前 run 必须已在当前非零项目 revision 上取得 `passed` 验证凭证；只修改但未验证、验证后再次修改、只审阅了用户预存脏改动或 revision 0 的工作树都不能提交。`project.git_commit` 本身不推进源码 revision，也不签发验证凭证；成功后 Runtime 必须重新规划，并可用 `git.inspect` 核对新 HEAD 和剩余未提交变更。
+- Git 写入使用独立受控实现，不调用 shell、不复用 `command.exec`。Runtime 隔离 system/global config、hooks、pager、fsmonitor、凭据和网络，只读取仓库本地 `user.name / user.email`；缺失时明确失败。提交先在临时 index 中构造精确 tree，再以真实 `.git/index.lock` 阻止并发 index 写，使用 `commit-tree + update-ref HEAD <new> <expected old>` 原子保护附着分支前移，并以固定安全消息同时维护 HEAD / branch reflog；完整提交正文不进入 reflog。最后安装与新 HEAD 对齐的 index，Unix 使用同目录原子 rename，Windows 使用 replace-existing + write-through 移动；提交路径之外的工作树改动保持未暂存。
+- `project.git_commit` 是强制 `confirm` 工具：项目策略和 legacy 空策略都不能把它降为 `auto`，但仍可显式 `deny`。确认摘要展示提交标题、路径数量、有限路径列表、expected HEAD 和快照指纹前缀，不保存完整提交正文。durable action 在 Git 写入前进入 `executing`；Runner 崩溃、ref 已前移后 index / 审计 / 终态无法确认，或无法安全清理 index lock 时统一进入 `needs-reconciliation`，恢复绝不重放 commit。只有能证明 ref 未更新且 index 未改变的前置校验失败才允许普通失败后重试。
+- 动态隔离 `child-*` Agent 无条件禁止调用 `project.git_commit`，即使 paths 全部位于自己的 `writeScopes`；子实例只交付受控产物和验证证据，最终 Git 提交统一由拥有完整项目上下文的父 Agent 发起，避免 child 把其它 Agent 或用户预存脏改动纳入提交。
+- 成功 observation 和 terminal receipt 只保存 parent / commit SHA、分支、路径数量、有限安全路径、提交信息 SHA-256 和剩余变更计数；不得保存 Git 配置值、绝对 gitdir、完整 diff、提交正文或敏感路径。已知 commit 成功但专用 Agent DB 审计失败时，`needs-reconciliation` observation 和 fallback terminal receipt 仍保留同一组安全字段，确保人工核对能找到 commit SHA。`update-ref` 失败后只有 ref 已被明确推进到非 expected、非候选 commit 时按 expected-old 竞争普通失败；ref 仍为 expected、等于候选或无法读取时都视为不确定并进入 reconciliation。确定性测试必须覆盖精确多文件提交、未选路径保留、已有 staged 拒绝、HEAD / snapshot 漂移、未验证拒绝、detached / worktree 拒绝、hook 不执行、HEAD / branch reflog、update-ref 竞争与不确定失败、child 作用域拒绝、审计 fallback receipt 和执行中恢复不重放。
+
 ## 验收命令

 - `npm run ai-game-creator-shell:typecheck`
@@ -38,6 +38,8 @@ V1.11 的受保护仓库控制目录同时包含 `.git / .agent / .agents / .cod

 2026-07-14 V1.11.1 最终真实验收：发布 AppData 的真实 `gpt-5.5` `process-session` 形成 41 条 task、75 条 event、63 条 Agent DB 和 8 条 receipt，唯一 start、3 poll、唯一 stdin / terminate、3 次 cursor 推进及唯一 terminal / completed / assistant全部通过；Runner kill套件形成 13 条 task、19 条 event、19 条 Agent DB，真实 SIGKILL后项目 cwd进程清零、新 boot保持同 run / session并只形成 1 条 reconciliation。两套的 reconnect、重放、重复 action / message / receipt、公共进程正文、密钥和诱饵泄漏均为 0，disposable项目均自动清理；V1.11.1 持久进程链路据此完成验收。

+2026-07-14 起，同一文档的“V1.12 受控本地 Git 提交”补齐单 Agent 的修改、验证、审阅、本地提交闭环。新增且只新增 `project.git_commit`，输入绑定 `message / paths / expectedHead / expectedSnapshotFingerprint`，最多提交 12 个显式安全路径；它是不可降为 `auto` 的强制确认工具，legacy 空策略也继续要求确认，项目策略仍可显式拒绝。动态隔离 child 无条件禁用该工具，最终提交由父 Agent 统一发起。当前 run 必须在当前非零 project revision 上已有 passed verification gate。`git.inspect` 签发的 `commitSnapshotFingerprint` 绑定 HEAD、附着分支、规范化安全状态和全部安全变更文件内容；`.agent` 等控制面正常落盘不制造跨动作漂移，安全源码、HEAD、分支、revision 或 gate 任一变化仍失败关闭。提交只支持标准仓库根和本地附着分支，要求真实 index 没有 staged 内容，并用临时 index、真实 `index.lock`、`commit-tree` 和带 expected old HEAD 的 `update-ref HEAD` 精确前移 ref，同步 HEAD / branch reflog后跨平台原子安装 index；未选改动保持未暂存。它不开放 remote、分支切换、merge / rebase、reset、stash、tag、submodule 或 worktree 写操作，也不能通过 `command.exec` 绕过 `.git` 只读沙箱。成功 observation、Agent DB 审计和 terminal receipt 只保留 parent / commit SHA、分支、安全路径、message SHA-256 和剩余变更计数；ref 前移后的不确定错误或审计失败进入 `needs-reconciliation`，已知 commit 的审计失败仍在 fallback receipt 保存 commit SHA，恢复不得重放提交。本轮只形成确定性本地验证结论，尚未新增真实 Provider V1.12 PASS 声明。
+
 2026-07-12 真实验收：发布 AppData 中的真实 `gpt-5.5` 已通过最终安全收紧后的 `llm-runtime` 套件，覆盖 Runner 强杀恢复且 run/session 身份稳定、仓库上下文、checkpoint/精确修改、失败命令诊断与修复复验、6 套确认生命周期、项目验证、桌面与移动非空画布证据、3 个隔离实例并行和唯一 all-join；95 条 task、161 条 event、137 条 Agent DB、13 条合法工具协议、副作用判重、终态投影、assistant audit、消息、回执和密钥泄露均以结构化落盘事实验收。`full` 套件仍要求 External Editor API 配置，缺失时必须返回 `BLOCKED(editorApi)`，不得记为通过。

 2026-07-13 V1.3 真实验收：同一真实 Provider 套件已改为先读取 SHA-256，再用唯一一次 `project.patchset` 同时更新和创建文件，并使用自动 checkpointId 读取 2 项内容 hunks；prepared / completed 审计各 1 条、patchset revision 增量为 1，Runner 强杀恢复、命令和项目验证、双视口浏览器验证、隔离 Agent join、重复副作用与密钥扫描继续全部通过。
@@ -19,8 +19,9 @@ describe('AI 游戏创作 App 共享契约', () => {
  it('keeps command permissions explicit', () => {
    const commandIds = GAME_CREATION_APP_COMMANDS.map((command) => command.id);

-    expect(GAME_CREATION_APP_COMMANDS).toHaveLength(60);
+    expect(GAME_CREATION_APP_COMMANDS).toHaveLength(61);
    expect(commandIds).toContain('project.git_inspect');
+    expect(commandIds).toContain('project.git_commit');
    expect(commandIds).toContain('project.patchset');
    expect(commandIds).toContain('command.exec');
    expect(commandIds).toContain('command.output_read');
@@ -46,6 +47,9 @@ describe('AI 游戏创作 App 共享契约', () => {
    expect(commandIds.indexOf('command.terminate')).toBe(
      commandIds.indexOf('command.stdin') + 1,
    );
+    expect(commandIds.indexOf('project.git_commit')).toBe(
+      commandIds.indexOf('project.git_inspect') + 1,
+    );
    expect(
      GAME_CREATION_APP_COMMANDS.find((command) => command.id === 'help.show')
        ?.permission,
@@ -90,6 +94,11 @@ describe('AI 游戏创作 App 共享契约', () => {
        (command) => command.id === 'project.git_inspect',
      )?.permission,
    ).toBe('auto');
+    expect(
+      GAME_CREATION_APP_COMMANDS.find(
+        (command) => command.id === 'project.git_commit',
+      )?.permission,
+    ).toBe('confirm');
    expect(
      GAME_CREATION_APP_COMMANDS.find(
        (command) => command.id === 'project.patchset',
@@ -20,6 +20,7 @@ export const GAME_CREATION_APP_COMMANDS = [
  { id: 'project.checkpoint', permission: 'confirm' },
  { id: 'project.diff', permission: 'auto' },
  { id: 'project.git_inspect', permission: 'auto' },
+  { id: 'project.git_commit', permission: 'confirm' },
  { id: 'project.patchset', permission: 'confirm' },
  { id: 'project.restore', permission: 'confirm' },
  { id: 'project.verify', permission: 'confirm' },
@@ -21,7 +21,7 @@ pub struct GameCreationAppCommandDescriptor {
    pub permission: GameCreationAppPermission,
 }

-pub const GAME_CREATION_APP_COMMANDS: [GameCreationAppCommandDescriptor; 60] = [
+pub const GAME_CREATION_APP_COMMANDS: [GameCreationAppCommandDescriptor; 61] = [
    command("help.show", GameCreationAppPermission::Auto),
    command("project.create", GameCreationAppPermission::Confirm),
    command("project.status", GameCreationAppPermission::Auto),
@@ -29,6 +29,7 @@ pub const GAME_CREATION_APP_COMMANDS: [GameCreationAppCommandDescriptor; 60] = [
    command("project.checkpoint", GameCreationAppPermission::Confirm),
    command("project.diff", GameCreationAppPermission::Auto),
    command("project.git_inspect", GameCreationAppPermission::Auto),
+    command("project.git_commit", GameCreationAppPermission::Confirm),
    command("project.patchset", GameCreationAppPermission::Confirm),
    command("project.restore", GameCreationAppPermission::Confirm),
    command("project.verify", GameCreationAppPermission::Confirm),
@@ -679,7 +680,7 @@ mod tests {

    #[test]
    fn command_contract_keeps_expected_permissions() {
-        assert_eq!(GAME_CREATION_APP_COMMANDS.len(), 60);
+        assert_eq!(GAME_CREATION_APP_COMMANDS.len(), 61);

        let command_ids = GAME_CREATION_APP_COMMANDS
            .iter()
@@ -792,6 +793,24 @@ mod tests {
            GameCreationAppPermission::Auto
        );

+        let project_git_commit = GAME_CREATION_APP_COMMANDS
+            .iter()
+            .find(|command| command.id == "project.git_commit")
+            .expect("project.git_commit command should exist");
+        assert_eq!(
+            project_git_commit.permission,
+            GameCreationAppPermission::Confirm
+        );
+        assert_eq!(
+            command_ids
+                .iter()
+                .position(|command_id| *command_id == "project.git_commit"),
+            command_ids
+                .iter()
+                .position(|command_id| *command_id == "project.git_inspect")
+                .map(|index| index + 1)
+        );
+
        let project_verify = GAME_CREATION_APP_COMMANDS
            .iter()
            .find(|command| command.id == "project.verify")