topchester-ai 0.19.0 → 0.20.0

package/dist/cli.mjs

@@ -2212,7 +2212,7 @@ function killChild(pid, detached, signal) {
 const inspectCommandTool = defineTool({
 	name: "inspect_command",
 	description: "Run a narrowly validated read-only command for repository orientation.",
-	prompt: "inspect_command: run a safe read-only discovery command inside the workspace for quick orientation; prefer read_file, list_files, grep, and find_file for exact file tasks, and do not use it for builds, tests, installs, network, shell scripts, or edits. To use it, reply with only JSON: {\"tool\":\"inspect_command\",\"args\":{\"command\":\"pwd && rg --files docs/plans | head -20\",\"workdir\":\".\",\"timeout_ms\":10000}}",
+	prompt: "inspect_command: run a safe read-only discovery command inside the workspace for quick repo orientation; prefer read_file, list_files, grep, and find_file for exact file tasks, and do not use it for builds, tests, installs, network, shell scripts, edits, or user-requested specific commands such as node --version, which node, or pnpm --version. To use it, reply with only JSON: {\"tool\":\"inspect_command\",\"args\":{\"command\":\"pwd && rg --files docs/plans | head -20\",\"workdir\":\".\",\"timeout_ms\":10000}}",
 	argsSchema: inspectCommandArgsSchema,
 	execute: (context, args) => inspectWorkspaceCommand(context.workspaceRoot, args, { pathEnv: context.pathEnv })
 });
@@ -3259,8 +3259,8 @@ const runCommandArgsSchema = z.object({
 });
 const runCommandTool = defineTool({
 	name: "run_command",
-	description: "Run a strictly policy-approved project command inside the workspace.",
-	prompt: "run_command: run a project command only when strict policy allows it; prefer run_validator for tests, lint, typecheck, build, check, format-check, and smoke. To use it, reply with only JSON: {\"tool\":\"run_command\",\"args\":{\"command\":\"node scripts/check-fixtures.mjs\",\"workdir\":\".\",\"timeout_ms\":30000}}",
+	description: "Run a policy-gated command inside the workspace.",
+	prompt: "run_command: run a user-requested command when no more specific tool fits; it is the general policy-gated command runner, and runtime policy decides whether the command is allowed, rejected, or needs approval. Prefer run_validator for tests, lint, typecheck, build, check, format-check, and smoke. To use it, reply with only JSON: {\"tool\":\"run_command\",\"args\":{\"command\":\"node --version\",\"workdir\":\".\",\"timeout_ms\":30000}}",
 	argsSchema: runCommandArgsSchema,
 	requiresExclusiveWorkspace: true,
 	execute: async (context, args) => runWorkspaceCommand(context.workspaceRoot, args, context.config?.tools?.commands, context.runCommandApprovals?.allowExactCommands, context.pathEnv, context.abortSignal)
@@ -4457,11 +4457,14 @@ const hookEventNames = [
 	"UserPromptSubmit",
 	"PreToolUse",
 	"PostToolUse",
+	"PermissionRequest",
 	"PreCompact",
 	"Stop"
 ];
 const hookEventAliasMap = {
 	TaskStart: "SessionStart",
+	TaskAcknowledge: "UserPromptSubmit",
+	UserActionRequired: "PermissionRequest",
 	TaskComplete: "Stop"
 };
 const hookTimeoutMsSchema = z.number().int().positive().max(6e5);
@@ -4478,11 +4481,14 @@ const canonicalHooksConfigSchema = z.object({
 	UserPromptSubmit: z.array(hookHandlerSchema).optional(),
 	PreToolUse: z.array(hookHandlerSchema).optional(),
 	PostToolUse: z.array(hookHandlerSchema).optional(),
+	PermissionRequest: z.array(hookHandlerSchema).optional(),
 	PreCompact: z.array(hookHandlerSchema).optional(),
 	Stop: z.array(hookHandlerSchema).optional()
 }).strict();
 const rawHooksConfigSchema = canonicalHooksConfigSchema.extend({
 	TaskStart: z.array(hookHandlerSchema).optional(),
+	TaskAcknowledge: z.array(hookHandlerSchema).optional(),
+	UserActionRequired: z.array(hookHandlerSchema).optional(),
 	TaskComplete: z.array(hookHandlerSchema).optional()
 }).strict();
 const topchesterConfigSchema = z.object({
@@ -9219,14 +9225,24 @@ function getChatSystemPrompt(options = {}) {
 		...canUseTool("list_files") && canUseTool("grep") && canUseTool("find_file") && canUseTool("read_file") ? ["- Use list_files, grep, find_file, and read_file for exact file listing, search, lookup, and reading tasks."] : [],
 		...canUseTool("git_status") && canUseTool("git_diff") && canUseTool("git_log") ? ["- Use git_status, git_diff, and git_log for Git state, diffs, and history. Prefer these over inspect_command for Git workflow inspection."] : [],
 		...canUseTool("git_add") && canUseTool("git_commit") ? ["- Use git_add and git_commit only when the user explicitly asks to stage or commit. Never stage unrelated files, never stage '.', and never commit unless staged paths exactly match the user's request."] : [],
-		...canUseTool("inspect_command") ? ["- Use inspect_command only for quick read-only repo orientation when a short familiar command chain is clearer than several dedicated tool calls.", "- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it."] : [],
+		...canUseTool("inspect_command") ? [
+			"- Use inspect_command only for quick read-only repo orientation when the user did not ask to run a specific command and a short familiar command chain is clearer than several dedicated tool calls.",
+			"- inspect_command is not a shell. Unsafe commands, shell expansion, scripts, installs, builds, tests, network access, and file mutation are not available through it.",
+			canUseTool("run_command") ? "- Do not use inspect_command when the user asks to run a specific command such as node --version, which node, or pnpm --version; use run_command or run_validator instead." : ""
+		].filter(Boolean) : [],
 		...canUseTool("run_validator") ? [
 			"- After code edits, use run_validator when there is a relevant test, lint, typecheck, build, check, format-check, or smoke command that can prove the change.",
 			"- Failed run_validator exits are evidence. Read stdout and stderr, fix the issue when it is in scope, and rerun the narrowest useful validator.",
 			canUseTool("run_command") ? "- If run_validator is rejected because the command is not a strict validator shape but the user still needs command output, retry with run_command when project policy allows it." : "",
 			"- Do not use inspect_command for tests, builds, lint, typecheck, format checks, or smoke checks. Use run_validator for verification."
 		].filter(Boolean) : [],
-		...canUseTool("run_command") ? ["- Use run_command only for commands allowed by project command policy. Prefer dedicated read, edit, Git, and validator tools when they fit.", "- Do not use run_command for installs, deploys, network commands, destructive commands, interactive commands, file reads, file writes, Git inspection, or validation when run_validator can do it."] : [],
+		...canUseTool("run_command") ? [
+			"- When the user explicitly asks to run a command or asks for command output, use run_command unless a more specific tool is clearly the right fit.",
+			"- run_command is the general policy-gated command runner. Do not avoid it because a command might be disallowed; call run_command and let command policy return the allowed, rejected, or approval result.",
+			"- Prefer dedicated tools for file reads, file writes, edits, Git inspection, and searches.",
+			"- Use run_command only for commands allowed by project command policy. Prefer dedicated read, edit, Git, and validator tools when they fit.",
+			"- Do not use run_command for installs, deploys, network commands, destructive commands, interactive commands, file reads, file writes, Git inspection, or validation when run_validator can do it."
+		] : [],
 		...canUseTool("edit_file") && canUseTool("read_file") ? ["- Use read_file before editing a file so your edit is based on current file content and hash metadata."] : [],
 		...canUseTool("read_file") && (canUseTool("edit_file") || canUseTool("write_file")) ? ["- When passing expected_current_hash to edit_file or write_file, use the current pre-edit/pre-write hash from the latest read_file result for that exact file. Never invent it and never use a predicted after-edit or after-write hash."] : [],
 		...canUseTool("edit_file") ? ["- Use edit_file for targeted edits to existing files. Make multiple disjoint edits for the same file in one call when possible."] : [],
@@ -10190,7 +10206,8 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 			}
 			if (preHook.blocked) toolResult = createToolErrorResult(executableToolCall.tool, preHook.blocked.message);
 			else {
-				const approval = await this.resolveRunCommandApproval(executableToolCall, options);
+				const approval = await this.resolveRunCommandApproval(executableToolCall, toolCall.id, options, session, abortSignal);
+				for (const event of approval.events) yield event;
 				if (approval.cancelled) toolResult = createToolErrorResult(executableToolCall.tool, approval.reason);
 				else {
 					const toolEventQueue = createRuntimeEventQueue();
@@ -10303,16 +10320,18 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		const hookContext = formatHookContextsForPrompt(event, contexts);
 		return hookContext ? `${prompt}\n\n${hookContext}` : prompt;
 	}
-	async resolveRunCommandApproval(call, options) {
+	async resolveRunCommandApproval(call, toolCallId, options, session, abortSignal) {
 		const approvedCommands = [...this.approvedRunCommands];
 		if (call.tool !== "run_command") return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const parsed = runCommandArgsSchema.safeParse(call.args);
 		if (!parsed.success) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const decision = await validateRunCommandPolicy(parsed.data, {
 			workspaceRoot: this.context.workspaceRoot,
@@ -10321,13 +10340,31 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		});
 		if (decision.allowed) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		if (!isRunCommandApprovalEligible(decision.reason) || !options.requestRunCommandApproval) return {
 			cancelled: false,
-			approvedCommands
+			approvedCommands,
+			events: []
 		};
 		const command = decision.commands[0] ?? parsed.data.command.trim();
+		const actionRequiredHook = await this.runHookEvent("PermissionRequest", this.createToolHookPayload("PermissionRequest", call, toolCallId, session, {
+			notification_type: "permission_prompt",
+			permission_mode: "",
+			command,
+			workdir: parsed.data.workdir,
+			reason: decision.reason
+		}), {
+			toolName: call.tool,
+			abortSignal
+		});
+		const events = this.hookResultToEvents(actionRequiredHook);
+		if (actionRequiredHook.blocked || actionRequiredHook.stopped) return {
+			cancelled: true,
+			reason: (actionRequiredHook.blocked ?? actionRequiredHook.stopped).message,
+			events
+		};
 		const approval = await options.requestRunCommandApproval({
 			command,
 			workdir: parsed.data.workdir,
@@ -10335,18 +10372,21 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 		});
 		if (approval === "cancel") return {
 			cancelled: true,
-			reason: `run_command cancelled by user for '${command}'.`
+			reason: `run_command cancelled by user for '${command}'.`,
+			events
 		};
 		if (approval === "allow_session" || approval === "allow_repo") {
 			this.approvedRunCommands.add(command);
 			return {
 				cancelled: false,
-				approvedCommands: [...this.approvedRunCommands]
+				approvedCommands: [...this.approvedRunCommands],
+				events
 			};
 		}
 		return {
 			cancelled: false,
-			approvedCommands: [...approvedCommands, command]
+			approvedCommands: [...approvedCommands, command],
+			events
 		};
 	}
 	/**