Merge main into search-opens-the-selected-chat

This commit is contained in:
2026-11-13 16:26:22 +00:00
19 changed files with 562 additions and 42 deletions
@@ -22,6 +22,12 @@ class FlutterTtsSpeechEngine extends SpeechEngine {
TargetPlatform.linux || TargetPlatform.fuchsia => false,
};
@override
bool get supportsVoiceDownloadHint =>
!kIsWeb &&
(defaultTargetPlatform == TargetPlatform.iOS ||
defaultTargetPlatform == TargetPlatform.macOS);
/// AVSpeechSynthesizer's normal rate is 0.5 on a 0..1 scale; Android's
/// TextToSpeech and the Web Speech API use 1.0 as normal.
bool get _appleScale =>
@@ -106,7 +112,7 @@ class FlutterTtsSpeechEngine extends SpeechEngine {
return [
for (final item in raw is List ? raw : const [])
if (item is Map && item['name'] != null && item['locale'] != null)
SpeechVoice(name: '${item['name']}', locale: '${item['locale']}'),
SpeechVoice.fromPlatform(item.cast<Object?, Object?>()),
];
}
}
@@ -90,7 +90,12 @@ class SpeechController extends ChangeNotifier with WidgetsBindingObserver {
_set(SpeechState.speaking);
return _guard(() async {
await engine.setRate(_rate);
await engine.setVoice(voice);
final selected = voice ??
bestSpeechVoice(
await engine.voices(),
WidgetsBinding.instance.platformDispatcher.locale.languageCode,
);
await engine.setVoice(selected);
await engine.speak(document.text);
});
}
@@ -3,13 +3,63 @@ import 'package:flutter/foundation.dart';
/// One platform voice. [locale] is a BCP 47 tag such as `en-GB`.
@immutable
class SpeechVoice {
const SpeechVoice({required this.name, required this.locale});
const SpeechVoice({
required this.name,
required this.locale,
this.qualityRank = 0,
this.networkRequired = false,
});
final String name;
final String locale;
/// A platform-independent quality score: 0 is unknown/compact and 3 is
/// premium, very high, or a browser's natural voice.
final int qualityRank;
final bool networkRequired;
/// The primary language subtag (`en` for `en-GB`), lower case.
String get language => locale.split(RegExp('[-_]')).first.toLowerCase();
bool get isNatural => qualityRank >= 2;
bool get isNovelty => _noveltyVoice.hasMatch(name);
/// Converts the maps returned by flutter_tts on Apple, Android, and web.
factory SpeechVoice.fromPlatform(Map<Object?, Object?> raw) {
final name = '${raw['name'] ?? ''}';
final locale = '${raw['locale'] ?? ''}';
final quality = '${raw['quality'] ?? ''}'.toLowerCase();
final identifier = '${raw['identifier'] ?? ''}'.toLowerCase();
final network = '${raw['network_required'] ?? ''}'.toLowerCase();
var rank = switch (quality) {
'3' => 3,
'2' => 2,
'1' || '0' => 1,
'premium' || 'very high' || 'very_high' => 3,
'enhanced' || 'high' => 2,
'default' ||
'normal' ||
'standard' ||
'low' ||
'very low' ||
'very_low' => 1,
_ => 0,
};
if (identifier.contains('premium') ||
name.toLowerCase().contains(RegExp(r'\b(natural|online|neural)\b')) ||
name.toLowerCase().contains('google ')) {
rank = 3;
} else if (identifier.contains('enhanced')) {
rank = 2;
} else if (identifier.contains('compact')) {
rank = 1;
}
return SpeechVoice(
name: name,
locale: locale,
qualityRank: rank,
networkRequired: network == '1' || network == 'true',
);
}
@override
bool operator ==(Object other) =>
@@ -19,6 +69,32 @@ class SpeechVoice {
int get hashCode => Object.hash(name, locale);
}
final _noveltyVoice = RegExp(
r'\b(bells|bubbles|zarvox|whisper|boing|cellos|good news|jester|organ|superstar|trinoids)\b',
caseSensitive: false,
);
/// Picks the best automatic voice without consulting platform APIs.
SpeechVoice? bestSpeechVoice(List<SpeechVoice> voices, String language) {
final matching = voices.where(
(voice) => voice.language == language.toLowerCase(),
);
if (matching.isEmpty) return null;
final ranked = [...matching]..sort(compareSpeechVoices);
return ranked.first;
}
int compareSpeechVoices(SpeechVoice a, SpeechVoice b) {
final quality = b.qualityRank.compareTo(a.qualityRank);
if (quality != 0) return quality;
final offline = a.networkRequired ? 1 : 0;
final offlineOther = b.networkRequired ? 1 : 0;
if (offline != offlineOther) return offline.compareTo(offlineOther);
if (a.isNovelty != b.isNovelty) return a.isNovelty ? 1 : -1;
final name = a.name.compareTo(b.name);
return name != 0 ? name : a.locale.compareTo(b.locale);
}
/// The platform text-to-speech service the [SpeechController] drives.
///
/// [setRate] takes a multiplier where 1.0 is the platform's normal speed; an
@@ -30,6 +106,12 @@ abstract class SpeechEngine {
/// Whether this platform can speak at all; the UI hides read aloud if not.
bool get supported;
/// Whether this engine can offer the Apple voice-download guidance.
///
/// This is deliberately false by default: only Apple engines have the
/// matching System Settings destination.
bool get supportsVoiceDownloadHint => false;
VoidCallback? onStart;
VoidCallback? onPause;
VoidCallback? onResume;
@@ -23,11 +23,13 @@ class SettingsReadAloudSection extends StatefulWidget {
class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
SpeechController get _speech => widget.controller ?? speechController;
late final Future<List<SpeechVoice>> _voices;
@override
void initState() {
super.initState();
unawaited(_speech.restore());
_voices = _speech.voices();
}
Future<void> _pickVoice() async {
@@ -65,12 +67,13 @@ class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
title: const Text('Voice'),
subtitle: Text(
voice == null
? 'System default'
? 'Automatic (most natural)'
: '${voice.name} · ${voice.locale}',
),
chevron: true,
onTap: () => unawaited(_pickVoice()),
),
_voiceDownloadHint(context),
SettingsGroupItem(
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
@@ -131,4 +134,38 @@ class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
);
},
);
Widget _voiceDownloadHint(BuildContext context) {
return FutureBuilder<List<SpeechVoice>>(
future: _voices,
builder: (context, snapshot) {
if (!snapshot.hasData ||
!needsSpeechVoiceHint(
snapshot.data!,
View.of(context).platformDispatcher.locale.languageCode,
supportsVoiceDownloadHint:
_speech.engine.supportsVoiceDownloadHint,
)) {
return const SizedBox.shrink();
}
const hint =
'For a more natural voice, download one in System Settings > '
'Accessibility > Spoken Content > System voice > Manage voices.';
return SettingsGroupItem(
key: const Key('settings-read-aloud-voice-hint'),
child: Tooltip(
message: hint,
child: Text(
hint,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: Theme.of(context).textTheme.bodySmall?.copyWith(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
),
);
},
);
}
}
@@ -4,6 +4,17 @@ import 'package:flutter/material.dart';
import '../chat/speech/speech.dart';
bool needsSpeechVoiceHint(
List<SpeechVoice> voices,
String language, {
bool supportsVoiceDownloadHint = false,
}) {
if (!supportsVoiceDownloadHint) return false;
return voices
.where((voice) => voice.language == language.toLowerCase())
.every((voice) => !voice.isNatural);
}
/// The picker's answer: a voice, or null for the system default.
typedef SpeechVoiceChoice = ({SpeechVoice? voice});
@@ -22,7 +33,7 @@ Future<SpeechVoiceChoice?> showSpeechVoicePicker(
}
/// Voices grouped by language subtag, the [device] language first and the
/// rest by name; voices within a group by name.
/// rest by name; natural voices and offline voices come first within a group.
List<({String language, List<SpeechVoice> voices})> groupSpeechVoices(
List<SpeechVoice> voices,
String device,
@@ -41,11 +52,7 @@ List<({String language, List<SpeechVoice> voices})> groupSpeechVoices(
for (final language in languages)
(
language: language,
voices: groups[language]!
..sort((a, b) {
final name = a.name.compareTo(b.name);
return name != 0 ? name : a.locale.compareTo(b.locale);
}),
voices: groups[language]!..sort(compareSpeechVoices),
),
];
}
@@ -113,7 +120,10 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
contentPadding: const EdgeInsets.symmetric(vertical: 16),
// A list needs a definite width; keep it to a readable dialog measure.
content: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 560),
constraints: BoxConstraints(
maxWidth: 560,
maxHeight: MediaQuery.sizeOf(context).height * .6,
),
child: SizedBox(
width: double.maxFinite,
child: FutureBuilder<List<SpeechVoice>>(
@@ -122,6 +132,17 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
if (snapshot.connectionState != ConnectionState.done) {
return const Center(child: CircularProgressIndicator());
}
if (snapshot.hasError) {
return Padding(
padding: const EdgeInsets.all(24),
child: Text(
'Voices could not be loaded. You can cancel and try again.',
style: TextStyle(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
);
}
final voices = snapshot.data ?? const <SpeechVoice>[];
return _list(context, groupSpeechVoices(voices, device));
},
@@ -154,9 +175,12 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
Navigator.of(context).pop((voice: voice));
},
child: ListView(
shrinkWrap: true,
primary: false,
children: [
const RadioListTile<String>(value: '', title: Text('System default')),
const RadioListTile<String>(
value: '',
title: Text('Automatic (most natural)'),
),
if (groups.isEmpty)
Padding(
padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 8),
@@ -181,7 +205,23 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
Expanded(
child: RadioListTile<String>(
value: _keyOf(voice),
title: Text(voice.name),
title: Row(
children: [
Flexible(child: Text(voice.name)),
if (voice.isNatural)
Padding(
padding: const EdgeInsetsDirectional.only(
start: 8,
),
child: Text(
'Natural',
style: theme.textTheme.labelSmall?.copyWith(
color: theme.colorScheme.primary,
),
),
),
],
),
subtitle: Text(voice.locale),
),
),
@@ -4,16 +4,26 @@ import 'package:pipelines_app/features/chat/speech/speech.dart';
/// A scripted [SpeechEngine]: it records calls and a test fires the platform's
/// events. [stop] reports a cancel like every real platform does.
class FakeSpeechEngine extends SpeechEngine {
FakeSpeechEngine({this.supported = true, this.available = const []});
FakeSpeechEngine({
this.supported = true,
this.available = const [],
this.voiceDownloadHint = false,
this.voiceFailure = false,
});
@override
final bool supported;
final List<SpeechVoice> available;
final bool voiceDownloadHint;
final bool voiceFailure;
final calls = <String>[];
final spoken = <String>[];
double? rate;
SpeechVoice? voice;
@override
bool get supportsVoiceDownloadHint => voiceDownloadHint;
@override
Future<void> speak(String text) async {
calls.add('speak');
@@ -36,7 +46,10 @@ class FakeSpeechEngine extends SpeechEngine {
Future<void> setVoice(SpeechVoice? voice) async => this.voice = voice;
@override
Future<List<SpeechVoice>> voices() async => available;
Future<List<SpeechVoice>> voices() async {
if (voiceFailure) throw StateError('voice inventory failed');
return available;
}
/// Reports [word] (its first occurrence at or after [from]) being spoken.
void speakWord(String word, {int from = 0}) {
@@ -165,4 +165,37 @@ void main() {
expect(speech.rate, defaultSpeechRate);
expect(store.saved, (rate: defaultSpeechRate, voice: null));
});
testWidgets('an explicitly selected voice does not require voice inventory', (
tester,
) async {
engine = FakeSpeechEngine(voiceFailure: true);
reader();
const voice = SpeechVoice(name: 'Daniel', locale: 'en-GB');
// The saved selection is passed directly to the engine, even if querying
// the platform voice inventory is unavailable.
await speech.setVoice(voice);
await speech.read('a', ['Hello']);
expect(engine.voice, voice);
expect(engine.spoken, ['Hello']);
});
testWidgets(
'automatic voice selects the most natural device-language voice',
(tester) async {
engine = FakeSpeechEngine(
available: const [
SpeechVoice(name: 'Compact', locale: 'en-US', qualityRank: 1),
SpeechVoice(name: 'Enhanced', locale: 'en-US', qualityRank: 2),
SpeechVoice(name: 'French Natural', locale: 'fr-FR', qualityRank: 3),
],
);
reader();
await speech.read('a', ['Hello']);
expect(engine.voice?.name, 'Enhanced');
expect(speech.voice, isNull);
},
);
}
@@ -0,0 +1,59 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/speech/speech.dart';
void main() {
test('parses Apple quality and identifier without changing identity', () {
final voice = SpeechVoice.fromPlatform({
'name': 'Samantha',
'locale': 'en-US',
'quality': 'premium',
'identifier': 'com.apple.voice.premium.en-US.Samantha',
});
expect(voice.qualityRank, 3);
expect(voice.isNatural, isTrue);
expect(voice, const SpeechVoice(name: 'Samantha', locale: 'en-US'));
});
test('parses Android quality and prefers offline on a quality tie', () {
final online = SpeechVoice.fromPlatform({
'name': 'English online',
'locale': 'en-US',
'quality': 'very high',
'network_required': '1',
});
final offline = SpeechVoice.fromPlatform({
'name': 'English local',
'locale': 'en-US',
'quality': 'very high',
'network_required': '0',
});
expect(bestSpeechVoice([online, offline], 'en'), offline);
});
test('recognises natural web voice names', () {
final voice = SpeechVoice.fromPlatform({
'name': 'Microsoft Aria Online (Natural)',
'locale': 'en-US',
});
expect(voice.qualityRank, 3);
expect(voice.isNatural, isTrue);
});
test('picker ranking buries compact novelty voices', () {
final natural = const SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
);
final novelty = const SpeechVoice(
name: 'Zarvox',
locale: 'en-US',
qualityRank: 1,
);
expect(compareSpeechVoices(natural, novelty), lessThan(0));
});
}
@@ -7,7 +7,11 @@ import 'package:pipelines_app/features/settings/settings_voice_picker.dart';
import '../chat/speech/fake_speech_engine.dart';
const _daniel = SpeechVoice(name: 'Daniel', locale: 'en-GB');
const _samantha = SpeechVoice(name: 'Samantha', locale: 'en-US');
const _samantha = SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
);
const _thomas = SpeechVoice(name: 'Thomas', locale: 'fr-FR');
const _anna = SpeechVoice(name: 'Anna', locale: 'de-DE');
@@ -21,9 +25,16 @@ late FakeSpeechEngine _engine;
/// A fresh reader over [store], as after an app reload, and its section.
Future<SpeechController> _open(
WidgetTester tester,
MemorySpeechPreferences store,
) async {
_engine = FakeSpeechEngine(available: [_samantha, _thomas, _anna, _daniel]);
MemorySpeechPreferences store, {
List<SpeechVoice>? available,
bool voiceDownloadHint = false,
bool voiceFailure = false,
}) async {
_engine = FakeSpeechEngine(
available: available ?? [_samantha, _thomas, _anna, _daniel],
voiceDownloadHint: voiceDownloadHint,
voiceFailure: voiceFailure,
);
final speech = SpeechController(engine: _engine, store: store);
addTearDown(speech.dispose);
await tester.pumpWidget(
@@ -47,10 +58,11 @@ void main() {
addTearDown(tester.platformDispatcher.clearLocaleTestValue);
final store = MemorySpeechPreferences();
await _open(tester, store);
expect(find.text('System default'), findsOneWidget);
expect(find.text('Automatic (most natural)'), findsOneWidget);
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
expect(find.text('Natural'), findsOneWidget);
// Grouped by language, the device's language first.
final french = tester.getTopLeft(find.text('French')).dy;
final english = tester.getTopLeft(find.text('English')).dy;
@@ -59,7 +71,7 @@ void main() {
expect(english, lessThan(german));
expect(
tester.getTopLeft(find.text('Daniel')).dy,
lessThan(tester.getTopLeft(find.text('Samantha')).dy),
greaterThan(tester.getTopLeft(find.text('Samantha Enhanced')).dy),
);
await tester.tap(find.text('Daniel'));
@@ -108,7 +120,7 @@ void main() {
expect(speech.voice, isNull);
expect(speech.rate, defaultSpeechRate);
expect(store.saved, (rate: defaultSpeechRate, voice: null));
expect(find.text('System default'), findsOneWidget);
expect(find.text('Automatic (most natural)'), findsOneWidget);
expect(find.text('Speaking rate 1.0×'), findsOneWidget);
expect(tester.widget<TextButton>(_reset).onPressed, isNull);
});
@@ -130,7 +142,7 @@ void main() {
// Each voice in the picker has its own sample; it does not choose it.
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
await tester.tap(find.byTooltip('Play sample of Samantha'));
await tester.tap(find.byTooltip('Play sample of Samantha Enhanced'));
await tester.pump();
expect(_engine.voice, _samantha);
expect(_engine.spoken, hasLength(2));
@@ -140,9 +152,72 @@ void main() {
expect(speech.state, SpeechState.idle, reason: 'closing stops the sample');
});
testWidgets(
'shows the Apple download hint only for a non-natural inventory',
(tester) async {
tester.platformDispatcher.localeTestValue = const Locale('en', 'US');
addTearDown(tester.platformDispatcher.clearLocaleTestValue);
final store = MemorySpeechPreferences();
await _open(
tester,
store,
available: const [
SpeechVoice(
name: 'Samantha Compact',
locale: 'en-US',
qualityRank: 1,
),
],
voiceDownloadHint: true,
);
expect(
find.textContaining('download one in System Settings'),
findsOneWidget,
);
final hint = tester.widget<Text>(
find.descendant(
of: find.byKey(const Key('settings-read-aloud-voice-hint')),
matching: find.byType(Text),
),
);
expect(hint.maxLines, 1);
expect(
tester
.getTopLeft(find.byKey(const Key('settings-read-aloud-voice-hint')))
.dy,
greaterThan(tester.getTopLeft(_voiceRow).dy),
);
expect(
tester.getTopLeft(find.text('Speaking rate 1.0×')).dy,
greaterThan(
tester
.getTopLeft(
find.byKey(const Key('settings-read-aloud-voice-hint')),
)
.dy,
),
);
},
);
testWidgets('failed voice inventory is safe and dismissible', (tester) async {
final speech = await _open(
tester,
MemorySpeechPreferences(),
voiceFailure: true,
);
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
expect(find.textContaining('Voices could not be loaded'), findsOneWidget);
expect(find.text('This device offers no other voices.'), findsNothing);
await tester.tap(find.text('Cancel'));
await tester.pumpAndSettle();
expect(speech.state, SpeechState.idle);
});
test('voices group by language, device language first', () {
final groups = groupSpeechVoices([_samantha, _anna, _daniel], 'de');
expect(groups.map((group) => group.language), ['de', 'en']);
expect(groups.last.voices, [_daniel, _samantha]);
expect(groups.last.voices, [_samantha, _daniel]);
});
}
+49 -10
View File
@@ -9,15 +9,31 @@ import 'package:pipelines_app/features/chat/speech/speech.dart';
void installSpeechFixture(Map<String, String> params) {
if (params['speech'] != 'fake') return;
final step = int.tryParse(params['speechStep'] ?? '') ?? 600;
final hint = params['speechHint'] == '1';
final empty = params['speechEmpty'] == '1';
final failure = params['speechFailure'] == '1';
debugSpeechController = SpeechController(
engine: _ScriptedSpeechEngine(Duration(milliseconds: step)),
engine: _ScriptedSpeechEngine(
Duration(milliseconds: step),
appleHint: hint,
empty: empty,
failure: failure,
),
);
}
class _ScriptedSpeechEngine extends SpeechEngine {
_ScriptedSpeechEngine(this.step);
_ScriptedSpeechEngine(
this.step, {
this.appleHint = false,
this.empty = false,
this.failure = false,
});
final Duration step;
final bool appleHint;
final bool empty;
final bool failure;
Timer? _timer;
String _text = '';
List<Match> _words = const [];
@@ -27,6 +43,9 @@ class _ScriptedSpeechEngine extends SpeechEngine {
@override
bool get supported => true;
@override
bool get supportsVoiceDownloadHint => appleHint;
@override
Future<void> speak(String text) async {
if (_paused && text == _text) {
@@ -81,12 +100,32 @@ class _ScriptedSpeechEngine extends SpeechEngine {
Future<void> setVoice(SpeechVoice? voice) async {}
@override
Future<List<SpeechVoice>> voices() async => const [
SpeechVoice(name: 'Samantha', locale: 'en-US'),
SpeechVoice(name: 'Daniel', locale: 'en-GB'),
SpeechVoice(name: 'Karen', locale: 'en-AU'),
SpeechVoice(name: 'Thomas', locale: 'fr-FR'),
SpeechVoice(name: 'Anna', locale: 'de-DE'),
SpeechVoice(name: 'Kyoko', locale: 'ja-JP'),
];
Future<List<SpeechVoice>> voices() async {
if (failure) throw StateError('fixture voice inventory failed');
if (empty) return const [];
return [
const SpeechVoice(
name: 'Samantha Compact',
locale: 'en-US',
qualityRank: 1,
),
if (!appleHint)
const SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
),
if (!appleHint)
const SpeechVoice(
name: 'Microsoft Aria Online (Natural)',
locale: 'en-US',
qualityRank: 3,
),
const SpeechVoice(name: 'Bells', locale: 'en-US', qualityRank: 1),
const SpeechVoice(name: 'Daniel', locale: 'en-GB', qualityRank: 1),
const SpeechVoice(name: 'Thomas', locale: 'fr-FR', qualityRank: 1),
const SpeechVoice(name: 'Anna', locale: 'de-DE', qualityRank: 1),
const SpeechVoice(name: 'Kyoko', locale: 'ja-JP', qualityRank: 1),
];
}
}
+5
View File
@@ -59,6 +59,11 @@ blocks; stages communicate through `output.md` (`# handoff`) and `public/`.
`pipelines submit DRAFT` publishes a new immutable version.
`pipelines help <command>` has flags.
Stage `tools` blocks may use `mcp:<server>` or `mcp:<server>/<tool>` for
Claude-only, allowlisted MCP access. Prefer read-only tools; unattended stages
deny every MCP tool not listed. The name is the Claude Code display name
(mapped internally to `mcp__<server>__<tool>`).
## References
Read only what the task needs. Rows marked operator only are for setting up or
+10 -1
View File
@@ -121,7 +121,8 @@ evidence route to `blocked` when declared, else `error`; never fabricate a resul
## Tools and permissions
`tools` lists `read`, `glob`, `grep`, `webfetch`, `websearch`, `edit`, `shell`,
one per line; an empty block denies all and a missing block grants local
or (Claude stages only) `mcp:<server>` / `mcp:<server>/<tool>`, one per line;
an empty block denies all and a missing block grants local
read/glob/grep/edit/shell (prefer explicit). Roles: `plan` reads (web only when
external knowledge is needed); `implement` reads, edits and runs shell; `review`
reads and may use shell for `git diff`, never edits; `land` has read/glob/grep and
@@ -134,6 +135,14 @@ enables a missing one. Empty arrays deny; wildcards, chaining, redirects and
traversal are rejected. With restricted edits and shell enabled, list shell too:
`{"edit":["README.md","plugin/*.qml"],"shell":["bash -n install.sh"]}`.
Named MCP entries are an explicit allowlist for unattended Claude stages:
`mcp:ai-memory` allows that server's tools, while `mcp:linear/list_issues`
allows one tool. Names are the server/tool names Claude Code displays (mapped
internally to `mcp__<server>__<tool>`; claude.ai connectors may look like
`claude_ai_Linear`). Other harnesses reject these entries. Prefer read-only
MCP tools; server configuration is not inspected during validation, so an
unknown name may fail at runtime.
## Checks
Every model stage that can modify the workspace (`edit` or `shell`, no `tools`
@@ -44,3 +44,9 @@ OS sandbox: approved shell can have broad side effects. Usage accumulates across
attempts and visits; missing required accounting fails closed. Session/RPC audit
lives in the execution user's cache under `pipelines/pi-sessions`; unconfirmed
cleanup blocks continuation and retry.
Claude stages may additionally allow named MCP servers/tools in the `tools`
block. These are Claude-only, exact allowlist entries; other MCP tools remain
denied in unattended `dontAsk` sessions. Use `mcp:<server>` or
`mcp:<server>/<tool>` with names as Claude Code displays them, and prefer
read-only tools.
+4 -3
View File
@@ -9,7 +9,8 @@ import (
)
func TestToolsBlockPersistenceAndAdapter(t *testing.T) {
source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nwebsearch\nwebfetch\n```", 1)
source := strings.Replace(Template([]string{"one"}, true), "```tools\n```", "```tools\nmcp:ai-memory\nmcp:linear/list_issues\n```", 1)
source = strings.Replace(source, "provider=opencode-go", "provider=anthropic\nharness=claude", 1)
store, err := Open(filepath.Join(t.TempDir(), "tools.db"))
if err != nil {
t.Fatal(err)
@@ -25,10 +26,10 @@ func TestToolsBlockPersistenceAndAdapter(t *testing.T) {
t.Fatal(err)
}
tools, explicit, err := stage.ToolNames(StageDefinition(d.Graph.Stages[0]))
if err != nil || !explicit || len(tools) != 2 || tools[0] != "websearch" {
if err != nil || !explicit || len(tools) != 2 || tools[0] != "mcp:ai-memory" || tools[1] != "mcp:linear/list_issues" {
t.Fatal("tool allowlist lost", tools, explicit, err)
}
if _, err := Parse(strings.Replace(source, "websearch\nwebfetch", "websearch\nunknown", 1)); err == nil {
if _, err := Parse(strings.Replace(source, "mcp:ai-memory\nmcp:linear/list_issues", "mcp:bad name", 1)); err == nil {
t.Fatal("unknown tool accepted")
}
}
+32 -2
View File
@@ -88,12 +88,36 @@ func claudeTools(tools []string) ([]string, error) {
case "websearch":
names = append(names, "WebSearch")
default:
if _, _, ok, err := MCPToolName(tool); err != nil {
return nil, err
} else if ok {
continue
}
return nil, fmt.Errorf("Claude Code has no audited builtin for %s; choose read/glob/grep/edit/shell/webfetch/websearch", tool)
}
}
return names, nil
}
func claudeMCPAllowRules(tools []string) ([]string, error) {
var rules []string
for _, name := range tools {
server, tool, ok, err := MCPToolName(name)
if err != nil {
return nil, err
}
if !ok {
continue
}
rule := "mcp__" + server + "__*"
if tool != "" {
rule = "mcp__" + server + "__" + tool
}
rules = append(rules, rule)
}
return rules, nil
}
// claudeAllowRules are the pre-approved permission rules. File edits are
// approved only below the run directory and the stage's artifacts directory;
// everything else a declared tool does not need approval for stays denied by
@@ -126,10 +150,16 @@ func (c *ClaudeStageClient) args(config ModelConfig, tools []string, effort stri
"--model", config.Model,
"--permission-mode", "dontAsk",
"--setting-sources", "",
"--strict-mcp-config",
"--disable-slash-commands",
"--tools", strings.Join(tools, ",")}
if rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir); len(rules) > 0 {
mcpRules, _ := claudeMCPAllowRules(c.Tools)
if len(mcpRules) == 0 {
tail := append([]string(nil), args[10:]...)
args = append(append(append([]string(nil), args[:10]...), "--strict-mcp-config"), tail...)
}
rules := claudeAllowRules(tools, c.Directory, c.ArtifactsDir)
rules = append(rules, mcpRules...)
if len(rules) > 0 {
args = append(args, "--allowedTools")
args = append(args, rules...)
}
+24
View File
@@ -217,6 +217,30 @@ func TestClaudeStageDeclaredToolsAreTheOnlyTools(t *testing.T) {
}
}
func TestClaudeStageNamedMCPToolsAreAllowlistedSeparately(t *testing.T) {
client, root, _ := fakeClaudeClient(t, "success")
client.Tools = []string{"read", "mcp:ai-memory", "mcp:linear/list_issues"}
if _, err := client.Generate(context.Background(), claudeConfig(nil), "task"); err != nil {
t.Fatal(err)
}
calls := fakeClaudeArgs(t, root)
if len(calls) != 1 {
t.Fatal(calls)
}
args := calls[0]
if slices.Contains(args, "--strict-mcp-config") {
t.Fatal("MCP-enabled stage must not use strict MCP config")
}
for _, want := range []string{"--tools", "Read", "--allowedTools", "Read", "mcp__ai-memory__*", "mcp__linear__list_issues"} {
if !slices.Contains(args, want) {
t.Fatalf("missing %q in args %q", want, args)
}
}
if slices.Contains(args, "mcp:ai-memory") || slices.Contains(args, "mcp:linear/list_issues") {
t.Fatalf("MCP entries leaked into builtin tools: %q", args)
}
}
func TestClaudeStageRefusesWhatItCannotEnforce(t *testing.T) {
for name, change := range map[string]func(*ClaudeStageClient, *ModelConfig){
"write paths": func(c *ClaudeStageClient, _ *ModelConfig) { c.WritePaths = []string{"app"} },
+8
View File
@@ -118,6 +118,14 @@ func (ModelStage) Spec(def Definition) (ModelSpec, error) {
return ModelSpec{}, err
}
}
if backend != ClaudeBackend {
tools, _, _ := ToolNames(def)
if mcp, err := MCPTools(tools); err != nil {
return ModelSpec{}, err
} else if len(mcp) > 0 {
return ModelSpec{}, fmt.Errorf("named MCP tools are supported only by the claude harness; remove mcp: entries or set harness=claude")
}
}
if backend == ClaudeBackend {
if def.Configs["provider"] != ClaudeProvider {
return ModelSpec{}, fmt.Errorf("the claude harness needs provider=%s", ClaudeProvider)
+32 -1
View File
@@ -148,7 +148,11 @@ func ToolNames(def Definition) ([]string, bool, error) {
switch name {
case "websearch", "webfetch", "read", "glob", "grep", "edit", "shell":
default:
return nil, true, fmt.Errorf("unsupported tool %q", name)
if _, _, ok, err := MCPToolName(name); err != nil {
return nil, true, err
} else if !ok {
return nil, true, fmt.Errorf("unsupported tool %q", name)
}
}
if seen[name] {
return nil, true, fmt.Errorf("duplicate tool %s", name)
@@ -165,6 +169,33 @@ func ToolNames(def Definition) ([]string, bool, error) {
// text-only stage.
var legacyTools = []string{"read", "glob", "grep", "edit", "shell"}
var mcpToolName = regexp.MustCompile(`^mcp:([A-Za-z0-9_-]+)(?:/([A-Za-z0-9_-]+))?$`)
// MCPToolName validates and splits a named MCP allowlist entry.
func MCPToolName(name string) (server, tool string, ok bool, err error) {
if !strings.HasPrefix(name, "mcp:") {
return "", "", false, nil
}
match := mcpToolName.FindStringSubmatch(name)
if match == nil {
return "", "", true, fmt.Errorf("invalid MCP tool %q; use mcp:<server> or mcp:<server>/<tool> with letters, digits, _ or -", name)
}
return match[1], match[2], true, nil
}
// MCPTools returns named MCP entries in declaration order.
func MCPTools(tools []string) ([]string, error) {
var result []string
for _, name := range tools {
if _, _, ok, err := MCPToolName(name); err != nil {
return nil, err
} else if ok {
result = append(result, name)
}
}
return result, nil
}
// effectiveTools is the single materialisation point for the tools a model
// stage is permitted. A present tools block (including an explicit empty block)
// is returned exactly as parsed by ToolNames; an absent block yields the legacy
+17
View File
@@ -26,6 +26,23 @@ func TestToolsValidation(t *testing.T) {
}
}
func TestNamedMCPToolsValidation(t *testing.T) {
for _, name := range []string{"mcp:", "mcp:/tool", "mcp:server/", "mcp:server/tool/extra", "mcp:server tool"} {
if _, _, _, err := MCPToolName(name); err == nil {
t.Fatalf("accepted malformed MCP tool %q", name)
}
}
def := Definition{Type: ModelType, Blocks: map[string]string{
"prompt": "task", "configs": "provider=opencode-go\nmodel=model",
}, Configs: map[string]string{
"provider": "opencode-go", "model": "model",
}}
def.Blocks["tools"] = "mcp:linear/list_issues"
if err := (ModelStage{}).Validate(def); err == nil || !strings.Contains(err.Error(), "only by the claude harness") {
t.Fatalf("non-Claude MCP stage error = %v", err)
}
}
func TestModelStageBindsExplicitToolPolicyToAgentSession(t *testing.T) {
for _, tools := range []string{"websearch\nwebfetch", ""} {
client := &AgentClient{Tools: []string{"read", "edit", "shell"}, WritePaths: []string{"one.go"}}