@gotgenes/pi-subagents 6.19.1 → 7.1.0

package/docs/plans/0185-remove-persistent-agent-memory.md

@@ -0,0 +1,161 @@
+---
+issue: 185
+issue_title: "pi-subagents: Remove persistent agent memory feature"
+---
+
+# Remove persistent agent memory feature
+
+## Problem Statement
+
+The `memory.ts` module and all supporting code for persistent agent memory (`MEMORY.md`, `agent-memory/` directories) should be removed from `pi-subagents`.
+The memory feature invents its own filesystem layout, file format, and security model — all outside the stated scope of `pi-subagents`, which is agent spawning, execution, and result retrieval.
+This follows the same scope-reduction rationale as the scheduling subsystem removal (issue #52).
+
+## Goals
+
+- Remove the `memory.ts` module and all memory-related code from the package.
+- Remove `MemoryScope` type and `memory` field from `AgentConfig`.
+- Remove memory block injection from session assembly.
+- Remove memory tool augmentation from agent-types.
+- Remove memory parsing from custom agent loading.
+- Remove memory display from UI components.
+- Extract `isSymlink`, `isUnsafeName`, and `safeReadFile` to a shared utility module — `skill-loader.ts` depends on them independently of memory.
+- Update architecture documentation to reflect the removal.
+
+## Non-Goals
+
+- Replacing memory with an alternative persistence mechanism — that is out of scope.
+- Changing the `skill-loader.ts` logic beyond updating the import source for the extracted utilities.
+
+## Background
+
+The memory system spans six source modules and two UI modules:
+
+| File                              | Memory surface                                                                                                                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/session/memory.ts`           | Core module: `buildMemoryBlock`, `buildReadOnlyMemoryBlock`, `resolveMemoryDir`, `ensureMemoryDir`, `readMemoryIndex`, plus shared utilities `isSymlink`, `isUnsafeName`, `safeReadFile` |
+| `src/types.ts`                    | `MemoryScope` type, `memory?: MemoryScope` field on `AgentConfig`                                                                                                                        |
+| `src/session/session-config.ts`   | `AssemblerIO.buildMemoryBlock` / `buildReadOnlyMemoryBlock` fields, memory logic block (~25 lines), `MemoryScope` import                                                                 |
+| `src/config/agent-types.ts`       | `getMemoryToolNames()`, `getReadOnlyMemoryToolNames()`, `MEMORY_TOOL_NAMES`, `READONLY_MEMORY_TOOL_NAMES`                                                                                |
+| `src/config/custom-agents.ts`     | `parseMemory()` function, `memory: parseMemory(fm.memory)` assignment                                                                                                                    |
+| `src/session/prompts.ts`          | `memoryBlock` field on `PromptExtras`, injection into system prompt                                                                                                                      |
+| `src/ui/agent-config-editor.ts`   | `if (cfg.memory) fmFields.push(...)`                                                                                                                                                     |
+| `src/ui/agent-creation-wizard.ts` | `memory:` line in frontmatter help text                                                                                                                                                  |
+| `src/index.ts`                    | Imports `buildMemoryBlock`, `buildReadOnlyMemoryBlock`; wires them into `assemblerIO`                                                                                                    |
+
+The three utility functions (`isSymlink`, `isUnsafeName`, `safeReadFile`) are imported by `skill-loader.ts` for filesystem safety — they are not memory-specific and must survive the removal.
+
+AGENTS.md constraint: the architecture doc in `docs/architecture/architecture.md` references `memory.ts` in the module listing and domain model diagram — both need updating.
+
+## Design Overview
+
+This is a pure removal with one extraction.
+The only design decision is where to place the extracted utilities.
+
+The three functions (`isSymlink`, `isUnsafeName`, `safeReadFile`) are filesystem safety primitives used by `skill-loader.ts`.
+They belong in a new `src/session/safe-fs.ts` module in the session domain, co-located with their sole remaining consumer.
+
+The removal works consumers-first, declaration-last:
+
+1. Extract shared utilities to `safe-fs.ts` (additive, no behavior change).
+2. Remove all memory consumers — session-config, prompts, agent-types, custom-agents, UI, index wiring.
+3. Remove the declarations — `MemoryScope`, `AgentConfig.memory`, `memory.ts`.
+4. Update architecture docs.
+
+## Module-Level Changes
+
+### New files
+
+- `src/session/safe-fs.ts` — extracted `isSymlink`, `isUnsafeName`, `safeReadFile`.
+- `test/session/safe-fs.test.ts` — tests moved from `memory.test.ts` for these three functions.
+
+### Modified files
+
+- `src/session/skill-loader.ts` — change import from `#src/session/memory` to `#src/session/safe-fs`.
+- `src/session/session-config.ts` — remove `buildMemoryBlock` / `buildReadOnlyMemoryBlock` from `AssemblerIO`; remove `MemoryScope` import; remove entire memory logic block (~lines 215–242).
+- `src/session/prompts.ts` — remove `memoryBlock` from `PromptExtras` interface; remove `extras?.memoryBlock` injection.
+- `src/config/agent-types.ts` — remove `MEMORY_TOOL_NAMES`, `READONLY_MEMORY_TOOL_NAMES`, `getMemoryToolNames()`, `getReadOnlyMemoryToolNames()`.
+- `src/config/custom-agents.ts` — remove `MemoryScope` import; remove `memory: parseMemory(fm.memory)` assignment; remove `parseMemory()` function.
+- `src/types.ts` — remove `MemoryScope` type; remove `memory?: MemoryScope` from `AgentConfig`; remove associated doc comment.
+- `src/ui/agent-config-editor.ts` — remove `if (cfg.memory)` line.
+- `src/ui/agent-creation-wizard.ts` — remove `memory:` line from frontmatter help text.
+- `src/index.ts` — remove `buildMemoryBlock` / `buildReadOnlyMemoryBlock` import; remove those fields from `assemblerIO` object.
+- `docs/architecture/architecture.md` — remove `memory.ts` from module listing; remove Memory node from domain model Mermaid diagram; update session domain description.
+
+### Deleted files
+
+- `src/session/memory.ts` — entire module.
+- `test/session/memory.test.ts` — entire test file (tests for `isSymlink`, `isUnsafeName`, `safeReadFile` are moved to `safe-fs.test.ts` first; remaining memory-specific tests are deleted).
+
+### Test files modified
+
+- `test/session/session-config.test.ts` — remove `mockBuildMemoryBlock` / `mockBuildReadOnlyMemoryBlock` mocks from `AssemblerIO` construction; remove "assembleSessionConfig — memory block selection" describe block (~lines 354–427).
+- `test/session/prompts.test.ts` — remove "injects memory block in replace mode", "injects memory block in append mode", and "injects both memory and skills" test cases.
+- `test/config/agent-types.test.ts` — remove `getMemoryToolNames` / `getReadOnlyMemoryToolNames` imports and test suite (~lines 26–51).
+- `test/config/custom-agents.test.ts` — remove memory scope parsing tests (~lines 361–403).
+
+## Test Impact Analysis
+
+1. The extraction of `isSymlink`, `isUnsafeName`, `safeReadFile` to `safe-fs.ts` enables their tests to exist independently of the memory module — currently they are co-located with memory-specific tests in `memory.test.ts`.
+2. The memory-specific tests in `memory.test.ts` (`resolveMemoryDir`, `ensureMemoryDir`, `readMemoryIndex`, `buildMemoryBlock`, `buildReadOnlyMemoryBlock`) become redundant and are deleted — the code they test is being removed.
+3. The memory block selection tests in `session-config.test.ts` (~70 lines) test the memory branching logic in `assembleSessionConfig` — they are deleted because that logic is removed.
+4. The memory injection tests in `prompts.test.ts` test `memoryBlock` injection — deleted because the field and injection code are removed.
+5. The memory parsing tests in `custom-agents.test.ts` test `parseMemory` — deleted because the function is removed.
+6. The memory tool name helper tests in `agent-types.test.ts` test `getMemoryToolNames` / `getReadOnlyMemoryToolNames` — deleted because the functions are removed.
+7. All other tests remain as-is — they do not depend on memory functionality.
+
+## TDD Order
+
+1. **Extract utilities to `safe-fs.ts`.**
+   Create `src/session/safe-fs.ts` with `isSymlink`, `isUnsafeName`, `safeReadFile`.
+   Create `test/session/safe-fs.test.ts` with tests moved from `memory.test.ts` for these three functions.
+   Update `src/session/skill-loader.ts` import to point to `#src/session/safe-fs`.
+   Update `src/session/memory.ts` import to point to `#src/session/safe-fs` (temporary — keeps memory working until removal).
+   Verify: `pnpm vitest run` and `pnpm run check`.
+   Commit: `refactor: extract safe-fs utilities from memory module`
+
+2. **Remove memory from session assembly and config layers.**
+   Remove `buildMemoryBlock` / `buildReadOnlyMemoryBlock` from `AssemblerIO` in `session-config.ts`.
+   Remove `MemoryScope` import and all memory logic from `session-config.ts`.
+   Remove `memoryBlock` from `PromptExtras` in `prompts.ts` and its injection logic.
+   Remove `getMemoryToolNames`, `getReadOnlyMemoryToolNames`, `MEMORY_TOOL_NAMES`, `READONLY_MEMORY_TOOL_NAMES` from `agent-types.ts`.
+   Remove `getMemoryToolNames` / `getReadOnlyMemoryToolNames` import from `session-config.ts`.
+   Remove `buildMemoryBlock` / `buildReadOnlyMemoryBlock` import and `assemblerIO` fields from `index.ts`.
+   Update `test/session/session-config.test.ts`: remove memory mocks from IO construction and memory block selection test suite.
+   Update `test/session/prompts.test.ts`: remove memory injection tests.
+   Update `test/config/agent-types.test.ts`: remove memory tool name helper tests.
+   Verify: `pnpm vitest run` and `pnpm run check`.
+   Commit: `feat!: remove memory from session assembly and config layers`
+
+3. **Remove memory from types, custom-agents, and UI.**
+   Remove `MemoryScope` type and `memory` field from `AgentConfig` in `types.ts`.
+   Remove `parseMemory()` function, `MemoryScope` import, and `memory:` assignment from `custom-agents.ts`.
+   Remove `if (cfg.memory)` line from `agent-config-editor.ts`.
+   Remove `memory:` help text line from `agent-creation-wizard.ts`.
+   Update `test/config/custom-agents.test.ts`: remove memory parsing tests.
+   Verify: `pnpm vitest run` and `pnpm run check`.
+   Commit: `feat!: remove MemoryScope type and memory config field`
+
+4. **Delete `memory.ts` and its test file.**
+   Delete `src/session/memory.ts`.
+   Delete `test/session/memory.test.ts`.
+   Verify: `pnpm vitest run` and `pnpm run check`.
+   Commit: `feat!: delete memory module`
+
+5. **Update architecture documentation.**
+   Remove Memory node from the domain model Mermaid diagram.
+   Remove `memory.ts` from the module listing.
+   Update session domain description.
+   Commit: `docs: update architecture after memory removal`
+
+## Risks and Mitigations
+
+| Risk                                                                                   | Mitigation                                                                                                                                                              |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Users with `memory:` in custom agent frontmatter — the field silently becomes a no-op. | `parseMemory` removal means unknown frontmatter keys are ignored by the markdown parser. No error, no crash — just no memory. This is acceptable for a feature removal. |
+| `skill-loader.ts` breaks if the utility extraction has a typo or missing re-export.    | Step 1 runs full test suite before proceeding. The skill-loader tests exercise `isUnsafeName` and `safeReadFile` indirectly.                                            |
+| Architecture doc Mermaid diagram breaks after node removal.                            | Verify the diagram renders correctly after editing — remove both the node and all edges referencing it.                                                                 |
+
+## Open Questions
+
+None — the issue scope is unambiguous and all affected files have been traced.

package/docs/plans/0192-define-session-context-interface.md

@@ -0,0 +1,107 @@
+---
+issue: 192
+issue_title: "Define SessionContext narrow interface"
+---
+
+# Define `SessionContext` narrow interface
+
+## Problem Statement
+
+`SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }`.
+Every consumer must cast through `as any` to read fields from the SDK context.
+This forces context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) to live as closures in `index.ts` with repeated `as any` casts, rather than as typed methods on the state holder.
+
+The SDK exports `ExtensionContext` — the `unknown` typing is a historical choice, not a constraint.
+
+## Goals
+
+- Define a narrow `SessionContext` interface in `src/types.ts` capturing the 5 fields `SubagentRuntime` actually reads.
+- Pure additive — no consumers change in this step.
+- Provide the typed foundation for Layer 1 (#193) and subsequent closure-to-class conversion issues.
+
+## Non-Goals
+
+- Changing `SubagentRuntime.currentCtx` type (that's #193).
+- Converting closure factories to classes (#195, #196).
+- Removing any `as any` casts from `index.ts` (that's #193).
+
+## Background
+
+Phase 11, Layer 0 in `docs/architecture/architecture.md`.
+This is the first step in a 5-issue sequence (issues #192–#196) that converts closure factories to classes, eliminating 44 adapter closures in `index.ts`.
+
+The SDK's `ExtensionContext` interface (in `@earendil-works/pi-coding-agent`) is broad — it exposes `ui`, `abort()`, `shutdown()`, `compact()`, etc.
+ISP (Interface Segregation Principle) from `code-design` mandates a narrow interface capturing only what `SubagentRuntime` needs.
+
+The 5 fields consumed by runtime (traced from `index.ts` lines 214–223 and `lifecycle/parent-snapshot.ts`):
+
+1. `cwd` — working directory for agent sessions.
+2. `model` — parent model instance for fallback resolution.
+3. `modelRegistry` — resolving config model strings.
+4. `getSystemPrompt()` — system prompt for append-mode agents.
+5. `sessionManager.getSessionFile()` / `.getSessionId()` / `.getBranch()` — session identification and context inheritance.
+
+The local `ModelRegistry` interface (in `src/session/model-resolver.ts`) already exists as a narrow ISP interface.
+`SessionContext` will reference it rather than redeclaring model-registry methods inline.
+
+## Design Overview
+
+```typescript
+import type { ModelRegistry } from "#src/session/model-resolver";
+
+/**
+ * Narrow interface capturing the 5 ExtensionContext fields SubagentRuntime needs.
+ * Avoids coupling runtime to the full SDK ExtensionContext surface.
+ */
+export interface SessionContext {
+  readonly cwd: string;
+  readonly model: unknown;
+  readonly modelRegistry: ModelRegistry | undefined;
+  getSystemPrompt(): string;
+  readonly sessionManager: {
+    getSessionFile(): string | undefined;
+    getSessionId(): string;
+    getBranch(): unknown[];
+  };
+}
+```
+
+Design decisions:
+
+1. `model` stays `unknown` — the runtime only passes it through to `resolveModel`; narrowing it gains nothing and would couple to `@earendil-works/pi-ai`'s `Model<Api>` generic.
+2. `modelRegistry` is `ModelRegistry | undefined` — the SDK type says `ModelRegistry` (non-optional), but `SubagentRuntime.currentCtx` can be undefined, and the architecture doc specifies this signature.
+   The `| undefined` reflects reality at the cast boundary (pre-bind, the registry may not exist).
+3. `sessionManager` uses an inline structural type rather than importing `ReadonlySessionManager` — we only need 3 of its 13 methods; a separate named type would be over-engineering for a nested structural slice.
+4. `getBranch()` returns `unknown[]` — the runtime passes entries through to `buildParentContext()` which already type-narrows internally.
+
+## Module-Level Changes
+
+| File           | Change                                                                                                         |
+| -------------- | -------------------------------------------------------------------------------------------------------------- |
+| `src/types.ts` | Add `SessionContext` interface export. Add `import type { ModelRegistry }` from `#src/session/model-resolver`. |
+
+No other files change — this is pure additive.
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — `SessionContext` is a pure type definition with no runtime behavior.
+2. No existing tests become redundant.
+3. A compile-time check (`pnpm run check`) verifies the interface is well-formed and the import resolves.
+
+## TDD Order
+
+1. **Add `SessionContext` interface to `src/types.ts`** — add the interface with its import.
+   Verify with `pnpm run check` (type-check passes).
+   Commit: `feat(pi-subagents): define SessionContext narrow interface (#192)`
+
+## Risks and Mitigations
+
+| Risk                                                             | Mitigation                                                                                                                 |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Interface shape doesn't match real `ExtensionContext` at runtime | Traced all 5 fields against SDK `.d.ts` declarations; shapes align exactly.                                                |
+| Circular import from `types.ts` → `session/model-resolver.ts`    | `model-resolver.ts` does not import from `types.ts`; no cycle.                                                             |
+| Future SDK changes break the narrow interface                    | The cast boundary (Layer 1, #193) will be the single enforcement point — structural typing ensures compile-time detection. |
+
+## Open Questions
+
+None — the issue's "Proposed change" section fully specifies the interface shape.

package/docs/retro/0185-remove-persistent-agent-memory.md

@@ -0,0 +1,73 @@
+---
+issue: 185
+issue_title: "pi-subagents: Remove persistent agent memory feature"
+---
+
+# Retro: #185 — pi-subagents: Remove persistent agent memory feature
+
+## Stage: Planning (2026-05-24T20:46:56Z)
+
+### Session summary
+
+Traced all memory-related code across 9 source files, 5 test files, and the architecture doc.
+Produced a 5-step TDD plan: extract shared utilities (`isSymlink`, `isUnsafeName`, `safeReadFile`) to `safe-fs.ts`, then remove memory consumers (session assembly, config, UI), then delete the module, then update docs.
+
+### Observations
+
+- The three utility functions in `memory.ts` are the only complication — `skill-loader.ts` imports them independently of memory.
+  Extracting to `src/session/safe-fs.ts` keeps them co-located with their sole remaining consumer.
+- The removal is consumers-first, declaration-last: session-config and prompts lose their memory logic before `MemoryScope` is removed from `types.ts`, avoiding intermediate type errors.
+- No ambiguous design choices — the issue scope section is precise about what to remove and what to extract.
+- Memory field in custom agent frontmatter will silently become a no-op (ignored by the YAML parser) — no user-facing error, just loss of the feature.
+- The `AssemblerIO` interface shrinks from 4 fields to 2 after removal, which is a welcome simplification.
+
+## Stage: Implementation — TDD (2026-05-24T22:41:23Z)
+
+### Session summary
+
+All 5 TDD steps completed across 5 commits.
+Test count went from 901 (54 files) to 848 (53 files) — a net reduction of 53 tests and 1 file, reflecting the deletion of the `memory.test.ts` file with its memory-specific tests and the removal of memory-related tests from `session-config.test.ts`, `prompts.test.ts`, `agent-types.test.ts`, and `custom-agents.test.ts`.
+New file `safe-fs.test.ts` was created with 13 tests for the extracted utilities.
+
+### Observations
+
+- Step 1 had a subtle bug: after re-exporting `isUnsafeName` from `safe-fs` in `memory.ts`, the function was not imported into the `memory.ts` module scope itself, so `resolveMemoryDir` got a `ReferenceError` at runtime.
+  Fix was trivial: add `isUnsafeName` to the import alongside `isSymlink` and `safeReadFile`.
+- Step 3 introduced a type error in `memory.ts` (still alive at that point): `MemoryScope` was imported from `#src/types` which no longer exported it.
+  Fix: inline the literal union `"user" | "project" | "local"` directly in `memory.ts` as a local type, so it compiles cleanly until deletion in step 4.
+- The `SKILL.md` for `package-pi-subagents` also listed `memory.ts` in the session domain table — updated alongside `architecture.md` in the docs commit.
+- No deviations from the plan other than the two minor bugs above (both self-corrected within the same TDD step).
+
+## Stage: Final Retrospective (2026-05-24T22:47:55Z)
+
+### Session summary
+
+Shipped issue #185 as `pi-subagents-v7.0.0`.
+CI passed, issue closed, release-please PR #190 merged.
+Three sessions total: planning, TDD (5 steps / 5 commits), shipping.
+
+### Observations
+
+#### What went well
+
+- The issue's "Scope" section was precise enough that the planning session required no `ask_user` and the Explore agent's trace matched the final commit diff exactly.
+- Consumers-first, declaration-last ordering kept each commit independently compilable (after the two self-corrected fixes).
+- The `SKILL.md` domain table update was caught naturally during the docs step even though the plan didn't list it.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In TDD step 1, `memory.ts` was updated to re-export `isUnsafeName` from `safe-fs`, but the function was not imported into `memory.ts`'s own scope.
+  `resolveMemoryDir` threw a `ReferenceError` at runtime.
+  Impact: one extra test-run cycle (~5 seconds) and a trivial one-line fix; no rework commit.
+- `missing-context` — In TDD step 3, removing `MemoryScope` from `types.ts` broke `memory.ts` (scheduled for deletion in step 4).
+  The plan said "consumers-first" but didn't account for the doomed module itself being a consumer of the type.
+  Impact: one extra `pnpm run check` cycle and a local type inline; no rework commit.
+  Both share the same root cause: incremental deletion plans must account for doomed files' own imports at each intermediate step.
+
+#### What caused friction (user side)
+
+- None observed — all three sessions ran without user corrections or redirections.
+
+### Changes made
+
+1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` about accounting for doomed modules' own imports during multi-step deletion.

package/docs/retro/0188-replace-any-casts-with-sdk-types.md

@@ -38,3 +38,32 @@ Test count: 902 → 901 (one test removed).
 - `ui-observer.ts` had one analogous fix: `event.assistantMessageEvent?.type` → `.type` (the field is required on `MessageUpdateEvent`).
 - No test file changes were needed for `ui-observer.ts` — its existing tests all emit conforming events.
 - The plan's contravariance reasoning about mock session compatibility was correct: `pnpm run check` passed without updating `MockSession.subscribe`.
+
+## Stage: Final Retrospective (2026-05-24T20:41:42Z)
+
+### Session summary
+
+Clean two-step refactoring shipped as `pi-subagents-v6.19.1`.
+Both TDD steps completed in a single session with two minor deviations from the plan, both caught by pre-commit hooks.
+Test count: 902 → 901 (one non-conforming test removed).
+
+### Observations
+
+#### What went well
+
+- The plan's contravariance analysis of `MockSession.subscribe` vs `SubscribableSession` was correct — zero test infrastructure changes needed.
+- Pre-commit hooks (ESLint) caught both deviations from the plan at commit time, before they could reach CI.
+- The user providing the Pi source path (`~/development/pi/pi`) unblocked verification of `AssistantMessage.usage` field requirements without guesswork.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's Risk 3 said "keep `?? ""` for safety" on `TextContent.text`, but `@typescript-eslint/no-unnecessary-condition` rejected it at commit time because `TextContent.text: string` is non-optional.
+  Impact: one failed commit attempt, immediate fix (changed `.map((c) => c.text ?? "")` to `.map((c) => c.text)`).
+- `missing-context` — The plan's step 2 didn't anticipate the five additional lint errors surfaced by properly typing the `record-observer` callback: unnecessary optional chain on `event.message?.role`, unnecessary `if (u)` guard, and three unnecessary `?? 0` guards on usage fields.
+  Impact: added ~5 minutes of investigation to verify the SDK types were truly non-optional before removing guards; required removing one test case (`"ignores message_end without usage"`).
+  Both instances stem from the same root cause: the plan checked that the SDK types *existed* but didn't trace the *field optionality* of types downstream of `AgentSessionEvent` (specifically `AgentMessage.usage` and `Usage.{input,output,cacheWrite}`).
+
+#### What caused friction (user side)
+
+- The Pi source path (`~/development/pi/pi`) was provided reactively after I'd already spent several tool calls trying to locate `AgentMessage` type definitions in `node_modules`.
+  Sharing this path earlier (or noting it in the package skill) would have saved ~4 `grep`/`find` calls.

package/docs/retro/0192-define-session-context-interface.md

@@ -0,0 +1,35 @@
+---
+issue: 192
+issue_title: "Define SessionContext narrow interface"
+---
+
+# Retro: #192 — Define SessionContext narrow interface
+
+## Stage: Planning (2026-05-24T16:00:00Z)
+
+### Session summary
+
+Planned the pure-additive `SessionContext` interface for `src/types.ts`.
+Traced all 5 consumed fields against the SDK's `ExtensionContext` type declarations to confirm shape alignment.
+Single TDD step: add the interface and verify with `pnpm run check`.
+
+### Observations
+
+- The interface is trivial in scope — one new export with no consumers changing.
+  This is intentionally the smallest possible first step to unblock Layer 1 (#193).
+- `ModelRegistry` already exists as a local narrow interface in `src/session/model-resolver.ts`; `SessionContext` imports it rather than redeclaring.
+- `sessionManager` uses an inline structural type (3 methods) rather than importing the SDK's `ReadonlySessionManager` (13 methods) — ISP applies here.
+- No design ambiguity required `ask_user`; the issue's proposed change section was fully specified.
+
+## Stage: Implementation — TDD (2026-05-24T19:55:00Z)
+
+### Session summary
+
+Added the `SessionContext` interface to `src/types.ts` with an `import type { ModelRegistry }` from `#src/session/model-resolver`.
+Single compile-time step — no runtime tests needed for a pure type definition.
+Baseline: 53 test files, 848 tests; final: unchanged.
+
+### Observations
+
+- Pre-existing lint failure in `docs/architecture/architecture.md` (5 unused MD053 link references for issues #164, #165, #170, #171, #172) was fixed as part of the baseline verification and included in the feat commit.
+- The interface landed exactly as planned — no deviations from the plan's Design Overview.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.19.1",
+  "version": "7.1.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/config/agent-types.ts

@@ -133,23 +133,3 @@ export class AgentTypeRegistry implements AgentConfigLookup {
 
 /** All known built-in tool names. */
 export const BUILTIN_TOOL_NAMES: string[] = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-
-/** Tool names required for memory management. */
-const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
-
-/**
- * Get memory tool names (read/write/edit) not already in the provided set.
- */
-export function getMemoryToolNames(existingToolNames: Set<string>): string[] {
-  return MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
-}
-
-/** Tool names needed for read-only memory access. */
-const READONLY_MEMORY_TOOL_NAMES = ["read"];
-
-/**
- * Get read-only memory tool names not already in the provided set.
- */
-export function getReadOnlyMemoryToolNames(existingToolNames: Set<string>): string[] {
-  return READONLY_MEMORY_TOOL_NAMES.filter(n => !existingToolNames.has(n));
-}

package/src/config/custom-agents.ts

@@ -7,7 +7,7 @@ import { basename, join } from "node:path";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "#src/config/agent-types";
 import { debugLog } from "#src/debug";
-import type { AgentConfig, MemoryScope, ThinkingLevel } from "#src/types";
+import type { AgentConfig, ThinkingLevel } from "#src/types";
 
 /**
  * Scan for custom agent .md files from multiple locations.
@@ -69,7 +69,6 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
       runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
       isolated: fm.isolated != null ? fm.isolated === true : undefined,
-      memory: parseMemory(fm.memory),
       isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false,  // default true; explicitly false disables
       source,
@@ -119,15 +118,6 @@ function csvListOptional(val: unknown): string[] | undefined {
   return parseCsvField(val);
 }
 
-/**
- * Parse a memory scope field.
- * omitted → undefined; "user"/"project"/"local" → MemoryScope.
- */
-function parseMemory(val: unknown): MemoryScope | undefined {
-  if (val === "user" || val === "project" || val === "local") return val;
-  return undefined;
-}
-
 /**
  * Parse an inherit field (extensions, skills).
  * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.

package/src/index.ts

@@ -34,7 +34,7 @@ import { createSubagentRuntime } from "#src/runtime";
 import { publishSubagentsService, unpublishSubagentsService } from "#src/service/service";
 import { createSubagentsService } from "#src/service/service-adapter";
 import { detectEnv } from "#src/session/env";
-import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "#src/session/memory";
+
 import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
 import { buildAgentPrompt } from "#src/session/prompts";
 import { deriveSubagentSessionDir } from "#src/session/session-dir";
@@ -146,8 +146,6 @@ export default function (pi: ExtensionAPI) {
     createSession: (opts) => createAgentSession(opts as any),
     assemblerIO: {
       preloadSkills,
-      buildMemoryBlock,
-      buildReadOnlyMemoryBlock,
       buildAgentPrompt,
     },
   };

package/src/session/prompts.ts

@@ -5,10 +5,8 @@
 import type { EnvInfo } from "#src/session/env";
 import type { AgentPromptConfig } from "#src/types";
 
-/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+/** Extra sections to inject into the system prompt (skills, etc.). */
 export interface PromptExtras {
-  /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
-  memoryBlock?: string;
   /** Preloaded skill contents to inject. */
   skillBlocks?: { name: string; content: string }[];
 }
@@ -45,9 +43,6 @@ Platform: ${env.platform}`;
 
   // Build optional extras suffix
   const extraSections: string[] = [];
-  if (extras?.memoryBlock) {
-    extraSections.push(extras.memoryBlock);
-  }
   if (extras?.skillBlocks?.length) {
     for (const skill of extras.skillBlocks) {
       extraSections.push(

package/src/session/safe-fs.ts

@@ -0,0 +1,45 @@
+/**
+ * safe-fs.ts — Filesystem safety utilities for reading untrusted paths.
+ *
+ * Used by skill-loader.ts to reject symlinks and path-traversal names
+ * before reading skill files from disk.
+ */
+
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { debugLog } from "#src/debug";
+
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name: string): boolean {
+  if (!name || name.length > 128) return true;
+  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath: string): boolean {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch (err) {
+    debugLog("lstatSync", err);
+    return false;
+  }
+}
+
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  if (isSymlink(filePath)) return undefined;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch (err) {
+    debugLog("readFileSync", err);
+    return undefined;
+  }
+}

package/src/session/session-config.ts

@@ -10,20 +10,11 @@
  * before invoking this function, keeping the assembler synchronous.
  */
 
-import {
-  type AgentConfigLookup,
-  getMemoryToolNames,
-  getReadOnlyMemoryToolNames,
-} from "#src/config/agent-types";
+import type { AgentConfigLookup } from "#src/config/agent-types";
 import type { EnvInfo } from "#src/session/env";
 import type { PromptExtras } from "#src/session/prompts";
 import type { PreloadedSkill } from "#src/session/skill-loader";
-import type {
-  AgentPromptConfig,
-  MemoryScope,
-  SubagentType,
-  ThinkingLevel,
-} from "#src/types";
+import type { AgentPromptConfig, SubagentType, ThinkingLevel } from "#src/types";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
@@ -52,12 +43,6 @@ export interface ToolFilterConfig {
  */
 export interface AssemblerIO {
   preloadSkills: (skills: string[], cwd: string) => PreloadedSkill[];
-  buildMemoryBlock: (name: string, scope: MemoryScope, cwd: string) => string;
-  buildReadOnlyMemoryBlock: (
-    name: string,
-    scope: MemoryScope,
-    cwd: string,
-  ) => string;
   buildAgentPrompt: (
     config: AgentPromptConfig,
     cwd: string,
@@ -210,38 +195,7 @@ export function assembleSessionConfig(
     }
   }
 
-  let toolNames = registry.getToolNamesForType(type);
-
-  // Persistent memory: detect write capability and branch accordingly.
-  // Account for disallowedTools — a tool in the base set but on the denylist
-  // is not truly available.
-  if (agentConfig.memory) {
-    const existingNames = new Set(toolNames);
-    const denied = agentConfig.disallowedTools
-      ? new Set(agentConfig.disallowedTools)
-      : undefined;
-    const effectivelyHas = (name: string) =>
-      existingNames.has(name) && !denied?.has(name);
-    const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
-
-    if (hasWriteTools) {
-      const extraNames = getMemoryToolNames(existingNames);
-      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = io.buildMemoryBlock(
-        agentConfig.name,
-        agentConfig.memory,
-        effectiveCwd,
-      );
-    } else {
-      const extraNames = getReadOnlyMemoryToolNames(existingNames);
-      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = io.buildReadOnlyMemoryBlock(
-        agentConfig.name,
-        agentConfig.memory,
-        effectiveCwd,
-      );
-    }
-  }
+  const toolNames = registry.getToolNamesForType(type);
 
   // Build system prompt from the resolved agent config
   const systemPrompt = io.buildAgentPrompt(

package/src/session/skill-loader.ts

@@ -24,7 +24,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import { isSymlink, isUnsafeName, safeReadFile } from "#src/session/memory";
+import { isSymlink, isUnsafeName, safeReadFile } from "#src/session/safe-fs";
 
 export interface PreloadedSkill {
   name: string;