@j-o-r/hello-dave 0.1.1 → 0.1.5

package/lib/genericToolset.js

@@ -1,5 +1,6 @@
-import { SH, bashEscape } from '@j-o-r/sh'
-import { ToolSet, env } from './index.js'
+import { SH } from '@j-o-r/sh'
+import ToolSet from './ToolSet.js';
+import { env } from './fafs.js'
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -16,7 +17,22 @@ const syntaxCheckSh = path.join(utilsDir, 'syntax_check.sh');
 // Do we have a SSH access point?
 const SSH_EP = process.env.SSH_EP || '';
 
-const user = await env();
+let user;
+try {
+	user = await env();
+} catch (e) {
+	user = {
+		name: process.env.USER || '',
+		system: process.platform,
+		city: '',
+		region: '',
+		country: '',
+		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || '',
+		external_ip: '',
+		cwd: process.cwd()
+	};
+}
+
 const environment = `
 Name: ${user.name}
 System: ${user.system}
@@ -29,45 +45,50 @@ ExternalIp: ${user.external_ip}
 const tools = new ToolSet('auto');
 
 /**
- * Single source of truth for cleaning over-escaped strings from LLMs.
+ * Preserve an arbitrary text argument exactly as a string.
+ *
+ * Important: do not JSON.parse arbitrary text arguments. A valid user payload
+ * can itself be a JavaScript/Bash/string literal such as `"hello"`; parsing it
+ * would remove the quotes and corrupt the code or content.
+ *
+ * @param {*} value - Candidate text value.
+ * @returns {string} Exact string value, or an empty string for non-strings.
+ */
+const exactText = (value) => typeof value === 'string' ? value : '';
+
+/**
+ * Normalize scalar selector arguments such as paths, URLs, email addresses, and
+ * subjects where accidental extra wrapping quotes are almost always unintended.
+ *
+ * This helper is intentionally not used for executable scripts or file content.
+ *
+ * @param {*} value - Candidate scalar value.
+ * @returns {*} Normalized scalar, or the original non-string value.
  */
-const guessOverEscaping = (s) => {
-	if (typeof s !== 'string') return s;
+const cleanScalar = (value) => {
+	if (typeof value !== 'string') return value;
 
-	let current = s.trim();
+	let current = value.trim();
 	const seen = new Set();
-	let iterations = 0;
-	const MAX_ITER = 6;
+	const MAX_ITER = 3;
 
-	while (iterations < MAX_ITER && !seen.has(current)) {
+	for (let i = 0; i < MAX_ITER && !seen.has(current); i++) {
 		seen.add(current);
-		iterations++;
-
-		try {
-			const parsed = JSON.parse(current);
-			if (typeof parsed === 'string') {
-				current = parsed;
-				continue;
-			}
-		} catch (e) { }
 
-		if (current.startsWith('\\"') && current.endsWith('\\"')) {
+		if (current.startsWith('\\"') && current.endsWith('\\"') && current.length > 4) {
 			current = current.slice(2, -2);
 			continue;
 		}
 
-		if (current.startsWith('"') && current.endsWith('"') && current.length > 2) {
-			const inner = current.slice(1, -1).trim();
-			if (!inner.startsWith('{') && !inner.startsWith('[')) {
-				current = inner;
-				continue;
-			}
-		}
-
-		if (!current.includes('\n') && (current.match(/\\"/g) || []).length >= 1) {
-			const lessEscaped = current.replace(/\\"/g, '"');
-			if (lessEscaped !== current) {
-				current = lessEscaped;
+		if (current.startsWith('"') && current.endsWith('"') && current.length > 1) {
+			try {
+				const parsed = JSON.parse(current);
+				if (typeof parsed === 'string') {
+					current = parsed;
+					continue;
+				}
+			} catch (_) {
+				current = current.slice(1, -1);
 				continue;
 			}
 		}
@@ -78,187 +99,489 @@ const guessOverEscaping = (s) => {
 	return current;
 };
 
+/**
+ * Extract concise JavaScript error text from Node stdin-module output.
+ * Keeps the user-facing error message, source location, and first code-frame
+ * lines while dropping Node internals and version banners.
+ *
+ * @param {string} errorStr - Raw error text.
+ * @returns {string} Condensed error text.
+ */
 const getJSError = (errorStr) => {
-	let result = '';
-	const linematch = errorStr.match(/\[eval\]:(\d+)/);
-	const lineNumber = linematch ? linematch[1] : '';
-	const match = errorStr.split(/" "\[eval\]:\d+/s);
-	if (match.length > 1) {
-		const res = match[1].split('\n').slice(0, -10).join('\n');
-		result = `Error: line ${lineNumber}\n${res} `;
+	const raw = String(errorStr || '').trim();
+	const withoutCommandPrefix = raw.replace(/^(?:Error: )?Command failed with code \d+:\s*/s, '');
+	const cleaned = withoutCommandPrefix
+		.split('\n')
+		.filter((line) => !/^\s*at (?:node:internal|ModuleJob\.|ModuleLoader\.|compileSourceTextModule|process\.|asyncRunEntryPoint|Object\.|evalModuleEntryPoint|Socket\.)/.test(line))
+		.filter((line) => !/^Node\.js v/.test(line))
+		.join('\n')
+		.trim();
+
+	const lines = cleaned.split('\n');
+	const location = lines.find((line) => /^file:\/\//.test(line));
+	const errorLine = lines.find((line) => /^(?:[A-Za-z]+Error|Error): /.test(line));
+	const frame = [];
+
+	if (location) frame.push(location);
+	for (const line of lines) {
+		if (line === location || line === errorLine) continue;
+		if (frame.length >= 3) break;
+		if (line.trim() !== '') frame.push(line);
+	}
+
+	const message = errorLine || lines.find((line) => line.trim() !== '') || 'JavaScript execution failed';
+	const prefixedMessage = message.startsWith('Error:') ? message : `Error: ${message}`;
+	return [prefixedMessage, ...frame].join('\n').trim();
+};
+
+/**
+ * Stringify a structured tool response with stable formatting.
+ * Structured responses preserve exact paths, URLs, commands, and other handles
+ * so the assistant can repeat essential references in normal conversation before
+ * raw function-call history is pruned.
+ *
+ * @param {Record<string, *>} payload - JSON-serializable tool response payload.
+ * @returns {string} Formatted JSON function response.
+ */
+const json = (payload) => JSON.stringify(payload, null, 2);
+
+/**
+ * Convert an unknown thrown value into a message.
+ *
+ * @param {*} error - Unknown error value.
+ * @returns {string} Error message.
+ */
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+
+/**
+ * Return true when child is cwd or a path inside cwd.
+ *
+ * @param {string} cwd - Real absolute CWD path.
+ * @param {string} child - Absolute candidate path.
+ * @returns {boolean} Whether child is inside cwd.
+ */
+const isInsideCwd = (cwd, child) => {
+	const relative = path.relative(cwd, child);
+	return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+/**
+ * Resolve a user-supplied path to a CWD-contained absolute path.
+ * For writes, parent directories are created safely and final symlinks are rejected
+ * if they resolve outside CWD.
+ *
+ * @param {string} file - User-supplied relative path.
+ * @param {{ forWrite?: boolean }} [options] - Resolution options.
+ * @returns {Promise<{ file: string, resolved: string }>} Clean relative and absolute paths.
+ */
+const resolveCwdPath = async (file, options = {}) => {
+	const cleaned = cleanScalar(file);
+	if (!cleaned || typeof cleaned !== 'string' || path.isAbsolute(cleaned)) {
+		throw new Error('Relative CWD path only');
+	}
+
+	const cwd = await fs.realpath(process.cwd());
+	const resolved = path.resolve(cwd, cleaned);
+	if (!isInsideCwd(cwd, resolved)) {
+		throw new Error('Path escapes CWD');
+	}
+
+	if (options.forWrite) {
+		await fs.mkdir(path.dirname(resolved), { recursive: true });
+		const parentReal = await fs.realpath(path.dirname(resolved));
+		if (!isInsideCwd(cwd, parentReal)) {
+			throw new Error('Path escapes CWD');
+		}
+
+		try {
+			const existingReal = await fs.realpath(resolved);
+			if (!isInsideCwd(cwd, existingReal)) {
+				throw new Error('Path escapes CWD');
+			}
+		} catch (e) {
+			if (e?.code !== 'ENOENT') throw e;
+		}
 	} else {
-		result = errorStr;
+		const real = await fs.realpath(resolved);
+		if (!isInsideCwd(cwd, real)) {
+			throw new Error('Path escapes CWD');
+		}
 	}
-	return result;
+
+	return { file: path.relative(cwd, resolved), resolved };
 };
 
+/**
+ * Return a structured failure response for a tool.
+ *
+ * @param {string} tool - Tool name.
+ * @param {*} error - Unknown error value.
+ * @param {Record<string, *>} [extra] - Additional response fields.
+ * @returns {string} JSON error payload.
+ */
+const toolError = (tool, error, extra = {}) => json({
+	tool,
+	success: false,
+	...extra,
+	error: errorMessage(error)
+});
+
 /**
  * @module lib/genericToolset
- * Secure utility tools. 
+ * Secure utility tools.
  */
 
 tools.add(
 	'javascript_interpreter',
-	'Execute ESM ES6 JavaScript on node.',
+	`Execute ESM ES6 JavaScript on node. Tool-specific calling rules: pass script as raw ESM JavaScript exactly as intended; preserve quotes, backticks, dollar braces, and newlines; do not JSON.parse, strip quotes, escape, shell-wrap, or otherwise transform the code. Use console.log for output. Returns structured JSON with success, output/error, and a note. If output contains exact paths, URLs, ids, or values needed later, include them verbatim in your assistant response before old tool calls are pruned.`,
 	{
 		type: 'object',
 		properties: {
 			script: {
 				type: 'string',
-				description: `ES6 ESM code. Use console.log for output. cwd: ${user.cwd}`
+				description: `Raw ES6 ESM code to execute with Node from stdin. Preserve the code exactly, including JavaScript string literal quotes such as "hello", template literals, dollar braces, and newlines. Use console.log for output. cwd: ${user.cwd}`
 			}
 		},
 		required: ['script']
 	},
 	async (params) => {
-		let response = '';
+		const tool = 'javascript_interpreter';
 		try {
-			const script = guessOverEscaping(params.script);
+			const script = exactText(params.script);
 			const delim = `JS_STDIN_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
-			response = await SH`cat <<'${delim}' | node --input-type=module -
+			const output = await SH`cat <<'${delim}' | node --input-type=module -
 ${script}
 ${delim}
 `.run();
+			return json({
+				tool,
+				success: true,
+				output,
+				note: 'Assistant: preserve exact paths, URLs, ids, and values from output in your normal response if needed for follow-up.'
+			});
 		} catch (e) {
-			response = getJSError(e.toString());
+			const error = getJSError(errorMessage(e));
+			return json({
+				tool,
+				success: false,
+				output: error,
+				error,
+				note: 'Assistant: report JavaScript errors compactly: message, relevant line/location, no Node internals unless asked.'
+			});
 		}
-		return response;
 	}
 );
 
 tools.add(
 	'get_user_env',
-	'Get user environment info.',
+	'Get user environment info. Tool-specific behavior: call with an empty object; do not invent missing fields. Returns name/location/system/cwd context as text; mention only user-relevant facts in your assistant response.',
 	{ type: 'object', properties: {} },
-	async () => environment
+	async () => json({
+		tool: 'get_user_env',
+		environment,
+		note: 'Assistant: use these environment facts only when relevant.'
+	})
 );
 
 tools.add(
 	'execute_bash_script',
-	'Execute raw bash script or command (no escaping needed). Supports timeout.',
+	'Execute raw bash script or command. Tool-specific calling rules: pass bash_script as raw Bash exactly as intended; preserve quotes, dollar signs, backticks, heredocs, and newlines; do not JSON.parse, escape, re-quote, or wrap the script. Use shellcheck=false for exploratory scripts unless the user explicitly requests linting; if shellcheck=true fails, report the ShellCheck error and do not imply the script ran. For timeout tests, report both timeout and timeoutSec from the tool result. Returns structured JSON with success, timeout, timeoutSec, and output. If output includes important paths, generated files, URLs, ids, or command results needed later, include those exact references in your assistant response before old tool calls are pruned.',
 	{
 		type: 'object',
 		properties: {
 			bash_script: {
 				type: 'string',
-				description: `Write raw bash exactly...`
+				description: 'Raw Bash to execute. Preserve exactly as intended, including quotes, variables, command substitutions, heredocs, and newlines. Do not add extra wrapping quotes or escaping.'
 			},
-			timeout: { type: 'number', default: 360 },
-			strict: { type: 'boolean', default: false }
+			timeout: {
+				type: 'number',
+				default: 360,
+				description: 'Timeout in seconds. For timeout tests, report both timeout and timeoutSec from the result.'
+			},
+			shellcheck: {
+				type: 'boolean',
+				default: false,
+				description: 'Run shellcheck before executing the script. Defaults to false; keep false for exploratory scripts unless the user explicitly asks for linting. If shellcheck fails, the script does not run.'
+			}
 		},
 		required: ['bash_script']
 	},
 	async (params) => {
-		let bash_script = params.bash_script;
-		if (typeof bash_script !== 'string') bash_script = '';
-		// Check if the bash_script string has a shebang on the first line '#!'
-		// If not, add a bash shebang
-		const firstLine = bash_script.split('\n')[0] || '';
-		if (!firstLine.trim().startsWith('#!')) {
-			bash_script = '#!/bin/bash\n' + bash_script;
+		const tool = 'execute_bash_script';
+		let timeoutSec = Number(params.timeout ?? 360);
+		try {
+			let bashScript = params.bash_script;
+			if (typeof bashScript !== 'string') bashScript = '';
+			if (!Number.isFinite(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
+			const timeout = timeoutSec * 1000;
+			const shouldRunShellcheck = Boolean(params.shellcheck ?? false);
+			if (shouldRunShellcheck) {
+				const valid = SH`shellcheck -s bash -`.runSync(bashScript).stdout.toString().trim();
+				if (valid !== '') throw new Error(valid);
+			}
+			const output = await SH`bash`.options({ timeout }).run(bashScript);
+			return json({
+				tool,
+				success: true,
+				timeout: false,
+				timeoutSec,
+				output,
+				note: 'Assistant: preserve exact paths, URLs, ids, filenames, and command results from output in your normal response if needed for follow-up.'
+			});
+		} catch (e) {
+			const message = errorMessage(e);
+			return toolError(tool, e, {
+				timeout: /timeout|timed out|killed/i.test(message),
+				timeoutSec
+			});
 		}
-		const timeoutSec = Number(params.timeout ?? 360);
-		const prams = params.strict ? '' : '-S error';
-		if (isNaN(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
-		const timeout = timeoutSec * 1000;
-		const valid = SH`shellcheck ${prams} -`.runSync(bash_script).stdout.toString().trim();
-		if (valid !== '') throw new Error(valid);
-		return await SH`bash`.options({ timeout }).run(bash_script);
 	}
 );
 
 tools.add(
-	'send_email', 'Send email via msmtp.', { type: 'object', properties: { to: { type: 'string' }, subject: { type: 'string' }, body: { type: 'string' } }, required: ['to', 'subject', 'body'] },
+	'send_email', 'Send email via msmtp. Tool-specific calling rules: to and subject are scalar fields, so do not add extra wrapping quotes; body is exact text and must preserve newlines, quotes, and formatting. Returns structured JSON with recipient and subject. After success, mention the recipient and subject exactly in your assistant response.', {
+		type: 'object',
+		properties: {
+			to: { type: 'string', description: 'Scalar recipient email address. Do not add extra wrapping quotes or newlines.' },
+			subject: { type: 'string', description: 'Scalar email subject. Do not add extra wrapping quotes or newlines.' },
+			body: { type: 'string', description: 'Exact email body text. Preserve newlines, quotes, and formatting exactly.' }
+		},
+		required: ['to', 'subject', 'body']
+	},
 	async (params) => {
-		const to = guessOverEscaping(params.to);
-		const subject = guessOverEscaping(params.subject);
-		const body = guessOverEscaping(params.body);
-		const delim = `END_EMAIL_${Date.now().toString(36)}`;
-		return await SH`msmtp ${params.to} <<'${delim}'
+		const tool = 'send_email';
+		try {
+			const to = cleanScalar(params.to);
+			const subject = cleanScalar(params.subject);
+			const body = exactText(params.body);
+			if (!to || /[\r\n]/.test(to) || /[\r\n]/.test(subject)) {
+				throw new Error('Email recipient and subject must be non-empty and must not contain newlines');
+			}
+			const delim = `END_EMAIL_${Date.now().toString(36)}`;
+			const output = await SH`msmtp ${to} <<'${delim}'
 To: ${to}
 Subject: ${subject}
 
 ${body}
 ${delim}
 `.run();
+			return json({
+				tool,
+				success: true,
+				to,
+				subject,
+				output,
+				note: 'Assistant: tell the user the email was sent and include the recipient and subject exactly.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
+		}
 	}
 );
 
 tools.add(
-	'open_link', 'Open URL/file with xdg-open.', { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
-	async (params) => await SH`xdg-open ${[guessOverEscaping(params.url)]}`.run()
+	'open_link', 'Open URL/file with xdg-open. Tool-specific calling rules: url is a scalar URL/file value; pass it without extra wrapping quotes such as "https://...". Returns structured JSON with the opened URL/file. After success, mention the exact URL/file if it is useful for follow-up.', {
+		type: 'object',
+		properties: {
+			url: { type: 'string', description: 'Scalar URL or file path to open. Do not add extra wrapping quotes.' }
+		},
+		required: ['url']
+	},
+	async (params) => {
+		const tool = 'open_link';
+		try {
+			const url = cleanScalar(params.url);
+			const output = await SH`xdg-open ${[url]}`.run();
+			return json({
+				tool,
+				success: true,
+				url,
+				output,
+				note: 'Assistant: mention the opened URL/file exactly if relevant for follow-up.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
+		}
+	}
 );
 
 tools.add(
-	'execute_remote_script', `Run bash on remote via SSH. ${SSH_EP}`,
+	'execute_remote_script', `Run bash on remote via SSH. Tool-specific calling rules: script is raw Bash and must preserve quotes, dollar signs, backticks, heredocs, and newlines exactly; url is a scalar ssh:// URL and should not have extra wrapping quotes. ${SSH_EP} Returns structured JSON with target, timeout, and output. If output contains important paths, URLs, ids, or files needed later, include them verbatim in your assistant response.`,
 	{
 		type: 'object',
 		properties: {
-			url: { type: 'string', description: `ssh://user@host[:port] default: ${SSH_EP}` },
-			script: { type: 'string' },
-			timeout: { type: 'number', default: 30 }
+			url: { type: 'string', description: `Scalar SSH URL ssh://user@host[:port]. Do not add extra wrapping quotes. Default: ${SSH_EP}` },
+			script: { type: 'string', description: 'Raw Bash to execute remotely. Preserve exactly, including quotes, variables, heredocs, and newlines.' },
+			timeout: {
+				type: 'number',
+				default: 30,
+				description: 'Remote execution timeout in seconds.'
+			}
 		},
-		required: ['url', 'script']
+		required: ['script']
 	},
 	async (params) => {
-		let { url, script } = params;
-		if (!url || url === '') url = SSH_EP;
-		url = guessOverEscaping(url);
-		script = guessOverEscaping(script);
-		const timeoutMs = (Number(params.timeout ?? 30)) * 1000;
-		if (!url.startsWith('ssh://')) throw new Error('ssh://user@host[:port]');
-		const withoutProto = url.slice(6);
-		const parts = withoutProto.split(':');
-		let port = 22, userHost = withoutProto;
-		if (parts.length > 1) { userHost = parts[0]; port = parseInt(parts[1]); }
-		const [user, host] = userHost.split('@');
-		return await SH`ssh -p ${port} ${user}@${host} bash`.options({ timeout: timeoutMs }).run(script);
+		const tool = 'execute_remote_script';
+		try {
+			let { url, script } = params;
+			if (!url || url === '') url = SSH_EP;
+			url = cleanScalar(url);
+			script = exactText(script);
+			const timeoutSec = Number(params.timeout ?? 30);
+			if (!Number.isFinite(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
+			const parsed = new URL(url);
+			if (parsed.protocol !== 'ssh:') throw new Error('Expected ssh://user@host[:port]');
+			const remoteUser = decodeURIComponent(parsed.username);
+			const host = parsed.hostname;
+			const port = parsed.port ? Number(parsed.port) : 22;
+			if (!remoteUser || !host || !Number.isInteger(port) || port < 1 || port > 65535) {
+				throw new Error('Invalid SSH URL');
+			}
+			const output = await SH`ssh -p ${port} ${remoteUser}@${host} bash`.options({ timeout: timeoutSec * 1000 }).run(script);
+			return json({
+				tool,
+				success: true,
+				url,
+				host,
+				user: remoteUser,
+				port,
+				timeoutSec,
+				output,
+				note: 'Assistant: preserve exact remote paths, URLs, ids, filenames, and command results from output in your normal response if needed for follow-up.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
+		}
 	}
 );
 
 tools.add(
-	'history_search', 'Search/list chat sessions in .cache/.',
-	{ type: 'object', properties: { query: { type: 'string' } } },
+	'history_search', 'Search/list chat sessions in .cache/. Tool-specific calling rules: query is a scalar search string; pass it without extra wrapping quotes. Omit query or pass an empty string to list sessions. Returns structured JSON with query and results. If a session id/path is useful for follow-up, include it exactly in your assistant response.',
+	{
+		type: 'object',
+		properties: {
+			query: { type: 'string', description: 'Scalar search query. Do not add extra wrapping quotes. Omit or use empty string to list sessions.' }
+		}
+	},
 	async (params) => {
-		if (typeof params.query === 'string' && params.query.trim()) {
-			return await SH`${searchSessionsSh} "${bashEscape(guessOverEscaping(params.query))}"`.run();
+		const tool = 'history_search';
+		try {
+			const query = typeof params.query === 'string' ? cleanScalar(params.query) : '';
+			const output = query.trim()
+				? await SH`${searchSessionsSh} ${[query]}`.run()
+				: await SH`${listSessionsSh}`.run();
+			return json({
+				tool,
+				success: true,
+				query,
+				output,
+				note: 'Assistant: if a session id or path is useful for follow-up, mention it exactly in your normal response.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
 		}
-		return await SH`${listSessionsSh}`.run();
 	}
 );
 
 tools.add(
-	'read_file', 'Read file from CWD (relative path only).',
-	{ type: 'object', properties: { file: { type: 'string' } }, required: ['file'] },
+	'read_file', 'Read file from CWD (relative path only). Tool-specific calling rules: file is a scalar relative path inside CWD; do not use absolute paths, parent-directory escapes, or extra wrapping quotes such as "src/file.js". Returns structured JSON with file path, byte count, and content. If this file is relevant for later edits, mention the exact relative path in your assistant response.',
+	{
+		type: 'object',
+		properties: {
+			file: { type: 'string', description: 'Scalar relative path inside CWD. Do not use absolute paths, parent-directory escapes, or extra wrapping quotes.' }
+		},
+		required: ['file']
+	},
 	async (params) => {
-		let file = guessOverEscaping(params.file?.trim());
-		if (!file || file.startsWith('/') || file.includes('..')) throw new Error('Relative CWD path only');
-		return await fs.readFile(path.resolve(process.cwd(), file), 'utf8');
+		const tool = 'read_file';
+		try {
+			const { file, resolved } = await resolveCwdPath(params.file);
+			const content = await fs.readFile(resolved, 'utf8');
+			return json({
+				tool,
+				success: true,
+				file,
+				absolutePath: resolved,
+				bytes: Buffer.byteLength(content, 'utf8'),
+				content,
+				note: 'Assistant: if this file matters for follow-up work, mention the exact relative file path in your normal response.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
+		}
 	}
 );
 
 tools.add(
-	'write_file', 'Write/validate file in CWD.',
-	{ type: 'object', properties: { file: { type: 'string' }, content: { type: 'string' } }, required: ['file', 'content'] },
+	'write_file', 'Write/validate file in CWD. Tool-specific calling rules: file is a scalar relative path inside CWD; do not use absolute paths, parent-directory escapes, or extra wrapping quotes. content is exact file content; preserve quotes, backticks, dollar braces, and newlines; do not JSON.parse, strip quotes, or reformat unless asked. Returns structured JSON with exact relative path and byte count. After success, mention the written file path exactly in your assistant response before old tool calls are pruned.',
+	{
+		type: 'object',
+		properties: {
+			file: { type: 'string', description: 'Scalar relative path inside CWD. Do not use absolute paths, parent-directory escapes, or extra wrapping quotes.' },
+			content: { type: 'string', description: 'Exact file content. Preserve quotes, backticks, dollar braces, and newlines exactly; do not JSON.parse, strip quotes, or reformat unless asked.' }
+		},
+		required: ['file', 'content']
+	},
 	async (params) => {
-		let fileParam = guessOverEscaping(params.file?.trim());
-		let content = guessOverEscaping(params.content || '');
-		if (!fileParam || fileParam.startsWith('/') || fileParam.includes('..')) throw new Error('Relative CWD path only');
-		const resolved = path.resolve(process.cwd(), fileParam);
-		await fs.mkdir(path.dirname(resolved), { recursive: true });
-		await fs.writeFile(resolved, content, 'utf8');
-		return `Wrote ${fileParam} (${Buffer.byteLength(content, 'utf8')} bytes).`;
+		const tool = 'write_file';
+		try {
+			const { file, resolved } = await resolveCwdPath(params.file, { forWrite: true });
+			const content = exactText(params.content);
+			await fs.writeFile(resolved, content, 'utf8');
+			const bytes = Buffer.byteLength(content, 'utf8');
+			return json({
+				tool,
+				success: true,
+				file,
+				absolutePath: resolved,
+				bytes,
+				message: `Wrote ${file} (${bytes} bytes).`,
+				note: 'Assistant: tell the user the exact written file path and byte count in your normal response.'
+			});
+		} catch (e) {
+			return toolError(tool, e);
+		}
 	}
 );
 
 tools.add(
-	'syntax_check', 'Syntax validate file via utils/syntax_check.sh.',
-	{ type: 'object', properties: { file: { type: 'string' } }, required: ['file'] },
+	'syntax_check', 'Syntax validate file via utils/syntax_check.sh. Tool-specific calling rules: file is a scalar relative path inside CWD; do not use absolute paths, parent-directory escapes, or extra wrapping quotes. Returns structured JSON with exact file path, status, and output. After success/failure, mention the file path and validation status exactly.',
+	{
+		type: 'object',
+		properties: {
+			file: { type: 'string', description: 'Scalar relative path inside CWD. Do not use absolute paths, parent-directory escapes, or extra wrapping quotes.' }
+		},
+		required: ['file']
+	},
 	async (params) => {
-		const file = guessOverEscaping(params.file?.trim());
-		const resolved = path.resolve(process.cwd(), file);
-		return await SH`${syntaxCheckSh} ${resolved}`.run() || 'Syntax OK';
+		const tool = 'syntax_check';
+		let file = '';
+		let resolved = '';
+		try {
+			({ file, resolved } = await resolveCwdPath(params.file));
+			const output = await SH`${syntaxCheckSh} ${resolved}`.run();
+			return json({
+				tool,
+				success: true,
+				file,
+				absolutePath: resolved,
+				status: 'ok',
+				output: output || 'Syntax OK',
+				note: 'Assistant: mention the exact file path and validation status in your normal response.'
+			});
+		} catch (e) {
+			return json({
+				tool,
+				success: false,
+				file: file || undefined,
+				absolutePath: resolved || undefined,
+				status: 'failed',
+				output: errorMessage(e),
+				error: errorMessage(e),
+				note: 'Assistant: mention the exact file path and validation status in your normal response.'
+			});
+		}
 	}
 );
 
-export default tools;
+export default tools;