@topolo/cli 0.13.17 → 0.13.21

package/agent-packs/src/topolo_agent_pack/claude_desktop.py

@@ -0,0 +1,181 @@
+"""Task workers in the already authenticated Claude Desktop process.
+
+The closed native endpoint survives closing the temporary setup inspector.
+It exposes task lifecycle operations only, never vendor credentials or eval.
+"""
+import asyncio
+import hashlib
+import json
+import os
+import pathlib
+import shlex
+import socket
+import stat
+import sys
+
+from .claude_runner import public_progress
+from .storage import read_json, canonical, atomic_json
+from .work import require
+
+
+def call(connection, operation):
+    info = pathlib.Path(connection['secretPath'])
+    metadata = info.lstat()
+    require(stat.S_ISREG(metadata.st_mode) and metadata.st_uid == os.getuid()
+            and metadata.st_mode & 0o077 == 0, 'Unowned native task connection secret')
+    target = pathlib.Path(connection['socket']).lstat()
+    require(stat.S_ISSOCK(target.st_mode) and target.st_uid == os.getuid(), 'Unowned native task socket')
+    secret = read_json(info)
+    payload = {'pid': connection['pid'], 'identity': connection['identity'],
+               'token': secret['token'], 'operation': operation}
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as channel:
+        channel.settimeout(65)
+        channel.connect(connection['socket'])
+        channel.sendall(canonical(payload) + b'\n')
+        with channel.makefile('rb') as stream:
+            raw = stream.readline(1048577)
+    require(raw.endswith(b'\n') and len(raw) <= 1048576, 'Native task response is missing or exceeds its boundary')
+    result = json.loads(raw)
+    require(set(result) == {'result'}, 'Native task operation refused: ' + str(result.get('error', 'invalid response')))
+    return result['result']
+
+
+def authorize(root, operation):
+    """Independent cloud read before a native creation, send or archive."""
+    from .cloud_work import CloudStore
+    from .work_artifacts import read_checkpoint
+    plan = operation['plan']
+    store = CloudStore(root)
+    worker = store.worker(plan['workerId'])
+    task = store.get(worker['taskId'])
+    require(task.get('ownerInstallationId') == store.binding['installationId']
+            and worker.get('nativePlan') == plan and worker['taskId'] == plan['taskId']
+            and worker['nativeId'] == plan['nativeId'], 'Native worker cloud ownership differs')
+    if operation['kind'] == 'create':
+        require(set(operation) == {'kind', 'plan', 'files'} and worker['state'] == 'creating'
+                and hashlib.sha256(canonical(operation['files'])).hexdigest() == plan['contextDigest'],
+                'Native creation has no exact cloud reservation')
+    elif operation['kind'] == 'send':
+        require(set(operation) == {'kind', 'plan', 'workerId', 'assignment'}
+                and worker['state'] == 'running' and worker['turnId'] == operation['assignment']['messageId']
+                and worker['resolution']['nativeACK'] == {'model': plan['model'], 'effort': plan['effort']},
+                'Native assignment has no acknowledged cloud delivery reservation')
+    else:
+        require(operation['kind'] == 'archive' and
+                set(operation) == {'kind', 'plan', 'workerId', 'messageId', 'terminal'}
+                and worker['state'] == 'archiving', 'Native archival has no checkpointed worker')
+        payload = read_checkpoint(store.root, worker['checkpoint'], task['id'], worker['id'])
+        receipt = payload['nativeReceipt']
+        terminal = operation['terminal']
+        require(receipt['status'] == 'completed' and receipt['threadId'] == plan['nativeId']
+                and receipt['turnId'] == operation['messageId'] == terminal['messageId']
+                and receipt['producer']['resultId'] == terminal['resultUuid'],
+                'Native archival differs from the verified cloud checkpoint')
+    return {'authorized': True}
+
+
+def main():
+    try:
+        raw = sys.stdin.read(262145)
+        require(len(raw) <= 262144 and len(sys.argv) == 2, 'Bounded native authority request required')
+        print(json.dumps(authorize(sys.argv[1], json.loads(raw))))
+        return 0
+    except Exception as exc:
+        print('Native cloud authority refused: ' + str(exc), file=sys.stderr)
+        return 2
+
+
+class Session:
+    def __init__(self, cwd, worker_id, model, effort, progress=None):
+        self.cwd = pathlib.Path(cwd)
+        self.id = worker_id
+        self.model = model
+        self.effort = effort
+        self.progress = progress
+        self.plan = None
+        self.connection = None
+        self.results = {}
+        self.pending = None
+        self.assigned = False
+        self.closed = False
+        self.archived = False
+        self.allow_tools = True
+        self.directory = self.cwd / '.topolo-worker'
+        self.directory.mkdir(mode=0o700)
+        atomic_json(self.directory / 'gate.json', {'sessionId': None, 'model': model,
+                    'effort': effort, 'phase': 'readiness'})
+        adapter = pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'
+        command = shlex.join([sys.executable, str(adapter), 'work', 'claude-worker-hook',
+                             '--harness', 'claude', '--input', str(self.directory)]) + ' || exit 2'
+        atomic_json(self.cwd / '.claude/settings.json', {'autoMemoryEnabled': False,
+                    'hooks': {'PreToolUse': [{'hooks': [{'type': 'command', 'command': command, 'timeout': 15}]}]}})
+
+    async def operation(self, value):
+        require(self.connection is not None, 'The signed-in Desktop task connection is unavailable')
+        return await asyncio.to_thread(call, self.connection, value)
+
+    async def start(self):
+        require(self.plan is not None, 'Exact cloud-reserved native plan required')
+        files = {str(p): hashlib.sha256(p.read_bytes()).hexdigest()
+                 for p in sorted(self.cwd.rglob('*')) if p.is_file() and not p.is_relative_to(self.directory)}
+        require(hashlib.sha256(canonical(files)).hexdigest() == self.plan['contextDigest'],
+                'Selected native context changed before creation')
+        await self.operation({'kind': 'create', 'plan': self.plan, 'files': files})
+        result = await self.wait(self.id)
+        require(result['output'].strip() == 'TOPOLO_WORKER_READY:' + self.id and result['toolItems'] == 0,
+                'Exact tool-free native readiness did not complete')
+        self.sdk_session = result['nativeSessionId']
+        return {'sessionId': self.plan['nativeId'], 'processId': self.connection['pid'],
+                'model': self.model, 'effort': self.effort, 'boundary': 'signed-in Desktop native terminal producer'}
+
+    async def assign(self, message_id, prompt):
+        require(not self.assigned and not self.closed and self.pending is None,
+                'This native worker already has an assignment; reconcile without resend')
+        self.assigned = True
+        self.pending = message_id
+        atomic_json(self.directory / 'gate.json', {'sessionId': self.sdk_session, 'model': self.model,
+                    'effort': self.effort, 'phase': 'assigned', 'allowTools': self.allow_tools})
+        await self.operation({'kind': 'send', 'workerId': self.id,
+                              'assignment': {'messageId': message_id, 'prompt': prompt}})
+        return await self.wait(message_id)
+
+    async def wait(self, message_id):
+        seen = set()
+        async with asyncio.timeout(1800):
+            while True:
+                result = await self.operation({'kind': 'read', 'workerId': self.id, 'messageId': message_id})
+                if self.assigned and self.progress:
+                    for row in result['messages']:
+                        if row['id'] not in seen and public_progress(row['text']):
+                            await self.progress(row['id'], row['text'][:1600])
+                            seen.add(row['id'])
+                if result['state'] == 'native-task-completed':
+                    require(result['nativeId'] == self.plan['nativeId'] and result['messageId'] == message_id
+                            and result['model'] == self.model and result['effort'] == self.effort,
+                            'Native terminal identity or settings differ')
+                    receipt = {'id': message_id, 'status': 'completed', 'output': result['result'],
+                               'toolItems': result['toolItems'], 'nativeSessionId': result['cliSessionId'],
+                               'nativeResultId': result['resultUuid']}
+                    self.results[message_id] = receipt
+                    self.pending = None
+                    return receipt
+                require(result['state'] == 'native-task-pending', 'Native task state is unqualified')
+                await asyncio.sleep(1)
+
+    async def archive(self, message_id):
+        result = await self.operation({'kind': 'archive', 'workerId': self.id, 'messageId': message_id})
+        require(result['state'] == 'native-worker-archived' and result['nativeId'] == self.plan['nativeId'],
+                'Native Desktop worker archival was not acknowledged')
+        self.closed = True
+        self.archived = True
+        return {'kind': 'native-desktop-session', 'desktopChatArchived': True, **result}
+
+    async def close(self):
+        # An uncertain task stays visible and owned. Closing an adapter is never
+        # represented as archival, and never cancels or deletes native work.
+        self.closed = True
+        return {'state': 'native-session-preserved', 'desktopChatArchived': self.archived}
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/agent-packs/src/topolo_agent_pack/claude_dispatch.py

@@ -0,0 +1,240 @@
+"""Claude subscription workers behind Desktop's three permanent front doors.
+
+Uses the same cloud state, checkpoints, review phases and Activity events as the
+Codex broker. It does not launch a competing local task ledger or import history.
+"""
+import asyncio
+import hashlib
+import copy
+import pathlib
+import sys
+import types
+import uuid
+
+from . import task_models
+from .claude_desktop import Session
+from .cicd import RELEASE_RISK_TYPES
+from .role_catalog import digest
+from .storage import atomic_json, read_json, component_key, canonical
+from .work import require
+from .work_native import Broker
+
+
+class ClaudeBroker(Broker):
+    def __init__(self, lib, session_factory=Session):
+        owner = types.SimpleNamespace(lib=lib, runtime=str(lib.root / 'claude/task-runtime'),
+                    execution=types.SimpleNamespace(roles={}, verified=set()))
+        super().__init__(owner)
+        require(getattr(self.store, 'cloud', False), 'Claude dispatch requires cloud authority; no local fallback')
+        self.factory = session_factory
+        self.sessions = {}
+
+    async def initialize(self):
+        await self.state_call('snapshot')
+        self.config()
+        for channel in ['engineering', 'operations', 'cicd']:
+            config, _, _ = self.config(channel)
+            await asyncio.to_thread(self.qualify, config)
+        workers = await self.state_call('workers')
+        for task in await self.state_call('list'):
+            if task.get('ownerInstallationId') == self.store.binding['installationId'] or task.get('resumeAfterCheckpoint') is not True:
+                continue
+            if task['state'] not in {'queued', 'executing', 'reviewing'}:
+                continue
+            owned = [w for w in workers if w['taskId'] == task['id']]
+            phase = {'queued': 'route', 'executing': 'execute', 'reviewing': 'review'}[task['state']]
+            if any(w['phase'] == phase and w.get('attempt', 1) == task.get('attempt', 1)
+                   and (phase != 'review' or w.get('reviewGeneration', 0) == task.get('reviewGeneration', 0)) for w in owned):
+                continue
+            if not all(w['state'] == 'archived' and w.get('nativeArchived') is True or
+                       w['state'] == 'failed' and not w.get('turnId') and
+                       (not w.get('nativeId') or w.get('nativeArchived') is True) for w in owned):
+                continue
+            await self.state_call('adopt_ready', task['id'], task['revision'])
+
+    def config(self, channel='engineering'):
+        root = self.store.root
+        saved = read_json(root / 'config.json')
+        catalog = read_json(root / 'role-catalog.json')
+        require(saved.get('format') == 'topolo-task-dispatch-v2'
+                and saved.get('requireCloudAuthority') is True and saved.get('frontdoorDispatch') is True,
+                'Claude requires the source-independent cloud dispatcher')
+        require(catalog.get('format') == 'topolo-task-role-catalog-v1'
+                and catalog.get('pack') == saved['pack'] and digest(catalog) == saved['catalogDigest'],
+                'Reviewed specialization catalog changed')
+        native, revision = self.owner.lib.load(saved['pack'])
+        require(revision == catalog['nativePackRevision'] and len(native['agents']) == 3,
+                'The three-coordinator installation changed')
+        require(channel in catalog['channels'] and type(saved['maxWorkers']) is int
+                and 1 <= saved['maxWorkers'] <= 8, 'Unknown channel or invalid worker capacity')
+        registry = read_json(root / 'role-bindings.json')
+        require(registry.get('organizationId') == 'org_topolo_platform'
+                and registry.get('roles') == catalog['bindings'], 'Agent definition references differ')
+        selected = catalog['channels'][channel]
+        manifest = {'packId': saved['pack'], 'sourceIndependent': True,
+                    'agents': [r for r in catalog['roles'] if component_key(r) in selected['roleKeys']]}
+        return {**selected, 'pack': saved['pack'], 'catalogOnly': True,
+                'maxWorkers': saved['maxWorkers']}, manifest, {
+                'configuration': catalog['configuration'], 'constraints': catalog['constraints']}
+
+    def qualify(self, config):
+        from .permissions import load
+        from .topolo import Client, organization_execution_policy
+        native, _ = self.owner.lib.load(config['pack'])
+        consent = load(self.owner.lib, config['pack'], native['agents'])
+        require(consent is not None and consent['profile'] == 'full-access',
+                'Explicit organization-bound full-access installation consent is required')
+        key = config['pack'] + '/intakes/' + config['intakeRole']
+        require(consent.get('overrides', {}).get(key, consent['profile']) == 'full-access',
+                'Selected channel does not have full-access installation consent')
+        client = Client('production', 'org:org_topolo_platform')
+        policy, proof = organization_execution_policy(client, consent, native['agents'],
+                                                       consent.get('agentWorkspaceId'))
+        require(policy.get('scopePolicyMode') == 'unrestricted' and policy.get('fullAccessEnabled') is True
+                and proof['profileCeilingVerified'],
+                'This worker cannot enforce an organization tool/action allowlist; execution remains blocked')
+        self.tool_path = client.env['PATH']
+
+    async def start(self, task, phase, config, manifest, models):
+        await asyncio.to_thread(self.qualify, config)
+        if phase == 'route':
+            role_id = config['intakeRole']
+            model_task = {'type': 'route-request', 'complexity': 'routine', 'risk': 'normal'}
+        elif phase == 'execute':
+            role_id, model_task = task['route']['role'], task['route']['task']
+        else:
+            role_id = config['reviewRole']
+            model_task = {**task['route']['task'], 'type': 'verify-task',
+                          'complexity': 'complex' if task['route']['task']['risk'] == 'security-critical'
+                          or task['channel'] == 'cicd' and task['route']['task']['type'] in RELEASE_RISK_TYPES else 'standard'}
+        roles = [r for r in manifest['agents'] if r['id'] == role_id]
+        require(len(roles) == 1, 'Selected specialization is ambiguous')
+        key = component_key(roles[0])
+        constraints = task_models.role_constraints(models['constraints'], key)
+        selected = task_models._selection(models['configuration'], model_task, 'claude', constraints)
+        require(task['channel'] != 'cicd' or model_task['type'] not in RELEASE_RISK_TYPES
+                or selected['rule']['profile'] == 'deep', 'Release-risk tasks require a deep profile')
+        effort = next(e for e in selected['preferences'] if e in selected['allowedEfforts'])
+        pending = {'harness': 'claude', 'resolved': {'model': selected['model'], 'effort': effort},
+                   'nativeACK': None, 'state': 'intent-only-awaiting-native-readiness'}
+        worker = await self.state_call('reserve', task['id'], phase, key, pending, config['maxWorkers'])
+        wid = worker['id']
+        cwd = pathlib.Path(self.owner.runtime) / 'task-workspaces' / wid
+        cwd.mkdir(parents=True, mode=0o700)
+        from .work_context import ensure, materialize
+        context = await asyncio.to_thread(ensure, self.store.root, task)
+        if task.get('contextRef') != context:
+            current = await self.state_call('get', task['id'])
+            task = await self.state_call('update', task['id'], current['revision'],
+                    {'contextRef': context, 'summary': 'Selected cloud task context is verified.'}, 'task-context-bound')
+        from .role_context import materialize as materialize_role
+        role = await asyncio.to_thread(materialize_role, self.store.root, key, cwd, harness='claude')
+        atomic_json(cwd / 'TASK.json', task)
+        await asyncio.to_thread(materialize, self.store.root, task, cwd)
+        if phase in {'execute', 'review'}:
+            from .linked_task_context import materialize as materialize_linked
+            await materialize_linked(self.store, task, cwd, lambda tid: self.state_call('get', tid))
+        atomic_json(cwd / 'context/retained-read-input.json', {'cursor': 0, 'limit': 50})
+        atomic_json(cwd / 'context/dispatch-connection.json', {
+            'format': 'topolo-dispatch-transport-v1',
+            'cloudReference': {k: self.store.binding[k] for k in ['organizationId', 'workspaceId', 'documentId', 'datasetId']},
+            'retainedReadCommand': [sys.executable, str(pathlib.Path(__file__).resolve().parents[2] / 'topolo-agent-pack'), '--store', str(self.owner.lib.root),
+                                    'work', 'retained', '--harness', 'claude', '--input', str(cwd / 'context/retained-read-input.json')],
+            'pageInput': {'cursor': 0, 'limit': 50},
+            'boundary': 'Read relevant retained context in pages; preserve original owners. Do not load the whole state document, portfolio export or old chats.'})
+        if phase == 'review':
+            from .work_artifacts import materialize_result
+            await asyncio.to_thread(materialize_result, self.store.root, task, cwd)
+            from .review_context import materialize as materialize_review
+            await asyncio.to_thread(materialize_review, self.store, task, cwd)
+        async def progress(identity, text):
+            await self.state_call('progress', wid, identity, text)
+            await self.notify()
+        session = self.factory(cwd, wid, selected['model'], effort, progress if phase == 'execute' else None)
+        session.allow_tools = phase != 'route'
+        settings_path = cwd / '.claude/settings.json'
+        settings = read_json(settings_path, {})
+        settings['env'] = {'PATH': self.tool_path}
+        atomic_json(settings_path, settings)
+        files = {str(p): hashlib.sha256(p.read_bytes()).hexdigest() for p in sorted(cwd.rglob('*'))
+                 if p.is_file() and not p.is_relative_to(cwd / '.topolo-worker')}
+        native_plan = {'taskId': task['id'], 'workerId': wid, 'nativeId': 'local_' + wid, 'cwd': str(cwd),
+                       'title': (phase.title() + ' · ' + task['objective'])[:256],
+                       'model': selected['model'], 'effort': effort, 'permissionMode': 'bypassPermissions',
+                       'contextDigest': hashlib.sha256(canonical(files)).hexdigest()}
+        await self.state_call('worker_update', wid, {'state': 'creating', 'cwd': str(cwd),
+                              'nativeId': native_plan['nativeId'], 'roleSource': role, 'nativePlan': native_plan})
+        session.plan = native_plan
+        session.connection = read_json(self.store.root / 'claude-frontdoors.json')['nativeConnection']
+        self.sessions[wid] = session
+        try:
+            ack = await session.start()
+            catalog = {'harness': 'claude', 'source': 'native-account-model-ids',
+                       'connectionGeneration': str(ack['processId']) + ':' + ack['sessionId'],
+                       'models': [ack['model']]}
+            resolution = task_models.resolve_intent(models['configuration'], model_task, 'claude', catalog, constraints)
+            resolution = task_models.acknowledge(resolution, {'model': ack['model'], 'effort': ack['effort']},
+                            configuration=models['configuration'], catalog=catalog, constraints=constraints)
+            message_id = str(uuid.uuid4())
+            # Cloud commit and readback precede stdin. An uncertain commit or
+            # delivery retains this exact worker/input; no replacement is sent.
+            await self.state_call('worker_update', wid, {'state': 'running', 'resolution': resolution, 'turnId': message_id})
+            current = await self.state_call('get', task['id'])
+            await self.state_call('update', task['id'], current['revision'],
+                    {'state': {'route': 'routing', 'execute': 'executing', 'review': 'reviewing'}[phase],
+                     'phase': phase, 'workerIds': current['workerIds'] + [wid],
+                     'summary': 'A fresh Claude ' + phase + ' specialist is running.'}, 'native-resume-verified')
+            check = await self.state_call('worker', wid)
+            require(check['turnId'] == message_id and check['resolution'] == resolution,
+                    'Canonical delivery reservation was not acknowledged')
+            await self.notify()
+            self.launch(self.execute(worker, session, message_id, self.prompt(task, phase, manifest, cwd)))
+        except Exception:
+            # Task input is sent only by execute(), after this startup block.
+            await session.close()
+            await self.state_call('worker_update', wid, {'state': 'failed', 'nativeArchived': False,
+                'nativeRetirement': {'kind': 'native-desktop-session', 'desktopChatArchived': False}})
+            raise
+
+    def prompt(self, task, phase, manifest, cwd):
+        prompt = super().prompt(task, phase, manifest, cwd).replace('Read AGENTS.md', 'Read CLAUDE.md')
+        if phase in {'execute', 'review'}:
+            prompt += '\nFor relevant existing-work inventory only, context/dispatch-connection.json supplies the current installation transport and paged read command. It grants no takeover or replay authority.'
+        if phase == 'review':
+            prompt += '\nRead context/dispatch-connection.json and context/workflow-evidence.json, including its evidenceContract, before declaring authority or lifecycle evidence missing. Save any read-only command output you cite in this reviewer workspace; never cite /tmp, /private/tmp or another worker directory. The transport supplies the pinned adapter command and bounded pageInput; run that read-only command to independently verify relevant retained evidence. A role such as queue-recovery is the selected specialization; status-read is its classified task type, not a separate specialist name. Workflow evidence records this attempt only. Inspect prior worker archival and native model acknowledgements there. The coordinator separately verifies this reviewer archives after its checkpoint and that Activity reaches the live GUI; never fabricate those post-review observations or perform work again.'
+        return prompt
+
+    async def execute(self, worker, session, message_id, prompt):
+        try:
+            result = await session.assign(message_id, prompt)
+            await self.finish(worker['id'], result)
+            saved = await self.state_call('worker', worker['id'])
+            if saved['state'] != 'archived':
+                await session.close()
+        except Exception as exc:
+            await self.state_call('worker_update', worker['id'], {'state': 'unknown', 'error': str(exc)})
+            task = await self.state_call('get', worker['taskId'])
+            await self.state_call('update', task['id'], task['revision'],
+                    {'state': 'unknown', 'summary': 'Claude task outcome is unresolved; no retry was sent.'}, 'delivery-unknown')
+            await session.close()
+            await self.notify()
+
+    async def read_turn(self, worker, turn):
+        receipt = self.sessions[worker['id']].results.get(turn['id'])
+        require(receipt is not None and receipt == turn, 'Exact native Claude completion is unavailable')
+        return {'id': turn['id'], 'status': 'completed',
+                'items': [{'type': 'agentMessage', 'text': turn['output']}] +
+                         [{'type': 'toolUse'} for _ in range(turn['toolItems'])],
+                'nativeProof': {'harness': 'claude-desktop', 'sessionId': receipt['nativeSessionId'],
+                                'resultId': receipt['nativeResultId']}}
+
+    async def archive_worker(self, worker):
+        session = self.sessions[worker['id']]
+        result = await session.archive(worker['turnId'])
+        require(session.closed and session.archived, 'Native Desktop worker remains unarchived')
+        return {'nativeRetirement': result}
+
+    def persist(self):
+        # The cloud store owns task/worker state. Never write a Codex execution
+        # policy for Claude or use a second local ledger as an execution fallback.
+        pass

package/agent-packs/src/topolo_agent_pack/claude_prompt.py

@@ -0,0 +1,74 @@
+"""Supported native coordinator conversation and typed broker-tool boundary.
+
+The native prompt_id is the deduplication identity. No transcript, chat export,
+or locally generated substitute is consulted when it is missing.
+"""
+import json
+import pathlib
+import sys
+import uuid
+
+from .storage import Library, PackError, read_json
+from .work import require
+
+
+def submit(root, event, send=None):
+    require(isinstance(event, dict), 'Native Claude hook input must be an object')
+    lib = Library(root)
+    binding = read_json(lib.root / 'work/claude-frontdoors.json')
+    require(binding.get('format') == 'topolo-claude-frontdoors-v1',
+            'Claude front-door binding is not installed')
+    require(event.get('hook_event_name') in {'UserPromptSubmit', 'PreToolUse'},
+            'Unsupported Claude front-door hook')
+    rows = [r for r in binding['roles'] if r['sessionId'] == event.get('session_id')
+            and r['cwd'] == event.get('cwd')]
+    require(len(rows) == 1, 'Native Claude session is not the bound front door')
+    role = rows[0]
+    if event['hook_event_name'] == 'PreToolUse':
+        from .coordinator_context import tool_allowed
+        try:allowed=tool_allowed(lib.root,role,event)
+        except (PackError,ValueError,TypeError,OSError):allowed=False
+        return {'hookSpecificOutput': {'hookEventName': 'PreToolUse',
+                'permissionDecision': 'allow' if allowed else 'deny', 'permissionDecisionReason':
+                'Use only the exact broker schemas in the current Topolo coordinator context. For continuation: read the existing task, then Write {requestId: dispatchRequestId, taskId, revision: latest task.revision, intent: continue/request_changes/hold, note} to context/coordinator-request.json and run the installed respond --input command. Do not use {taskId,message}, create a replacement task, or perform engineering effects.'}}
+    identity = event.get('prompt_id')
+    try:
+        valid = isinstance(identity, str) and str(uuid.UUID(identity)) == identity
+    except ValueError:
+        valid = False
+    require(valid, 'Native Claude prompt identity is unavailable; no task was submitted')
+    require(event.get('permission_mode') == 'bypassPermissions',
+            'Claude front-door startup permissions differ from the installation')
+    require(isinstance(event.get('prompt'),str) and 1<=len(event['prompt'])<=16000,'Bounded native human input required')
+    if send is None:
+        from .live import request as live_request
+        send = lambda operation, params: live_request(lib, operation, params)
+    status = send('status', {})
+    require(status.get('harness') == 'claude' and status.get('cloudDispatchReady') is True
+            and status.get('desktopPid') == binding.get('desktopPid'),
+            'Claude cloud dispatch is not active; the coordinator will not execute the request itself')
+    from .coordinator_context import prepare
+    selected=prepare(lib.root,role,event,send('work-list',{}))
+    return {'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit',
+            'additionalContext':'Topolo coordinator context (the original human prompt is unchanged; no task was submitted):\n'+json.dumps(selected,sort_keys=True,separators=(',',':'))}}
+
+
+
+def main(root, stream=None):
+    try:
+        source = (stream or sys.stdin).read(100001)
+        require(len(source) <= 100000, 'Claude hook input exceeds its boundary')
+        event = json.loads(source)
+        if isinstance(event, dict) and event.get('hook_event_name') == 'UserPromptSubmit':
+            from .claude_service import ensure_running, refresh_desktop_owner
+            lib = Library(root)
+            refresh_desktop_owner(lib)
+            ensure_running(lib)
+        result = submit(pathlib.Path(root), event)
+        print(json.dumps(result))
+        return 0
+    except Exception as exc:
+        # Nonzero hook exit blocks direct execution on a failed handoff. Never
+        # print the incoming human prompt or a transcript in a diagnostic.
+        print('Topolo handoff unavailable: ' + str(exc), file=sys.stderr)
+        return 2