Merge remote-tracking branch 'origin/worktree-agent-scope-design' into codex/pr224-simplification-audit

docs/cordis-catalog/events.md

@@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:606`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:605`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — serial
 
@@ -165,15 +165,15 @@ Source: [`packages/core/agent/src/types.ts:570`](../../packages/core/agent/src/t
 
 ### `agent/turn-stop` — serial
 
-Serial terminal-stop checkpoint after the ordinary `agent/turn-continuation` waterfall, any `continue.reason`, and the pending-steering continuation override have been folded. A listener returns `{ action: 'stop' }` to make this turn terminal, or `undefined` to abstain. Terminal stop is monotonic: listener order and steering cannot resume the turn, and pending steering is discarded rather than becoming another step or turn. A malformed non-undefined result fails the turn closed.
+Serial terminal-stop checkpoint after the ordinary `agent/turn-continuation` waterfall, any `continue.reason`, and the pending-steering continuation override have been folded. A listener returns `{ action: 'stop' }` to make this turn terminal, or `undefined` to abstain. Terminal stop is monotonic: listener order and steering cannot resume the turn, and pending steering is discarded rather than becoming another step or turn.
 
 ```ts cordis-catalog
-'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): Promise<ContinuationStop | undefined> | ContinuationStop | undefined
+'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
 ```
 
 Types: [Agent](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:589`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:588`](../../packages/core/agent/src/types.ts)
 
 ## `approval/*`
 
@@ -419,12 +419,12 @@ Types: [ToolExecution](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:101`](../../packages/core/tools/src/index.ts)
 
-### `tools/result` — parallel
+### `tools/result` — emit
 
-Awaited notification of the authoritative FINAL tool outcome, after the complete pre/execute/post pipeline, final lossless-JSON validation, and outer error normalization. Unlike the three waterfalls, this seam cannot transform the result: each listener receives the now-frozen execution object and a deep-frozen result snapshot; listener failures are contained and logged, and ToolRegistry.execute still returns the outcome. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`, using the same carrier as the pipeline.
+Synchronous notification of the authoritative FINAL tool outcome, after the complete pre/execute/post pipeline, final lossless-JSON validation, and outer error normalization. Unlike the three waterfalls, this seam cannot transform the result: each listener receives the now-frozen execution object and a deep-frozen result snapshot; listener failures are contained and logged, and ToolRegistry.execute still returns the outcome. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`, using the same carrier as the pipeline.
 
 ```ts cordis-catalog
-'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): Promise<void> | void
+'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
 Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)

docs/cordis-catalog/services.md

@@ -26,10 +26,10 @@ Source: [`packages/core/agent-loop/src/index.ts:338`](../../packages/core/agent-
 Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
 
 ```ts cordis-catalog
-setFactory(factory: AgentFactory): () => Promise<void> | void
+setFactory(factory: AgentFactory): () => void
 async create(options: CreateAgentOptions): Promise<AgentHandle>
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
-register(agent: Agent): () => Promise<void> | void
+register(agent: Agent): () => void
 enter(agent: Agent): () => void
 announce(agent: Agent): void
 get(id: AgentId): Agent | undefined
@@ -225,8 +225,8 @@ Source: [`packages/core/session/src/index.ts:591`](../../packages/core/session/s
 Registry of skill providers. It merges provider catalogs with stable first-wins duplicate handling, exposes sorted model-visible summaries, and loads full skill bodies on demand.
 
 ```ts cordis-catalog
-registerProvider(provider: SkillProvider): () => Promise<void> | void
-register(skill: SkillRegistration): () => Promise<void> | void
+registerProvider(provider: SkillProvider): () => void
+register(skill: SkillRegistration): () => void
 async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
@@ -238,7 +238,7 @@ Source: [`packages/skill/skill/src/index.ts:158`](../../packages/skill/skill/src
 Named provider registry and capability-checked start surface.
 
 ```ts cordis-catalog
-registerProvider(provider: SubagentProvider): () => Promise<void> | void
+registerProvider(provider: SubagentProvider): () => void
 getProvider(name: string): SubagentProvider | undefined
 list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
@@ -251,9 +251,9 @@ Source: [`packages/subagent/subagent/src/index.ts:123`](../../packages/subagent/
 Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, named prompt variables, and owner-final contributions; the agent loop calls `assemble(context)` once per step. Registers the harness-owned `harness:identity` and `deployment:persona` sections itself (see Config.persona).
 
 ```ts cordis-catalog
-section(section: PromptSection): () => Promise<void> | void
-tools(provider: (context: AssembleContext) => ToolProviderResult): () => Promise<void> | void
-variable(name: string, provider: (context: AssembleContext) => string | undefined): () => Promise<void> | void
+section(section: PromptSection): () => void
+tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
+variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
@@ -266,9 +266,9 @@ Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop e
 Two registration layers (`@deepseek-ai/dsh-scope`): a registration through a plain plugin context is GLOBAL (visible to every agent); one through a scoped context (`agent.ctx`) is filed in that scope's layer — visible to that agent alone, disposed with the scope, and SHADOWING a global tool of the same name for that agent (most-specific-wins; within one layer a duplicate name still throws). restrict masks the global layer per scope. One private visibility resolver feeds prompt assembly, get, and execute — and, under a non-native mode, the SDK section and `run_code`'s bindings — so what the model is shown, what a presenter renders, what a program can call, and what dispatches can never disagree.
 
 ```ts cordis-catalog
-register(definition: ToolDefinition): () => Promise<void> | void
-restrict(filter: ToolRestriction): () => Promise<void> | void
-guard(guard: ToolGuard): () => Promise<void> | void
+register(definition: ToolDefinition): () => void
+restrict(filter: ToolRestriction): () => void
+guard(guard: ToolGuard): () => void
 get(name: string, scope?: ScopeKey): ToolDefinition | undefined
 schemas(scope?: ScopeKey): ToolSchema[]
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>